Merge pull request '0.9.3: Graph from Source on main.archify works again' (#30) from fix/source-graph-switch into main

On a main.archify page in Source, Graph built the Graph page but the
host held it back until Source closed, so nothing happened, and Model
then showed the held Graph page. Switching between the model and its
graph now leaves Source first, and the page forgets Source when Graph
replaces it, so Model on the Graph page comes back to the model.

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.9.3 — 2026-11-04
+
+- Fixed: on a `main.archify` page in Source, **Graph** did nothing, and **Model** then showed the Graph page instead of the model. Graph now leaves Source and opens at once, and **Model** on the Graph page comes back to the model, not to Source.
+
+## 0.9.2 — 2026-10-27
+
+- **Source view.** Every Archify page can show its file's YAML in place: **Diagram | Graph | Source** on diagrams (the old **Diagram | Graph** switch, now on every diagram; Graph only inside a model), **Model | Graph | Source** on `main.archify`, **View | Source** on registry and decision pages, and Source on the Graph page too. The YAML opens in an editor inside the page, under its toolbar and heading, in the page's own colours: line numbers, folding, brackets, multiple cursors, undo and redo, ⌘S/Ctrl+S saves. Problems are underlined as you type, listed under the editor (click the count to go to the next one) and counted on the **Source** segment, also while the picture shows. Completion and hover come from the schema of the file, with nothing else installed. Edits go to the VS Code document, so the tab's dirty dot, save, Git and the text editor stay in step. **Diagram** (or **Model**, **View**) brings the picture back as it was left; anything rendered meanwhile shows then.
+- **2D | 3D** now sits left of the view switch (it says how the picture is drawn, the switch what is shown) and hides while Source shows; the 3D stage stops drawing meanwhile.
+- **Schema checks without the YAML extension.** `.archify` files are checked against the extension's schema on the YAML as written, at once and with readable messages (`Unknown key "lable" in connections[4].`) on the key or value concerned; `archify validate` runs once the schema is satisfied. `.archify-registry` files are checked against the registry schema for the first time (types, unknown keys, ids). The decision schema is no longer handed to the YAML extension: decision files use the `decision` key twice by design, which it reported as an error in every file.
+- **Commands.** *Archify | Show Source* switches the focused page to its Source view. The old behaviour, the YAML in VS Code's text editor beside the page, is *Archify | Open in Text Editor*, which is now the editor-title button.
+- Registry and decision pages are text editors of their files (as diagram pages already were), so edits made there make the tab dirty and save with it.
+- Fixed: a YAML error in a registry or decision file was reported on its first line instead of where it is.
+- Fixed: an unhandled "Webview is disposed" error when a diagram closed while it was rendering. On `main.archify` pages with a diagram, the model heading no longer runs under the toolbar in narrow editors.
+
 ## 0.9.1 — 2026-10-23
 
 - No functional change. Republished so that Open VSX carries the release: the 0.9.0 upload there was held under review while the `root-at-skic` namespace was still unverified, and a held upload is not released by the later ownership grant.

README.md

@@ -12,7 +12,7 @@ Free and open source. If it saves you time, you can [buy me a coffee](https://bu
 
 | File | Format | What the extension does |
 |---|---|---|
-| **`name.archify`** | **YAML** (the main format) | Opens as the interactive diagram. Show Source, live updates, validation, completion, templates. |
+| **`name.archify`** | **YAML** (the main format) | Opens as the interactive diagram, with a Source view for its YAML. Live updates, validation, completion, templates. |
 | `name.architecture.json`, `name.workflow.json`, `name.sequence.json`, `name.dataflow.json`, `name.lifecycle.json` | JSON (Archify's own CLI format) | Opens as text, with a preview beside it and validation. For files produced by the Archify CLI or AI agents. |
 | Rendered Archify `.html` | HTML | Read-only viewer instead of a browser. |
 
@@ -44,7 +44,7 @@ To write one by hand:
    ```
 
 2. Click it in the Explorer: the diagram opens.
-3. To edit, use **Show Source** in the editor title. The YAML opens beside the diagram, which re-renders as you type.
+3. To edit, click **Source** in the diagram's toolbar (**Diagram | Graph | Source**). The YAML takes the picture's place, checked as you type; **Diagram** brings the picture back. To see the text and the picture side by side, use **Open in Text Editor** in the editor title instead: the diagram re-renders as you type.
 
 The same file is in [examples/hello.archify](examples/hello.archify).
 
@@ -53,7 +53,7 @@ The same file is in [examples/hello.archify](examples/hello.archify).
 A `.archify` file is an Archify diagram written in **YAML**. Its fields are those of Archify's diagram schema; the extension converts the YAML for the renderer, so you never handle JSON yourself. `diagram_type` selects the kind of diagram: `architecture`, `workflow`, `sequence`, `dataflow` or `lifecycle`.
 
 - **Opening:** the **Archify Diagram** editor is the default for `.archify`. Use *Reopen Editor With… → Text Editor* to edit the YAML full-screen.
-- **Completion:** with the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) (`redhat.vscode-yaml`) installed, `.archify` files get completion and hover from Archify's schemas. The schema follows `diagram_type`.
+- **Completion:** in the Source view, `.archify` and `.archify-registry` files get completion and hover from Archify's schemas, with nothing else installed; the schema follows `diagram_type`. In VS Code's text editor the same comes from the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) (`redhat.vscode-yaml`), if installed.
 
 `.archify` files from extension version 0.2.0 were written in JSON. They still open, because JSON is valid YAML, but new files should use YAML.
 
@@ -66,19 +66,19 @@ The Archify CLI and the AI agents that use it write diagrams as JSON, named `nam
 - **New diagram from a template**: *Archify | New Diagram…* creates a starter `.archify` file for any of the five diagram kinds, or an everyday plan, in the chosen folder.
 - **New model from an example**: *Archify | New Model…* creates a complete model folder from a C4 example (Standard Web App, E-Shop, Event-Based Integration).
 - **Model graph**: the **Graph** switch on any page of a model shows the whole model as one graph, with a query box (`type:database`, `uses:api`, `from:web to:db`, …), a side panel per element and PNG export. See [Models](#models).
-- **Diagram editor**: `.archify` files open as the rendered diagram. **Show Source** opens the YAML beside it, and edits re-render live.
+- **Diagram editor**: `.archify` files open as the rendered diagram. **Source** shows the YAML in its place, in an editor inside the page: problems underlined as you type and counted on the switch, completion and hover from the schema, undo, and ⌘S/Ctrl+S to save. **Open in Text Editor** opens the YAML beside the diagram instead, and edits re-render live.
 - **Live updates**: the diagram re-renders as you edit, and keeps the focus and route you selected (`#focus=…`, `#route=…`).
 - **HTML viewer**: right-click a rendered `.html` file and choose **Archify | Open in HTML Viewer**, or use *Reopen Editor With… → Archify HTML Viewer*. For Archify HTML already open as text, a button appears in the editor title. The viewer reloads when the file changes on disk.
-- **Problems**: YAML syntax errors, plus `archify validate`'s schema, layout and evidence problems, appear at the matching line of the `.archify` file.
+- **Problems**: YAML syntax errors, schema problems (unknown keys, wrong types, missing fields, checked with the extension's own schema check on the YAML as written) and `archify validate`'s layout and evidence problems appear at the matching place in the `.archify` file. Registries are checked against their schema too.
 - **Brand logos**: after `brand:` the editor suggests Archify's built-in brand IDs (PostgreSQL, Redis, Kafka, Docker, …). Typing an alias or product name finds them too, so `kafka` offers `apache-kafka`. An unknown brand is reported on its own line.
-- **Schema help**: completion and hover from Archify's own schemas, through the YAML extension for `.archify` files.
+- **Schema help**: completion and hover from Archify's own schemas: in the Source view built in, in the text editor through the YAML extension.
 - **Source links**: in source-backed diagrams, clicking a source reference opens that file and line range in the editor. If the file is not in the workspace, the web link opens instead.
 - **Export**: the diagram's own Export menu (PNG, SVG, share card, …) saves through a VS Code save dialog.
-- **Commands**: *Archify | New Model…*, *Archify | New Registry…*, *Archify | New Diagram…*, *Archify | New Decision…*, *Archify | Open Model*, *Archify | Open Model Graph*, *Archify | Render to HTML File…*, *Archify | Open in Browser*, *Archify | Refresh Preview*, *Archify | Show Source*.
+- **Commands**: *Archify | New Model…*, *Archify | New Registry…*, *Archify | New Diagram…*, *Archify | New Decision…*, *Archify | Open Model*, *Archify | Open Model Graph*, *Archify | Render to HTML File…*, *Archify | Open in Browser*, *Archify | Refresh Preview*, *Archify | Show Source* (switches the page to its Source view), *Archify | Open in Text Editor*.
 
 ## 3D view
 
-Every diagram can also be seen in 3D. The **2D | 3D** switch next to **Export** in the diagram's toolbar shows which view you are in; click it to flip.
+Every diagram can also be seen in 3D. The **2D | 3D** switch in the diagram's toolbar, left of **Diagram | Graph | Source**, shows which view you are in; click it to flip. It hides while Source shows, and **Diagram** returns to the 2D or 3D you left.
 
 ![The same diagram in the 3D view](docs/preview-3d.png)
 
@@ -124,10 +124,10 @@ online-shop/
 - **Links.** A registry element (or a component) with `diagram: 0300-components/api.archify` points at the diagram that explains it: double-click the node in the 2D view to open it.
 - **Descriptions.** Under a model diagram, hovering a row of the **Elements** panel shows the registry description of that element.
 - **Decisions.** One `*.archify-decision` file per architecture decision: id, title, status, date, the registry elements and diagrams it is about, and prose for context, decision and consequences. Diagrams point at decisions with `decisions: [<id>]` on the diagram, a component or a connection. They show as a **Decisions** panel on the `main.archify` page, a **Decisions** rail panel under each diagram (hover lights up what the decision is attached to), on element cards and in the element dialog, and a decision opens as its own page. *Archify | New Decision…* creates one; links are checked in Problems.
-- **Registry view.** A `.archify-registry` file opens as its elements, as cards. Click one and a dialog shows its description, where it is defined and the diagrams that use it; click a diagram to open it. **Show Source** opens the YAML beside it.
+- **Registry view.** A `.archify-registry` file opens as its elements, as cards. Click one and a dialog shows its description, where it is defined and the diagrams that use it; click a diagram to open it. **View | Source** at the top right switches to the YAML, checked against the registry schema as you type.
 - **Elements and Connectors.** Under every diagram, Archify's node index is titled **Elements**, and a **Connectors** panel next to it lists every connection as "from → to" with its label. Hovering highlights the connector in the diagram; clicking keeps it highlighted and scrolls to it.
 - **Starting one.** *Archify | New Model…* (right-click a folder) copies one of the shipped examples into a new folder, named as you choose: **C4 - Standard Web App** (single-page app, API, database, cache, storage, identity provider), **C4 - E-Shop** (web shop, API, worker, queue, payment and email providers) or **C4 - Event-Based Integration** (event bus, router, dead-letter queue, event store, consumers). Each has a registry and context, container and component diagrams. For an empty model, *Archify | New Diagram… → Model* creates just a `main.archify`.
-- **The graph.** The **Model | Graph** switch at the top of the `main.archify` page (next to **Export** when the file has a diagram) replaces the page with the whole model as one graph: every element any diagram draws plus every registry element, every connection between them, each once. Registry elements have a solid border, inline ones a dashed border; colours are Archify's type colours and the legend chips at the bottom hide or show a type. **Decisions** are nodes too (tags coloured by status, dotted links to the elements they are about, dashed links to what they supersede), and so are **registries** (one node per file, dotted links to the elements it defines); their chips hide them when the picture gets busy. The layout is **Layered** by default, like Archify's stack: clients on the left, data on the right, registries in a row above, decisions in a row below, connections drawn orthogonally; click the button for a **Force** layout instead. Drag nodes, scroll to zoom, **Fit** (or <kbd>0</kbd>) frames what matches, **Labels** toggles connection labels, the dotted **Links** from decisions and registries to their elements are on by default and can be switched off, in which case only the selected element's show (hovering an element lights up its connections), the sun/moon button switches the page between its dark and light theme (remembered, shared with the diagram pages' theme choice), **Export PNG** saves the picture. On a diagram page the switch reads **Diagram | Graph** and opens the graph already narrowed to that diagram. *Archify | Open Model Graph* does the same from the Command Palette or Explorer.
+- **The graph.** The **Model | Graph | Source** switch at the top of the `main.archify` page (next to **Export** when the file has a diagram) replaces the page with the whole model as one graph: every element any diagram draws plus every registry element, every connection between them, each once. Registry elements have a solid border, inline ones a dashed border; colours are Archify's type colours and the legend chips at the bottom hide or show a type. **Decisions** are nodes too (tags coloured by status, dotted links to the elements they are about, dashed links to what they supersede), and so are **registries** (one node per file, dotted links to the elements it defines); their chips hide them when the picture gets busy. The layout is **Layered** by default, like Archify's stack: clients on the left, data on the right, registries in a row above, decisions in a row below, connections drawn orthogonally; click the button for a **Force** layout instead. Drag nodes, scroll to zoom, **Fit** (or <kbd>0</kbd>) frames what matches, **Labels** toggles connection labels, the dotted **Links** from decisions and registries to their elements are on by default and can be switched off, in which case only the selected element's show (hovering an element lights up its connections), the sun/moon button switches the page between its dark and light theme (remembered, shared with the diagram pages' theme choice), **Export PNG** saves the picture. On a diagram page the switch reads **Diagram | Graph | Source** and Graph opens the graph already narrowed to that diagram; **Source** on the graph page goes back to `main.archify` in its Source view. *Archify | Open Model Graph* does the same from the Command Palette or Explorer.
 - **Queries.** Type a few words in the box (<kbd>/</kbd> focuses it); matches stay bright, the rest dims, the count shows "9 of 14 elements". Terms combine with AND and a leading `-` excludes: `database` (id, label, sublabel, brand or type contain it), `type:backend`, `diagram:0200-*` (what those diagrams draw), `decision:<id>` (what a decision is about or is attached to), `uses:api` (an element and its neighbours), `near:api,2` (within two steps), `from:web to:db` (the shortest path, following the arrows first), `unused` (registry elements no diagram draws), `shared` and `-shared` (registry or inline elements only), `type:decision` and `type:registry` for the decision and registry nodes. Decisions and registries follow the elements they are attached to into a result; `-type:decision` or `-type:registry` leaves them out. Walks and paths follow the diagrams' connections only, so a registry is never a shortcut between its elements. The **?** button lists them; clicking an example runs it.
 - **Side panel.** Click an element for its description, type, where it is defined (**Registry** opens the file at the line), the diagrams that draw it (click to open), its connections and its decisions (click to open). **Neighbours** runs `uses:` for it. Click a connection for its labels, the diagrams that draw it and its decisions. Click a decision node for its status, context and decision text, the elements and connections it is about, and **Open decision**; a registry node for the elements it defines, the ones no diagram draws yet, and **Open registry**.
 - **Commands.** *Archify | Open Model* opens the model page of the current file, from the editor title, the Command Palette or the Explorer menu of a `.archify` or `.archify-registry` file; *Archify | Open Model Graph* opens the graph.

esbuild.mjs

@@ -18,6 +18,17 @@ const common = {
   mainFields: ['module', 'main'],
 };
 
+// codemirror-json-schema formats schema descriptions with markdown-it and
+// shiki (about 400 KB); a small stub does what our descriptions need.
+const stubMarkdown = {
+  name: 'stub-markdown',
+  setup(build) {
+    build.onResolve({ filter: /utils\/markdown(\.js)?$/ }, (args) =>
+      args.importer.includes('codemirror-json-schema') ? { path: path.resolve('src/webview/source/markdownStub.ts') } : undefined,
+    );
+  },
+};
+
 if (tests) {
   // Unit tests cover the modules that do not import 'vscode'; the
   // integration suite runs inside VS Code, which provides it.
@@ -58,6 +69,16 @@ if (tests) {
       entryPoints: ['src/graph/index.ts'],
       outfile: 'dist/graph.js',
     }),
+    // The Source view; CodeMirror is bundled in. Loaded the first time Source is chosen.
+    esbuild.context({
+      ...common,
+      format: 'iife',
+      platform: 'browser',
+      target: 'es2022',
+      entryPoints: ['src/webview/source/index.ts'],
+      outfile: 'dist/source.js',
+      plugins: [stubMarkdown],
+    }),
   ]);
   if (watch) {
     await Promise.all(contexts.map((ctx) => ctx.watch()));

package.json

@@ -2,7 +2,7 @@
   "name": "archify-vscode-ext",
   "displayName": "Archify Diagram Viewer",
   "description": "Archify diagrams in VS Code. Write diagrams as .archify files in YAML: they open as the interactive diagram, with live updates, validation, templates and completion. Also previews Archify's own JSON files (*.architecture.json, …) and opens rendered Archify HTML.",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "publisher": "root-at-skic",
   "license": "MIT",
   "sponsor": {
@@ -102,6 +102,11 @@
       {
         "command": "archify.showSource",
         "title": "Archify | Show Source",
+        "icon": "$(code)"
+      },
+      {
+        "command": "archify.openInTextEditor",
+        "title": "Archify | Open in Text Editor",
         "icon": "$(go-to-file)"
       },
       {
@@ -145,6 +150,10 @@
           "command": "archify.showSource",
           "when": "archifyPreviewFocus || activeCustomEditorId == 'archify.htmlViewer' || activeCustomEditorId == 'archify.diagram' || activeCustomEditorId == 'archify.registry' || activeCustomEditorId == 'archify.decision'"
         },
+        {
+          "command": "archify.openInTextEditor",
+          "when": "archifyPreviewFocus || activeCustomEditorId == 'archify.htmlViewer' || activeCustomEditorId == 'archify.diagram' || activeCustomEditorId == 'archify.registry' || activeCustomEditorId == 'archify.decision'"
+        },
         {
           "command": "archify.openModel",
           "when": "archify.isDiagramSource || archifyPreviewFocus || activeCustomEditorId == 'archify.diagram' || activeCustomEditorId == 'archify.registry' || activeCustomEditorId == 'archify.decision'"
@@ -171,7 +180,7 @@
           "group": "navigation"
         },
         {
-          "command": "archify.showSource",
+          "command": "archify.openInTextEditor",
           "when": "archifyPreviewFocus || activeCustomEditorId == 'archify.htmlViewer' || activeCustomEditorId == 'archify.diagram' || activeCustomEditorId == 'archify.registry' || activeCustomEditorId == 'archify.decision'",
           "group": "navigation"
         },
@@ -454,10 +463,6 @@
       {
         "fileMatch": "*.archify-registry",
         "url": "./schemas/archify-registry.schema.json"
-      },
-      {
-        "fileMatch": "*.archify-decision",
-        "url": "./schemas/archify-decision.schema.json"
       }
     ]
   },
@@ -479,7 +484,6 @@
     "@types/vscode": "~1.100.0",
     "@vscode/test-electron": "^3.1.0",
     "@vscode/vsce": "^3.0.0",
-    "ajv": "^8.20.0",
     "esbuild": "^0.25.0",
     "jsonc-parser": "^3.3.1",
     "typescript": "^5.8.0"
@@ -489,6 +493,17 @@
   },
   "homepage": "https://gitea.lego-cloud.eu/vscode-extensions/archify-vscode-ext#readme",
   "dependencies": {
+    "@codemirror/autocomplete": "^6.20.4",
+    "@codemirror/commands": "^6.11.1",
+    "@codemirror/lang-yaml": "^6.1.3",
+    "@codemirror/language": "^6.13.1",
+    "@codemirror/lint": "^6.9.7",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/view": "^6.43.15",
+    "@lezer/highlight": "^1.2.5",
+    "ajv": "^8.20.0",
+    "codemirror": "^6.0.2",
+    "codemirror-json-schema": "^0.8.1",
     "cytoscape": "^3.34.4",
     "cytoscape-fcose": "^2.2.0",
     "three": "^0.186.1",

src/commands/viewCommands.ts

@@ -39,7 +39,17 @@ export function viewCommands(ctx: CommandContext): vscode.Disposable[] {
 
     vscode.commands.registerCommand('archify.refreshPreview', () => ctx.views.activePreview?.update(true)),
 
+    // On a page that has a Source view, show it; elsewhere open the text.
     vscode.commands.registerCommand('archify.showSource', async () => {
+      const session = ctx.views.activePreview?.source ?? ctx.registry.activeView?.source ?? ctx.decision.activeView?.source;
+      if (session) {
+        session.reveal();
+        return;
+      }
+      await vscode.commands.executeCommand('archify.openInTextEditor');
+    }),
+
+    vscode.commands.registerCommand('archify.openInTextEditor', async () => {
       const preview = ctx.views.activePreview;
       if (preview?.isEditor) {
         // The diagram is the editor; open the YAML text beside it.

src/extension.ts

@@ -22,8 +22,8 @@ export function activate(context: vscode.ExtensionContext): void {
     extension: context,
     views: new DiagramViewManager(context, models),
     htmlViewer: new HtmlViewerProvider(context.extensionUri),
-    registry: new RegistryViewProvider(models),
+    registry: new RegistryViewProvider(context, models),
-    decision: new DecisionViewProvider(models),
+    decision: new DecisionViewProvider(context, models),
     models,
   };
   const refs = new RefLanguage(models);

src/graph/index.ts

@@ -226,12 +226,27 @@ class GraphPage {
     this.nameEl.textContent = this.graph.meta.name || this.graph.meta.id || 'Untitled model';
     titles.append(this.kickerEl, this.nameEl);
     const actions = el('div', 'ag-actions');
-    const sw = el('button', 'ag-switch');
+    // Model | Graph | Source, as on the model page. Source goes back to the
-    sw.type = 'button';
+    // model page and opens it in Source (the page reads sourceView on load).
-    sw.title = 'Back to the model page';
+    const sw = el('div', 'ag-switch');
-    sw.setAttribute('aria-label', 'Graph view on; switch to the model page');
+    sw.setAttribute('role', 'group');
-    sw.append(el('span', 'ag-seg', 'Model'), el('span', 'ag-seg on', 'Graph'));
+    sw.setAttribute('aria-label', 'View');
-    sw.addEventListener('click', () => this.host.post({ type: 'showModel' }));
+    const segment = (label: string, title: string, on: boolean, action?: () => void) => {
+      const button = el('button', `ag-seg${on ? ' on' : ''}`, label);
+      button.type = 'button';
+      button.title = title;
+      button.setAttribute('aria-pressed', String(on));
+      if (action) button.addEventListener('click', action);
+      return button;
+    };
+    sw.append(
+      segment('Model', 'Back to the model page', false, () => this.host.post({ type: 'showModel' })),
+      segment('Graph', 'The model as one graph', true),
+      segment('Source', 'Edit the YAML of main.archify, checked as you type', false, () => {
+        this.host.setState({ sourceView: true });
+        this.host.post({ type: 'showModel' });
+      }),
+    );
     const exportButton = el('button', 'ag-button ag-primary', 'Export PNG');
     exportButton.type = 'button';
     exportButton.title = 'Save the graph as it is on screen, as a PNG';

src/graph/style.ts

@@ -20,13 +20,14 @@ html, body { margin: 0; height: 100%; overflow: hidden; background: var(--ag-bg)
 .ag-actions { margin-left: auto; display: flex; align-items: center; gap: 0.5rem; }
 .ag-bar .ag-button { min-height: 2rem; }
 /* Toolbar controls follow Archify's: quiet pills (0.5rem) inside 0.5625rem buttons, one filled primary action (0.6875rem), the 2D | 3D switch's twin. */
-.ag-switch { position: relative; isolation: isolate; display: inline-flex; padding: 0 0.25rem; border: 0; border-radius: 0.5625rem; background: transparent; color: var(--ag-muted); font: inherit; cursor: pointer; }
+.ag-switch { position: relative; isolation: isolate; display: inline-flex; padding: 0 0.25rem; border: 0; border-radius: 0.5625rem; background: transparent; color: var(--ag-muted); font: inherit; }
 .ag-switch::before { content: ""; position: absolute; z-index: -1; inset: 0.25rem 0; border-radius: 0.6875rem; background: color-mix(in srgb, var(--ag-panel) 78%, transparent); box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--ag-border) 85%, transparent), 0 1px 2px rgba(15, 23, 42, 0.04); }
 .ag-switch:hover::before { box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--ag-fg) 22%, transparent), 0 1px 2px rgba(15, 23, 42, 0.04); }
-.ag-switch:focus-visible { outline: 2px solid var(--ag-accent); outline-offset: -4px; }
+.ag-seg { display: inline-flex; align-items: center; height: 1.75rem; margin: 0.25rem 0; padding: 0 0.7rem; border: 0; border-radius: 0.5rem; background: transparent; color: inherit; font: inherit; font-weight: 550; font-size: 0.8125rem; cursor: pointer; transition: background 0.15s, color 0.15s; }
-.ag-seg { display: inline-flex; align-items: center; height: 1.75rem; margin: 0.25rem 0; padding: 0 0.7rem; border-radius: 0.5rem; font-weight: 550; font-size: 0.8125rem; transition: background 0.15s, color 0.15s; }
+.ag-seg.on { cursor: default; }
+.ag-seg:focus-visible { outline: 2px solid var(--ag-accent); outline-offset: 1px; }
 .ag-seg.on { color: var(--ag-bg); background: var(--ag-fg); box-shadow: 0 1px 2px rgba(15, 23, 42, 0.12), 0 6px 16px -8px rgba(15, 23, 42, 0.4); }
-.ag-switch:hover .ag-seg:not(.on) { color: var(--ag-fg); }
+.ag-seg:hover:not(.on) { color: var(--ag-fg); }
 .ag-button { position: relative; isolation: isolate; display: inline-flex; align-items: center; gap: 0.4rem; font: inherit; font-size: 0.8125rem; font-weight: 500; min-height: 2.25rem; padding: 0.25rem 0.58rem; border-radius: 0.5625rem; border: 0; background: transparent; color: var(--ag-muted); cursor: pointer; white-space: nowrap; transition: color 0.15s; }
 .ag-button::before { content: ""; position: absolute; z-index: -1; inset: 0.25rem 0; border-radius: 0.5rem; background: transparent; transition: background 0.15s, box-shadow 0.15s; }
 .ag-button:hover { color: var(--ag-fg); }

src/language/diagnostics.ts

@@ -10,6 +10,7 @@ import { isArchifyFile } from '../sources/detect';
 import { log } from '../util/log';
 import path from 'node:path';
 import { diagnosticPointer, rangeForPointer, rangeForPointerYaml, yamlSyntaxProblems } from './jsonPointer';
+import { DIAGRAM_SCHEMA, REGISTRY_SCHEMA, SchemaChecker, SchemaProblem, readSchemas } from './schemaCheck';
 
 const JSON_LANGUAGES = new Set(['json', 'jsonc']);
 
@@ -33,6 +34,7 @@ export class DiagnosticsController implements vscode.Disposable {
   private readonly timers = new Map<string, NodeJS.Timeout>();
   private readonly sequence = new Map<string, number>();
   private readonly disposables: vscode.Disposable[];
+  private checker: SchemaChecker | undefined;
 
   constructor(
     private readonly context: vscode.ExtensionContext,
@@ -54,6 +56,22 @@ export class DiagnosticsController implements vscode.Disposable {
     this.revalidateAll();
   }
 
+  /** Our schemas, compiled on first use. */
+  private schemas(): SchemaChecker {
+    this.checker ??= new SchemaChecker(readSchemas(vscode.Uri.joinPath(this.context.extensionUri, 'schemas').fsPath));
+    return this.checker;
+  }
+
+  private schemaDiagnostic(doc: vscode.TextDocument, problem: SchemaProblem): vscode.Diagnostic {
+    const diagnostic = new vscode.Diagnostic(
+      new vscode.Range(doc.positionAt(problem.from), doc.positionAt(problem.to)),
+      problem.message,
+      vscode.DiagnosticSeverity.Error,
+    );
+    diagnostic.source = 'archify';
+    return diagnostic;
+  }
+
   private enabled(uri: vscode.Uri): boolean {
     return vscode.workspace.getConfiguration('archify', uri).get<boolean>('validation.enabled', true);
   }
@@ -136,6 +154,17 @@ export class DiagnosticsController implements vscode.Disposable {
       }
     }
 
+    if (isArchifyFile(doc.fileName)) {
+      // The schema check sees the source as written and answers at once; a
+      // file that fails it would fail archify validate the same way, so that
+      // runs only on files the schema accepts.
+      const schemaProblems = this.schemas().check(text, DIAGRAM_SCHEMA);
+      if (schemaProblems.length) {
+        this.collection.set(doc.uri, [...modelDiagnostics, ...schemaProblems.map((problem) => this.schemaDiagnostic(doc, problem))]);
+        return;
+      }
+    }
+
     try {
       const runtime = await runtimeFor(this.context, doc.uri);
       const result = await validate(runtime, source.type, source.json);
@@ -210,6 +239,10 @@ export class DiagnosticsController implements vscode.Disposable {
     const root = await this.models.rootOf(doc.uri);
     const rel = root ? path.relative(root.fsPath, doc.uri.fsPath) : path.basename(doc.uri.fsPath);
     const problems: ModelProblem[] = [...parseRegistry(text, rel).problems];
+    // The schema adds what the parser does not check (types, unknown keys,
+    // ids); a file the parser already rejects as a whole gets no second opinion.
+    const shapeless = problems.some((p) => /not valid YAML|must be a mapping|needs an "elements" mapping/.test(p.message));
+    const schemaProblems = shapeless ? [] : this.schemas().check(text, REGISTRY_SCHEMA);
     if (root) {
       try {
         const index = await this.models.index(root);
@@ -223,7 +256,10 @@ export class DiagnosticsController implements vscode.Disposable {
       problems.push({ message: `This registry is not inside a model: no main.archify above ${path.basename(doc.uri.fsPath)}.`, severity: 'warning', line: 0 });
     }
     if (seq !== this.sequence.get(doc.uri.toString()) || doc.isClosed) return;
-    this.collection.set(doc.uri, problems.map((problem) => this.modelDiagnostic(doc, text, 'yaml', problem)));
+    this.collection.set(doc.uri, [
+      ...problems.map((problem) => this.modelDiagnostic(doc, text, 'yaml', problem)),
+      ...schemaProblems.map((problem) => this.schemaDiagnostic(doc, problem)),
+    ]);
   }
 
   dispose(): void {

src/language/editorSchemas.ts

@@ -0,0 +1,85 @@
+import { DIAGRAM_SCHEMA, REGISTRY_SCHEMA } from './schemaCheck';
+
+type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+/**
+ * Schemas for completion and hover in the Source view. The editor's schema
+ * library reads one draft-07 document, while ours are 2020-12 files that
+ * refer to each other; so the referenced files are folded into `$defs` and
+ * 2020-12 tuples become draft-07 ones. Problems never come from these
+ * copies (the host checks with the originals), only suggestions.
+ */
+export class EditorSchemas {
+  private readonly cache = new Map<string, object>();
+
+  constructor(private readonly schemas: Record<string, object>) {}
+
+  /** The schema for a file kind; for diagrams the one of its diagram_type. */
+  forSource(kind: 'diagram' | 'registry' | 'decision', text: string): { key: string; schema: object } | undefined {
+    if (kind === 'decision') return undefined;
+    if (kind === 'registry') return this.get(REGISTRY_SCHEMA);
+    const type = /^diagram_type:\s*["']?([a-z]+)/m.exec(text)?.[1];
+    const name = type && this.schemas[`${type}.schema.json`] ? `${type}.schema.json` : DIAGRAM_SCHEMA;
+    return this.get(name);
+  }
+
+  private get(name: string): { key: string; schema: object } | undefined {
+    if (!this.schemas[name]) return undefined;
+    if (!this.cache.has(name)) this.cache.set(name, bundleSchema(this.schemas, name));
+    return { key: name, schema: this.cache.get(name)! };
+  }
+}
+
+const defKey = (file: string) => `file:${file}`;
+
+/** One self-contained draft-07 shaped schema for `root` and every file it refers to. */
+export function bundleSchema(schemas: Record<string, object>, root: string): object {
+  const files = new Set<string>([root]);
+  const queue = [root];
+  while (queue.length) {
+    const file = queue.shift()!;
+    for (const ref of refsOf(schemas[file] as Json)) {
+      const target = ref.split('#')[0];
+      if (target && !files.has(target) && schemas[target]) {
+        files.add(target);
+        queue.push(target);
+      }
+    }
+  }
+  const base = (file: string) => (file === root ? '#' : `#/$defs/${defKey(file)}`);
+  const rewrite = (node: Json, file: string): Json => {
+    if (Array.isArray(node)) return node.map((item) => rewrite(item, file));
+    if (!node || typeof node !== 'object') return node;
+    const out: { [key: string]: Json } = {};
+    for (const [key, value] of Object.entries(node)) {
+      if (key === '$ref' && typeof value === 'string') {
+        const [target, pointer = ''] = value.split('#');
+        out.$ref = `${base(target || file)}${pointer}`;
+      } else if (key !== '$schema' && key !== '$id') {
+        out[key] = rewrite(value, file);
+      }
+    }
+    if (out.prefixItems) {
+      if (out.items === false) out.additionalItems = false;
+      else if (out.items !== undefined) out.additionalItems = out.items;
+      out.items = out.prefixItems;
+      delete out.prefixItems;
+    }
+    return out;
+  };
+  const bundled = rewrite(schemas[root] as Json, root) as { [key: string]: Json };
+  const defs = { ...((bundled.$defs as { [key: string]: Json } | undefined) ?? {}) };
+  for (const file of files) if (file !== root) defs[defKey(file)] = rewrite(schemas[file] as Json, file);
+  return { ...bundled, $defs: defs };
+}
+
+function refsOf(node: Json, out: string[] = []): string[] {
+  if (Array.isArray(node)) node.forEach((item) => refsOf(item, out));
+  else if (node && typeof node === 'object') {
+    for (const [key, value] of Object.entries(node)) {
+      if (key === '$ref' && typeof value === 'string') out.push(value);
+      else refsOf(value, out);
+    }
+  }
+  return out;
+}

src/language/schemaCheck.ts

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Ajv2020, { ErrorObject, ValidateFunction } from 'ajv/dist/2020';
+import { LineCounter, Node, isMap, isScalar, isSeq, parseDocument } from 'yaml';
+
+/** A schema problem placed on the YAML node it is about; offsets into the text. */
+export interface SchemaProblem {
+  from: number;
+  to: number;
+  message: string;
+  /** 'yaml' for a syntax error (only the first is reported), 'schema' otherwise. */
+  kind: 'yaml' | 'schema';
+}
+
+/** Schema file names in schemas/ that a file kind is checked against. */
+export const DIAGRAM_SCHEMA = 'archify.schema.json';
+export const REGISTRY_SCHEMA = 'archify-registry.schema.json';
+
+/** Reads every *.schema.json of a folder: file name → schema. */
+export function readSchemas(folder: string): Record<string, object> {
+  return Object.fromEntries(
+    fs
+      .readdirSync(folder)
+      .filter((name) => name.endsWith('.schema.json'))
+      .map((name) => [name, JSON.parse(fs.readFileSync(path.join(folder, name), 'utf8')) as object]),
+  );
+}
+
+/**
+ * Checks YAML text against our JSON Schemas (draft 2020-12, with ajv), so the
+ * Source view and the Problems panel see the same problems whether or not a
+ * YAML extension is installed. Schemas refer to each other by file name.
+ */
+export class SchemaChecker {
+  private readonly ajv = new Ajv2020({ allErrors: true, strict: false });
+  private readonly compiled = new Map<string, ValidateFunction | undefined>();
+
+  constructor(schemas: Record<string, object>) {
+    for (const [name, schema] of Object.entries(schemas)) this.ajv.addSchema(schema, name);
+  }
+
+  private validator(name: string): ValidateFunction | undefined {
+    if (!this.compiled.has(name)) this.compiled.set(name, this.ajv.getSchema(name));
+    return this.compiled.get(name);
+  }
+
+  check(text: string, schema: string): SchemaProblem[] {
+    const doc = parseDocument(text, { lineCounter: new LineCounter(), prettyErrors: false, uniqueKeys: false });
+    if (doc.errors.length) {
+      // Later syntax errors are usually echoes of the first.
+      const error = doc.errors[0];
+      return [{ from: error.pos[0], to: Math.max(error.pos[1], error.pos[0] + 1), message: `YAML: ${error.message.split('\n')[0]}`, kind: 'yaml' }];
+    }
+    const validate = this.validator(schema);
+    if (!validate || validate(doc.toJS())) return [];
+    return collapse(validate.errors ?? []).map((error) => {
+      const [from, to] = rangeFor(doc.contents, error, text.length);
+      return { from, to, message: describe(error), kind: 'schema' as const };
+    });
+  }
+}
+
+/** oneOf/anyOf/if produce a cascade; keep the errors a person can act on. */
+function collapse(errors: ErrorObject[]): ErrorObject[] {
+  const seen = new Set<string>();
+  return errors
+    .filter((e) => !['if', 'oneOf', 'anyOf', 'allOf'].includes(e.keyword))
+    .filter((e) => {
+      const key = `${e.instancePath}|${e.keyword}|${JSON.stringify(e.params)}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+}
+
+/** "/connections/4/label" → "connections[4].label". */
+export function readablePointer(pointer: string): string {
+  if (!pointer) return 'the file';
+  return pointer
+    .split('/')
+    .slice(1)
+    .map((part) => (/^\d+$/.test(part) ? `[${part}]` : `.${part.replace(/~1/g, '/').replace(/~0/g, '~')}`))
+    .join('')
+    .replace(/^\./, '');
+}
+
+function describe(e: ErrorObject): string {
+  const where = readablePointer(e.instancePath);
+  const params = e.params as Record<string, unknown>;
+  switch (e.keyword) {
+    case 'additionalProperties':
+      return `Unknown key "${params.additionalProperty}" in ${where}.`;
+    case 'required':
+      return `"${params.missingProperty}" is required in ${where}.`;
+    case 'enum':
+      return `${where} must be one of: ${(params.allowedValues as unknown[]).join(', ')}.`;
+    case 'const':
+      return `${where} must be ${JSON.stringify(params.allowedValue)}.`;
+    case 'type': {
+      const type = String(params.type);
+      return `${where} must be ${type === 'array' ? 'a list' : type === 'object' ? 'a mapping' : `a ${type}`}.`;
+    }
+    case 'minItems':
+    case 'maxItems': {
+      const limit = Number(params.limit);
+      return `${where} needs ${e.keyword === 'minItems' ? 'at least' : 'at most'} ${limit} item${limit === 1 ? '' : 's'}.`;
+    }
+    case 'propertyNames':
+      return `"${params.propertyName}" in ${where} is not a valid id: start with a letter; letters, digits, - and _ after.`;
+    default:
+      return `${where} ${e.message ?? 'is not valid'}.`;
+  }
+}
+
+function keyText(key: unknown): string {
+  return isScalar(key) ? String(key.value) : String(key);
+}
+
+/** The node an error is about: the offending key for unknown keys, else the value. */
+function rangeFor(root: Node | null, error: ErrorObject, length: number): [number, number] {
+  const parts = error.instancePath.split('/').slice(1).map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let node: unknown = root;
+  let keyNode: Node | null = null;
+  for (const part of parts) {
+    if (isMap(node)) {
+      const pair = node.items.find((p) => keyText(p.key) === part);
+      if (!pair) break;
+      keyNode = pair.key as Node;
+      node = pair.value;
+    } else if (isSeq(node)) {
+      keyNode = null;
+      node = node.items[Number(part)];
+    } else break;
+  }
+  const params = error.params as Record<string, unknown>;
+  const extra = params.additionalProperty ?? params.propertyName;
+  if (extra !== undefined && isMap(node)) {
+    const pair = node.items.find((p) => keyText(p.key) === String(extra));
+    const range = (pair?.key as Node | undefined)?.range;
+    if (range) return [range[0], range[1]];
+  }
+  if (error.keyword === 'required' && keyNode?.range) return [keyNode.range[0], keyNode.range[1]];
+  const target = (node as Node | undefined)?.range ? (node as Node) : keyNode;
+  if (!target?.range) return [0, Math.min(1, length)];
+  // A block mapping or list spans many lines; mark its first character only.
+  if ((isMap(target) || isSeq(target)) && !target.flow) return [target.range[0], target.range[0] + 1];
+  return [target.range[0], Math.max(target.range[1], target.range[0] + 1)];
+}

src/model/decisions.ts

@@ -1,4 +1,4 @@
-import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
+import { LineCounter, isMap, isScalar, isSeq, parseDocument } from 'yaml';
 import { ModelProblem, Registry } from './format';
 
 /**
@@ -46,9 +46,11 @@ export function slugify(title: string): string {
 /** Parses one decision file. Problems carry 0-based lines. */
 export function parseDecision(text: string, file: string): { decision?: Decision; problems: ModelProblem[] } {
   const problems: ModelProblem[] = [];
-  const doc = parseDocument(text, { prettyErrors: false, uniqueKeys: false });
+  // prettyErrors would put line numbers into the messages; the line counter gives them without.
+  const lines = new LineCounter();
+  const doc = parseDocument(text, { prettyErrors: false, uniqueKeys: false, lineCounter: lines });
   for (const error of doc.errors) {
-    problems.push({ message: `Decision is not valid YAML: ${error.message.split('\n')[0]}`, severity: 'error', file, line: error.linePos?.[0].line ? error.linePos[0].line - 1 : 0 });
+    problems.push({ message: `Decision is not valid YAML: ${error.message.split('\n')[0]}`, severity: 'error', file, line: lines.linePos(error.pos[0]).line - 1 });
   }
   if (doc.errors.length) return { problems };
   const lineOf = (offset: number | undefined) => (offset === undefined ? 0 : text.slice(0, offset).split('\n').length - 1);

src/model/format.ts

@@ -1,4 +1,4 @@
-import { isMap, isScalar, parseDocument, parse as parseYaml } from 'yaml';
+import { LineCounter, isMap, isScalar, parse as parseYaml, parseDocument } from 'yaml';
 
 /**
  * The model file formats (see docs/model.md): `main.archify` with a `model`
@@ -83,9 +83,11 @@ export function hasDiagramBody(doc: unknown): boolean {
 export function parseRegistry(text: string, file: string): { elements: RegistryElement[]; problems: ModelProblem[] } {
   const problems: ModelProblem[] = [];
   const elements: RegistryElement[] = [];
-  const doc = parseDocument(text, { prettyErrors: false, uniqueKeys: false });
+  // prettyErrors would put line numbers into the messages; the line counter gives them without.
+  const lines = new LineCounter();
+  const doc = parseDocument(text, { prettyErrors: false, uniqueKeys: false, lineCounter: lines });
   for (const error of doc.errors) {
-    problems.push({ message: `Registry is not valid YAML: ${error.message.split('\n')[0]}`, severity: 'error', file, line: error.linePos?.[0].line ? error.linePos[0].line - 1 : 0 });
+    problems.push({ message: `Registry is not valid YAML: ${error.message.split('\n')[0]}`, severity: 'error', file, line: lines.linePos(error.pos[0]).line - 1 });
   }
   if (doc.errors.length) return { elements, problems };
   const lineOf = (offset: number | undefined) => (offset === undefined ? 0 : text.slice(0, offset).split('\n').length - 1);

src/util/textDiff.ts

@@ -0,0 +1,64 @@
+// Text helpers shared by the host and the Source view in the page. The page's
+// editor always works in "\n" text; documents may use "\r\n".
+
+export interface TextChange {
+  from: number;
+  to: number;
+  insert: string;
+}
+
+/** The text with "\r\n" turned into "\n". */
+export function normalizeEol(text: string): string {
+  return text.replace(/\r\n/g, '\n');
+}
+
+/**
+ * The smallest single change that turns `before` into `after`: the common
+ * start and end are kept, so a cursor outside the change stays put.
+ */
+export function minimalChange(before: string, after: string): TextChange | undefined {
+  if (before === after) return undefined;
+  let start = 0;
+  const max = Math.min(before.length, after.length);
+  while (start < max && before.charCodeAt(start) === after.charCodeAt(start)) start++;
+  let endBefore = before.length;
+  let endAfter = after.length;
+  while (endBefore > start && endAfter > start && before.charCodeAt(endBefore - 1) === after.charCodeAt(endAfter - 1)) {
+    endBefore--;
+    endAfter--;
+  }
+  return { from: start, to: endBefore, insert: after.slice(start, endAfter) };
+}
+
+/** Line and character of an offset into "\n" text. */
+export function positionOf(text: string, offset: number): { line: number; character: number } {
+  const clamped = Math.max(0, Math.min(offset, text.length));
+  let line = 0;
+  let lineStart = 0;
+  for (let i = text.indexOf('\n'); i !== -1 && i < clamped; i = text.indexOf('\n', i + 1)) {
+    line++;
+    lineStart = i + 1;
+  }
+  return { line, character: clamped - lineStart };
+}
+
+/** Offset into "\n" text of a line and character (clamped to the line). */
+export function offsetOf(text: string, line: number, character: number): number {
+  let start = 0;
+  for (let l = 0; l < line; l++) {
+    const next = text.indexOf('\n', start);
+    if (next === -1) return text.length;
+    start = next + 1;
+  }
+  const end = text.indexOf('\n', start);
+  return Math.min(start + Math.max(0, character), end === -1 ? text.length : end);
+}
+
+/** Applies changes given in the coordinates of `text` (as one editor transaction reports them). */
+export function applyChanges(text: string, changes: TextChange[]): string {
+  let out = text;
+  for (const change of [...changes].sort((a, b) => b.from - a.from)) {
+    out = out.slice(0, change.from) + change.insert + out.slice(change.to);
+  }
+  return out;
+}

src/viewer3d/index.ts

@@ -58,13 +58,20 @@ class Viewer3D {
     this.interceptViewerControls();
     if (this.saved.active ?? host.defaultView === '3d') this.setActive(true);
     else this.syncButtons();
+    // The Source view hides the picture; the stage stops drawing meanwhile.
+    window.addEventListener('archify-source', (event) => {
+      if (!this.active || !this.stage) return;
+      if ((event as CustomEvent<{ on: boolean }>).detail.on) this.stage.stop();
+      else this.stage.start();
+    });
   }
 
   // -------------------------------------------------------------- chrome
 
   /**
-   * The 2D | 3D switch: Export's twin in the toolbar. Both states are always
+   * The 2D | 3D switch in the toolbar, left of Diagram | Graph | Source (it
-   * visible, the filled half is the current one, a click flips it.
+   * says how the picture is drawn, that one what is shown). Both states are
+   * always visible, the filled half is the current one, a click flips it.
    */
   private buildSwitch(): HTMLButtonElement {
     const button = document.createElement('button');
@@ -79,8 +86,8 @@ class Viewer3D {
       event.stopPropagation();
       this.setActive(!this.active);
     });
-    const exportWrap = document.querySelector('.toolbar .export-wrap');
+    const anchor = document.querySelector('.toolbar #archify-mode-switch') ?? document.querySelector('.toolbar .export-wrap');
-    if (exportWrap?.parentElement) exportWrap.parentElement.insertBefore(button, exportWrap);
+    if (anchor?.parentElement) anchor.parentElement.insertBefore(button, anchor);
     else document.querySelector('.toolbar')?.appendChild(button);
     return button;
   }

src/views/decisionView.ts

@@ -6,31 +6,41 @@ import { DecisionPanel, decisionPanelFromIndex, decisionPanelStandalone } from '
 import { ModelService } from '../model/service';
 import { readText } from '../util/files';
 import { log } from '../util/log';
+import { sourceScriptUri } from '../webview/viewer3d';
+import { SourceSession } from './sourceSession';
 import { handleWebviewMessage, WebviewMessage } from '../webview/messages';
 import { decisionPage, makeNonce } from '../webview/page';
 import { DECISION_VIEW_TYPE, DIAGRAM_EDITOR_VIEW_TYPE, REGISTRY_VIEW_TYPE } from './viewTypes';
 
 export { DECISION_VIEW_TYPE };
 
-class DecisionDocument implements vscode.CustomDocument {
-  constructor(readonly uri: vscode.Uri) {}
-  dispose(): void {}
-}
-
 class DecisionView implements vscode.Disposable {
   private seq = 0;
   private timer: NodeJS.Timeout | undefined;
   private last: string | undefined;
   root: vscode.Uri | undefined;
   private readonly disposables: vscode.Disposable[] = [];
+  /** The Source view; while it shows, a new page waits in `heldHtml`. */
+  readonly source: SourceSession;
+  private heldHtml: string | undefined;
 
   constructor(
+    private readonly context: vscode.ExtensionContext,
     private readonly models: ModelService,
     readonly panel: vscode.WebviewPanel,
     readonly uri: vscode.Uri,
   ) {
+    this.source = new SourceSession(context, panel, uri, 'decision', (shown) => {
+      if (!shown && this.heldHtml !== undefined) {
+        const html = this.heldHtml;
+        this.heldHtml = undefined;
+        this.panel.webview.html = html;
+      }
+    });
     this.disposables.push(
+      this.source,
       panel.webview.onDidReceiveMessage((message: WebviewMessage) => {
+        if (this.source.handle(message)) return;
         if (message.type === 'openDiagram') return void this.openInModel(message.path, DIAGRAM_EDITOR_VIEW_TYPE);
         if (message.type === 'openRegistry') return void this.openRegistryLine(message.file, message.line);
         if (message.type === 'openDecision') return void this.openInModel(message.file, DECISION_VIEW_TYPE);
@@ -86,7 +96,12 @@ class DecisionView implements vscode.Disposable {
     const fingerprint = JSON.stringify(decision);
     if (fingerprint === this.last) return;
     this.last = fingerprint;
-    this.panel.webview.html = decisionPage({ cspSource: this.panel.webview.cspSource, nonce: makeNonce() }, decision);
+    const html = decisionPage(
+      { cspSource: this.panel.webview.cspSource, nonce: makeNonce(), source: { scriptUri: sourceScriptUri(this.panel.webview, this.context.extensionUri), left: 'View' } },
+      decision,
+    );
+    if (this.source.shown) this.heldHtml = html;
+    else this.panel.webview.html = html;
   }
 
   dispose(): void {
@@ -95,13 +110,16 @@ class DecisionView implements vscode.Disposable {
   }
 }
 
-/** Read-only custom editor for .archify-decision files: the decision as a page, with its elements and diagrams. */
+/** Custom editor for .archify-decision files: the decision as a page, with its elements and diagrams. */
-export class DecisionViewProvider implements vscode.CustomReadonlyEditorProvider<DecisionDocument>, vscode.Disposable {
+export class DecisionViewProvider implements vscode.CustomTextEditorProvider, vscode.Disposable {
   private readonly views = new Set<DecisionView>();
   private active: DecisionView | undefined;
   private readonly disposables: vscode.Disposable[];
 
-  constructor(private readonly models: ModelService) {
+  constructor(
+    private readonly context: vscode.ExtensionContext,
+    private readonly models: ModelService,
+  ) {
     this.disposables = [
       vscode.window.registerCustomEditorProvider(DECISION_VIEW_TYPE, this, {
         webviewOptions: { retainContextWhenHidden: true, enableFindWidget: true },
@@ -122,13 +140,16 @@ export class DecisionViewProvider implements vscode.CustomReadonlyEditorProvider
     return this.active?.uri;
   }
 
-  openCustomDocument(uri: vscode.Uri): DecisionDocument {
+  /** The view of the focused page, if any. */
-    return new DecisionDocument(uri);
+  get activeView(): { source: SourceSession } | undefined {
+    return this.active;
   }
 
-  async resolveCustomEditor(document: DecisionDocument, panel: vscode.WebviewPanel): Promise<void> {
+  // A text editor provider: the page edits the file's own TextDocument (in
+  // its Source view), so dirty state, save and undo are VS Code's.
+  async resolveCustomTextEditor(document: vscode.TextDocument, panel: vscode.WebviewPanel): Promise<void> {
     panel.webview.options = { enableScripts: true };
-    const view = new DecisionView(this.models, panel, document.uri);
+    const view = new DecisionView(this.context, this.models, panel, document.uri);
     this.views.add(view);
     const onViewState = () => {
       if (panel.active) this.active = view;

src/views/diagramView.ts

@@ -13,7 +13,8 @@ import { log } from '../util/log';
 import { viewerTheme } from '../util/settings';
 import { handleWebviewMessage, WebviewMessage } from '../webview/messages';
 import { graphPage, makeNonce, messagePage, modelPage, prepareDiagramHtml } from '../webview/page';
-import { graphScriptUri, viewer3dOption, viewerRoots } from '../webview/viewer3d';
+import { graphScriptUri, sourceScriptUri, viewer3dOption, viewerRoots } from '../webview/viewer3d';
+import { SourceSession } from './sourceSession';
 
 import { DECISION_VIEW_TYPE, DIAGRAM_EDITOR_VIEW_TYPE, PREVIEW_VIEW_TYPE, REGISTRY_VIEW_TYPE } from './viewTypes';
 
@@ -50,6 +51,10 @@ class DiagramPreview implements vscode.Disposable {
   private graphQuery: string | undefined;
   /** True while the webview shows the Graph page, which takes model updates as messages. */
   private graphShown = false;
+  /** The Source view of a .archify file; while it shows, new HTML waits in `heldHtml`. */
+  readonly source: SourceSession | undefined;
+  private heldHtml: string | undefined;
+  private disposed = false;
 
   constructor(
     private readonly context: vscode.ExtensionContext,
@@ -69,9 +74,22 @@ class DiagramPreview implements vscode.Disposable {
       panel.title = `Preview ${path.basename(uri.path)}`;
     }
 
+    if (isArchifyFile(uri.path)) {
+      this.source = new SourceSession(context, panel, uri, 'diagram', (shown) => {
+        // Back from Source: show what was rendered meanwhile.
+        if (!shown && this.heldHtml !== undefined) {
+          const html = this.heldHtml;
+          this.heldHtml = undefined;
+          this.panel.webview.html = html;
+        }
+      });
+      this.disposables.push(this.source);
+    }
+
     this.disposables.push(
       panel.onDidDispose(() => this.dispose()),
       panel.webview.onDidReceiveMessage((message: WebviewMessage) => {
+        if (this.source?.handle(message)) return;
         if (message.type === 'hash') {
           this.hash = message.hash;
           return;
@@ -121,6 +139,22 @@ class DiagramPreview implements vscode.Disposable {
     Promise.resolve(this.panel.webview.postMessage(message)).catch(() => undefined);
   }
 
+  /** Replaces the page, unless Source is open in it: then the page waits until it closes. */
+  private setHtml(html: string): void {
+    if (this.disposed) return;
+    if (this.source?.shown) {
+      this.heldHtml = html;
+      return;
+    }
+    this.heldHtml = undefined;
+    this.panel.webview.html = html;
+  }
+
+  /** Page option for the Source view, on .archify files. */
+  private sourceOption(left: 'Model' | 'Diagram'): { scriptUri: string; left: 'Model' | 'Diagram' } | undefined {
+    return this.source ? { scriptUri: sourceScriptUri(this.panel.webview, this.context.extensionUri), left } : undefined;
+  }
+
   private state(): PreviewState {
     return { uri: this.uri.toString(), hash: this.hash, graph: this.graph };
   }
@@ -131,6 +165,10 @@ class DiagramPreview implements vscode.Disposable {
 
   /** Switches a main.archify editor between its model page and the Graph page. */
   setGraph(on: boolean, query?: string): void {
+    // Leaving Source for another page: drop what it held, or that page would
+    // wait for a sourceClose that never comes and show up later instead.
+    this.heldHtml = undefined;
+    this.source?.leave();
     this.graph = on;
     this.graphQuery = query;
     const modes = this.graphModes();
@@ -156,21 +194,21 @@ class DiagramPreview implements vscode.Disposable {
       return;
     }
     this.graphShown = true;
-    this.panel.webview.html = graphPage(
+    this.setHtml(graphPage(
       { cspSource: this.panel.webview.cspSource, nonce: makeNonce(), state: this.state() },
       { graph, query: this.graphQuery, scriptUri: graphScriptUri(this.panel.webview, this.context.extensionUri) },
-    );
+    ));
     this.graphQuery = undefined;
   }
 
   private showMessage(title: string, body: string, detail?: string): void {
     this.lastHtml = undefined;
-    this.panel.webview.html = messagePage(
+    this.setHtml(messagePage(
-      { cspSource: this.panel.webview.cspSource, nonce: makeNonce(), state: this.state() },
+      { cspSource: this.panel.webview.cspSource, nonce: makeNonce(), state: this.state(), source: this.sourceOption('Diagram') },
       title,
       body,
       detail,
-    );
+    ));
   }
 
   /** Opens a diagram of the model, given its path relative to the model root. */
@@ -192,7 +230,7 @@ class DiagramPreview implements vscode.Disposable {
     this.lastHtml = fingerprint;
     this.rendered = false;
     this.graphShown = false;
-    this.panel.webview.html = modelPage({ cspSource: this.panel.webview.cspSource, nonce: makeNonce(), state: this.state() }, model);
+    this.setHtml(modelPage({ cspSource: this.panel.webview.cspSource, nonce: makeNonce(), state: this.state(), source: this.sourceOption('Model') }, model));
   }
 
   scheduleUpdate(): void {
@@ -203,6 +241,7 @@ class DiagramPreview implements vscode.Disposable {
 
   async update(force = false): Promise<void> {
     clearTimeout(this.timer);
+    if (this.disposed) return;
     const seq = ++this.seq;
     let text: string;
     try {
@@ -285,6 +324,7 @@ class DiagramPreview implements vscode.Disposable {
       decisions: prepared.decisions,
       model,
       graphSwitch: main ? { left: 'Model' } : prepared.root ? { left: 'Diagram', query: `diagram:${path.relative(prepared.root.fsPath, this.uri.fsPath).split(path.sep).join('/')}` } : undefined,
+      source: this.sourceOption(main ? 'Model' : 'Diagram'),
     });
     // Nonces differ per render, so compare the renderer output instead.
     const fingerprint = `${viewerTheme()}\u0000${result.evidenceNotice ?? ''}\u0000${JSON.stringify([model ?? null, [...prepared.links], [...prepared.descriptions], prepared.decisions])}\u0000${result.html}`;
@@ -294,10 +334,14 @@ class DiagramPreview implements vscode.Disposable {
     }
     this.lastHtml = fingerprint;
     this.rendered = true;
-    this.panel.webview.html = html;
+    this.setHtml(html);
   }
 
   dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    // Renders in flight check the sequence after every await; this ends them.
+    this.seq++;
     clearTimeout(this.timer);
     this.onDisposeEmitter.fire();
     this.onDisposeEmitter.dispose();

src/views/registryView.ts

@@ -5,31 +5,41 @@ import { RegistryPanel, registryPanelFromIndex, registryPanelStandalone } from '
 import { ModelService } from '../model/service';
 import { readText } from '../util/files';
 import { log } from '../util/log';
+import { sourceScriptUri } from '../webview/viewer3d';
+import { SourceSession } from './sourceSession';
 import { handleWebviewMessage, WebviewMessage } from '../webview/messages';
 import { makeNonce, registryPage } from '../webview/page';
 import { DECISION_VIEW_TYPE, DIAGRAM_EDITOR_VIEW_TYPE, REGISTRY_VIEW_TYPE } from './viewTypes';
 
 export { REGISTRY_VIEW_TYPE };
 
-class RegistryDocument implements vscode.CustomDocument {
-  constructor(readonly uri: vscode.Uri) {}
-  dispose(): void {}
-}
-
 class RegistryView implements vscode.Disposable {
   private seq = 0;
   private timer: NodeJS.Timeout | undefined;
   private last: string | undefined;
   root: vscode.Uri | undefined;
   private readonly disposables: vscode.Disposable[] = [];
+  /** The Source view; while it shows, a new page waits in `heldHtml`. */
+  readonly source: SourceSession;
+  private heldHtml: string | undefined;
 
   constructor(
+    private readonly context: vscode.ExtensionContext,
     private readonly models: ModelService,
     readonly panel: vscode.WebviewPanel,
     readonly uri: vscode.Uri,
   ) {
+    this.source = new SourceSession(context, panel, uri, 'registry', (shown) => {
+      if (!shown && this.heldHtml !== undefined) {
+        const html = this.heldHtml;
+        this.heldHtml = undefined;
+        this.panel.webview.html = html;
+      }
+    });
     this.disposables.push(
+      this.source,
       panel.webview.onDidReceiveMessage((message: WebviewMessage) => {
+        if (this.source.handle(message)) return;
         if (message.type === 'openDiagram') return void this.openInModel(message.path, DIAGRAM_EDITOR_VIEW_TYPE);
         if (message.type === 'openRegistry') return void this.openRegistryLine(message.file, message.line);
         if (message.type === 'openDecision') return void this.openInModel(message.file, DECISION_VIEW_TYPE);
@@ -84,7 +94,12 @@ class RegistryView implements vscode.Disposable {
     const fingerprint = JSON.stringify(registry);
     if (fingerprint === this.last) return;
     this.last = fingerprint;
-    this.panel.webview.html = registryPage({ cspSource: this.panel.webview.cspSource, nonce: makeNonce() }, registry);
+    const html = registryPage(
+      { cspSource: this.panel.webview.cspSource, nonce: makeNonce(), source: { scriptUri: sourceScriptUri(this.panel.webview, this.context.extensionUri), left: 'View' } },
+      registry,
+    );
+    if (this.source.shown) this.heldHtml = html;
+    else this.panel.webview.html = html;
   }
 
   dispose(): void {
@@ -93,12 +108,15 @@ class RegistryView implements vscode.Disposable {
   }
 }
 
-export class RegistryViewProvider implements vscode.CustomReadonlyEditorProvider<RegistryDocument>, vscode.Disposable {
+export class RegistryViewProvider implements vscode.CustomTextEditorProvider, vscode.Disposable {
   private readonly views = new Set<RegistryView>();
   private active: RegistryView | undefined;
   private readonly disposables: vscode.Disposable[];
 
-  constructor(private readonly models: ModelService) {
+  constructor(
+    private readonly context: vscode.ExtensionContext,
+    private readonly models: ModelService,
+  ) {
     this.disposables = [
       vscode.window.registerCustomEditorProvider(REGISTRY_VIEW_TYPE, this, {
         webviewOptions: { retainContextWhenHidden: true, enableFindWidget: true },
@@ -121,13 +139,16 @@ export class RegistryViewProvider implements vscode.CustomReadonlyEditorProvider
     return this.active?.uri;
   }
 
-  openCustomDocument(uri: vscode.Uri): RegistryDocument {
+  /** The view of the focused page, if any. */
-    return new RegistryDocument(uri);
+  get activeView(): { source: SourceSession } | undefined {
+    return this.active;
   }
 
-  async resolveCustomEditor(document: RegistryDocument, panel: vscode.WebviewPanel): Promise<void> {
+  // A text editor provider: the page edits the file's own TextDocument (in
+  // its Source view), so dirty state, save and undo are VS Code's.
+  async resolveCustomTextEditor(document: vscode.TextDocument, panel: vscode.WebviewPanel): Promise<void> {
     panel.webview.options = { enableScripts: true };
-    const view = new RegistryView(this.models, panel, document.uri);
+    const view = new RegistryView(this.context, this.models, panel, document.uri);
     this.views.add(view);
     const onViewState = () => {
       if (panel.active) this.active = view;

src/views/sourceSession.ts

@@ -0,0 +1,201 @@
+import * as vscode from 'vscode';
+import { EditorSchemas } from '../language/editorSchemas';
+import { readSchemas } from '../language/schemaCheck';
+import { log } from '../util/log';
+import { TextChange, normalizeEol, offsetOf, positionOf } from '../util/textDiff';
+
+/** Page → host messages of the Source view. */
+export type SourceMessage =
+  | { type: 'sourceReady' }
+  | { type: 'sourceOpen' }
+  | { type: 'sourceClose' }
+  | { type: 'sourceEdit'; base: string; text: string; changes: TextChange[] };
+
+export type SourceKind = 'diagram' | 'registry' | 'decision';
+
+const CHECKS: Record<SourceKind, string> = {
+  diagram: 'YAML · checked against the Archify schema and the model',
+  registry: 'YAML · checked against the registry schema and the model',
+  decision: 'YAML · checked as a decision of the model',
+};
+
+let editorSchemas: EditorSchemas | undefined;
+
+function schemasFor(context: vscode.ExtensionContext): EditorSchemas {
+  editorSchemas ??= new EditorSchemas(readSchemas(vscode.Uri.joinPath(context.extensionUri, 'schemas').fsPath));
+  return editorSchemas;
+}
+
+export function isSourceMessage(message: { type?: string }): message is SourceMessage {
+  return message.type === 'sourceReady' || message.type === 'sourceOpen' || message.type === 'sourceClose' || message.type === 'sourceEdit';
+}
+
+/**
+ * The host half of a page's Source view. The document stays VS Code's: page
+ * edits become WorkspaceEdits (so dirty state, save, undo and Git work as
+ * for any file), and changes from anywhere else (undo, the text editor, git)
+ * go back to the page. Problems are whatever the Problems panel holds for the
+ * file, sent as offsets; the page shows their count on the Source switch even
+ * while the picture is shown.
+ */
+export class SourceSession implements vscode.Disposable {
+  /** True while the page shows Source; the view must not replace its HTML then. */
+  shown = false;
+  /** Texts our own edits will produce, oldest first; their change events are not echoed. */
+  private readonly expected: string[] = [];
+  private queue: Promise<void> = Promise.resolve();
+  private schemaKey: string | undefined;
+  private readonly disposables: vscode.Disposable[];
+
+  constructor(
+    private readonly context: vscode.ExtensionContext,
+    private readonly panel: vscode.WebviewPanel,
+    readonly uri: vscode.Uri,
+    readonly kind: SourceKind,
+    /** Called when Source opens or closes, so the view can hold or apply its HTML. */
+    private readonly onShown: (shown: boolean) => void,
+  ) {
+    const same = (uri: vscode.Uri) => uri.toString() === this.uri.toString();
+    this.disposables = [
+      vscode.languages.onDidChangeDiagnostics((event) => {
+        if (event.uris.some(same)) void this.postDiagnostics();
+      }),
+      vscode.workspace.onDidChangeTextDocument((event) => {
+        if (!same(event.document.uri) || !event.contentChanges.length) return;
+        this.post({ type: 'sourceDirty', dirty: event.document.isDirty });
+        if (this.shown) this.syncFrom(event.document);
+      }),
+      vscode.workspace.onDidSaveTextDocument((doc) => {
+        if (same(doc.uri)) this.post({ type: 'sourceDirty', dirty: false });
+      }),
+    ];
+  }
+
+  /** Asks the page to show its Source view (Archify | Show Source). */
+  reveal(): void {
+    this.post({ type: 'setView', view: 'source' });
+  }
+
+  /** The page is being replaced by another one (the Graph page): Source is no longer shown. */
+  leave(): void {
+    this.setShown(false);
+  }
+
+  /** Handles a Source message from the page; false for any other message. */
+  handle(message: { type?: string }): boolean {
+    if (!isSourceMessage(message)) return false;
+    switch (message.type) {
+      case 'sourceReady':
+        void this.postDiagnostics();
+        break;
+      case 'sourceOpen':
+        this.setShown(true);
+        void this.sendText(true);
+        break;
+      case 'sourceClose':
+        this.setShown(false);
+        break;
+      case 'sourceEdit':
+        this.edit(message);
+        break;
+    }
+    return true;
+  }
+
+  private setShown(shown: boolean): void {
+    if (this.shown === shown) return;
+    this.shown = shown;
+    this.onShown(shown);
+  }
+
+  private post(message: unknown): void {
+    Promise.resolve(this.panel.webview.postMessage(message)).catch(() => undefined);
+  }
+
+  private document(): Promise<vscode.TextDocument> {
+    return Promise.resolve(vscode.workspace.openTextDocument(this.uri));
+  }
+
+  private async sendText(withDiagnostics: boolean): Promise<void> {
+    const doc = await this.document();
+    const text = normalizeEol(doc.getText());
+    this.expected.length = 0;
+    this.schemaKey = undefined;
+    this.post({ type: 'sourceText', text, schema: this.schemaChange(text), checks: CHECKS[this.kind] });
+    this.post({ type: 'sourceDirty', dirty: doc.isDirty });
+    if (withDiagnostics) await this.postDiagnostics();
+  }
+
+  /** The editor schema when it differs from the one the page has (a diagram's type may change), else undefined. */
+  private schemaChange(text: string): { key: string; schema: object } | null | undefined {
+    const next = schemasFor(this.context).forSource(this.kind, text);
+    const key = next?.key ?? '';
+    if (key === this.schemaKey) return undefined;
+    this.schemaKey = key;
+    return next ?? null;
+  }
+
+  private syncFrom(doc: vscode.TextDocument): void {
+    const text = normalizeEol(doc.getText());
+    const index = this.expected.indexOf(text);
+    if (index !== -1) {
+      // Our own edit coming back; anything older is settled too.
+      this.expected.splice(0, index + 1);
+      return;
+    }
+    this.post({ type: 'sourceText', text, schema: this.schemaChange(text), checks: CHECKS[this.kind] });
+  }
+
+  private edit(message: Extract<SourceMessage, { type: 'sourceEdit' }>): void {
+    this.expected.push(message.text);
+    const schema = this.schemaChange(message.text);
+    if (schema !== undefined) this.post({ type: 'sourceSchema', schema });
+    this.queue = this.queue.then(async () => {
+      try {
+        const doc = await this.document();
+        const current = normalizeEol(doc.getText());
+        if (current === message.text) return;
+        const edit = new vscode.WorkspaceEdit();
+        // Positions come from "\n" text; VS Code turns inserted text into the document's line endings.
+        const at = (text: string, offset: number) => {
+          const { line, character } = positionOf(text, offset);
+          return new vscode.Position(line, character);
+        };
+        if (current === message.base) {
+          for (const change of message.changes) edit.replace(this.uri, new vscode.Range(at(current, change.from), at(current, change.to)), change.insert);
+        } else {
+          // The document moved on under the page (rare): the page's text wins.
+          edit.replace(this.uri, new vscode.Range(at(current, 0), at(current, current.length)), message.text);
+        }
+        if (!(await vscode.workspace.applyEdit(edit))) {
+          log().warn(`Source edit was not applied to ${this.uri.fsPath}`);
+          void this.sendText(false);
+        }
+      } catch (error) {
+        log().error(`Source edit failed for ${this.uri.fsPath}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    });
+  }
+
+  /** Problems of the file as offsets into its "\n" text, and their count for the switch. */
+  async postDiagnostics(): Promise<void> {
+    const diagnostics = vscode.languages.getDiagnostics(this.uri);
+    let items: unknown[] = [];
+    if (this.shown && diagnostics.length) {
+      const text = normalizeEol((await this.document()).getText());
+      items = diagnostics.map((d) => ({
+        from: offsetOf(text, d.range.start.line, d.range.start.character),
+        to: offsetOf(text, d.range.end.line, d.range.end.character),
+        severity: d.severity === vscode.DiagnosticSeverity.Error ? 'error' : d.severity === vscode.DiagnosticSeverity.Warning ? 'warning' : 'info',
+        message: d.message,
+        source: d.source,
+      }));
+    }
+    const count = diagnostics.filter((d) => d.severity === vscode.DiagnosticSeverity.Error || d.severity === vscode.DiagnosticSeverity.Warning).length;
+    this.post({ type: 'sourceDiagnostics', items, count });
+  }
+
+  dispose(): void {
+    for (const d of this.disposables.splice(0)) d.dispose();
+  }
+}

src/webview/page.ts

@@ -28,6 +28,8 @@ export interface PageOptions {
   decisions?: DiagramDecision[];
   /** Pages inside a model get a switch to the model's Graph page; `left` names the page they are on. */
   graphSwitch?: { left: 'Model' | 'Diagram'; query?: string };
+  /** Pages of a file that can be edited in place: the Source view's script, and the name of the page's own view. */
+  source?: { scriptUri: string; left: 'Model' | 'Diagram' | 'View' };
   /** The Graph page: the model as one graph, the bundled script that draws it, and the query to start with. */
   graph?: { graph: ModelGraph; query?: string; scriptUri: string };
 }
@@ -93,6 +95,7 @@ function bridgeScript(options: PageOptions): string {
     decisions: options.decisions || [],
     descriptions: options.descriptions || {},
     graphSwitch: options.graphSwitch,
+    source: options.source,
     graph: options.graph ? { graph: options.graph.graph, query: options.graph.query } : undefined,
   };
   return `(function () {
@@ -676,35 +679,102 @@ function bridgeScript(options: PageOptions): string {
     if (anchor && anchor.parentNode) anchor.parentNode.insertBefore(body, anchor.nextSibling); else document.body.appendChild(body);
   }
 
-  // Model | Graph (or Diagram | Graph): Export's twin in Archify's toolbar,
+  // What the page shows: Diagram | Graph | Source (Model | Graph | Source on
-  // or at the top of the model page. Graph opens the model's Graph page.
+  // main.archify, View | Source on registry and decision pages). It sits
+  // left of Export in Archify's toolbar, after 2D | 3D, which only says how
+  // the picture is drawn; on our own pages it sits top right. Graph opens the
+  // model's Graph page; Source puts the file's YAML in place of the picture.
+  var sourceOn = false;
+  var syncModeSwitch = function () {};
   function renderModeSwitch() {
     var sw = config.graphSwitch;
-    if (!sw || document.getElementById('archify-mode-switch')) return;
+    var src = config.source;
-    var button = el('button', 'archify-mode-switch');
+    if ((!sw && !src) || document.getElementById('archify-mode-switch')) return;
-    button.id = 'archify-mode-switch';
+    var group = el('div', 'archify-mode-switch');
-    button.type = 'button';
+    group.id = 'archify-mode-switch';
-    button.title = 'Open the model as one graph, with a query box';
+    group.setAttribute('role', 'group');
-    button.setAttribute('aria-label', sw.left + ' view; switch to the model graph');
+    group.setAttribute('aria-label', 'View');
-    button.appendChild(el('span', 'archify-mode-seg on', sw.left));
+    function segment(label, title, action) {
-    button.appendChild(el('span', 'archify-mode-seg', 'Graph'));
+      var button = el('button', 'archify-mode-seg', label);
-    button.addEventListener('click', function (event) {
+      button.type = 'button';
-      event.stopPropagation();
+      button.title = title;
+      button.addEventListener('click', function (event) { event.stopPropagation(); action(); });
+      group.appendChild(button);
+      return button;
+    }
+    var name = (src && src.left) || sw.left;
+    var left = segment(name, name === 'View' ? 'Show the page' : 'Show the ' + name.toLowerCase(), function () { setSource(false); });
+    if (sw) segment('Graph', 'Open the model as one graph, with a query box', function () {
+      // On main.archify the Graph page replaces this one; coming back must
+      // show the model, not Source. Other pages open the graph beside them.
+      if (sourceOn && config.model) vscode.setState(Object.assign({}, vscode.getState() || {}, { sourceView: false }));
       post({ type: 'showGraph', query: sw.query });
     });
+    var source = src ? segment('Source', 'Edit the YAML of this file, checked as you type', function () { setSource(true); }) : null;
+    if (source) {
+      var badge = el('span', 'archify-source-badge');
+      badge.id = 'archify-source-badge';
+      badge.hidden = true;
+      source.appendChild(badge);
+    }
+    syncModeSwitch = function () {
+      left.classList.toggle('on', !sourceOn);
+      left.setAttribute('aria-pressed', String(!sourceOn));
+      if (source) {
+        source.classList.toggle('on', sourceOn);
+        source.setAttribute('aria-pressed', String(sourceOn));
+      }
+    };
+    syncModeSwitch();
     var exportWrap = document.querySelector('.toolbar .export-wrap');
     var head = document.querySelector('.archify-model-head');
-    if (exportWrap && exportWrap.parentNode) exportWrap.parentNode.insertBefore(button, exportWrap);
+    if (exportWrap && exportWrap.parentNode) exportWrap.parentNode.insertBefore(group, exportWrap);
-    else if (head) {
+    else {
       var row = el('div', 'archify-model-switch-row');
-      row.appendChild(button);
+      row.appendChild(group);
-      head.insertBefore(row, head.firstChild);
+      if (head) head.insertBefore(row, head.firstChild);
-    } else document.body.appendChild(button);
+      else document.body.insertBefore(row, document.body.firstChild);
+    }
+  }
+
+  // The Source view lives in dist/source.js, loaded the first time it is chosen.
+  function setSource(on) {
+    if (!config.source || on === sourceOn) return;
+    sourceOn = on;
+    vscode.setState(Object.assign({}, vscode.getState() || {}, { sourceView: on }));
+    syncModeSwitch();
+    if (!on) {
+      if (window.__archifySource) window.__archifySource.close();
+      return;
+    }
+    if (window.__archifySource) {
+      window.__archifySource.open();
+      return;
+    }
+    var script = document.createElement('script');
+    script.src = config.source.scriptUri;
+    script.onload = function () { if (sourceOn && window.__archifySource) window.__archifySource.open(); };
+    script.onerror = function () {
+      sourceOn = false;
+      syncModeSwitch();
+      post({ type: 'error', message: 'The Source view could not be loaded.' });
+    };
+    document.head.appendChild(script);
+  }
+
+  function showProblemCount(count) {
+    var badge = document.getElementById('archify-source-badge');
+    if (!badge) return;
+    badge.hidden = !count;
+    badge.textContent = count ? String(count) : '';
+    badge.title = count ? count + (count === 1 ? ' problem' : ' problems') + ' in the source' : '';
   }
 
   window.addEventListener('message', function (event) {
     var message = event.data || {};
     if (message.type === 'notice') showNotice(message.notice);
+    if (message.type === 'sourceDiagnostics') showProblemCount(message.count);
+    if (message.type === 'setView') setSource(message.view === 'source');
   });
   function onReady(fn) {
     if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', fn);
@@ -717,6 +787,11 @@ function bridgeScript(options: PageOptions): string {
   onReady(renderDecisionsRail);
   onReady(describeElements);
   onReady(renderModeSwitch);
+  if (config.source) {
+    // The host answers with the problem count for the Source badge.
+    post({ type: 'sourceReady' });
+    if ((vscode.getState() || {}).sourceView) onReady(function () { setSource(true); });
+  }
   if (config.notice) {
     if (document.readyState === 'loading') {
       document.addEventListener('DOMContentLoaded', function () { showNotice(config.notice); });
@@ -731,6 +806,8 @@ const MODEL_STYLE = `
 .archify-model { --m-text: var(--text, var(--vscode-foreground, CanvasText)); --m-muted: var(--text-muted, var(--vscode-descriptionForeground, GrayText)); --m-panel: var(--panel, var(--vscode-editorWidget-background, Canvas)); --m-border: var(--panel-border, var(--vscode-editorWidget-border, rgba(128,128,128,.35))); --m-accent: var(--frontend-stroke, var(--vscode-textLink-foreground));
   max-width: 1400px; margin: 0 auto; padding: 1.25rem 2rem; color: var(--m-text); font-family: var(--vscode-font-family, system-ui, sans-serif); }
 .archify-model-head { padding-top: 1.5rem; }
+/* Under Archify's fixed toolbar (diagram pages of main.archify), start below it. */
+.toolbar ~ .archify-model-head { padding-top: 4.25rem; }
 .archify-model-kicker { font-size: 0.6875rem; font-weight: 700; letter-spacing: 0.12em; text-transform: uppercase; color: var(--m-accent); }
 .archify-model-name { margin: 0.25rem 0 0.5rem; font-size: 1.5rem; font-weight: 700; letter-spacing: -0.02em; }
 .archify-model-description { margin: 0; max-width: 72ch; font-size: 0.9375rem; line-height: 1.55; color: var(--m-muted); white-space: pre-line; }
@@ -815,15 +892,19 @@ const MODEL_STYLE = `
 
 /* The Model | Graph switch: in Archify's toolbar it is the 2D | 3D switch's twin; on the model page it sits top right. */
 const SWITCH_STYLE = `
-.archify-mode-switch { display: inline-flex; align-items: center; padding: 0 0.25rem; gap: 0; border: 0; background: transparent; color: var(--text-muted, var(--vscode-descriptionForeground)); font: inherit; cursor: pointer; position: relative; }
+.archify-mode-switch { display: inline-flex; align-items: center; padding: 0 0.25rem; gap: 0; color: var(--text-muted, var(--vscode-descriptionForeground)); position: relative; }
 .toolbar .archify-mode-switch::before { content: ""; position: absolute; inset: 0.25rem 0; border-radius: 0.6875rem; background: color-mix(in srgb, var(--panel) 78%, transparent); box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--panel-border) 85%, transparent), 0 1px 2px rgba(15, 23, 42, 0.04); backdrop-filter: blur(12px); }
 .toolbar .archify-mode-switch:hover::before { box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--text) 22%, transparent), 0 1px 2px rgba(15, 23, 42, 0.04); }
-.archify-mode-seg { position: relative; display: inline-flex; align-items: center; height: 1.75rem; padding: 0 0.7rem; border-radius: 0.5rem; font-weight: 550; font-size: 0.8125rem; transition: background 0.15s, color 0.15s; }
+/* Anchored on the id: Archify's .toolbar button rules (one of them with :not(#btn-theme)) would win otherwise. */
-.archify-mode-seg.on { color: var(--bg, var(--vscode-editor-background)); background: var(--text, var(--vscode-foreground)); box-shadow: 0 1px 2px rgba(15, 23, 42, 0.12), 0 6px 16px -8px rgba(15, 23, 42, 0.4); }
+#archify-mode-switch .archify-mode-seg { position: relative; display: inline-flex; align-items: center; height: 1.75rem; padding: 0 0.7rem; border: 0; border-radius: 0.5rem; background: transparent; color: inherit; font: inherit; font-weight: 550; font-size: 0.8125rem; cursor: pointer; transition: background 0.15s, color 0.15s; }
-.archify-mode-switch:hover .archify-mode-seg:not(.on) { color: var(--text, var(--vscode-foreground)); }
+#archify-mode-switch .archify-mode-seg.on[aria-pressed="true"] { color: var(--bg, var(--vscode-editor-background)); background: var(--text, var(--vscode-foreground)); box-shadow: 0 1px 2px rgba(15, 23, 42, 0.12), 0 6px 16px -8px rgba(15, 23, 42, 0.4); }
-.archify-mode-switch:focus-visible { outline: 2px solid var(--frontend-stroke, var(--vscode-focusBorder)); outline-offset: 2px; border-radius: 0.75rem; }
+#archify-mode-switch .archify-mode-seg:hover:not(.on) { color: var(--text, var(--vscode-foreground)); }
+#archify-mode-switch .archify-mode-seg:focus-visible { outline: 2px solid var(--frontend-stroke, var(--vscode-focusBorder)); outline-offset: 1px; }
+.archify-source-badge { display: inline-block; min-width: 1rem; margin-left: 0.35rem; padding: 0 0.3rem; border-radius: 999px; background: var(--security-stroke, var(--vscode-editorError-foreground, #f14c4c)); color: var(--bg, #fff); font-size: 0.6875rem; font-weight: 700; line-height: 1rem; text-align: center; }
+.archify-source-badge[hidden] { display: none; }
 .archify-model-switch-row { float: right; margin: 1.5rem 0 0 1rem; }
-.archify-model-switch-row .archify-mode-switch { border: 1px solid var(--m-border); border-radius: 0.75rem; background: var(--m-panel); padding: 0.1rem 0.25rem; }
+body > .archify-model-switch-row { position: relative; z-index: 2; margin: 1rem 1.25rem 0 1rem; }
+.archify-model-switch-row .archify-mode-switch { border: 1px solid var(--m-border, var(--vscode-editorWidget-border, rgba(128,128,128,.35))); border-radius: 0.75rem; background: var(--m-panel, var(--vscode-editorWidget-background)); padding: 0.1rem 0.25rem; }
 `;
 
 /* Connectors rail panel: highlight of the hovered or selected edge in the SVG. */
@@ -895,8 +976,8 @@ export function prepareDiagramHtml(html: string, options: PageOptions): string {
 }
 
 /** The model page for a main.archify without a diagram of its own. */
-export function modelPage(options: Pick<PageOptions, 'cspSource' | 'nonce' | 'state'>, model: ModelPanel): string {
+export function modelPage(options: Pick<PageOptions, 'cspSource' | 'nonce' | 'state' | 'source'>, model: ModelPanel): string {
-  const bridge = bridgeScript({ cspSource: options.cspSource, nonce: options.nonce, theme: undefined, state: options.state, model, links: {}, graphSwitch: { left: 'Model' } });
+  const bridge = bridgeScript({ cspSource: options.cspSource, nonce: options.nonce, theme: undefined, state: options.state, model, links: {}, graphSwitch: { left: 'Model' }, source: options.source });
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -935,8 +1016,8 @@ export function graphPage(options: Pick<PageOptions, 'cspSource' | 'nonce' | 'st
 }
 
 /** The registry page for one .archify-registry file. */
-export function registryPage(options: Pick<PageOptions, 'cspSource' | 'nonce' | 'state'>, registry: RegistryPanel): string {
+export function registryPage(options: Pick<PageOptions, 'cspSource' | 'nonce' | 'state' | 'source'>, registry: RegistryPanel): string {
-  const bridge = bridgeScript({ cspSource: options.cspSource, nonce: options.nonce, theme: undefined, state: options.state, registry, links: {} });
+  const bridge = bridgeScript({ cspSource: options.cspSource, nonce: options.nonce, theme: undefined, state: options.state, registry, links: {}, source: options.source });
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -947,6 +1028,8 @@ export function registryPage(options: Pick<PageOptions, 'cspSource' | 'nonce' |
 <style>
   body { margin: 0; color: var(--vscode-foreground); background: var(--vscode-editor-background); }
   ${MODEL_STYLE}
+  ${SWITCH_STYLE}
+  ${NOTICE_STYLE}
 </style>
 </head>
 <body></body>
@@ -954,8 +1037,8 @@ export function registryPage(options: Pick<PageOptions, 'cspSource' | 'nonce' |
 }
 
 /** The decision page for one .archify-decision file. */
-export function decisionPage(options: Pick<PageOptions, 'cspSource' | 'nonce' | 'state'>, decision: DecisionPanel): string {
+export function decisionPage(options: Pick<PageOptions, 'cspSource' | 'nonce' | 'state' | 'source'>, decision: DecisionPanel): string {
-  const bridge = bridgeScript({ cspSource: options.cspSource, nonce: options.nonce, theme: undefined, state: options.state, decision, links: {} });
+  const bridge = bridgeScript({ cspSource: options.cspSource, nonce: options.nonce, theme: undefined, state: options.state, decision, links: {}, source: options.source });
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -966,28 +1049,34 @@ export function decisionPage(options: Pick<PageOptions, 'cspSource' | 'nonce' |
 <style>
   body { margin: 0; color: var(--vscode-foreground); background: var(--vscode-editor-background); }
   ${MODEL_STYLE}
+  ${SWITCH_STYLE}
+  ${NOTICE_STYLE}
 </style>
 </head>
 <body></body>
 </html>`;
 }
 
-/** A small VS Code-styled page for loading and error states. */
+/** A small VS Code-styled page for loading and error states; with `source`, the YAML can be fixed in place. */
 export function messagePage(
-  options: Pick<PageOptions, 'cspSource' | 'nonce' | 'state'>,
+  options: Pick<PageOptions, 'cspSource' | 'nonce' | 'state' | 'source'>,
   title: string,
   body: string,
   detail?: string,
 ): string {
+  const script = options.source
+    ? bridgeScript({ cspSource: options.cspSource, nonce: options.nonce, theme: undefined, state: options.state, links: {}, source: options.source })
+    : `(function () { var vscode = acquireVsCodeApi(); var state = ${scriptJson(options.state)}; if (state) vscode.setState(state); })();`;
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <meta http-equiv="Content-Security-Policy" content="${escapeHtml(contentSecurityPolicy(options.cspSource, options.nonce))}">
-<script nonce="${options.nonce}">(function () { var vscode = acquireVsCodeApi(); var state = ${scriptJson(options.state)}; if (state) vscode.setState(state); })();</script>
+<script nonce="${options.nonce}">${script}</script>
 <style>
   body { font-family: var(--vscode-font-family); color: var(--vscode-foreground); background: var(--vscode-editor-background); padding: 24px 28px; }
+  ${options.source ? SWITCH_STYLE + NOTICE_STYLE : ''}
   h2 { font-weight: 600; font-size: 15px; margin: 0 0 8px; }
   p { margin: 0 0 12px; color: var(--vscode-descriptionForeground); }
   pre { font-family: var(--vscode-editor-font-family); font-size: 12px; white-space: pre-wrap; word-break: break-word;

src/webview/source/codemirror-json-schema.d.ts

@@ -0,0 +1,5 @@
+// The package's "./yaml" export needs "bundler" module resolution; this
+// repository resolves like Node 10, so point at its types directly.
+declare module 'codemirror-json-schema/yaml' {
+  export * from 'codemirror-json-schema/dist/yaml/index';
+}

src/webview/source/editor.ts

@@ -0,0 +1,157 @@
+import { autocompletion, closeBrackets, closeBracketsKeymap, completionKeymap } from '@codemirror/autocomplete';
+import { defaultKeymap, history, historyKeymap, indentWithTab } from '@codemirror/commands';
+import { yaml, yamlLanguage } from '@codemirror/lang-yaml';
+import { HighlightStyle, bracketMatching, foldGutter, foldKeymap, indentOnInput, indentUnit, syntaxHighlighting } from '@codemirror/language';
+import { lintGutter, lintKeymap, nextDiagnostic, setDiagnostics } from '@codemirror/lint';
+import { Annotation, EditorState, Transaction } from '@codemirror/state';
+import {
+  EditorView,
+  drawSelection,
+  dropCursor,
+  highlightActiveLine,
+  highlightActiveLineGutter,
+  highlightSpecialChars,
+  hoverTooltip,
+  keymap,
+  lineNumbers,
+  rectangularSelection,
+} from '@codemirror/view';
+import { tags as t } from '@lezer/highlight';
+import { stateExtensions, updateSchema } from 'codemirror-json-schema';
+import { yamlCompletion, yamlSchemaHover } from 'codemirror-json-schema/yaml';
+import type { TextChange } from '../../util/textDiff';
+
+/** A problem from the host, as offsets into the "\n" text it checked. */
+export interface SourceDiagnostic {
+  from: number;
+  to: number;
+  severity: 'error' | 'warning' | 'info';
+  message: string;
+  source?: string;
+}
+
+/** Marks transactions that carry text from the host, so they are not sent back. */
+const fromHost = Annotation.define<boolean>();
+
+// The page's own variables (Archify's, or ours on model pages), so the
+// editor follows the page theme, light or dark.
+const theme = EditorView.theme({
+  '&': { height: '100%', color: 'var(--text, var(--vscode-editor-foreground))', backgroundColor: 'transparent', fontSize: '12.5px' },
+  '.cm-scroller': { fontFamily: 'var(--vscode-editor-font-family, ui-monospace, Menlo, "SF Mono", monospace)', lineHeight: '1.6' },
+  '.cm-content': { caretColor: 'var(--frontend-stroke, var(--vscode-editorCursor-foreground))' },
+  '.cm-cursor, .cm-dropCursor': { borderLeftColor: 'var(--frontend-stroke, var(--vscode-editorCursor-foreground))' },
+  '.cm-gutters': { backgroundColor: 'transparent', color: 'var(--text-muted, var(--vscode-editorLineNumber-foreground))', border: 'none' },
+  '.cm-activeLine, .cm-activeLineGutter': { backgroundColor: 'color-mix(in srgb, var(--text, var(--vscode-editor-foreground)) 5%, transparent)' },
+  '&.cm-focused .cm-selectionBackground, .cm-selectionBackground, .cm-content ::selection': {
+    backgroundColor: 'color-mix(in srgb, var(--frontend-stroke, var(--vscode-editor-selectionBackground)) 28%, transparent) !important',
+  },
+  '&.cm-focused': { outline: 'none' },
+  '.cm-tooltip': {
+    backgroundColor: 'var(--panel, var(--vscode-editorHoverWidget-background))',
+    color: 'var(--text, var(--vscode-editorHoverWidget-foreground))',
+    border: '1px solid var(--panel-border, var(--vscode-editorHoverWidget-border))',
+    borderRadius: '8px',
+    maxWidth: '440px',
+  },
+  '.cm-tooltip code': { fontFamily: 'var(--vscode-editor-font-family, ui-monospace, Menlo, monospace)', color: 'var(--frontend-stroke, var(--vscode-textPreformat-foreground))' },
+  '.cm-tooltip-autocomplete ul li[aria-selected]': { backgroundColor: 'var(--frontend-stroke, var(--vscode-list-activeSelectionBackground))', color: 'var(--bg, var(--vscode-list-activeSelectionForeground))' },
+  '.cm-diagnostic': { padding: '4px 8px' },
+  '.cm-foldPlaceholder': { backgroundColor: 'transparent', border: '1px solid var(--panel-border, var(--vscode-editorWidget-border))', color: 'inherit' },
+});
+
+const highlight = HighlightStyle.define([
+  { tag: [t.propertyName, t.definition(t.propertyName)], color: 'var(--frontend-stroke, var(--vscode-symbolIcon-propertyForeground, #22d3ee))' },
+  { tag: [t.number, t.bool, t.null, t.atom], color: 'var(--cloud-stroke, var(--vscode-debugTokenExpression-number, #fbbf24))' },
+  { tag: [t.comment, t.lineComment], color: 'var(--text-muted, var(--vscode-descriptionForeground))', fontStyle: 'italic' },
+  { tag: [t.punctuation, t.separator, t.squareBracket, t.brace], color: 'var(--text-muted, var(--vscode-descriptionForeground))' },
+  { tag: [t.keyword, t.typeName, t.labelName, t.meta], color: 'var(--database-stroke, var(--vscode-symbolIcon-keywordForeground, #a78bfa))' },
+]);
+
+export class SourceEditor {
+  readonly view: EditorView;
+  private schemaKey: string | undefined;
+
+  constructor(parent: HTMLElement, text: string, onEdit: (changes: TextChange[], text: string) => void) {
+    this.view = new EditorView({
+      parent,
+      state: EditorState.create({
+        doc: text,
+        extensions: [
+          // Undo and redo are the editor's own: VS Code sends ⌘Z in a focused
+          // webview to the webview, not to the document. Every step still
+          // reaches the document as an edit. Save and find stay VS Code's
+          // (no search panel here).
+          history(),
+          lineNumbers(),
+          highlightActiveLineGutter(),
+          highlightSpecialChars(),
+          foldGutter(),
+          drawSelection(),
+          dropCursor(),
+          EditorState.allowMultipleSelections.of(true),
+          indentOnInput(),
+          bracketMatching(),
+          closeBrackets(),
+          autocompletion(),
+          rectangularSelection(),
+          highlightActiveLine(),
+          keymap.of([...closeBracketsKeymap, ...defaultKeymap, ...historyKeymap, ...foldKeymap, ...completionKeymap, ...lintKeymap, indentWithTab]),
+          EditorState.tabSize.of(2),
+          indentUnit.of('  '),
+          yaml(),
+          theme,
+          syntaxHighlighting(highlight),
+          lintGutter(),
+          stateExtensions(undefined as never),
+          yamlLanguage.data.of({ autocomplete: yamlCompletion() }),
+          hoverTooltip(yamlSchemaHover()),
+          EditorView.updateListener.of((update) => {
+            if (!update.docChanged || update.transactions.some((tr) => tr.annotation(fromHost))) return;
+            const changes: TextChange[] = [];
+            update.changes.iterChanges((fromA, toA, _fromB, _toB, inserted) => changes.push({ from: fromA, to: toA, insert: inserted.toString() }));
+            onEdit(changes, update.state.doc.toString());
+          }),
+        ],
+      }),
+    });
+  }
+
+  get text(): string {
+    return this.view.state.doc.toString();
+  }
+
+  /** Text from the host (an edit elsewhere, git): one change, cursor kept, not undoable here. */
+  applyFromHost(change: TextChange): void {
+    this.view.dispatch({ changes: change, annotations: [fromHost.of(true), Transaction.addToHistory.of(false)] });
+  }
+
+  /** The schema that completion and hover read; `undefined` turns them off. */
+  setSchema(key: string | undefined, schema: object | undefined): void {
+    if (key === this.schemaKey) return;
+    this.schemaKey = key;
+    updateSchema(this.view, schema as never);
+  }
+
+  /** The host's problems for the text it checked; the editor maps them through later typing. */
+  setDiagnostics(items: SourceDiagnostic[]): void {
+    const length = this.view.state.doc.length;
+    const diagnostics = items
+      .filter((d) => d.from <= length)
+      .map((d) => ({ from: d.from, to: Math.min(Math.max(d.to, d.from), length), severity: d.severity, message: d.message, source: d.source }));
+    this.view.dispatch(setDiagnostics(this.view.state, diagnostics));
+  }
+
+  /** Moves the cursor to the next problem and opens its message. */
+  nextProblem(): void {
+    this.view.focus();
+    nextDiagnostic(this.view);
+  }
+
+  focus(): void {
+    this.view.focus();
+  }
+
+  requestMeasure(): void {
+    this.view.requestMeasure();
+  }
+}

src/webview/source/index.ts

@@ -0,0 +1,195 @@
+import type { ArchifyHost } from '../host';
+import { TextChange, minimalChange } from '../../util/textDiff';
+import { SourceDiagnostic, SourceEditor } from './editor';
+
+/**
+ * The Source view of an Archify page: the file's YAML in an editor, in the
+ * page under its toolbar and heading, in place of the picture. The bridge
+ * script (page.ts) loads this file the first time Source is chosen and calls
+ * window.__archifySource.open(); the document itself stays in the host, which
+ * applies every edit to it and sends back problems and outside changes.
+ */
+
+/** Host → page. */
+type HostMessage =
+  | { type: 'sourceText'; text: string; schema?: { key: string; schema: object } | null; checks: string }
+  | { type: 'sourceDiagnostics'; items: SourceDiagnostic[]; count: number }
+  | { type: 'sourceSchema'; schema: { key: string; schema: object } | null }
+  | { type: 'sourceDirty'; dirty: boolean };
+
+const STYLE = `
+html.archify-source-on .container > :not(.header):not(#archify-source),
+html.archify-source-on body > :not(.toolbar):not(.container):not(.archify-model-head):not(.archify-model-switch-row):not(#archify-source):not(script):not(style):not(.archify-modal-backdrop),
+html.archify-source-on #btn-3d,
+html.archify-source-on .archify-vscode-notice { display: none !important; }
+.archify-source { display: flex; flex-direction: column; box-sizing: border-box; min-height: 260px; margin: 0.75rem 0 1rem; }
+body > .archify-source { max-width: 1400px; margin: 0.75rem auto 1rem; padding: 0 2rem; }
+.archify-source-editor { flex: 1; min-height: 0; overflow: hidden; border: 1px solid var(--panel-border, var(--vscode-editorWidget-border, rgba(128,128,128,.35))); border-radius: 0.75rem;
+  background: color-mix(in srgb, var(--panel, var(--vscode-editor-background)) 70%, transparent); }
+.archify-source-editor .cm-editor { height: 100%; }
+.archify-source-strip { display: flex; flex-wrap: wrap; gap: 0.35rem 1rem; align-items: center; padding: 0.45rem 0.25rem 0; font-size: 0.75rem;
+  color: var(--text-muted, var(--vscode-descriptionForeground)); font-family: var(--vscode-font-family, system-ui, sans-serif); }
+.archify-source-strip .is-ok { color: var(--backend-stroke, var(--vscode-testing-iconPassed, #34d399)); }
+.archify-source-strip .is-bad { color: var(--security-stroke, var(--vscode-editorError-foreground, #fb7185)); }
+.archify-source-strip button { font: inherit; color: inherit; background: none; border: 0; padding: 0; cursor: pointer; }
+.archify-source-strip button:hover { text-decoration: underline; }
+.archify-source-strip .archify-source-hint { margin-left: auto; }
+.archify-source-strip kbd { font: inherit; font-size: 0.6875rem; padding: 0 0.3rem; border: 1px solid currentColor; border-radius: 0.25rem; opacity: 0.8; }
+`;
+
+const MAC = /Mac|iPhone|iPad/.test(navigator.platform);
+
+function isUndoRedo(event: KeyboardEvent): boolean {
+  const key = event.key.toLowerCase();
+  return (event.metaKey || event.ctrlKey) && !event.altKey && (key === 'z' || key === 'y');
+}
+
+class SourcePane {
+  private root: HTMLElement | undefined;
+  private editorHost!: HTMLElement;
+  private stateEl!: HTMLElement;
+  private countEl!: HTMLButtonElement;
+  private checksEl!: HTMLElement;
+  private editor: SourceEditor | undefined;
+  /** The text the host last knew the page to have; edits are sent against it. */
+  private text = '';
+  private diagnostics: SourceDiagnostic[] = [];
+  private shown = false;
+
+  constructor(private readonly host: ArchifyHost) {
+    window.addEventListener('message', (event) => this.onMessage(event.data as HostMessage));
+    window.addEventListener('resize', () => this.fit());
+  }
+
+  open(): void {
+    this.build();
+    this.shown = true;
+    document.documentElement.classList.add('archify-source-on');
+    window.dispatchEvent(new CustomEvent('archify-source', { detail: { on: true } }));
+    this.fit();
+    this.host.post({ type: 'sourceOpen' });
+    this.editor?.focus();
+  }
+
+  close(): void {
+    this.shown = false;
+    document.documentElement.classList.remove('archify-source-on');
+    window.dispatchEvent(new CustomEvent('archify-source', { detail: { on: false } }));
+    this.host.post({ type: 'sourceClose' });
+  }
+
+  private build(): void {
+    if (this.root) return;
+    const style = document.createElement('style');
+    style.textContent = STYLE;
+    document.head.appendChild(style);
+
+    const root = document.createElement('section');
+    root.id = 'archify-source';
+    root.className = 'archify-source';
+    root.setAttribute('aria-label', 'Source');
+    this.editorHost = document.createElement('div');
+    this.editorHost.className = 'archify-source-editor';
+    const strip = document.createElement('div');
+    strip.className = 'archify-source-strip';
+    this.stateEl = document.createElement('span');
+    this.countEl = document.createElement('button');
+    this.countEl.type = 'button';
+    this.countEl.title = 'Go to the next problem';
+    this.countEl.addEventListener('click', () => this.editor?.nextProblem());
+    this.checksEl = document.createElement('span');
+    const hint = document.createElement('span');
+    hint.className = 'archify-source-hint';
+    hint.innerHTML = 'Completion as you type, or <kbd>Ctrl</kbd>+<kbd>Space</kbd> · hover a key for its description';
+    strip.append(this.stateEl, this.countEl, this.checksEl, hint);
+    root.append(this.editorHost, strip);
+    this.renderState(false);
+    this.renderCount();
+
+    // Archify's page has single-key shortcuts; typing here must not reach
+    // them. Keys with ⌘ or Ctrl go on to VS Code (save, find, quick open),
+    // except undo and redo, which the editor has handled already.
+    for (const type of ['keydown', 'keypress', 'keyup'] as const) {
+      root.addEventListener(type, (event) => {
+        if (!event.metaKey && !event.ctrlKey) event.stopPropagation();
+        else if (isUndoRedo(event)) event.stopPropagation();
+      });
+    }
+
+    const header = document.querySelector('.container > .header');
+    const modelHead = document.querySelector('.archify-model-head');
+    if (header?.parentElement) header.parentElement.insertBefore(root, header.nextSibling);
+    else if (modelHead?.parentElement) modelHead.parentElement.insertBefore(root, modelHead.nextSibling);
+    else document.body.appendChild(root);
+    this.root = root;
+  }
+
+  /** The editor fills the window below where it starts. */
+  private fit(): void {
+    if (!this.root || !this.shown) return;
+    const top = this.root.getBoundingClientRect().top;
+    this.root.style.height = `${Math.max(260, window.innerHeight - Math.max(top, 0) - 12)}px`;
+    this.editor?.requestMeasure();
+  }
+
+  private onMessage(message: HostMessage): void {
+    if (!message || typeof message !== 'object') return;
+    switch (message.type) {
+      case 'sourceText':
+        this.build();
+        if (!this.editor) {
+          this.text = message.text;
+          this.editor = new SourceEditor(this.editorHost, message.text, (changes, text) => this.onEdit(changes, text));
+          this.editor.setDiagnostics(this.diagnostics);
+          this.fit();
+          if (this.shown) this.editor.focus();
+        } else {
+          const change = minimalChange(this.editor.text, message.text);
+          if (change) this.editor.applyFromHost(change);
+          this.text = message.text;
+        }
+        if (message.schema !== undefined) this.editor.setSchema(message.schema?.key, message.schema?.schema);
+        this.checksEl.textContent = message.checks;
+        return;
+      case 'sourceDiagnostics':
+        this.diagnostics = message.items;
+        this.editor?.setDiagnostics(message.items);
+        this.renderCount();
+        return;
+      case 'sourceSchema':
+        this.editor?.setSchema(message.schema?.key, message.schema?.schema);
+        return;
+      case 'sourceDirty':
+        this.renderState(message.dirty);
+        return;
+    }
+  }
+
+  private onEdit(changes: TextChange[], text: string): void {
+    const base = this.text;
+    this.text = text;
+    this.host.post({ type: 'sourceEdit', base, text, changes });
+  }
+
+  private renderState(dirty: boolean): void {
+    if (!this.stateEl) return;
+    this.stateEl.innerHTML = dirty ? `● Unsaved · <kbd>${MAC ? '⌘' : 'Ctrl+'}S</kbd> saves` : 'Saved';
+  }
+
+  private renderCount(): void {
+    if (!this.countEl) return;
+    const problems = this.diagnostics.filter((d) => d.severity !== 'info').length;
+    this.countEl.className = problems ? 'is-bad' : 'is-ok';
+    this.countEl.textContent = problems ? `✕ ${problems} problem${problems === 1 ? '' : 's'}` : '✓ No problems';
+    this.countEl.disabled = !problems;
+  }
+}
+
+declare global {
+  interface Window {
+    __archifySource?: { open(): void; close(): void };
+  }
+}
+
+const host = window.__archifyHost;
+if (host) window.__archifySource = new SourcePane(host);

src/webview/source/markdownStub.ts

@@ -0,0 +1,10 @@
+// Stands in for codemirror-json-schema's utils/markdown, which brings
+// markdown-it and shiki (about 400 KB) to format schema descriptions. Ours
+// only use `code` spans: escape the text and keep those. esbuild.mjs swaps
+// this file in.
+const escape = (s: string) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]!);
+
+export function renderMarkdown(markdown: string, inline = true): string {
+  const html = escape(String(markdown)).replace(/`([^`]+)`/g, '<code>$1</code>');
+  return inline ? html : `<p>${html.replace(/\n{2,}/g, '</p><p>')}</p>`;
+}

src/webview/viewer3d.ts

@@ -18,3 +18,8 @@ export function viewer3dOption(webview: vscode.Webview, extensionUri: vscode.Uri
 export function graphScriptUri(webview: vscode.Webview, extensionUri: vscode.Uri): string {
   return webview.asWebviewUri(vscode.Uri.joinPath(extensionUri, 'dist', 'graph.js')).toString();
 }
+
+/** The Source view script (a webview URI), loaded by the page the first time Source is chosen. */
+export function sourceScriptUri(webview: vscode.Webview, extensionUri: vscode.Uri): string {
+  return webview.asWebviewUri(vscode.Uri.joinPath(extensionUri, 'dist', 'source.js')).toString();
+}

test/editorSchemas.test.ts

@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { test } from 'node:test';
+import { EditorSchemas, bundleSchema } from '../src/language/editorSchemas';
+import { readSchemas } from '../src/language/schemaCheck';
+
+const schemas = readSchemas(path.resolve(__dirname, '..', '..', 'schemas'));
+
+/** Every "$ref" in a bundled schema must point inside it. */
+function resolveAll(schema: object): void {
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) return node.forEach(visit);
+    if (!node || typeof node !== 'object') return;
+    for (const [key, value] of Object.entries(node)) {
+      if (key === '$ref') {
+        assert.match(String(value), /^#/, `local ref: ${value}`);
+        let target: unknown = schema;
+        for (const part of String(value).slice(1).split('/').filter(Boolean)) {
+          target = (target as Record<string, unknown>)[part.replace(/~1/g, '/').replace(/~0/g, '~')];
+          assert.ok(target !== undefined, `${value} resolves`);
+        }
+      } else visit(value);
+    }
+  };
+  visit(schema);
+}
+
+test('each schema bundles into one self-contained document', () => {
+  for (const name of Object.keys(schemas)) {
+    const bundled = bundleSchema(schemas, name);
+    resolveAll(bundled);
+    const text = JSON.stringify(bundled);
+    assert.ok(!text.includes('"prefixItems"'), `${name}: no prefixItems`);
+    assert.ok(!text.includes('"$schema"'), `${name}: no $schema`);
+  }
+});
+
+test('points become draft-07 tuples', () => {
+  const architecture = bundleSchema(schemas, 'architecture.schema.json') as { $defs: Record<string, { $defs: Record<string, unknown> }> };
+  const point = architecture.$defs['file:common.schema.json'].$defs.point as Record<string, unknown>;
+  assert.deepEqual(point.items, [{ type: 'number' }, { type: 'number' }]);
+  assert.equal(point.additionalItems, false);
+});
+
+test('a diagram gets the schema of its diagram_type, a decision none', () => {
+  const editor = new EditorSchemas(schemas);
+  assert.equal(editor.forSource('diagram', 'schema_version: 1\ndiagram_type: sequence\n')?.key, 'sequence.schema.json');
+  assert.equal(editor.forSource('diagram', 'diagram_type: "workflow"\n')?.key, 'workflow.schema.json');
+  assert.equal(editor.forSource('diagram', 'meta:\n  title: x\n')?.key, 'archify.schema.json');
+  assert.equal(editor.forSource('diagram', 'diagram_type: poster\n')?.key, 'archify.schema.json');
+  assert.equal(editor.forSource('registry', '')?.key, 'archify-registry.schema.json');
+  assert.equal(editor.forSource('decision', ''), undefined);
+});

test/integration/suite.ts

@@ -61,9 +61,18 @@ export async function run(): Promise<void> {
     assert.equal(vscode.window.activeTextEditor?.document.uri.toString() === uri.toString(), false, 'no text editor was opened for it');
   });
 
-  await check('.archify files are YAML and Show Source opens the text beside the diagram', async () => {
+  await check('Show Source keeps the diagram in its one tab (the page switches to Source)', async () => {
     const uri = workspaceFile('web-platform.archify');
     await vscode.commands.executeCommand('archify.showSource');
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    assert.equal(vscode.window.visibleTextEditors.some((e) => e.document.uri.toString() === uri.toString()), false, 'no text editor was opened');
+    const tabs = vscode.window.tabGroups.all.flatMap((g) => g.tabs).filter((t) => t.input instanceof vscode.TabInputCustom && t.input.uri.toString() === uri.toString());
+    assert.equal(tabs.length, 1);
+  });
+
+  await check('.archify files are YAML and Open in Text Editor opens the text beside the diagram', async () => {
+    const uri = workspaceFile('web-platform.archify');
+    await vscode.commands.executeCommand('archify.openInTextEditor');
     const editor = await waitFor('source text editor', () =>
       vscode.window.visibleTextEditors.find((e) => e.document.uri.toString() === uri.toString()),
     );
@@ -333,14 +342,14 @@ export async function run(): Promise<void> {
     await new Promise((resolve) => setTimeout(resolve, 500));
   });
 
-  await check('a .archify-registry file opens as the registry view and Show Source opens the YAML', async () => {
+  await check('a .archify-registry file opens as the registry view and Open in Text Editor opens the YAML', async () => {
     const registry = workspaceFile('model/registry/people.archify-registry');
     await vscode.commands.executeCommand('vscode.open', registry);
     const tab = await waitFor('registry view tab', () =>
       vscode.window.tabGroups.all.flatMap((g) => g.tabs).find((t) => t.isActive && t.input instanceof vscode.TabInputCustom && t.input.viewType === 'archify.registry' && t.input.uri.toString() === registry.toString()),
     );
     assert.ok(tab);
-    await vscode.commands.executeCommand('archify.showSource');
+    await vscode.commands.executeCommand('archify.openInTextEditor');
     const editor = await waitFor('registry text editor', () => vscode.window.visibleTextEditors.find((e) => e.document.uri.toString() === registry.toString()));
     assert.equal(editor.document.languageId, 'yaml');
   });
@@ -459,4 +468,45 @@ export async function run(): Promise<void> {
     const errors = vscode.languages.getDiagnostics(containers.uri).filter((d) => d.severity === vscode.DiagnosticSeverity.Error);
     assert.deepEqual(errors.map((d) => d.message), []);
   });
+
+  await check('a registry is checked against its schema without a YAML extension', async () => {
+    const target = workspaceFile('model/registry/typo.archify-registry');
+    await vscode.workspace.fs.writeFile(target, new TextEncoder().encode('schema_version: 1\nelements:\n  billing:\n    typ: backend\n    label: Billing\n'));
+    const doc = await vscode.workspace.openTextDocument(target);
+    await vscode.window.showTextDocument(doc);
+    const unknown = await waitFor('unknown key diagnostic', () =>
+      vscode.languages.getDiagnostics(doc.uri).find((d) => d.source === 'archify' && /Unknown key "typ" in elements\.billing/.test(d.message)),
+    );
+    assert.equal(doc.getText(unknown.range), 'typ');
+    assert.ok(vscode.languages.getDiagnostics(doc.uri).some((d) => /"type" is required in elements\.billing/.test(d.message)));
+    await vscode.commands.executeCommand('workbench.action.closeActiveEditor');
+    await vscode.workspace.fs.delete(target);
+  });
+
+  await check('registry and decision pages own their document: edits make it dirty and VS Code undo reverts them', async () => {
+    for (const [file, viewType] of [
+      ['model/registry/containers.archify-registry', 'archify.registry'],
+      ['model/decisions/0001-postgres-as-source-of-truth.archify-decision', 'archify.decision'],
+    ] as const) {
+      const uri = workspaceFile(file);
+      await vscode.commands.executeCommand('vscode.openWith', uri, viewType);
+      await waitFor(`${viewType} tab`, () =>
+        vscode.window.tabGroups.activeTabGroup.activeTab?.input instanceof vscode.TabInputCustom &&
+        (vscode.window.tabGroups.activeTabGroup.activeTab.input as vscode.TabInputCustom).uri.toString() === uri.toString(),
+      );
+      const doc = await vscode.workspace.openTextDocument(uri);
+      const before = doc.getText();
+      // What the Source view does with a keystroke: a WorkspaceEdit on the document.
+      const edit = new vscode.WorkspaceEdit();
+      edit.insert(uri, new vscode.Position(0, 0), '# edited in Source\n');
+      assert.ok(await vscode.workspace.applyEdit(edit));
+      assert.ok(doc.isDirty, `${file} is dirty`);
+      const tab = vscode.window.tabGroups.activeTabGroup.activeTab;
+      assert.ok(tab?.isDirty, 'the page tab shows the dirty dot');
+      // ⌘Z in the page reaches VS Code as the undo command.
+      await vscode.commands.executeCommand('undo');
+      await waitFor('undo', () => doc.getText() === before);
+      await vscode.commands.executeCommand('workbench.action.revertAndCloseActiveEditor');
+    }
+  });
 }

test/model.test.ts

@@ -141,3 +141,10 @@ test('summaries and groups: root first, then folders', () => {
   assert.deepEqual(groups.map((g) => g.group), ['', '0100-context', '0300-components']);
   assert.deepEqual(groups[0].diagrams.map((d) => d.relativePath), ['broken.archify', 'checkout.archify']);
 });
+
+test('a registry YAML error is reported at its line, not the first', () => {
+  const { problems } = parseRegistry('schema_version: 1\nelements:\n  api:\n    type: backend\n    sub\n    label: API\n', 'r.archify-registry');
+  const yaml = problems.find((p) => /not valid YAML/.test(p.message));
+  assert.ok(yaml, 'a YAML problem');
+  assert.ok((yaml.line ?? 0) >= 3, `reported on line ${(yaml.line ?? 0) + 1}`);
+});

test/page.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
-import { prepareDiagramHtml } from '../src/webview/page';
+import { decisionPage, messagePage, prepareDiagramHtml, registryPage } from '../src/webview/page';
 
 const page = `<!DOCTYPE html><html><head>
 <meta http-equiv="Content-Security-Policy" content="default-src *">
@@ -61,3 +61,29 @@ test('saved view state is merged, not replaced, when the hash changes', () => {
   const html = prepareDiagramHtml(page, { cspSource: 'x', nonce: 'n', theme: 'dark', state: { uri: 'file:///a.archify' } });
   assert.match(html, /vscode\.setState\(Object\.assign\(\{\}, vscode\.getState\(\) \|\| \{\}, config\.state, \{ hash: location\.hash \}\)\)/);
 });
+
+test('a page with Source carries its script and the name of its own view', () => {
+  const html = prepareDiagramHtml(page, {
+    cspSource: 'x',
+    nonce: 'n',
+    theme: 'dark',
+    graphSwitch: { left: 'Diagram', query: 'diagram:a.archify' },
+    source: { scriptUri: 'https://file+.vscode-resource/ext/dist/source.js', left: 'Diagram' },
+  });
+  assert.match(html, /"source":\{"scriptUri":"https:\/\/file\+\.vscode-resource\/ext\/dist\/source\.js","left":"Diagram"\}/);
+  // Loaded on first use, not with the page.
+  assert.ok(!/<script[^>]+source\.js/.test(html));
+  assert.match(html, /post\(\{ type: 'sourceReady' \}\)/);
+});
+
+test('registry, decision and message pages offer View | Source when given the script', () => {
+  const source = { scriptUri: 'https://x/dist/source.js', left: 'View' as const };
+  const registry = registryPage({ cspSource: 'x', nonce: 'n', source }, { file: 'r.archify-registry', inModel: false, problems: [], elements: [] } as never);
+  const decision = decisionPage({ cspSource: 'x', nonce: 'n', source }, { file: 'd.archify-decision', inModel: false, problems: [], supersededBy: [] } as never);
+  const message = messagePage({ cspSource: 'x', nonce: 'n', source: { ...source, left: 'Diagram' } }, 'Archify could not render this diagram', 'Fix it');
+  for (const html of [registry, decision, message]) {
+    assert.match(html, /"source":\{"scriptUri":"https:\/\/x\/dist\/source\.js"/);
+    assert.match(html, /\.archify-mode-seg/, 'switch styles');
+  }
+  assert.ok(!messagePage({ cspSource: 'x', nonce: 'n' }, 'Rendering…', '').includes('"source"'), 'no Source without the option');
+});

test/schemaCheck.test.ts

@@ -0,0 +1,77 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { test } from 'node:test';
+import { DIAGRAM_SCHEMA, REGISTRY_SCHEMA, SchemaChecker, readSchemas, readablePointer } from '../src/language/schemaCheck';
+
+const root = path.resolve(__dirname, '..', '..');
+const checker = new SchemaChecker(readSchemas(path.join(root, 'schemas')));
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, out);
+    else if (/\.archify(-registry)?$/.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+const schemaFor = (file: string) => (file.endsWith('-registry') ? REGISTRY_SCHEMA : DIAGRAM_SCHEMA);
+
+test('every shipped .archify and registry file passes the schema check', () => {
+  const files = ['examples', 'templates', path.join('test', 'fixtures')].flatMap((dir) => walk(path.join(root, dir)));
+  assert.ok(files.length > 30, `found ${files.length} files`);
+  for (const file of files) {
+    const problems = checker.check(fs.readFileSync(file, 'utf8'), schemaFor(file));
+    assert.deepEqual(problems.map((p) => p.message), [], path.relative(root, file));
+  }
+});
+
+function problemsAfter(file: string, from: string, to: string) {
+  const original = fs.readFileSync(path.join(root, file), 'utf8');
+  assert.ok(original.includes(from), `${file} contains ${from}`);
+  const text = original.replace(from, to);
+  return checker.check(text, schemaFor(file)).map((p) => ({ ...p, text: text.slice(p.from, p.to) }));
+}
+
+const DIAGRAM = 'templates/models/c4-standard-web-app/0200-containers/web-app.archify';
+const REGISTRY = 'templates/models/c4-standard-web-app/registry/containers.archify-registry';
+
+test('an unknown key is placed on the key', () => {
+  const [problem, ...rest] = problemsAfter(DIAGRAM, 'label: SQL', 'lable: SQL');
+  assert.equal(rest.length, 0);
+  assert.equal(problem.text, 'lable');
+  assert.match(problem.message, /^Unknown key "lable" in connections\[\d+\]\.$/);
+});
+
+test('a point with one number is placed on the whole flow list', () => {
+  const problems = problemsAfter(DIAGRAM, 'pos: [690, 160]', 'pos: [690]');
+  assert.equal(problems.length, 1);
+  assert.equal(problems[0].text, '[690]');
+  assert.match(problems[0].message, /pos needs at least 2 items\.$/);
+});
+
+test('registry: a misspelt type key, a bad type, a bad id', () => {
+  const typo = problemsAfter(REGISTRY, '    type: database', '    typ: database');
+  assert.deepEqual(typo.map((p) => p.text).sort(), ['db', 'typ']);
+  assert.ok(typo.some((p) => p.text === 'typ' && /Unknown key "typ"/.test(p.message)));
+  assert.ok(typo.some((p) => p.text === 'db' && /"type" is required in elements\.db/.test(p.message)));
+
+  const bad = problemsAfter(REGISTRY, '    type: cloud', '    type: bucket');
+  assert.equal(bad.length, 1);
+  assert.equal(bad[0].text, 'bucket');
+  assert.match(bad[0].message, /must be one of: frontend, backend, database, cloud, security, messagebus, external\.$/);
+});
+
+test('a YAML syntax error is reported once, as YAML', () => {
+  const problems = problemsAfter(REGISTRY, 'label: API', 'label: [API');
+  assert.equal(problems.length, 1);
+  assert.equal(problems[0].kind, 'yaml');
+  assert.match(problems[0].message, /^YAML: /);
+});
+
+test('pointers read like paths', () => {
+  assert.equal(readablePointer('/connections/4/label'), 'connections[4].label');
+  assert.equal(readablePointer('/elements/db'), 'elements.db');
+  assert.equal(readablePointer(''), 'the file');
+});

test/textDiff.test.ts

@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { applyChanges, minimalChange, normalizeEol, offsetOf, positionOf } from '../src/util/textDiff';
+
+test('minimalChange keeps the common start and end', () => {
+  assert.equal(minimalChange('abc', 'abc'), undefined);
+  assert.deepEqual(minimalChange('label: SQL', 'lable: SQL'), { from: 3, to: 5, insert: 'le' });
+  assert.deepEqual(minimalChange('a\nb\n', 'a\nx\nb\n'), { from: 2, to: 2, insert: 'x\n' });
+  assert.deepEqual(minimalChange('aaa', 'aa'), { from: 2, to: 3, insert: '' });
+  assert.deepEqual(minimalChange('', 'new'), { from: 0, to: 0, insert: 'new' });
+});
+
+test('minimalChange round-trips through applyChanges', () => {
+  const pairs = [['schema_version: 1\nmeta:\n  title: A\n', 'schema_version: 1\nmeta:\n  title: B\n  output: b.html\n'], ['x', ''], ['', 'y'], ['abab', 'ab']];
+  for (const [before, after] of pairs) {
+    const change = minimalChange(before, after)!;
+    assert.equal(applyChanges(before, [change]), after);
+  }
+});
+
+test('applyChanges takes several changes in the coordinates of the original text', () => {
+  assert.equal(applyChanges('one two three', [{ from: 0, to: 3, insert: '1' }, { from: 8, to: 13, insert: '3' }]), '1 two 3');
+});
+
+test('positions and offsets in "\\n" text', () => {
+  const text = 'ab\ncde\n\nf';
+  assert.deepEqual(positionOf(text, 0), { line: 0, character: 0 });
+  assert.deepEqual(positionOf(text, 4), { line: 1, character: 1 });
+  assert.deepEqual(positionOf(text, 7), { line: 2, character: 0 });
+  assert.deepEqual(positionOf(text, 99), { line: 3, character: 1 });
+  for (let offset = 0; offset <= text.length; offset++) {
+    const { line, character } = positionOf(text, offset);
+    assert.equal(offsetOf(text, line, character), offset);
+  }
+  assert.equal(offsetOf(text, 0, 50), 2, 'clamped to the end of the line');
+  assert.equal(offsetOf(text, 9, 0), text.length);
+});
+
+test('normalizeEol', () => {
+  assert.equal(normalizeEol('a\r\nb\nc\r\n'), 'a\nb\nc\n');
+});