From 96399b6095553a512e5399e1c59b5e11ad744ee2 Mon Sep 17 00:00:00 2001
From: Sergii Demianchuk <sergeydemjanchyk@gmail.com>
Date: Mon, 5 Oct 2026 00:25:45 -0400
Subject: [PATCH 1/9] =?UTF-8?q?test(chat):=20pin=20how=20the=20chat=20rend?=
 =?UTF-8?q?ers=20code=20fences=20and=20inline=20code=20=E2=80=94=20before?=
 =?UTF-8?q?=20changing=20it?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The chat's Markdown renderer lives inline in media/chat.html, and no suite ran
it. The next commit changes how it finds a code fence, so this one writes down
what it does today, against today's code:

  an ordinary fenced block      a code block; the language line is not in it
  two blocks, prose between     and a block still being typed is shown as code
  inline code                   escaped, never formatted; a lone backtick is text
  a path in inline code         a file chip, when it names a real project file
  a fence inside a list item    still a code block, indented as it was
  a fence stuck to a line       "Run this: ```bash" opens a block, and a closing
                                fence stuck to the last line of code closes one
                                — sloppy, and already tolerated

The functions are sliced out of chat.html itself, the way shHighlight.test.js
does it, so the suite runs the shipped code and not a copy of it.
---
 .../test/chatMarkdownFences.test.js           | 124 ++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 extensions/levelcode-ai/test/chatMarkdownFences.test.js

diff --git a/extensions/levelcode-ai/test/chatMarkdownFences.test.js b/extensions/levelcode-ai/test/chatMarkdownFences.test.js
new file mode 100644
index 0000000..41169af
--- /dev/null
+++ b/extensions/levelcode-ai/test/chatMarkdownFences.test.js
@@ -0,0 +1,124 @@
+/*---------------------------------------------------------------------------------------------
+ *  The chat's Markdown renderer: code fences and inline code — run: node test/chatMarkdownFences.test.js
+ *
+ *  What it does today, pinned before the way it finds a code fence is changed: an ordinary fenced
+ *  block, two of them with prose between, a block still being typed, a fence indented inside a list
+ *  item, inline code and file chips — and the two sloppy shapes models produce that it already
+ *  tolerates (a fence stuck to the end of a line of prose; a closing fence stuck to the code).
+ *
+ *  The renderer lives inline in media/chat.html, so its functions are sliced out of the file itself
+ *  (the pattern of shHighlight.test.js): these tests run the shipped code, not a copy of it.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const html = fs.readFileSync(path.join(__dirname, '..', 'media', 'chat.html'), 'utf8');
+
+/** Slice a 2-space-indented function out of chat.html (see shHighlight.test.js for why not brace counting). */
+function extract(name) {
+	const start = html.indexOf('\n  function ' + name + '(');
+	assert.ok(start >= 0, 'chat.html no longer defines ' + name + '()');
+	const from = start + 1;
+	const oneLiner = html.slice(from, html.indexOf('\n', from));
+	if (/}\s*$/.test(oneLiner) && oneLiner.split('{').length === oneLiner.split('}').length) { return oneLiner; }
+	const end = html.indexOf('\n  }', from);
+	assert.ok(end >= 0, 'no closing brace found for ' + name + '()');
+	return html.slice(from, end + 4);
+}
+/** A top-level `const NAME = …;` line (or lines, up to the first line ending in `;`). */
+function decl(name) {
+	const m = new RegExp('\\n  const ' + name + ' = [\\s\\S]*?;\\n').exec(html);
+	assert.ok(m, 'chat.html no longer declares ' + name);
+	return m[0];
+}
+
+// A document just big enough for streamFeed(): elements that hold innerHTML and keep their children in order.
+function fakeDocument() {
+	const el = () => ({ innerHTML: '', children: [], appendChild(c) { this.children.push(c); return c; }, insertBefore(c, ref) { const i = this.children.indexOf(ref); this.children.splice(i < 0 ? this.children.length : i, 0, c); return c; } });
+	return { createElement: el };
+}
+
+const FUNCS = ['esc', 'escAttr', 'highlight', 'resolveFile', 'fileIcon', 'fileLinkChip', 'linkifyFiles', 'mdFmt', 'mdInline', 'mdListItem', 'mdBlockKind', 'mdParseList', 'mdTableBlock', 'mdBlocks', 'render', 'lastStableIndex', 'makeStream', 'stripThink', 'streamFeed'];
+// eslint-disable-next-line no-new-func
+const boot = new Function('document', [
+	'let fileIndex = null; function scrollIfStuck(){}',
+	decl('FENCE'), decl('TICK'), decl('HL_KW'), decl('HTML5_SHIELD'),
+	...FUNCS.map(extract),
+	'return { render, mdInline, mdBlocks, lastStableIndex, makeStream, streamFeed, setFiles: function(rels){ const paths = new Set(rels); const byBase = new Map(); for (const r of rels){ const b = r.split("/").pop(); if (!byBase.has(b)) byBase.set(b, []); byBase.get(b).push(r); } fileIndex = { paths: paths, byBase: byBase }; } };'
+].join('\n'));
+const doc = fakeDocument();
+const C = boot(doc);
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+const T = '`', F = '```';
+const text = (h) => h.replace(/<[^>]+>/g, '').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+const count = (h, tag) => (h.match(new RegExp('<' + tag + '[ >]', 'g')) || []).length;
+
+const DOCS = {
+	fenced: 'Here is the code:\n\n' + F + 'js\nconst a = 1;\nconsole.log(a);\n' + F + '\n\nAnd then some prose after it.\n\n- one\n- two\n',
+	twoBlocks: 'First:\n' + F + '\nplain block\n' + F + '\nbetween\n' + F + 'python\nprint("x")\n' + F + '\nlast words',
+	inList: '1. Install it:\n   ' + F + 'bash\n   npm install\n   ' + F + '\n2. Run it.\n'
+};
+
+// ---------------------------------------------------------------------------------------------------
+
+test('PIN: an ordinary fenced block is a code block, and what surrounds it is prose', () => {
+	const h = C.render(DOCS.fenced);
+	assert.strictEqual(count(h, 'pre'), 1);
+	assert.match(h, /<p>Here is the code:<\/p><pre><code>/);
+	assert.ok(text(h).includes('const a = 1;\nconsole.log(a);\n'), 'the code, line for line');
+	assert.ok(!text(h).includes('js\nconst'), 'the language tag is not part of the code');
+	assert.match(h, /<\/code><\/pre><p>And then some prose after it\.<\/p><ul><li>one<\/li><li>two<\/li><\/ul>$/);
+});
+
+test('PIN: two blocks, prose between them, and an unfinished block at the end is still shown as code', () => {
+	const h = C.render(DOCS.twoBlocks);
+	assert.strictEqual(count(h, 'pre'), 2);
+	assert.ok(text(h).includes('plain block\n') && text(h).includes('print("x")\n'));
+	assert.match(h, /<p>between<\/p>/); assert.match(h, /<p>last words<\/p>$/);
+	const open = C.render('Look:\n' + F + 'js\nconst a = 1;\nstill typing');
+	assert.strictEqual(count(open, 'pre'), 1);
+	assert.match(open, /<pre><code>[\s\S]*still typing<\/code><\/pre>$/, 'the tail of an open block is code, not prose');
+});
+
+test('PIN: inline code is escaped and never formatted; a lone backtick is just a backtick', () => {
+	assert.strictEqual(C.mdInline('use ' + T + 'a<b> **x**' + T + ' here'), 'use <code>a&lt;b&gt; **x**</code> here');
+	assert.strictEqual(C.mdInline('a ' + T + 'one' + T + ' and ' + T + 'two' + T + '.'), 'a <code>one</code> and <code>two</code>.');
+	assert.strictEqual(C.mdInline('5' + T + ' is a backtick'), '5' + T + ' is a backtick');
+	assert.strictEqual(C.mdInline('**bold** and *em*'), '<strong>bold</strong> and <em>em</em>');
+});
+
+test('PIN: a path in inline code that names a real project file becomes a file chip', () => {
+	C.setFiles(['docs/MCP.md', 'extensions/levelcode-ai/agent.js']);
+	const h = C.mdInline('see ' + T + 'docs/MCP.md' + T + ' and ' + T + 'nope.md' + T);
+	assert.match(h, /<span class="filechip" data-path="docs\/MCP\.md"/);
+	assert.match(h, /<code>nope\.md<\/code>/);
+	C.setFiles([]);
+});
+
+test('PIN: a fence inside a list item, indented, is still a code block', () => {
+	const h = C.render(DOCS.inList);
+	assert.strictEqual(count(h, 'pre'), 1);
+	assert.ok(text(h).includes('npm install'));
+	assert.ok(/Run it\./.test(text(h)));
+});
+
+test('FENCES, SLOPPY: a fence stuck to the end of a line of prose, or a closing fence stuck to the code, still works', () => {
+	const opener = C.render('Run this: ' + F + 'bash\nnpm test\n' + F + '\nDone.');
+	assert.strictEqual(count(opener, 'pre'), 1);
+	assert.match(opener, /^<p>Run this:\s*<\/p><pre><code>/);
+	assert.ok(text(opener).includes('npm test\n'));
+	assert.match(opener, /<p>Done\.<\/p>$/);
+	const closer = C.render(F + 'js\nlet a = 1;' + F + '\nAfter.');
+	assert.strictEqual(count(closer, 'pre'), 1);
+	assert.strictEqual(text(/<pre><code>([\s\S]*?)<\/code><\/pre>/.exec(closer)[1]), 'let a = 1;');
+	assert.match(closer, /<p>After\.<\/p>$/);
+});
+
+console.log('chatMarkdownFences: ' + n + ' tests passed');

From 3b05fd3c3bb8cf218f18696c0172aa25793d743d Mon Sep 17 00:00:00 2001
From: Sergii Demianchuk <sergeydemjanchyk@gmail.com>
Date: Mon, 5 Oct 2026 00:26:13 -0400
Subject: [PATCH 2/9] =?UTF-8?q?fix(chat):=20three=20backticks=20in=20a=20s?=
 =?UTF-8?q?entence=20are=20not=20a=20code=20fence=20=E2=80=94=20the=20para?=
 =?UTF-8?q?graph=20came=20out=20a=20fragment=20per=20line?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An answer that mentioned a code fence in passing — "each closed by a plain
```` ``` ````" — was rendered as two code blocks holding one backtick each, and
the rest of the paragraph arrived one streamed fragment per line: "gr",
"ounded ent", "irely in the actual code". Reported from a real session. The
model had quoted the fence correctly, in an inline span of four backticks.

Two things were wrong, and the second is what made it look so bad.

render() split the text on every run of three backticks, wherever it stood. So
```` ``` ```` was three fences: a block containing "` ", and then an unfinished
block containing the rest of the message.

lastStableIndex() decides what the streaming renderer may freeze — move out of
the live tail and into the page for good. It counted fences the same way, and
when the text after an even-numbered one had no newline yet, it answered "all
of it". From then on every delta was frozen as it arrived, each in its own
<div>.

A fence is a line. mdSegments() reads the text line by line: a block opens on a
line that is, after its indentation, three or more backticks and a language (or
anything else without a backtick in it), and closes on a line ending in a run
at least as long as the one that opened it. render() and lastStableIndex() both
use it, so they cannot disagree again. A block counts as finished only once its
closing line has its newline; text after it stays live until the next block
finishes.

Inline code takes the count seriously too: a run of N backticks opens a span
that the next run of exactly N closes, on the same line. That is how three
backticks are quoted (inside four), and one (inside two).

Kept, because models do it and the old code let them: a fence stuck to the end
of a line of prose ("Run this: ```bash") still opens a block — when nothing but
a one-word language follows it and it is not the closing half of an inline
span — and a closing fence stuck to the last line of code still closes one.

Not changed: tildes are not fences; and a line of prose that ENDS in three bare
backticks still opens a block, as it did. CommonMark would not; a model that
wants to say "```" has an inline span for it, and now it works.

chatMarkdownFences.test.js gains the report itself, whole and streamed — in
sixty different chunkings, and one character at a time; the property that
makes streaming safe (streamed and whole are the same page, and only finished
blocks are frozen) over six documents and 400 random mixes of backticks,
newlines and words; N-backtick spans; fences nested by length; language lines
that say more than a word; and that nothing in a message becomes markup. The
six pins from the last commit pass unchanged. The ten new tests fail on the old
code.

Replayed in Chromium against the shipped page with the session's exact text, in
184 deltas: the paragraph was 57 lines and two code blocks before, and is one
paragraph and none after. 21 single-edit mutations of the new code are each
caught by the suite.
---
 extensions/levelcode-ai/media/chat.html       | 109 +++++++++---
 .../test/chatMarkdownFences.test.js           | 155 +++++++++++++++++-
 2 files changed, 237 insertions(+), 27 deletions(-)

diff --git a/extensions/levelcode-ai/media/chat.html b/extensions/levelcode-ai/media/chat.html
index 4a125c1..8c59bf6 100644
--- a/extensions/levelcode-ai/media/chat.html
+++ b/extensions/levelcode-ai/media/chat.html
@@ -1841,14 +1841,35 @@
     s = s.replace(/~~([^~\n]+)~~/g, '<del>$1</del>');
     return s;
   }
+  // The runs of backticks on one line: [{ at, len }], left to right.
+  function tickRuns(line){
+    const runs = []; let i = 0;
+    while (i < line.length){
+      if (line[i] !== TICK){ i++; continue; }
+      let j = i; while (j < line.length && line[j] === TICK){ j++; }
+      runs.push({ at: i, len: j - i }); i = j;
+    }
+    return runs;
+  }
   // Split text into inline-code spans (escaped, never formatted) and formatted text — no sentinels.
+  // A run of N backticks opens a span that the next run of exactly N closes, on the same line — which
+  // is how three backticks are quoted (inside four). A run with no partner is just backticks.
   function mdInline(text){
-    const re = new RegExp(TICK + '([^' + TICK + '\\n]+)' + TICK, 'g');
-    let out = '', last = 0, m;
-    while ((m = re.exec(text))){
-      const code = m[1], rel = resolveFile(code.trim());
-      out += mdFmt(text.slice(last, m.index)) + (rel ? fileLinkChip(rel, esc(code)) : '<code>' + esc(code) + '</code>');
-      last = m.index + m[0].length;
+    let out = '', last = 0, lineAt = 0;
+    for (const line of String(text).split('\n')){
+      const runs = tickRuns(line);
+      for (let a = 0; a < runs.length; a++){
+        let b = a + 1; while (b < runs.length && runs[b].len !== runs[a].len){ b++; }
+        if (b >= runs.length){ continue; }
+        const open = lineAt + runs[a].at, from = open + runs[a].len, to = lineAt + runs[b].at;
+        let code = text.slice(from, to);
+        // Padding that exists only to keep the content's own backticks off the delimiters is not content.
+        if (runs[a].len > 1 && code.length > 2 && code[0] === ' ' && code[code.length - 1] === ' ' && code.trim()){ code = code.slice(1, -1); }
+        const rel = resolveFile(code.trim());
+        out += mdFmt(text.slice(last, open)) + (rel ? fileLinkChip(rel, esc(code)) : '<code>' + esc(code) + '</code>');
+        last = to + runs[b].len; a = b;
+      }
+      lineAt += line.length + 1;
     }
     return out + mdFmt(text.slice(last));
   }
@@ -1899,28 +1920,72 @@
     }
     return html;
   }
-  function render(md){
-    const parts = String(md == null ? '' : md).split(FENCE);
-    let out = '';
-    for (let i = 0; i < parts.length; i++){
-      if (i % 2 === 1){
-        const body = parts[i].replace(/^[a-zA-Z0-9_+-]*\n/, '');
-        out += '<pre><code>' + highlight(body) + '</code></pre>';
+  // ---- Fenced code ----
+  // A fence is a LINE: indentation, three or more backticks, a language (or anything else without a
+  // backtick in it), and the end of the line. Three backticks in the middle of a sentence are text —
+  // usually one half of an inline span quoting a fence — and reading them as a fence used to turn the
+  // rest of the paragraph into a code block and, while it streamed, freeze it one fragment per line.
+  const FENCE_LINE = new RegExp('^[ \\t]*(' + TICK + '{3,})([^' + TICK + ']*)$');
+  // Tolerated, because models do it: a fence stuck to the END of a line of prose ("Run: ```bash").
+  // Only when nothing but a one-word language follows it, and it is not closing an inline span.
+  const FENCE_TAIL = new RegExp('^[ \\t]*[A-Za-z0-9_+.#-]*[ \\t]*$');
+  // The end of a block: a run at least as long as the one that opened it, with nothing after it.
+  const FENCE_END = new RegExp('(' + TICK + '{3,})[ \\t]*$');
+  /**
+   * Text as prose and code: [{ code: false, text } | { code: true, text, closed, end }]. `end` is the
+   * offset just past a closed block's last line, set only once that line has its newline — until
+   * then more could still arrive on it, so the block is not finished.
+   */
+  function mdSegments(src){
+    const text = String(src == null ? '' : src);
+    const out = []; let proseFrom = 0, pos = 0, open = null;
+    while (pos < text.length){
+      const nl = text.indexOf('\n', pos), lineEnd = nl < 0 ? text.length : nl, next = nl < 0 ? text.length : nl + 1;
+      const line = text.slice(pos, lineEnd);
+      if (!open){
+        let at = -1, ticks = 0;
+        const whole = FENCE_LINE.exec(line);
+        if (whole){ at = pos; ticks = whole[1].length; }
+        else if (line.indexOf(FENCE) >= 0){
+          const runs = tickRuns(line), last = runs[runs.length - 1];
+          // the last run on the line, if it pairs with nothing before it (a pair is an inline span)
+          let paired = false;
+          for (let a = 0; a < runs.length - 1 && !paired; a++){
+            let b = a + 1; while (b < runs.length && runs[b].len !== runs[a].len){ b++; }
+            if (b < runs.length){ if (b === runs.length - 1){ paired = true; } a = b; }
+          }
+          if (last.len >= 3 && !paired && FENCE_TAIL.test(line.slice(last.at + last.len))){ at = pos + last.at; ticks = last.len; }
+        }
+        if (at >= 0){
+          if (at > proseFrom){ out.push({ code: false, text: text.slice(proseFrom, at) }); }
+          open = { ticks: ticks, bodyFrom: next };
+        }
       } else {
-        out += mdBlocks(parts[i]);
+        const m = FENCE_END.exec(line);
+        if (m && m[1].length >= open.ticks){
+          out.push({ code: true, text: text.slice(open.bodyFrom, pos + m.index), closed: true, end: nl < 0 ? -1 : next });
+          open = null; proseFrom = next;
+        }
       }
+      pos = next;
+    }
+    if (open){ out.push({ code: true, text: text.slice(Math.min(open.bodyFrom, text.length)), closed: false, end: -1 }); }
+    else if (proseFrom < text.length){ out.push({ code: false, text: text.slice(proseFrom) }); }
+    return out;
+  }
+  function render(md){
+    let out = '';
+    for (const seg of mdSegments(md)){
+      out += seg.code ? '<pre><code>' + highlight(seg.text) + '</code></pre>' : mdBlocks(seg.text);
     }
     return out;
   }
-  // Index just past the last fully-closed code block. Everything before it is stable forever.
+  // Index just past the last FINISHED code block. Everything before it is stable forever — and
+  // nothing else is: text after a block stays live until the next block finishes.
   function lastStableIndex(text){
-    const pos = []; let p = text.indexOf(FENCE);
-    while (p >= 0){ pos.push(p); p = text.indexOf(FENCE, p + 3); }
-    const stableFences = pos.length - (pos.length % 2);
-    if (stableFences === 0) { return 0; }
-    const end = pos[stableFences - 1] + 3;
-    const nl = text.indexOf('\n', end);
-    return nl >= 0 ? nl + 1 : text.length;
+    let stable = 0;
+    for (const seg of mdSegments(text)){ if (seg.code && seg.closed && seg.end > stable){ stable = seg.end; } }
+    return stable;
   }
   // A streaming renderer: completed code/diff blocks are FROZEN into immutable child nodes
   // (never re-rendered), so later-streamed text can never truncate or corrupt them.
diff --git a/extensions/levelcode-ai/test/chatMarkdownFences.test.js b/extensions/levelcode-ai/test/chatMarkdownFences.test.js
index 41169af..0ba1933 100644
--- a/extensions/levelcode-ai/test/chatMarkdownFences.test.js
+++ b/extensions/levelcode-ai/test/chatMarkdownFences.test.js
@@ -1,10 +1,14 @@
 /*---------------------------------------------------------------------------------------------
  *  The chat's Markdown renderer: code fences and inline code — run: node test/chatMarkdownFences.test.js
  *
- *  What it does today, pinned before the way it finds a code fence is changed: an ordinary fenced
- *  block, two of them with prose between, a block still being typed, a fence indented inside a list
- *  item, inline code and file chips — and the two sloppy shapes models produce that it already
- *  tolerates (a fence stuck to the end of a line of prose; a closing fence stuck to the code).
+ *  The bug this suite exists for: an answer that mentioned three backticks in the middle of a
+ *  sentence — the model had quoted them properly, in an inline span of four — was rendered as two
+ *  one-character code blocks, and the rest of the paragraph came out ONE STREAMED FRAGMENT PER LINE
+ *  ("gr / ounded ent / irely in the actual code"). Two causes, both pinned here:
+ *
+ *    1. Any three backticks, anywhere, were a code fence. A fence is a line; an inline span is not.
+ *    2. While streaming, text after a "closed" fence with no newline yet was frozen into the page as
+ *       it arrived, one piece per delta. Only a block that is really finished may be frozen.
  *
  *  The renderer lives inline in media/chat.html, so its functions are sliced out of the file itself
  *  (the pattern of shHighlight.test.js): these tests run the shipped code, not a copy of it.
@@ -35,6 +39,8 @@ function decl(name) {
 	assert.ok(m, 'chat.html no longer declares ' + name);
 	return m[0];
 }
+const optional = (name) => (html.indexOf('\n  function ' + name + '(') >= 0 ? extract(name) : '');
+const optionalDecl = (name) => (new RegExp('\\n  const ' + name + ' = ').test(html) ? decl(name) : '');
 
 // A document just big enough for streamFeed(): elements that hold innerHTML and keep their children in order.
 function fakeDocument() {
@@ -47,6 +53,8 @@ const FUNCS = ['esc', 'escAttr', 'highlight', 'resolveFile', 'fileIcon', 'fileLi
 const boot = new Function('document', [
 	'let fileIndex = null; function scrollIfStuck(){}',
 	decl('FENCE'), decl('TICK'), decl('HL_KW'), decl('HTML5_SHIELD'),
+	optionalDecl('FENCE_LINE'), optionalDecl('FENCE_TAIL'), optionalDecl('FENCE_END'),
+	optional('tickRuns'), optional('mdSegments'),
 	...FUNCS.map(extract),
 	'return { render, mdInline, mdBlocks, lastStableIndex, makeStream, streamFeed, setFiles: function(rels){ const paths = new Set(rels); const byBase = new Map(); for (const r of rels){ const b = r.split("/").pop(); if (!byBase.has(b)) byBase.set(b, []); byBase.get(b).push(r); } fileIndex = { paths: paths, byBase: byBase }; } };'
 ].join('\n'));
@@ -59,11 +67,31 @@ function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
 const T = '`', F = '```';
 const text = (h) => h.replace(/<[^>]+>/g, '').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
 const count = (h, tag) => (h.match(new RegExp('<' + tag + '[ >]', 'g')) || []).length;
+/** Feed `full` through the streaming renderer in the given pieces; return what the page holds at the end, and after each piece. */
+function stream(pieces) {
+	const body = doc.createElement();
+	const s = C.makeStream(body);
+	let acc = ''; const frames = [];
+	for (const p of pieces) {
+		acc += p; C.streamFeed(s, acc);
+		frames.push({ frozen: body.children.filter((c) => c !== s.live).map((c) => c.innerHTML), live: s.live.innerHTML });
+	}
+	return { html: body.children.map((c) => c.innerHTML).join(''), frames, frozen: body.children.filter((c) => c !== s.live).map((c) => c.innerHTML) };
+}
+const chunk = (s, sizes) => { const out = []; let i = 0, k = 0; while (i < s.length) { const z = sizes[k++ % sizes.length]; out.push(s.slice(i, i + z)); i += z; } return out; };
+/** Deterministic pseudo-random chunk sizes. */
+const sizesFor = (seed) => { let x = seed * 2654435761 >>> 0; const out = []; for (let i = 0; i < 40; i++) { x = (x * 1664525 + 1013904223) >>> 0; out.push(1 + (x >>> 24) % 17); } return out; };
+
+// The paragraph from the report, exactly as the model wrote it.
+const REPORTED = 'Four opening fences, matching four diagrams, each closed by a plain ' + F + T + ' ' + F + ' ' + F + T + '. The diagram is grounded entirely in the actual code: config trust tiers (' + T + 'loadServerConfig' + T + '), SHA-256 launch fingerprint (' + T + 'launchFingerprint' + T + '/' + T + 'approveMcpLaunch' + T + '), the ' + T + 'server__tool' + T + ' naming + routes (' + T + 'buildAgentTools' + T + '), and the four §4 gates.\n\nDone: Added ' + T + 'docs/MCP-DIAGRAM.md' + T + ' — four Mermaid diagrams.\n\n- **Flow diagram** traces config sources.\n- **Sequence diagram** walks one ' + T + 'tools/call' + T + '.\n';
 
 const DOCS = {
+	plain: 'A paragraph.\n\nAnother, with ' + T + 'inline code' + T + ' and **bold**.\n',
 	fenced: 'Here is the code:\n\n' + F + 'js\nconst a = 1;\nconsole.log(a);\n' + F + '\n\nAnd then some prose after it.\n\n- one\n- two\n',
 	twoBlocks: 'First:\n' + F + '\nplain block\n' + F + '\nbetween\n' + F + 'python\nprint("x")\n' + F + '\nlast words',
-	inList: '1. Install it:\n   ' + F + 'bash\n   npm install\n   ' + F + '\n2. Run it.\n'
+	inList: '1. Install it:\n   ' + F + 'bash\n   npm install\n   ' + F + '\n2. Run it.\n',
+	nested: 'A Markdown example:\n\n' + F + T + 'markdown\nUse a fence:\n' + F + 'js\nlet x;\n' + F + '\n' + F + T + '\n\nThat was four backticks around three.\n',
+	reported: REPORTED
 };
 
 // ---------------------------------------------------------------------------------------------------
@@ -109,6 +137,100 @@ test('PIN: a fence inside a list item, indented, is still a code block', () => {
 	assert.ok(/Run it\./.test(text(h)));
 });
 
+test('THE REPORT: three backticks quoted inside four are inline code — one paragraph, no code block', () => {
+	const h = C.render(REPORTED);
+	assert.strictEqual(count(h, 'pre'), 0, 'no code block: ' + h.slice(0, 300));
+	assert.match(h, /^<p>Four opening fences, matching four diagrams, each closed by a plain <code>```<\/code>\. The diagram is grounded entirely in the actual code: config trust tiers \(<code>loadServerConfig<\/code>\)/);
+	assert.strictEqual(count(h, 'p'), 2, 'the paragraph, then the Done line');
+	assert.match(h, /<p>Done: Added <code>docs\/MCP-DIAGRAM\.md<\/code> — four Mermaid diagrams\.<\/p><ul><li><strong>Flow diagram<\/strong>/);
+});
+
+test('THE REPORT, STREAMED: however it arrives, nothing is frozen mid-paragraph and the page ends up the same', () => {
+	const whole = C.render(REPORTED);
+	for (let seed = 1; seed <= 60; seed++) {
+		const r = stream(chunk(REPORTED, sizesFor(seed)));
+		assert.strictEqual(r.html, whole, 'seed ' + seed + ': streamed in pieces, it must render as it does whole');
+		assert.deepStrictEqual(r.frozen, [], 'seed ' + seed + ': there is no finished code block here, so nothing may be frozen');
+	}
+	// one character at a time — the worst case for anything that looks at "the text so far"
+	const slow = stream(REPORTED.split(''));
+	assert.strictEqual(slow.html, whole);
+	assert.ok(slow.frames.every((f) => f.frozen.length === 0), 'not at any point along the way either');
+});
+
+test('STREAMING: for every document, streamed and whole are the same page — and only finished blocks are frozen', () => {
+	for (const [name, src] of Object.entries(DOCS)) {
+		const whole = C.render(src);
+		for (let seed = 1; seed <= 40; seed++) {
+			const r = stream(chunk(src, sizesFor(seed * 7 + name.length)));
+			assert.strictEqual(r.html, whole, name + ', seed ' + seed);
+			for (const f of r.frozen) { assert.ok(/<\/code><\/pre>$/.test(f) || !/<pre>/.test(f) || /<\/pre>/.test(f), name + ': a frozen piece ends an open block: ' + f.slice(-80)); }
+			// frozen pieces are never taken back or changed once written
+			let seen = [];
+			for (const frame of r.frames) { assert.deepStrictEqual(frame.frozen.slice(0, seen.length), seen, name + ', seed ' + seed + ': a frozen piece changed'); seen = frame.frozen; }
+		}
+	}
+});
+
+test('STREAMING: a finished block is frozen as soon as its closing line is complete, and not a moment before', () => {
+	const src = 'Intro\n' + F + 'js\nlet a;\n' + F + '\nAfter the block, more words.';
+	const at = (upto) => stream([src.slice(0, upto)]);
+	const closeAt = src.indexOf(F + '\nAfter');
+	assert.deepStrictEqual(at(closeAt + 2).frozen, [], 'two of the three closing backticks: still open');
+	assert.deepStrictEqual(at(closeAt + 3).frozen, [], 'the closing fence with no newline yet: the line is not finished');
+	const done = at(closeAt + 4);
+	assert.strictEqual(done.frozen.length, 1, 'the newline ends the closing line');
+	assert.match(done.frozen[0], /^<p>Intro<\/p><pre><code>[\s\S]*<\/code><\/pre>$/);
+	// and what follows it, word by word, stays in the live tail — one paragraph, never a pile of fragments
+	const r = stream(chunk(src, [3]));
+	assert.strictEqual(r.frozen.length, 1);
+	assert.strictEqual(r.html, C.render(src));
+	assert.match(r.html, /<p>After the block, more words\.<\/p>$/);
+});
+
+test('INLINE: N backticks open a span that N backticks close — so backticks can be quoted', () => {
+	assert.strictEqual(C.mdInline('a ' + T + T + 'x ' + T + ' y' + T + T + ' b'), 'a <code>x ' + T + ' y</code> b', 'one backtick inside two');
+	assert.strictEqual(C.mdInline('the marker ' + F + T + ' ' + F + ' ' + F + T + ' opens a block'), 'the marker <code>```</code> opens a block', 'three inside four, the padding spaces dropped');
+	assert.strictEqual(C.mdInline(T + T + 'plain' + T + T), '<code>plain</code>');
+	assert.strictEqual(C.mdInline('odd ' + T + T + 'x' + T + ' ones'), 'odd ' + T + T + 'x' + T + ' ones', 'two and one do not pair: text');
+	assert.strictEqual(C.mdInline('a ' + T + 'b\nc' + T + ' d'), 'a ' + T + 'b\nc' + T + ' d', 'a span does not run across a line break');
+	assert.strictEqual(C.mdInline(T + ' spaced ' + T), '<code> spaced </code>', 'a single-backtick span keeps its text as written');
+	assert.strictEqual(C.mdInline('one ' + T + ' then two ' + T + T + ' end'), 'one ' + T + ' then two ' + T + T + ' end', 'a run is closed by one of the SAME length, not by a longer one');
+	assert.strictEqual(C.mdInline('a ' + T + T + ' b ' + F + ' c ' + T + T + ' d'), 'a <code>b ' + F + ' c</code> d', 'a longer run inside is content');
+	// a paragraph is handed over whole: spans on its later lines are found where they are
+	assert.strictEqual(C.mdInline('first line\nsecond ' + T + 'code' + T + ' here\nthird ' + T + T + 'x' + T + T + '.'), 'first line\nsecond <code>code</code> here\nthird <code>x</code>.');
+	assert.strictEqual(C.mdBlocks('one ' + T + 'a' + T + '\ntwo ' + T + 'b' + T), '<p>one <code>a</code><br>two <code>b</code></p>');
+});
+
+test('FENCES: a fence is a line — backticks in the middle of a sentence never start a block', () => {
+	for (const prose of [
+		'Wrap it in ' + F + T + ' ' + F + ' ' + F + T + ' to quote a fence.',
+		'The ' + F + ' marker, then text, then ' + F + ' again on one line.',
+		'Three ticks ' + F + ' then words and nothing else on the line',
+		'It ends with a quoted fence: ' + F + T + ' ' + F + ' ' + F + T
+	]) {
+		const h = C.render(prose + '\n\nNext paragraph.');
+		assert.strictEqual(count(h, 'pre'), 0, 'no code block for: ' + prose);
+		assert.match(h, /<p>Next paragraph\.<\/p>$/, 'and the next paragraph is still a paragraph: ' + prose);
+	}
+});
+
+test('FENCES: a longer fence holds shorter ones — a Markdown example inside four backticks is one block', () => {
+	const h = C.render(DOCS.nested);
+	assert.strictEqual(count(h, 'pre'), 1);
+	assert.ok(text(h).includes('Use a fence:\n' + F + 'js\nlet x;\n' + F + '\n'), 'the inner fence is shown as code, backticks and all');
+	assert.match(h, /<p>That was four backticks around three\.<\/p>$/);
+});
+
+test('FENCES: the language line may say more than a word, and is never shown as code', () => {
+	for (const info of ['js', 'diff', 'c++', 'objective-c', 'js title="app.js"', '{r, echo=FALSE}', 'python {1,3}']) {
+		const h = C.render('Before\n' + F + info + '\nBODY\n' + F + '\nAfter');
+		assert.strictEqual(count(h, 'pre'), 1, info);
+		assert.strictEqual(text(/<pre><code>([\s\S]*?)<\/code><\/pre>/.exec(h)[1]), 'BODY\n', 'info "' + info + '" is not in the block');
+		assert.match(h, /<p>After<\/p>$/);
+	}
+});
+
 test('FENCES, SLOPPY: a fence stuck to the end of a line of prose, or a closing fence stuck to the code, still works', () => {
 	const opener = C.render('Run this: ' + F + 'bash\nnpm test\n' + F + '\nDone.');
 	assert.strictEqual(count(opener, 'pre'), 1);
@@ -121,4 +243,27 @@ test('FENCES, SLOPPY: a fence stuck to the end of a line of prose, or a closing
 	assert.match(closer, /<p>After\.<\/p>$/);
 });
 
+test('SAFE: nothing in a message becomes markup — in prose, in inline code, or in a block', () => {
+	const evil = '<img src=x onerror=alert(1)> ' + T + '<script>alert(2)</script>' + T + ' ' + F + T + ' <b>x</b> ' + F + T + '\n' + F + 'html\n<script>alert(3)</script>\n' + F + '\n';
+	const h = C.render(evil);
+	assert.ok(!/<img|<script|<b>/.test(h), h);
+	assert.ok(h.includes('&lt;img src=x onerror=alert(1)&gt;') && h.includes('<code>&lt;script&gt;alert(2)&lt;/script&gt;</code>') && h.includes('<code>&lt;b&gt;x&lt;/b&gt;</code>'));
+	assert.strictEqual(stream(evil.split('')).html, h);
+});
+
+test('ROBUST: any mix of backticks, newlines and words renders without throwing, streamed or whole, to the same page', () => {
+	const bits = [T, T + T, F, F + T, '\n', '\n\n', ' ', 'word', 'js', '- item', '**b**', '   ', 'x' + T + 'y', F + 'py\n', '\n' + F + '\n'];
+	let x = 12345;
+	const rnd = (k) => { x = (x * 1103515245 + 12345) >>> 0; return (x >>> 16) % k; };
+	for (let i = 0; i < 400; i++) {
+		let src = ''; const len = 3 + rnd(14);
+		for (let j = 0; j < len; j++) { src += bits[rnd(bits.length)]; }
+		const whole = C.render(src);
+		assert.strictEqual(typeof whole, 'string');
+		const r = stream(chunk(src, sizesFor(i + 1)));
+		assert.strictEqual(r.html, whole, 'case ' + i + ': ' + JSON.stringify(src));
+		assert.ok(C.lastStableIndex(src) <= src.length);
+	}
+});
+
 console.log('chatMarkdownFences: ' + n + ' tests passed');

From 42159e59a14af301e484dc21f37e1713db367f5e Mon Sep 17 00:00:00 2001
From: Sergii Demianchuk <sergeydemjanchyk@gmail.com>
Date: Mon, 5 Oct 2026 00:26:40 -0400
Subject: [PATCH 3/9] =?UTF-8?q?feat(diagrams):=20the=20spec=20=E2=80=94=20?=
 =?UTF-8?q?a=20schema,=20a=20validator=20that=20reports=20every=20error=20?=
 =?UTF-8?q?at=20once,=20and=20the=20repair=20ladder?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First slice of rich diagrams; docs/RICH-DIAGRAMS.md arrives with the last one.
The agent draws flows and architectures out of box-drawing characters. The plan
is that it describes STRUCTURE instead — nodes, edges, groups, one accent,
never a coordinate or a colour — and the editor draws. This commit is the part
that decides whether a description may be drawn. Nothing calls it yet.

  diagram/schema.js     the versioned schema, and a small interpreter for the
                        subset of JSON Schema it uses. One object is both the
                        tool's input schema and what a spec is checked against.
                        Two tiers of limits: HOUSE is what a model is held to
                        (12 nodes; labels 28, second lines 32, edge labels 20,
                        title 80; groups two deep), HARD is what the renderer
                        will still draw (24 nodes, 48 edges).
  diagram/validate.js   schema, then semantics: edge ends exist, ids are unique,
                        one accent, groups known, acyclic, at most two deep.
                        EVERY error, each with a JSON Pointer, what was
                        expected and the valid options:
                          /edges/1/to: unknown node "billing". Known ids: in, jev, bill, rev.
  diagram/repair.js     the ladder. prepare() takes one call up it.

The ladder departs from the spec in one place, on purpose. The spec lists
"dedupe ids" and "drop edges to unknown nodes" among the fixes made without a
model, while its own table says semantic errors go to the model, "because
intent is needed". Both cannot hold: an edge to "billing" when the node is
"bill" is a typo the model fixes in one pass, and dropping it silently changes
what the diagram says. So:

  1  auto-fix, lossless only   lenient JSON (comments, trailing commas, smart
                               quotes, bare keys), synonyms ("diamond" for
                               decision, source/target for from/to), slugged
                               ids, an edge that names a node by its label,
                               long labels shortened with the full text kept
  2  every error, once         returned for the model's one repair pass
  3  degrade                   only now the lossy fixes: edges to nowhere
                               dropped, duplicates renamed, one accent kept,
                               counts up to the HARD tier — each loss named

An auto-fixed diagram never says something different from what the model
wrote; a degraded one always says what it lost.

accept() is the same gate for a spec that is read back rather than received —
from a session file, say: validate, hand on only the fields the schema
declares, and fall back to the rungs that need no model.

No Ajv: it is a dependency, and this extension has neither dependencies nor a
build step.

test/fixtures/diagrams/corpus.json holds 39 broken specs with the exact outcome
of each attempt. They are seeded from the ways models are known to get this
wrong, not collected in the field; real ones should be added as they turn up.

diagramSchema (18 tests) and diagramRepair (65).
---
 extensions/levelcode-ai/diagram/repair.js     |  691 +++++++
 extensions/levelcode-ai/diagram/schema.js     |  253 +++
 extensions/levelcode-ai/diagram/validate.js   |  177 ++
 .../levelcode-ai/test/diagramRepair.test.js   |  361 ++++
 .../levelcode-ai/test/diagramSchema.test.js   |  207 ++
 .../test/fixtures/diagrams/corpus.json        | 1811 +++++++++++++++++
 6 files changed, 3500 insertions(+)
 create mode 100644 extensions/levelcode-ai/diagram/repair.js
 create mode 100644 extensions/levelcode-ai/diagram/schema.js
 create mode 100644 extensions/levelcode-ai/diagram/validate.js
 create mode 100644 extensions/levelcode-ai/test/diagramRepair.test.js
 create mode 100644 extensions/levelcode-ai/test/diagramSchema.test.js
 create mode 100644 extensions/levelcode-ai/test/fixtures/diagrams/corpus.json

diff --git a/extensions/levelcode-ai/diagram/repair.js b/extensions/levelcode-ai/diagram/repair.js
new file mode 100644
index 0000000..d1da189
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/repair.js
@@ -0,0 +1,691 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · the repair ladder  (docs/RICH-DIAGRAMS.md, "Validation and repair")
+ *
+ *  Most broken specs are broken MECHANICALLY — a trailing comma, `"shape": "diamond"`, an edge that
+ *  names a node by its label — so most should never cost a model call. The ladder reaches for a
+ *  model only when deterministic fixes run out, and it never loops:
+ *
+ *    rung 1  normalize()  deterministic, no model. Tidies everything that has ONE obvious reading:
+ *                         lenient JSON, synonyms ("diamond" → decision), an edge that names a node by
+ *                         its label, a label over the limit (shortened; the full text survives as a
+ *                         tooltip and in the screen-reader outline).
+ *    rung 2  (the caller) ONE model pass: whatever needs intent — an edge to a node that does not
+ *                         exist, two accents, 17 nodes, groups three deep — goes back as an error list.
+ *    rung 3  normalize({lossy}) + degrade()   still broken after that pass: drop the edges that point
+ *                         nowhere, rename the colliding ids, keep one accent, flatten the nesting —
+ *                         and draw what is left under a banner that says what was lost. Or give up
+ *                         honestly (`failed`) so the UI can show the source and a Retry.
+ *
+ *  THE RULE THAT ORDERS THE RUNGS: an "auto-fixed" diagram never says something different from what
+ *  the model wrote, and a "degraded" one always says what it lost. So a fix that changes MEANING
+ *  (a dropped edge, a renamed duplicate) is never applied before the model has had its one chance
+ *  to do it properly — while a fix that only changes PRESENTATION never costs a model call.
+ *
+ *  prepare() runs the ladder for one call and says which rung it ended on. It is pure: the caller
+ *  decides what "the repair pass was already spent" means (`final`) and what to do with the answer.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+(function (root, factory) {
+	'use strict';
+	if (typeof module === 'object' && module.exports) { module.exports = factory(require('./schema'), require('./validate')); }
+	else { (root.LCDiagram = root.LCDiagram || {}).repair = factory(root.LCDiagram.schema, root.LCDiagram.validate); }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function (schema, validator) {
+	'use strict';
+
+	const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+	const q = (s) => JSON.stringify(String(s));
+	const HOUSE = schema.HOUSE, HARD = schema.HARD;
+
+	// ---- text hygiene ---------------------------------------------------------------------------
+	// Control characters and bidirectional overrides have no business in a label: the first break
+	// layout, the second can make a node READ as something other than what it says.
+	// eslint-disable-next-line no-control-regex
+	const UNSAFE_CHARS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f​-‏‪-‮⁠-⁩]/g;
+	/** One clean line: unsafe characters gone, runs of whitespace collapsed. */
+	function cleanText(s) { return String(s == null ? '' : s).replace(UNSAFE_CHARS, '').replace(/\s+/g, ' ').trim(); }
+	const count = (s) => Array.from(s).length;
+
+	/**
+	 * Cut `text` to `max` characters, ending in an ellipsis. Prefers a word boundary when one is
+	 * close, so "Validate the incoming request" shortens to "Validate the incoming…", not "…incoming reque…".
+	 */
+	function truncate(text, max) {
+		const chars = Array.from(String(text));
+		if (chars.length <= max) { return String(text); }
+		let cut = chars.slice(0, Math.max(1, max - 1)).join('');
+		const sp = cut.lastIndexOf(' ');
+		if (sp >= Math.floor(max * 0.6)) { cut = cut.slice(0, sp); }
+		return cut.replace(/[\s,;:.\-–—(]+$/, '') + '…';
+	}
+
+	/** A model-supplied name → a lowercase slug. '' when nothing sluggable is left (the caller invents one). */
+	function slugify(s) {
+		let t = String(s == null ? '' : s);
+		try { t = t.normalize('NFKD'); } catch (e) { /* no ICU — fine, non-ASCII just becomes '-' */ }
+		t = t.replace(/[̀-ͯ]/g, '').toLowerCase().trim()
+			.replace(/[^a-z0-9_-]+/g, '-').replace(/-{2,}/g, '-').replace(/^[-_]+|[-_]+$/g, '');
+		return t.slice(0, HOUSE.id).replace(/[-_]+$/, '');
+	}
+
+	// ---- lenient JSON ---------------------------------------------------------------------------
+	const QUOTES = { '"': '"', "'": "'", '“': '”', '”': '”' };
+
+	/**
+	 * Parse JSON the way models actually write it: comments, trailing commas, single or "smart"
+	 * quotes, bare keys, Python's True/False/None, a ```json fence around the lot.
+	 *
+	 * What it will NOT do is finish a spec that stops mid-structure. Truncated output means the
+	 * model hit its token cap, and guessing at the rest would draw a diagram nobody wrote — so that
+	 * comes back as `truncated`, and the caller re-requests instead of repairing.
+	 * @param {string} text
+	 * @returns {{ ok: boolean, value?: any, lenient?: boolean, truncated?: boolean, error?: string }}
+	 */
+	function parseLenient(text) {
+		let src = String(text == null ? '' : text).replace(/^/, '').trim();
+		try { return { ok: true, value: JSON.parse(src), lenient: false }; } catch (e) { /* fall through to the tolerant path */ }
+		const fence = /^```[a-zA-Z0-9_-]*\s*\n([\s\S]*?)\n?```\s*$/.exec(src);
+		if (fence) { src = fence[1].trim(); }
+		const start = src.search(/[{[]/);
+		if (start < 0) { return { ok: false, error: 'no JSON object found' }; }
+		src = src.slice(start);
+
+		let out = '', i = 0, depth = 0;
+		const n = src.length;
+		const skipSpaceAndComments = (j) => {
+			for (;;) {
+				while (j < n && /\s/.test(src[j])) { j++; }
+				if (src[j] === '/' && src[j + 1] === '/') { const e = src.indexOf('\n', j); j = e < 0 ? n : e; continue; }
+				if (src[j] === '/' && src[j + 1] === '*') { const e = src.indexOf('*/', j + 2); j = e < 0 ? n : e + 2; continue; }
+				return j;
+			}
+		};
+		while (i < n) {
+			const c = src[i];
+			if (QUOTES[c]) {
+				const close = QUOTES[c], smart = c !== '"' && c !== "'";
+				let j = i + 1, buf = '', closed = false;
+				while (j < n) {
+					const d = src[j];
+					if (d === '\\') {
+						if (j + 1 >= n) { break; }
+						buf += (c === "'" && src[j + 1] === "'") ? "'" : d + src[j + 1];
+						j += 2; continue;
+					}
+					if (d === close || (smart && d === '“')) { closed = true; j++; break; }
+					if (d === '"') { buf += '\\"'; j++; continue; }             // a bare " inside '…' or “…”
+					if (d === '\n') { buf += '\\n'; j++; continue; }
+					if (d === '\r') { j++; continue; }
+					if (d === '\t') { buf += '\\t'; j++; continue; }
+					buf += d; j++;
+				}
+				if (!closed) { return { ok: false, truncated: true, error: 'unterminated string' }; }
+				out += '"' + buf + '"'; i = j; continue;
+			}
+			if (c === '/' && (src[i + 1] === '/' || src[i + 1] === '*')) {
+				const j = skipSpaceAndComments(i);
+				if (j >= n && src[i + 1] === '*' && src.indexOf('*/', i + 2) < 0) { return { ok: false, truncated: true, error: 'unterminated comment' }; }
+				i = j; continue;
+			}
+			if (c === ',') {
+				const j = skipSpaceAndComments(i + 1);
+				if (src[j] === '}' || src[j] === ']') { i++; continue; }      // trailing comma
+			}
+			if (/[A-Za-z_$]/.test(c)) {
+				let j = i; while (j < n && /[\w$]/.test(src[j])) { j++; }
+				const word = src.slice(i, j);
+				const k = skipSpaceAndComments(j);
+				if (src[k] === ':') { out += '"' + word + '"'; }               // bare key
+				else if (word === 'True') { out += 'true'; }
+				else if (word === 'False') { out += 'false'; }
+				else if (word === 'None' || word === 'undefined') { out += 'null'; }
+				else { out += word; }
+				i = j; continue;
+			}
+			if (c === '{' || c === '[') { depth++; }
+			else if (c === '}' || c === ']') {
+				depth--;
+				if (depth === 0) { out += c; break; }                          // ignore prose after the object
+			}
+			out += c; i++;
+		}
+		if (depth > 0) { return { ok: false, truncated: true, error: 'the JSON stops before it is complete' }; }
+		try { return { ok: true, value: JSON.parse(out), lenient: true }; }
+		catch (e) { return { ok: false, error: String((e && e.message) || e) }; }
+	}
+
+	// ---- rung 1: normalize ----------------------------------------------------------------------
+	const DIRECTION_SYNONYMS = {
+		right: 'right', lr: 'right', 'left-to-right': 'right', 'left-right': 'right', ltr: 'right', horizontal: 'right', east: 'right', row: 'right',
+		rl: 'right', 'right-to-left': 'right', left: 'right',
+		down: 'down', tb: 'down', td: 'down', 'top-to-bottom': 'down', 'top-down': 'down', 'top-bottom': 'down', vertical: 'down', south: 'down', column: 'down',
+		bt: 'down', 'bottom-to-top': 'down', up: 'down'
+	};
+	const SHAPE_SYNONYMS = {
+		box: 'box', rect: 'box', rectangle: 'box', square: 'box', process: 'box', step: 'box', node: 'box', default: 'box', task: 'box', service: 'box', component: 'box',
+		decision: 'decision', diamond: 'decision', rhombus: 'decision', condition: 'decision', choice: 'decision', branch: 'decision', 'if': 'decision', gateway: 'decision',
+		store: 'store', database: 'store', db: 'store', cylinder: 'store', storage: 'store', datastore: 'store', 'data-store': 'store', table: 'store', cache: 'store', queue: 'store', bucket: 'store',
+		actor: 'actor', person: 'actor', user: 'actor', human: 'actor', external: 'actor', pill: 'actor', stadium: 'actor', terminal: 'actor', terminator: 'actor', round: 'actor', rounded: 'actor', start: 'actor', end: 'actor', client: 'actor'
+	};
+	const STYLE_SYNONYMS = {
+		solid: 'solid', line: 'solid', normal: 'solid', plain: 'solid', thick: 'solid', bold: 'solid',
+		dashed: 'dashed', dash: 'dashed', dashes: 'dashed', dotted: 'dashed', dots: 'dashed', dot: 'dashed', broken: 'dashed', optional: 'dashed', async: 'dashed'
+	};
+	const WRAPPERS = ['spec', 'diagram', 'graph', 'input', 'json', 'arguments', 'data'];
+	const key = (s) => String(s == null ? '' : s).toLowerCase().trim().replace(/[\s_]+/g, '-');
+	const pick = (obj, names) => { for (const n of names) { if (obj[n] !== undefined && obj[n] !== null) { return obj[n]; } } return undefined; };
+	const asBool = (v) => (v === true || v === 1 || (typeof v === 'string' && /^(true|yes|1)$/i.test(v.trim())));
+	const scalar = (v) => (typeof v === 'string' || typeof v === 'number') ? String(v) : undefined;
+
+	/**
+	 * Rung 1. Turn whatever the model sent into a clean spec in canonical form, recording each thing
+	 * it changed.
+	 *
+	 * Three kinds of fix come out of here, and the difference is what the user is told:
+	 *   (plain)  a tidy-up with one obvious reading — `"shape": "diamond"`, a trailing comma, an id
+	 *            with a space in it. The drawing is what the model meant; nobody needs a badge.
+	 *   `show`   the drawing differs from what was written, but says the same thing: a label over
+	 *            the limit was shortened, a shape nobody knows became a box. "auto-fixed" badge.
+	 *   `lossy`  it changed what the diagram SAYS — an edge dropped, a duplicate id renamed. Only
+	 *            ever applied when `opts.lossy` is set, which the ladder does on its last rung.
+	 *
+	 * Never throws. A value it cannot make sense of is passed through for validate() to name.
+	 * @param {any} input
+	 * @param {{ lossy?: boolean }} [opts]
+	 * @returns {{ spec: any, fixes: Array<{pointer:string, cls:string, message:string, show?:boolean, lossy?:boolean, shortened?:boolean}>, truncated?: boolean, syntax?: string }}
+	 */
+	function normalize(input, opts) {
+		const allowLossy = !!(opts && opts.lossy);
+		/** @type {Array<{pointer:string, cls:string, message:string, show?:boolean, lossy?:boolean, shortened?:boolean}>} */
+		const fixes = [];
+		const fix = (pointer, cls, message, flags) => { fixes.push(Object.assign({ pointer, cls, message }, flags || {})); };
+
+		// -- syntax: text → object, and unwrap a spec that arrived inside an envelope
+		let raw = input;
+		for (let hop = 0; hop < 3; hop++) {
+			if (typeof raw === 'string') {
+				const p = parseLenient(raw);
+				if (!p.ok) { return p.truncated ? { spec: null, fixes, truncated: true } : { spec: null, fixes, syntax: p.error || 'not valid JSON' }; }
+				fix('', p.lenient ? 'lenient-json' : 'stringified', p.lenient ? 'JSON repaired (comments, quotes or trailing commas).' : 'spec arrived as a JSON string; parsed it.');
+				raw = p.value; continue;
+			}
+			if (isObj(raw) && raw.nodes === undefined) {
+				const w = WRAPPERS.find((k) => raw[k] !== undefined && (isObj(raw[k]) || typeof raw[k] === 'string'));
+				if (w) { fix('', 'unwrapped', 'spec was nested under "' + w + '"; unwrapped it.'); raw = raw[w]; continue; }
+			}
+			break;
+		}
+		if (!isObj(raw)) { return { spec: raw, fixes }; }
+		// A structural copy: plain data only, and nothing shared with the caller's object.
+		try { raw = JSON.parse(JSON.stringify(raw)); } catch (e) { return { spec: null, fixes, syntax: 'spec is not plain JSON data' }; }
+
+		const spec = {};
+		let dropped = 0;   // unknown fields, counted not listed
+		// `tip` is the renderer's own field (the full text of a label that was shortened). A spec that
+		// has been through here before carries them, and going through again must not lose them.
+		const keepTip = (from, to) => { if (typeof from.tip === 'string' && cleanText(from.tip)) { to.tip = truncate(cleanText(from.tip), HARD.tip); } };
+		keepTip(raw, spec);
+
+		// -- v
+		if (raw.v === undefined || raw.v === null) { spec.v = schema.VERSION; }
+		else if (typeof raw.v === 'string' && /^\d+$/.test(raw.v.trim())) { spec.v = Number(raw.v); fix('/v', 'coerced', 'version given as a string; read it as a number.'); }
+		else { spec.v = raw.v; }
+
+		// -- title
+		const title = scalar(pick(raw, ['title', 'name', 'caption', 'heading']));
+		if (title !== undefined) { spec.title = cleanText(title); }
+		if (raw.title === undefined && title !== undefined) { fix('/title', 'renamed-field', 'used the "name"/"caption" field as the title.'); }
+
+		// -- direction
+		const dirRaw = pick(raw, ['direction', 'dir', 'rankdir', 'orientation', 'flow']);
+		if (dirRaw === undefined) { spec.direction = 'right'; }
+		else {
+			const d = DIRECTION_SYNONYMS[key(dirRaw)];
+			if (d) { spec.direction = d; if (d !== dirRaw) { fix('/direction', 'synonym', JSON.stringify(dirRaw) + ' read as "' + d + '".'); } }
+			else { spec.direction = 'right'; fix('/direction', 'enum', JSON.stringify(dirRaw) + ' is not a direction; used "right".', { show: true }); }
+		}
+
+		// -- groups first: nodes refer to them
+		const groupIdOf = new Map();   // what the model wrote → the slug we settled on
+		let groupsIn = raw.groups;
+		if (isObj(groupsIn)) {
+			groupsIn = Object.keys(groupsIn).map((k) => (isObj(groupsIn[k]) ? Object.assign({ id: k }, groupsIn[k]) : { id: k, label: scalar(groupsIn[k]) }));
+			fix('/groups', 'coerced', 'groups given as an object; read as a list.');
+		}
+		let groups;
+		if (Array.isArray(groupsIn)) {
+			groups = [];
+			groupsIn.forEach((g, i) => {
+				if (typeof g === 'string') { g = { id: g, label: g }; }
+				if (!isObj(g)) { groups.push(g); return; }
+				const out = {};
+				const rawId = scalar(pick(g, ['id', 'key', 'name']));
+				const label = scalar(pick(g, ['label', 'title', 'name', 'text']));
+				let id = rawId !== undefined ? slugify(rawId) : '';
+				if (!id) { id = slugify(label || '') || ('g' + (i + 1)); }
+				if (rawId !== undefined) { groupIdOf.set(rawId, id); groupIdOf.set(key(rawId), id); }
+				if (rawId !== id && rawId !== undefined) { fix('/groups/' + i + '/id', 'slug', q(rawId) + ' written as the slug "' + id + '".'); }
+				out.id = id;
+				out.label = label !== undefined && cleanText(label) ? cleanText(label) : (rawId !== undefined ? cleanText(rawId) : id);
+				if (label === undefined) { fix('/groups/' + i + '/label', 'defaulted', 'group had no label; used its id.'); }
+				const parent = scalar(pick(g, ['parent', 'in', 'group']));
+				if (parent !== undefined && cleanText(parent)) { out.parent = parent; }
+				keepTip(g, out);
+				dropped += Object.keys(g).filter((k) => ['id', 'key', 'name', 'label', 'title', 'text', 'parent', 'in', 'group', 'tip'].indexOf(k) < 0).length;
+				groups.push(out);
+			});
+			const gid = (ref) => (groupIdOf.has(ref) ? groupIdOf.get(ref) : groupIdOf.has(key(ref)) ? groupIdOf.get(key(ref)) : (slugify(ref) || String(ref)));
+			for (const g of groups) { if (isObj(g) && g.parent !== undefined) { g.parent = gid(g.parent); } }
+		} else if (groupsIn !== undefined && groupsIn !== null) { groups = groupsIn; }
+		const groupRef = (ref) => (groupIdOf.has(ref) ? groupIdOf.get(ref) : groupIdOf.has(key(ref)) ? groupIdOf.get(key(ref)) : (slugify(ref) || String(ref)));
+
+		// -- nodes
+		const idOf = new Map();        // what the model wrote → the slug we settled on
+		const idByLabel = new Map();   // lowercased label → id (null when two nodes share a label)
+		let nodesIn = raw.nodes;
+		if (isObj(nodesIn)) {
+			nodesIn = Object.keys(nodesIn).map((k) => (isObj(nodesIn[k]) ? Object.assign({ id: k }, nodesIn[k]) : { id: k, label: scalar(nodesIn[k]) }));
+			fix('/nodes', 'coerced', 'nodes given as an object; read as a list.');
+		}
+		let nodes;
+		if (Array.isArray(nodesIn)) {
+			nodes = [];
+			nodesIn.forEach((n, i) => {
+				const at = '/nodes/' + i;
+				if (typeof n === 'string' || typeof n === 'number') { n = { id: String(n), label: String(n) }; fix(at, 'coerced', 'node given as a bare name; used it as both id and label.'); }
+				if (!isObj(n)) { nodes.push(n); return; }
+				const out = {};
+				const rawId = scalar(pick(n, ['id', 'key']));
+				let labelRaw = scalar(pick(n, ['label', 'name', 'title', 'text']));
+				let subRaw = scalar(pick(n, ['sub', 'subtitle', 'sublabel', 'description', 'desc', 'detail', 'note']));
+				if (n.label === undefined && labelRaw !== undefined) { fix(at + '/label', 'renamed-field', 'used the "name"/"title" field as the label.'); }
+				if (n.sub === undefined && subRaw !== undefined) { fix(at + '/sub', 'renamed-field', 'used the "description"/"subtitle" field as the second line.'); }
+				// "Jev\nreturns probabilities" is a label and a sub written in one field.
+				if (labelRaw !== undefined && subRaw === undefined && /\r?\n|<br\s*\/?>/i.test(labelRaw)) {
+					const parts = labelRaw.split(/\r?\n|<br\s*\/?>/i).map(cleanText).filter(Boolean);
+					if (parts.length > 1) { labelRaw = parts[0]; subRaw = parts.slice(1).join(' '); fix(at + '/label', 'split-label', 'two-line label split into label and sub.'); }
+				}
+				const label = labelRaw !== undefined ? cleanText(labelRaw) : undefined;
+				let id = rawId !== undefined ? slugify(rawId) : '';
+				if (!id) { id = slugify(label || '') || ('n' + (i + 1)); if (rawId === undefined) { fix(at + '/id', 'defaulted', 'node had no id; made "' + id + '" from its label.'); } }
+				if (rawId !== undefined && rawId !== id) { fix(at + '/id', 'slug', q(rawId) + ' written as the slug "' + id + '".'); }
+				if (rawId !== undefined) { if (!idOf.has(rawId)) { idOf.set(rawId, id); } if (!idOf.has(key(rawId))) { idOf.set(key(rawId), id); } }
+				out.id = id;
+				if (label !== undefined && label) { out.label = label; }
+				else if (rawId !== undefined && cleanText(rawId)) { out.label = cleanText(rawId); fix(at + '/label', 'defaulted', 'node had no label; used its id.'); }
+				if (out.label) { const lk = out.label.toLowerCase(); idByLabel.set(lk, idByLabel.has(lk) ? null : id); }
+				const sub = subRaw !== undefined ? cleanText(subRaw) : '';
+				if (sub) { out.sub = sub; }
+				const shapeRaw = pick(n, ['shape', 'type', 'kind']);
+				if (shapeRaw !== undefined) {
+					const s = SHAPE_SYNONYMS[key(shapeRaw)];
+					if (s) { if (s !== 'box') { out.shape = s; } if (s !== shapeRaw) { fix(at + '/shape', 'synonym', JSON.stringify(shapeRaw) + ' read as "' + s + '".'); } }
+					else { fix(at + '/shape', 'enum', JSON.stringify(shapeRaw) + ' is not a shape; drew a box.', { show: true }); }
+				}
+				const accentRaw = pick(n, ['accent', 'highlight', 'primary', 'emphasis']);
+				if (accentRaw !== undefined) {
+					if (asBool(accentRaw)) { out.accent = true; }
+					if (typeof accentRaw !== 'boolean') { fix(at + '/accent', 'coerced', 'accent read as ' + asBool(accentRaw) + '.'); }
+				}
+				const groupRaw = scalar(pick(n, ['group', 'parent', 'cluster', 'in']));
+				if (groupRaw !== undefined && cleanText(groupRaw)) { out.group = groupRef(groupRaw); }
+				const link = normalizeLink(pick(n, ['link', 'file', 'href', 'path']));
+				if (link) { out.link = link; }
+				keepTip(n, out);
+				dropped += Object.keys(n).filter((k) => NODE_KEYS.indexOf(k) < 0).length;
+				nodes.push(out);
+			});
+		} else if (nodesIn !== undefined) { nodes = nodesIn; }
+
+		// -- duplicate ids. The same node listed twice is one node. Two DIFFERENT nodes under one id
+		//    is a question only the model can answer (which one do the edges mean?), so that is
+		//    left for validate() to report — and settled by renaming only on the last rung.
+		if (Array.isArray(nodes)) {
+			const seen = new Map();
+			const kept = [];
+			nodes.forEach((n, i) => {
+				if (!isObj(n) || typeof n.id !== 'string') { kept.push(n); return; }
+				if (!seen.has(n.id)) { seen.set(n.id, n); kept.push(n); return; }
+				if (JSON.stringify(seen.get(n.id)) === JSON.stringify(n)) {
+					fix('/nodes/' + i, 'duplicate-node', 'node "' + n.id + '" was listed twice; kept one.');
+					return;
+				}
+				if (!allowLossy) { kept.push(n); return; }
+				let k = 2, id = n.id + '-' + k;
+				const taken = (x) => seen.has(x) || nodes.some((m) => isObj(m) && m !== n && m.id === x);
+				while (taken(id)) { id = n.id + '-' + (++k); }
+				fix('/nodes/' + i + '/id', 'duplicate-id', 'duplicate id "' + n.id + '" renamed to "' + id + '"; edges to "' + n.id + '" point at the first one.', { lossy: true });
+				n.id = id; seen.set(id, n); kept.push(n);
+			});
+			nodes = kept;
+		}
+		if (Array.isArray(groups)) {
+			const seen = new Set();
+			groups = groups.filter((g, i) => {
+				if (!isObj(g) || typeof g.id !== 'string') { return true; }
+				if (!seen.has(g.id)) { seen.add(g.id); return true; }
+				const twin = groups.find((x) => isObj(x) && x.id === g.id);
+				if (JSON.stringify(twin) === JSON.stringify(g)) { fix('/groups/' + i, 'duplicate-node', 'group "' + g.id + '" was listed twice; kept one.'); return false; }
+				if (!allowLossy) { return true; }
+				fix('/groups/' + i, 'duplicate-id', 'duplicate group id "' + g.id + '"; kept the first.', { lossy: true });
+				return false;
+			});
+		}
+		const known = new Set((Array.isArray(nodes) ? nodes : []).filter((n) => isObj(n) && typeof n.id === 'string').map((n) => n.id));
+		const knownList = Array.from(known);
+
+		// -- edges
+		const nodeRef = (ref) => {
+			if (idOf.has(ref)) { return idOf.get(ref); }
+			if (idOf.has(key(ref))) { return idOf.get(key(ref)); }
+			const s = slugify(ref);
+			if (known.has(s)) { return s; }
+			// Models often point an edge at a node's LABEL. When exactly one node has that label,
+			// that is not a guess — it is a lookup.
+			const byLabel = idByLabel.get(cleanText(ref).toLowerCase());
+			if (byLabel) { fix('/edges', 'ref-by-label', 'an edge named a node by its label (' + q(ref) + '); matched it to "' + byLabel + '".'); return byLabel; }
+			return s || String(ref);
+		};
+		let edgesIn = raw.edges !== undefined ? raw.edges : pick(raw, ['links', 'connections', 'arrows']);
+		if (raw.edges === undefined && edgesIn !== undefined) { fix('/edges', 'renamed-field', 'used the "links"/"connections" field as the edges.'); }
+		let edges;
+		if (edgesIn === undefined || edgesIn === null) { edges = []; if (raw.edges === undefined) { fix('/edges', 'defaulted', 'no edges given; drew the nodes alone.'); } }
+		else if (Array.isArray(edgesIn)) {
+			edges = [];
+			const seenEdge = new Set();
+			edgesIn.forEach((e, i) => {
+				const at = '/edges/' + i;
+				if (typeof e === 'string') {
+					const m = /^\s*(.+?)\s*(-{1,3}|={1,3}|\.{1,3}-?)>\s*(.+?)(?:\s*:\s*(.+))?$/.exec(e);
+					if (m) { e = { from: m[1], to: m[3], label: m[4], style: m[2][0] === '.' ? 'dashed' : undefined }; fix(at, 'coerced', 'edge written as "a -> b"; read it as from/to.'); }
+				} else if (Array.isArray(e) && e.length >= 2) { e = { from: e[0], to: e[1], label: e[2] }; fix(at, 'coerced', 'edge given as a list; read it as from/to.'); }
+				if (!isObj(e)) { edges.push(e); return; }
+				const out = {};
+				const fromRaw = scalar(pick(e, ['from', 'source', 'src', 'start', 'a']));
+				const toRaw = scalar(pick(e, ['to', 'target', 'dst', 'dest', 'end', 'b']));
+				if (e.from === undefined && fromRaw !== undefined) { fix(at + '/from', 'renamed-field', 'used "source" as the from end.'); }
+				if (fromRaw !== undefined) { out.from = nodeRef(fromRaw); }
+				if (toRaw !== undefined) { out.to = nodeRef(toRaw); }
+				const label = scalar(pick(e, ['label', 'text', 'name', 'title']));
+				if (label !== undefined && cleanText(label)) { out.label = cleanText(label); }
+				const styleRaw = pick(e, ['style', 'type', 'line', 'kind']);
+				if (styleRaw !== undefined) {
+					const s = STYLE_SYNONYMS[key(styleRaw)];
+					if (s === 'dashed') { out.style = 'dashed'; }
+					if (!s) { fix(at + '/style', 'enum', JSON.stringify(styleRaw) + ' is not a line style; drew it solid.', { show: true }); }
+					else if (s !== styleRaw) { fix(at + '/style', 'synonym', JSON.stringify(styleRaw) + ' read as "' + s + '".'); }
+				} else if (e.dashed === true) { out.style = 'dashed'; }
+				keepTip(e, out);
+				dropped += Object.keys(e).filter((k) => EDGE_KEYS.indexOf(k) < 0).length;
+				// An edge to a node that does not exist. On the last rung it is dropped (and the banner
+				// says so); before that it stays, so validate() can hand the model the list of known ids.
+				const bad = ['from', 'to'].filter((end) => typeof out[end] === 'string' && !known.has(out[end]));
+				if (bad.length && known.size && allowLossy) {
+					fix(at, 'unknown-node', 'dropped: unknown node ' + bad.map((end) => q(end === 'from' ? fromRaw : toRaw)).join(' and ') + '. Known ids: ' + validator.listIds(knownList) + '.', { lossy: true });
+					return;
+				}
+				const sig = out.from + '\u0000' + out.to + '\u0000' + (out.label || '') + '\u0000' + (out.style || '');
+				if (out.from !== undefined && out.to !== undefined && seenEdge.has(sig)) { fix(at, 'duplicate-edge', 'the same edge was listed twice; kept one.'); return; }
+				seenEdge.add(sig);
+				edges.push(out);
+			});
+		} else { edges = edgesIn; }
+
+		// -- long text: the spec's "truncate long labels with a tooltip". Presentation, not meaning —
+		//    the whole label is still there on hover and in the outline — so it never costs a model call.
+		const shorten = (obj, field, max, pointer) => {
+			if (!isObj(obj) || typeof obj[field] !== 'string' || count(obj[field]) <= max) { return null; }
+			const full = obj[field];
+			obj[field] = truncate(full, max);
+			fix(pointer, 'length', count(full) + ' chars, max ' + max + ' — shortened to ' + q(obj[field]) + ' (the full text is kept as a tooltip).', { shortened: true, show: true });
+			return full;
+		};
+		const tip = (s) => truncate(s, HARD.tip);
+		const fullTitle = shorten(spec, 'title', HOUSE.title, '/title');
+		if (fullTitle) { spec.tip = tip(fullTitle); }
+		if (Array.isArray(nodes)) {
+			nodes.forEach((n, i) => {
+				if (!isObj(n)) { return; }
+				const before = [n.label, n.sub];
+				const a = shorten(n, 'label', HOUSE.label, '/nodes/' + i + '/label');
+				const b = shorten(n, 'sub', HOUSE.sub, '/nodes/' + i + '/sub');
+				if (a || b) { n.tip = tip([before[0], before[1]].filter(Boolean).join(' — ')); }
+			});
+		}
+		if (Array.isArray(edges)) { edges.forEach((e, i) => { const f = shorten(e, 'label', HOUSE.edgeLabel, '/edges/' + i + '/label'); if (f) { e.tip = tip(f); } }); }
+		if (Array.isArray(groups)) { groups.forEach((g, i) => { const f = shorten(g, 'label', HOUSE.groupLabel, '/groups/' + i + '/label'); if (f) { g.tip = tip(f); } }); }
+
+		// -- a group nothing lives in has no geometry; drop it rather than draw an empty frame
+		if (Array.isArray(groups) && Array.isArray(nodes)) {
+			const used = new Set(nodes.filter((n) => isObj(n) && typeof n.group === 'string').map((n) => n.group));
+			let changed = true;
+			while (changed) {
+				changed = false;
+				for (const g of groups) { if (isObj(g) && used.has(g.id) && typeof g.parent === 'string' && !used.has(g.parent)) { used.add(g.parent); changed = true; } }
+			}
+			const declared = new Set(groups.filter(isObj).map((g) => g.id));
+			const before = groups.length;
+			groups = groups.filter((g) => !isObj(g) || used.has(g.id) || (typeof g.parent === 'string' && !declared.has(g.parent)));
+			if (groups.length !== before) { fix('/groups', 'empty-group', (before - groups.length) + ' empty group(s) left out.'); }
+		}
+
+		spec.nodes = nodes;
+		spec.edges = edges;
+		if (Array.isArray(groups) ? groups.length : groups !== undefined) { spec.groups = groups; }
+		const KNOWN_TOP = ['v', 'title', 'name', 'caption', 'heading', 'direction', 'dir', 'rankdir', 'orientation', 'flow', 'nodes', 'edges', 'links', 'connections', 'arrows', 'groups', 'tip'];
+		dropped += Object.keys(raw).filter((k) => KNOWN_TOP.indexOf(k) < 0).length;
+		if (dropped) { fix('', 'unknown-field', dropped + ' unrecognised field(s) ignored.'); }
+		return { spec, fixes };
+	}
+	const NODE_KEYS = ['id', 'key', 'label', 'name', 'title', 'text', 'sub', 'subtitle', 'sublabel', 'description', 'desc', 'detail', 'note', 'shape', 'type', 'kind', 'accent', 'highlight', 'primary', 'emphasis', 'group', 'parent', 'cluster', 'in', 'link', 'file', 'href', 'path', 'tip'];
+	const EDGE_KEYS = ['from', 'source', 'src', 'start', 'a', 'to', 'target', 'dst', 'dest', 'end', 'b', 'label', 'text', 'name', 'title', 'style', 'type', 'line', 'kind', 'dashed', 'tip'];
+
+	/**
+	 * `link` in any of the ways a model writes one — an object, "src/app.js:42", "src/app.js#render".
+	 * Only shapes it; WHETHER the path may be opened is decided by the host against the workspace.
+	 */
+	function normalizeLink(v) {
+		if (v === undefined || v === null) { return null; }
+		let p, symbol, line;
+		if (typeof v === 'string') {
+			const m = /^(.*?)(?::(\d+)(?::\d+)?|#(.+))?$/.exec(v.trim());
+			p = m ? m[1] : v; line = m && m[2] ? Number(m[2]) : undefined; symbol = m && m[3] ? m[3] : undefined;
+		} else if (isObj(v)) {
+			p = scalar(pick(v, ['path', 'file', 'uri', 'href']));
+			symbol = scalar(pick(v, ['symbol', 'name', 'function', 'fn']));
+			const l = pick(v, ['line', 'lineNumber', 'row']);
+			line = (typeof l === 'number' || (typeof l === 'string' && /^\d+$/.test(l.trim()))) ? Number(l) : undefined;
+		} else { return null; }
+		p = cleanText(p == null ? '' : p).replace(/^file:\/\//i, '');
+		if (!p) { return null; }
+		const out = { path: Array.from(p).slice(0, HOUSE.path).join('') };
+		if (symbol !== undefined && cleanText(symbol)) { out.symbol = Array.from(cleanText(symbol)).slice(0, HOUSE.symbol).join(''); }
+		if (Number.isInteger(line) && line >= 1) { out.line = line; }
+		return out;
+	}
+
+	// ---- rung 3: degrade ------------------------------------------------------------------------
+	/**
+	 * The repair pass is spent and the spec is still invalid. Cut it down to the part that IS valid,
+	 * and say exactly what was cut — or return null when nothing drawable is left.
+	 *
+	 * Counts relax here and nowhere else: a 17-node diagram the model twice declined to split is
+	 * drawn whole under a banner, because showing 12 of 17 would be a different diagram presented as
+	 * the answer. The HARD ceiling still applies; past it, the tail really is dropped.
+	 * @param {any} spec  a normalize()d spec
+	 * @returns {{ spec: any, notes: string[] } | null}
+	 */
+	function degrade(spec) {
+		if (!isObj(spec) || !Array.isArray(spec.nodes)) { return null; }
+		const notes = [];
+		const plural = (n, word) => n + ' ' + word + (n === 1 ? '' : 's');
+		const out = { v: schema.VERSION, title: '', direction: schema.DIRECTIONS.indexOf(spec.direction) >= 0 ? spec.direction : 'right', nodes: [], edges: [] };
+		if (typeof spec.title === 'string' && cleanText(spec.title)) { out.title = truncate(cleanText(spec.title), HOUSE.title); }
+		else { out.title = 'Untitled diagram'; notes.push('no title given'); }
+		if (typeof spec.tip === 'string') { out.tip = truncate(spec.tip, HARD.tip); }
+		// A spec from a NEWER editor than this one: draw what this schema understands, and say so.
+		if (spec.v !== undefined && !schema.SCHEMAS[spec.v]) { notes.push('written for schema v' + String(spec.v).slice(0, 8) + '; drawn as v' + schema.VERSION); }
+
+		// nodes: keep the well-formed ones, up to the hard ceiling
+		const ids = new Set();
+		let badNodes = 0;
+		for (const n of spec.nodes) {
+			if (!isObj(n) || typeof n.id !== 'string' || !schema.ID_RE.test(n.id) || ids.has(n.id) || typeof n.label !== 'string' || !n.label) { badNodes++; continue; }
+			if (out.nodes.length >= HARD.nodesMax) { badNodes++; continue; }
+			const m = { id: n.id.slice(0, HOUSE.id), label: truncate(n.label, HOUSE.label) };
+			if (typeof n.sub === 'string' && n.sub) { m.sub = truncate(n.sub, HOUSE.sub); }
+			if (schema.SHAPES.indexOf(n.shape) >= 0 && n.shape !== 'box') { m.shape = n.shape; }
+			if (n.accent === true) { m.accent = true; }
+			if (typeof n.group === 'string') { m.group = n.group; }
+			if (isObj(n.link) && typeof n.link.path === 'string' && n.link.path) {
+				m.link = { path: n.link.path.slice(0, HOUSE.path) };
+				if (typeof n.link.symbol === 'string' && n.link.symbol) { m.link.symbol = n.link.symbol.slice(0, HOUSE.symbol); }
+				if (Number.isInteger(n.link.line) && n.link.line >= 1) { m.link.line = n.link.line; }
+			}
+			if (typeof n.tip === 'string') { m.tip = truncate(n.tip, HARD.tip); }
+			ids.add(m.id); out.nodes.push(m);
+		}
+		if (!out.nodes.length) { return null; }
+		if (badNodes) { notes.push(plural(badNodes, 'node') + ' dropped: malformed or over the limit'); }
+		if (out.nodes.length > HOUSE.nodesMax) { notes.push(out.nodes.length + ' nodes — over the ' + HOUSE.nodesMax + '-node limit, drawn anyway'); }
+
+		// one accent
+		const accented = out.nodes.filter((n) => n.accent);
+		if (accented.length > 1) { accented.slice(1).forEach((n) => { delete n.accent; }); notes.push(plural(accented.length - 1, 'extra accent') + ' removed'); }
+
+		// groups: unknown parents and cycles lose their parent; anything deeper than the limit is lifted
+		const groups = [];
+		const gids = new Set();
+		for (const g of (Array.isArray(spec.groups) ? spec.groups : [])) {
+			if (!isObj(g) || typeof g.id !== 'string' || !schema.ID_RE.test(g.id) || gids.has(g.id) || groups.length >= HARD.groupsMax) { continue; }
+			const m = { id: g.id.slice(0, HOUSE.id), label: truncate(typeof g.label === 'string' && g.label ? g.label : g.id, HOUSE.groupLabel) };
+			if (typeof g.parent === 'string') { m.parent = g.parent; }
+			if (typeof g.tip === 'string') { m.tip = truncate(g.tip, HARD.tip); }
+			gids.add(m.id); groups.push(m);
+		}
+		let regrouped = 0;
+		for (const g of groups) { if (g.parent !== undefined && (!gids.has(g.parent) || g.parent === g.id)) { delete g.parent; regrouped++; } }
+		let depths = validator.groupDepths(groups);
+		for (const g of groups) { const d = depths.get(g.id); if (d && d.cycle && g.parent !== undefined) { delete g.parent; regrouped++; depths = validator.groupDepths(groups); } }
+		// too deep: fold the group into its parent (its nodes move up a level) until everything fits
+		const byId = new Map(groups.map((g) => [g.id, g]));
+		const folded = new Map();
+		for (let guard = 0; guard < 32; guard++) {
+			depths = validator.groupDepths(groups.filter((g) => !folded.has(g.id)));
+			const deep = groups.find((g) => !folded.has(g.id) && (depths.get(g.id) || { depth: 1 }).depth > HOUSE.groupDepth);
+			if (!deep) { break; }
+			folded.set(deep.id, deep.parent);
+			for (const g of groups) { if (g.parent === deep.id) { g.parent = deep.parent; } }
+		}
+		const live = groups.filter((g) => !folded.has(g.id));
+		const resolveGroup = (id) => { let cur = id, guard = 0; while (folded.has(cur) && guard++ < 32) { cur = folded.get(cur); } return cur; };
+		let ungrouped = 0;
+		for (const n of out.nodes) {
+			if (n.group === undefined) { continue; }
+			const g = resolveGroup(n.group);
+			if (g !== undefined && byId.has(g) && !folded.has(g)) { n.group = g; } else { delete n.group; ungrouped++; }
+		}
+		if (folded.size) { notes.push(plural(folded.size, 'group') + ' flattened: nested too deep'); }
+		if (regrouped || ungrouped) { notes.push('group references that did not resolve were removed'); }
+		// groups left with nothing in them are not drawn
+		const used = new Set(out.nodes.map((n) => n.group).filter(Boolean));
+		for (let changed = true; changed;) { changed = false; for (const g of live) { if (used.has(g.id) && g.parent && !used.has(g.parent)) { used.add(g.parent); changed = true; } } }
+		const keptGroups = live.filter((g) => used.has(g.id));
+		if (keptGroups.length) { out.groups = keptGroups; }
+
+		// edges: both ends must exist
+		let droppedEdges = 0;
+		for (const e of (Array.isArray(spec.edges) ? spec.edges : [])) {
+			if (!isObj(e) || !ids.has(e.from) || !ids.has(e.to) || out.edges.length >= HARD.edgesMax) { droppedEdges++; continue; }
+			const m = { from: e.from, to: e.to };
+			if (typeof e.label === 'string' && e.label) { m.label = truncate(e.label, HOUSE.edgeLabel); }
+			if (e.style === 'dashed') { m.style = 'dashed'; }
+			if (typeof e.tip === 'string') { m.tip = truncate(e.tip, HARD.tip); }
+			out.edges.push(m);
+		}
+		if (droppedEdges) { notes.push(plural(droppedEdges, 'edge') + ' dropped: no valid ends'); }
+		return { spec: out, notes };
+	}
+
+	// ---- the ladder -----------------------------------------------------------------------------
+	/** What the "auto-fixed" popover and the tool result list: the fixes a person might care about. */
+	function visibleFixes(fixes) { return (fixes || []).filter((f) => f.show || f.lossy); }
+	const plural = (n, one, many) => n + ' ' + (n === 1 ? one : many);
+	/** "2 edges dropped: unknown nodes" — what a degraded diagram's banner says it lost. */
+	function lossNotes(fixes) {
+		const lossy = (fixes || []).filter((f) => f.lossy);
+		const edges = lossy.filter((f) => f.cls === 'unknown-node').length;
+		const ids = lossy.filter((f) => f.cls === 'duplicate-id').length;
+		const notes = [];
+		if (edges) { notes.push(plural(edges, 'edge', 'edges') + ' dropped: unknown nodes'); }
+		if (ids) { notes.push(plural(ids, 'duplicate id', 'duplicate ids') + ' renamed'); }
+		return notes;
+	}
+	/** "2 labels shortened" — the short form that sits beside the auto-fixed badge. */
+	function fixSummary(fixes) {
+		const n = (fixes || []).filter((f) => f.shortened).length;
+		return n ? plural(n, 'label', 'labels') + ' shortened' : '';
+	}
+
+	/**
+	 * Run the ladder for ONE render_diagram call.
+	 *
+	 *   status   ok         valid as written (defaults aside)                        → draw it
+	 *            fixed      rung 1 tidied something, meaning untouched               → draw it, "auto-fixed" badge
+	 *            errors     needs the model's one repair pass (only when !final)     → return the error list
+	 *            degraded   repair pass spent; the valid part is drawn               → draw it, banner + Retry
+	 *            failed     nothing drawable                                         → source + errors + Retry
+	 *            truncated  the JSON stops mid-structure                             → re-request, never repair
+	 *
+	 * @param {any} input  the tool call's arguments (an object), or raw text
+	 * @param {{ final?: boolean }} [opts]  final: the model has had its repair pass (or there is no
+	 *        model to ask — a replay, a fence) so `errors` is not an option; degrade instead.
+	 */
+	function prepare(input, opts) {
+		const final = !!(opts && opts.final);
+		const n = normalize(input);
+		if (n.truncated) { return { status: 'truncated', fixes: n.fixes, errors: [{ pointer: '', cls: 'truncated', message: 'the spec was cut off before it was complete.' }], notes: [] }; }
+		if (n.syntax) {
+			const errors = [{ pointer: '', cls: 'syntax', message: 'not valid JSON (' + n.syntax + '). Send one JSON object with "title", "nodes" and "edges".' }];
+			return { status: final ? 'failed' : 'errors', fixes: n.fixes, errors, notes: [] };
+		}
+		const first = validator.validate(n.spec, { tier: 'house' });
+		if (first.ok) {
+			const summary = fixSummary(n.fixes);
+			return { status: visibleFixes(n.fixes).length ? 'fixed' : 'ok', spec: n.spec, fixes: n.fixes, errors: [], notes: summary ? [summary] : [] };
+		}
+		if (!final) { return { status: 'errors', fixes: n.fixes, errors: first.errors, notes: [] }; }
+
+		// Rung 3. The same tidy-up again, this time allowed to drop and rename; then cut away
+		// whatever is still invalid. `first.errors` is kept: it is what the banner's details show.
+		const last = normalize(input, { lossy: true });
+		const d = degrade(last.spec);
+		if (d) {
+			const again = validator.validate(d.spec, { tier: 'hard' });
+			if (again.ok) { return { status: 'degraded', spec: d.spec, fixes: last.fixes, errors: first.errors, notes: lossNotes(last.fixes).concat(d.notes) }; }
+		}
+		return { status: 'failed', fixes: last.fixes, errors: first.errors, notes: [] };
+	}
+
+	/**
+	 * Accept a spec the RENDERER was handed — from the host, or from a session written by an older
+	 * build. It has already been through the ladder once, so this is the cheap re-check that makes
+	 * "no unvalidated spec reaches the renderer" true at the last possible moment: migrate, validate
+	 * against the HARD tier, and if (and only if) that fails, run the ladder with no model to ask.
+	 * @returns {{ ok: boolean, spec?: any, notes?: string[], errors?: any[] }}
+	 */
+	function accept(spec) {
+		const m = validator.migrate(spec);
+		const r = validator.validate(m, { tier: 'hard' });
+		if (r.ok) {
+			// Valid — but the validator checks the fields it knows and is silent about any others, and a
+			// record from a session file can carry anything. What is handed on is the declared shape only.
+			const declared = schema.project(schema.SCHEMAS[m.v].hard, m);
+			return { ok: true, spec: Object.assign({ v: m.v }, declared), notes: [] };
+		}
+		const p = prepare(spec, { final: true });
+		if (p.spec) { return { ok: true, spec: p.spec, notes: p.notes }; }
+		return { ok: false, errors: p.errors };
+	}
+
+	return { parseLenient, normalize, degrade, prepare, accept, truncate, slugify, cleanText, visibleFixes, lossNotes, fixSummary };
+}));
diff --git a/extensions/levelcode-ai/diagram/schema.js b/extensions/levelcode-ai/diagram/schema.js
new file mode 100644
index 0000000..bb263b1
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/schema.js
@@ -0,0 +1,253 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · the Graph JSON schema  (docs/RICH-DIAGRAMS.md, "Diagram spec")
+ *
+ *  The model describes STRUCTURE only — nodes, edges, groups and one accent. It never sets
+ *  coordinates, colours or font sizes, so it cannot violate the style guide; the renderer owns those.
+ *
+ *  This file is the single definition of what a spec may contain. The SAME object is:
+ *    • sent to the model as `render_diagram`'s input schema (diagram/tool.js), and
+ *    • interpreted here to validate every spec that comes back (check()),
+ *  so the contract the model is shown and the contract it is held to cannot drift apart.
+ *
+ *  Two tiers of limits, deliberately:
+ *    HOUSE — what the model is asked for (12 nodes, 28-char labels …). Breaking one is an error the
+ *            repair ladder deals with.
+ *    HARD  — what the renderer will ever accept, even from a degraded spec. These exist because a
+ *            spec is untrusted input: they bound layout time and DOM size no matter what arrives.
+ *
+ *  Versioned: `v` names the schema a spec was written against, and SCHEMAS keeps every version this
+ *  editor can still read, so a chat saved today renders after the schema moves on (NFR-4).
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+(function (root, factory) {
+	'use strict';
+	if (typeof module === 'object' && module.exports) { module.exports = factory(); }
+	else { (root.LCDiagram = root.LCDiagram || {}).schema = factory(); }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+	'use strict';
+
+	/** The schema version new specs are written against. */
+	const VERSION = 1;
+
+	const SHAPES = ['box', 'decision', 'store', 'actor'];
+	const DIRECTIONS = ['right', 'down'];
+	const EDGE_STYLES = ['solid', 'dashed'];
+	/** "Lowercase slug": starts alphanumeric, then letters, digits, `_` or `-`. */
+	const ID_RE = /^[a-z0-9][a-z0-9_-]*$/;
+	const ID_PATTERN = '^[a-z0-9][a-z0-9_-]*$';
+
+	/** What the model is asked for — the numbers in the spec's field tables. */
+	const HOUSE = Object.freeze({
+		title: 80, label: 28, sub: 32, edgeLabel: 20, groupLabel: 28,
+		nodesMin: 1, nodesMax: 12, groupDepth: 2,
+		// Not in the field tables, but a spec is untrusted and these have to be SOME number. Chosen
+		// so no diagram that respects the 12-node cap can run into them.
+		edgesMax: 30, groupsMax: 8, id: 32, path: 260, symbol: 80
+	});
+	/**
+	 * What the renderer accepts at all. A degraded spec may exceed a HOUSE count (it is drawn anyway,
+	 * under a banner) but never these; text limits do not relax, because truncation always applies.
+	 */
+	const HARD = Object.freeze(Object.assign({}, HOUSE, { nodesMax: 24, edgesMax: 48, groupsMax: 12, tip: 400 }));
+
+	/**
+	 * Build the JSON Schema for one tier.
+	 *
+	 * `house` is the wire schema — plain JSON Schema with nothing a provider could reject (no custom
+	 * keywords, no `additionalProperties`: a model that adds a stray field is tidied, not failed).
+	 * `v` is deliberately not in it: the version is checked by validate() before any schema is
+	 * chosen, and a model writing a new spec never needs to state it.
+	 * `hard` is the render-ready shape: the same fields under the HARD limits, plus `tip` — the full
+	 * text of a label the auto-fixer had to truncate, which the renderer shows as a tooltip. `tip` is
+	 * ours; the model is never told about it.
+	 * @param {'house'|'hard'} tier
+	 */
+	function build(tier) {
+		const L = tier === 'hard' ? HARD : HOUSE;
+		const hard = tier === 'hard';
+		const tip = hard ? { tip: { type: 'string', maxLength: HARD.tip } } : {};
+		// Only a DECLARED id carries the slug rule. A reference (an edge end, a node's group, a group's
+		// parent) needs no rule of its own: the semantic layer requires it to equal a declared id, so it
+		// is a slug or it is an error either way — and every keyword here is paid for on each request.
+		const id = { type: 'string', maxLength: L.id, pattern: ID_PATTERN };
+		const ref = { type: 'string' };
+		return {
+			type: 'object',
+			properties: Object.assign({
+				title: { type: 'string', minLength: 1, maxLength: L.title, description: 'The takeaway, not the topic.' },
+				direction: { type: 'string', enum: DIRECTIONS, description: 'Default right.' },
+				nodes: {
+					type: 'array', minItems: L.nodesMin, maxItems: L.nodesMax,
+					items: {
+						type: 'object',
+						properties: Object.assign({
+							id: Object.assign({ description: 'Unique lowercase slug.' }, id),
+							label: { type: 'string', minLength: 1, maxLength: L.label },
+							sub: { type: 'string', maxLength: L.sub, description: 'Second line.' },
+							shape: { type: 'string', enum: SHAPES, description: 'box=step (default), decision=branch, store=data at rest, actor=person or outside system.' },
+							accent: { type: 'boolean', description: 'At most one node.' },
+							group: Object.assign({ description: 'Group id.' }, ref),
+							link: {
+								type: 'object',
+								description: 'Workspace file to open on click.',
+								properties: {
+									path: { type: 'string', minLength: 1, maxLength: L.path },
+									symbol: { type: 'string', maxLength: L.symbol },
+									line: { type: 'integer', minimum: 1 }
+								},
+								required: ['path']
+							}
+						}, tip),
+						required: ['id', 'label']
+					}
+				},
+				edges: {
+					type: 'array', maxItems: L.edgesMax,
+					items: {
+						type: 'object',
+						properties: Object.assign({
+							from: ref, to: ref,
+							label: { type: 'string', maxLength: L.edgeLabel },
+							style: { type: 'string', enum: EDGE_STYLES }
+						}, tip),
+						required: ['from', 'to']
+					}
+				},
+				groups: {
+					type: 'array', maxItems: L.groupsMax,
+					items: {
+						type: 'object',
+						properties: Object.assign({
+							id: id,
+							label: { type: 'string', minLength: 1, maxLength: L.groupLabel },
+							parent: Object.assign({ description: 'Enclosing group (depth 2 max).' }, ref)
+						}, tip),
+						required: ['id', 'label']
+					}
+				}
+			}, tip),
+			required: ['title', 'nodes', 'edges']
+		};
+	}
+
+	/**
+	 * Every schema version this editor can read, each in both tiers. Adding v2 means adding a row
+	 * here and a step in validate.migrate() — never editing v1, which stored chats still point at.
+	 */
+	const deepFreeze = (o) => { if (o && typeof o === 'object' && !Object.isFrozen(o)) { Object.freeze(o); for (const k of Object.keys(o)) { deepFreeze(o[k]); } } return o; };
+	const SCHEMAS = deepFreeze({
+		1: { house: build('house'), hard: build('hard') }
+	});
+	const KNOWN_VERSIONS = Object.keys(SCHEMAS).map(Number);
+
+	// ---- a JSON-Schema-subset interpreter -------------------------------------------------------
+	// Exactly the keywords build() uses, and no more: type, properties, required, items, enum,
+	// minLength/maxLength, minItems/maxItems, pattern, minimum. Ajv would do this too, but it would be
+	// the extension's first runtime dependency for ~80 lines of work — and its messages are not the
+	// ones the repair ladder needs. Each error names WHAT WAS EXPECTED and THE VALID OPTIONS, because
+	// that is what turns a model's repair into a lookup instead of a guess.
+
+	/** JSON's own type names, with `integer` and `array` told apart from number/object. */
+	function typeOf(v) {
+		if (v === null) { return 'null'; }
+		if (Array.isArray(v)) { return 'array'; }
+		if (typeof v === 'number') { return Number.isInteger(v) ? 'integer' : 'number'; }
+		return typeof v;
+	}
+	/** Escape one JSON Pointer segment (RFC 6901). */
+	function seg(s) { return String(s).replace(/~/g, '~0').replace(/\//g, '~1'); }
+
+	/**
+	 * What a too-long / too-many error should tell the model to DO. Keyed by the tail of the
+	 * pointer, so `/nodes/3/label` and `/nodes/7/label` share one hint.
+	 */
+	const HINTS = {
+		'title': 'Say the takeaway in fewer words.',
+		'label': 'Shorten or move detail to prose.',
+		'sub': 'Shorten or move detail to prose.',
+		'nodes': 'Draw an overview, then one diagram per sub-flow.',
+		'edges': 'Keep the connections that carry the point.',
+		'groups': 'Use fewer containers.'
+	};
+	function hintFor(pointer) {
+		const tail = String(pointer).split('/').pop() || '';
+		return HINTS[tail] ? ' ' + HINTS[tail] : '';
+	}
+	const NOUN = { nodes: 'nodes', edges: 'edges', groups: 'groups' };
+
+	/**
+	 * Check `value` against `schema`, appending every violation to `errors`.
+	 * @param {any} schema
+	 * @param {any} value
+	 * @param {string} pointer  JSON Pointer of `value` ('' for the root)
+	 * @param {Array<{pointer:string, cls:string, message:string}>} errors
+	 */
+	function check(schema, value, pointer, errors) {
+		const got = typeOf(value);
+		const want = schema.type;
+		const typeOk = want === got || (want === 'number' && got === 'integer');
+		if (!typeOk) {
+			errors.push({ pointer, cls: 'type', message: 'expected ' + (want === 'object' ? 'an object' : want === 'array' ? 'an array' : want === 'integer' ? 'an integer' : 'a ' + want) + ', got ' + got + '.' });
+			return;   // nothing below means anything on a value of the wrong type
+		}
+		if (schema.enum && schema.enum.indexOf(value) < 0) {
+			errors.push({ pointer, cls: pointer === '/v' ? 'version' : 'enum', message: JSON.stringify(value) + ' is not allowed. Use one of: ' + schema.enum.join(', ') + '.' });
+		}
+		if (want === 'string') {
+			const n = Array.from(value).length;   // code points — an emoji is one character, not two
+			if (schema.maxLength != null && n > schema.maxLength) {
+				errors.push({ pointer, cls: 'length', message: n + ' chars, max ' + schema.maxLength + '.' + hintFor(pointer) });
+			}
+			if (schema.minLength != null && n < schema.minLength) {
+				errors.push({ pointer, cls: 'required', message: 'must not be empty.' });
+			} else if (schema.pattern && n <= (schema.maxLength != null ? schema.maxLength : n) && !new RegExp(schema.pattern).test(value)) {
+				errors.push({ pointer, cls: 'pattern', message: JSON.stringify(value) + ' is not a lowercase slug (letters, digits, "-" or "_"; e.g. "auth-check").' });
+			}
+		}
+		if ((want === 'integer' || want === 'number') && schema.minimum != null && value < schema.minimum) {
+			errors.push({ pointer, cls: 'range', message: value + ' is below the minimum ' + schema.minimum + '.' });
+		}
+		if (want === 'array') {
+			const noun = NOUN[String(pointer).split('/').pop() || ''] || 'items';
+			if (schema.maxItems != null && value.length > schema.maxItems) {
+				errors.push({ pointer, cls: 'count', message: value.length + ' ' + noun + ', max ' + schema.maxItems + '.' + hintFor(pointer) });
+			}
+			if (schema.minItems != null && value.length < schema.minItems) {
+				errors.push({ pointer, cls: 'count', message: value.length + ' ' + noun + ', min ' + schema.minItems + '.' });
+			}
+			if (schema.items) {
+				for (let i = 0; i < value.length; i++) { check(schema.items, value[i], pointer + '/' + i, errors); }
+			}
+		}
+		if (want === 'object') {
+			for (const key of (schema.required || [])) {
+				if (value[key] === undefined) { errors.push({ pointer: pointer + '/' + seg(key), cls: 'required', message: 'missing. This field is required.' }); }
+			}
+			const props = schema.properties || {};
+			for (const key of Object.keys(props)) {
+				if (value[key] !== undefined) { check(props[key], value[key], pointer + '/' + seg(key), errors); }
+			}
+		}
+	}
+
+	/**
+	 * A copy of `value` holding only what `schema` declares, in the order the value had it.
+	 * check() says whether the declared fields are right; it does not object to fields it has never
+	 * heard of — a model that adds `color` should not be sent back for it. So after a spec passes,
+	 * this is what makes "validated" mean "exactly this shape, and nothing that came along with it".
+	 */
+	function project(schema, value) {
+		if (schema.type === 'object' && typeOf(value) === 'object') {
+			const props = schema.properties || {};
+			const out = {};
+			for (const key of Object.keys(value)) {
+				if (Object.prototype.hasOwnProperty.call(props, key) && value[key] !== undefined) { out[key] = project(props[key], value[key]); }
+			}
+			return out;
+		}
+		if (schema.type === 'array' && Array.isArray(value)) { return value.map((v) => (schema.items ? project(schema.items, v) : v)); }
+		return value;
+	}
+
+	return { VERSION, KNOWN_VERSIONS, SHAPES, DIRECTIONS, EDGE_STYLES, ID_RE, ID_PATTERN, HOUSE, HARD, SCHEMAS, build, check, project, typeOf, seg };
+}));
diff --git a/extensions/levelcode-ai/diagram/validate.js b/extensions/levelcode-ai/diagram/validate.js
new file mode 100644
index 0000000..1b45819
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/validate.js
@@ -0,0 +1,177 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · layered validation  (docs/RICH-DIAGRAMS.md, "Validation and repair")
+ *
+ *  THE ONE GATE. Every spec — whichever model wrote it, whether it arrived a second ago or was read
+ *  back from a session saved last month — passes through validate() before anything lays it out.
+ *  That is what keeps the quality of a diagram independent of the model that asked for it.
+ *
+ *  Layers, cheapest first:
+ *    version    `v` names a schema this editor still reads (migrate() lifts old ones forward)
+ *    schema     fields, types, enums, lengths, counts — schema.check(), driven by the wire schema
+ *    semantics  the things a schema cannot say: edge ends exist, ids are unique, one accent at most,
+ *               groups nest two deep and never in a circle
+ *
+ *  EVERY error comes back at once, each as  <JSON Pointer>: <what was expected + the valid options>.
+ *  A model handed "unknown node" has to guess; handed the list of known ids it only has to look.
+ *
+ *  Pure, synchronous, dependency-free — it runs in the extension host (the tool result) and again in
+ *  the webview (the renderer refuses anything this rejects).
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+(function (root, factory) {
+	'use strict';
+	if (typeof module === 'object' && module.exports) { module.exports = factory(require('./schema')); }
+	else { (root.LCDiagram = root.LCDiagram || {}).validate = factory(root.LCDiagram.schema); }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function (schema) {
+	'use strict';
+
+	const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+	const q = (s) => JSON.stringify(String(s));
+	/** "a, b, c" — capped, so one error line can never carry a whole oversized spec back to the model. */
+	function listIds(ids, max) {
+		const cap = max || 16;
+		const shown = ids.slice(0, cap).join(', ');
+		return ids.length > cap ? shown + ', … (' + (ids.length - cap) + ' more)' : (shown || '(none)');
+	}
+
+	/**
+	 * Lift a spec written against an older schema to the current one. Today there is only v1, so
+	 * this is the identity — but it is the single place a future v2 teaches the editor to keep
+	 * reading v1, and render paths call it so that promise is exercised from day one.
+	 * A spec with no `v` at all is read as v1 (the tool marks the field optional).
+	 */
+	function migrate(spec) {
+		if (!isObj(spec)) { return spec; }
+		if (spec.v === undefined) { return Object.assign({ v: 1 }, spec); }
+		return spec;
+	}
+
+	/**
+	 * The group each group id sits in, walking `parent` links. Returns { depth, cycle } per id.
+	 * Depth 1 = a top-level group. A cycle is reported once, on every member of it.
+	 */
+	function groupDepths(groups) {
+		const byId = new Map();
+		for (const g of groups) { if (isObj(g) && typeof g.id === 'string' && !byId.has(g.id)) { byId.set(g.id, g); } }
+		const out = new Map();
+		for (const id of byId.keys()) {
+			let depth = 1, cur = byId.get(id), cycle = false;
+			const seen = new Set([id]);
+			while (cur && typeof cur.parent === 'string' && byId.has(cur.parent)) {
+				if (seen.has(cur.parent)) { cycle = true; break; }
+				seen.add(cur.parent);
+				cur = byId.get(cur.parent);
+				depth++;
+			}
+			out.set(id, { depth, cycle });
+		}
+		return out;
+	}
+
+	/** The semantic layer. Assumes nothing about shape — it skips whatever the schema layer already flagged. */
+	function checkSemantics(spec, errors, limits) {
+		const nodes = Array.isArray(spec.nodes) ? spec.nodes : [];
+		const edges = Array.isArray(spec.edges) ? spec.edges : [];
+		const groups = Array.isArray(spec.groups) ? spec.groups : [];
+
+		// ids are unique
+		const firstAt = new Map();
+		const ids = [];
+		nodes.forEach((n, i) => {
+			if (!isObj(n) || typeof n.id !== 'string') { return; }
+			if (firstAt.has(n.id)) {
+				errors.push({ pointer: '/nodes/' + i + '/id', cls: 'duplicate-id', message: 'duplicate id ' + q(n.id) + ' (already used by /nodes/' + firstAt.get(n.id) + '). Every node needs its own id.' });
+			} else { firstAt.set(n.id, i); ids.push(n.id); }
+		});
+
+		// one accent at most
+		const accented = nodes.filter((n) => isObj(n) && n.accent === true).map((n) => String(n.id));
+		if (accented.length > 1) {
+			errors.push({ pointer: '/nodes', cls: 'accent-count', message: accented.length + ' nodes have accent=true, max 1 (' + listIds(accented) + '). Keep it on the node the title is about.' });
+		}
+
+		// groups: unique ids, parents exist, no cycles, depth within the limit
+		const groupAt = new Map();
+		const groupIds = [];
+		groups.forEach((g, i) => {
+			if (!isObj(g) || typeof g.id !== 'string') { return; }
+			if (groupAt.has(g.id)) {
+				errors.push({ pointer: '/groups/' + i + '/id', cls: 'duplicate-id', message: 'duplicate group id ' + q(g.id) + ' (already used by /groups/' + groupAt.get(g.id) + ').' });
+			} else { groupAt.set(g.id, i); groupIds.push(g.id); }
+		});
+		const depths = groupDepths(groups);
+		groups.forEach((g, i) => {
+			if (!isObj(g) || typeof g.id !== 'string' || groupAt.get(g.id) !== i) { return; }
+			if (typeof g.parent === 'string') {
+				if (g.parent === g.id) {
+					errors.push({ pointer: '/groups/' + i + '/parent', cls: 'group-cycle', message: 'a group cannot contain itself. Remove "parent" or name another group.' });
+					return;
+				}
+				if (!groupAt.has(g.parent)) {
+					errors.push({ pointer: '/groups/' + i + '/parent', cls: 'unknown-group', message: 'unknown group ' + q(g.parent) + '. Known groups: ' + listIds(groupIds) + '.' });
+					return;
+				}
+			}
+			const d = depths.get(g.id);
+			if (d && d.cycle) {
+				errors.push({ pointer: '/groups/' + i + '/parent', cls: 'group-cycle', message: 'groups contain each other in a circle (' + q(g.id) + ' → ' + q(g.parent) + ' → …). Nesting must be a tree.' });
+			} else if (d && d.depth > limits.groupDepth) {
+				errors.push({ pointer: '/groups/' + i + '/parent', cls: 'group-depth', message: 'nested ' + d.depth + ' deep, max ' + limits.groupDepth + '. Flatten it.' });
+			}
+		});
+		nodes.forEach((n, i) => {
+			if (isObj(n) && typeof n.group === 'string' && !groupAt.has(n.group)) {
+				errors.push({ pointer: '/nodes/' + i + '/group', cls: 'unknown-group', message: 'unknown group ' + q(n.group) + '. Known groups: ' + listIds(groupIds) + '.' });
+			}
+		});
+
+		// each end of an edge names an existing node
+		edges.forEach((e, i) => {
+			if (!isObj(e)) { return; }
+			for (const end of ['from', 'to']) {
+				if (typeof e[end] === 'string' && !firstAt.has(e[end])) {
+					errors.push({ pointer: '/edges/' + i + '/' + end, cls: 'unknown-node', message: 'unknown node ' + q(e[end]) + '. Known ids: ' + listIds(ids) + '.' });
+				}
+			}
+		});
+	}
+
+	/**
+	 * Validate a parsed spec.
+	 * @param {any} spec
+	 * @param {{ tier?: 'house'|'hard' }} [opts]  `house` (default) is what the model is held to; `hard`
+	 *        is what the renderer accepts — see schema.js.
+	 * @returns {{ ok: boolean, errors: Array<{pointer:string, cls:string, message:string}> }}
+	 */
+	function validate(spec, opts) {
+		const tier = opts && opts.tier === 'hard' ? 'hard' : 'house';
+		/** @type {Array<{pointer:string, cls:string, message:string}>} */
+		const errors = [];
+		if (!isObj(spec)) {
+			errors.push({ pointer: '', cls: 'type', message: 'expected an object with "title", "nodes" and "edges", got ' + schema.typeOf(spec) + '.' });
+			return { ok: false, errors };
+		}
+		const v = spec.v === undefined ? schema.VERSION : spec.v;
+		const known = schema.SCHEMAS[v];
+		if (!known) {
+			errors.push({ pointer: '/v', cls: 'version', message: 'unknown schema version ' + JSON.stringify(spec.v) + '. This editor reads: ' + schema.KNOWN_VERSIONS.join(', ') + '.' });
+			return { ok: false, errors };
+		}
+		schema.check(known[tier], spec, '', errors);
+		checkSemantics(spec, errors, tier === 'hard' ? schema.HARD : schema.HOUSE);
+		return { ok: errors.length === 0, errors };
+	}
+
+	/** One error as the line the model (and the details popover) reads. */
+	function formatError(e) { return (e.pointer || '/') + ': ' + e.message; }
+	/** Every error, one per line — the spec's "Error format". */
+	function formatErrors(errors) { return (errors || []).map(formatError).join('\n'); }
+	/** Error classes with counts — what telemetry records (classes, never the text). */
+	function errorClasses(errors) {
+		const out = {};
+		for (const e of (errors || [])) { out[e.cls] = (out[e.cls] || 0) + 1; }
+		return out;
+	}
+
+	return { validate, migrate, groupDepths, formatError, formatErrors, errorClasses, listIds };
+}));
diff --git a/extensions/levelcode-ai/test/diagramRepair.test.js b/extensions/levelcode-ai/test/diagramRepair.test.js
new file mode 100644
index 0000000..e1cf867
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramRepair.test.js
@@ -0,0 +1,361 @@
+/*---------------------------------------------------------------------------------------------
+ *  Rich diagrams — the repair ladder — run: node test/diagramRepair.test.js
+ *
+ *  docs/RICH-DIAGRAMS.md, "Validation and repair". Two things are tested here:
+ *
+ *  1. THE GOLDEN CORPUS (test/fixtures/diagrams/corpus.json): every recorded way a model gets a
+ *     spec wrong, with the outcome the ladder must reach — the exact errors returned to the model,
+ *     the fixes shown to the user, and what is drawn once the one repair pass is spent. A change to
+ *     the validator or the auto-fixer must keep every case green.
+ *
+ *  2. THE RULES THAT ORDER THE RUNGS, as properties of prepare() itself: a deterministic fix never
+ *     costs a model call; a fix that changes what the diagram SAYS is never applied before the
+ *     model's one pass; nothing loops; truncated output is re-requested, never repaired.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const R = require('../diagram/repair');
+const V = require('../diagram/validate');
+const schema = require('../diagram/schema');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+const corpus = JSON.parse(fs.readFileSync(path.join(__dirname, 'fixtures', 'diagrams', 'corpus.json'), 'utf8'));
+const jev = () => JSON.parse(JSON.stringify(corpus.find((c) => c.name === 'spec-example').input));
+
+/** What the fixture records about one attempt, recomputed from the live code. */
+function outcome(input) {
+	const a = R.prepare(input), b = R.prepare(input, { final: true });
+	const first = { status: a.status };
+	if (a.errors.length) { first.errors = V.formatErrors(a.errors).split('\n'); }
+	const shown = R.visibleFixes(a.fixes).map((f) => (f.pointer || '/') + ': ' + f.message);
+	if (shown.length) { first.shown = shown; }
+	const tidied = Array.from(new Set(a.fixes.filter((f) => !f.show && !f.lossy).map((f) => f.cls))).sort();
+	if (tidied.length) { first.tidied = tidied; }
+	const final = { status: b.status };
+	if (b.notes.length) { final.notes = b.notes; }
+	if (b.spec) { final.drawn = { nodes: b.spec.nodes.length, edges: b.spec.edges.length, groups: (b.spec.groups || []).length }; }
+	return { first, final, a, b };
+}
+
+test('CORPUS: it exists, every case says why it is there, and names are unique', () => {
+	assert.ok(corpus.length >= 30, 'a corpus of ' + corpus.length + ' is not a corpus');
+	const names = new Set();
+	for (const c of corpus) {
+		assert.ok(c.name && !names.has(c.name), 'duplicate or missing name: ' + c.name);
+		names.add(c.name);
+		assert.ok(typeof c.why === 'string' && c.why.length > 15, c.name + ' needs a `why`');
+		assert.ok(c.first && c.final, c.name + ' records both attempts');
+	}
+});
+
+for (const c of corpus) {
+	test('CORPUS · ' + c.name + ' — ' + c.first.status + ' → ' + c.final.status, () => {
+		const o = outcome(c.input);
+		assert.deepStrictEqual(o.first, c.first, 'first attempt');
+		assert.deepStrictEqual(o.final, c.final, 'after the repair pass');
+	});
+}
+
+test('LADDER: whatever prepare() hands the renderer is valid — every corpus case, both attempts', () => {
+	for (const c of corpus) {
+		const { a, b } = outcome(c.input);
+		for (const r of [a, b]) {
+			if (r.status === 'ok' || r.status === 'fixed') { assert.deepStrictEqual(V.validate(r.spec), { ok: true, errors: [] }, c.name + ': ' + r.status + ' must meet the HOUSE limits'); }
+			else if (r.status === 'degraded') { assert.deepStrictEqual(V.validate(r.spec, { tier: 'hard' }), { ok: true, errors: [] }, c.name + ': degraded must meet the HARD limits'); }
+			else { assert.strictEqual(r.spec, undefined, c.name + ': ' + r.status + ' carries no spec to draw'); }
+		}
+	}
+});
+
+test('LADDER: a fix that changes MEANING is never applied before the model has had its pass', () => {
+	for (const c of corpus) {
+		const { a, b } = outcome(c.input);
+		assert.ok(!a.fixes.some((f) => f.lossy), c.name + ': a lossy fix on the first attempt');
+		if (a.status === 'ok' || a.status === 'fixed') {
+			// what is drawn has exactly as many nodes and edges as when nothing lossy is allowed
+			assert.strictEqual(a.spec.nodes.length, b.spec.nodes.length, c.name);
+			assert.strictEqual(a.spec.edges.length, b.spec.edges.length, c.name);
+			assert.deepStrictEqual(a.spec, b.spec, c.name + ': `final` changes nothing when the first attempt was fine');
+		}
+		if (b.status === 'degraded') { assert.ok(b.notes.length > 0, c.name + ': a degraded diagram always says what it lost'); }
+	}
+});
+
+test('LADDER: the first attempt never degrades, and the final attempt never asks again', () => {
+	for (const c of corpus) {
+		const { a, b } = outcome(c.input);
+		assert.ok(['ok', 'fixed', 'errors', 'truncated'].includes(a.status), c.name + ': first=' + a.status);
+		assert.ok(['ok', 'fixed', 'degraded', 'failed', 'truncated'].includes(b.status), c.name + ': final=' + b.status + ' — "no automatic second repair"');
+		if (a.status === 'errors') { assert.ok(a.errors.length > 0, c.name + ': `errors` with no errors would be a blank result'); }
+	}
+});
+
+test('LADDER: truncated output is re-requested, never repaired — even on the final attempt', () => {
+	for (const cut of ['{"title":"T","nodes":[{"id":"a","label":"A"},{"id":"b","la', '{"title":"T","nodes":[', '{"title":"T","nodes":[{"id":"a","label":"A"}],"edges":[{"from":"a"', '{"title": "T" /* comment never closed']) {
+		for (const final of [false, true]) {
+			const r = R.prepare(cut, { final });
+			assert.strictEqual(r.status, 'truncated', JSON.stringify(cut));
+			assert.strictEqual(r.spec, undefined, 'nothing is drawn from a guess');
+		}
+	}
+	// ...but a complete object followed by chatter is complete
+	assert.strictEqual(R.prepare('{"title":"T","nodes":[{"id":"a","label":"A"}],"edges":[]} Hope that helps!').status, 'ok');
+});
+
+test('LADDER: it is idempotent — a prepared spec passes again untouched, with nothing to fix', () => {
+	for (const c of corpus) {
+		const { b } = outcome(c.input);
+		if (!b.spec) { continue; }
+		const again = R.prepare(b.spec, { final: true });
+		// a degraded spec may exceed the HOUSE counts by design; everything else must come back clean
+		if (b.status !== 'degraded') { assert.strictEqual(again.status, 'ok', c.name + ': ' + JSON.stringify(again.errors)); }
+		assert.deepStrictEqual(R.visibleFixes(again.fixes), [], c.name + ': a second pass found something to fix');
+		assert.deepStrictEqual(again.spec, b.spec, c.name + ': a second pass changed the spec');
+	}
+});
+
+test('FIXED vs DEGRADED: shortening a label keeps the whole text, as a tooltip', () => {
+	const r = R.prepare({ title: 'T', nodes: [{ id: 'a', label: 'Validate the incoming request payload', sub: 'and then hand the whole thing to the next stage' }], edges: [] });
+	assert.strictEqual(r.status, 'fixed');
+	assert.strictEqual(r.spec.nodes[0].label, 'Validate the incoming…');
+	assert.ok(Array.from(r.spec.nodes[0].label).length <= schema.HOUSE.label);
+	assert.ok(Array.from(r.spec.nodes[0].sub).length <= schema.HOUSE.sub);
+	assert.strictEqual(r.spec.nodes[0].tip, 'Validate the incoming request payload — and then hand the whole thing to the next stage');
+	assert.deepStrictEqual(r.notes, ['2 labels shortened']);
+	assert.ok(r.fixes.every((f) => !f.lossy), 'nothing was lost, so nothing is lossy');
+});
+
+test('FIXED vs DEGRADED: an edge to nowhere goes to the model first; only then is it dropped, loudly', () => {
+	const spec = { title: 'T', nodes: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }], edges: [{ from: 'a', to: 'b' }, { from: 'a', to: 'ghost' }] };
+	const first = R.prepare(spec);
+	assert.strictEqual(first.status, 'errors');
+	assert.deepStrictEqual(V.formatErrors(first.errors), '/edges/1/to: unknown node "ghost". Known ids: a, b.');
+	const last = R.prepare(spec, { final: true });
+	assert.strictEqual(last.status, 'degraded');
+	assert.deepStrictEqual(last.spec.edges, [{ from: 'a', to: 'b' }]);
+	assert.deepStrictEqual(last.notes, ['1 edge dropped: unknown nodes']);
+});
+
+test('TIDY: an edge that names a node by its label is a lookup, not a guess — unless two nodes share it', () => {
+	const one = R.prepare({ title: 'T', nodes: [{ id: 'n1', label: 'Load balancer' }, { id: 'n2', label: 'API' }], edges: [{ from: 'load balancer', to: 'API' }] });
+	assert.strictEqual(one.status, 'ok');
+	assert.deepStrictEqual(one.spec.edges, [{ from: 'n1', to: 'n2' }]);
+	const two = R.prepare({ title: 'T', nodes: [{ id: 'n1', label: 'API' }, { id: 'n2', label: 'API' }, { id: 'n3', label: 'DB' }], edges: [{ from: 'API', to: 'DB' }] });
+	assert.strictEqual(two.status, 'errors', 'two nodes are called "API": which one is a question for the model');
+	assert.match(V.formatErrors(two.errors), /unknown node "api"\. Known ids: n1, n2, n3\./);
+});
+
+test('TIDY: ids are slugged, and every edge follows its node to the new id', () => {
+	const r = R.prepare({ title: 'T', nodes: [{ id: 'Auth Service', label: 'Auth' }, { id: 'Müller & Söhne', label: 'M' }, { id: '  ', label: 'Blank id' }], edges: [{ from: 'Auth Service', to: 'Müller & Söhne' }, { from: 'auth service', to: 'Blank id' }] });
+	assert.strictEqual(r.status, 'ok', JSON.stringify(r.errors));
+	assert.deepStrictEqual(r.spec.nodes.map((x) => x.id), ['auth-service', 'muller-sohne', 'blank-id']);
+	assert.deepStrictEqual(r.spec.edges, [{ from: 'auth-service', to: 'muller-sohne' }, { from: 'auth-service', to: 'blank-id' }]);
+	for (const x of r.spec.nodes) { assert.match(x.id, schema.ID_RE); }
+});
+
+test('TIDY: defaults are not fixes — the plain example comes back byte-for-byte, with none recorded', () => {
+	const r = R.prepare(jev());
+	assert.strictEqual(r.status, 'ok');
+	assert.deepStrictEqual(r.fixes, []);
+	assert.strictEqual(JSON.stringify(r.spec), JSON.stringify(jev()));
+	const bare = R.prepare({ title: 'T', nodes: [{ id: 'a', label: 'A' }] });
+	assert.strictEqual(bare.status, 'ok');
+	assert.deepStrictEqual(bare.spec, { v: 1, title: 'T', direction: 'right', nodes: [{ id: 'a', label: 'A' }], edges: [] });
+});
+
+test('TIDY: prepare() never mutates what it was given', () => {
+	for (const c of corpus) {
+		if (typeof c.input !== 'object') { continue; }
+		const before = JSON.stringify(c.input);
+		R.prepare(c.input); R.prepare(c.input, { final: true });
+		assert.strictEqual(JSON.stringify(c.input), before, c.name);
+	}
+});
+
+test('DEGRADE: counts relax up to the hard ceiling and no further; what is cut is counted', () => {
+	const many = (k) => ({ title: 'T', nodes: Array.from({ length: k }, (_, i) => ({ id: 'n' + i, label: 'L' + i })), edges: Array.from({ length: k - 1 }, (_, i) => ({ from: 'n' + i, to: 'n' + (i + 1) })) });
+	const d14 = R.prepare(many(14), { final: true });
+	assert.strictEqual(d14.status, 'degraded');
+	assert.strictEqual(d14.spec.nodes.length, 14, 'showing 12 of 14 would be a different diagram presented as the answer');
+	assert.deepStrictEqual(d14.notes, ['14 nodes — over the 12-node limit, drawn anyway']);
+	const d40 = R.prepare(many(40), { final: true });
+	assert.strictEqual(d40.spec.nodes.length, schema.HARD.nodesMax);
+	assert.ok(d40.spec.edges.every((e) => d40.spec.nodes.some((x) => x.id === e.from) && d40.spec.nodes.some((x) => x.id === e.to)), 'no edge is left pointing at a dropped node');
+	assert.match(d40.notes.join(' | '), /16 nodes dropped/);
+});
+
+test('DEGRADE: one accent survives — the first; groups past depth two fold into their parent', () => {
+	const acc = R.prepare({ title: 'T', nodes: [{ id: 'a', label: 'A', accent: true }, { id: 'b', label: 'B', accent: true }, { id: 'c', label: 'C', accent: true }], edges: [] }, { final: true });
+	assert.deepStrictEqual(acc.spec.nodes.filter((x) => x.accent).map((x) => x.id), ['a']);
+	assert.deepStrictEqual(acc.notes, ['2 extra accents removed']);
+	const deep = R.prepare({ title: 'T', groups: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B', parent: 'a' }, { id: 'c', label: 'C', parent: 'b' }, { id: 'd', label: 'D', parent: 'c' }], nodes: [{ id: 'x', label: 'X', group: 'd' }, { id: 'y', label: 'Y', group: 'c' }, { id: 'z', label: 'Z', group: 'b' }], edges: [] }, { final: true });
+	assert.strictEqual(deep.status, 'degraded');
+	assert.deepStrictEqual(deep.spec.groups.map((g) => g.id), ['a', 'b']);
+	assert.deepStrictEqual(deep.spec.nodes.map((x) => x.group), ['b', 'b', 'b'], 'the nodes move up to the deepest group that is still allowed');
+});
+
+test('DEGRADE: whatever part is well-formed is drawn — one good node among junk is a diagram', () => {
+	const r = R.prepare({ title: 'T', nodes: [{}, { id: 7 }, null, { id: 'ok', label: 'Fine' }], edges: [{ from: 'ok', to: '7' }, { from: 'ok' }] }, { final: true });
+	assert.strictEqual(r.status, 'degraded');
+	assert.deepStrictEqual(r.spec.nodes, [{ id: '7', label: '7' }, { id: 'ok', label: 'Fine' }], 'a node with only an id is labelled by it');
+	assert.deepStrictEqual(r.spec.edges, [{ from: 'ok', to: '7' }]);
+	assert.match(r.notes.join(' | '), /2 nodes dropped/);
+});
+
+test('DEGRADE: nothing drawable is `failed` — never an empty picture', () => {
+	for (const bad of [{ title: 'T', nodes: [], edges: [] }, { title: 'T', nodes: [{}, { sub: 'no name' }, null, []], edges: [] }, { title: 'T' }, 'prose', 42, null, [], { nodes: 'a,b' }]) {
+		const r = R.prepare(bad, { final: true });
+		assert.strictEqual(r.status, 'failed', JSON.stringify(bad));
+		assert.ok(r.errors.length > 0, 'failed, with the reason');
+		assert.strictEqual(r.spec, undefined);
+	}
+});
+
+test('ACCEPT: the renderer\'s last-moment check — valid passes, old versions migrate, broken is cut down or refused', () => {
+	assert.deepStrictEqual(R.accept(jev()), { ok: true, spec: jev(), notes: [] });
+	const noV = jev(); delete noV.v;
+	assert.strictEqual(R.accept(noV).spec.v, 1);
+	const broken = jev(); broken.edges.push({ from: 'jev', to: 'ghost' });
+	const cut = R.accept(broken);
+	assert.strictEqual(cut.ok, true);
+	assert.strictEqual(cut.spec.edges.length, 3);
+	assert.deepStrictEqual(cut.notes, ['1 edge dropped: unknown nodes']);
+	assert.strictEqual(R.accept({ title: 'T', nodes: [] }).ok, false);
+	assert.strictEqual(R.accept(null).ok, false);
+	// a degraded spec (over the house count) is accepted as-is: it already went through the ladder
+	const big = { v: 1, title: 'T', direction: 'right', nodes: Array.from({ length: 15 }, (_, i) => ({ id: 'n' + i, label: 'L' })), edges: [] };
+	assert.deepStrictEqual(R.accept(big), { ok: true, spec: big, notes: [] });
+});
+
+test('ACCEPT: what is handed to the renderer is the declared shape and nothing that came along with it', () => {
+	// a record from a session file can carry anything; the validator is silent about fields it does not know
+	const stored = jev();
+	stored.script = 'alert(1)'; stored.onload = 'x()'; stored.nodes[0].onclick = 'alert(2)'; stored.nodes[0].style = 'position:fixed';
+	stored.nodes[1].link = { path: 'agent.js', symbol: 'runAgent', href: 'javascript:alert(3)', command: 'rm -rf' };
+	stored.edges[0].href = 'https://example.invalid/'; stored.nodes[0].tip = 'the full label';
+	const a = R.accept(stored);
+	assert.strictEqual(a.ok, true);
+	assert.deepStrictEqual(a.notes, [], 'nothing was lost that a picture shows, so there is nothing to tell the user');
+	const want = jev(); want.nodes[0].tip = 'the full label'; want.nodes[1].link = { path: 'agent.js', symbol: 'runAgent' };
+	assert.deepStrictEqual(a.spec, want);
+	assert.ok(!/alert|javascript:|rm -rf|example\.invalid|position:fixed/.test(JSON.stringify(a.spec)));
+	assert.strictEqual(stored.script, 'alert(1)', 'the input is not edited in place');
+	// a clean spec comes back equal, field for field and in the order it was stored — Copy source does not reshuffle
+	const clean = R.prepare(jev()).spec;
+	assert.strictEqual(JSON.stringify(R.accept(clean).spec), JSON.stringify(clean));
+	// and accepting twice is accepting once
+	assert.deepStrictEqual(R.accept(a.spec).spec, a.spec);
+	// the version is kept: it is how an old chat is told from a new one
+	assert.strictEqual(a.spec.v, 1);
+	assert.strictEqual(Object.keys(a.spec)[0], 'v');
+	// names every object already answers to are not "declared" just because a lookup finds them
+	const sly = JSON.parse('{"v":1,"title":"T","toString":"x","hasOwnProperty":"y","constructor":"z","__proto__":{"polluted":1},"nodes":[{"id":"a","label":"A","constructor":"z","valueOf":"w","__proto__":{"polluted":2}}],"edges":[]}');
+	const got = R.accept(sly);
+	assert.strictEqual(got.ok, true);
+	assert.deepStrictEqual([Object.keys(got.spec), Object.keys(got.spec.nodes[0])], [['v', 'title', 'nodes', 'edges'], ['id', 'label']]);
+	assert.strictEqual(got.spec.polluted, undefined); assert.strictEqual(got.spec.nodes[0].polluted, undefined);
+	assert.strictEqual(Object.getPrototypeOf(got.spec), Object.prototype); assert.strictEqual(Object.getPrototypeOf(got.spec.nodes[0]), Object.prototype);
+	assert.strictEqual(({}).polluted, undefined);
+	assert.strictEqual(typeof got.spec.toString, 'function', 'and the real ones are still the real ones');
+});
+
+test('LENIENT JSON: what is inside a string is left alone', () => {
+	const src = '{"title": "a } b // not a comment, /* nor this */ and a trailing , ]", "nodes": [{"id": "a", "label": "it\'s \\"quoted\\" \\\\ here"}], "edges": [],}';
+	const p = R.parseLenient(src);
+	assert.strictEqual(p.ok, true, p.error);
+	assert.strictEqual(p.value.title, 'a } b // not a comment, /* nor this */ and a trailing , ]');
+	assert.strictEqual(p.value.nodes[0].label, 'it\'s "quoted" \\ here');
+});
+
+test('LENIENT JSON: strict JSON takes the strict path; numbers, nesting and unicode survive the tolerant one', () => {
+	assert.deepStrictEqual(R.parseLenient('{"a":[1,2.5,-3e2,true,null,{"b":"é🙂"}]}'), { ok: true, value: { a: [1, 2.5, -300, true, null, { b: 'é🙂' }] }, lenient: false });
+	const p = R.parseLenient("{a: [1, 2.5, -3e2, True, None, {b: 'é🙂'},],}");
+	assert.deepStrictEqual(p, { ok: true, value: { a: [1, 2.5, -300, true, null, { b: 'é🙂' }] }, lenient: true });
+	assert.strictEqual(R.parseLenient('').ok, false);
+	assert.strictEqual(R.parseLenient('no braces here').ok, false);
+	assert.strictEqual(R.parseLenient('{"a": }').ok, false, 'garbage is not guessed at');
+	assert.strictEqual(R.parseLenient('{"a": }').truncated, undefined, 'and it is not mistaken for truncation');
+});
+
+test('TEXT: truncate() cuts at a word when one is near, counts characters, and never exceeds the limit', () => {
+	assert.strictEqual(R.truncate('Validate the incoming request payload', 28), 'Validate the incoming…');
+	assert.strictEqual(R.truncate('short', 28), 'short');
+	assert.strictEqual(R.truncate('Supercalifragilisticexpialidocious', 12), 'Supercalifr…');
+	assert.strictEqual(Array.from(R.truncate('🙂'.repeat(40), 10)).length, 10, 'an emoji is one character and is never split');
+	for (let max = 2; max < 40; max++) { assert.ok(Array.from(R.truncate('The quick brown fox jumps over the lazy dog, twice.', max)).length <= max); }
+});
+
+test('TEXT: control characters, zero-width characters and bidi overrides never reach a label', () => {
+	const r = R.prepare({ title: 'a\u0000b\u0007c', nodes: [{ id: 'a', label: 'invoice‮fdp.exe', sub: 'zero​width and\ttab\nnewline' }], edges: [] });
+	assert.strictEqual(r.spec.title, 'abc');
+	assert.strictEqual(r.spec.nodes[0].label, 'invoicefdp.exe', 'the right-to-left override is gone, so the label reads as what it is');
+	assert.strictEqual(r.spec.nodes[0].sub, 'zerowidth and tab newline');
+	// eslint-disable-next-line no-control-regex
+	assert.ok(!/[\u0000-\u001f​-‏‪-‮⁦-⁩]/.test(JSON.stringify(r.spec).replace(/\\u/g, '')));
+});
+
+test('TEXT: markup in a label is TEXT — kept exactly, never interpreted (the painter escapes it)', () => {
+	const r = R.prepare({ title: '<script>alert(1)</script>', nodes: [{ id: 'a', label: '<b onclick=x>hi</b>' }], edges: [] });
+	assert.strictEqual(r.spec.title, '<script>alert(1)</script>');
+	assert.strictEqual(r.spec.nodes[0].label, '<b onclick=x>hi</b>');
+});
+
+test('LINKS: shaped here, never trusted here — the host decides what may be opened', () => {
+	const r = R.prepare({ title: 'T', nodes: [
+		{ id: 'a', label: 'A', link: { path: 'src/agent.js', symbol: 'runAgent', line: '12' } },
+		{ id: 'b', label: 'B', link: 'src/agent.js:890' },
+		{ id: 'c', label: 'C', link: 'src/agent.js#runTool' },
+		{ id: 'd', label: 'D', link: 'file:///etc/passwd' },
+		{ id: 'e', label: 'E', link: { path: '../../secrets.env', line: -4 } },
+		{ id: 'f', label: 'F', link: { symbol: 'no path' } },
+		{ id: 'g', label: 'G', link: 42 }
+	], edges: [] });
+	assert.strictEqual(r.status, 'ok', JSON.stringify(r.errors));
+	const links = r.spec.nodes.map((x) => x.link);
+	assert.deepStrictEqual(links[0], { path: 'src/agent.js', symbol: 'runAgent', line: 12 });
+	assert.deepStrictEqual(links[1], { path: 'src/agent.js', line: 890 });
+	assert.deepStrictEqual(links[2], { path: 'src/agent.js', symbol: 'runTool' });
+	assert.deepStrictEqual(links[3], { path: '/etc/passwd' }, 'kept as a path; refusing it is the host\'s job, and it does');
+	assert.deepStrictEqual(links[4], { path: '../../secrets.env' }, 'a bad line number is dropped, the path is not judged here');
+	assert.strictEqual(links[5], undefined, 'no path, no link');
+	assert.strictEqual(links[6], undefined);
+});
+
+test('SAFETY: a spec cannot reach Object.prototype', () => {
+	const evil = '{"title":"T","__proto__":{"polluted":1},"constructor":{"prototype":{"polluted":1}},"nodes":[{"id":"a","label":"A","__proto__":{"polluted":1}}],"edges":[{"from":"a","to":"a","__proto__":{"polluted":1}}],"groups":{"__proto__":{"label":"x"}}}';
+	const r = R.prepare(evil, { final: true });
+	assert.ok(r.spec, r.status);
+	assert.strictEqual(({}).polluted, undefined);
+	assert.strictEqual(Object.prototype.polluted, undefined);
+	assert.strictEqual(Object.getPrototypeOf(r.spec), Object.prototype);
+	for (const x of r.spec.nodes) { assert.deepStrictEqual(Object.keys(x).sort(), ['id', 'label']); }
+});
+
+test('ROBUST: prepare() never throws and always names a status — seeded junk, both attempts', () => {
+	let seed = 20261004;
+	const rnd = () => { seed = (seed * 1664525 + 1013904223) >>> 0; return seed / 4294967296; };
+	const atoms = [null, undefined, 0, -1, 1e21, NaN, '', 'a', 'right', 'true', true, false, [], {}, [[]], { id: 'a' }, { from: 'a', to: 'b' }, 'a -> b', ['a', 'b'], '\u0000', '🙂', { path: 'x' }];
+	const pick = () => atoms[Math.floor(rnd() * atoms.length)];
+	const STATUSES = ['ok', 'fixed', 'errors', 'degraded', 'failed', 'truncated'];
+	for (let i = 0; i < 1500; i++) {
+		const spec = {};
+		for (const k of ['v', 'title', 'direction', 'nodes', 'edges', 'groups']) {
+			if (rnd() < 0.75) { spec[k] = rnd() < 0.5 ? pick() : Array.from({ length: Math.floor(rnd() * 5) }, () => (rnd() < 0.5 ? pick() : { id: pick(), label: pick(), sub: pick(), shape: pick(), accent: pick(), group: pick(), link: pick(), from: pick(), to: pick(), parent: pick(), style: pick() })); }
+		}
+		for (const final of [false, true]) {
+			const r = R.prepare(rnd() < 0.2 ? JSON.stringify(spec) : spec, { final });
+			assert.ok(STATUSES.includes(r.status), r.status);
+			assert.ok(Array.isArray(r.fixes) && Array.isArray(r.errors) && Array.isArray(r.notes));
+			if (r.spec) { assert.strictEqual(V.validate(r.spec, { tier: 'hard' }).ok, true, 'whatever is drawn is valid: ' + JSON.stringify(spec)); }
+			if (final) { assert.notStrictEqual(r.status, 'errors'); }
+		}
+	}
+});
+
+console.log('diagramRepair: ' + n + ' tests passed');
diff --git a/extensions/levelcode-ai/test/diagramSchema.test.js b/extensions/levelcode-ai/test/diagramSchema.test.js
new file mode 100644
index 0000000..1682224
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramSchema.test.js
@@ -0,0 +1,207 @@
+/*---------------------------------------------------------------------------------------------
+ *  Rich diagrams — the Graph JSON schema and the validator — run: node test/diagramSchema.test.js
+ *
+ *  docs/RICH-DIAGRAMS.md: "The validator is the one gate every format passes." These tests pin the
+ *  contract a model is shown (the wire schema), the contract it is held to (validate), and the one
+ *  thing that makes a broken spec cheap to fix: every error at once, each naming what was expected.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const schema = require('../diagram/schema');
+const V = require('../diagram/validate');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+/** The worked example from the spec, verbatim. */
+const jev = () => ({
+	v: 1, title: 'Jev classifies; your code decides the action', direction: 'right',
+	nodes: [
+		{ id: 'in', label: 'Customer message', sub: 'plus account details' },
+		{ id: 'jev', label: 'Jev', sub: 'returns probabilities', accent: true },
+		{ id: 'bill', label: 'Route to billing' },
+		{ id: 'rev', label: 'Human review' }
+	],
+	edges: [{ from: 'in', to: 'jev' }, { from: 'jev', to: 'bill', label: '0.90 or more' }, { from: 'jev', to: 'rev', label: 'under 0.90' }]
+});
+const lines = (r) => V.formatErrors(r.errors).split('\n');
+
+test('LIMITS: the numbers are the ones in the spec\'s field tables', () => {
+	const H = schema.HOUSE;
+	assert.strictEqual(H.title, 80);
+	assert.strictEqual(H.label, 28);
+	assert.strictEqual(H.sub, 32);
+	assert.strictEqual(H.edgeLabel, 20);
+	assert.strictEqual(H.nodesMin, 1);
+	assert.strictEqual(H.nodesMax, 12);
+	assert.strictEqual(H.groupDepth, 2);
+	assert.deepStrictEqual(schema.SHAPES, ['box', 'decision', 'store', 'actor']);
+	assert.deepStrictEqual(schema.DIRECTIONS, ['right', 'down']);
+	assert.deepStrictEqual(schema.EDGE_STYLES, ['solid', 'dashed']);
+	assert.strictEqual(schema.VERSION, 1);
+});
+
+test('LIMITS: the hard tier only ever RELAXES counts — text limits hold even for a degraded spec', () => {
+	const H = schema.HOUSE, X = schema.HARD;
+	assert.ok(X.nodesMax > H.nodesMax && X.edgesMax > H.edgesMax && X.groupsMax > H.groupsMax);
+	for (const k of ['title', 'label', 'sub', 'edgeLabel', 'groupLabel', 'groupDepth', 'id']) {
+		assert.strictEqual(X[k], H[k], k + ' must not relax');
+	}
+	assert.ok(X.nodesMax <= 32, 'the hard ceiling exists to bound layout time and DOM size');
+});
+
+test('WIRE: the schema sent to providers uses plain JSON Schema and nothing a provider could reject', () => {
+	const ALLOWED = new Set(['type', 'properties', 'required', 'items', 'enum', 'minLength', 'maxLength', 'minItems', 'maxItems', 'pattern', 'minimum', 'description']);
+	const walk = (node, where) => {
+		for (const k of Object.keys(node)) { assert.ok(ALLOWED.has(k), 'keyword "' + k + '" at ' + where + ' is not plain JSON Schema'); }
+		for (const [k, v] of Object.entries(node.properties || {})) { walk(v, where + '/' + k); }
+		if (node.items) { walk(node.items, where + '[]'); }
+	};
+	walk(schema.SCHEMAS[1].house, '');
+	const wire = JSON.stringify(schema.SCHEMAS[1].house);
+	assert.ok(!/additionalProperties/.test(wire), 'a stray field is tidied, not failed — so it is never forbidden on the wire');
+	assert.ok(!/"tip"/.test(wire), '`tip` is the renderer\'s, never the model\'s');
+	assert.ok(/"tip"/.test(JSON.stringify(schema.SCHEMAS[1].hard)), 'the render-ready shape carries tooltips');
+	assert.deepStrictEqual(schema.SCHEMAS[1].house.required, ['title', 'nodes', 'edges']);
+});
+
+test('WIRE: the schema the model sees and the schema it is checked against are one object', () => {
+	// If these ever diverge, a spec could satisfy what the model was told and still be rejected.
+	const r = { errors: [] };
+	schema.check(schema.SCHEMAS[1].house, jev(), '', r.errors);
+	assert.deepStrictEqual(r.errors, []);
+	assert.deepStrictEqual(V.validate(jev()), { ok: true, errors: [] });
+});
+
+test('EXAMPLE: the spec\'s worked example is valid, and validating it does not change it', () => {
+	const spec = jev(), before = JSON.stringify(spec);
+	assert.strictEqual(V.validate(spec).ok, true);
+	assert.strictEqual(JSON.stringify(spec), before, 'validate() is read-only');
+});
+
+test('ERROR FORMAT: the three lines the spec prints, word for word', () => {
+	const bad = jev();
+	bad.edges[1].to = 'billing';
+	bad.nodes[0].sub = 'x'.repeat(46);
+	bad.nodes[2].accent = true;
+	const out = lines(V.validate(bad));
+	assert.ok(out.includes('/edges/1/to: unknown node "billing". Known ids: in, jev, bill, rev.'), out.join('\n'));
+	assert.ok(out.includes('/nodes/0/sub: 46 chars, max 32. Shorten or move detail to prose.'), out.join('\n'));
+	assert.ok(out.some((l) => l.startsWith('/nodes: 2 nodes have accent=true, max 1 (jev, bill).')), out.join('\n'));
+	assert.strictEqual(out.length, 3, 'EVERY error at once — and no extras');
+});
+
+test('ERROR FORMAT: each error is a JSON Pointer, what was expected, and the valid options', () => {
+	const r = V.validate({ title: 'T', direction: 'sideways', nodes: [{ id: 'a', label: 'A', shape: 'blob' }], edges: [{ from: 'a', to: 'a', style: 'wavy' }] });
+	const out = lines(r);
+	assert.ok(out.includes('/direction: "sideways" is not allowed. Use one of: right, down.'), out.join('\n'));
+	assert.ok(out.includes('/nodes/0/shape: "blob" is not allowed. Use one of: box, decision, store, actor.'), out.join('\n'));
+	assert.ok(out.includes('/edges/0/style: "wavy" is not allowed. Use one of: solid, dashed.'), out.join('\n'));
+	for (const e of r.errors) {
+		assert.ok(e.pointer === '' || e.pointer[0] === '/', 'pointer: ' + e.pointer);
+		assert.ok(typeof e.cls === 'string' && e.cls, 'every error has a class for telemetry');
+		assert.ok(/[.]$/.test(e.message), 'a sentence, not a code: ' + e.message);
+	}
+});
+
+test('ERROR FORMAT: a pointer escapes "/" and "~" (RFC 6901)', () => {
+	assert.strictEqual(schema.seg('a/b~c'), 'a~1b~0c');
+});
+
+test('ERROR FORMAT: the list of known ids is capped, so one error cannot carry a whole spec back', () => {
+	const many = { title: 'T', nodes: Array.from({ length: 24 }, (_, i) => ({ id: 'n' + i, label: 'L' })), edges: [{ from: 'n0', to: 'ghost' }] };
+	const line = lines(V.validate(many, { tier: 'hard' })).find((l) => l.startsWith('/edges/0/to'));
+	assert.ok(line, 'reported');
+	assert.match(line, /Known ids: n0, n1, .*n15, … \(8 more\)\.$/);
+	assert.ok(line.length < 220, 'bounded: ' + line.length);
+});
+
+test('SCHEMA: required fields, types, lengths and counts', () => {
+	assert.ok(lines(V.validate({ nodes: [{ id: 'a', label: 'A' }], edges: [] })).includes('/title: missing. This field is required.'));
+	assert.ok(lines(V.validate({ title: 'T', nodes: 'a,b', edges: [] })).includes('/nodes: expected an array, got string.'));
+	assert.ok(lines(V.validate({ title: 'T', nodes: [], edges: [] })).includes('/nodes: 0 nodes, min 1.'));
+	assert.ok(lines(V.validate({ title: 'T', nodes: [{ id: 'a' }], edges: [] })).includes('/nodes/0/label: missing. This field is required.'));
+	assert.ok(lines(V.validate({ title: 'T', nodes: [{ id: 'a', label: 7 }], edges: [] })).includes('/nodes/0/label: expected a string, got integer.'));
+	assert.ok(lines(V.validate({ title: 'T', nodes: [{ id: 'a', label: '' }], edges: [] })).includes('/nodes/0/label: must not be empty.'));
+	assert.ok(lines(V.validate({ title: 'x'.repeat(81), nodes: [{ id: 'a', label: 'A' }], edges: [] })).includes('/title: 81 chars, max 80. Say the takeaway in fewer words.'));
+	assert.ok(lines(V.validate({ title: 'T', nodes: [{ id: 'a', label: 'A' }], edges: [{ from: 'a', to: 'a', label: 'x'.repeat(21) }] })).includes('/edges/0/label: 21 chars, max 20. Shorten or move detail to prose.'));
+	assert.ok(lines(V.validate({ title: 'T', nodes: [{ id: 'Not A Slug', label: 'A' }], edges: [] }))[0].startsWith('/nodes/0/id: "Not A Slug" is not a lowercase slug'));
+	assert.ok(lines(V.validate({ title: 'T', nodes: [{ id: 'a', label: 'A', link: { path: 'a.js', line: 0 } }], edges: [] })).includes('/nodes/0/link/line: 0 is below the minimum 1.'));
+	assert.ok(lines(V.validate({ title: 'T', nodes: [{ id: 'a', label: 'A', link: {} }], edges: [] })).includes('/nodes/0/link/path: missing. This field is required.'));
+});
+
+test('SCHEMA: over twelve nodes is an error that tells the model what to do instead', () => {
+	const spec = { title: 'T', nodes: Array.from({ length: 13 }, (_, i) => ({ id: 'n' + i, label: 'L' })), edges: [] };
+	assert.deepStrictEqual(lines(V.validate(spec)), ['/nodes: 13 nodes, max 12. Draw an overview, then one diagram per sub-flow.']);
+	assert.strictEqual(V.validate(spec, { tier: 'hard' }).ok, true, 'the renderer can still draw it — that is what degrading relies on');
+	spec.nodes = Array.from({ length: schema.HARD.nodesMax + 1 }, (_, i) => ({ id: 'n' + i, label: 'L' }));
+	assert.strictEqual(V.validate(spec, { tier: 'hard' }).ok, false, 'but never past the hard ceiling');
+});
+
+test('SCHEMA: length is counted in characters, not UTF-16 units', () => {
+	const spec = { title: 'T', nodes: [{ id: 'a', label: '🙂'.repeat(28) }], edges: [] };
+	assert.strictEqual(V.validate(spec).ok, true, '28 emoji are 28 characters');
+	spec.nodes[0].label = '🙂'.repeat(29);
+	assert.ok(lines(V.validate(spec)).includes('/nodes/0/label: 29 chars, max 28. Shorten or move detail to prose.'));
+});
+
+test('SEMANTICS: ids are unique — nodes and groups each', () => {
+	const r = V.validate({ title: 'T', groups: [{ id: 'g', label: 'G' }, { id: 'g', label: 'H' }], nodes: [{ id: 'a', label: 'A', group: 'g' }, { id: 'a', label: 'B' }], edges: [] });
+	const out = lines(r);
+	assert.ok(out.includes('/nodes/1/id: duplicate id "a" (already used by /nodes/0). Every node needs its own id.'), out.join('\n'));
+	assert.ok(out.includes('/groups/1/id: duplicate group id "g" (already used by /groups/0).'), out.join('\n'));
+	assert.deepStrictEqual(V.errorClasses(r.errors), { 'duplicate-id': 2 });
+});
+
+test('SEMANTICS: groups — unknown parent, self parent, a circle, and nesting past two', () => {
+	const base = (groups, nodes) => ({ title: 'T', groups, nodes: nodes || [{ id: 'x', label: 'X', group: groups[0].id }], edges: [] });
+	assert.ok(lines(V.validate(base([{ id: 'a', label: 'A', parent: 'zz' }]))).includes('/groups/0/parent: unknown group "zz". Known groups: a.'));
+	assert.ok(lines(V.validate(base([{ id: 'a', label: 'A', parent: 'a' }]))).includes('/groups/0/parent: a group cannot contain itself. Remove "parent" or name another group.'));
+	const circle = V.validate(base([{ id: 'a', label: 'A', parent: 'b' }, { id: 'b', label: 'B', parent: 'a' }]));
+	assert.deepStrictEqual(V.errorClasses(circle.errors), { 'group-cycle': 2 });
+	const deep = V.validate(base([{ id: 'a', label: 'A' }, { id: 'b', label: 'B', parent: 'a' }, { id: 'c', label: 'C', parent: 'b' }]));
+	assert.deepStrictEqual(lines(deep), ['/groups/2/parent: nested 3 deep, max 2. Flatten it.']);
+	assert.strictEqual(V.validate(base([{ id: 'a', label: 'A' }, { id: 'b', label: 'B', parent: 'a' }])).ok, true, 'depth 2 is allowed');
+	assert.ok(lines(V.validate({ title: 'T', groups: [{ id: 'a', label: 'A' }], nodes: [{ id: 'x', label: 'X', group: 'nope' }], edges: [] })).includes('/nodes/0/group: unknown group "nope". Known groups: a.'));
+});
+
+test('SEMANTICS: a self-loop and a cycle are legal — a state machine needs both', () => {
+	const r = V.validate({ title: 'T', nodes: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }], edges: [{ from: 'a', to: 'a' }, { from: 'a', to: 'b' }, { from: 'b', to: 'a' }] });
+	assert.deepStrictEqual(r, { ok: true, errors: [] });
+});
+
+test('VERSION: an unknown version is refused by name; no version reads as v1', () => {
+	const future = jev(); future.v = 3;
+	assert.deepStrictEqual(lines(V.validate(future)), ['/v: unknown schema version 3. This editor reads: 1.']);
+	const none = jev(); delete none.v;
+	assert.strictEqual(V.validate(none).ok, true);
+	assert.strictEqual(V.migrate(none).v, 1);
+	assert.strictEqual(none.v, undefined, 'migrate() returns a copy');
+});
+
+test('VERSION: every schema version in the registry has both tiers and still reads the example (NFR-4)', () => {
+	assert.ok(schema.KNOWN_VERSIONS.includes(schema.VERSION));
+	for (const v of schema.KNOWN_VERSIONS) {
+		assert.ok(schema.SCHEMAS[v].house && schema.SCHEMAS[v].hard, 'v' + v + ' has both tiers');
+		const spec = V.migrate(Object.assign(jev(), { v }));
+		assert.strictEqual(V.validate(spec, { tier: 'hard' }).ok, true, 'a v' + v + ' spec still renders');
+	}
+	assert.ok(Object.isFrozen(schema.SCHEMAS) && Object.isFrozen(schema.SCHEMAS[1]), 'a stored chat points at v1; v1 must not be edited in place');
+});
+
+test('ROBUST: validate() never throws, whatever it is handed', () => {
+	const junk = [null, undefined, 0, 'x', [], [1, 2], true, {}, { nodes: null }, { nodes: [null, 1, 'a', [], {}] }, { title: {}, nodes: {}, edges: {} },
+		{ title: 'T', nodes: [{ id: 'a', label: 'A', link: 'x' }], edges: [null, 3, { from: {}, to: [] }] }, { title: 'T', nodes: [{ id: 'a', label: 'A' }], edges: [], groups: [null, { id: 4 }, 'g'] }];
+	for (const j of junk) {
+		const r = V.validate(j);
+		assert.strictEqual(typeof r.ok, 'boolean');
+		assert.ok(Array.isArray(r.errors));
+		assert.strictEqual(r.ok, r.errors.length === 0);
+		assert.strictEqual(typeof V.formatErrors(r.errors), 'string');
+	}
+	assert.strictEqual(lines(V.validate('nope'))[0], '/: expected an object with "title", "nodes" and "edges", got string.');
+});
+
+console.log('diagramSchema: ' + n + ' tests passed');
diff --git a/extensions/levelcode-ai/test/fixtures/diagrams/corpus.json b/extensions/levelcode-ai/test/fixtures/diagrams/corpus.json
new file mode 100644
index 0000000..a34a45a
--- /dev/null
+++ b/extensions/levelcode-ai/test/fixtures/diagrams/corpus.json
@@ -0,0 +1,1811 @@
+[
+	{
+		"name": "spec-example",
+		"why": "The worked example in the spec. Must pass untouched.",
+		"input": {
+			"v": 1,
+			"title": "Jev classifies; your code decides the action",
+			"direction": "right",
+			"nodes": [
+				{
+					"id": "in",
+					"label": "Customer message",
+					"sub": "plus account details"
+				},
+				{
+					"id": "jev",
+					"label": "Jev",
+					"sub": "returns probabilities",
+					"accent": true
+				},
+				{
+					"id": "bill",
+					"label": "Route to billing"
+				},
+				{
+					"id": "rev",
+					"label": "Human review"
+				}
+			],
+			"edges": [
+				{
+					"from": "in",
+					"to": "jev"
+				},
+				{
+					"from": "jev",
+					"to": "bill",
+					"label": "0.90 or more"
+				},
+				{
+					"from": "jev",
+					"to": "rev",
+					"label": "under 0.90"
+				}
+			]
+		},
+		"first": {
+			"status": "ok"
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 4,
+				"edges": 3,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "spec-error-format",
+		"why": "The three errors the spec uses to show the error format: an unknown node, a 46-char sub, two accents.",
+		"input": {
+			"v": 1,
+			"title": "Jev classifies; your code decides the action",
+			"direction": "right",
+			"nodes": [
+				{
+					"id": "in",
+					"label": "Customer message",
+					"sub": "plus the account details we already hold on file"
+				},
+				{
+					"id": "jev",
+					"label": "Jev",
+					"sub": "returns probabilities",
+					"accent": true
+				},
+				{
+					"id": "bill",
+					"label": "Route to billing",
+					"accent": true
+				},
+				{
+					"id": "rev",
+					"label": "Human review"
+				}
+			],
+			"edges": [
+				{
+					"from": "in",
+					"to": "jev"
+				},
+				{
+					"from": "jev",
+					"to": "billing",
+					"label": "0.90 or more"
+				},
+				{
+					"from": "jev",
+					"to": "rev",
+					"label": "under 0.90"
+				}
+			]
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/nodes: 2 nodes have accent=true, max 1 (jev, bill). Keep it on the node the title is about.",
+				"/edges/1/to: unknown node \"billing\". Known ids: in, jev, bill, rev."
+			],
+			"shown": [
+				"/nodes/0/sub: 48 chars, max 32 — shortened to \"plus the account details we…\" (the full text is kept as a tooltip)."
+			]
+		},
+		"final": {
+			"status": "degraded",
+			"notes": [
+				"1 edge dropped: unknown nodes",
+				"1 extra accent removed"
+			],
+			"drawn": {
+				"nodes": 4,
+				"edges": 2,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "trailing-commas-and-comments",
+		"why": "Models write JSON5: comments and a comma after the last item.",
+		"input": "{\n  \"title\": \"Requests are cached before they are routed\", // the takeaway\n  \"nodes\": [\n    {\"id\": \"a\", \"label\": \"Request\"},\n    {\"id\": \"b\", \"label\": \"Cache\"},\n  ],\n  \"edges\": [{\"from\": \"a\", \"to\": \"b\"},],\n}",
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"lenient-json"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "fenced",
+		"why": "A spec pasted inside a Markdown fence.",
+		"input": "```json\n{\"title\":\"One step\",\"nodes\":[{\"id\":\"a\",\"label\":\"A\"}],\"edges\":[]}\n```",
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"lenient-json"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 1,
+				"edges": 0,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "single-quotes-bare-keys",
+		"why": "JavaScript object literal instead of JSON.",
+		"input": "{ title: 'It is a two-step flow', nodes: [{ id: 'a', label: 'Parse' }, { id: 'b', label: 'Don\\'t retry' }], edges: [{ from: 'a', to: 'b' }] }",
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"lenient-json"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "smart-quotes",
+		"why": "Typographic quotes from a chat UI.",
+		"input": "{“title”: “Two boxes”, “nodes”: [{“id”: “a”, “label”: “A”}, {“id”: “b”, “label”: “B”}], “edges”: [{“from”: “a”, “to”: “b”}]}",
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"lenient-json"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "python-literals",
+		"why": "True/False/None from a Python-flavoured model.",
+		"input": "{\"title\": \"One accent\", \"nodes\": [{\"id\": \"a\", \"label\": \"A\", \"accent\": True}, {\"id\": \"b\", \"label\": \"B\", \"accent\": False, \"sub\": None}], \"edges\": []}",
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"lenient-json"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 2,
+				"edges": 0,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "truncated-mid-string",
+		"why": "The model hit max_tokens inside a label. Never repaired: re-requested.",
+		"input": "{\"title\":\"Cut off\",\"nodes\":[{\"id\":\"a\",\"label\":\"A\"},{\"id\":\"b\",\"la",
+		"first": {
+			"status": "truncated",
+			"errors": [
+				"/: the spec was cut off before it was complete."
+			]
+		},
+		"final": {
+			"status": "truncated"
+		}
+	},
+	{
+		"name": "truncated-mid-array",
+		"why": "The model hit max_tokens between nodes.",
+		"input": "{\"title\":\"Cut off\",\"nodes\":[{\"id\":\"a\",\"label\":\"A\"},",
+		"first": {
+			"status": "truncated",
+			"errors": [
+				"/: the spec was cut off before it was complete."
+			]
+		},
+		"final": {
+			"status": "truncated"
+		}
+	},
+	{
+		"name": "wrapped-in-spec",
+		"why": "The arguments arrive nested under a \"spec\" key.",
+		"input": {
+			"spec": {
+				"v": 1,
+				"title": "Jev classifies; your code decides the action",
+				"direction": "right",
+				"nodes": [
+					{
+						"id": "in",
+						"label": "Customer message",
+						"sub": "plus account details"
+					},
+					{
+						"id": "jev",
+						"label": "Jev",
+						"sub": "returns probabilities",
+						"accent": true
+					},
+					{
+						"id": "bill",
+						"label": "Route to billing"
+					},
+					{
+						"id": "rev",
+						"label": "Human review"
+					}
+				],
+				"edges": [
+					{
+						"from": "in",
+						"to": "jev"
+					},
+					{
+						"from": "jev",
+						"to": "bill",
+						"label": "0.90 or more"
+					},
+					{
+						"from": "jev",
+						"to": "rev",
+						"label": "under 0.90"
+					}
+				]
+			}
+		},
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"unwrapped"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 4,
+				"edges": 3,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "stringified",
+		"why": "The whole spec arrives as one JSON string.",
+		"input": "{\"v\":1,\"title\":\"Jev classifies; your code decides the action\",\"direction\":\"right\",\"nodes\":[{\"id\":\"in\",\"label\":\"Customer message\",\"sub\":\"plus account details\"},{\"id\":\"jev\",\"label\":\"Jev\",\"sub\":\"returns probabilities\",\"accent\":true},{\"id\":\"bill\",\"label\":\"Route to billing\"},{\"id\":\"rev\",\"label\":\"Human review\"}],\"edges\":[{\"from\":\"in\",\"to\":\"jev\"},{\"from\":\"jev\",\"to\":\"bill\",\"label\":\"0.90 or more\"},{\"from\":\"jev\",\"to\":\"rev\",\"label\":\"under 0.90\"}]}",
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"stringified"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 4,
+				"edges": 3,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "stringified-inside-wrapper",
+		"why": "Both at once: {\"diagram\": \"<json>\"}.",
+		"input": {
+			"diagram": "{\"v\":1,\"title\":\"Jev classifies; your code decides the action\",\"direction\":\"right\",\"nodes\":[{\"id\":\"in\",\"label\":\"Customer message\",\"sub\":\"plus account details\"},{\"id\":\"jev\",\"label\":\"Jev\",\"sub\":\"returns probabilities\",\"accent\":true},{\"id\":\"bill\",\"label\":\"Route to billing\"},{\"id\":\"rev\",\"label\":\"Human review\"}],\"edges\":[{\"from\":\"in\",\"to\":\"jev\"},{\"from\":\"jev\",\"to\":\"bill\",\"label\":\"0.90 or more\"},{\"from\":\"jev\",\"to\":\"rev\",\"label\":\"under 0.90\"}]}"
+		},
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"stringified",
+				"unwrapped"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 4,
+				"edges": 3,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "shape-synonyms",
+		"why": "Mermaid and draw.io vocabulary for shapes.",
+		"input": {
+			"title": "Shapes by any other name",
+			"nodes": [
+				{
+					"id": "a",
+					"label": "User",
+					"shape": "person"
+				},
+				{
+					"id": "b",
+					"label": "Valid?",
+					"shape": "diamond"
+				},
+				{
+					"id": "c",
+					"label": "Orders",
+					"shape": "database"
+				},
+				{
+					"id": "d",
+					"label": "Step",
+					"shape": "rectangle"
+				},
+				{
+					"id": "e",
+					"label": "Blob",
+					"shape": "hexagon"
+				}
+			],
+			"edges": [
+				{
+					"from": "a",
+					"to": "b"
+				},
+				{
+					"from": "b",
+					"to": "c"
+				},
+				{
+					"from": "b",
+					"to": "d"
+				},
+				{
+					"from": "d",
+					"to": "e"
+				}
+			]
+		},
+		"first": {
+			"status": "fixed",
+			"shown": [
+				"/nodes/4/shape: \"hexagon\" is not a shape; drew a box."
+			],
+			"tidied": [
+				"synonym"
+			]
+		},
+		"final": {
+			"status": "fixed",
+			"drawn": {
+				"nodes": 5,
+				"edges": 4,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "direction-synonyms",
+		"why": "Graphviz rankdir.",
+		"input": {
+			"title": "Top to bottom",
+			"rankdir": "TB",
+			"nodes": [
+				{
+					"id": "a",
+					"label": "A"
+				},
+				{
+					"id": "b",
+					"label": "B"
+				}
+			],
+			"edges": [
+				{
+					"from": "a",
+					"to": "b"
+				}
+			]
+		},
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"synonym"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "nodes-as-map",
+		"why": "Nodes keyed by id instead of listed.",
+		"input": {
+			"title": "A map of nodes",
+			"nodes": {
+				"api": {
+					"label": "API"
+				},
+				"db": {
+					"label": "Postgres",
+					"shape": "store"
+				}
+			},
+			"edges": [
+				{
+					"from": "api",
+					"to": "db"
+				}
+			]
+		},
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"coerced"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "edges-as-pairs-and-arrows",
+		"why": "Three ways to write an edge that are not {from,to}.",
+		"input": {
+			"title": "Edges written three ways",
+			"nodes": [
+				{
+					"id": "a",
+					"label": "A"
+				},
+				{
+					"id": "b",
+					"label": "B"
+				},
+				{
+					"id": "c",
+					"label": "C"
+				},
+				{
+					"id": "d",
+					"label": "D"
+				}
+			],
+			"edges": [
+				[
+					"a",
+					"b"
+				],
+				"b -> c: next",
+				{
+					"source": "c",
+					"target": "d",
+					"style": "dotted"
+				}
+			]
+		},
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"coerced",
+				"renamed-field",
+				"synonym"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 4,
+				"edges": 3,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "edge-names-a-label",
+		"why": "An edge points at a node by its label, not its id. One node has that label, so this is a lookup.",
+		"input": {
+			"title": "The edge names the label",
+			"nodes": [
+				{
+					"id": "n1",
+					"label": "Load balancer"
+				},
+				{
+					"id": "n2",
+					"label": "API server"
+				}
+			],
+			"edges": [
+				{
+					"from": "Load balancer",
+					"to": "API server"
+				}
+			]
+		},
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"ref-by-label"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "ids-not-slugs",
+		"why": "Ids with capitals and spaces; edges use the same spelling.",
+		"input": {
+			"title": "Ids that need tidying",
+			"nodes": [
+				{
+					"id": "Auth Service",
+					"label": "Auth"
+				},
+				{
+					"id": "DB_Main",
+					"label": "Database",
+					"shape": "store"
+				}
+			],
+			"edges": [
+				{
+					"from": "Auth Service",
+					"to": "DB_Main"
+				}
+			]
+		},
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"slug"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "label-too-long",
+		"why": "The most common violation: a label over 28 characters.",
+		"input": {
+			"title": "Long labels are shortened, not rejected",
+			"nodes": [
+				{
+					"id": "a",
+					"label": "Validate the incoming request payload"
+				},
+				{
+					"id": "b",
+					"label": "Store"
+				}
+			],
+			"edges": [
+				{
+					"from": "a",
+					"to": "b",
+					"label": "when every field checks out"
+				}
+			]
+		},
+		"first": {
+			"status": "fixed",
+			"shown": [
+				"/nodes/0/label: 37 chars, max 28 — shortened to \"Validate the incoming…\" (the full text is kept as a tooltip).",
+				"/edges/0/label: 27 chars, max 20 — shortened to \"when every field…\" (the full text is kept as a tooltip)."
+			]
+		},
+		"final": {
+			"status": "fixed",
+			"notes": [
+				"2 labels shortened"
+			],
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "two-line-label",
+		"why": "Label and sub written as one string with a newline.",
+		"input": {
+			"title": "One field, two lines",
+			"nodes": [
+				{
+					"id": "jev",
+					"label": "Jev\nreturns probabilities"
+				}
+			],
+			"edges": []
+		},
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"split-label"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 1,
+				"edges": 0,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "same-node-twice",
+		"why": "A node repeated verbatim.",
+		"input": {
+			"title": "Listed twice",
+			"nodes": [
+				{
+					"id": "a",
+					"label": "A"
+				},
+				{
+					"id": "a",
+					"label": "A"
+				},
+				{
+					"id": "b",
+					"label": "B"
+				}
+			],
+			"edges": [
+				{
+					"from": "a",
+					"to": "b"
+				}
+			]
+		},
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"duplicate-node"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "two-nodes-one-id",
+		"why": "Two different nodes share an id — which one do the edges mean? Only the model knows.",
+		"input": {
+			"title": "One id, two nodes",
+			"nodes": [
+				{
+					"id": "api",
+					"label": "Public API"
+				},
+				{
+					"id": "api",
+					"label": "Admin API"
+				},
+				{
+					"id": "db",
+					"label": "Postgres"
+				}
+			],
+			"edges": [
+				{
+					"from": "api",
+					"to": "db"
+				}
+			]
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/nodes/1/id: duplicate id \"api\" (already used by /nodes/0). Every node needs its own id."
+			]
+		},
+		"final": {
+			"status": "degraded",
+			"notes": [
+				"1 duplicate id renamed"
+			],
+			"drawn": {
+				"nodes": 3,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "fourteen-nodes",
+		"why": "Over the 12-node cap: the model must split it.",
+		"input": {
+			"title": "Too much for one picture",
+			"nodes": [
+				{
+					"id": "n0",
+					"label": "Step 1"
+				},
+				{
+					"id": "n1",
+					"label": "Step 2"
+				},
+				{
+					"id": "n2",
+					"label": "Step 3"
+				},
+				{
+					"id": "n3",
+					"label": "Step 4"
+				},
+				{
+					"id": "n4",
+					"label": "Step 5"
+				},
+				{
+					"id": "n5",
+					"label": "Step 6"
+				},
+				{
+					"id": "n6",
+					"label": "Step 7"
+				},
+				{
+					"id": "n7",
+					"label": "Step 8"
+				},
+				{
+					"id": "n8",
+					"label": "Step 9"
+				},
+				{
+					"id": "n9",
+					"label": "Step 10"
+				},
+				{
+					"id": "n10",
+					"label": "Step 11"
+				},
+				{
+					"id": "n11",
+					"label": "Step 12"
+				},
+				{
+					"id": "n12",
+					"label": "Step 13"
+				},
+				{
+					"id": "n13",
+					"label": "Step 14"
+				}
+			],
+			"edges": [
+				{
+					"from": "n0",
+					"to": "n1"
+				},
+				{
+					"from": "n1",
+					"to": "n2"
+				},
+				{
+					"from": "n2",
+					"to": "n3"
+				},
+				{
+					"from": "n3",
+					"to": "n4"
+				},
+				{
+					"from": "n4",
+					"to": "n5"
+				},
+				{
+					"from": "n5",
+					"to": "n6"
+				},
+				{
+					"from": "n6",
+					"to": "n7"
+				},
+				{
+					"from": "n7",
+					"to": "n8"
+				},
+				{
+					"from": "n8",
+					"to": "n9"
+				},
+				{
+					"from": "n9",
+					"to": "n10"
+				},
+				{
+					"from": "n10",
+					"to": "n11"
+				},
+				{
+					"from": "n11",
+					"to": "n12"
+				},
+				{
+					"from": "n12",
+					"to": "n13"
+				}
+			]
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/nodes: 14 nodes, max 12. Draw an overview, then one diagram per sub-flow."
+			]
+		},
+		"final": {
+			"status": "degraded",
+			"notes": [
+				"14 nodes — over the 12-node limit, drawn anyway"
+			],
+			"drawn": {
+				"nodes": 14,
+				"edges": 13,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "thirty-nodes",
+		"why": "Over the HARD ceiling: even a degraded diagram stops at 24.",
+		"input": {
+			"title": "Too much for one picture",
+			"nodes": [
+				{
+					"id": "n0",
+					"label": "Step 1"
+				},
+				{
+					"id": "n1",
+					"label": "Step 2"
+				},
+				{
+					"id": "n2",
+					"label": "Step 3"
+				},
+				{
+					"id": "n3",
+					"label": "Step 4"
+				},
+				{
+					"id": "n4",
+					"label": "Step 5"
+				},
+				{
+					"id": "n5",
+					"label": "Step 6"
+				},
+				{
+					"id": "n6",
+					"label": "Step 7"
+				},
+				{
+					"id": "n7",
+					"label": "Step 8"
+				},
+				{
+					"id": "n8",
+					"label": "Step 9"
+				},
+				{
+					"id": "n9",
+					"label": "Step 10"
+				},
+				{
+					"id": "n10",
+					"label": "Step 11"
+				},
+				{
+					"id": "n11",
+					"label": "Step 12"
+				},
+				{
+					"id": "n12",
+					"label": "Step 13"
+				},
+				{
+					"id": "n13",
+					"label": "Step 14"
+				},
+				{
+					"id": "n14",
+					"label": "Step 15"
+				},
+				{
+					"id": "n15",
+					"label": "Step 16"
+				},
+				{
+					"id": "n16",
+					"label": "Step 17"
+				},
+				{
+					"id": "n17",
+					"label": "Step 18"
+				},
+				{
+					"id": "n18",
+					"label": "Step 19"
+				},
+				{
+					"id": "n19",
+					"label": "Step 20"
+				},
+				{
+					"id": "n20",
+					"label": "Step 21"
+				},
+				{
+					"id": "n21",
+					"label": "Step 22"
+				},
+				{
+					"id": "n22",
+					"label": "Step 23"
+				},
+				{
+					"id": "n23",
+					"label": "Step 24"
+				},
+				{
+					"id": "n24",
+					"label": "Step 25"
+				},
+				{
+					"id": "n25",
+					"label": "Step 26"
+				},
+				{
+					"id": "n26",
+					"label": "Step 27"
+				},
+				{
+					"id": "n27",
+					"label": "Step 28"
+				},
+				{
+					"id": "n28",
+					"label": "Step 29"
+				},
+				{
+					"id": "n29",
+					"label": "Step 30"
+				}
+			],
+			"edges": [
+				{
+					"from": "n0",
+					"to": "n1"
+				},
+				{
+					"from": "n1",
+					"to": "n2"
+				},
+				{
+					"from": "n2",
+					"to": "n3"
+				},
+				{
+					"from": "n3",
+					"to": "n4"
+				},
+				{
+					"from": "n4",
+					"to": "n5"
+				},
+				{
+					"from": "n5",
+					"to": "n6"
+				},
+				{
+					"from": "n6",
+					"to": "n7"
+				},
+				{
+					"from": "n7",
+					"to": "n8"
+				},
+				{
+					"from": "n8",
+					"to": "n9"
+				},
+				{
+					"from": "n9",
+					"to": "n10"
+				},
+				{
+					"from": "n10",
+					"to": "n11"
+				},
+				{
+					"from": "n11",
+					"to": "n12"
+				},
+				{
+					"from": "n12",
+					"to": "n13"
+				},
+				{
+					"from": "n13",
+					"to": "n14"
+				},
+				{
+					"from": "n14",
+					"to": "n15"
+				},
+				{
+					"from": "n15",
+					"to": "n16"
+				},
+				{
+					"from": "n16",
+					"to": "n17"
+				},
+				{
+					"from": "n17",
+					"to": "n18"
+				},
+				{
+					"from": "n18",
+					"to": "n19"
+				},
+				{
+					"from": "n19",
+					"to": "n20"
+				},
+				{
+					"from": "n20",
+					"to": "n21"
+				},
+				{
+					"from": "n21",
+					"to": "n22"
+				},
+				{
+					"from": "n22",
+					"to": "n23"
+				},
+				{
+					"from": "n23",
+					"to": "n24"
+				},
+				{
+					"from": "n24",
+					"to": "n25"
+				},
+				{
+					"from": "n25",
+					"to": "n26"
+				},
+				{
+					"from": "n26",
+					"to": "n27"
+				},
+				{
+					"from": "n27",
+					"to": "n28"
+				},
+				{
+					"from": "n28",
+					"to": "n29"
+				}
+			]
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/nodes: 30 nodes, max 12. Draw an overview, then one diagram per sub-flow."
+			]
+		},
+		"final": {
+			"status": "degraded",
+			"notes": [
+				"6 nodes dropped: malformed or over the limit",
+				"24 nodes — over the 12-node limit, drawn anyway",
+				"6 edges dropped: no valid ends"
+			],
+			"drawn": {
+				"nodes": 24,
+				"edges": 23,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "two-accents",
+		"why": "More than one accent.",
+		"input": {
+			"v": 1,
+			"title": "Jev classifies; your code decides the action",
+			"direction": "right",
+			"nodes": [
+				{
+					"id": "in",
+					"label": "Customer message",
+					"sub": "plus account details",
+					"accent": true
+				},
+				{
+					"id": "jev",
+					"label": "Jev",
+					"sub": "returns probabilities",
+					"accent": true
+				},
+				{
+					"id": "bill",
+					"label": "Route to billing"
+				},
+				{
+					"id": "rev",
+					"label": "Human review"
+				}
+			],
+			"edges": [
+				{
+					"from": "in",
+					"to": "jev"
+				},
+				{
+					"from": "jev",
+					"to": "bill",
+					"label": "0.90 or more"
+				},
+				{
+					"from": "jev",
+					"to": "rev",
+					"label": "under 0.90"
+				}
+			]
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/nodes: 2 nodes have accent=true, max 1 (in, jev). Keep it on the node the title is about."
+			]
+		},
+		"final": {
+			"status": "degraded",
+			"notes": [
+				"1 extra accent removed"
+			],
+			"drawn": {
+				"nodes": 4,
+				"edges": 3,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "groups-three-deep",
+		"why": "Nesting past depth 2.",
+		"input": {
+			"title": "Nested too deep",
+			"groups": [
+				{
+					"id": "a",
+					"label": "Cloud"
+				},
+				{
+					"id": "b",
+					"label": "Region",
+					"parent": "a"
+				},
+				{
+					"id": "c",
+					"label": "Zone",
+					"parent": "b"
+				}
+			],
+			"nodes": [
+				{
+					"id": "x",
+					"label": "VM",
+					"group": "c"
+				},
+				{
+					"id": "y",
+					"label": "LB",
+					"group": "a"
+				}
+			],
+			"edges": [
+				{
+					"from": "y",
+					"to": "x"
+				}
+			]
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/groups/2/parent: nested 3 deep, max 2. Flatten it."
+			]
+		},
+		"final": {
+			"status": "degraded",
+			"notes": [
+				"1 group flattened: nested too deep"
+			],
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 2
+			}
+		}
+	},
+	{
+		"name": "groups-in-a-circle",
+		"why": "a contains b contains a.",
+		"input": {
+			"title": "Groups in a circle",
+			"groups": [
+				{
+					"id": "a",
+					"label": "A",
+					"parent": "b"
+				},
+				{
+					"id": "b",
+					"label": "B",
+					"parent": "a"
+				}
+			],
+			"nodes": [
+				{
+					"id": "x",
+					"label": "X",
+					"group": "a"
+				},
+				{
+					"id": "y",
+					"label": "Y",
+					"group": "b"
+				}
+			],
+			"edges": [
+				{
+					"from": "x",
+					"to": "y"
+				}
+			]
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/groups/0/parent: groups contain each other in a circle (\"a\" → \"b\" → …). Nesting must be a tree.",
+				"/groups/1/parent: groups contain each other in a circle (\"b\" → \"a\" → …). Nesting must be a tree."
+			]
+		},
+		"final": {
+			"status": "degraded",
+			"notes": [
+				"group references that did not resolve were removed"
+			],
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 2
+			}
+		}
+	},
+	{
+		"name": "unknown-group",
+		"why": "A node names a group that was never declared.",
+		"input": {
+			"title": "A group that is not there",
+			"groups": [
+				{
+					"id": "edge",
+					"label": "Edge"
+				}
+			],
+			"nodes": [
+				{
+					"id": "x",
+					"label": "CDN",
+					"group": "edge"
+				},
+				{
+					"id": "y",
+					"label": "API",
+					"group": "backend"
+				}
+			],
+			"edges": [
+				{
+					"from": "x",
+					"to": "y"
+				}
+			]
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/nodes/1/group: unknown group \"backend\". Known groups: edge."
+			]
+		},
+		"final": {
+			"status": "degraded",
+			"notes": [
+				"group references that did not resolve were removed"
+			],
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 1
+			}
+		}
+	},
+	{
+		"name": "no-title",
+		"why": "The takeaway is missing.",
+		"input": {
+			"nodes": [
+				{
+					"id": "a",
+					"label": "A"
+				}
+			],
+			"edges": []
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/title: missing. This field is required."
+			]
+		},
+		"final": {
+			"status": "degraded",
+			"notes": [
+				"no title given"
+			],
+			"drawn": {
+				"nodes": 1,
+				"edges": 0,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "no-nodes",
+		"why": "Nothing to draw.",
+		"input": {
+			"title": "Empty",
+			"nodes": [],
+			"edges": []
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/nodes: 0 nodes, min 1."
+			]
+		},
+		"final": {
+			"status": "failed"
+		}
+	},
+	{
+		"name": "not-json",
+		"why": "Prose where a spec should be.",
+		"input": "I would draw a box that points at another box.",
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/: not valid JSON (no JSON object found). Send one JSON object with \"title\", \"nodes\" and \"edges\"."
+			]
+		},
+		"final": {
+			"status": "failed"
+		}
+	},
+	{
+		"name": "nodes-not-a-list",
+		"why": "A scalar where the node list should be.",
+		"input": {
+			"title": "Wrong type",
+			"nodes": "a, b, c",
+			"edges": []
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/nodes: expected an array, got string."
+			]
+		},
+		"final": {
+			"status": "failed"
+		}
+	},
+	{
+		"name": "future-version",
+		"why": "A spec from a newer editor, read back from a saved session.",
+		"input": {
+			"v": 3,
+			"title": "Jev classifies; your code decides the action",
+			"direction": "right",
+			"nodes": [
+				{
+					"id": "in",
+					"label": "Customer message",
+					"sub": "plus account details"
+				},
+				{
+					"id": "jev",
+					"label": "Jev",
+					"sub": "returns probabilities",
+					"accent": true
+				},
+				{
+					"id": "bill",
+					"label": "Route to billing"
+				},
+				{
+					"id": "rev",
+					"label": "Human review"
+				}
+			],
+			"edges": [
+				{
+					"from": "in",
+					"to": "jev"
+				},
+				{
+					"from": "jev",
+					"to": "bill",
+					"label": "0.90 or more"
+				},
+				{
+					"from": "jev",
+					"to": "rev",
+					"label": "under 0.90"
+				}
+			]
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/v: unknown schema version 3. This editor reads: 1."
+			]
+		},
+		"final": {
+			"status": "degraded",
+			"notes": [
+				"written for schema v3; drawn as v1"
+			],
+			"drawn": {
+				"nodes": 4,
+				"edges": 3,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "hostile-text",
+		"why": "Markup, control characters and a bidi override in labels. They are TEXT: kept as written, minus the invisible ones.",
+		"input": {
+			"title": "<script>alert(1)</script>",
+			"nodes": [
+				{
+					"id": "a",
+					"label": "\"><img src=x onerror=alert(1)>"
+				},
+				{
+					"id": "b",
+					"label": "safe‮gnp.exe",
+					"sub": "bell\u0007 and ​zero width"
+				}
+			],
+			"edges": [
+				{
+					"from": "a",
+					"to": "b",
+					"label": "</text><script>"
+				}
+			]
+		},
+		"first": {
+			"status": "fixed",
+			"shown": [
+				"/nodes/0/label: 30 chars, max 28 — shortened to \"\\\"><img src=x onerror=alert…\" (the full text is kept as a tooltip)."
+			]
+		},
+		"final": {
+			"status": "fixed",
+			"notes": [
+				"1 label shortened"
+			],
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "links-three-ways",
+		"why": "A link as an object, as path:line, as path#symbol.",
+		"input": {
+			"title": "Links",
+			"nodes": [
+				{
+					"id": "a",
+					"label": "Agent",
+					"link": {
+						"path": "agent.js",
+						"symbol": "runAgent"
+					}
+				},
+				{
+					"id": "b",
+					"label": "Loop",
+					"link": "agent.js:890"
+				},
+				{
+					"id": "c",
+					"label": "Tool",
+					"link": "agent.js#runTool"
+				},
+				{
+					"id": "d",
+					"label": "File",
+					"file": "file:///etc/passwd"
+				}
+			],
+			"edges": [
+				{
+					"from": "a",
+					"to": "b"
+				},
+				{
+					"from": "b",
+					"to": "c"
+				},
+				{
+					"from": "c",
+					"to": "d"
+				}
+			]
+		},
+		"first": {
+			"status": "ok"
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 4,
+				"edges": 3,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "prototype-keys",
+		"why": "A spec that tries to reach Object.prototype.",
+		"input": "{\"title\":\"Proto\",\"__proto__\":{\"polluted\":true},\"constructor\":{\"prototype\":{\"polluted\":true}},\"nodes\":[{\"id\":\"a\",\"label\":\"A\",\"__proto__\":{\"x\":1}}],\"edges\":[]}",
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"stringified",
+				"unknown-field"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 1,
+				"edges": 0,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "self-loop-and-back-edge",
+		"why": "A state machine: a retry loop and an edge back to the start.",
+		"input": {
+			"title": "Retries stay inside the worker",
+			"nodes": [
+				{
+					"id": "q",
+					"label": "Queued"
+				},
+				{
+					"id": "run",
+					"label": "Running",
+					"accent": true
+				},
+				{
+					"id": "ok",
+					"label": "Done"
+				}
+			],
+			"edges": [
+				{
+					"from": "q",
+					"to": "run"
+				},
+				{
+					"from": "run",
+					"to": "run",
+					"label": "retry"
+				},
+				{
+					"from": "run",
+					"to": "ok"
+				},
+				{
+					"from": "ok",
+					"to": "q",
+					"label": "reschedule",
+					"style": "dashed"
+				}
+			]
+		},
+		"first": {
+			"status": "ok"
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 3,
+				"edges": 4,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "edge-to-nowhere-and-missing-end",
+		"why": "One edge names a node that does not exist; another has no \"to\".",
+		"input": {
+			"title": "Edges that lead nowhere",
+			"nodes": [
+				{
+					"id": "a",
+					"label": "A"
+				},
+				{
+					"id": "b",
+					"label": "B"
+				}
+			],
+			"edges": [
+				{
+					"from": "a",
+					"to": "b"
+				},
+				{
+					"from": "a",
+					"to": "c"
+				},
+				{
+					"from": "b"
+				}
+			]
+		},
+		"first": {
+			"status": "errors",
+			"errors": [
+				"/edges/2/to: missing. This field is required.",
+				"/edges/1/to: unknown node \"c\". Known ids: a, b."
+			]
+		},
+		"final": {
+			"status": "degraded",
+			"notes": [
+				"1 edge dropped: unknown nodes",
+				"1 edge dropped: no valid ends"
+			],
+			"drawn": {
+				"nodes": 2,
+				"edges": 1,
+				"groups": 0
+			}
+		}
+	},
+	{
+		"name": "empty-group",
+		"why": "A declared group with nothing in it is simply not drawn.",
+		"input": {
+			"title": "An empty container",
+			"groups": [
+				{
+					"id": "used",
+					"label": "Used"
+				},
+				{
+					"id": "unused",
+					"label": "Unused"
+				}
+			],
+			"nodes": [
+				{
+					"id": "a",
+					"label": "A",
+					"group": "used"
+				}
+			],
+			"edges": []
+		},
+		"first": {
+			"status": "ok",
+			"tidied": [
+				"empty-group"
+			]
+		},
+		"final": {
+			"status": "ok",
+			"drawn": {
+				"nodes": 1,
+				"edges": 0,
+				"groups": 1
+			}
+		}
+	}
+]

From fb2e67ab3c130647188783d39d92994f299af59d Mon Sep 17 00:00:00 2001
From: Sergii Demianchuk <sergeydemjanchyk@gmail.com>
Date: Mon, 5 Oct 2026 00:27:01 -0400
Subject: [PATCH 4/9] =?UTF-8?q?feat(diagrams):=20layout=20=E2=80=94=20laye?=
 =?UTF-8?q?red,=20with=20orthogonal=20connectors,=20in=20one=20house=20sty?=
 =?UTF-8?q?le?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

  diagram/theme.js    the style guide as numbers: title 15, node name 13
                      semibold, second lines and edge labels 11.5, nothing
                      under 10.5; radius 8, border 1.25, padding 12; groups
                      inset 16; the accent a low-opacity fill and a 2px border.
                      Colours are editor theme tokens, with two fixed palettes
                      for exported files.
  diagram/layout.js   layout(spec, opts) gives geometry; inspect(geometry) lists
                      whatever overlaps, overflows or leaves the frame.

The spec names ELK.js. This is not ELK: ELK is EPL-2.0 in a repository that is
otherwise MIT-clean, about 1.5 MB, and this extension has no build step. The
spec's own open question asks whether a simpler layered layout is needed as a
fallback; this is that layout, as the only one. layout() is the single entry
point, so ELK can replace it without touching anything else.

What it does: ranks by longest path; crossings reduced by sweeps; positions
across the flow solved as constraints and then lined up by medians; a port per
edge; a track per connector in each gap, so lines cross but never run along
each other; and each edge label placed BESIDE its line, scored against nodes,
lines and other labels. A flow asked for left-to-right that will not fit its
column is laid out top-to-bottom instead.

A group's name sits in the top-left of its frame — which, when the flow runs
down, is exactly where lines come in. No connector runs through it. The name
slides along the frame to the nearest clear stretch; if there is none and the
lines have under 72px to move, they are moved to the far side of the name (the
frame grows by that much, never past the column); otherwise the name stays and
is marked to be drawn over the line.

Measured over 6,000 random specs at the model-facing limits: no node overlaps
another, no connector crosses a node or an unbacked group name, nothing leaves
the frame. Three known limits, each bounded in the suite so it cannot quietly
get worse:

  an edge label that falls back to a halo over a line   6.5% of specs
  two connectors that swap lanes in one gap             0.3%
  a group's name with a connector behind it             2.7% of specs with groups

None of the nine gallery diagrams (fixtures/diagrams/gallery.json) shows any of
the three, at its natural width or at 560, 420 and 320px. The twelve-node one
lays out in under a millisecond once warm; the slowest of the 6,000 took 7ms.

diagramLayout (23 tests, one of them a 1,500-spec fuzz).
---
 extensions/levelcode-ai/diagram/layout.js     | 1317 +++++++++++++++++
 extensions/levelcode-ai/diagram/theme.js      |  198 +++
 .../levelcode-ai/test/diagramLayout.test.js   |  432 ++++++
 .../test/fixtures/diagrams/gallery.json       |  569 +++++++
 4 files changed, 2516 insertions(+)
 create mode 100644 extensions/levelcode-ai/diagram/layout.js
 create mode 100644 extensions/levelcode-ai/diagram/theme.js
 create mode 100644 extensions/levelcode-ai/test/diagramLayout.test.js
 create mode 100644 extensions/levelcode-ai/test/fixtures/diagrams/gallery.json

diff --git a/extensions/levelcode-ai/diagram/layout.js b/extensions/levelcode-ai/diagram/layout.js
new file mode 100644
index 0000000..5b8ad86
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/layout.js
@@ -0,0 +1,1317 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · layout  (docs/RICH-DIAGRAMS.md, "Architecture" + "Style guide")
+ *
+ *  Turns a validated Graph JSON spec into geometry: where every box sits, the route every connector
+ *  takes, and where each label goes. The model never supplies a coordinate; this file supplies all
+ *  of them, the same way every time — which is the whole reason a diagram looks the same whichever
+ *  model asked for it.
+ *
+ *  It is a layered ("Sugiyama") layout with orthogonal routing, written for the house rules:
+ *
+ *    rank      nodes are placed in columns (or rows) along the flow; cycles are broken first, and the
+ *              edge that closes one is drawn running back
+ *    order     within a rank, positions are chosen to minimise crossings — with every group kept
+ *              contiguous, and sibling groups in one consistent order so their frames never interleave
+ *    place     positions across the flow come from a small constraint system (nothing overlaps,
+ *              every group owns one band through all the ranks it spans) relaxed until connected
+ *              things line up
+ *    route     connectors leave and enter on the sides that face the flow, each on its own port, and
+ *              turn in their own track in the gap between ranks — so lines run THROUGH GAPS and
+ *              never share a segment
+ *    label     an edge label is placed BESIDE its line, on the best spot that touches nothing else;
+ *              the gap it needs is reserved before routing rather than hoped for after
+ *
+ *  WHY NOT ELK.js (the spec names it): ELK is EPL-2.0 and a ~1.5 MB bundle. This extension is
+ *  MIT-clean, plain JS and dependency-free (CLAUDE.md, "Conventions"), and the spec's own open
+ *  question allows "a simpler layered layout". With a 12-node cap the problem is small enough to do
+ *  directly. layout(spec, opts) is the entire interface, so swapping ELK in later touches one call.
+ *
+ *  Everything is computed on two abstract axes — M, along the flow, and C, across it — and mapped to
+ *  x/y at the very end, so `direction: "down"` is the same code as `"right"`, not a second copy.
+ *
+ *  Pure and deterministic: no randomness, no clock, no DOM. Text is measured by an injected
+ *  `measure(text, role)` — a canvas in the webview, theme.approxMeasure in Node.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+(function (root, factory) {
+	'use strict';
+	if (typeof module === 'object' && module.exports) { module.exports = factory(require('./theme')); }
+	else { (root.LCDiagram = root.LCDiagram || {}).layout = factory(root.LCDiagram.theme); }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function (theme) {
+	'use strict';
+
+	/** Two cross coordinates this close are "the same line": the connector between them is drawn straight. */
+	const STRAIGHT = 1.0;
+	const r2 = (v) => Math.round(v * 100) / 100;
+
+	// ---- node sizes -----------------------------------------------------------------------------
+
+	/** Split a decision's label into two balanced lines when it is long enough to make the diamond sprawl. */
+	function wrapTwo(text, measure, role) {
+		const words = String(text).split(' ');
+		if (words.length < 2 || Array.from(text).length <= 14) { return [text]; }
+		let best = null;
+		for (let i = 1; i < words.length; i++) {
+			const a = words.slice(0, i).join(' '), b = words.slice(i).join(' ');
+			const w = Math.max(measure(a, role), measure(b, role));
+			if (!best || w < best.w) { best = { w, lines: [a, b] }; }
+		}
+		return best ? best.lines : [text];
+	}
+
+	/**
+	 * The size of a node and the lines of text inside it, in screen terms (w across, h down).
+	 * "Width from the measured longest line plus 24" — plus whatever the shape itself needs.
+	 */
+	function nodeSize(node, measure, T, B) {
+		const shape = node.shape || 'box';
+		const nameLines = shape === 'decision' ? wrapTwo(node.label, measure, 'name') : [node.label];
+		const lines = nameLines.map((t) => ({ text: t, role: 'name', w: measure(t, 'name'), h: T.name.line }));
+		if (node.sub) { lines.push({ text: node.sub, role: 'sub', w: measure(node.sub, 'sub'), h: T.sub.line }); }
+		const textW = Math.max.apply(null, lines.map((l) => l.w));
+		const textH = lines.reduce((s, l) => s + l.h, 0) + (node.sub ? B.textGap : 0);
+		const link = node.link ? B.linkIcon : 0;
+		let w, h, textDy = 0;
+		if (shape === 'decision') {
+			// A rhombus with half-diagonals a (across) and b (down) contains a line of half-width hw whose
+			// far edge is `far` from the centre when hw/a + far/b <= 1. Fit EACH line rather than the
+			// block's bounding box — a short line near a tip needs far less room than the widest one —
+			// and take the smallest diamond that is neither a sliver nor a square.
+			let yy = -textH / 2;
+			const rows = lines.map((l, i) => {
+				if (l.role === 'sub' && i > 0) { yy += B.textGap; }
+				const far = Math.max(Math.abs(yy), Math.abs(yy + l.h)) + 3;
+				yy += l.h;
+				return { hw: l.w / 2 + 6 + (i === 0 ? link : 0), far };
+			});
+			const farMax = Math.max.apply(null, rows.map((rw) => rw.far));
+			let best = null;
+			for (let b = farMax * 1.2; b <= farMax * 3.2; b += 1) {
+				const a = Math.max.apply(null, rows.map((rw) => rw.hw / (1 - rw.far / b)));
+				const ratio = a / b;
+				if (ratio < 1.35 || ratio > 3.1) { continue; }
+				if (!best || a * b < best.a * best.b) { best = { a, b }; }
+			}
+			if (!best) { const b = farMax * 2; best = { a: Math.max.apply(null, rows.map((rw) => rw.hw / (1 - rw.far / b))), b }; }
+			w = Math.ceil(2 * best.a); h = Math.ceil(2 * best.b);
+		} else if (shape === 'store') {
+			const cap = B.storeCap != null ? B.storeCap : 6;
+			w = Math.max(B.minWidth, Math.ceil(textW + 2 * B.padX + link));
+			h = Math.ceil(textH + 2 * B.padY + cap);
+			textDy = cap / 2;                                         // the lid pushes the text down a little
+		} else if (shape === 'actor') {
+			h = Math.ceil(textH + 2 * B.padY);
+			w = Math.max(B.minWidth, Math.ceil(textW + 2 * B.padX + link + h * 0.3));   // room for the round ends
+		} else {
+			w = Math.max(B.minWidth, Math.ceil(textW + 2 * B.padX + link));
+			h = Math.ceil(textH + 2 * B.padY);
+		}
+		return { shape, w, h, lines, textH, textDy };
+	}
+
+	/**
+	 * How far the outline is from the node's centre, measured along `axis`, at offset `off` on the
+	 * other axis. Connectors stop ON the outline, so a line into a diamond meets its slanted edge
+	 * rather than floating at the corner of its bounding box.
+	 * @param {{shape:string, w:number, h:number}} n  screen size
+	 * @param {'x'|'y'} axis
+	 */
+	function outline(n, axis, off, B) {
+		const hw = n.w / 2, hh = n.h / 2, a = Math.abs(off);
+		if (n.shape === 'decision') {
+			return axis === 'x' ? hw * Math.max(0, 1 - a / hh) : hh * Math.max(0, 1 - a / hw);
+		}
+		if (n.shape === 'actor') {
+			const r = Math.min(hw, hh);                                // the pill's end radius
+			if (axis === 'x') { return hw - r + Math.sqrt(Math.max(0, r * r - Math.min(a, r) * Math.min(a, r))); }
+			const d = a - (hw - r);
+			return d <= 0 ? hh : Math.sqrt(Math.max(0, r * r - Math.min(d, r) * Math.min(d, r)));
+		}
+		if (n.shape === 'store' && axis === 'y') {
+			const cap = B.storeCap != null ? B.storeCap : 6;
+			const t = Math.min(1, a / hw);
+			return hh - cap * (1 - Math.sqrt(1 - t * t));
+		}
+		return axis === 'x' ? hw : hh;
+	}
+	/** How much of a side connectors may spread over, by shape (kept off corners and slants). */
+	function portSpan(n, sideLen, S) {
+		if (n.shape === 'decision') { return sideLen * 0.5; }
+		if (n.shape === 'actor') { return Math.max(0, sideLen * 0.55); }
+		return Math.max(0, sideLen - 2 * S.portInset);
+	}
+
+	/** The least distance between a connector and a group's name. */
+	const NAME_CLEAR = 6;
+	/** How far a group's incoming lines may be moved aside to clear its name before a backed name is the better picture. */
+	const NAME_ROOM = 72;
+
+	// ---- the layout -----------------------------------------------------------------------------
+
+	/**
+	 * @param {any} spec  a spec that passed validate() (or repair.accept())
+	 * @param {{ measure?: (text:string, role:string)=>number, maxWidth?: number,
+	 *           space?: object, box?: object, type?: object }} [opts]
+	 * @returns geometry — see the bottom of layoutOnce()
+	 */
+	function layout(spec, opts) {
+		const o = opts || {};
+		const asked = spec.direction === 'down' ? 'down' : 'right';
+		let geo = layoutDir(spec, asked, o);
+		// "Diagrams grow downward, never wider than the chat column." A flow that was asked for
+		// left-to-right but cannot fit is laid out top-to-bottom instead, when that actually helps.
+		if (o.maxWidth && asked === 'right' && geo.width > o.maxWidth) {
+			const down = layoutDir(spec, 'down', o);
+			if (down.width <= o.maxWidth || down.width < geo.width * 0.8) { down.flipped = true; geo = down; }
+		}
+		geo.asked = asked;
+		return geo;
+	}
+
+	/**
+	 * One direction, laid out — and, when the flow runs down, laid out again if a group's name was left
+	 * with a connector behind it. A name is first slid along its frame to a clear stretch, which costs
+	 * nothing. Where the frame has no such stretch, room can be MADE: the group's incoming lines are
+	 * kept to the far side of its name, which widens the frame by however far the lines have to move.
+	 * That is worth a little width and not a lot — a frame half empty under a long name reads worse
+	 * than a line passing behind the name — so it is done only for groups where the lines have less
+	 * than NAME_ROOM to move, and kept only if the drawing still fits its column. The rest keep their
+	 * backed name.
+	 */
+	function layoutDir(spec, dir, o) {
+		let best = layoutOnce(spec, dir, o, null);
+		if (dir !== 'down') { return tidy(best); }
+		const reserve = new Set();
+		for (let pass = 0; pass < 2; pass++) {
+			const more = best.groups.filter((g) => g.labelHalo && !reserve.has(g.id) && g.labelNeed <= NAME_ROOM);
+			if (!more.length) { break; }
+			more.forEach((g) => reserve.add(g.id));
+			const next = layoutOnce(spec, dir, o, reserve);
+			// Kept unless the result is wider than its column: a name is not worth shrinking the whole drawing.
+			if (o.maxWidth && next.width > o.maxWidth) { break; }
+			best = next;
+		}
+		return tidy(best);
+	}
+
+	/** @param {Set<string>|null} reserve  groups whose incoming lines must keep clear of the name (see layoutDir) */
+	function layoutOnce(spec, dir, o, reserve) {
+		const T = Object.assign({}, theme.TYPE, o.type);
+		const B = Object.assign({}, theme.BOX, o.box);
+		const S = Object.assign({}, theme.SPACE, o.space);
+		const measure = o.measure || theme.approxMeasure;
+		const right = dir === 'right';
+		const warnings = [];
+
+		// ---- nodes, groups, edges as indexed records ------------------------------------------
+		const specNodes = Array.isArray(spec.nodes) ? spec.nodes : [];
+		const idIndex = new Map();
+		const N = specNodes.map((n, i) => {
+			const sz = nodeSize(n, measure, T, B);
+			idIndex.set(n.id, i);
+			return { i, id: n.id, spec: n, shape: sz.shape, w: sz.w, h: sz.h, lines: sz.lines, textH: sz.textH, textDy: sz.textDy, grp: -1, rank: 0 };
+		});
+		const specGroups = Array.isArray(spec.groups) ? spec.groups : [];
+		const gIndex = new Map();
+		const G = specGroups.map((g, i) => { gIndex.set(g.id, i); return { i, id: g.id, label: g.label, tip: g.tip, parent: -1, kids: [], path: [], nodes: new Set(), rmin: Infinity, rmax: -Infinity, labelW: measure(g.label, 'group') }; });
+		for (const g of G) {
+			const p = specGroups[g.i].parent;
+			if (p !== undefined && gIndex.has(p) && gIndex.get(p) !== g.i) { g.parent = gIndex.get(p); }
+		}
+		// a parent chain that loops (validate() rejects it; this is belt and braces) is cut
+		for (const g of G) { let cur = g, hops = 0; while (cur.parent >= 0 && hops++ <= G.length) { cur = G[cur.parent]; } if (hops > G.length) { g.parent = -1; } }
+		for (const g of G) { if (g.parent >= 0) { G[g.parent].kids.push(g.i); } }
+		const pathOf = (g) => { const p = []; let cur = g; while (cur) { p.unshift(cur.i); cur = cur.parent >= 0 ? G[cur.parent] : null; } return p; };
+		for (const g of G) { g.path = pathOf(g); }
+		for (const n of N) {
+			const gi = n.spec.group !== undefined ? gIndex.get(n.spec.group) : undefined;
+			if (gi !== undefined) { n.grp = gi; for (const a of G[gi].path) { G[a].nodes.add(n.i); } }
+		}
+		const liveGroups = G.filter((g) => g.nodes.size > 0);
+
+		const E = [];
+		(Array.isArray(spec.edges) ? spec.edges : []).forEach((e, k) => {
+			const u = idIndex.get(e.from), v = idIndex.get(e.to);
+			if (u === undefined || v === undefined) { return; }
+			const label = e.label ? { text: e.label, w: measure(e.label, 'edge'), h: T.edge.line } : null;
+			E.push({ k, u, v, self: u === v, rev: false, dashed: e.style === 'dashed', label, tip: e.tip });
+		});
+		const flow = E.filter((e) => !e.self);
+
+		// ---- rank: break cycles, then longest path, then pull loose ends in --------------------
+		const outE = N.map(() => []), inDeg = N.map(() => 0);
+		for (const e of flow) { outE[e.u].push(e); inDeg[e.v]++; }
+		const mark = N.map(() => 0);
+		const visit = (u) => {
+			mark[u] = 1;
+			for (const e of outE[u]) { if (mark[e.v] === 1) { e.rev = true; } else if (mark[e.v] === 0) { visit(e.v); } }
+			mark[u] = 2;
+		};
+		// Sources first, in the order the model wrote them: a spec lists a flow start-to-finish, so
+		// the edge that points back at an earlier node is the one to treat as the loop.
+		for (const n of N) { if (inDeg[n.i] === 0 && mark[n.i] === 0) { visit(n.i); } }
+		for (const n of N) { if (mark[n.i] === 0) { visit(n.i); } }
+		for (const e of flow) { e.a = e.rev ? e.v : e.u; e.b = e.rev ? e.u : e.v; }
+
+		const succ = N.map(() => []), pred = N.map(() => []);
+		for (const e of flow) { succ[e.a].push(e.b); pred[e.b].push(e.a); }
+		if (!flow.length) {
+			// Nothing connects anything: a tidy grid reads better than one long line of boxes.
+			const order = N.slice().sort((p, q) => (p.grp - q.grp) || (p.i - q.i));
+			const per = Math.max(1, Math.ceil(order.length / Math.max(1, Math.round(Math.sqrt(order.length)))));
+			order.forEach((n, j) => { n.rank = Math.floor(j / per); });
+		} else {
+			const deg = N.map((n) => pred[n.i].length);
+			const queue = N.filter((n) => deg[n.i] === 0).map((n) => n.i);
+			for (let qi = 0; qi < queue.length; qi++) {
+				const u = queue[qi];
+				for (const v of succ[u]) { N[v].rank = Math.max(N[v].rank, N[u].rank + 1); if (--deg[v] === 0) { queue.push(v); } }
+			}
+			// Tighten: move each node, within the slack its neighbours leave, toward the side it has
+			// more connections on. Stops a source being parked five ranks from its only successor.
+			for (let pass = 0; pass < 12; pass++) {
+				let moved = false;
+				for (const n of N) {
+					if (!pred[n.i].length && !succ[n.i].length) { continue; }
+					const lo = pred[n.i].length ? Math.max.apply(null, pred[n.i].map((p) => N[p].rank)) + 1 : 0;
+					const hi = succ[n.i].length ? Math.min.apply(null, succ[n.i].map((s) => N[s].rank)) - 1 : n.rank;
+					let want = n.rank;
+					if (succ[n.i].length > pred[n.i].length) { want = hi; }
+					else if (pred[n.i].length > succ[n.i].length) { want = lo; }
+					want = Math.max(lo, Math.min(Math.max(lo, hi), want));
+					if (want !== n.rank) { n.rank = want; moved = true; }
+				}
+				if (!moved) { break; }
+			}
+			const minRank = Math.min.apply(null, N.map((n) => n.rank));
+			if (minRank) { for (const n of N) { n.rank -= minRank; } }
+		}
+		const R = N.length ? Math.max.apply(null, N.map((n) => n.rank)) + 1 : 1;
+		for (const g of liveGroups) { for (const ni of g.nodes) { g.rmin = Math.min(g.rmin, N[ni].rank); g.rmax = Math.max(g.rmax, N[ni].rank); } }
+
+		// ---- items: real nodes, the virtual nodes that carry long edges, group spacers ---------
+		const items = [];
+		const ms = (n) => (right ? n.w : n.h), cs = (n) => (right ? n.h : n.w);
+		const nodeItem = N.map((n) => {
+			const it = { kind: 'node', node: n, rank: n.rank, ms: ms(n), cs: cs(n), grp: n.grp, path: n.grp >= 0 ? G[n.grp].path : [], order: 0, x: 0, extraLo: 0, extraHi: 0, lo: [], hi: [] };
+			items.push(it); return it;
+		});
+		/**
+		 * Which group a long edge is "in" as it crosses rank r. An edge into a group enters at the
+		 * group's edge and then travels INSIDE its band to the node it wants — it does not skirt the
+		 * frame and double back. So: the innermost group of either end that spans this rank; when the
+		 * two ends offer unrelated groups, the one whose node is nearer.
+		 */
+		const groupAt = (n, r) => {
+			if (n.grp < 0) { return -1; }
+			const path = G[n.grp].path;
+			for (let i = path.length - 1; i >= 0; i--) { const g = G[path[i]]; if (g.rmin <= r && r <= g.rmax) { return g.i; } }
+			return -1;
+		};
+		const chainGroup = (a, b, r) => {
+			const ga = groupAt(a, r), gb = groupAt(b, r);
+			if (ga < 0 || gb < 0) { return Math.max(ga, gb); }
+			if (ga === gb || G[gb].path.indexOf(ga) >= 0) { return gb; }
+			if (G[ga].path.indexOf(gb) >= 0) { return ga; }
+			return (r - a.rank) <= (b.rank - r) ? ga : gb;
+		};
+		const lm = (label) => (right ? label.w : label.h), lc = (label) => (right ? label.h : label.w);
+		const rankMs = new Array(R).fill(0);
+		for (const it of nodeItem) { rankMs[it.rank] = Math.max(rankMs[it.rank], it.ms); }
+		const chains = [];
+		for (const e of flow) {
+			const a = nodeItem[e.a], b = nodeItem[e.b];
+			const seq = [a];
+			for (let r = a.rank + 1; r < b.rank; r++) {
+				const grp = chainGroup(N[e.a], N[e.b], r);
+				const v = { kind: 'virt', rank: r, ms: 0, cs: 0, grp, path: grp >= 0 ? G[grp].path : [], order: 0, x: 0, extraLo: 0, extraHi: 0, chain: null };
+				items.push(v); seq.push(v);
+			}
+			seq.push(b);
+			const ch = { e, seq, offA: 0, offB: 0, host: null };
+			for (const v of seq) { if (v.kind === 'virt') { v.chain = ch; } }
+			// A long edge's label rides above the line where it crosses a rank that is wide enough for it.
+			if (e.label) {
+				const host = seq.find((v) => v.kind === 'virt' && rankMs[v.rank] >= lm(e.label) + 2 * S.labelPad);
+				if (host) { ch.host = host; host.extraLo = lc(e.label) + S.labelGap + 2; }
+			}
+			chains.push(ch);
+		}
+		// A group owns one band across EVERY rank it spans. Where it has nothing of its own in a
+		// rank, a zero-size spacer holds its place, so what else is in that rank is above or below.
+		const inSubtree = (it, g) => it.path.indexOf(g.i) >= 0;
+		for (const g of liveGroups.slice().sort((p, q) => q.path.length - p.path.length)) {
+			for (let r = g.rmin; r <= g.rmax; r++) {
+				if (!items.some((it) => it.rank === r && inSubtree(it, g))) {
+					items.push({ kind: 'spacer', rank: r, ms: 0, cs: 0, grp: g.i, path: g.path, order: 0, x: 0, extraLo: 0, extraHi: 0 });
+				}
+			}
+		}
+		const ranks = [];
+		for (let r = 0; r < R; r++) { ranks.push(items.filter((it) => it.rank === r)); }
+		/** segs[r] = the pieces of chains that cross the gap between rank r and r+1. */
+		const segs = [];
+		for (let r = 0; r < R; r++) { segs.push([]); }
+		for (const ch of chains) { for (let j = 0; j + 1 < ch.seq.length; j++) { segs[ch.seq[j].rank].push({ a: ch.seq[j], b: ch.seq[j + 1], ch, j }); } }
+
+		orderRanks(ranks, segs, G, N, nodeItem);
+
+		// ---- ports: every connector end gets its own point on its side -------------------------
+		// A side's ends are sorted by where the other end sits in the neighbouring rank, so two
+		// connectors leaving one node never cross on the way out.
+		for (const ch of chains) {
+			const first = ch.seq[0], last = ch.seq[ch.seq.length - 1];
+			first.hi.push({ ch, other: ch.seq[1], end: 'A' });
+			last.lo.push({ ch, other: ch.seq[ch.seq.length - 2], end: 'B' });
+		}
+		const selfLoops = E.filter((e) => e.self);
+		for (const e of selfLoops) { nodeItem[e.u].hi.push({ self: e, other: { order: -1 }, end: 'S' }); }
+		for (const it of nodeItem) {
+			for (const side of ['lo', 'hi']) {
+				const ends = it[side];
+				if (!ends.length) { continue; }
+				ends.sort((p, q) => (p.other.order - q.other.order) || ((p.ch ? p.ch.e.k : -1) - (q.ch ? q.ch.e.k : -1)));
+				const n = ends.length;
+				// A label sits on the stub that carries the arrowhead. Where several connectors arrive
+				// side by side and one is labelled, they are spread a label-height apart so each label
+				// has a lane of its own — and the node grows to fit them. Only when the flow runs right:
+				// run down, a label lies ACROSS the stubs and no sane spacing would hold it.
+				const arrowEnd = (en) => !!en.ch && !!en.ch.e.label && !en.ch.host && (en.ch.e.rev ? en.end === 'A' : en.end === 'B');
+				const labelled = right && n > 1 && ends.some(arrowEnd);
+				const lane = S.labelLane != null ? S.labelLane : T.edge.line + S.labelGap + 2;
+				const floor = labelled ? lane : (S.portMin != null ? S.portMin : 6);
+				let gap = Math.max(S.portGap, labelled ? floor : 0);
+				let span = portSpan(it.node, it.cs, S);
+				if (n > 1 && (n - 1) * gap > span) {
+					gap = Math.max(floor, span / (n - 1));
+					if ((n - 1) * gap > span + 1e-6) {
+						// Still does not fit: the node grows along its side. ("Renderer only: widen, wrap.")
+						const need = (n - 1) * gap;
+						const grow = it.node.shape === 'decision' ? need / 0.5 : it.node.shape === 'actor' ? need / 0.55 : need + 2 * S.portInset;
+						if (right) { it.node.h = Math.ceil(grow); } else { it.node.w = Math.ceil(grow); }
+						it.cs = cs(it.node); span = portSpan(it.node, it.cs, S);
+					}
+				}
+				ends.forEach((en, i) => {
+					const off = (i - (n - 1) / 2) * gap;
+					if (en.end === 'A') { en.ch.offA = off; } else if (en.end === 'B') { en.ch.offB = off; } else { en.self.off = off; }
+				});
+			}
+			// a self-loop steps out above the node; keep that space free
+			const loop = selfLoops.filter((e) => e.u === it.node.i);
+			if (loop.length) { it.extraLo = Math.max(it.extraLo, S.selfLoop + (loop.length - 1) * S.track + (loop.some((e) => e.label) ? Math.max.apply(null, loop.filter((e) => e.label).map((e) => lc(e.label))) + S.labelGap : 0) + 2); }
+		}
+
+		// ---- place across the flow --------------------------------------------------------------
+		const crossPadLo = right ? S.groupHeader + S.groupInset - 6 : S.groupInset;
+		const crossPadHi = S.groupInset;
+		const mainPadLo = right ? S.groupInset : S.groupHeader + S.groupInset - 6;
+		const mainPadHi = S.groupInset;
+		placeCross(items, ranks, liveGroups, G, chains, S, { crossPadLo, crossPadHi, right, reserve: reserve || null }, warnings);
+
+		// ---- gaps between ranks: tracks for the bends, room for the labels -----------------------
+		const nestLo = (g) => mainPadLo + Math.max(0, Math.max.apply(null, [0].concat(g.kids.filter((k) => G[k].nodes.size && G[k].rmin === g.rmin).map((k) => nestLo(G[k])))));
+		const nestHi = (g) => mainPadHi + Math.max(0, Math.max.apply(null, [0].concat(g.kids.filter((k) => G[k].nodes.size && G[k].rmax === g.rmax).map((k) => nestHi(G[k])))));
+		const openPad = new Array(R + 1).fill(0), closePad = new Array(R + 1).fill(0);
+		for (const g of liveGroups) {
+			if (g.parent >= 0) { continue; }
+			openPad[g.rmin] = Math.max(openPad[g.rmin], nestLo(g));
+			closePad[g.rmax] = Math.max(closePad[g.rmax], nestHi(g));
+		}
+		const crossAt = (it, ch, end) => it.x + (it.kind === 'node' ? (end === 'A' ? ch.offA : ch.offB) : 0);
+		const gaps = [];
+		const hasLoop = new Array(R).fill(0);
+		const loopCount = new Map();
+		for (const e of selfLoops) { loopCount.set(e.u, (loopCount.get(e.u) || 0) + 1); hasLoop[N[e.u].rank] = Math.max(hasLoop[N[e.u].rank], loopCount.get(e.u)); }
+		for (let r = 0; r + 1 < R; r++) {
+			const conns = segs[r].map((sg) => {
+				const ca = crossAt(sg.a, sg.ch, 'A'), cb = crossAt(sg.b, sg.ch, 'B');
+				return { sg, ca, cb, lo: Math.min(ca, cb), hi: Math.max(ca, cb), bent: Math.abs(ca - cb) > STRAIGHT, track: -1 };
+			});
+			const tracks = assignTracks(conns.filter((c) => c.bent), S);
+			// Which labels live in THIS gap: an edge with no wide-enough rank to ride over puts its
+			// label on the stub into its target, i.e. in the last gap it crosses.
+			let tail = 0, straightRoom = 0, crowd = 0;
+			const arriving = new Map();
+			for (const c of conns) {
+				const ch = c.sg.ch, e = ch.e;
+				if (!e.label || ch.host || c.sg.j !== ch.seq.length - 2) { continue; }
+				if (c.bent) { tail = Math.max(tail, lm(e.label) + 2 * S.labelPad); }
+				else { straightRoom = Math.max(straightRoom, lm(e.label) + 2 * S.labelPad + S.arrow + 4); }
+				arriving.set(c.sg.b, (arriving.get(c.sg.b) || 0) + 1);
+				if (arriving.get(c.sg.b) > 2) { crowd = Math.max(crowd, lm(e.label) + 2 * S.labelPad + 2); }
+			}
+			// Three or more labelled connectors into one node cannot all be labelled where they arrive;
+			// a longer stub out of each SOURCE gives the extra ones somewhere clear to sit.
+			const loopPad = hasLoop[r] ? S.selfLoop + (hasLoop[r] - 1) * S.track + 6 : 0;
+			const lead = Math.max(S.channelPad, crowd) + loopPad;
+			const bundle = tracks > 0 ? (tracks - 1) * S.track : 0;
+			const trail = Math.max(S.channelPad, tail ? tail + S.arrow + 4 : 0);
+			let core = tracks > 0 ? lead + bundle + trail : Math.max(loopPad + S.channelPad, 0);
+			core = Math.max(core, straightRoom + loopPad, S.rankGap);
+			gaps.push({ conns, tracks, lead, bundle, trail, core, hugLo: tail > 0 || loopPad > 0, width: closePad[r] + core + openPad[r + 1] });
+		}
+
+		// ---- place along the flow, then route ----------------------------------------------------
+		const rankLo = new Array(R).fill(0), rankHi = new Array(R).fill(0);
+		const placeMain = () => {
+			let m = openPad[0];
+			for (let r = 0; r < R; r++) {
+				rankLo[r] = m; rankHi[r] = m + rankMs[r];
+				m = rankHi[r] + (r + 1 < R ? gaps[r].width : 0);
+			}
+		};
+		placeMain();
+		// A group must be wide enough to carry its own label along the top.
+		if (right) {
+			const extra = new Array(R).fill(0);
+			for (const g of liveGroups) {
+				const have = (rankHi[g.rmax] + mainPadHi) - (rankLo[g.rmin] - mainPadLo);
+				const need = g.labelW + 2 * S.groupInset;
+				if (need > have) { g.extraHi = need - have; extra[g.rmax] = Math.max(extra[g.rmax], g.extraHi); }
+			}
+			if (extra.some((v) => v > 0)) {
+				for (let r = 0; r + 1 < R; r++) { gaps[r].width += extra[r]; }
+				placeMain();
+			}
+		}
+		for (const it of items) { it.m = (rankLo[it.rank] + rankHi[it.rank]) / 2; }
+
+		const P = (m, c) => (right ? { x: m, y: c } : { x: c, y: m });
+		const mAxis = right ? 'x' : 'y', cAxis = right ? 'y' : 'x';
+		for (let r = 0; r + 1 < R; r++) {
+			const gp = gaps[r];
+			const zoneLo = rankHi[r] + closePad[r], zoneHi = rankLo[r + 1] - openPad[r + 1];
+			const start = gp.hugLo ? zoneLo + gp.lead : zoneLo + ((zoneHi - zoneLo) - gp.bundle) / 2;
+			for (const c of gp.conns) { if (c.bent) { c.m = start + c.track * S.track; } }
+		}
+		const connOf = new Map();
+		for (const gp of gaps) { for (const c of gp.conns) { connOf.set(c.sg.ch.e.k + ':' + c.sg.j, c); } }
+
+		const routes = [];
+		for (const ch of chains) {
+			const first = ch.seq[0], last = ch.seq[ch.seq.length - 1];
+			let cur = first.x + ch.offA;
+			const pts = [{ m: first.m + outline(first.node, mAxis, ch.offA, B), c: cur }];
+			for (let j = 0; j + 1 < ch.seq.length; j++) {
+				const next = ch.seq[j + 1];
+				const c = connOf.get(ch.e.k + ':' + j);
+				if (c && c.bent) { pts.push({ m: c.m, c: cur }); cur = c.cb; pts.push({ m: c.m, c: cur }); }
+				if (next.kind === 'virt') { pts.push({ m: rankLo[next.rank], c: cur }, { m: rankHi[next.rank], c: cur }); }
+			}
+			pts.push({ m: last.m - outline(last.node, mAxis, cur - last.x, B), c: cur });
+			routes.push({ e: ch.e, ch, pts: simplify(pts) });
+		}
+		const loopsAt = new Map();
+		for (const e of selfLoops) {
+			const it = nodeItem[e.u], n = it.node;
+			const nth = loopsAt.get(e.u) || 0; loopsAt.set(e.u, nth + 1);
+			const L = S.selfLoop + nth * S.track;
+			const top = it.x - it.cs / 2, enter = Math.max(-it.ms / 2 + S.portInset, it.ms / 4 - nth * S.track);
+			const pts = [
+				{ m: it.m + outline(n, mAxis, e.off, B), c: it.x + e.off },
+				{ m: it.m + it.ms / 2 + L, c: it.x + e.off },
+				{ m: it.m + it.ms / 2 + L, c: top - L },
+				{ m: it.m + enter, c: top - L },
+				{ m: it.m + enter, c: it.x - outline(n, cAxis, enter, B) }
+			];
+			routes.push({ e, ch: null, pts: simplify(pts), loop: true });
+		}
+		for (const rt of routes) { if (rt.e.rev) { rt.pts.reverse(); } }
+
+		// ---- group frames -----------------------------------------------------------------------
+		const frames = [];
+		const frameOf = new Map();
+		const frame = (g) => {
+			if (frameOf.has(g.i)) { return frameOf.get(g.i); }
+			let mLo = rankLo[g.rmin] - mainPadLo, mHi = rankHi[g.rmax] + mainPadHi + (g.extraHi || 0);
+			for (const k of g.kids) {
+				if (!G[k].nodes.size) { continue; }
+				const f = frame(G[k]);
+				mLo = Math.min(mLo, f.mLo - mainPadLo); mHi = Math.max(mHi, f.mHi + mainPadHi);
+			}
+			const f = { g, mLo, mHi, cLo: g.lo, cHi: g.hi };
+			frameOf.set(g.i, f); return f;
+		};
+		for (const g of liveGroups) { frames.push(frame(g)); }
+
+		// ---- everything into screen coordinates -------------------------------------------------
+		const rectMC = (mLo, mHi, cLo, cHi) => (right ? { x: mLo, y: cLo, w: mHi - mLo, h: cHi - cLo } : { x: cLo, y: mLo, w: cHi - cLo, h: mHi - mLo });
+		const nodesOut = nodeItem.map((it) => {
+			const n = it.node;
+			const c = P(it.m, it.x);
+			return { id: n.id, shape: n.shape, x: c.x - n.w / 2, y: c.y - n.h / 2, w: n.w, h: n.h, cx: c.x, cy: c.y, accent: n.spec.accent === true, link: n.spec.link || null, tip: n.spec.tip || null, group: n.grp >= 0 ? G[n.grp].id : null, lines: n.lines, textH: n.textH, textDy: n.textDy };
+		});
+		const groupsOut = frames.map((f) => {
+			const rc = rectMC(f.mLo, f.mHi, f.cLo, f.cHi);
+			return { id: f.g.id, label: f.g.label, tip: f.g.tip || null, parent: f.g.parent >= 0 ? G[f.g.parent].id : null, depth: f.g.path.length, x: rc.x, y: rc.y, w: rc.w, h: rc.h, labelW: f.g.labelW, labelH: T.group.line };
+		});
+		for (const g of groupsOut) { g.labelX = g.x + S.groupInset - 4; g.labelY = g.y + 7; g.labelHalo = false; g.labelNeed = 0; }
+		const edgesOut = routes.map((rt) => {
+			const points = rt.pts.map((p) => P(p.m, p.c));
+			const n = points.length, a = points[n - 2], b = points[n - 1];
+			const dx = Math.sign(r2(b.x - a.x)), dy = Math.sign(r2(b.y - a.y));
+			const host = rt.ch && rt.ch.host ? P(rt.ch.host.m, rt.ch.host.x) : null;
+			return { index: rt.e.k, from: N[rt.e.u].id, to: N[rt.e.v].id, dashed: rt.e.dashed, points, arrow: { x: b.x, y: b.y, dx, dy }, label: null, tip: rt.e.tip || null, loop: !!rt.loop, back: !!rt.e.rev, _e: rt.e, _host: host };
+		});
+
+		placeGroupLabels(groupsOut, edgesOut, warnings);
+		placeLabels(edgesOut, nodesOut, groupsOut, S, warnings, right);
+
+		// ---- frame it: shift so the drawing starts at the margin, and measure --------------------
+		let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+		const grow = (x, y) => { if (x < minX) { minX = x; } if (y < minY) { minY = y; } if (x > maxX) { maxX = x; } if (y > maxY) { maxY = y; } };
+		for (const n of nodesOut) { grow(n.x - 1, n.y - 1); grow(n.x + n.w + 1, n.y + n.h + 1); }
+		for (const g of groupsOut) { grow(g.x, g.y); grow(g.x + g.w, g.y + g.h); }
+		for (const e of edgesOut) {
+			for (const p of e.points) { grow(p.x - S.arrowHalf, p.y - S.arrowHalf); grow(p.x + S.arrowHalf, p.y + S.arrowHalf); }
+			if (e.label) { grow(e.label.x, e.label.y); grow(e.label.x + e.label.w, e.label.y + e.label.h); }
+		}
+		if (!Number.isFinite(minX)) { minX = minY = 0; maxX = maxY = 0; }
+		const dx = S.margin - minX, dy = S.margin - minY;
+		for (const n of nodesOut) { n.x = r2(n.x + dx); n.y = r2(n.y + dy); n.cx = r2(n.cx + dx); n.cy = r2(n.cy + dy); }
+		for (const g of groupsOut) { g.x = r2(g.x + dx); g.y = r2(g.y + dy); g.w = r2(g.w); g.h = r2(g.h); g.labelX = r2(g.labelX + dx); g.labelY = r2(g.labelY + dy); }
+		for (const e of edgesOut) {
+			for (const p of e.points) { p.x = r2(p.x + dx); p.y = r2(p.y + dy); }
+			e.arrow.x = r2(e.arrow.x + dx); e.arrow.y = r2(e.arrow.y + dy);
+			if (e.label) { e.label.x = r2(e.label.x + dx); e.label.y = r2(e.label.y + dy); }
+			delete e._e; delete e._host;
+		}
+		const geo = {
+			direction: dir, flipped: false, asked: dir,
+			width: Math.ceil(maxX - minX + 2 * S.margin), height: Math.ceil(maxY - minY + 2 * S.margin),
+			nodes: nodesOut, edges: edgesOut, groups: groupsOut, ranks: R,
+			crossings: countAllCrossings(ranks, segs), warnings
+		};
+		for (const w of inspect(geo)) { warnings.push(w); }
+		return geo;
+	}
+	/** What layoutDir() needs from a pass and nobody else does. */
+	function tidy(geo) { for (const g of geo.groups) { delete g.labelNeed; } return geo; }
+
+	/** Drop repeated points and points in the middle of a straight run. */
+	function simplify(pts) {
+		const out = [];
+		for (const p of pts) {
+			const q = out[out.length - 1];
+			if (q && Math.abs(q.m - p.m) < 0.01 && Math.abs(q.c - p.c) < 0.01) { continue; }
+			out.push({ m: p.m, c: p.c });
+		}
+		for (let i = out.length - 2; i > 0; i--) {
+			const a = out[i - 1], b = out[i], c = out[i + 1];
+			if ((Math.abs(a.m - b.m) < 0.01 && Math.abs(b.m - c.m) < 0.01) || (Math.abs(a.c - b.c) < 0.01 && Math.abs(b.c - c.c) < 0.01)) { out.splice(i, 1); }
+		}
+		return out;
+	}
+
+	// ---- ordering -------------------------------------------------------------------------------
+
+	function crossingsBetween(sgs) {
+		let c = 0;
+		for (let i = 0; i < sgs.length; i++) {
+			for (let j = i + 1; j < sgs.length; j++) {
+				const p = sgs[i], q = sgs[j];
+				const da = p.a.order - q.a.order, db = p.b.order - q.b.order;
+				if (da * db < 0) { c++; }
+			}
+		}
+		return c;
+	}
+	function countAllCrossings(ranks, segs) { let c = 0; for (let r = 0; r + 1 < ranks.length; r++) { c += crossingsBetween(segs[r]); } return c; }
+
+	/**
+	 * Order every rank to minimise crossings. A rank is a TREE, not a list: items that share a group
+	 * stay next to each other at every level, so the order is found by sorting blocks (an item, or a
+	 * whole group) among their siblings and recursing — which keeps frames contiguous by construction.
+	 */
+	function orderRanks(ranks, segs, G, N, nodeItem) {
+		const R = ranks.length;
+		const number = () => { for (const rk of ranks) { rk.forEach((it, i) => { it.order = i; }); } };
+		const blocksOf = (list, depth) => {
+			const blocks = [], by = new Map();
+			for (const it of list) {
+				const g = it.path[depth];
+				if (g === undefined) { blocks.push({ group: -1, items: [it] }); continue; }
+				let b = by.get(g);
+				if (!b) { b = { group: g, items: [] }; by.set(g, b); blocks.push(b); }
+				b.items.push(it);
+			}
+			return blocks;
+		};
+		const mean = (arr) => arr.reduce((s, v) => s + v, 0) / arr.length;
+		/** Sort a rank's tree by each block's mean key (stable — ties keep their order). */
+		const arrange = (list, depth, flip) => {
+			const blocks = blocksOf(list, depth);
+			blocks.forEach((b, i) => { b.key = mean(b.items.map((it) => it.key)); b.at = i; });
+			blocks.sort((p, q) => (p.key - q.key) || (flip ? q.at - p.at : p.at - q.at));
+			const out = [];
+			for (const b of blocks) { if (b.group < 0) { out.push(b.items[0]); } else { for (const it of arrange(b.items, depth + 1, flip)) { out.push(it); } } }
+			return out;
+		};
+		// Sibling groups must keep ONE order through every rank they share, or their bands would
+		// have to cross. Decide that order once (by where each group sits on average) and impose it.
+		const groupKey = new Map();
+		const settleGroups = () => {
+			number();
+			const sum = new Map(), cnt = new Map();
+			for (const rk of ranks) {
+				const span = Math.max(1, rk.length - 1);
+				for (const it of rk) { for (const g of it.path) { sum.set(g, (sum.get(g) || 0) + it.order / span); cnt.set(g, (cnt.get(g) || 0) + 1); } }
+			}
+			for (const g of sum.keys()) { groupKey.set(g, sum.get(g) / cnt.get(g)); }
+			const keep = (list, depth) => {
+				const blocks = blocksOf(list, depth);
+				const slots = [], groups = [];
+				blocks.forEach((b, i) => { if (b.group >= 0) { slots.push(i); groups.push(b); } });
+				groups.sort((p, q) => (groupKey.get(p.group) - groupKey.get(q.group)) || (p.group - q.group));
+				slots.forEach((s, i) => { blocks[s] = groups[i]; });
+				const out = [];
+				for (const b of blocks) { if (b.group < 0) { out.push(b.items[0]); } else { for (const it of keep(b.items, depth + 1)) { out.push(it); } } }
+				return out;
+			};
+			for (let r = 0; r < R; r++) { ranks[r] = keep(ranks[r], 0); }
+			number();
+		};
+
+		// Start from a depth-first walk in the order the model wrote things: a flow drawn the way it
+		// was described is usually already close to crossing-free.
+		const adjHi = new Map();
+		for (const sg of segs.flat()) { if (!adjHi.has(sg.a)) { adjHi.set(sg.a, []); } adjHi.get(sg.a).push(sg.b); }
+		let tick = 0;
+		const seen = new Set();
+		const walk = (it) => { if (seen.has(it)) { return; } seen.add(it); it.key = tick++; for (const nx of (adjHi.get(it) || [])) { walk(nx); } };
+		for (const it of nodeItem.slice().sort((p, q) => (p.rank - q.rank) || (p.node.i - q.node.i))) { walk(it); }
+		for (const rk of ranks) { for (const it of rk) { if (!seen.has(it)) { it.key = tick++; } } }
+		for (let r = 0; r < R; r++) { ranks[r] = arrange(ranks[r], 0, false); }
+		settleGroups();
+
+		const nbrLo = new Map(), nbrHi = new Map();
+		for (const sg of segs.flat()) {
+			if (!nbrHi.has(sg.a)) { nbrHi.set(sg.a, []); } nbrHi.get(sg.a).push(sg.b);
+			if (!nbrLo.has(sg.b)) { nbrLo.set(sg.b, []); } nbrLo.get(sg.b).push(sg.a);
+		}
+		const snapshot = () => ranks.map((rk) => rk.slice());
+		const restore = (snap) => { for (let r = 0; r < R; r++) { ranks[r] = snap[r].slice(); } number(); };
+		let best = snapshot(), bestCost = countAllCrossings(ranks, segs);
+		for (let it = 0; it < 24 && bestCost > 0; it++) {
+			const down = it % 2 === 0, flip = it % 4 >= 2;
+			for (let s = 1; s < R; s++) {
+				const r = down ? s : R - 1 - s;
+				const ref = down ? nbrLo : nbrHi;
+				for (const item of ranks[r]) {
+					const ns = ref.get(item);
+					item.key = ns && ns.length ? mean(ns.map((n) => n.order)) : item.order;
+				}
+				ranks[r] = arrange(ranks[r], 0, flip);
+				ranks[r].forEach((x, i) => { x.order = i; });
+			}
+			settleGroups();
+			const cost = countAllCrossings(ranks, segs);
+			if (cost < bestCost) { bestCost = cost; best = snapshot(); }
+		}
+		restore(best);
+
+		// Transpose: swap neighbouring siblings wherever that removes a crossing. (Two groups are
+		// never swapped here — their order is global, settled above.)
+		const local = (r) => (r > 0 ? crossingsBetween(segs[r - 1]) : 0) + (r + 1 < R ? crossingsBetween(segs[r]) : 0);
+		const treeOf = (list, depth) => blocksOf(list, depth).map((b) => (b.group < 0 ? { item: b.items[0] } : { group: b.group, kids: treeOf(b.items, depth + 1) }));
+		const flat = (tree, out) => { for (const t of tree) { if (t.item) { out.push(t.item); } else { flat(t.kids, out); } } return out; };
+		for (let pass = 0; pass < 30 && bestCost > 0; pass++) {
+			let improved = false;
+			for (let r = 0; r < R; r++) {
+				const tree = treeOf(ranks[r], 0);
+				const apply = () => { ranks[r] = flat(tree, []); ranks[r].forEach((x, i) => { x.order = i; }); };
+				const sweep = (level) => {
+					for (let i = 0; i + 1 < level.length; i++) {
+						if (level[i].group !== undefined && level[i + 1].group !== undefined) { continue; }
+						const before = local(r);
+						const t = level[i]; level[i] = level[i + 1]; level[i + 1] = t; apply();
+						if (local(r) < before) { improved = true; }
+						else { level[i + 1] = level[i]; level[i] = t; apply(); }
+					}
+					for (const t of level) { if (t.kids) { sweep(t.kids); } }
+				};
+				sweep(tree);
+			}
+			if (!improved) { break; }
+			bestCost = countAllCrossings(ranks, segs);
+		}
+		number();
+	}
+
+	// ---- placement across the flow ----------------------------------------------------------------
+
+	/**
+	 * Give every item its cross coordinate, and every group its band.
+	 *
+	 * The hard part is stated as difference constraints (x[b] - x[a] >= d): neighbours in a rank keep
+	 * their gap, a group's band contains its members plus padding, and — because a group's band is ONE
+	 * pair of variables shared by every rank it spans — nothing outside a group can ever sit inside it.
+	 * The soft part is alignment: sweeps along the flow move each item to the median of what it
+	 * connects to, as far as the constraints let it; then anything within a hair of straight is made
+	 * exactly straight.
+	 */
+	function placeCross(items, ranks, liveGroups, G, chains, S, pad, warnings) {
+		const vars = [];
+		items.forEach((it) => { it.v = vars.length; vars.push(0); });
+		for (const g of liveGroups) { g.vLo = vars.length; vars.push(0); g.vHi = vars.length; vars.push(0); }
+		const X = new Float64Array(vars.length);
+		const cons = [];
+		const add = (a, b, d) => { cons.push({ a, b, d }); };
+
+		const gapBetween = (p, q) => {
+			if (p.group >= 0 || q.group >= 0) { return S.groupGap; }
+			const a = p.items[0], b = q.items[0];
+			if (a.kind === 'node' && b.kind === 'node') { return S.nodeGap; }
+			if (a.kind === 'virt' && b.kind === 'virt') { return S.track; }
+			return S.lineClear;
+		};
+		const blocksOf = (list, depth) => {
+			const blocks = [], by = new Map();
+			for (const it of list) {
+				const g = it.path[depth];
+				if (g === undefined) { blocks.push({ group: -1, items: [it] }); continue; }
+				let b = by.get(g);
+				if (!b) { b = { group: g, items: [] }; by.set(g, b); blocks.push(b); }
+				b.items.push(it);
+			}
+			return blocks;
+		};
+		const hiOf = (b) => (b.group >= 0 ? { v: G[b.group].vHi, off: 0 } : { v: b.items[0].v, off: b.items[0].cs / 2 + b.items[0].extraHi });
+		const loOf = (b) => (b.group >= 0 ? { v: G[b.group].vLo, off: 0 } : { v: b.items[0].v, off: -(b.items[0].cs / 2 + b.items[0].extraLo) });
+		const walk = (list, depth) => {
+			const blocks = blocksOf(list, depth);
+			for (let i = 0; i + 1 < blocks.length; i++) {
+				const hi = hiOf(blocks[i]), lo = loOf(blocks[i + 1]);
+				// (x[lo.v] + lo.off) - (x[hi.v] + hi.off) >= gap
+				add(hi.v, lo.v, gapBetween(blocks[i], blocks[i + 1]) + hi.off - lo.off);
+			}
+			for (const b of blocks) { if (b.group >= 0) { walk(b.items, depth + 1); } }
+		};
+		for (const rk of ranks) { walk(rk, 0); }
+		// containment: a group's band holds its direct items and its child groups, plus padding
+		const kidsOf = new Map();
+		for (const it of items) {
+			if (it.grp < 0) { continue; }
+			const g = G[it.grp];
+			const isSpacer = it.kind === 'spacer';
+			add(g.vLo, it.v, isSpacer ? 0 : it.cs / 2 + it.extraLo + (it.kind === 'virt' ? S.lineClear : pad.crossPadLo));
+			add(it.v, g.vHi, isSpacer ? 0 : it.cs / 2 + it.extraHi + (it.kind === 'virt' ? S.lineClear : pad.crossPadHi));
+			if (!kidsOf.has(g.i)) { kidsOf.set(g.i, []); } kidsOf.get(g.i).push(it);
+		}
+		for (const g of liveGroups) {
+			if (g.parent >= 0 && G[g.parent].nodes.size) {
+				add(G[g.parent].vLo, g.vLo, pad.crossPadLo);
+				add(g.vHi, G[g.parent].vHi, pad.crossPadHi);
+			}
+			// when the flow runs down, the label lies across the band: the band must be wide enough for it
+			add(g.vLo, g.vHi, pad.right ? 0 : g.labelW + 2 * S.groupInset);
+		}
+		// When the flow runs down, a group's name lies along the very edge its connectors come in by.
+		// For the groups named in `reserve` — the ones whose name found no clear stretch on the first
+		// pass — every line entering from above is kept to the far side of the name, so the name stays
+		// in its corner with nothing through it.
+		const besideName = new Map();   // group index → [{ v, d }]: x[v] - x[group.vLo] >= d
+		if (!pad.right && pad.reserve && pad.reserve.size) {
+			for (const ch of chains) {
+				for (let j = 0; j + 1 < ch.seq.length; j++) {
+					const a = ch.seq[j], b = ch.seq[j + 1];
+					const port = b.kind === 'node' ? ch.offB : 0;   // where on `b` the line lands, from its centre
+					for (const gi of b.path) {
+						if (!pad.reserve.has(G[gi].id) || a.path.indexOf(gi) >= 0) { continue; }   // (a line already inside does not cross this frame's top)
+						const d = (S.groupInset - 4) + G[gi].labelW + NAME_CLEAR - port;
+						add(G[gi].vLo, b.v, d);
+						if (!besideName.has(gi)) { besideName.set(gi, []); }
+						besideName.get(gi).push({ v: b.v, d });
+					}
+				}
+			}
+		}
+
+		/** Push everything down until every constraint holds. Returns false if they contradict. */
+		const settle = () => {
+			for (let pass = 0; pass <= X.length + 1; pass++) {
+				let changed = false;
+				for (const c of cons) { if (X[c.b] < X[c.a] + c.d - 1e-9) { X[c.b] = X[c.a] + c.d; changed = true; } }
+				if (!changed) { return true; }
+			}
+			return false;
+		};
+		if (!settle()) { warnings.push({ cls: 'layout-constraints', message: 'group bands could not all be honoured' }); }
+
+		// What each item would like to line up with: the items its connectors lead to, one rank down
+		// the flow (`tLo`) and one rank up it (`tHi`), each adjusted for the port the connector uses.
+		for (const it of items) { it.tLo = []; it.tHi = []; }
+		const terms = [];
+		for (const ch of chains) {
+			for (let j = 0; j + 1 < ch.seq.length; j++) {
+				const a = ch.seq[j], b = ch.seq[j + 1];
+				const off = (a.kind === 'node' ? ch.offA : 0) - (b.kind === 'node' ? ch.offB : 0);   // want x[b] - x[a] = off
+				a.tHi.push({ o: b.v, off: -off }); b.tLo.push({ o: a.v, off: off });
+				terms.push({ u: a.v, v: b.v, off });
+			}
+		}
+		const inc = Array.from({ length: X.length }, () => []), out = Array.from({ length: X.length }, () => []);
+		for (const c of cons) { inc[c.b].push(c); out[c.a].push(c); }
+		const lbOf = (v) => { let lb = -Infinity; for (const c of inc[v]) { lb = Math.max(lb, X[c.a] + c.d); } return lb; };
+		const ubOf = (v) => { let ub = Infinity; for (const c of out[v]) { ub = Math.min(ub, X[c.b] - c.d); } return ub; };
+		const itemOf = new Map(items.map((it) => [it.v, it]));
+
+		/**
+		 * Where an item wants to be, looking at one side: the MEDIAN of what it connects to there.
+		 * A median, not a mean, because a connector is either straight or it has two corners — being
+		 * "nearly" in line buys nothing. Two neighbours: sit exactly between them (the symmetric fork).
+		 * Four or more, an even count: take whichever middle one is nearer the centre of mass, so one
+		 * connector still runs straight.
+		 */
+		const target = (it, side) => {
+			let ts = side === 'lo' ? it.tLo : it.tHi;
+			if (!ts.length) { ts = side === 'lo' ? it.tHi : it.tLo; }
+			if (!ts.length) { return null; }
+			const ds = ts.map((t) => X[t.o] + t.off).sort((p, q) => p - q);
+			const n = ds.length, lo = ds[Math.floor((n - 1) / 2)], hi = ds[Math.floor(n / 2)];
+			const mean = ds.reduce((p, q) => p + q, 0) / n;
+			if (n >= 4 && n % 2 === 0) { return Math.abs(lo - mean) <= Math.abs(hi - mean) ? lo : hi; }
+			return Math.max(lo, Math.min(hi, mean));
+		};
+		const byDepth = liveGroups.slice().sort((p, q) => p.path.length - q.path.length);
+		/**
+		 * Open every band as far as its surroundings allow, so its members can move inside it. Two
+		 * neighbouring groups cannot both have the free space between them, so who is asked first
+		 * alternates from sweep to sweep.
+		 */
+		const loosen = (flip) => {
+			const order = flip ? byDepth.slice().sort((p, q) => (p.path.length - q.path.length) || (q.i - p.i)) : byDepth;
+			for (const g of order) {
+				const lb = lbOf(g.vLo), ub = ubOf(g.vHi);
+				X[g.vLo] = Number.isFinite(lb) ? Math.min(lb, X[g.vLo]) : X[g.vLo] - 600;
+				X[g.vHi] = Number.isFinite(ub) ? Math.max(ub, X[g.vHi]) : X[g.vHi] + 600;
+			}
+		};
+		/**
+		 * Close every band back around what it holds. A band may have to stay wider than its
+		 * contents (when the flow runs down, its label lies across it); the spare width is shared
+		 * out on both sides where there is room, and taken from whichever side has it where there
+		 * is not — it is never taken from a neighbour.
+		 */
+		const tighten = () => {
+			for (const g of byDepth.slice().reverse()) {
+				let lo = Infinity, hi = -Infinity;
+				for (const it of (kidsOf.get(g.i) || [])) {
+					const sp = it.kind === 'spacer', vt = it.kind === 'virt';
+					lo = Math.min(lo, X[it.v] - (sp ? 0 : it.cs / 2 + it.extraLo + (vt ? S.lineClear : pad.crossPadLo)));
+					hi = Math.max(hi, X[it.v] + (sp ? 0 : it.cs / 2 + it.extraHi + (vt ? S.lineClear : pad.crossPadHi)));
+				}
+				for (const k of g.kids) { if (G[k].nodes.size) { lo = Math.min(lo, X[G[k].vLo] - pad.crossPadLo); hi = Math.max(hi, X[G[k].vHi] + pad.crossPadHi); } }
+				// the band also reaches far enough to the low side for its name to sit clear of the lines coming in
+				for (const c of (besideName.get(g.i) || [])) { lo = Math.min(lo, X[c.v] - c.d); }
+				if (!Number.isFinite(lo)) { continue; }
+				const spare = (pad.right ? 0 : g.labelW + 2 * S.groupInset) - (hi - lo);
+				if (spare > 0) {
+					// how far each side may move out before it meets something
+					let roomLo = Infinity, roomHi = Infinity;
+					for (const c of inc[g.vLo]) { roomLo = Math.min(roomLo, lo - (X[c.a] + c.d)); }
+					for (const c of out[g.vHi]) { if (c.b !== g.vLo) { roomHi = Math.min(roomHi, (X[c.b] - c.d) - hi); } }
+					roomLo = Math.max(0, roomLo); roomHi = Math.max(0, roomHi);
+					let takeLo = Math.min(spare / 2, roomLo), takeHi = Math.min(spare - takeLo, roomHi);
+					takeLo = Math.min(spare - takeHi, roomLo);
+					lo -= takeLo; hi += spare - takeLo;          // anything still owed goes down-flow; settle() makes the room
+				}
+				X[g.vLo] = lo; X[g.vHi] = hi;
+			}
+		};
+		/**
+		 * Move an item toward `want`. Rank-mates it is pressed against in that direction come along —
+		 * but only as far as that cluster agrees to go (the median of what each member wants), and
+		 * never past the next thing in the way. So two children stacked under one parent slide
+		 * together until the parent is centred on them, instead of the first one hogging the line.
+		 *
+		 * A group's band is a WALL here, not a member: nothing pushes a group, and a group pushes
+		 * nothing. Letting pushes travel through bands links every rank into one cluster that never
+		 * settles; with walls, a group moves only because the things inside it did.
+		 */
+		const move = (it, want, side, alone) => {
+			const delta = want - X[it.v];
+			if (Math.abs(delta) < 0.01) { return; }
+			const dir = delta > 0 ? 1 : -1;
+			const cluster = new Set([it.v]), stack = [it.v];
+			while (!alone && stack.length) {
+				const a = stack.pop();
+				for (const c of (dir > 0 ? out[a] : inc[a])) {
+					const o = dir > 0 ? c.b : c.a;
+					if (!cluster.has(o) && itemOf.has(o) && X[c.b] - X[c.a] - c.d <= 1e-6) { cluster.add(o); stack.push(o); }
+				}
+			}
+			let limit = Infinity;
+			const wishes = [];
+			for (const v of cluster) {
+				for (const c of (dir > 0 ? out[v] : inc[v])) {
+					if (!cluster.has(dir > 0 ? c.b : c.a)) { limit = Math.min(limit, X[c.b] - X[c.a] - c.d); }
+				}
+				const m = itemOf.get(v);
+				if (m.kind !== 'spacer') { const t = target(m, side); if (t !== null) { wishes.push((t - X[v]) * dir); } }
+			}
+			wishes.sort((p, q) => p - q);
+			const n = wishes.length;
+			let step = n ? (wishes[Math.floor((n - 1) / 2)] + wishes[Math.floor(n / 2)]) / 2 : Math.abs(delta);
+			step = Math.max(0, Math.min(step, Math.abs(delta), limit));
+			if (step > 1e-6) { for (const v of cluster) { X[v] += dir * step; } }
+		};
+		const R = ranks.length;
+		const sweep = (down, flip, alone) => {
+			loosen(flip);
+			for (let s = 0; s < R; s++) {
+				const rk = ranks[down ? s : R - 1 - s];
+				for (const list of [rk, rk.slice().reverse()]) {
+					for (const it of list) {
+						if (it.kind === 'spacer') { continue; }
+						const t = target(it, down ? 'lo' : 'hi');
+						if (t !== null) { move(it, t, down ? 'lo' : 'hi', alone); }
+					}
+				}
+			}
+			tighten();
+		};
+		// Sweep up the flow lining things up with what they lead to, then down it lining them up
+		// with what leads to them. The last sweeps run WITH the flow and move one item at a time, so
+		// a line leaves its source straight, does its turning at the far end, and nothing that was
+		// just lined up is nudged again.
+		for (let round = 0; round < 6; round++) { sweep(false, round % 2 === 1, false); sweep(true, round % 2 === 0, false); }
+		for (let polish = 0; polish < 3; polish++) { sweep(true, polish % 2 === 1, true); }
+		settle();
+
+		// Straighten: a connector within a hair of straight is MADE straight, when nothing objects.
+		const holds = (v) => inc[v].every((c) => X[c.b] - X[c.a] >= c.d - 1e-6) && out[v].every((c) => X[c.b] - X[c.a] >= c.d - 1e-6);
+		for (let pass = 0; pass < 2; pass++) {
+			for (const t of terms) {
+				const delta = X[t.v] - X[t.u] - t.off;
+				if (Math.abs(delta) < 1e-9 || Math.abs(delta) > 2.5) { continue; }
+				const keep = X[t.v];
+				X[t.v] = X[t.u] + t.off;
+				if (holds(t.v)) { continue; }
+				X[t.v] = keep;
+				const keepU = X[t.u];
+				X[t.u] = X[t.v] - t.off;
+				if (!holds(t.u)) { X[t.u] = keepU; }
+			}
+		}
+		tighten();
+		settle();
+		for (const it of items) { it.x = X[it.v]; }
+		for (const g of liveGroups) { g.lo = X[g.vLo]; g.hi = X[g.vHi]; }
+	}
+
+	// ---- channel tracks -----------------------------------------------------------------------------
+
+	/**
+	 * Give each bent connector in a gap a track to turn in. Two connectors whose turns overlap never
+	 * share a track; among the orders that satisfy that, the one with the fewest crossings wins.
+	 * Returns the number of tracks used; sets `track` on each connector.
+	 */
+	function assignTracks(bent, S) {
+		const n = bent.length;
+		if (!n) { return 0; }
+		// i before j (i turns closer to the source rank): its inbound stub crosses j's turn when it
+		// lands inside j's span, and j's outbound stub crosses i's turn when it starts inside i's.
+		const inside = (v, c) => v > c.lo + 0.5 && v < c.hi - 0.5;
+		// ...and when i's inbound stub and j's outbound stub lie on (nearly) the same line, i turning
+		// first lays one on top of the other. That is worse than a crossing: two connectors that
+		// run along each other read as one.
+		const along = (u, v) => Math.abs(u - v) < 4;
+		const cost = (order) => {
+			let x = 0;
+			for (let i = 0; i < order.length; i++) {
+				for (let j = i + 1; j < order.length; j++) {
+					const p = order[i], q = order[j];
+					if (inside(p.cb, q)) { x++; }
+					if (inside(q.ca, p)) { x++; }
+					if (along(p.cb, q.ca)) { x += 4; }
+				}
+			}
+			return x;
+		};
+		let order = bent.slice().sort((p, q) => (p.lo - q.lo) || (p.hi - q.hi));
+		if (n <= 7) {
+			let best = order, bestCost = cost(order);
+			const permute = (arr, k) => {
+				if (bestCost === 0) { return; }
+				if (k === arr.length) { const c = cost(arr); if (c < bestCost) { bestCost = c; best = arr.slice(); } return; }
+				for (let i = k; i < arr.length; i++) {
+					const t = arr[k]; arr[k] = arr[i]; arr[i] = t;
+					permute(arr, k + 1);
+					arr[i] = arr[k]; arr[k] = t;
+				}
+			};
+			permute(order.slice(), 0);
+			order = best;
+		} else {
+			let improved = true, guard = 0;
+			while (improved && guard++ < 60) {
+				improved = false;
+				for (let i = 0; i + 1 < order.length; i++) {
+					const before = cost(order);
+					const t = order[i]; order[i] = order[i + 1]; order[i + 1] = t;
+					if (cost(order) < before) { improved = true; } else { order[i + 1] = order[i]; order[i] = t; }
+				}
+			}
+		}
+		// Turns that do not overlap may share a track (a fan-out going up and one going down meet on one line).
+		const clear = S.track * 0.75;
+		let track = 0, current = [];
+		for (const c of order) {
+			const fits = current.every((o) => (c.lo > o.hi + clear || c.hi < o.lo - clear) && !along(c.cb, o.ca) && !along(c.ca, o.cb));
+			if (current.length && !fits) { track++; current = []; }
+			c.track = track; current.push(c);
+		}
+		return track + 1;
+	}
+
+	// ---- labels -------------------------------------------------------------------------------------
+
+	const overlap = (a, b, padBy) => !(a.x + a.w <= b.x - padBy || b.x + b.w <= a.x - padBy || a.y + a.h <= b.y - padBy || b.y + b.h <= a.y - padBy);
+	/** Does the axis-aligned segment p→q pass through rectangle r (grown by `padBy`)? */
+	function segHitsRect(p, q, r, padBy) {
+		const x0 = Math.min(p.x, q.x), x1 = Math.max(p.x, q.x), y0 = Math.min(p.y, q.y), y1 = Math.max(p.y, q.y);
+		return !(x1 <= r.x - padBy || x0 >= r.x + r.w + padBy || y1 <= r.y - padBy || y0 >= r.y + r.h + padBy);
+	}
+	/**
+	 * Does a rectangle touch a NODE — its drawn outline, not its bounding box? A diamond's box has
+	 * four empty corners, and a label tucked into one of them is beside the node, not on it.
+	 */
+	function rectHitsNode(rc, n, padBy) {
+		if (!overlap(rc, n, padBy)) { return false; }
+		if (n.shape !== 'decision') { return true; }
+		const cx = n.x + n.w / 2, cy = n.y + n.h / 2, hw = n.w / 2 + padBy, hh = n.h / 2 + padBy;
+		// the point of the rectangle nearest the diamond's centre decides it
+		const px = Math.max(rc.x, Math.min(cx, rc.x + rc.w)), py = Math.max(rc.y, Math.min(cy, rc.y + rc.h));
+		return Math.abs(px - cx) / hw + Math.abs(py - cy) / hh <= 1;
+	}
+
+	/**
+	 * A group's name sits in the top-left of its frame — which, when the flow runs down, is exactly
+	 * where connectors come in. A name with a line through it is slid along the top of the frame to
+	 * the nearest clear stretch; if the frame has none, it stays where it was and is marked to be
+	 * backed, so the line passes behind it and the name still reads. Runs before the edge labels are
+	 * placed, so they keep clear of wherever the name ends up.
+	 */
+	function placeGroupLabels(groups, edges, warnings) {
+		const CLEAR = NAME_CLEAR - 1;
+		for (const g of groups) {
+			const y = g.labelY, h = g.labelH, w = g.labelW;
+			const lo = g.labelX, hi = g.x + g.w - (g.labelX - g.x) - w;   // from the left inset to the same inset on the right
+			const crossed = (x) => {
+				const rc = { x, y, w, h };
+				for (const e of edges) { for (let i = 0; i + 1 < e.points.length; i++) { if (segHitsRect(e.points[i], e.points[i + 1], rc, 2)) { return true; } } }
+				return false;
+			};
+			if (!crossed(lo)) { continue; }
+			// The places worth trying: just past each line that comes through the name's row, and the far end.
+			const cands = [hi];
+			for (const e of edges) {
+				for (let i = 0; i + 1 < e.points.length; i++) {
+					const p = e.points[i], q = e.points[i + 1];
+					if (Math.abs(p.x - q.x) > 0.02) { continue; }   // a line running ALONG the row cannot be stepped past
+					if (Math.max(p.y, q.y) <= y - 2 || Math.min(p.y, q.y) >= y + h + 2) { continue; }
+					cands.push(p.x + CLEAR, p.x - CLEAR - w);
+				}
+			}
+			const clear = cands.filter((x) => x >= lo - 0.01 && x <= hi + 0.01).sort((a, b) => a - b).find((x) => !crossed(x));
+			if (clear !== undefined) { g.labelX = clear; continue; }
+			g.labelHalo = true;
+			// How far the leftmost line through the name would have to move to clear it (layoutDir decides
+			// whether that is worth doing). A line running along the row cannot be moved aside at all.
+			let need = 0;
+			for (const e of edges) {
+				for (let i = 0; i + 1 < e.points.length; i++) {
+					const p = e.points[i], q = e.points[i + 1];
+					if (!segHitsRect(p, q, { x: lo, y, w, h }, 2)) { continue; }
+					need = Math.max(need, Math.abs(p.x - q.x) > 0.02 ? Infinity : lo + w + CLEAR - p.x);
+				}
+			}
+			g.labelNeed = need;
+			warnings.push({ cls: 'group-label-backed', message: 'group ' + g.id + ': a connector runs behind its name' });
+		}
+	}
+
+	/**
+	 * Put each edge label BESIDE its line. Candidates are stepped along every run of the route
+	 * (above and below a horizontal run, left and right of a vertical one) and scored by what they
+	 * would touch; the cleanest wins, with a preference for the run that carries the arrowhead. The
+	 * labels with the fewest clean options choose first. A label that cannot be placed clear of
+	 * everything is still placed — with a halo so it stays legible — and reported, never dropped.
+	 */
+	function placeLabels(edges, nodes, groups, S, warnings, right) {
+		const groupLabels = groups.map((g) => ({ x: g.labelX, y: g.labelY, w: g.labelW, h: g.labelH }));
+		const STEP = 8;
+		const side = S.labelSideGap != null ? S.labelSideGap : S.labelGap + 1;   // beside a vertical run
+		const jobs = [];
+		for (const e of edges) {
+			const lab = e._e && e._e.label;
+			if (!lab) { continue; }
+			const cands = [];
+			const pts = e.points;
+			const last = pts.length - 2;
+			for (let i = 0; i + 1 < pts.length; i++) {
+				const p = pts[i], q = pts[i + 1];
+				const horizontal = Math.abs(p.y - q.y) < 0.01;
+				const runPen = i === last ? 0 : 4;
+				// keep clear of the arrowhead on the last run, and of the corner on any run
+				const headLo = (i === last && (horizontal ? q.x < p.x : q.y < p.y)) ? S.arrow + 4 : 3;
+				const headHi = (i === last && (horizontal ? q.x > p.x : q.y > p.y)) ? S.arrow + 4 : 3;
+				if (horizontal) {
+					const lo = Math.min(p.x, q.x) + headLo, hi = Math.max(p.x, q.x) - headHi;
+					const room = (hi - lo) - lab.w;
+					const prefer = i === last ? (q.x > p.x ? hi - lab.w : lo) : lo + room / 2;
+					const xs = [];
+					if (room >= 0) { for (let x = lo; x <= lo + room + 0.01; x += STEP) { xs.push(x); } xs.push(lo + room); xs.push(lo + room / 2); }
+					else { xs.push(lo + room / 2); }
+					for (const x of xs) {
+						const far = Math.abs(x - prefer) * 0.02 + (room < 0 ? 40 : 0);
+						cands.push({ x, y: p.y - S.labelGap - lab.h, pen: runPen + far });
+						cands.push({ x, y: p.y + S.labelGap, pen: runPen + far + 6 });
+					}
+				} else {
+					const lo = Math.min(p.y, q.y) + headLo, hi = Math.max(p.y, q.y) - headHi;
+					const room = (hi - lo) - lab.h;
+					if (room < -4) { continue; }
+					const ys = [];
+					for (let y = lo; y <= lo + Math.max(0, room) + 0.01; y += STEP) { ys.push(y); }
+					ys.push(lo + room / 2);
+					const prefer = lo + room / 2;
+					for (const y of ys) {
+						const far = Math.abs(y - prefer) * 0.02;
+						cands.push({ x: p.x + side, y, pen: runPen + far + (right ? 8 : 1) });
+						cands.push({ x: p.x - side - lab.w, y, pen: runPen + far + (right ? 10 : 3) });
+					}
+				}
+			}
+			// A long edge reserved clear space above its line in one rank; that spot goes first.
+			if (e._host) {
+				cands.push(right
+					? { x: e._host.x - lab.w / 2, y: e._host.y - S.labelGap - lab.h, pen: -2 }
+					: { x: e._host.x - side - lab.w, y: e._host.y - lab.h / 2, pen: -2 });
+			}
+			if (!cands.length) { const p = pts[0]; cands.push({ x: p.x + 4, y: p.y - S.labelGap - lab.h, pen: 50 }); }
+			// what each candidate touches that will not move: nodes, lines, frames
+			for (const c of cands) {
+				const rc = { x: c.x, y: c.y, w: lab.w, h: lab.h };
+				let score = c.pen;
+				for (const n of nodes) { if (rectHitsNode(rc, n, 3)) { score += 1000; } }
+				for (const g of groupLabels) { if (overlap(rc, g, 3)) { score += 600; } }
+				for (const g of groups) {
+					// a label straddling a group's border reads as belonging to neither side
+					const inside = rc.x >= g.x + 2 && rc.x + rc.w <= g.x + g.w - 2 && rc.y >= g.y + 2 && rc.y + rc.h <= g.y + g.h - 2;
+					if (!inside && overlap(rc, g, 0)) { score += 40; }
+				}
+				for (const o of edges) {
+					for (let i = 0; i + 1 < o.points.length; i++) {
+						if (segHitsRect(o.points[i], o.points[i + 1], rc, o === e ? 1 : 2)) { score += 300; }
+					}
+				}
+				c.rc = rc; c.fixed = score;
+			}
+			jobs.push({ e, lab, cands, clean: cands.filter((c) => c.fixed < 300).length });
+		}
+		jobs.sort((p, q) => (p.clean - q.clean) || (p.e.index - q.e.index));
+		const placed = [];
+		for (const job of jobs) {
+			let best = null;
+			for (const c of job.cands) {
+				let score = c.fixed;
+				for (const o of placed) { if (overlap(c.rc, o, 4)) { score += 1000; } }
+				if (!best || score < best.score) { best = { rc: c.rc, score }; }
+			}
+			job.e.label = { text: job.lab.text, x: best.rc.x, y: best.rc.y, w: job.lab.w, h: job.lab.h, halo: best.score >= 300 };
+			if (best.score >= 300) { warnings.push({ cls: 'label-collision', message: 'edge ' + job.e.index + ': no clear spot for its label' }); }
+			placed.push(best.rc);
+		}
+	}
+
+	// ---- the layout layer's own check ----------------------------------------------------------------
+
+	/**
+	 * "No text overflow, overlap or out-of-frame content." Returns what is wrong with a geometry —
+	 * empty when it is clean. The renderer logs these; the tests assert there are none.
+	 */
+	function inspect(geo) {
+		const out = [];
+		const ns = geo.nodes;
+		for (let i = 0; i < ns.length; i++) {
+			for (let j = i + 1; j < ns.length; j++) {
+				if (overlap(ns[i], ns[j], 1)) { out.push({ cls: 'node-overlap', message: ns[i].id + ' overlaps ' + ns[j].id }); }
+			}
+		}
+		for (const n of ns) {
+			if (n.x < 0 || n.y < 0 || n.x + n.w > geo.width || n.y + n.h > geo.height) { out.push({ cls: 'out-of-frame', message: 'node ' + n.id }); }
+			for (const l of n.lines) { if (l.w > n.w + 0.5) { out.push({ cls: 'text-overflow', message: 'node ' + n.id + ': "' + l.text + '"' }); } }
+		}
+		for (const e of geo.edges) {
+			for (const p of e.points) { if (p.x < 0 || p.y < 0 || p.x > geo.width || p.y > geo.height) { out.push({ cls: 'out-of-frame', message: 'edge ' + e.index }); break; } }
+			for (let i = 0; i + 1 < e.points.length; i++) {
+				const p = e.points[i], q = e.points[i + 1];
+				if (Math.abs(p.x - q.x) > 0.02 && Math.abs(p.y - q.y) > 0.02) { out.push({ cls: 'diagonal', message: 'edge ' + e.index + ' is not orthogonal' }); }
+				for (const n of ns) {
+					// A connector touches the two nodes it joins — with its first and last run only —
+					// and nothing else.
+					const own = n.id === e.from || n.id === e.to;
+					const terminal = i === 0 || i === e.points.length - 2;
+					if (own && (terminal || e.loop)) { continue; }
+					if (segHitsRect(p, q, n, -1)) { out.push({ cls: 'edge-through-node', message: 'edge ' + e.index + ' crosses ' + n.id }); }
+				}
+			}
+			if (e.label) {
+				for (const n of ns) { if (rectHitsNode(e.label, n, 0)) { out.push({ cls: 'label-on-node', message: 'edge ' + e.index + ' label on ' + n.id }); } }
+				if (e.label.x < 0 || e.label.y < 0 || e.label.x + e.label.w > geo.width || e.label.y + e.label.h > geo.height) { out.push({ cls: 'out-of-frame', message: 'label of edge ' + e.index }); }
+			}
+		}
+		// "Never share a segment": two connectors may cross, but never run along each other.
+		const runs = [];
+		for (const e of geo.edges) {
+			for (let i = 0; i + 1 < e.points.length; i++) {
+				const p = e.points[i], q = e.points[i + 1];
+				const hz = Math.abs(p.y - q.y) < 0.02;
+				runs.push({ e: e.index, hz, at: hz ? p.y : p.x, lo: Math.min(hz ? p.x : p.y, hz ? q.x : q.y), hi: Math.max(hz ? p.x : p.y, hz ? q.x : q.y) });
+			}
+		}
+		for (let i = 0; i < runs.length; i++) {
+			for (let j = i + 1; j < runs.length; j++) {
+				const a = runs[i], b = runs[j];
+				if (a.e === b.e || a.hz !== b.hz || Math.abs(a.at - b.at) > 0.75) { continue; }
+				if (Math.min(a.hi, b.hi) - Math.max(a.lo, b.lo) > 1.5) { out.push({ cls: 'shared-segment', message: 'edges ' + a.e + ' and ' + b.e + ' run along each other' }); }
+			}
+		}
+		const gs = geo.groups;
+		const inside = (inner, outer) => inner.x >= outer.x - 0.5 && inner.y >= outer.y - 0.5 && inner.x + inner.w <= outer.x + outer.w + 0.5 && inner.y + inner.h <= outer.y + outer.h + 0.5;
+		for (let i = 0; i < gs.length; i++) {
+			for (let j = i + 1; j < gs.length; j++) {
+				if (overlap(gs[i], gs[j], 0) && !inside(gs[i], gs[j]) && !inside(gs[j], gs[i])) { out.push({ cls: 'group-overlap', message: gs[i].id + ' overlaps ' + gs[j].id }); }
+			}
+			if (gs[i].labelW + 8 > gs[i].w) { out.push({ cls: 'text-overflow', message: 'group ' + gs[i].id + ' label' }); }
+			else if (gs[i].labelX < gs[i].x - 0.5 || gs[i].labelX + gs[i].labelW > gs[i].x + gs[i].w + 0.5) { out.push({ cls: 'out-of-frame', message: 'the name of group ' + gs[i].id }); }
+		}
+		// A group's name is text like any other: no connector runs through it. (One marked to be backed
+		// is drawn over the line on purpose, and reported separately.)
+		for (const g of gs) {
+			if (g.labelHalo) { continue; }
+			const rc = { x: g.labelX, y: g.labelY, w: g.labelW, h: g.labelH };
+			for (const e of geo.edges) {
+				for (let i = 0; i + 1 < e.points.length; i++) {
+					if (segHitsRect(e.points[i], e.points[i + 1], rc, 1)) { out.push({ cls: 'group-label-crossed', message: 'edge ' + e.index + ' runs through the name of group ' + g.id }); break; }
+				}
+			}
+		}
+		// a node is inside every group it belongs to, and outside every other
+		const parentOf = new Map(gs.map((g) => [g.id, g.parent]));
+		for (const n of ns) {
+			const mine = new Set();
+			for (let g = n.group, hops = 0; g && hops < 16; g = parentOf.get(g), hops++) { mine.add(g); }
+			for (const g of gs) {
+				if (mine.has(g.id)) { if (!inside(n, g)) { out.push({ cls: 'member-outside-group', message: n.id + ' is outside ' + g.id }); } }
+				else if (overlap(n, g, 0)) { out.push({ cls: 'stranger-in-group', message: n.id + ' sits inside ' + g.id }); }
+			}
+		}
+		return out;
+	}
+
+	return { layout, inspect, nodeSize, outline, assignTracks, simplify };
+}));
diff --git a/extensions/levelcode-ai/diagram/theme.js b/extensions/levelcode-ai/diagram/theme.js
new file mode 100644
index 0000000..7beb8b2
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/theme.js
@@ -0,0 +1,198 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · the house style  (docs/RICH-DIAGRAMS.md, "Style guide")
+ *
+ *  ONE module owns every visual decision a diagram makes: the type scale, the box geometry, the
+ *  spacing the layout reserves, and the colours. The layout reads the numbers, the painter reads the
+ *  class names, the webview injects css(), and an exported file embeds css(resolved) — so the rule
+ *  "the same style whichever model drew it" has exactly one place it can drift.
+ *
+ *  Colours are EDITOR THEME TOKENS, never literals: a diagram is drawn with `var(--lcd-*)`, and those
+ *  are defined from `--vscode-*`. Switching the editor theme therefore restyles every diagram already
+ *  on screen without re-rendering anything — nothing is baked in until the moment a file is exported.
+ *
+ *  Loads in Node (require) and in the chat webview (inlined by diagram/bundle.js) — no dependencies.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+(function (root, factory) {
+	'use strict';
+	if (typeof module === 'object' && module.exports) { module.exports = factory(); }
+	else { (root.LCDiagram = root.LCDiagram || {}).theme = factory(); }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+	'use strict';
+
+	/**
+	 * The type scale. Three sizes carry a diagram (title 15, node name 13 semibold, secondary 11.5);
+	 * edge and group labels are "secondary lines". `line` is the line box the layout reserves.
+	 */
+	const TYPE = {
+		title: { size: 15, weight: 600, line: 20 },
+		name: { size: 13, weight: 600, line: 18 },
+		sub: { size: 11.5, weight: 400, line: 16 },
+		edge: { size: 11.5, weight: 400, line: 16 },
+		group: { size: 11.5, weight: 600, line: 16 }
+	};
+	/** Nothing in a diagram is set smaller than this — the floor the style guide names. */
+	const MIN_TEXT = 10.5;
+
+	/** Box geometry: corner radius 8, border 1.25 (2 on the accent), padding 12. */
+	const BOX = {
+		radius: 8, border: 1.25, accentBorder: 2,
+		padX: 12, padY: 12,
+		textGap: 2,          // between the name line and the secondary line
+		minWidth: 64,        // a one-letter label is still a box, not a pill of padding
+		linkIcon: 14         // extra width a linked node reserves for its file glyph
+	};
+
+	/**
+	 * Everything the layout reserves between things. Kept here, not in layout.js, because these ARE
+	 * style decisions — "connectors routed through gaps" is only true if the gaps exist.
+	 */
+	const SPACE = {
+		margin: 8,           // around the whole drawing, so a 2px accent border is never clipped
+		nodeGap: 22,         // between neighbours in the same rank (across the flow)
+		rankGap: 44,         // minimum between ranks (along the flow) before channels/labels widen it
+		track: 12,           // between parallel connector segments in a channel
+		channelPad: 16,      // from a node's side to the first channel track
+		portGap: 12,         // between connectors leaving the same side of a node
+		portInset: 8,        // keep ports off the rounded corners
+		lineClear: 12,       // a connector passing a node keeps this far from its border
+		groupInset: 16,      // children sit this far inside their group
+		groupHeader: 20,     // the strip a group's label occupies above its children
+		groupGap: 14,        // between a group's border and anything outside it
+		labelGap: 5,         // "labels beside lines with a clear gap"
+		labelPad: 6,         // breathing room around an edge label when checking for collisions
+		arrow: 7,            // arrowhead length
+		arrowHalf: 3.6,      // arrowhead half-width
+		selfLoop: 16         // how far a self-loop steps out of its node
+	};
+
+	/**
+	 * The live token map: `--lcd-*` custom properties, each defined from editor theme variables.
+	 * Neutral boxes and ONE accent — the accent is the theme's link colour because that is the one
+	 * hue every theme guarantees is legible on the editor background.
+	 */
+	const TOKENS = {
+		fg: 'var(--vscode-foreground)',
+		bg: 'var(--vscode-editor-background)',
+		muted: 'var(--vscode-descriptionForeground, color-mix(in srgb, var(--vscode-foreground) 68%, transparent))',
+		line: 'color-mix(in srgb, var(--vscode-foreground) 56%, transparent)',
+		'node-fill': 'color-mix(in srgb, var(--vscode-foreground) 5%, transparent)',
+		'node-stroke': 'color-mix(in srgb, var(--vscode-foreground) 36%, transparent)',
+		accent: 'var(--vscode-textLink-foreground, var(--vscode-focusBorder, #4c8dff))',
+		'accent-fill': 'color-mix(in srgb, var(--vscode-textLink-foreground, var(--vscode-focusBorder, #4c8dff)) 14%, transparent)',
+		'group-fill': 'color-mix(in srgb, var(--vscode-foreground) 3.5%, transparent)',
+		'group-stroke': 'color-mix(in srgb, var(--vscode-foreground) 17%, transparent)',
+		font: 'var(--vscode-font-family, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif)'
+	};
+	const TOKEN_NAMES = Object.keys(TOKENS);
+
+	/**
+	 * Concrete palettes — used ONLY where there is no editor to ask: the Node-side snapshot tests, the
+	 * docs, and as the fallback when an export cannot read computed styles. The live view never
+	 * touches these.
+	 */
+	const PALETTES = {
+		light: {
+			fg: '#1f2328', bg: '#ffffff', muted: '#59636e', line: '#7d8590',
+			'node-fill': '#f4f5f6', 'node-stroke': '#aeb4bb',
+			accent: '#0969da', 'accent-fill': '#ddebfb',
+			'group-fill': '#f8f9fa', 'group-stroke': '#d5d9de',
+			font: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif'
+		},
+		dark: {
+			fg: '#d4d7dc', bg: '#1e1f22', muted: '#9198a1', line: '#8b929b',
+			'node-fill': '#27292d', 'node-stroke': '#5f666f',
+			accent: '#4c9aff', 'accent-fill': '#1f3350',
+			'group-fill': '#232528', 'group-stroke': '#3a3e44',
+			font: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif'
+		}
+	};
+
+	/**
+	 * The stylesheet, generated from the tables above.
+	 *
+	 *   css()                     live: rules read `var(--lcd-*)`, and `.lcd` defines them from the theme.
+	 *   css({ resolved: {...} })  export: every token replaced by a concrete value, scoped to `svg.lcd-svg`
+	 *                             so the block can sit inside a standalone SVG file.
+	 *
+	 * Selectors are all class-based and prefixed `lcd-`, so nothing here can reach the rest of the chat.
+	 * @param {{ resolved?: Record<string,string> }} [opts]
+	 */
+	function css(opts) {
+		const resolved = opts && opts.resolved;
+		const v = (name) => (resolved ? String(resolved[name] != null ? resolved[name] : PALETTES.light[name]) : 'var(--lcd-' + name + ')');
+		const scope = resolved ? 'svg.lcd-svg' : '.lcd';
+		const t = TYPE;
+		const out = [];
+		if (!resolved) {
+			out.push(scope + ' {' + TOKEN_NAMES.map((n) => ' --lcd-' + n + ': ' + TOKENS[n] + ';').join('') + ' }');
+			// High-contrast themes ask for real borders, not tints.
+			out.push('body.vscode-high-contrast ' + scope + ', body.vscode-high-contrast-light ' + scope
+				+ ' { --lcd-node-stroke: var(--vscode-contrastBorder, var(--vscode-foreground));'
+				+ ' --lcd-group-stroke: var(--vscode-contrastBorder, var(--vscode-foreground));'
+				+ ' --lcd-line: var(--vscode-foreground); --lcd-node-fill: transparent; --lcd-group-fill: transparent; }');
+		}
+		const text = (cls, type, fill) => scope + ' .' + cls + ' { font-family: ' + v('font') + '; font-size: ' + type.size + 'px; font-weight: '
+			+ type.weight + '; fill: ' + v(fill) + '; }';
+		out.push(
+			scope + ' .lcd-bg { fill: ' + v('bg') + '; }',
+			scope + ' text { font-family: ' + v('font') + '; }',
+			text('lcd-title', t.title, 'fg'),
+			text('lcd-name', t.name, 'fg'),
+			text('lcd-sub', t.sub, 'muted'),
+			text('lcd-edge-label', t.edge, 'muted'),
+			text('lcd-group-label', t.group, 'muted'),
+			scope + ' .lcd-shape { fill: ' + v('node-fill') + '; stroke: ' + v('node-stroke') + '; stroke-width: ' + BOX.border + 'px; stroke-linejoin: round; }',
+			scope + ' .lcd-accent .lcd-shape { fill: ' + v('accent-fill') + '; stroke: ' + v('accent') + '; stroke-width: ' + BOX.accentBorder + 'px; }',
+			scope + ' .lcd-node .lcd-lid { fill: none; }',
+			scope + ' .lcd-group-box { fill: ' + v('group-fill') + '; stroke: ' + v('group-stroke') + '; stroke-width: 1px; }',
+			scope + ' .lcd-edge { fill: none; stroke: ' + v('line') + '; stroke-width: 1.25px; stroke-linejoin: round; stroke-linecap: round; }',
+			scope + ' .lcd-edge.lcd-dashed { stroke-dasharray: 5 4; }',
+			scope + ' .lcd-arrow { fill: ' + v('line') + '; stroke: ' + v('line') + '; stroke-width: 1px; stroke-linejoin: round; }',
+			scope + ' .lcd-link-icon { fill: none; stroke: ' + v('muted') + '; stroke-width: 1px; stroke-linejoin: round; }',
+			// The halo is the LAST resort of label placement (a label that had nowhere clear to sit):
+			// it keeps the text legible over a line it could not avoid.
+			scope + ' .lcd-halo { paint-order: stroke; stroke: ' + v('bg') + '; stroke-width: 4px; stroke-linejoin: round; }'
+		);
+		if (!resolved) {
+			out.push(
+				scope + ' .lcd-linked { cursor: pointer; }',
+				scope + ' .lcd-linked:hover .lcd-shape, ' + scope + ' .lcd-linked:focus-visible .lcd-shape { stroke: ' + v('accent') + '; }',
+				scope + ' .lcd-linked:hover .lcd-link-icon, ' + scope + ' .lcd-linked:focus-visible .lcd-link-icon { stroke: ' + v('accent') + '; }',
+				scope + ' .lcd-linked:focus { outline: none; }'
+			);
+		}
+		return out.join('\n');
+	}
+
+	// ---- text measurement without a browser ----------------------------------------------------
+	// The webview measures with a canvas and the real UI font. Node has neither, so tests, the ASCII
+	// renderer and the host's size estimates use this table: per-character advance in em, calibrated
+	// against a system UI sans. It errs slightly WIDE, because the failure that matters is text
+	// overflowing its box, not a box two pixels too roomy.
+	const NARROW = new Set(Array.from("iIl.,:;'|!jtfr()[]{}` "));
+	const WIDE = new Set(Array.from('mwMW@%&'));
+	function charEm(ch) {
+		if (NARROW.has(ch)) { return 0.33; }
+		if (WIDE.has(ch)) { return 0.88; }
+		const c = ch.codePointAt(0) || 0;
+		if (c >= 0x30 && c <= 0x39) { return 0.60; }          // digits
+		if (c >= 0x41 && c <= 0x5a) { return 0.69; }          // A–Z
+		if (c >= 0x2e80) { return 1.0; }                      // CJK and other full-width scripts
+		if (c > 0xffff) { return 1.1; }                       // emoji / astral
+		return 0.57;
+	}
+	/**
+	 * Approximate rendered width, in px, of `text` set in the role's type.
+	 * @param {string} text
+	 * @param {keyof typeof TYPE} role
+	 */
+	function approxMeasure(text, role) {
+		const ty = TYPE[role] || TYPE.sub;
+		let em = 0;
+		for (const ch of Array.from(String(text == null ? '' : text))) { em += charEm(ch); }
+		return Math.ceil(em * ty.size * (ty.weight >= 600 ? 1.045 : 1) * 10) / 10;
+	}
+
+	return { TYPE, MIN_TEXT, BOX, SPACE, TOKENS, TOKEN_NAMES, PALETTES, css, approxMeasure };
+}));
diff --git a/extensions/levelcode-ai/test/diagramLayout.test.js b/extensions/levelcode-ai/test/diagramLayout.test.js
new file mode 100644
index 0000000..93c23ad
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramLayout.test.js
@@ -0,0 +1,432 @@
+/*---------------------------------------------------------------------------------------------
+ *  Rich diagrams — layout — run: node test/diagramLayout.test.js
+ *
+ *  docs/RICH-DIAGRAMS.md: the model decides what connects to what; the renderer decides where
+ *  everything goes, the same way every time. So the layout is tested as GEOMETRY: boxes never
+ *  overlap, a connector never passes through a box it does not join, lines are orthogonal and never
+ *  run along one another, a group's frame holds its members and nothing else, labels sit beside
+ *  lines, and all of it fits the frame — for the diagrams the feature exists for, and for a few
+ *  thousand random ones nobody would draw on purpose.
+ *
+ *  Text is measured with theme.approxMeasure here (the webview uses a canvas), so every number in
+ *  this file is deterministic on any machine.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const L = require('../diagram/layout');
+const R = require('../diagram/repair');
+const theme = require('../diagram/theme');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+const gallery = JSON.parse(fs.readFileSync(path.join(__dirname, 'fixtures', 'diagrams', 'gallery.json'), 'utf8'));
+const spec = (name) => R.prepare(gallery.find((g) => g.name === name).spec).spec;
+const byId = (geo, id) => geo.nodes.find((x) => x.id === id);
+const edge = (geo, from, to) => geo.edges.find((e) => e.from === from && e.to === to);
+/** The hard rules. A label or a group's name that had to be backed is reported separately — it is legible, just not ideal. */
+const HARD = (w) => w.cls !== 'label-collision' && w.cls !== 'shared-segment' && w.cls !== 'group-label-backed';
+/** Does any connector run through this rectangle (with `pad` to spare)? Measured here, not asked of the layout. */
+const lineThrough = (geo, rc, pad) => geo.edges.some((e) => e.points.some((p, i) => {
+	const q = e.points[i + 1]; if (!q) { return false; }
+	return !(Math.max(p.x, q.x) <= rc.x - pad || Math.min(p.x, q.x) >= rc.x + rc.w + pad || Math.max(p.y, q.y) <= rc.y - pad || Math.min(p.y, q.y) >= rc.y + rc.h + pad);
+}));
+const nameOf = (g) => ({ x: g.labelX, y: g.labelY, w: g.labelW, h: g.labelH });
+
+test('EXAMPLE: the spec\'s routing flow — three ranks, the fork centred on its source, nothing flagged', () => {
+	const geo = L.layout(spec('jev'));
+	assert.deepStrictEqual(geo.warnings, []);
+	assert.strictEqual(geo.direction, 'right');
+	assert.strictEqual(geo.ranks, 3);
+	assert.strictEqual(geo.crossings, 0);
+	const inn = byId(geo, 'in'), jev = byId(geo, 'jev'), bill = byId(geo, 'bill'), rev = byId(geo, 'rev');
+	assert.ok(inn.x + inn.w < jev.x && jev.x + jev.w < bill.x, 'the flow reads left to right');
+	assert.strictEqual(inn.cy, jev.cy, 'a single connector is a straight line');
+	assert.deepStrictEqual(edge(geo, 'in', 'jev').points.length, 2, 'in → jev has no bends');
+	assert.ok(bill.cy < jev.cy && jev.cy < rev.cy, 'the two outcomes sit either side of the classifier');
+	assert.ok(Math.abs((bill.cy + rev.cy) / 2 - jev.cy) < 0.01, 'and it is centred on them exactly');
+	assert.ok(jev.accent && !inn.accent);
+});
+
+test('LABELS: an edge label sits BESIDE its line, clear of it, and nowhere near a box', () => {
+	const geo = L.layout(spec('jev'));
+	for (const e of geo.edges.filter((x) => x.label)) {
+		assert.strictEqual(e.label.halo, false, 'no fallback needed');
+		const last = e.points[e.points.length - 1], prev = e.points[e.points.length - 2];
+		assert.strictEqual(prev.y, last.y, 'the run into the target is horizontal');
+		assert.ok(e.label.y + e.label.h <= last.y - 3, 'the label is ABOVE that run with a clear gap, never on it');
+		assert.ok(e.label.x >= Math.min(prev.x, last.x) && e.label.x + e.label.w <= Math.max(prev.x, last.x), 'and within its length');
+		for (const node of geo.nodes) {
+			const apart = e.label.x + e.label.w <= node.x || node.x + node.w <= e.label.x || e.label.y + e.label.h <= node.y || node.y + node.h <= e.label.y;
+			assert.ok(apart, 'label "' + e.label.text + '" touches ' + node.id);
+		}
+	}
+	assert.strictEqual(edge(geo, 'jev', 'bill').label.text, '0.90 or more');
+});
+
+test('GALLERY: every realistic diagram lays out with nothing flagged at all', () => {
+	for (const g of gallery) {
+		const p = R.prepare(g.spec);
+		assert.ok(p.status === 'ok' || p.status === 'fixed', g.name + ' is a valid spec: ' + JSON.stringify(p.errors));
+		const geo = L.layout(p.spec);
+		assert.deepStrictEqual(geo.warnings, [], g.name);
+		assert.strictEqual(geo.crossings, 0, g.name + ': these can all be drawn without a crossing');
+		assert.ok(geo.width > 0 && geo.height > 0);
+		assert.strictEqual(geo.nodes.length, p.spec.nodes.length);
+		assert.strictEqual(geo.edges.length, p.spec.edges.length, g.name + ': every edge is drawn');
+	}
+});
+
+test('GALLERY: …and at the widths a chat panel really has, where most of them turn downward', () => {
+	for (const g of gallery) {
+		for (const maxWidth of [560, 420, 320]) {
+			const geo = L.layout(R.prepare(g.spec).spec, { maxWidth });
+			assert.deepStrictEqual(geo.warnings, [], g.name + ' at ' + maxWidth + 'px (' + geo.direction + ')');
+			for (const grp of geo.groups) { assert.strictEqual(lineThrough(geo, nameOf(grp), 2), false, g.name + ' at ' + maxWidth + 'px: a connector runs through the name of ' + grp.id); }
+		}
+	}
+});
+
+test('DETERMINISM: the same spec is the same picture, every time', () => {
+	for (const g of gallery) {
+		const a = L.layout(R.prepare(g.spec).spec), b = L.layout(R.prepare(g.spec).spec);
+		assert.deepStrictEqual(a, b, g.name);
+	}
+});
+
+test('DIRECTION: "down" is the same layout turned — ranks run top to bottom', () => {
+	const s = spec('jev'); s.direction = 'down';
+	const geo = L.layout(s);
+	assert.deepStrictEqual(geo.warnings, []);
+	assert.strictEqual(geo.direction, 'down');
+	const inn = byId(geo, 'in'), jev = byId(geo, 'jev'), bill = byId(geo, 'bill'), rev = byId(geo, 'rev');
+	assert.ok(inn.y + inn.h < jev.y && jev.y + jev.h < bill.y, 'the flow reads top to bottom');
+	assert.strictEqual(inn.cx, jev.cx);
+	assert.strictEqual(bill.cy, rev.cy, 'siblings share a row');
+	assert.ok(Math.abs((bill.cx + rev.cx) / 2 - jev.cx) < 0.01);
+	const e = edge(geo, 'in', 'jev');
+	assert.deepStrictEqual([e.arrow.dx, e.arrow.dy], [0, 1], 'arrowheads point down the flow');
+});
+
+test('FIT: a flow too wide for the column is laid out downward instead — when that helps', () => {
+	const chain = { title: 'T', direction: 'right', nodes: Array.from({ length: 8 }, (_, i) => ({ id: 'n' + i, label: 'Pipeline stage ' + (i + 1) })), edges: Array.from({ length: 7 }, (_, i) => ({ from: 'n' + i, to: 'n' + (i + 1) })) };
+	const s = R.prepare(chain).spec;
+	const wide = L.layout(s);
+	assert.strictEqual(wide.direction, 'right');
+	assert.strictEqual(wide.flipped, false);
+	assert.ok(wide.width > 900, 'eight boxes in a row are wide: ' + wide.width);
+	const fit = L.layout(s, { maxWidth: 480 });
+	assert.strictEqual(fit.direction, 'down', '"Diagrams grow downward, never wider than the chat column"');
+	assert.strictEqual(fit.flipped, true);
+	assert.strictEqual(fit.asked, 'right', 'what the model asked for is still on record');
+	assert.ok(fit.width <= 480, 'and now it fits: ' + fit.width);
+	assert.deepStrictEqual(fit.warnings, []);
+	assert.strictEqual(L.layout(s, { maxWidth: 4000 }).direction, 'right', 'no flip when it already fits');
+	const down = Object.assign({}, s, { direction: 'down' });
+	assert.strictEqual(L.layout(down, { maxWidth: 10 }).flipped, false, 'a downward flow is never turned sideways');
+});
+
+test('GROUPS: a frame holds its members with room for its label, and nested frames nest', () => {
+	const geo = L.layout(spec('twelve'));
+	assert.deepStrictEqual(geo.warnings, []);
+	const frame = (id) => geo.groups.find((g) => g.id === id);
+	const inside = (a, b, pad) => a.x >= b.x + pad && a.y >= b.y + pad && a.x + a.w <= b.x + b.w - pad && a.y + a.h <= b.y + b.h - pad;
+	for (const node of geo.nodes) {
+		if (!node.group) { continue; }
+		assert.ok(inside(node, frame(node.group), theme.SPACE.groupInset - 0.01), node.id + ' sits ' + theme.SPACE.groupInset + 'px inside ' + node.group);
+	}
+	assert.ok(inside(frame('w'), frame('app'), theme.SPACE.groupInset - 0.01), 'Workers nests inside Application');
+	assert.strictEqual(frame('w').parent, 'app');
+	assert.strictEqual(frame('w').depth, 2);
+	for (const g of geo.groups) {
+		assert.ok(g.labelX >= g.x && g.labelY >= g.y, 'the label is in the top-left');
+		assert.ok(g.labelX + g.labelW <= g.x + g.w, 'and fits: ' + g.id);
+		for (const node of geo.nodes.filter((x) => x.group === g.id)) { assert.ok(node.y >= g.labelY + g.labelH, node.id + ' is below the label of ' + g.id); }
+	}
+	const stripe = byId(geo, 'ext');
+	for (const g of geo.groups) { assert.ok(!(stripe.x < g.x + g.w && g.x < stripe.x + stripe.w && stripe.y < g.y + g.h && g.y < stripe.y + stripe.h), 'a node in no group is inside none'); }
+});
+
+test('GROUPS: a long group label widens its frame instead of spilling out of it', () => {
+	const s = R.prepare({ title: 'T', groups: [{ id: 'g', label: 'A container with a long name' }], nodes: [{ id: 'a', label: 'A', group: 'g' }, { id: 'b', label: 'B' }], edges: [{ from: 'a', to: 'b' }] }).spec;
+	for (const direction of ['right', 'down']) {
+		const geo = L.layout(Object.assign({}, s, { direction }));
+		assert.deepStrictEqual(geo.warnings, [], direction);
+		const g = geo.groups[0];
+		assert.ok(g.w >= g.labelW + 16, direction + ': frame ' + g.w + ' vs label ' + g.labelW);
+	}
+});
+
+test('GROUP NAMES: a connector never runs through one — the name slides along its frame to a clear stretch', () => {
+	// The architecture diagram, turned downward: the line into "Anthropic" comes in exactly where "Providers" would sit.
+	const geo = L.layout(spec('arch'), { maxWidth: 420 });
+	assert.strictEqual(geo.direction, 'down');
+	const prov = geo.groups.find((g) => g.id === 'prov'), ext = geo.groups.find((g) => g.id === 'ext');
+	const corner = (g) => g.x + theme.SPACE.groupInset - 4;
+	assert.strictEqual(ext.labelX, corner(ext), 'a name nothing crosses stays in its corner');
+	assert.ok(prov.labelX > corner(prov) + 10, 'the crossed one has moved along: ' + (prov.labelX - corner(prov)));
+	// …to the NEAREST clear stretch — it starts just past the line that was in its way, not at the far end of the frame
+	const into = edge(geo, 'reg', 'ant'), lineX = into.points[into.points.length - 1].x;
+	assert.ok(prov.labelX - lineX >= 4 && prov.labelX - lineX <= 7, 'the name starts ' + (prov.labelX - lineX).toFixed(1) + 'px after the line into Anthropic');
+	assert.ok(prov.labelX + prov.labelW < prov.x + prov.w - 60, 'with most of the frame still to its right');
+	assert.ok(lineThrough(geo, { x: corner(prov), y: prov.labelY, w: prov.labelW, h: prov.labelH }, 2), 'and it had to — the corner has a line through it');
+	for (const g of geo.groups) {
+		assert.strictEqual(lineThrough(geo, nameOf(g), 2), false, g.id);
+		assert.strictEqual(g.labelHalo, false, g.id + ' needs no backing');
+		assert.ok(g.labelX >= g.x + 8 && g.labelX + g.labelW <= g.x + g.w - 8, g.id + ': the name is still inside its frame');
+		assert.strictEqual(g.labelY, g.y + 7, 'and still on the top row');
+		assert.ok(!('labelNeed' in g), 'working values are not part of the geometry');
+	}
+	// The same diagram left to right: lines come in through the side, the names are never in the way.
+	const right = L.layout(spec('arch'));
+	for (const g of right.groups) { assert.strictEqual(g.labelX, corner(g), g.id); }
+});
+
+test('GROUP NAMES: where the frame has no clear stretch, room is made — the line comes in beside the name — if that is cheap', () => {
+	const one = (name, node) => R.prepare({ title: 'T', direction: 'down', groups: [{ id: 'g', label: name }], nodes: [{ id: 'top', label: 'Chat webview' }, { id: 'a', label: node, group: 'g' }, { id: 'b', label: 'Next', group: 'g' }], edges: [{ from: 'top', to: 'a' }, { from: 'a', to: 'b' }] }).spec;
+	// A short name over a wide node: the line is already clear of it. Nothing to do.
+	const easy = L.layout(one('Data', 'Redis'));
+	assert.deepStrictEqual(easy.warnings, []);
+	// A name longer than half its node, in a frame one node wide: no stretch is clear.
+	const geo = L.layout(one('Extension host', 'agent.js'));
+	assert.deepStrictEqual(geo.warnings, []);
+	const g = geo.groups[0], into = edge(geo, 'top', 'a');
+	const lineX = into.points[into.points.length - 1].x;
+	assert.strictEqual(g.labelX, g.x + theme.SPACE.groupInset - 4, 'the name keeps its corner');
+	assert.strictEqual(g.labelHalo, false);
+	assert.ok(lineX >= g.labelX + g.labelW + 5, 'the line comes in ' + (lineX - g.labelX - g.labelW).toFixed(1) + 'px to the right of it');
+	assert.strictEqual(lineThrough(geo, nameOf(g), 2), false);
+	const a = byId(geo, 'a');
+	assert.ok(Math.abs(lineX - a.cx) < 0.5 && Math.abs(into.points[0].x - lineX) < 0.5, 'and still drops straight into the middle of its node');
+	// what it cost: the frame grew by less than the name is long
+	const narrow = L.layout(one('E', 'agent.js'));
+	assert.ok(g.w > narrow.groups[0].w && g.w < narrow.groups[0].w + g.labelW, 'frame ' + narrow.groups[0].w + ' → ' + g.w);
+});
+
+test('GROUP NAMES: room is made even when something stands to the left of the frame — and only for lines that come in through the top', () => {
+	// A neighbour on the left, both fed from above: the frame cannot simply reach leftward for the room.
+	const s1 = R.prepare({ title: 'T', direction: 'down', groups: [{ id: 'g', label: 'check Billing API' }], nodes: [{ id: 'top', label: 'Billing sessions' }, { id: 'gw', label: 'Gateway' }, { id: 'a', label: 'request Cache', group: 'g' }], edges: [{ from: 'top', to: 'gw' }, { from: 'top', to: 'a' }] }).spec;
+	const geo = L.layout(s1);
+	assert.deepStrictEqual(geo.warnings, []);
+	const g = geo.groups[0], gw = byId(geo, 'gw'), into = edge(geo, 'top', 'a');
+	assert.strictEqual(g.labelHalo, false);
+	assert.ok(gw.x + gw.w + theme.SPACE.groupGap <= g.x + 0.01, 'the neighbour keeps its distance from the frame');
+	assert.ok(into.points[into.points.length - 1].x >= g.labelX + g.labelW + 5, 'and the line still comes in beside the name');
+	assert.strictEqual(lineThrough(geo, nameOf(g), 2), false);
+	// A fork INSIDE the frame: those lines are nowhere near the name's row, so they spread under the name as usual.
+	const s2 = R.prepare({ title: 'T', direction: 'down', groups: [{ id: 'g', label: 'Extension host' }], nodes: [{ id: 'top', label: 'Chat' }, { id: 'a', label: 'agent', group: 'g' }, { id: 'b1', label: 'One', group: 'g' }, { id: 'b2', label: 'Two', group: 'g' }], edges: [{ from: 'top', to: 'a' }, { from: 'a', to: 'b1' }, { from: 'a', to: 'b2' }] }).spec;
+	const fork = L.layout(s2);
+	assert.deepStrictEqual(fork.warnings, []);
+	const fg = fork.groups[0], a = byId(fork, 'a'), b1 = byId(fork, 'b1'), b2 = byId(fork, 'b2');
+	assert.ok(edge(fork, 'top', 'a').points[0].x >= fg.labelX + fg.labelW + 5, 'the line from outside comes in beside the name');
+	assert.ok(b1.cx < fg.labelX + fg.labelW, 'while a child sits under the name: ' + b1.cx + ' < ' + (fg.labelX + fg.labelW));
+	assert.ok(Math.abs((b1.cx + b2.cx) / 2 - a.cx) < 0.5, 'and the fork is still centred on its source');
+});
+
+test('GROUP NAMES: …and where it is not cheap, the name is backed instead: the line passes behind it, and the layout says so', () => {
+	const s = R.prepare({ title: 'T', direction: 'down', groups: [{ id: 'g', label: 'A container with a long name' }], nodes: [{ id: 'top', label: 'Chat webview' }, { id: 'a', label: 'A', group: 'g' }], edges: [{ from: 'top', to: 'a' }] }).spec;
+	const geo = L.layout(s);
+	assert.deepStrictEqual(geo.warnings, [{ cls: 'group-label-backed', message: 'group g: a connector runs behind its name' }]);
+	const g = geo.groups[0];
+	assert.strictEqual(g.labelHalo, true);
+	assert.strictEqual(g.labelX, g.x + theme.SPACE.groupInset - 4, 'it stays in its corner');
+	assert.ok(lineThrough(geo, nameOf(g), 0), 'with the line behind it');
+	// the picture is otherwise the one it would have been: a node is not shoved aside to free a long name
+	const a = byId(geo, 'a');
+	assert.ok(Math.abs((a.x + a.w / 2) - (g.x + g.w / 2)) < 1, 'the node is still centred in its frame');
+	// the self-check would call an UNBACKED name with a line through it an error
+	const lied = JSON.parse(JSON.stringify(geo)); lied.groups[0].labelHalo = false;
+	assert.deepStrictEqual(L.inspect(lied).map((w) => w.cls), ['group-label-crossed']);
+	assert.deepStrictEqual(L.inspect(geo), [], 'and a backed one is not');
+});
+
+test('GROUP NAMES: freeing a name never pushes a drawing that fitted its column out of it', () => {
+	const s = R.prepare({ title: 'T', direction: 'down', groups: [{ id: 'g', label: 'Extension host' }], nodes: [{ id: 'top', label: 'Chat webview' }, { id: 'a', label: 'agent.js', group: 'g' }], edges: [{ from: 'top', to: 'a' }] }).spec;
+	const free = L.layout(s);
+	assert.strictEqual(free.groups[0].labelHalo, false, 'with room to spare the name is freed…');
+	// …which made the drawing a little wider. A column that the narrower drawing fits and the wider one does not:
+	const column = free.width - 4;
+	const tight = L.layout(s, { maxWidth: column });
+	assert.ok(tight.width <= column, 'the drawing fits: ' + tight.width + ' in ' + column);
+	assert.strictEqual(tight.groups[0].labelHalo, true, 'and its name is backed instead');
+	assert.deepStrictEqual(tight.warnings.map((w) => w.cls), ['group-label-backed']);
+	assert.ok(free.width > tight.width);
+	// a column wide enough for either: the freed name wins
+	assert.strictEqual(L.layout(s, { maxWidth: free.width + 40 }).groups[0].labelHalo, false);
+});
+
+test('CYCLES: the edge that closes a loop is drawn running back, and its arrow still points the right way', () => {
+	const s = R.prepare({ title: 'T', nodes: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }, { id: 'c', label: 'C' }], edges: [{ from: 'a', to: 'b' }, { from: 'b', to: 'c' }, { from: 'c', to: 'a' }] }).spec;
+	const geo = L.layout(s);
+	assert.deepStrictEqual(geo.warnings.filter(HARD), []);
+	assert.strictEqual(geo.ranks, 3, 'a → b → c still reads as three steps');
+	const a = byId(geo, 'a'), c = byId(geo, 'c');
+	assert.ok(a.x < c.x);
+	const back = edge(geo, 'c', 'a');
+	assert.strictEqual(back.back, true);
+	assert.strictEqual(edge(geo, 'a', 'b').back, false);
+	const tip = back.points[back.points.length - 1], start = back.points[0];
+	assert.ok(Math.abs(start.x - c.x) < 0.01 || Math.abs(start.x - (c.x + c.w)) < 0.01, 'it leaves c');
+	assert.ok(tip.x >= a.x - 0.01 && tip.x <= a.x + a.w + 0.01 && tip.y >= a.y && tip.y <= a.y + a.h, 'and its arrowhead lands on a');
+	assert.deepStrictEqual([back.arrow.x, back.arrow.y], [tip.x, tip.y]);
+});
+
+test('SELF-LOOP: steps out of its node and back in, without touching anything else', () => {
+	const geo = L.layout(spec('state'));
+	assert.deepStrictEqual(geo.warnings, []);
+	const loop = geo.edges.find((e) => e.loop);
+	assert.strictEqual(loop.from, 'active'); assert.strictEqual(loop.to, 'active');
+	const node = byId(geo, 'active');
+	assert.ok(loop.points.length >= 4, 'a loop has corners');
+	assert.ok(loop.points.some((p) => p.y < node.y - 4), 'it rises above the node');
+	assert.strictEqual(loop.label.text, 'new turn');
+	// two loops on one node do not draw on top of each other
+	const two = L.layout(R.prepare({ title: 'T', nodes: [{ id: 'a', label: 'Worker' }], edges: [{ from: 'a', to: 'a', label: 'retry' }, { from: 'a', to: 'a', label: 'backoff' }] }).spec);
+	assert.deepStrictEqual(two.warnings.filter((w) => w.cls === 'shared-segment'), []);
+});
+
+test('PORTS: connectors that share a side each get their own point on it — and the node grows if it must', () => {
+	const fan = L.layout(spec('fan'));
+	const router = byId(fan, 'r');
+	const starts = fan.edges.filter((e) => e.from === 'r').map((e) => e.points[0]);
+	assert.strictEqual(starts.length, 5);
+	assert.strictEqual(new Set(starts.map((p) => p.y)).size, 5, 'five connectors, five ports');
+	for (const p of starts) { assert.ok(Math.abs(p.x - (router.x + router.w)) < 0.01 && p.y > router.y && p.y < router.y + router.h, 'each on the side that faces the flow'); }
+	const gaps = starts.map((p) => p.y).sort((a, b) => a - b).map((y, i, arr) => (i ? y - arr[i - 1] : null)).slice(1);
+	assert.ok(gaps.every((g) => g >= 6 - 0.01), 'never closer than the minimum: ' + gaps.join(','));
+	// a hub with more connectors than its side can hold gets taller rather than crowding them
+	const hub = { title: 'T', nodes: [{ id: 'h', label: 'Hub' }].concat(Array.from({ length: 9 }, (_, i) => ({ id: 't' + i, label: 'T' + i }))), edges: Array.from({ length: 9 }, (_, i) => ({ from: 'h', to: 't' + i })) };
+	const big = L.layout(R.prepare(hub).spec);
+	assert.deepStrictEqual(big.warnings, []);
+	assert.ok(byId(big, 'h').h > byId(big, 't0').h, 'the hub grew along its side');
+});
+
+test('SHAPES: size comes from the measured text — and a connector stops ON a diamond\'s outline', () => {
+	const double = (t, role) => theme.approxMeasure(t, role) * 2;
+	const s = R.prepare({ title: 'T', nodes: [{ id: 'a', label: 'A fairly long label' }], edges: [] }).spec;
+	const normal = L.layout(s).nodes[0], wide = L.layout(s, { measure: double }).nodes[0];
+	assert.strictEqual(normal.w, Math.ceil(theme.approxMeasure('A fairly long label', 'name') + 2 * theme.BOX.padX), '"width from the measured longest line plus 24"');
+	assert.ok(wide.w > normal.w * 1.6, 'a wider font makes a wider box, so text never overflows');
+	const d = L.layout(spec('decision'));
+	const q = byId(d, 'q');
+	assert.strictEqual(q.shape, 'decision');
+	for (const e of d.edges.filter((x) => x.from === 'q')) {
+		const p = e.points[0];
+		const onOutline = Math.abs(p.x - q.cx) / (q.w / 2) + Math.abs(p.y - q.cy) / (q.h / 2);
+		assert.ok(Math.abs(onOutline - 1) < 0.02, 'the line leaves from the diamond\'s edge, not its bounding box (' + onOutline.toFixed(3) + ')');
+	}
+	for (const node of d.nodes) { for (const line of node.lines) { assert.ok(line.w <= node.w, node.id + ': "' + line.text + '" fits'); } }
+});
+
+test('SHAPES: a long decision label wraps to two lines so the diamond stays compact', () => {
+	const one = L.layout(R.prepare({ title: 'T', nodes: [{ id: 'a', label: 'Valid?', shape: 'decision' }], edges: [] }).spec).nodes[0];
+	const two = L.layout(R.prepare({ title: 'T', nodes: [{ id: 'a', label: 'Is the session still valid?', shape: 'decision' }], edges: [] }).spec).nodes[0];
+	assert.strictEqual(one.lines.length, 1);
+	assert.strictEqual(two.lines.length, 2);
+	assert.strictEqual(two.lines.map((l) => l.text).join(' '), 'Is the session still valid?', 'no word is lost');
+	assert.ok(two.w < theme.approxMeasure('Is the session still valid?', 'name') * 2, 'narrower than a one-line diamond would be');
+});
+
+test('NO EDGES: unconnected nodes make a tidy block, not one long line', () => {
+	const s = R.prepare({ title: 'T', nodes: Array.from({ length: 9 }, (_, i) => ({ id: 'n' + i, label: 'Item ' + i })), edges: [] }).spec;
+	const geo = L.layout(s);
+	assert.deepStrictEqual(geo.warnings, []);
+	assert.strictEqual(geo.ranks, 3, 'nine nodes → three by three');
+	assert.ok(geo.width < 600 && geo.height < 300, geo.width + '×' + geo.height);
+});
+
+test('DEFENSIVE: a spec that slipped past validation still lays out — the edge to nowhere is just not drawn', () => {
+	const geo = L.layout({ title: 'T', nodes: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B', group: 'nope' }], edges: [{ from: 'a', to: 'ghost' }, { from: 'a', to: 'b' }], groups: [{ id: 'x', label: 'X', parent: 'x' }] });
+	assert.strictEqual(geo.edges.length, 1);
+	assert.strictEqual(geo.groups.length, 0, 'an empty group draws nothing');
+	assert.deepStrictEqual(geo.warnings, []);
+	assert.doesNotThrow(() => L.layout({ title: 'T', nodes: [], edges: [] }));
+});
+
+// ---- a few thousand diagrams nobody would draw on purpose ----------------------------------------
+function rng(seed) { let a = seed >>> 0; return () => { a |= 0; a = a + 0x6D2B79F5 | 0; let t = Math.imul(a ^ a >>> 15, 1 | a); t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t; return ((t ^ t >>> 14) >>> 0) / 4294967296; }; }
+const WORDS = ['Auth', 'API', 'Queue', 'Worker', 'Cache', 'Router', 'Billing', 'Search', 'Index', 'Parse', 'Validate', 'Render', 'Store', 'Notify', 'User', 'Admin', 'Gateway', 'Token', 'Session', 'Upload', 'the', 'of', 'request', 'response', 'check', 'retry', 'done', 'fail', 'ok', 'data'];
+function words(r, maxChars) { let s = ''; const k = 1 + Math.floor(r() * 4); for (let i = 0; i < k; i++) { const w = WORDS[Math.floor(r() * WORDS.length)]; if ((s + ' ' + w).trim().length > maxChars) { break; } s = (s + ' ' + w).trim(); } return s || 'X'; }
+/** A random VALID spec: any shapes, any groups (nested or not), forward edges, back edges, self-loops, duplicates, labels. */
+function randomSpec(seed) {
+	const r = rng(seed);
+	const count = 1 + Math.floor(r() * 12);
+	const shapes = ['box', 'box', 'box', 'decision', 'store', 'actor'];
+	const groupCount = r() < 0.45 ? 1 + Math.floor(r() * 4) : 0;
+	const groups = [];
+	for (let g = 0; g < groupCount; g++) { const gr = { id: 'g' + g, label: words(r, 28) }; if (g > 0 && r() < 0.3 && !groups[g - 1].parent) { gr.parent = 'g' + (g - 1); } groups.push(gr); }
+	const accent = r() < 0.7 ? Math.floor(r() * count) : -1;
+	const nodes = [];
+	for (let i = 0; i < count; i++) {
+		const nd = { id: 'n' + i, label: words(r, 28) };
+		if (r() < 0.4) { nd.sub = words(r, 32); }
+		const sh = shapes[Math.floor(r() * shapes.length)]; if (sh !== 'box') { nd.shape = sh; }
+		if (i === accent) { nd.accent = true; }
+		if (groupCount && r() < 0.6) { nd.group = 'g' + Math.floor(r() * groupCount); }
+		if (r() < 0.15) { nd.link = { path: 'src/a.js', line: 3 }; }
+		nodes.push(nd);
+	}
+	const edges = [];
+	const m = Math.floor(r() * Math.min(18, count * 1.8));
+	for (let k = 0; k < m; k++) {
+		let a = Math.floor(r() * count), b = Math.floor(r() * count);
+		if (r() < 0.75 && a > b) { const t = a; a = b; b = t; }
+		if (a === b && r() > 0.12) { b = (a + 1) % count; }
+		const e = { from: 'n' + a, to: 'n' + b };
+		if (r() < 0.35) { e.label = words(r, 20); }
+		if (r() < 0.2) { e.style = 'dashed'; }
+		edges.push(e);
+	}
+	const out = { v: 1, title: words(r, 60), direction: r() < 0.5 ? 'right' : 'down', nodes, edges };
+	if (groups.length) { out.groups = groups; }
+	return out;
+}
+
+const FUZZ = Number(process.env.DIAGRAM_FUZZ || 1500);
+test('PROPERTY: ' + FUZZ + ' random specs — no overlap, no line through a box, nothing out of frame, frames intact', () => {
+	const soft = { 'label-collision': 0, 'shared-segment': 0, 'group-label-backed': 0 };
+	let flagged = 0, worst = 0, backedNames = 0, grouped = 0;
+	for (let seed = 1; seed <= FUZZ; seed++) {
+		const p = R.prepare(randomSpec(seed), { final: true });
+		assert.ok(p.spec, 'seed ' + seed + ' did not prepare');
+		const t0 = process.hrtime.bigint();
+		const geo = L.layout(p.spec);
+		worst = Math.max(worst, Number(process.hrtime.bigint() - t0) / 1e6);
+		const hard = geo.warnings.filter(HARD);
+		assert.deepStrictEqual(hard, [], 'seed ' + seed + ' (' + geo.direction + ')');
+		assert.strictEqual(geo.edges.length, p.spec.edges.length, 'seed ' + seed + ': every edge is drawn');
+		for (const e of geo.edges) { assert.ok(e.points.length >= 2 && e.points.every((pt) => Number.isFinite(pt.x) && Number.isFinite(pt.y)), 'seed ' + seed + ': edge ' + e.index + ' has a route'); }
+		const seen = new Set();
+		for (const w of geo.warnings.filter((x) => !HARD(x))) { soft[w.cls]++; seen.add(w.cls); }
+		if (seen.has('label-collision')) { flagged++; }
+		if (geo.groups.length) { grouped++; }
+		if (seen.has('group-label-backed')) { backedNames++; }
+		// measured here rather than taken from the layout's own check: no connector through an unbacked name
+		for (const g of geo.groups) { if (!g.labelHalo) { assert.strictEqual(lineThrough(geo, nameOf(g), 1), false, 'seed ' + seed + ': a connector runs through the name of ' + g.id); } }
+	}
+	// The soft findings are known limits, bounded here so they cannot quietly get worse:
+	//   label-collision     a label with no clear spot falls back to a halo (dense fan-ins, mostly when the flow runs down)
+	//   shared-segment      two connectors that swap lanes exactly cannot both be straight
+	//   group-label-backed  a group's name with no clear stretch in its frame has a connector pass behind it
+	assert.ok(grouped > FUZZ / 4, 'the fuzz still exercises groups: ' + grouped);
+	assert.ok(backedNames / grouped <= 0.10, 'backed group names in ' + (100 * backedNames / grouped).toFixed(1) + '% of specs with groups (limit 10%)');
+	assert.ok(flagged / FUZZ <= 0.09, 'label fallbacks in ' + (100 * flagged / FUZZ).toFixed(1) + '% of specs (limit 9%)');
+	assert.ok(soft['shared-segment'] / FUZZ <= 0.005, 'lane swaps in ' + (100 * soft['shared-segment'] / FUZZ).toFixed(2) + '% of specs (limit 0.5%)');
+	assert.ok(worst < 200, 'slowest layout ' + worst.toFixed(1) + ' ms — the spec budgets 200 ms for layout');
+});
+
+test('SPEED: a full twelve-node diagram lays out in a few milliseconds (budget: 200 ms)', () => {
+	const s = spec('twelve');
+	L.layout(s);   // warm up
+	const times = [];
+	for (let i = 0; i < 40; i++) { const t0 = process.hrtime.bigint(); L.layout(s); times.push(Number(process.hrtime.bigint() - t0) / 1e6); }
+	times.sort((a, b) => a - b);
+	const p95 = times[Math.floor(times.length * 0.95)];
+	assert.ok(p95 < 50, 'p95 ' + p95.toFixed(2) + ' ms');
+});
+
+console.log('diagramLayout: ' + n + ' tests passed');
diff --git a/extensions/levelcode-ai/test/fixtures/diagrams/gallery.json b/extensions/levelcode-ai/test/fixtures/diagrams/gallery.json
new file mode 100644
index 0000000..931a343
--- /dev/null
+++ b/extensions/levelcode-ai/test/fixtures/diagrams/gallery.json
@@ -0,0 +1,569 @@
+[
+	{
+		"name": "jev",
+		"spec": {
+			"v": 1,
+			"title": "Jev classifies; your code decides the action",
+			"direction": "right",
+			"nodes": [
+				{
+					"id": "in",
+					"label": "Customer message",
+					"sub": "plus account details"
+				},
+				{
+					"id": "jev",
+					"label": "Jev",
+					"sub": "returns probabilities",
+					"accent": true
+				},
+				{
+					"id": "bill",
+					"label": "Route to billing"
+				},
+				{
+					"id": "rev",
+					"label": "Human review"
+				}
+			],
+			"edges": [
+				{
+					"from": "in",
+					"to": "jev"
+				},
+				{
+					"from": "jev",
+					"to": "bill",
+					"label": "0.90 or more"
+				},
+				{
+					"from": "jev",
+					"to": "rev",
+					"label": "under 0.90"
+				}
+			]
+		}
+	},
+	{
+		"name": "pipeline",
+		"spec": {
+			"title": "Every diagram travels one pipeline; a failing spec takes one trip through repair",
+			"direction": "right",
+			"nodes": [
+				{
+					"id": "model",
+					"label": "Model",
+					"sub": "emits a spec",
+					"shape": "actor"
+				},
+				{
+					"id": "val",
+					"label": "Validate",
+					"sub": "four layers",
+					"accent": true
+				},
+				{
+					"id": "lay",
+					"label": "Layout",
+					"sub": "house style"
+				},
+				{
+					"id": "san",
+					"label": "Sanitize"
+				},
+				{
+					"id": "chat",
+					"label": "Chat",
+					"shape": "actor"
+				},
+				{
+					"id": "rep",
+					"label": "Repair ladder",
+					"sub": "fix, one model pass, degrade",
+					"shape": "decision"
+				}
+			],
+			"edges": [
+				{
+					"from": "model",
+					"to": "val"
+				},
+				{
+					"from": "val",
+					"to": "lay",
+					"label": "valid"
+				},
+				{
+					"from": "lay",
+					"to": "san"
+				},
+				{
+					"from": "san",
+					"to": "chat"
+				},
+				{
+					"from": "val",
+					"to": "rep",
+					"label": "errors",
+					"style": "dashed"
+				},
+				{
+					"from": "rep",
+					"to": "val",
+					"label": "repaired",
+					"style": "dashed"
+				}
+			]
+		}
+	},
+	{
+		"name": "arch",
+		"spec": {
+			"title": "The agent talks to providers through one registry",
+			"direction": "right",
+			"groups": [
+				{
+					"id": "ext",
+					"label": "Extension host"
+				},
+				{
+					"id": "prov",
+					"label": "Providers"
+				}
+			],
+			"nodes": [
+				{
+					"id": "chat",
+					"label": "Chat webview",
+					"shape": "actor"
+				},
+				{
+					"id": "agent",
+					"label": "agent.js",
+					"sub": "tool loop",
+					"group": "ext",
+					"accent": true,
+					"link": {
+						"path": "agent.js",
+						"symbol": "runAgent"
+					}
+				},
+				{
+					"id": "reg",
+					"label": "providers/index.js",
+					"sub": "registry",
+					"group": "ext",
+					"link": {
+						"path": "providers/index.js"
+					}
+				},
+				{
+					"id": "store",
+					"label": "Sessions",
+					"sub": "append-only JSONL",
+					"shape": "store",
+					"group": "ext"
+				},
+				{
+					"id": "ant",
+					"label": "Anthropic",
+					"group": "prov"
+				},
+				{
+					"id": "oai",
+					"label": "OpenAI-compatible",
+					"sub": "one adapter, ten providers",
+					"group": "prov"
+				}
+			],
+			"edges": [
+				{
+					"from": "chat",
+					"to": "agent",
+					"label": "goal"
+				},
+				{
+					"from": "agent",
+					"to": "reg"
+				},
+				{
+					"from": "reg",
+					"to": "ant"
+				},
+				{
+					"from": "reg",
+					"to": "oai"
+				},
+				{
+					"from": "agent",
+					"to": "store",
+					"label": "each turn",
+					"style": "dashed"
+				}
+			]
+		}
+	},
+	{
+		"name": "decision",
+		"spec": {
+			"title": "A steer is applied at the next safe point, never mid-tool",
+			"direction": "down",
+			"nodes": [
+				{
+					"id": "s",
+					"label": "Steer arrives",
+					"shape": "actor"
+				},
+				{
+					"id": "q",
+					"label": "Tool running?",
+					"shape": "decision",
+					"accent": true
+				},
+				{
+					"id": "wait",
+					"label": "Queue it",
+					"sub": "until the tool returns"
+				},
+				{
+					"id": "now",
+					"label": "Inject now"
+				},
+				{
+					"id": "next",
+					"label": "Next model turn"
+				}
+			],
+			"edges": [
+				{
+					"from": "s",
+					"to": "q"
+				},
+				{
+					"from": "q",
+					"to": "wait",
+					"label": "yes"
+				},
+				{
+					"from": "q",
+					"to": "now",
+					"label": "no"
+				},
+				{
+					"from": "wait",
+					"to": "next"
+				},
+				{
+					"from": "now",
+					"to": "next"
+				}
+			]
+		}
+	},
+	{
+		"name": "state",
+		"spec": {
+			"title": "A session is only ever archived, never deleted",
+			"direction": "right",
+			"nodes": [
+				{
+					"id": "active",
+					"label": "Active",
+					"accent": true
+				},
+				{
+					"id": "arch",
+					"label": "Archived"
+				},
+				{
+					"id": "trash",
+					"label": "Trashed"
+				}
+			],
+			"edges": [
+				{
+					"from": "active",
+					"to": "arch",
+					"label": "Done"
+				},
+				{
+					"from": "arch",
+					"to": "active",
+					"label": "Undo"
+				},
+				{
+					"from": "active",
+					"to": "trash",
+					"label": "Delete"
+				},
+				{
+					"from": "trash",
+					"to": "active",
+					"label": "Restore"
+				},
+				{
+					"from": "active",
+					"to": "active",
+					"label": "new turn"
+				}
+			]
+		}
+	},
+	{
+		"name": "fan",
+		"spec": {
+			"title": "One router, five handlers",
+			"direction": "right",
+			"nodes": [
+				{
+					"id": "r",
+					"label": "Router",
+					"accent": true
+				},
+				{
+					"id": "a",
+					"label": "Auth"
+				},
+				{
+					"id": "b",
+					"label": "Billing"
+				},
+				{
+					"id": "c",
+					"label": "Search"
+				},
+				{
+					"id": "d",
+					"label": "Uploads"
+				},
+				{
+					"id": "e",
+					"label": "Webhooks"
+				},
+				{
+					"id": "db",
+					"label": "Postgres",
+					"shape": "store"
+				}
+			],
+			"edges": [
+				{
+					"from": "r",
+					"to": "a"
+				},
+				{
+					"from": "r",
+					"to": "b"
+				},
+				{
+					"from": "r",
+					"to": "c"
+				},
+				{
+					"from": "r",
+					"to": "d"
+				},
+				{
+					"from": "r",
+					"to": "e"
+				},
+				{
+					"from": "a",
+					"to": "db"
+				},
+				{
+					"from": "b",
+					"to": "db"
+				},
+				{
+					"from": "c",
+					"to": "db"
+				}
+			]
+		}
+	},
+	{
+		"name": "twelve",
+		"spec": {
+			"title": "A request crosses four layers before it reaches storage",
+			"direction": "right",
+			"groups": [
+				{
+					"id": "edge",
+					"label": "Edge"
+				},
+				{
+					"id": "app",
+					"label": "Application"
+				},
+				{
+					"id": "data",
+					"label": "Data"
+				},
+				{
+					"id": "w",
+					"label": "Workers",
+					"parent": "app"
+				}
+			],
+			"nodes": [
+				{
+					"id": "u",
+					"label": "Browser",
+					"shape": "actor"
+				},
+				{
+					"id": "cdn",
+					"label": "CDN",
+					"group": "edge"
+				},
+				{
+					"id": "lb",
+					"label": "Load balancer",
+					"group": "edge"
+				},
+				{
+					"id": "api",
+					"label": "API",
+					"sub": "Rails",
+					"group": "app",
+					"accent": true
+				},
+				{
+					"id": "auth",
+					"label": "Auth",
+					"group": "app"
+				},
+				{
+					"id": "q",
+					"label": "Queue",
+					"shape": "store",
+					"group": "w"
+				},
+				{
+					"id": "job",
+					"label": "Job runner",
+					"group": "w"
+				},
+				{
+					"id": "mail",
+					"label": "Mailer",
+					"group": "w"
+				},
+				{
+					"id": "pg",
+					"label": "Postgres",
+					"shape": "store",
+					"group": "data"
+				},
+				{
+					"id": "rd",
+					"label": "Redis",
+					"shape": "store",
+					"group": "data"
+				},
+				{
+					"id": "s3",
+					"label": "Object store",
+					"shape": "store",
+					"group": "data"
+				},
+				{
+					"id": "ext",
+					"label": "Stripe",
+					"shape": "actor"
+				}
+			],
+			"edges": [
+				{
+					"from": "u",
+					"to": "cdn"
+				},
+				{
+					"from": "cdn",
+					"to": "lb"
+				},
+				{
+					"from": "lb",
+					"to": "api"
+				},
+				{
+					"from": "api",
+					"to": "auth"
+				},
+				{
+					"from": "api",
+					"to": "q",
+					"label": "enqueue"
+				},
+				{
+					"from": "q",
+					"to": "job"
+				},
+				{
+					"from": "job",
+					"to": "mail"
+				},
+				{
+					"from": "api",
+					"to": "pg"
+				},
+				{
+					"from": "auth",
+					"to": "rd"
+				},
+				{
+					"from": "job",
+					"to": "s3"
+				},
+				{
+					"from": "api",
+					"to": "ext",
+					"label": "charge",
+					"style": "dashed"
+				},
+				{
+					"from": "job",
+					"to": "pg"
+				}
+			]
+		}
+	},
+	{
+		"name": "lonely",
+		"spec": {
+			"title": "Three stores, no flow between them",
+			"nodes": [
+				{
+					"id": "a",
+					"label": "Journal",
+					"shape": "store"
+				},
+				{
+					"id": "b",
+					"label": "Facts",
+					"shape": "store"
+				},
+				{
+					"id": "c",
+					"label": "MEMORY.md"
+				}
+			],
+			"edges": []
+		}
+	},
+	{
+		"name": "single",
+		"spec": {
+			"title": "One box",
+			"nodes": [
+				{
+					"id": "a",
+					"label": "Only me",
+					"accent": true
+				}
+			],
+			"edges": []
+		}
+	}
+]

From f35fbc13ceb708f3665043be2c6394edf974a600 Mon Sep 17 00:00:00 2001
From: Sergii Demianchuk <sergeydemjanchyk@gmail.com>
Date: Mon, 5 Oct 2026 00:27:39 -0400
Subject: [PATCH 5/9] feat(diagrams): the painter, and the same diagram as text

  diagram/scene.js   geometry to a tree of elements, built from two allow-lists:
                     seven tags (svg g rect path text title style) and a set of
                     attributes with no href, no style, no id and no on*.
                     mount() turns it into DOM with createElementNS and
                     textContent; toSvg() into an escaped string for a file. A
                     label is never parsed as markup by either, and both refuse
                     anything off the lists rather than trust whoever built the
                     tree.
  diagram/text.js    the outline a screen reader is given (nodes, then edges, in
                     reading order); the one-line stub that stands in for a spec
                     once a conversation is compacted; Mermaid and source
                     export.
  diagram/ascii.js   for when a picture cannot be shown: the SAME layout on a
                     character grid, so it puts things where the picture would.
                     Plain ASCII; East Asian wide characters and emoji count as
                     two cells, combining marks as none.

A linked node carries data-lc-link = its NODE ID, never the path: whoever
handles the click looks the link up in its own copy of the spec.

A group's name that the layout could not keep clear of a connector is drawn
after the connectors, with the halo an edge label gets, so the line reads as
passing behind the word.

Snapshots of three gallery diagrams in both palettes (fixtures/diagrams/
snapshots): a change to the style, the layout or the painter shows up there as
a diff. diagramScene (23 tests) and diagramText (17).
---
 extensions/levelcode-ai/diagram/ascii.js      | 184 +++++++++++
 extensions/levelcode-ai/diagram/scene.js      | 254 ++++++++++++++
 extensions/levelcode-ai/diagram/text.js       | 151 +++++++++
 .../levelcode-ai/test/diagramScene.test.js    | 310 ++++++++++++++++++
 .../levelcode-ai/test/diagramText.test.js     | 227 +++++++++++++
 .../fixtures/diagrams/snapshots/arch.dark.svg |  16 +
 .../diagrams/snapshots/arch.light.svg         |  16 +
 .../diagrams/snapshots/decision.dark.svg      |  16 +
 .../diagrams/snapshots/decision.light.svg     |  16 +
 .../fixtures/diagrams/snapshots/jev.dark.svg  |  16 +
 .../fixtures/diagrams/snapshots/jev.light.svg |  16 +
 11 files changed, 1222 insertions(+)
 create mode 100644 extensions/levelcode-ai/diagram/ascii.js
 create mode 100644 extensions/levelcode-ai/diagram/scene.js
 create mode 100644 extensions/levelcode-ai/diagram/text.js
 create mode 100644 extensions/levelcode-ai/test/diagramScene.test.js
 create mode 100644 extensions/levelcode-ai/test/diagramText.test.js
 create mode 100644 extensions/levelcode-ai/test/fixtures/diagrams/snapshots/arch.dark.svg
 create mode 100644 extensions/levelcode-ai/test/fixtures/diagrams/snapshots/arch.light.svg
 create mode 100644 extensions/levelcode-ai/test/fixtures/diagrams/snapshots/decision.dark.svg
 create mode 100644 extensions/levelcode-ai/test/fixtures/diagrams/snapshots/decision.light.svg
 create mode 100644 extensions/levelcode-ai/test/fixtures/diagrams/snapshots/jev.dark.svg
 create mode 100644 extensions/levelcode-ai/test/fixtures/diagrams/snapshots/jev.light.svg

diff --git a/extensions/levelcode-ai/diagram/ascii.js b/extensions/levelcode-ai/diagram/ascii.js
new file mode 100644
index 0000000..010dba7
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/ascii.js
@@ -0,0 +1,184 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · the ASCII fallback  (docs/RICH-DIAGRAMS.md, "UX → Fallback")
+ *
+ *  "If rendering is unavailable, the user sees an ASCII rendering generated from the same spec, so
+ *  the model never has to draw ASCII itself."
+ *
+ *  This is the SAME layout as the picture, not a second one: layout.layout() is run with every
+ *  character one cell wide, and its geometry is rasterised onto a character grid — boxes, connectors
+ *  with their corners and arrowheads, labels beside lines, group frames. So the fallback puts things
+ *  where the picture would have, and a fix to the layout fixes both.
+ *
+ *  It is drawn by the editor, for a <pre> in a monospaced face — the one place box-and-arrow
+ *  characters hold their shape. That is the difference from a model typing them into prose.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+(function (root, factory) {
+	'use strict';
+	if (typeof module === 'object' && module.exports) { module.exports = factory(require('./layout')); }
+	else { (root.LCDiagram = root.LCDiagram || {}).ascii = factory(root.LCDiagram.layout); }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function (layoutMod) {
+	'use strict';
+
+	/** One character cell, in the layout's pixels. Tall cells are halved so two lines 12px apart stay on different rows. */
+	const CW = 8, CH = 8;
+	const chars = (s) => Array.from(String(s));
+	// How wide text is in a monospaced face, in cells. Ranges are [first, last], from Unicode's East Asian
+	// Width (Wide and Fullwidth) and its combining blocks — the common cases, not the whole standard.
+	// Without this a label in Japanese, or one with an emoji in it, pushes the right-hand side of its own
+	// box — and everything after it on the row — out of line.
+	const MARKS = [[0x300, 0x36f], [0x1ab0, 0x1aff], [0x1dc0, 0x1dff], [0x200b, 0x200f], [0x20d0, 0x20ff], [0xfe00, 0xfe0f], [0xfe20, 0xfe2f], [0xe0100, 0xe01ef]];
+	const WIDE = [[0x1100, 0x115f], [0x231a, 0x231b], [0x23e9, 0x23ec], [0x23f0, 0x23f0], [0x23f3, 0x23f3], [0x25fd, 0x25fe], [0x2614, 0x2615], [0x2648, 0x2653], [0x267f, 0x267f], [0x2693, 0x2693],
+		[0x26a1, 0x26a1], [0x26aa, 0x26ab], [0x26bd, 0x26be], [0x26c4, 0x26c5], [0x26ce, 0x26ce], [0x26d4, 0x26d4], [0x26ea, 0x26ea], [0x26f2, 0x26f3], [0x26f5, 0x26f5], [0x26fa, 0x26fa], [0x26fd, 0x26fd],
+		[0x2705, 0x2705], [0x270a, 0x270b], [0x2728, 0x2728], [0x274c, 0x274c], [0x274e, 0x274e], [0x2753, 0x2755], [0x2757, 0x2757], [0x2795, 0x2797], [0x27b0, 0x27b0], [0x27bf, 0x27bf], [0x2b1b, 0x2b1c],
+		[0x2b50, 0x2b50], [0x2b55, 0x2b55], [0x2e80, 0x303e], [0x3041, 0x33ff], [0x3400, 0x4dbf], [0x4e00, 0x9fff], [0xa000, 0xa4cf], [0xa960, 0xa97f], [0xac00, 0xd7a3], [0xf900, 0xfaff], [0xfe30, 0xfe4f],
+		[0xff00, 0xff60], [0xffe0, 0xffe6], [0x1f004, 0x1f004], [0x1f0cf, 0x1f0cf], [0x1f18e, 0x1f18e], [0x1f191, 0x1f19a], [0x1f200, 0x1f2ff], [0x1f300, 0x1f64f], [0x1f680, 0x1f6ff], [0x1f7e0, 0x1f7eb],
+		[0x1f900, 0x1faff], [0x20000, 0x3fffd]];
+	const within = (table, c) => table.some((r) => c >= r[0] && c <= r[1]);
+	/** Text as the units a monospaced face sets: a character with any marks that sit on it, and its width in cells. */
+	function units(text) {
+		const out = [];
+		for (const ch of chars(text)) {
+			const c = ch.codePointAt(0);
+			if (c >= 0x300 && out.length && within(MARKS, c)) {
+				const last = out[out.length - 1];
+				last.text += ch;
+				if (c === 0xfe0f) { last.w = 2; }   // "show the character before me as an emoji" — which is a wide one
+				continue;
+			}
+			out.push({ text: ch, w: c >= 0x1100 && within(WIDE, c) ? 2 : 1 });
+		}
+		return out;
+	}
+	const width = (text) => units(text).reduce((a, u) => a + u.w, 0);
+	/** The layout is told how wide text is in cells, and sizes boxes to match. */
+	const measure = (text) => width(text) * CW;
+	/** The mark a shortened label ends with, in characters every terminal has. */
+	const plain = (s) => (typeof s === 'string' ? s.replace(/\u2026/g, '...') : s);
+
+	// Box furniture per shape — different corners so "same kind, same shape" survives without curves.
+	const FRAME = {
+		box: { tl: '+', tr: '+', bl: '+', br: '+', h: '-', v: '|' },
+		decision: { tl: '/', tr: '\\', bl: '\\', br: '/', h: '-', v: '|' },
+		store: { tl: '.', tr: '.', bl: "'", br: "'", h: '=', v: '|' },
+		actor: { tl: '.', tr: '.', bl: "'", br: "'", h: '-', v: '(' }
+	};
+
+	/**
+	 * Render a validated spec as text.
+	 * @param {any} spec
+	 * @param {{ maxCols?: number, title?: boolean }} [opts]  maxCols: the width to fit (a flow asked for left-to-right
+	 *        turns downward when it will not). title: false leaves the title line out, for a card that already shows it.
+	 * @returns {string}
+	 */
+	function render(spec, opts) {
+		const o = opts || {};
+		// A character grid has no slanted or curved edges for a connector to stop on, so every shape is
+		// laid out as a rectangle here; what kind it is shows in how its frame is drawn.
+		const shapeOf = new Map((spec.nodes || []).map((n) => [n.id, n.shape || 'box']));
+		const flat = Object.assign({}, spec, {
+			nodes: (spec.nodes || []).map((n) => Object.assign({}, n, { shape: 'box', label: plain(n.label), sub: plain(n.sub) })),
+			edges: (spec.edges || []).map((e) => Object.assign({}, e, { label: plain(e.label) })),
+			groups: (spec.groups || []).map((g) => Object.assign({}, g, { label: plain(g.label) }))
+		});
+		const geo = layoutMod.layout(flat, {
+			measure,
+			maxWidth: o.maxCols ? o.maxCols * CW : undefined,
+			// a little more air than the picture needs: after rounding to cells, neighbours must still be apart
+			// Every distance is a whole number of cells: two things a fixed distance apart are then the
+			// same number of cells apart after rounding, wherever on the grid they land.
+			space: { portGap: 2 * CH, portMin: 2 * CH, labelLane: 2 * CH, track: 2 * CW, labelGap: CH / 2, labelSideGap: CW, labelPad: CW, channelPad: 3 * CW, nodeGap: 3 * CH, rankGap: 6 * CW, lineClear: 2 * CH, groupGap: 2 * CH, groupInset: 2 * CW, groupHeader: 2 * CH, arrow: CW, arrowHalf: 1, margin: CW, selfLoop: 2 * CW },
+			type: { name: { size: 13, weight: 400, line: CH }, sub: { size: 13, weight: 400, line: CH }, edge: { size: 13, weight: 400, line: CH }, group: { size: 13, weight: 400, line: CH }, title: { size: 13, weight: 400, line: CH } },
+			box: { padX: 1.5 * CW, padY: CH / 2, textGap: 0, minWidth: 5 * CW, linkIcon: 0, storeCap: 0 }
+		});
+		const col = (x) => Math.round(x / CW), row = (y) => Math.round(y / CH);
+		const W = col(geo.width) + 2, H = row(geo.height) + 2;
+		const grid = Array.from({ length: H }, () => new Array(W).fill(' '));
+		const put = (r, c, ch) => { if (r >= 0 && r < H && c >= 0 && c < W) { grid[r][c] = ch; } };
+		const get = (r, c) => (r >= 0 && r < H && c >= 0 && c < W ? grid[r][c] : ' ');
+		// A wide character fills its own cell and empties the next, so the row still adds up.
+		const write = (r, c, text) => {
+			let at = c;
+			for (const u of units(text)) { put(r, at, u.text); if (u.w === 2) { put(r, at + 1, ''); } at += u.w; }
+		};
+
+		// group frames first: everything else is drawn over them
+		const byDepth = geo.groups.slice().sort((a, b) => a.depth - b.depth);
+		for (const g of byDepth) {
+			const c0 = col(g.x), c1 = col(g.x + g.w), r0 = row(g.y), r1 = row(g.y + g.h);
+			for (let c = c0; c <= c1; c++) { put(r0, c, (c - c0) % 2 ? ' ' : '.'); put(r1, c, (c - c0) % 2 ? ' ' : '.'); }
+			for (let r = r0 + 1; r < r1; r++) { put(r, c0, ':'); put(r, c1, ':'); }
+		}
+		// A group's name sits on its frame's top row, where the layout put it: slid clear of the lines
+		// that come in through that row when there was room. It is written AFTER the connectors, so one
+		// that has to share the row with a line is still whole.
+		const nameGroups = () => {
+			for (const g of byDepth) {
+				const c0 = col(g.x), c1 = col(g.x + g.w), r0 = row(g.y);
+				const slid = col(g.labelX - (g.x + 2 * CW - 4));   // how far the layout moved it from the corner
+				const text = ' ' + g.label + ' ';
+				write(r0, Math.max(c0 + 2, Math.min(c0 + 2 + slid, c1 - 1 - width(text))), text);
+			}
+		};
+
+		// connectors: runs, then corners, then the arrowhead
+		const HORIZ = new Set(['-', '.', '=']), VERT = new Set(['|', ':']);
+		for (const e of geo.edges) {
+			const pts = e.points.map((p) => ({ c: col(p.x), r: row(p.y) }));
+			for (let i = 0; i + 1 < pts.length; i++) {
+				const a = pts[i], b = pts[i + 1];
+				if (a.r === b.r) {
+					for (let c = Math.min(a.c, b.c); c <= Math.max(a.c, b.c); c++) {
+						const cur = get(a.r, c);
+						put(a.r, c, VERT.has(cur) || cur === '+' ? '+' : (e.dashed && c % 2 ? ' ' : '-'));
+					}
+				} else {
+					for (let r = Math.min(a.r, b.r); r <= Math.max(a.r, b.r); r++) {
+						const cur = get(r, a.c);
+						put(r, a.c, HORIZ.has(cur) || cur === '+' ? '+' : (e.dashed ? ':' : '|'));
+					}
+				}
+			}
+			for (let i = 1; i + 1 < pts.length; i++) { put(pts[i].r, pts[i].c, '+'); }
+		}
+		nameGroups();
+
+		// nodes over the connectors that end on them
+		for (const n of geo.nodes) {
+			const shape = shapeOf.get(n.id) || 'box';
+			const f = FRAME[shape] || FRAME.box;
+			const c0 = col(n.x), c1 = col(n.x + n.w), r0 = row(n.y), r1 = row(n.y + n.h);
+			for (let r = r0; r <= r1; r++) { for (let c = c0; c <= c1; c++) { put(r, c, ' '); } }
+			for (let c = c0 + 1; c < c1; c++) { put(r0, c, n.accent ? '#' : f.h); put(r1, c, n.accent ? '#' : f.h); }
+			for (let r = r0 + 1; r < r1; r++) { put(r, c0, f.v); put(r, c1, f.v === '(' ? ')' : f.v); }
+			put(r0, c0, f.tl); put(r0, c1, f.tr); put(r1, c0, f.bl); put(r1, c1, f.br);
+			if (shape === 'decision') { const mid = Math.round((r0 + r1) / 2); put(mid, c0, '<'); put(mid, c1, '>'); }
+			const first = Math.round((r0 + r1) / 2 - (n.lines.length - 1) / 2);
+			n.lines.forEach((line, i) => {
+				write(first + i, Math.round((c0 + c1) / 2 - (width(line.text) - 1) / 2), line.text);
+			});
+		}
+
+		// arrowheads sit in the last cell BEFORE the node, so they survive the node being drawn
+		for (const e of geo.edges) {
+			const a = e.arrow, c = col(a.x) - a.dx, r = row(a.y) - a.dy;
+			put(r, c, a.dx > 0 ? '>' : a.dx < 0 ? '<' : a.dy > 0 ? 'v' : '^');
+		}
+
+		// labels last, each on the row its line box is centred on
+		for (const e of geo.edges) {
+			if (!e.label) { continue; }
+			write(row(e.label.y + e.label.h / 2), col(e.label.x), e.label.text);
+		}
+
+		const lines = grid.map((r) => r.join('').replace(/\s+$/, ''));
+		while (lines.length && !lines[0]) { lines.shift(); }
+		while (lines.length && !lines[lines.length - 1]) { lines.pop(); }
+		const indent = Math.min.apply(null, lines.filter(Boolean).map((l) => l.search(/\S/)).concat([Infinity]));
+		const body = lines.map((l) => (Number.isFinite(indent) ? l.slice(indent) : l));
+		const title = o.title !== false && spec && spec.title ? [String(spec.tip || spec.title), ''] : [];
+		return title.concat(body).join('\n') + '\n';
+	}
+
+	return { render, width, CW, CH };
+}));
diff --git a/extensions/levelcode-ai/diagram/scene.js b/extensions/levelcode-ai/diagram/scene.js
new file mode 100644
index 0000000..6761b94
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/scene.js
@@ -0,0 +1,254 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · the painter  (docs/RICH-DIAGRAMS.md, "Safe rendering")
+ *
+ *  LevelCode builds the SVG itself. A diagram is a tree of plain objects — { tag, attrs, text,
+ *  children } — produced here from a laid-out spec, and turned into pixels one of two ways:
+ *
+ *    mount(vnode, document)   the chat: real DOM nodes via createElementNS. A label becomes a TEXT
+ *                             NODE (textContent) — never markup, never innerHTML — so nothing a model
+ *                             writes into a label can become an element, an attribute or a script.
+ *    toSvg(vnode)             an export / a test: a string, every text and attribute value escaped.
+ *
+ *  Both walk the same tree, so "exports match the rendered view" holds by construction.
+ *
+ *  The tree is drawn from two short allow-lists (TAGS, ATTRS). There is no script element, no
+ *  foreignObject, no href, no style attribute and no event handler in them, and mount() refuses
+ *  anything else — the allow-list is the guarantee, not the care taken by whoever built the tree.
+ *
+ *  (This file is inlined into the chat page's own script block, so it must never spell an HTML
+ *  script tag or comment opener, even in a comment like this one — diagram/bundle.js refuses to
+ *  build the page if it does, and test/diagramHost.test.js checks every module that ships there.)
+ *
+ *  Colour never appears here. Elements carry classes; theme.css() gives the classes their paint from
+ *  editor theme tokens, which is why a theme switch restyles a diagram without rebuilding it.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+(function (root, factory) {
+	'use strict';
+	if (typeof module === 'object' && module.exports) { module.exports = factory(require('./theme')); }
+	else { (root.LCDiagram = root.LCDiagram || {}).scene = factory(root.LCDiagram.theme); }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function (theme) {
+	'use strict';
+
+	const SVG_NS = 'http://www.w3.org/2000/svg';
+	/** Every element a diagram may contain. `style` exists only in exported files (toSvg), never in the chat. */
+	const TAGS = new Set(['svg', 'g', 'rect', 'path', 'text', 'title', 'style']);
+	/** Every attribute a diagram may carry. Note what is absent: href, style, on*, xlink:*, src. */
+	const ATTRS = new Set([
+		'class', 'd', 'x', 'y', 'width', 'height', 'rx', 'ry', 'viewBox', 'transform', 'text-anchor',
+		'role', 'aria-label', 'aria-hidden', 'tabindex', 'focusable', 'data-lc-link', 'data-lc-node', 'xmlns'
+	]);
+
+	const n2 = (v) => String(Math.round(v * 100) / 100);
+	const h = (tag, attrs, kids) => {
+		const node = { tag, attrs: attrs || {} };
+		if (typeof kids === 'string') { node.text = kids; } else if (kids) { node.children = kids.filter(Boolean); }
+		return node;
+	};
+
+	/** Where a line of text's baseline sits, given the centre of its line box. Avoids `dominant-baseline`, which exporters disagree about. */
+	const baseline = (centerY, size) => centerY + size * 0.355;
+
+	/**
+	 * An orthogonal polyline as a path with softly rounded corners. `trim` shortens the final run so
+	 * the stroke ends at the base of the arrowhead instead of poking through its tip.
+	 */
+	function edgePath(points, radius, trim) {
+		const pts = points.map((p) => ({ x: p.x, y: p.y }));
+		const n = pts.length;
+		if (n < 2) { return ''; }
+		if (trim) {
+			const a = pts[n - 2], b = pts[n - 1];
+			const len = Math.hypot(b.x - a.x, b.y - a.y);
+			if (len > trim + 0.5) { b.x -= (b.x - a.x) / len * trim; b.y -= (b.y - a.y) / len * trim; }
+		}
+		let d = 'M' + n2(pts[0].x) + ',' + n2(pts[0].y);
+		for (let i = 1; i < n; i++) {
+			const p = pts[i];
+			if (i === n - 1) { d += ' L' + n2(p.x) + ',' + n2(p.y); break; }
+			const a = pts[i - 1], b = pts[i + 1];
+			const inLen = Math.hypot(p.x - a.x, p.y - a.y), outLen = Math.hypot(b.x - p.x, b.y - p.y);
+			const r = Math.min(radius, inLen / 2, outLen / 2);
+			if (r < 0.75) { d += ' L' + n2(p.x) + ',' + n2(p.y); continue; }
+			const s = { x: p.x - (p.x - a.x) / inLen * r, y: p.y - (p.y - a.y) / inLen * r };
+			const e = { x: p.x + (b.x - p.x) / outLen * r, y: p.y + (b.y - p.y) / outLen * r };
+			d += ' L' + n2(s.x) + ',' + n2(s.y) + ' Q' + n2(p.x) + ',' + n2(p.y) + ' ' + n2(e.x) + ',' + n2(e.y);
+		}
+		return d;
+	}
+	/** A filled triangle whose tip is the end of the connector. */
+	function arrowPath(arrow, S) {
+		const L = S.arrow, W = S.arrowHalf;
+		const bx = arrow.x - arrow.dx * L, by = arrow.y - arrow.dy * L;
+		const px = -arrow.dy, py = arrow.dx;   // perpendicular
+		return 'M' + n2(arrow.x) + ',' + n2(arrow.y) + ' L' + n2(bx + px * W) + ',' + n2(by + py * W) + ' L' + n2(bx - px * W) + ',' + n2(by - py * W) + ' Z';
+	}
+
+	/** The outline(s) of one node, by shape. "Same kind, same shape." */
+	function shapeNodes(n, B) {
+		const x = n.x, y = n.y, w = n.w, ht = n.h;
+		if (n.shape === 'decision') {
+			return [h('path', { class: 'lcd-shape', d: 'M' + n2(x + w / 2) + ',' + n2(y) + ' L' + n2(x + w) + ',' + n2(y + ht / 2) + ' L' + n2(x + w / 2) + ',' + n2(y + ht) + ' L' + n2(x) + ',' + n2(y + ht / 2) + ' Z' })];
+		}
+		if (n.shape === 'store') {
+			const ry = B.storeCap != null ? B.storeCap : 6, rx = w / 2;
+			const body = 'M' + n2(x) + ',' + n2(y + ry) + ' A' + n2(rx) + ',' + n2(ry) + ' 0 0 1 ' + n2(x + w) + ',' + n2(y + ry)
+				+ ' V' + n2(y + ht - ry) + ' A' + n2(rx) + ',' + n2(ry) + ' 0 0 1 ' + n2(x) + ',' + n2(y + ht - ry) + ' Z';
+			const lid = 'M' + n2(x) + ',' + n2(y + ry) + ' A' + n2(rx) + ',' + n2(ry) + ' 0 0 0 ' + n2(x + w) + ',' + n2(y + ry);
+			return [h('path', { class: 'lcd-shape', d: body }), h('path', { class: 'lcd-shape lcd-lid', d: lid })];
+		}
+		const r = n.shape === 'actor' ? Math.min(w, ht) / 2 : B.radius;
+		return [h('rect', { class: 'lcd-shape', x: n2(x), y: n2(y), width: n2(w), height: n2(ht), rx: n2(r), ry: n2(r) })];
+	}
+	/** A 9×11 "file" glyph — the mark of a node that opens code. */
+	function fileGlyph(x, y) {
+		return h('path', { class: 'lcd-link-icon', 'aria-hidden': 'true', d: 'M' + n2(x) + ',' + n2(y) + ' h5.5 l3.5,3.5 v7.5 h-9 Z M' + n2(x + 5.5) + ',' + n2(y) + ' v3.5 h3.5' });
+	}
+
+	/** Greedy word wrap to a pixel width — used for the title of an exported file. */
+	function wrapText(text, maxWidth, measure, role) {
+		const words = String(text).split(' ');
+		const lines = [];
+		let cur = '';
+		for (const w of words) {
+			const next = cur ? cur + ' ' + w : w;
+			if (cur && measure(next, role) > maxWidth) { lines.push(cur); cur = w; } else { cur = next; }
+		}
+		if (cur) { lines.push(cur); }
+		return lines;
+	}
+
+	/**
+	 * Build the tree for one diagram.
+	 * @param {any} spec  the validated spec (for the title)
+	 * @param {any} geo   layout.layout(spec, …)
+	 * @param {{ title?: boolean, css?: string, measure?: (t:string, role:string)=>number, standalone?: boolean, background?: boolean }} [opts]
+	 *        title: draw the spec's title inside the SVG (exports — in the chat it is HTML above the picture)
+	 *        css: a stylesheet to embed (exports)        standalone: add xmlns (a file, not inline SVG)
+	 *        background: paint the editor background behind the drawing (exports — a file has no page behind it)
+	 */
+	function build(spec, geo, opts) {
+		const o = opts || {};
+		const T = theme.TYPE, B = theme.BOX, S = theme.SPACE;
+		const measure = o.measure || theme.approxMeasure;
+		const kids = [];
+		let top = 0, width = geo.width;
+		if (o.css) { kids.push(h('style', {}, o.css)); }
+		if (o.title && spec.title) {
+			const lines = wrapText(spec.title, Math.max(geo.width - 2 * S.margin, 260), measure, 'title');
+			width = Math.max(width, Math.ceil(Math.max.apply(null, lines.map((l) => measure(l, 'title')))) + 2 * S.margin);
+			lines.forEach((line, i) => {
+				kids.push(h('text', { class: 'lcd-title', x: n2(S.margin), y: n2(baseline(S.margin + T.title.line * (i + 0.5), T.title.size)) }, line));
+			});
+			top = S.margin + lines.length * T.title.line + 6;
+		}
+
+		// A group's name is drawn with its frame — unless a connector has to run behind it (the layout
+		// found no clear stretch for it). Then it is drawn after the connectors, backed like an edge label.
+		const groupName = (g) => h('text', { class: 'lcd-group-label' + (g.labelHalo ? ' lcd-halo' : ''), x: n2(g.labelX), y: n2(baseline(g.labelY + g.labelH / 2, T.group.size)) }, g.label);
+		const groups = geo.groups.slice().sort((a, b) => a.depth - b.depth).map((g) => h('g', { class: 'lcd-group' }, [
+			h('rect', { class: 'lcd-group-box', x: n2(g.x), y: n2(g.y), width: n2(g.w), height: n2(g.h), rx: '10', ry: '10' }),
+			g.labelHalo ? null : groupName(g),
+			g.tip ? h('title', {}, g.tip) : null
+		]));
+		const backedNames = geo.groups.filter((g) => g.labelHalo).map(groupName);
+
+		const edges = geo.edges.map((e) => h('g', { class: 'lcd-edge-g' }, [
+			h('path', { class: 'lcd-edge' + (e.dashed ? ' lcd-dashed' : ''), d: edgePath(e.points, 5, S.arrow - 1) }),
+			h('path', { class: 'lcd-arrow', d: arrowPath(e.arrow, S) }),
+			e.tip ? h('title', {}, e.tip) : null
+		]));
+
+		const nodes = geo.nodes.map((n) => {
+			const cls = 'lcd-node lcd-' + n.shape + (n.accent ? ' lcd-accent' : '') + (n.link ? ' lcd-linked' : '');
+			const attrs = { class: cls, 'data-lc-node': n.id };
+			if (n.link) {
+				// The attribute carries the NODE ID, not the path: the host looks the link up in its own
+				// copy of the spec, so nothing the webview says can choose which file is opened.
+				attrs['data-lc-link'] = n.id; attrs.tabindex = '0'; attrs.role = 'link';
+				attrs['aria-label'] = 'Open ' + n.link.path + (n.link.symbol ? ' at ' + n.link.symbol : n.link.line ? ' line ' + n.link.line : '');
+			}
+			const parts = shapeNodes(n, B);
+			let yy = n.cy - n.textH / 2 + (n.textDy || 0);
+			let firstCenter = null, nameW = 0;
+			n.lines.forEach((line, i) => {
+				if (line.role === 'sub' && i > 0) { yy += B.textGap; }
+				const cy = yy + line.h / 2;
+				if (firstCenter === null) { firstCenter = cy; nameW = line.w; }
+				parts.push(h('text', { class: line.role === 'sub' ? 'lcd-sub' : 'lcd-name', x: n2(n.cx), y: n2(baseline(cy, T[line.role].size)), 'text-anchor': 'middle' }, line.text));
+				yy += line.h;
+			});
+			if (n.link) { parts.push(fileGlyph(n.cx + nameW / 2 + 4, (firstCenter || n.cy) - 5.5)); }
+			const tips = [];
+			if (n.tip) { tips.push(n.tip); }
+			if (n.link) { tips.push(n.link.path + (n.link.symbol ? ' · ' + n.link.symbol : n.link.line ? ':' + n.link.line : '')); }
+			if (tips.length) { parts.push(h('title', {}, tips.join('\n'))); }
+			return h('g', attrs, parts);
+		});
+
+		const labels = geo.edges.filter((e) => e.label).map((e) => h('text', {
+			class: 'lcd-edge-label' + (e.label.halo ? ' lcd-halo' : ''),
+			x: n2(e.label.x), y: n2(baseline(e.label.y + e.label.h / 2, T.edge.size))
+		}, e.label.text));
+
+		const body = [h('g', { class: 'lcd-groups' }, groups), h('g', { class: 'lcd-edges' }, edges), h('g', { class: 'lcd-nodes' }, nodes), h('g', { class: 'lcd-labels' }, backedNames.concat(labels))];
+		kids.push(top ? h('g', { transform: 'translate(0,' + n2(top) + ')' }, body) : h('g', {}, body));
+
+		const height = geo.height + top;
+		if (o.background) { kids.splice(o.css ? 1 : 0, 0, h('rect', { class: 'lcd-bg', x: '0', y: '0', width: String(width), height: String(height) })); }
+		const attrs = { class: 'lcd-svg', viewBox: '0 0 ' + width + ' ' + height, width: String(width), height: String(height), role: 'img', 'aria-label': spec.title || 'Diagram', focusable: 'false' };
+		if (o.standalone) { attrs.xmlns = SVG_NS; }
+		const svg = h('svg', attrs, kids);
+		svg.width = width; svg.height = height;
+		return svg;
+	}
+
+	// ---- two ways to draw the same tree -----------------------------------------------------------
+
+	const escText = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+	const escAttr = (s) => escText(s).replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+	/**
+	 * Characters XML 1.0 does not allow at all. repair.cleanText() already strips them from labels;
+	 * this is the same rule again at the last moment, so an exported file is always well-formed.
+	 */
+	// eslint-disable-next-line no-control-regex
+	const xmlSafe = (s) => String(s).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f￾￿]/g, '');
+
+	/** Serialize a tree to an SVG string. Unknown tags and attributes are a bug, so they throw. */
+	function toSvg(vnode) {
+		if (!TAGS.has(vnode.tag)) { throw new Error('diagram: element <' + vnode.tag + '> is not allowed'); }
+		let out = '<' + vnode.tag;
+		for (const k of Object.keys(vnode.attrs || {})) {
+			if (!ATTRS.has(k)) { throw new Error('diagram: attribute "' + k + '" is not allowed'); }
+			out += ' ' + k + '="' + escAttr(xmlSafe(vnode.attrs[k])) + '"';
+		}
+		if (vnode.text == null && !(vnode.children && vnode.children.length)) { return out + '/>'; }
+		out += '>';
+		if (vnode.text != null) {
+			// A stylesheet is ours (theme.css) and CDATA keeps it readable; text is escaped.
+			out += vnode.tag === 'style' ? '<![CDATA[' + String(vnode.text).replace(/]]>/g, ']] >') + ']]>' : escText(xmlSafe(vnode.text));
+		}
+		for (const c of (vnode.children || [])) { out += toSvg(c); }
+		return out + '</' + vnode.tag + '>';
+	}
+
+	/**
+	 * Build real DOM for the chat. Refuses any tag or attribute off the allow-lists, and refuses
+	 * <style> outright — the live view is styled by the page's own stylesheet.
+	 * @param {any} vnode
+	 * @param {Document} doc
+	 */
+	function mount(vnode, doc) {
+		if (!TAGS.has(vnode.tag) || vnode.tag === 'style') { throw new Error('diagram: element <' + vnode.tag + '> is not allowed'); }
+		const el = doc.createElementNS(SVG_NS, vnode.tag);
+		for (const k of Object.keys(vnode.attrs || {})) {
+			if (!ATTRS.has(k) || k === 'xmlns') { if (k === 'xmlns') { continue; } throw new Error('diagram: attribute "' + k + '" is not allowed'); }
+			el.setAttribute(k, String(vnode.attrs[k]));
+		}
+		if (vnode.text != null) { el.textContent = String(vnode.text); }
+		for (const c of (vnode.children || [])) { el.appendChild(mount(c, doc)); }
+		return el;
+	}
+
+	return { SVG_NS, TAGS, ATTRS, build, toSvg, mount, edgePath, arrowPath, wrapText };
+}));
diff --git a/extensions/levelcode-ai/diagram/text.js b/extensions/levelcode-ai/diagram/text.js
new file mode 100644
index 0000000..9dec93e
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/text.js
@@ -0,0 +1,151 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · a diagram as words  (docs/RICH-DIAGRAMS.md, "UX" + "Context budget")
+ *
+ *  Three text forms of one spec, each for a reader a picture cannot serve:
+ *
+ *    outline(spec)    a screen reader. The nodes and the connections, in the order the model wrote
+ *                     them, as sentences — carried next to the picture so the diagram has an
+ *                     accessible name AND a description that says what it shows.
+ *    stub(record)     the model, later. "diagram: Jev routing, 4 nodes, id d-17" — the one line that
+ *                     stands in for a spec once the conversation is compacted.
+ *    toMermaid(spec)  another tool. A flowchart GitHub, GitLab and most docs sites render natively —
+ *                     what "Open as Mermaid" and "Insert into Markdown" produce, and what a session
+ *                     exported to Markdown carries in place of the picture.
+ *
+ *  All three read the full text of a label that was shortened for display (`tip`), because none of
+ *  them has a tooltip to hover.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+(function (root, factory) {
+	'use strict';
+	if (typeof module === 'object' && module.exports) { module.exports = factory(); }
+	else { (root.LCDiagram = root.LCDiagram || {}).text = factory(); }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+	'use strict';
+
+	const arr = (v) => (Array.isArray(v) ? v : []);
+	const SHAPE_WORD = { decision: 'decision', store: 'data store', actor: 'actor' };
+
+	/** A node's name as it should be READ: the full label and second line, not the shortened ones. */
+	function nodeName(n) {
+		if (n.tip) { return String(n.tip); }
+		return n.sub ? n.label + ' — ' + n.sub : String(n.label);
+	}
+	const shortName = (n) => String(n.tip ? String(n.tip).split(' — ')[0] : n.label);
+
+	/**
+	 * The screen-reader outline.
+	 * @returns {{ title: string, summary: string, nodes: string[], edges: string[], text: string }}
+	 */
+	function outline(spec) {
+		const nodes = arr(spec && spec.nodes), edges = arr(spec && spec.edges), groups = arr(spec && spec.groups);
+		const byId = new Map(nodes.map((n) => [n.id, n]));
+		const groupLabel = new Map(groups.map((g) => [g.id, g.tip || g.label]));
+		const nodeLines = nodes.map((n) => {
+			const bits = [nodeName(n)];
+			if (SHAPE_WORD[n.shape]) { bits.push(SHAPE_WORD[n.shape]); }
+			if (n.group && groupLabel.has(n.group)) { bits.push('in ' + groupLabel.get(n.group)); }
+			if (n.accent) { bits.push('highlighted'); }
+			if (n.link && n.link.path) { bits.push('opens ' + n.link.path); }
+			return bits.join(', ');
+		});
+		const edgeLines = edges.filter((e) => byId.has(e.from) && byId.has(e.to)).map((e) => {
+			const label = e.tip || e.label;
+			return shortName(byId.get(e.from)) + ' to ' + shortName(byId.get(e.to)) + (label ? ', ' + label : '') + (e.style === 'dashed' ? ' (dashed)' : '');
+		});
+		const count = (k, one, many) => k + ' ' + (k === 1 ? one : many);
+		const title = String((spec && (spec.tip || spec.title)) || 'Diagram');
+		const summary = count(nodeLines.length, 'node', 'nodes') + ', ' + count(edgeLines.length, 'connection', 'connections') + '.';
+		const text = title + '. ' + summary
+			+ (nodeLines.length ? ' Nodes: ' + nodeLines.join('; ') + '.' : '')
+			+ (edgeLines.length ? ' Connections: ' + edgeLines.join('; ') + '.' : '');
+		return { title, summary, nodes: nodeLines, edges: edgeLines, text };
+	}
+
+	/**
+	 * The one-line stand-in for a diagram once its spec has left the conversation.
+	 * @param {{ id: string, spec: any }} record
+	 */
+	function stub(record) {
+		const spec = (record && record.spec) || {};
+		const k = arr(spec.nodes).length;
+		// One line, always: the title is the only free text in it, so that is where a newline could hide.
+		const title = String(spec.title || 'untitled').replace(/\s+/g, ' ').trim();
+		return 'diagram: ' + title + ', ' + k + ' node' + (k === 1 ? '' : 's') + ', id ' + String((record && record.id) || '?');
+	}
+
+	// ---- Mermaid ------------------------------------------------------------------------------------
+	// The source is written to be pasted somewhere else, so it is written defensively: every label is
+	// quoted and entity-escaped, and ids are rewritten wherever Mermaid would read them as something
+	// else — `end` closes a subgraph, and a leading digit or a hyphen is not an id at all.
+	const RESERVED = new Set(['end', 'subgraph', 'graph', 'flowchart', 'class', 'classdef', 'click', 'style', 'linkstyle', 'default', 'direction', 'call', 'href', 'interpolate']);
+	const mmText = (s) => String(s).replace(/&/g, '#amp;').replace(/"/g, '#quot;').replace(/</g, '#lt;').replace(/>/g, '#gt;').replace(/[\r\n]+/g, ' ');
+
+	/** Map every node and group id to one Mermaid accepts, keeping them readable and unique. */
+	function mermaidIds(ids) {
+		const used = new Set(), out = new Map();
+		for (const id of ids) {
+			let m = String(id).replace(/[^A-Za-z0-9_]/g, '_');
+			if (!m || /^[0-9_]/.test(m) || RESERVED.has(m.toLowerCase())) { m = 'n_' + m; }
+			let k = 2, candidate = m;
+			while (used.has(candidate)) { candidate = m + '_' + (k++); }
+			used.add(candidate); out.set(id, candidate);
+		}
+		return out;
+	}
+
+	/**
+	 * The spec as a Mermaid flowchart.
+	 * @param {any} spec
+	 * @param {{ title?: boolean }} [opts]  title: emit the spec's title as Mermaid front matter (default true)
+	 */
+	function toMermaid(spec, opts) {
+		const nodes = arr(spec && spec.nodes), edges = arr(spec && spec.edges), groups = arr(spec && spec.groups);
+		const ids = mermaidIds(nodes.map((n) => n.id).concat(groups.map((g) => 'group:' + g.id)));
+		const gid = (id) => ids.get('group:' + id);
+		const lines = [];
+		if ((!opts || opts.title !== false) && spec && spec.title) {
+			lines.push('---', 'title: ' + JSON.stringify(String(spec.tip || spec.title)), '---');
+		}
+		lines.push('flowchart ' + (spec && spec.direction === 'down' ? 'TD' : 'LR'));
+		const shape = (n) => {
+			const label = '"' + mmText(n.tip ? String(n.tip).replace(' — ', '<br/>') : (n.sub ? n.label + '<br/>' + n.sub : n.label)).replace(/#lt;br\/#gt;/g, '<br/>') + '"';
+			const id = ids.get(n.id);
+			if (n.shape === 'decision') { return id + '{' + label + '}'; }
+			if (n.shape === 'store') { return id + '[(' + label + ')]'; }
+			if (n.shape === 'actor') { return id + '([' + label + '])'; }
+			return id + '[' + label + ']';
+		};
+		const groupIds = new Set(groups.map((g) => g.id));
+		const emitGroup = (g, depth) => {
+			const pad = '  '.repeat(depth);
+			lines.push(pad + 'subgraph ' + gid(g.id) + '["' + mmText(g.tip || g.label) + '"]');
+			for (const n of nodes) { if (n.group === g.id) { lines.push(pad + '  ' + shape(n)); } }
+			for (const k of groups) { if (k.parent === g.id && k.id !== g.id) { emitGroup(k, depth + 1); } }
+			lines.push(pad + 'end');
+		};
+		for (const n of nodes) { if (!n.group || !groupIds.has(n.group)) { lines.push('  ' + shape(n)); } }
+		for (const g of groups) { if (!g.parent || !groupIds.has(g.parent) || g.parent === g.id) { emitGroup(g, 1); } }
+		for (const e of edges) {
+			if (!ids.has(e.from) || !ids.has(e.to)) { continue; }
+			const label = e.tip || e.label;
+			lines.push('  ' + ids.get(e.from) + (e.style === 'dashed' ? ' -.->' : ' -->') + (label ? '|"' + mmText(label) + '"| ' : ' ') + ids.get(e.to));
+		}
+		const accent = nodes.filter((n) => n.accent).map((n) => ids.get(n.id));
+		if (accent.length) { lines.push('  classDef accent stroke-width:2px', '  class ' + accent.join(',') + ' accent'); }
+		return lines.join('\n') + '\n';
+	}
+
+	/** The spec as it should be shown or copied: stable key order, two-space indent, no renderer-only fields. */
+	function toSource(spec) {
+		const strip = (o) => { const c = Object.assign({}, o); delete c.tip; return c; };
+		const clean = Object.assign({}, spec);
+		delete clean.tip;
+		if (Array.isArray(clean.nodes)) { clean.nodes = clean.nodes.map(strip); }
+		if (Array.isArray(clean.edges)) { clean.edges = clean.edges.map(strip); }
+		if (Array.isArray(clean.groups)) { clean.groups = clean.groups.map(strip); }
+		return JSON.stringify(clean, null, 2);
+	}
+
+	return { outline, stub, toMermaid, toSource, mermaidIds, nodeName };
+}));
diff --git a/extensions/levelcode-ai/test/diagramScene.test.js b/extensions/levelcode-ai/test/diagramScene.test.js
new file mode 100644
index 0000000..ad4a589
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramScene.test.js
@@ -0,0 +1,310 @@
+/*---------------------------------------------------------------------------------------------
+ *  Rich diagrams — the painter and the house style — run: node test/diagramScene.test.js
+ *
+ *  docs/RICH-DIAGRAMS.md, "Safe rendering" and "Style guide". Two promises are pinned here:
+ *
+ *  SAFE.   Model output is untrusted. A label is a text node, never markup; a diagram is built from
+ *          two short allow-lists with no script, no foreignObject, no href, no style attribute and no
+ *          event handler in them; and the painter refuses anything off the lists.
+ *  STYLED. One module owns every visual decision, colours are editor theme tokens, and the rendered
+ *          SVG for known diagrams is snapshotted under both palettes — so a change of style is a
+ *          diff someone looked at, not an accident.
+ *
+ *      UPDATE_SNAPSHOTS=1 node test/diagramScene.test.js     regenerate, then LOOK at the result
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const scene = require('../diagram/scene');
+const layout = require('../diagram/layout');
+const repair = require('../diagram/repair');
+const theme = require('../diagram/theme');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+const FIX = path.join(__dirname, 'fixtures', 'diagrams');
+const gallery = JSON.parse(fs.readFileSync(path.join(FIX, 'gallery.json'), 'utf8'));
+const specOf = (name) => repair.prepare(gallery.find((g) => g.name === name).spec).spec;
+const build = (spec, opts) => scene.build(spec, layout.layout(spec), opts);
+const walk = (node, fn) => { fn(node); for (const c of (node.children || [])) { walk(c, fn); } };
+/** Every start tag in a serialized SVG, with its attribute names. Text is escaped, so a raw "<" only ever opens one of ours. */
+function tagsIn(svg) {
+	const out = [];
+	const body = svg.replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, '');
+	const re = /<([A-Za-z][\w:-]*)((?:\s+[\w:-]+="[^"]*")*)\s*\/?>/g;
+	let m;
+	while ((m = re.exec(body))) { out.push({ tag: m[1], attrs: (m[2].match(/[\w:-]+(?==")/g) || []) }); }
+	return out;
+}
+
+/** The nastiest labels we can think of — each of these must come out as the text it is. */
+const HOSTILE = {
+	title: '</title><script>alert("t")</script>',
+	nodes: [
+		{ id: 'a', label: '<script>alert(1)</script>', sub: '"><img src=x onerror=alert(2)>' },
+		{ id: 'b', label: "'><svg onload=alert(3)>", link: { path: 'javascript:alert(4)', symbol: '"><x' } },
+		{ id: 'c', label: '</text><foreignObject>', sub: '&lt;b&gt; ]]> &amp; &#x3c;' },
+		{ id: 'd', label: '<a href="//evil">x</a>', shape: 'decision' }
+	],
+	edges: [{ from: 'a', to: 'b', label: '<style>*{}</style>' }, { from: 'b', to: 'c', label: '" onmouseover="x' }, { from: 'c', to: 'd' }],
+	groups: [{ id: 'g', label: '<iframe src=//evil>' }]
+};
+HOSTILE.nodes[0].group = 'g';
+
+test('ALLOW-LIST: there is no script, foreignObject, link or image element, and no href, style or handler attribute', () => {
+	for (const bad of ['script', 'foreignObject', 'a', 'image', 'use', 'iframe', 'object', 'embed', 'animate', 'set']) { assert.ok(!scene.TAGS.has(bad), '<' + bad + '> must not be drawable'); }
+	for (const bad of ['href', 'xlink:href', 'style', 'src', 'onclick', 'onload', 'onerror', 'id', 'filter', 'mask', 'clip-path', 'fill', 'stroke']) { assert.ok(!scene.ATTRS.has(bad), 'attribute "' + bad + '" must not be settable'); }
+	for (const a of scene.ATTRS) { assert.ok(!/^on/i.test(a), a + ' looks like an event handler'); }
+});
+
+test('ALLOW-LIST: everything the painter builds is on the lists — the gallery and the hostile spec', () => {
+	const specs = gallery.map((g) => repair.prepare(g.spec).spec).concat([repair.prepare(HOSTILE, { final: true }).spec]);
+	for (const spec of specs) {
+		for (const opts of [{}, { title: true, css: theme.css({ resolved: theme.PALETTES.dark }), standalone: true }]) {
+			walk(build(spec, opts), (node) => {
+				assert.ok(scene.TAGS.has(node.tag), '<' + node.tag + '>');
+				for (const k of Object.keys(node.attrs)) { assert.ok(scene.ATTRS.has(k), k + ' on <' + node.tag + '>'); }
+				assert.ok(!(node.text != null && node.children && node.children.length), 'an element has text or children, never both');
+			});
+		}
+	}
+});
+
+test('ALLOW-LIST: both painters REFUSE what is off the lists, rather than trusting whoever built the tree', () => {
+	const fakeDoc = { createElementNS: () => ({ setAttribute() {}, appendChild() {}, set textContent(v) {} }) };
+	const bad = [
+		{ tag: 'script', attrs: {}, text: 'alert(1)' },
+		{ tag: 'foreignObject', attrs: {} },
+		{ tag: 'a', attrs: {} },
+		{ tag: 'g', attrs: { onclick: 'alert(1)' } },
+		{ tag: 'g', attrs: { href: 'javascript:alert(1)' } },
+		{ tag: 'rect', attrs: { style: 'background:url(//evil)' } },
+		{ tag: 'svg', attrs: {}, children: [{ tag: 'g', attrs: {}, children: [{ tag: 'script', attrs: {} }] }] }
+	];
+	for (const vnode of bad) {
+		assert.throws(() => scene.toSvg(vnode), /not allowed/, 'toSvg: ' + JSON.stringify(vnode));
+		assert.throws(() => scene.mount(vnode, fakeDoc), /not allowed/, 'mount: ' + JSON.stringify(vnode));
+	}
+	assert.throws(() => scene.mount({ tag: 'style', attrs: {}, text: '*{}' }, fakeDoc), /not allowed/, 'the live view never takes a stylesheet from a tree');
+});
+
+test('TEXT NODES: mount() puts every label in with textContent — markup in a label never becomes an element', () => {
+	// A stand-in document that records what was done to it, and has no innerHTML to misuse.
+	const made = [];
+	const doc = { createElementNS(ns, tag) {
+		const el = { ns, tag, attrs: {}, kids: [], text: null,
+			setAttribute(k, v) { this.attrs[k] = v; }, appendChild(c) { this.kids.push(c); },
+			set textContent(v) { this.text = v; }, get textContent() { return this.text; },
+			set innerHTML(v) { throw new Error('innerHTML was used'); }, set outerHTML(v) { throw new Error('outerHTML was used'); },
+			insertAdjacentHTML() { throw new Error('insertAdjacentHTML was used'); } };
+		made.push(el); return el;
+	} };
+	const spec = repair.prepare(HOSTILE, { final: true }).spec;
+	const root = scene.mount(build(spec), doc);
+	assert.strictEqual(root.tag, 'svg');
+	assert.ok(made.every((el) => el.ns === 'http://www.w3.org/2000/svg'), 'every element is created in the SVG namespace');
+	assert.ok(made.every((el) => scene.TAGS.has(el.tag) && el.tag !== 'style'));
+	const texts = made.filter((el) => el.text != null).map((el) => el.text);
+	assert.ok(texts.includes('<script>alert(1)</script>'), 'the label is there, as text: ' + texts.join(' | '));
+	assert.ok(texts.includes('</text><foreignObject>'));
+	assert.ok(!made.some((el) => /script|foreignobject|img|iframe/i.test(el.tag)), 'and nothing it "contained" exists as an element');
+	for (const el of made) { for (const k of Object.keys(el.attrs)) { assert.ok(scene.ATTRS.has(k) && !/^on|href|style/i.test(k), k); } }
+});
+
+test('ESCAPING: a serialized diagram contains only our elements and attributes, whatever the labels said', () => {
+	const spec = repair.prepare(HOSTILE, { final: true }).spec;
+	const svg = scene.toSvg(build(spec, { title: true, css: theme.css({ resolved: theme.PALETTES.light }), standalone: true }));
+	const tags = tagsIn(svg);
+	assert.ok(tags.length > 20);
+	for (const t of tags) {
+		assert.ok(scene.TAGS.has(t.tag), 'unexpected element <' + t.tag + '>');
+		for (const a of t.attrs) { assert.ok(scene.ATTRS.has(a), 'unexpected attribute ' + a + ' on <' + t.tag + '>'); }
+	}
+	// No attribute value was broken out of. Text is escaped, so every "<" opens a tag — and every tag
+	// must be either a plain end tag or a start tag made of nothing but name="value" pairs.
+	const markup = svg.replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, '');
+	for (const m of markup.matchAll(/<[^>]*>/g)) {
+		assert.ok(/^<\/[A-Za-z][\w:-]*>$/.test(m[0]) || /^<[A-Za-z][\w:-]*(\s+[\w:-]+="[^"<>]*")*\s*\/?>$/.test(m[0]), 'malformed tag: ' + m[0]);
+	}
+	assert.ok(!/<[^>]*$/.test(markup), 'no tag is left open');
+	assert.ok(svg.includes('&lt;script&gt;alert(1)&lt;/script&gt;'), 'the label survives, escaped');
+	assert.ok(!/<script|<foreignObject|<img|<iframe|<a\s/i.test(svg));
+	// well-formed: every tag that opens closes, in order
+	const stack = [];
+	const body = svg.replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, '');
+	for (const m of body.matchAll(/<(\/?)([A-Za-z][\w:-]*)[^>]*?(\/?)>/g)) {
+		if (m[1]) { assert.strictEqual(stack.pop(), m[2], 'mismatched </' + m[2] + '>'); } else if (!m[3]) { stack.push(m[2]); }
+	}
+	assert.deepStrictEqual(stack, []);
+});
+
+test('LINKS: a clickable node carries its NODE ID, never the path — the host looks the link up itself', () => {
+	const spec = specOf('arch');
+	let linked = 0;
+	walk(build(spec), (node) => {
+		if (node.attrs['data-lc-link'] === undefined) { return; }
+		linked++;
+		assert.match(String(node.attrs['data-lc-link']), /^[a-z0-9][a-z0-9_-]*$/, 'a slug, so it cannot smuggle anything');
+		assert.strictEqual(node.attrs['data-lc-link'], node.attrs['data-lc-node']);
+		assert.strictEqual(node.attrs.tabindex, '0', 'reachable from the keyboard');
+		assert.strictEqual(node.attrs.role, 'link');
+		assert.match(node.attrs['aria-label'], /^Open /);
+		assert.ok(node.children.some((c) => c.tag === 'title'), 'hover shows the path');
+		assert.ok(node.children.some((c) => c.attrs.class === 'lcd-link-icon'), 'and a small file glyph marks it');
+	});
+	assert.strictEqual(linked, 2);
+	const hostile = repair.prepare(HOSTILE, { final: true }).spec;
+	walk(build(hostile), (node) => { if (node.attrs['data-lc-link']) { assert.strictEqual(node.attrs['data-lc-link'], 'b', 'the javascript: "path" is nowhere in an attribute the host acts on'); } });
+});
+
+test('ACCESSIBLE: the picture is an image named by its title', () => {
+	const svg = build(specOf('jev'));
+	assert.strictEqual(svg.attrs.role, 'img');
+	assert.strictEqual(svg.attrs['aria-label'], 'Jev classifies; your code decides the action');
+	assert.strictEqual(svg.attrs.focusable, 'false');
+});
+
+test('STYLE GUIDE: the type scale, the box and the accent are the numbers in the spec', () => {
+	assert.deepStrictEqual([theme.TYPE.title.size, theme.TYPE.name.size, theme.TYPE.sub.size], [15, 13, 11.5], 'three sizes: title 15, node name 13, secondary 11.5');
+	assert.strictEqual(theme.TYPE.name.weight, 600, 'node name is semibold');
+	assert.strictEqual(theme.MIN_TEXT, 10.5);
+	for (const t of Object.values(theme.TYPE)) { assert.ok(t.size >= theme.MIN_TEXT, 'nothing below 10.5'); }
+	assert.deepStrictEqual([theme.BOX.radius, theme.BOX.border, theme.BOX.padX, theme.BOX.accentBorder], [8, 1.25, 12, 2]);
+	assert.strictEqual(theme.SPACE.groupInset, 16, 'children inset 16');
+	const css = theme.css();
+	assert.match(css, /\.lcd-shape \{[^}]*stroke-width: 1\.25px/);
+	assert.match(css, /\.lcd-accent \.lcd-shape \{[^}]*stroke-width: 2px/);
+	const box = build(specOf('jev')).children[0].children.find((g) => g.attrs.class === 'lcd-nodes').children[0].children[0];
+	assert.strictEqual(box.tag, 'rect'); assert.strictEqual(box.attrs.rx, '8');
+});
+
+test('STYLE GUIDE: same kind, same shape — box, diamond, cylinder, pill', () => {
+	const spec = repair.prepare({ title: 'T', nodes: [{ id: 'a', label: 'Step' }, { id: 'b', label: 'Branch?', shape: 'decision' }, { id: 'c', label: 'Data', shape: 'store' }, { id: 'd', label: 'Person', shape: 'actor' }], edges: [] }).spec;
+	const nodes = build(spec).children[0].children.find((g) => g.attrs.class === 'lcd-nodes').children;
+	const shapeOf = (i) => nodes[i].children.filter((c) => /lcd-shape/.test(c.attrs.class || ''));
+	assert.strictEqual(shapeOf(0)[0].tag, 'rect');
+	assert.strictEqual(shapeOf(1)[0].tag, 'path'); assert.strictEqual((shapeOf(1)[0].attrs.d.match(/L/g) || []).length, 3, 'a diamond has four corners');
+	assert.strictEqual(shapeOf(2).length, 2, 'a cylinder is a body and a lid'); assert.match(shapeOf(2)[0].attrs.d, /A/);
+	const pill = shapeOf(3)[0];
+	assert.strictEqual(pill.tag, 'rect'); assert.strictEqual(Number(pill.attrs.rx), Number(pill.attrs.height) / 2, 'a pill is rounded to half its height');
+});
+
+test('THEME: colours are editor theme tokens — the live stylesheet contains no colour of its own', () => {
+	const css = theme.css();
+	const rules = css.split('\n').filter((l) => !/--lcd-[a-z-]+:/.test(l));   // everything except the token definitions
+	for (const rule of rules) { assert.ok(!/#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(/.test(rule), 'a literal colour in: ' + rule); }
+	for (const m of css.matchAll(/var\(--lcd-([a-z-]+)\)/g)) { assert.ok(theme.TOKEN_NAMES.includes(m[1]), '--lcd-' + m[1] + ' is used but never defined'); }
+	for (const name of theme.TOKEN_NAMES) { assert.match(theme.TOKENS[name], /var\(--vscode-/, name + ' is defined from the editor theme'); }
+	assert.match(css, /^\.lcd \{/, 'scoped to the diagram container');
+	assert.ok(css.split('\n').every((l) => /^(body\.vscode-high-contrast[^{]*)?\.lcd[ ,{]/.test(l)), 'no rule reaches outside it');
+	assert.match(css, /vscode-high-contrast/, 'high-contrast themes get real borders');
+});
+
+test('THEME: an exported stylesheet has every token resolved, and both palettes are legible', () => {
+	const lum = (hex) => { const v = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255).map((c) => (c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4))); return 0.2126 * v[0] + 0.7152 * v[1] + 0.0722 * v[2]; };
+	const contrast = (a, b) => { const x = lum(a), y = lum(b); return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05); };
+	for (const mode of ['light', 'dark']) {
+		const pal = theme.PALETTES[mode];
+		for (const name of theme.TOKEN_NAMES) { assert.ok(pal[name], mode + ' palette is missing ' + name); }
+		const css = theme.css({ resolved: pal });
+		assert.ok(!/var\(/.test(css), mode + ': nothing is left to resolve');
+		assert.match(css, /^svg\.lcd-svg /m, 'scoped so it can sit inside a standalone file');
+		assert.ok(contrast(pal.fg, pal.bg) >= 7, mode + ' text ' + contrast(pal.fg, pal.bg).toFixed(1));
+		assert.ok(contrast(pal.muted, pal.bg) >= 4.5, mode + ' secondary text ' + contrast(pal.muted, pal.bg).toFixed(1));
+		assert.ok(contrast(pal.fg, pal['node-fill']) >= 7, mode + ' text on a box');
+		assert.ok(contrast(pal.fg, pal['accent-fill']) >= 7, mode + ' text on the accent box');
+		assert.ok(contrast(pal.accent, pal.bg) >= 3, mode + ' accent border');
+		assert.ok(contrast(pal.line, pal.bg) >= 3, mode + ' connectors');
+		assert.ok(contrast(pal['node-stroke'], pal.bg) >= 1.8, mode + ' box border is visible but quiet');
+	}
+});
+
+test('EXPORT: a file has no page behind it, so an export paints the editor background itself', () => {
+	const spec = specOf('jev');
+	const bare = build(spec, {}), filled = build(spec, { background: true, css: theme.css({ resolved: theme.PALETTES.dark }), standalone: true });
+	const bg = (tree) => { let found = null; walk(tree, (node) => { if (node.attrs.class === 'lcd-bg') { found = node; } }); return found; };
+	assert.strictEqual(bg(bare), null, 'in the chat the page IS the background');
+	const rect = bg(filled);
+	assert.deepStrictEqual([rect.tag, rect.attrs.width, rect.attrs.height], ['rect', String(filled.width), String(filled.height)], 'it covers the whole picture');
+	assert.strictEqual(filled.children[0].tag, 'style'); assert.strictEqual(filled.children[1], rect, 'and sits behind everything else');
+	assert.match(theme.css({ resolved: theme.PALETTES.dark }), /\.lcd-bg \{ fill: #1e1f22; \}/);
+});
+
+test('EXPORT: the title is drawn inside an exported file, wrapped to the picture', () => {
+	const spec = specOf('decision');
+	const plain = build(spec), titled = build(spec, { title: true });
+	const titles = [];
+	walk(titled, (node) => { if (node.attrs.class === 'lcd-title') { titles.push(node.text); } });
+	assert.ok(titles.length >= 2, 'a long title wraps: ' + titles.join(' / '));
+	assert.strictEqual(titles.join(' '), spec.title, 'and loses no word');
+	assert.ok(titled.height > plain.height);
+	let any = false; walk(plain, (node) => { if (node.attrs.class === 'lcd-title') { any = true; } });
+	assert.strictEqual(any, false, 'in the chat the title is HTML above the picture, not part of it');
+	assert.strictEqual(scene.toSvg(build(spec, { standalone: true })).slice(0, 5), '<svg ');
+	assert.match(scene.toSvg(build(spec, { standalone: true })), /xmlns="http:\/\/www\.w3\.org\/2000\/svg"/);
+});
+
+test('GEOMETRY: connectors round their corners, and stop at the base of the arrowhead', () => {
+	const d = scene.edgePath([{ x: 0, y: 0 }, { x: 50, y: 0 }, { x: 50, y: 40 }, { x: 100, y: 40 }], 5, 6);
+	assert.strictEqual(d, 'M0,0 L45,0 Q50,0 50,5 L50,35 Q50,40 55,40 L94,40');
+	assert.strictEqual(scene.edgePath([{ x: 0, y: 0 }, { x: 3, y: 0 }, { x: 3, y: 3 }], 5, 0), 'M0,0 L1.5,0 Q3,0 3,1.5 L3,3', 'a corner never rounds past half a run');
+	assert.strictEqual(scene.arrowPath({ x: 100, y: 40, dx: 1, dy: 0 }, theme.SPACE), 'M100,40 L93,43.6 L93,36.4 Z');
+});
+
+test('GROUP NAMES: a name that a connector has to pass behind is drawn AFTER the connectors, backed — every other name is drawn with its frame', () => {
+	// one group whose name is clear, and one whose frame has no clear stretch for it
+	const s = repair.prepare({ title: 'T', direction: 'down', groups: [{ id: 'long', label: 'A container with a long name' }, { id: 'ok', label: 'Data' }],
+		nodes: [{ id: 'top', label: 'Chat webview' }, { id: 'a', label: 'A', group: 'long' }, { id: 'r', label: 'Redis cache', group: 'ok' }], edges: [{ from: 'top', to: 'a' }, { from: 'a', to: 'r' }] }).spec;
+	const geo = layout.layout(s);
+	assert.deepStrictEqual(geo.groups.map((g) => [g.id, g.labelHalo]), [['long', true], ['ok', false]]);
+	const svg = scene.build(s, geo, {});
+	const body = svg.children[svg.children.length - 1];
+	const layer = (cls) => body.children.find((c) => c.attrs.class === cls);
+	assert.deepStrictEqual(body.children.map((c) => c.attrs.class), ['lcd-groups', 'lcd-edges', 'lcd-nodes', 'lcd-labels'], 'the paint order: frames, connectors, boxes, then text that must stay on top');
+	const names = (root) => { const out = []; walk(root, (n) => { if (n.tag === 'text' && /lcd-group-label/.test(n.attrs.class)) { out.push([n.text, n.attrs.class]); } }); return out; };
+	assert.deepStrictEqual(names(layer('lcd-groups')), [['Data', 'lcd-group-label']], 'a clear name stays with its frame, under the connectors');
+	assert.deepStrictEqual(names(layer('lcd-labels')), [['A container with a long name', 'lcd-group-label lcd-halo']], 'a crossed one goes on top, with the halo an edge label gets');
+	assert.strictEqual(names(svg).length, 2, 'each name is drawn exactly once');
+	// and the halo is the background colour, so the line reads as passing BEHIND the word
+	assert.match(theme.css(), /\.lcd-halo \{ paint-order: stroke; stroke: var\(--lcd-bg\)/);
+	// both painters accept it
+	assert.ok(/class="lcd-group-label lcd-halo"/.test(scene.toSvg(scene.build(s, geo, { standalone: true, css: theme.css({ resolved: theme.PALETTES.light }) }))));
+});
+
+test('WELL-FORMED: a control character that slipped through cannot break an exported file', () => {
+	const svg = scene.toSvg({ tag: 'svg', attrs: { 'aria-label': 'a\u0000b\u0008c' }, children: [{ tag: 'text', attrs: {}, text: 'x\u0001y\u000bz' }] });
+	// eslint-disable-next-line no-control-regex
+	assert.ok(!/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(svg));
+	assert.match(svg, /aria-label="abc"/);
+});
+
+// ---- visual regression: the exact SVG, under both palettes ----------------------------------------
+const SNAP = path.join(FIX, 'snapshots');
+for (const name of ['jev', 'arch', 'decision']) {
+	for (const mode of ['light', 'dark']) {
+		test('SNAPSHOT: ' + name + ' · ' + mode, () => {
+			const spec = specOf(name);
+			// exactly the options the chat exports with: title, background, resolved colours
+			const svg = scene.toSvg(build(spec, { title: true, background: true, css: theme.css({ resolved: theme.PALETTES[mode] }), standalone: true })) + '\n';
+			const file = path.join(SNAP, name + '.' + mode + '.svg');
+			if (process.env.UPDATE_SNAPSHOTS) { fs.mkdirSync(SNAP, { recursive: true }); fs.writeFileSync(file, svg); return; }
+			assert.ok(fs.existsSync(file), 'no snapshot yet — run with UPDATE_SNAPSHOTS=1 and look at ' + file);
+			assert.strictEqual(svg, fs.readFileSync(file, 'utf8'), name + '.' + mode + '.svg changed. If that was intended: UPDATE_SNAPSHOTS=1, then look at it.');
+		});
+	}
+}
+
+test('SNAPSHOT: light and dark differ only in colour — one layout, one set of rules', () => {
+	for (const name of ['jev', 'arch', 'decision']) {
+		const strip = (s) => s.replace(/<style>[\s\S]*?<\/style>/, '');
+		const light = fs.readFileSync(path.join(SNAP, name + '.light.svg'), 'utf8'), dark = fs.readFileSync(path.join(SNAP, name + '.dark.svg'), 'utf8');
+		assert.notStrictEqual(light, dark);
+		assert.strictEqual(strip(light), strip(dark), name + ': the drawing itself is identical');
+	}
+});
+
+console.log('diagramScene: ' + n + ' tests passed');
diff --git a/extensions/levelcode-ai/test/diagramText.test.js b/extensions/levelcode-ai/test/diagramText.test.js
new file mode 100644
index 0000000..6819f8f
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramText.test.js
@@ -0,0 +1,227 @@
+/*---------------------------------------------------------------------------------------------
+ *  Rich diagrams — a diagram as words — run: node test/diagramText.test.js
+ *
+ *  docs/RICH-DIAGRAMS.md, "UX" (accessibility, fallback) and "Context budget" (the stub).
+ *  A picture has three readers it cannot serve: a screen reader, a model reading a compacted
+ *  conversation, and another tool. Each gets text generated from the SAME spec — so the model never
+ *  has to draw ASCII itself, and nothing the picture says is missing from the words.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const T = require('../diagram/text');
+const A = require('../diagram/ascii');
+const R = require('../diagram/repair');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+const gallery = JSON.parse(fs.readFileSync(path.join(__dirname, 'fixtures', 'diagrams', 'gallery.json'), 'utf8'));
+const specOf = (name) => R.prepare(gallery.find((g) => g.name === name).spec).spec;
+
+test('OUTLINE: every node and every connection, in the order the model wrote them', () => {
+	const o = T.outline(specOf('jev'));
+	assert.strictEqual(o.title, 'Jev classifies; your code decides the action');
+	assert.strictEqual(o.summary, '4 nodes, 3 connections.');
+	assert.deepStrictEqual(o.nodes, ['Customer message — plus account details', 'Jev — returns probabilities, highlighted', 'Route to billing', 'Human review']);
+	assert.deepStrictEqual(o.edges, ['Customer message to Jev', 'Jev to Route to billing, 0.90 or more', 'Jev to Human review, under 0.90']);
+	assert.ok(o.text.startsWith('Jev classifies; your code decides the action. 4 nodes, 3 connections. Nodes: '));
+});
+
+test('OUTLINE: shape, group, link and line style are said in words', () => {
+	const o = T.outline(specOf('arch'));
+	assert.ok(o.nodes.includes('Chat webview, actor'));
+	assert.ok(o.nodes.includes('agent.js — tool loop, in Extension host, highlighted, opens agent.js'));
+	assert.ok(o.nodes.includes('Sessions — append-only JSONL, data store, in Extension host'));
+	assert.ok(o.edges.includes('agent.js to Sessions, each turn (dashed)'));
+	assert.strictEqual(T.outline(specOf('single')).summary, '1 node, 0 connections.');
+});
+
+test('OUTLINE: a shortened label is read out in full — a screen reader has no tooltip to hover', () => {
+	const spec = R.prepare({ title: 'T', nodes: [{ id: 'a', label: 'Validate the incoming request payload' }, { id: 'b', label: 'Store' }], edges: [{ from: 'a', to: 'b', label: 'when every field checks out' }] }).spec;
+	assert.strictEqual(spec.nodes[0].label, 'Validate the incoming…');
+	const o = T.outline(spec);
+	assert.strictEqual(o.nodes[0], 'Validate the incoming request payload');
+	assert.strictEqual(o.edges[0], 'Validate the incoming request payload to Store, when every field checks out');
+});
+
+test('OUTLINE: never throws, whatever it is handed', () => {
+	for (const junk of [null, undefined, {}, { nodes: 'x' }, { nodes: [], edges: [{ from: 'a', to: 'b' }] }]) {
+		const o = T.outline(junk);
+		assert.strictEqual(typeof o.text, 'string');
+		assert.strictEqual(o.edges.length, 0);
+	}
+});
+
+test('STUB: one line, in the shape the spec gives — "diagram: <title>, <n> nodes, id <id>"', () => {
+	assert.strictEqual(T.stub({ id: 'd-17', spec: specOf('jev') }), 'diagram: Jev classifies; your code decides the action, 4 nodes, id d-17');
+	assert.strictEqual(T.stub({ id: 'd-2', spec: specOf('single') }), 'diagram: One box, 1 node, id d-2');
+	assert.ok(!/\n/.test(T.stub({ id: 'd-1', spec: { title: 'a\nb', nodes: [] } })), 'always exactly one line');
+	assert.strictEqual(T.stub(null), 'diagram: untitled, 0 nodes, id ?');
+	assert.ok(T.stub({ id: 'd-17', spec: specOf('twelve') }).length < JSON.stringify(specOf('twelve')).length / 10, 'a stub is a fraction of the spec it stands for');
+});
+
+test('MERMAID: a flowchart with shapes, groups, labels, dashes and the accent', () => {
+	const mm = T.toMermaid(specOf('arch'));
+	assert.strictEqual(mm.split('\n').slice(0, 4).join('\n'), '---\ntitle: "The agent talks to providers through one registry"\n---\nflowchart LR');
+	assert.match(mm, /^ {2}chat\(\["Chat webview"\]\)$/m, 'actor → stadium');
+	assert.match(mm, /^ {2}subgraph group_ext\["Extension host"\]$/m);
+	assert.match(mm, /^ {4}agent\["agent\.js<br\/>tool loop"\]$/m, 'label and second line');
+	assert.match(mm, /^ {4}store\[\("Sessions<br\/>append-only JSONL"\)\]$/m, 'store → cylinder');
+	assert.match(mm, /^ {2}chat -->\|"goal"\| agent$/m);
+	assert.match(mm, /^ {2}agent -\.->\|"each turn"\| store$/m, 'dashed');
+	assert.match(mm, /^ {2}class agent accent$/m);
+	assert.strictEqual((mm.match(/^\s*subgraph /gm) || []).length, (mm.match(/^\s*end$/gm) || []).length, 'every subgraph closes');
+	assert.match(T.toMermaid(specOf('decision')), /^flowchart TD$/m, 'down → TD');
+	assert.match(T.toMermaid(specOf('decision')), /q\{"Tool running\?"\}/, 'decision → diamond');
+	assert.ok(!T.toMermaid(specOf('jev'), { title: false }).startsWith('---'));
+});
+
+test('MERMAID: nested groups nest, and every node appears exactly once', () => {
+	const spec = specOf('twelve');
+	const mm = T.toMermaid(spec);
+	const lines = mm.split('\n');
+	const app = lines.findIndex((l) => /subgraph group_app/.test(l)), w = lines.findIndex((l) => /subgraph group_w/.test(l));
+	assert.ok(app >= 0 && w > app, 'Workers is declared inside Application');
+	assert.ok(lines[w].startsWith('    '), 'and indented under it');
+	for (const node of spec.nodes) {
+		const id = T.mermaidIds(spec.nodes.map((x) => x.id)).get(node.id);
+		assert.strictEqual(lines.filter((l) => new RegExp('^\\s*' + id + '[\\[({]').test(l)).length, 1, node.id + ' is declared once');
+	}
+});
+
+test('MERMAID: the breakers the spec lists cannot occur — ids are rewritten, labels quoted and escaped', () => {
+	// "capitalize a lowercase `end`", "an `o` or `x` that starts a linked node", "quote labels containing special characters"
+	const spec = R.prepare({ title: 'A "quoted" <title>', nodes: [{ id: 'end', label: 'end' }, { id: 'o1', label: 'say "hi" & <go>' }, { id: 'x-ray', label: 'a|b [c] {d} (e)' }, { id: '9lives', label: 'nine' }, { id: 'class', label: 'class' }], edges: [{ from: 'end', to: 'o1', label: 'a "b" | c' }, { from: 'o1', to: 'x-ray' }, { from: 'x-ray', to: '9lives' }, { from: '9lives', to: 'class' }] }).spec;
+	const mm = T.toMermaid(spec);
+	assert.match(mm, /^ {2}n_end\["end"\]$/m, '`end` would close a subgraph; as an id it is renamed');
+	assert.match(mm, /^ {2}n_class\["class"\]$/m);
+	assert.match(mm, /^ {2}n_9lives\["nine"\]$/m, 'an id cannot start with a digit');
+	assert.match(mm, /^ {2}x_ray\[/m, 'no hyphens in ids');
+	assert.match(mm, /o1\["say #quot;hi#quot; #amp; #lt;go#gt;"\]/, 'quotes and angle brackets are entities');
+	assert.match(mm, /^ {2}n_end -->\|"a #quot;b#quot; \| c"\| o1$/m, 'a pipe inside a QUOTED label is just a pipe');
+	assert.match(mm, /^ {2}o1 --> x_ray$/m, 'an arrow always has spaces round it, so "o"/"x" never read as an arrowhead');
+	assert.match(mm, /^title: "A \\"quoted\\" <title>"$/m);
+	for (const line of mm.split('\n')) { assert.ok(!/["\]]\s*-->\S|\S-->/.test(line), 'spaced arrows: ' + line); }
+	// ids stay unique even when two different slugs collapse to the same Mermaid id
+	const ids = T.mermaidIds(['a-b', 'a_b', 'a.b']);
+	assert.strictEqual(new Set(ids.values()).size, 3);
+});
+
+test('SOURCE: what "Copy source" gives is the model\'s spec — none of the renderer\'s own fields', () => {
+	const spec = R.prepare({ title: 'T', nodes: [{ id: 'a', label: 'Validate the incoming request payload' }], edges: [] }).spec;
+	assert.ok(spec.nodes[0].tip);
+	const src = JSON.parse(T.toSource(spec));
+	assert.strictEqual(src.nodes[0].tip, undefined);
+	assert.strictEqual(R.prepare(src).status, 'ok', 'and it is a valid spec to send straight back');
+	assert.ok(spec.nodes[0].tip, 'toSource() does not mutate');
+});
+
+test('ASCII: drawn from the same layout as the picture — boxes, arrows, and labels beside their lines', () => {
+	const out = A.render(specOf('jev'));
+	const lines = out.split('\n');
+	assert.strictEqual(lines[0], 'Jev classifies; your code decides the action');
+	for (const label of ['Customer message', 'plus account details', 'Jev', 'returns probabilities', 'Route to billing', 'Human review', '0.90 or more', 'under 0.90']) { assert.ok(out.includes(label), 'missing "' + label + '"'); }
+	const row = (text) => lines.findIndex((l) => l.includes(text));
+	assert.ok(row('Route to billing') < row('Human review'), 'the two outcomes are stacked as in the picture');
+	assert.ok(lines[row('Customer message')].indexOf('Customer message') < lines[row('Route to billing')].indexOf('Route to billing'), 'and the flow still reads left to right');
+	assert.strictEqual((out.match(/>/g) || []).length, 3, 'three connectors, three arrowheads');
+	assert.match(lines[row('0.90 or more') + 1], /-+>\|/, 'the label sits on the row ABOVE its line, which runs into the box');
+	assert.match(out, /#{5,}/, 'the accent box is marked');
+	assert.ok(lines.every((l) => l === l.replace(/\s+$/, '')), 'no trailing spaces');
+	assert.ok(out.endsWith('\n') && !out.endsWith('\n\n'));
+});
+
+test('ASCII: plain ASCII only — it must survive any terminal and any font', () => {
+	for (const g of gallery) {
+		const out = A.render(R.prepare(g.spec).spec).split('\n').slice(1).join('\n');   // the title is the user's text
+		// eslint-disable-next-line no-control-regex
+		assert.ok(/^[\x20-\x7e\n]*$/.test(out), g.name + ' uses a character outside printable ASCII');
+	}
+});
+
+test('ASCII: a shortened label ends in three dots — a diagram of plain words stays plain ASCII when it is cut to fit', () => {
+	const p = R.prepare({ title: 'Long labels are shortened', nodes: [{ id: 'a', label: 'Customer message with the whole account history', sub: 'and a second line that also runs on far too long', group: 'g' }, { id: 'b', label: 'B' }], edges: [{ from: 'a', to: 'b', label: 'a label that is much too long' }], groups: [{ id: 'g', label: 'A group whose name is longer than a group name may be' }] });
+	assert.ok(/…$/.test(p.spec.nodes[0].label), 'the stored label carries the ellipsis the picture shows');
+	const out = A.render(p.spec);
+	// eslint-disable-next-line no-control-regex
+	assert.ok(/^[\x20-\x7e\n]*$/.test(out), 'nothing outside printable ASCII: ' + JSON.stringify(out.match(/[^\x20-\x7e\n]/g)));
+	const lines = out.split('\n');
+	const sub = lines.find((l) => l.includes('and a second line that also...'));
+	assert.match(sub, /\| and a second line that also\.\.\. \|/, 'the box is sized for the dots it is given: one space each side of its longest line\n' + out);
+	assert.match(out, /\| +Customer message with the\.\.\. +\|/);
+	assert.match(out, /a label that is\.\.\./);
+	assert.match(out, /\. {2}A group whose name is\.\.\. /, 'a group\'s name too\n' + out);
+	assert.ok(/…$/.test(p.spec.nodes[0].label), 'and the spec itself is untouched');
+});
+
+test('ASCII: wide characters take two cells and marks take none — a box in Japanese still closes on one column', () => {
+	assert.deepStrictEqual(['abc', '日本語', 'Café', '🚀', 'ｆｕｌｌ', '한국어', '', '⚠️', '⚠'].map(A.width), [3, 6, 4, 2, 8, 6, 0, 2, 1]);
+	// measured independently of the renderer: anything in the CJK and fullwidth blocks counts double
+	const cols = (line) => Array.from(line).reduce((a, ch) => a + (/[　-鿿가-힣＀-｠]/.test(ch) ? 2 : 1), 0);
+	const out = A.render(R.prepare({ title: 'T', nodes: [{ id: 'a', label: '顧客メッセージ', sub: 'アカウント情報つき' }, { id: 'b', label: '請求へ回す' }], edges: [{ from: 'a', to: 'b', label: '分類' }] }).spec);
+	const rows = out.split('\n').slice(2).filter(Boolean);
+	const first = rows.filter((l) => /^[+|]/.test(l));
+	assert.strictEqual(first.length, 4, 'the first box: its lid, two lines of text, its base\n' + out);
+	// where the first box closes, on every one of its rows
+	const closes = first.map((l) => { const m = /^(\+-+\+|\|.*?\|)/.exec(l); return cols(m[1]); });
+	assert.strictEqual(new Set(closes).size, 1, 'the right-hand side is on columns ' + closes.join(', ') + '\n' + out);
+	// and the second box, further along the row, is square too: every row of it ends on the same column
+	const ends = rows.filter((l) => /[+|]$/.test(l) && cols(l) > closes[0]).map(cols);
+	assert.ok(ends.length >= 3 && new Set(ends).size === 1, 'the second box ends on columns ' + ends.join(', ') + '\n' + out);
+	assert.ok(out.includes('顧客メッセージ') && out.includes('分類'), 'the text itself is not altered');
+});
+
+test('ASCII: shapes are told apart, groups are framed, dashed lines are dashed', () => {
+	const d = A.render(specOf('decision'));
+	assert.match(d, /\.-+\.\n\s*\( +Steer arrives +\)/, 'an actor is a rounded box');
+	assert.match(d, /< +Tool running\? +>/, 'a decision is marked with angle brackets');
+	assert.match(d, /\|yes/); assert.match(d, /\|no/);
+	assert.ok((d.match(/v/g) || []).length >= 5, 'arrowheads point down the flow');
+	const a = A.render(specOf('arch'));
+	assert.match(a, /\. {2}Extension host /, 'a group frame carries its label');
+	assert.match(a, /\.=+\..*\n.*Sessions/, 'a store has a doubled lid');
+	assert.match(a, /- - - /, 'the dashed edge is drawn dashed');
+});
+
+test('ASCII: a group\'s name is never cut by a line — it moves along its frame as it does in the picture, or is written over the line', () => {
+	// the architecture diagram turned downward: a connector comes in exactly where "Providers" would sit
+	const out = A.render(specOf('arch'), { maxCols: 60 });
+	const row = out.split('\n').find((l) => l.includes('Providers'));
+	assert.ok(row, out);
+	assert.match(row, /^\.[ .]*\+ Providers [ .+]*\.$/, 'the name is whole, on the frame\'s top row, just past the line that comes in: ' + JSON.stringify(row));
+	assert.match(out, /\. {2}Extension host /, 'a name nothing crosses stays in its corner');
+	// no stretch of the frame is clear: the name is written over the line, and the line carries on below it
+	const s = R.prepare({ title: 'T', direction: 'down', groups: [{ id: 'g', label: 'A container with a long name' }], nodes: [{ id: 'top', label: 'Chat webview' }, { id: 'a', label: 'A', group: 'g' }], edges: [{ from: 'top', to: 'a' }] }).spec;
+	const lines = A.render(s).split('\n');
+	const at = lines.findIndex((l) => l.includes('A container with a long name'));
+	assert.ok(at > 0, lines.join('\n'));
+	assert.match(lines[at], /^\. {2}A container with a long name [ .]*\.$/);
+	const col = lines[at - 1].indexOf('|');
+	assert.ok(col > 0 && lines[at + 1][col] === '|', 'the connector is there above the name and below it:\n' + lines.slice(at - 1, at + 2).join('\n'));
+	assert.ok(col > lines[at].indexOf('A container') && col < lines[at].indexOf('name') + 4, 'and it is the name that covers it');
+});
+
+test('ASCII: every gallery diagram renders, each node label is on the page, and it is deterministic', () => {
+	for (const g of gallery) {
+		const spec = R.prepare(g.spec).spec;
+		const out = A.render(spec);
+		for (const node of spec.nodes) { assert.ok(out.includes(node.label), g.name + ': "' + node.label + '" is missing'); }
+		assert.strictEqual(A.render(spec), out, g.name);
+		assert.ok(out.split('\n').every((l) => l.length < 260), g.name + ' is absurdly wide');
+	}
+});
+
+test('ASCII: a flow too wide for the page turns downward, like the picture does', () => {
+	const chain = R.prepare({ title: 'T', direction: 'right', nodes: Array.from({ length: 7 }, (_, i) => ({ id: 'n' + i, label: 'Pipeline stage ' + (i + 1) })), edges: Array.from({ length: 6 }, (_, i) => ({ from: 'n' + i, to: 'n' + (i + 1) })) }).spec;
+	const wide = A.render(chain), fit = A.render(chain, { maxCols: 60 });
+	const widest = (s) => Math.max.apply(null, s.split('\n').map((l) => l.length));
+	assert.ok(widest(wide) > 120);
+	assert.ok(widest(fit) <= 60, 'fits 60 columns: ' + widest(fit));
+	assert.ok(fit.split('\n').length > wide.split('\n').length, 'by growing downward');
+});
+
+console.log('diagramText: ' + n + ' tests passed');
diff --git a/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/arch.dark.svg b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/arch.dark.svg
new file mode 100644
index 0000000..d766209
--- /dev/null
+++ b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/arch.dark.svg
@@ -0,0 +1,16 @@
+<svg class="lcd-svg" viewBox="0 0 808 272" width="808" height="272" role="img" aria-label="The agent talks to providers through one registry" focusable="false" xmlns="http://www.w3.org/2000/svg"><style><![CDATA[svg.lcd-svg .lcd-bg { fill: #1e1f22; }
+svg.lcd-svg text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; }
+svg.lcd-svg .lcd-title { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 15px; font-weight: 600; fill: #d4d7dc; }
+svg.lcd-svg .lcd-name { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 13px; font-weight: 600; fill: #d4d7dc; }
+svg.lcd-svg .lcd-sub { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #9198a1; }
+svg.lcd-svg .lcd-edge-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #9198a1; }
+svg.lcd-svg .lcd-group-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 600; fill: #9198a1; }
+svg.lcd-svg .lcd-shape { fill: #27292d; stroke: #5f666f; stroke-width: 1.25px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-accent .lcd-shape { fill: #1f3350; stroke: #4c9aff; stroke-width: 2px; }
+svg.lcd-svg .lcd-node .lcd-lid { fill: none; }
+svg.lcd-svg .lcd-group-box { fill: #232528; stroke: #3a3e44; stroke-width: 1px; }
+svg.lcd-svg .lcd-edge { fill: none; stroke: #8b929b; stroke-width: 1.25px; stroke-linejoin: round; stroke-linecap: round; }
+svg.lcd-svg .lcd-edge.lcd-dashed { stroke-dasharray: 5 4; }
+svg.lcd-svg .lcd-arrow { fill: #8b929b; stroke: #8b929b; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-link-icon { fill: none; stroke: #9198a1; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-halo { paint-order: stroke; stroke: #1e1f22; stroke-width: 4px; stroke-linejoin: round; }]]></style><rect class="lcd-bg" x="0" y="0" width="808" height="272"/><text class="lcd-title" x="8" y="23.33">The agent talks to providers through one registry</text><g transform="translate(0,34)"><g class="lcd-groups"><g class="lcd-group"><rect class="lcd-group-box" x="185.5" y="35.5" width="370.8" height="194" rx="10" ry="10"/><text class="lcd-group-label" x="197.5" y="54.58">Extension host</text></g><g class="lcd-group"><rect class="lcd-group-box" x="600.3" y="8" width="199" height="170" rx="10" ry="10"/><text class="lcd-group-label" x="612.3" y="27.08">Providers</text></g></g><g class="lcd-edges"><g class="lcd-edge-g"><path class="lcd-edge" d="M139,138 L195.5,138"/><path class="lcd-arrow" d="M201.5,138 L194.5,141.6 L194.5,134.4 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M292.5,132 L303.5,132 Q308.5,132 308.5,127 L308.5,100.5 Q308.5,95.5 313.5,95.5 L376.3,95.5"/><path class="lcd-arrow" d="M382.3,95.5 L375.3,99.1 L375.3,91.9 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M540.3,89.5 L573.3,89.5 Q578.3,89.5 578.3,84.5 L578.3,64 Q578.3,59 583.3,59 L650.8,59"/><path class="lcd-arrow" d="M656.8,59 L649.8,62.6 L649.8,55.4 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M540.3,101.5 L573.3,101.5 Q578.3,101.5 578.3,106.5 L578.3,127 Q578.3,132 583.3,132 L610.3,132"/><path class="lcd-arrow" d="M616.3,132 L609.3,135.6 L609.3,128.4 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge lcd-dashed" d="M292.5,144 L303.5,144 Q308.5,144 308.5,149 L308.5,175.5 Q308.5,180.5 313.5,180.5 L386.8,180.5"/><path class="lcd-arrow" d="M392.8,180.5 L385.8,184.1 L385.8,176.9 Z"/></g></g><g class="lcd-nodes"><g class="lcd-node lcd-actor" data-lc-node="chat"><rect class="lcd-shape" x="9" y="117" width="130" height="42" rx="21" ry="21"/><text class="lcd-name" x="74" y="142.62" text-anchor="middle">Chat webview</text></g><g class="lcd-node lcd-box lcd-accent lcd-linked" data-lc-node="agent" data-lc-link="agent" tabindex="0" role="link" aria-label="Open agent.js at runAgent"><rect class="lcd-shape" x="201.5" y="108" width="91" height="60" rx="8" ry="8"/><text class="lcd-name" x="247" y="133.62" text-anchor="middle">agent.js</text><text class="lcd-sub" x="247" y="152.08" text-anchor="middle">tool loop</text><path class="lcd-link-icon" aria-hidden="true" d="M277.1,123.5 h5.5 l3.5,3.5 v7.5 h-9 Z M282.6,123.5 v3.5 h3.5"/><title>agent.js · runAgent</title></g><g class="lcd-node lcd-box lcd-linked" data-lc-node="reg" data-lc-link="reg" tabindex="0" role="link" aria-label="Open providers/index.js"><rect class="lcd-shape" x="382.3" y="65.5" width="158" height="60" rx="8" ry="8"/><text class="lcd-name" x="461.3" y="91.12" text-anchor="middle">providers/index.js</text><text class="lcd-sub" x="461.3" y="109.58" text-anchor="middle">registry</text><path class="lcd-link-icon" aria-hidden="true" d="M525.25,81 h5.5 l3.5,3.5 v7.5 h-9 Z M530.75,81 v3.5 h3.5"/><title>providers/index.js</title></g><g class="lcd-node lcd-store" data-lc-node="store"><path class="lcd-shape" d="M392.8,153.5 A68.5,6 0 0 1 529.8,153.5 V207.5 A68.5,6 0 0 1 392.8,207.5 Z"/><path class="lcd-shape lcd-lid" d="M392.8,153.5 A68.5,6 0 0 0 529.8,153.5"/><text class="lcd-name" x="461.3" y="179.12" text-anchor="middle">Sessions</text><text class="lcd-sub" x="461.3" y="197.58" text-anchor="middle">append-only JSONL</text></g><g class="lcd-node lcd-box" data-lc-node="ant"><rect class="lcd-shape" x="656.8" y="38" width="86" height="42" rx="8" ry="8"/><text class="lcd-name" x="699.8" y="63.62" text-anchor="middle">Anthropic</text></g><g class="lcd-node lcd-box" data-lc-node="oai"><rect class="lcd-shape" x="616.3" y="102" width="167" height="60" rx="8" ry="8"/><text class="lcd-name" x="699.8" y="127.62" text-anchor="middle">OpenAI-compatible</text><text class="lcd-sub" x="699.8" y="146.08" text-anchor="middle">one adapter, ten providers</text></g></g><g class="lcd-labels"><text class="lcd-edge-label" x="158" y="129.08">goal</text><text class="lcd-edge-label" x="331" y="171.58">each turn</text></g></g></svg>
diff --git a/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/arch.light.svg b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/arch.light.svg
new file mode 100644
index 0000000..2248874
--- /dev/null
+++ b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/arch.light.svg
@@ -0,0 +1,16 @@
+<svg class="lcd-svg" viewBox="0 0 808 272" width="808" height="272" role="img" aria-label="The agent talks to providers through one registry" focusable="false" xmlns="http://www.w3.org/2000/svg"><style><![CDATA[svg.lcd-svg .lcd-bg { fill: #ffffff; }
+svg.lcd-svg text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; }
+svg.lcd-svg .lcd-title { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 15px; font-weight: 600; fill: #1f2328; }
+svg.lcd-svg .lcd-name { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 13px; font-weight: 600; fill: #1f2328; }
+svg.lcd-svg .lcd-sub { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #59636e; }
+svg.lcd-svg .lcd-edge-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #59636e; }
+svg.lcd-svg .lcd-group-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 600; fill: #59636e; }
+svg.lcd-svg .lcd-shape { fill: #f4f5f6; stroke: #aeb4bb; stroke-width: 1.25px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-accent .lcd-shape { fill: #ddebfb; stroke: #0969da; stroke-width: 2px; }
+svg.lcd-svg .lcd-node .lcd-lid { fill: none; }
+svg.lcd-svg .lcd-group-box { fill: #f8f9fa; stroke: #d5d9de; stroke-width: 1px; }
+svg.lcd-svg .lcd-edge { fill: none; stroke: #7d8590; stroke-width: 1.25px; stroke-linejoin: round; stroke-linecap: round; }
+svg.lcd-svg .lcd-edge.lcd-dashed { stroke-dasharray: 5 4; }
+svg.lcd-svg .lcd-arrow { fill: #7d8590; stroke: #7d8590; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-link-icon { fill: none; stroke: #59636e; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-halo { paint-order: stroke; stroke: #ffffff; stroke-width: 4px; stroke-linejoin: round; }]]></style><rect class="lcd-bg" x="0" y="0" width="808" height="272"/><text class="lcd-title" x="8" y="23.33">The agent talks to providers through one registry</text><g transform="translate(0,34)"><g class="lcd-groups"><g class="lcd-group"><rect class="lcd-group-box" x="185.5" y="35.5" width="370.8" height="194" rx="10" ry="10"/><text class="lcd-group-label" x="197.5" y="54.58">Extension host</text></g><g class="lcd-group"><rect class="lcd-group-box" x="600.3" y="8" width="199" height="170" rx="10" ry="10"/><text class="lcd-group-label" x="612.3" y="27.08">Providers</text></g></g><g class="lcd-edges"><g class="lcd-edge-g"><path class="lcd-edge" d="M139,138 L195.5,138"/><path class="lcd-arrow" d="M201.5,138 L194.5,141.6 L194.5,134.4 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M292.5,132 L303.5,132 Q308.5,132 308.5,127 L308.5,100.5 Q308.5,95.5 313.5,95.5 L376.3,95.5"/><path class="lcd-arrow" d="M382.3,95.5 L375.3,99.1 L375.3,91.9 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M540.3,89.5 L573.3,89.5 Q578.3,89.5 578.3,84.5 L578.3,64 Q578.3,59 583.3,59 L650.8,59"/><path class="lcd-arrow" d="M656.8,59 L649.8,62.6 L649.8,55.4 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M540.3,101.5 L573.3,101.5 Q578.3,101.5 578.3,106.5 L578.3,127 Q578.3,132 583.3,132 L610.3,132"/><path class="lcd-arrow" d="M616.3,132 L609.3,135.6 L609.3,128.4 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge lcd-dashed" d="M292.5,144 L303.5,144 Q308.5,144 308.5,149 L308.5,175.5 Q308.5,180.5 313.5,180.5 L386.8,180.5"/><path class="lcd-arrow" d="M392.8,180.5 L385.8,184.1 L385.8,176.9 Z"/></g></g><g class="lcd-nodes"><g class="lcd-node lcd-actor" data-lc-node="chat"><rect class="lcd-shape" x="9" y="117" width="130" height="42" rx="21" ry="21"/><text class="lcd-name" x="74" y="142.62" text-anchor="middle">Chat webview</text></g><g class="lcd-node lcd-box lcd-accent lcd-linked" data-lc-node="agent" data-lc-link="agent" tabindex="0" role="link" aria-label="Open agent.js at runAgent"><rect class="lcd-shape" x="201.5" y="108" width="91" height="60" rx="8" ry="8"/><text class="lcd-name" x="247" y="133.62" text-anchor="middle">agent.js</text><text class="lcd-sub" x="247" y="152.08" text-anchor="middle">tool loop</text><path class="lcd-link-icon" aria-hidden="true" d="M277.1,123.5 h5.5 l3.5,3.5 v7.5 h-9 Z M282.6,123.5 v3.5 h3.5"/><title>agent.js · runAgent</title></g><g class="lcd-node lcd-box lcd-linked" data-lc-node="reg" data-lc-link="reg" tabindex="0" role="link" aria-label="Open providers/index.js"><rect class="lcd-shape" x="382.3" y="65.5" width="158" height="60" rx="8" ry="8"/><text class="lcd-name" x="461.3" y="91.12" text-anchor="middle">providers/index.js</text><text class="lcd-sub" x="461.3" y="109.58" text-anchor="middle">registry</text><path class="lcd-link-icon" aria-hidden="true" d="M525.25,81 h5.5 l3.5,3.5 v7.5 h-9 Z M530.75,81 v3.5 h3.5"/><title>providers/index.js</title></g><g class="lcd-node lcd-store" data-lc-node="store"><path class="lcd-shape" d="M392.8,153.5 A68.5,6 0 0 1 529.8,153.5 V207.5 A68.5,6 0 0 1 392.8,207.5 Z"/><path class="lcd-shape lcd-lid" d="M392.8,153.5 A68.5,6 0 0 0 529.8,153.5"/><text class="lcd-name" x="461.3" y="179.12" text-anchor="middle">Sessions</text><text class="lcd-sub" x="461.3" y="197.58" text-anchor="middle">append-only JSONL</text></g><g class="lcd-node lcd-box" data-lc-node="ant"><rect class="lcd-shape" x="656.8" y="38" width="86" height="42" rx="8" ry="8"/><text class="lcd-name" x="699.8" y="63.62" text-anchor="middle">Anthropic</text></g><g class="lcd-node lcd-box" data-lc-node="oai"><rect class="lcd-shape" x="616.3" y="102" width="167" height="60" rx="8" ry="8"/><text class="lcd-name" x="699.8" y="127.62" text-anchor="middle">OpenAI-compatible</text><text class="lcd-sub" x="699.8" y="146.08" text-anchor="middle">one adapter, ten providers</text></g></g><g class="lcd-labels"><text class="lcd-edge-label" x="158" y="129.08">goal</text><text class="lcd-edge-label" x="331" y="171.58">each turn</text></g></g></svg>
diff --git a/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/decision.dark.svg b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/decision.dark.svg
new file mode 100644
index 0000000..699f62e
--- /dev/null
+++ b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/decision.dark.svg
@@ -0,0 +1,16 @@
+<svg class="lcd-svg" viewBox="0 0 271 416" width="271" height="416" role="img" aria-label="A steer is applied at the next safe point, never mid-tool" focusable="false" xmlns="http://www.w3.org/2000/svg"><style><![CDATA[svg.lcd-svg .lcd-bg { fill: #1e1f22; }
+svg.lcd-svg text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; }
+svg.lcd-svg .lcd-title { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 15px; font-weight: 600; fill: #d4d7dc; }
+svg.lcd-svg .lcd-name { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 13px; font-weight: 600; fill: #d4d7dc; }
+svg.lcd-svg .lcd-sub { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #9198a1; }
+svg.lcd-svg .lcd-edge-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #9198a1; }
+svg.lcd-svg .lcd-group-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 600; fill: #9198a1; }
+svg.lcd-svg .lcd-shape { fill: #27292d; stroke: #5f666f; stroke-width: 1.25px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-accent .lcd-shape { fill: #1f3350; stroke: #4c9aff; stroke-width: 2px; }
+svg.lcd-svg .lcd-node .lcd-lid { fill: none; }
+svg.lcd-svg .lcd-group-box { fill: #232528; stroke: #3a3e44; stroke-width: 1px; }
+svg.lcd-svg .lcd-edge { fill: none; stroke: #8b929b; stroke-width: 1.25px; stroke-linejoin: round; stroke-linecap: round; }
+svg.lcd-svg .lcd-edge.lcd-dashed { stroke-dasharray: 5 4; }
+svg.lcd-svg .lcd-arrow { fill: #8b929b; stroke: #8b929b; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-link-icon { fill: none; stroke: #9198a1; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-halo { paint-order: stroke; stroke: #1e1f22; stroke-width: 4px; stroke-linejoin: round; }]]></style><rect class="lcd-bg" x="0" y="0" width="271" height="416"/><text class="lcd-title" x="8" y="23.33">A steer is applied at the next safe</text><text class="lcd-title" x="8" y="43.33">point, never mid-tool</text><g transform="translate(0,54)"><g class="lcd-groups"/><g class="lcd-edges"><g class="lcd-edge-g"><path class="lcd-edge" d="M145.25,51 L145.25,89"/><path class="lcd-arrow" d="M145.25,95 L141.65,88 L148.85,88 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M139.25,150.06 L139.25,163 Q139.25,168 134.25,168 L82,168 Q77,168 77,173 L77,201"/><path class="lcd-arrow" d="M77,207 L73.4,200 L80.6,200 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M151.25,150.06 L151.25,163 Q151.25,168 156.25,168 L208.5,168 Q213.5,168 213.5,173 L213.5,210"/><path class="lcd-arrow" d="M213.5,216 L209.9,209 L217.1,209 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M77,267 L77,284 Q77,289 82,289 L134.25,289 Q139.25,289 139.25,294 L139.25,305"/><path class="lcd-arrow" d="M139.25,311 L135.65,304 L142.85,304 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M213.5,258 L213.5,284 Q213.5,289 208.5,289 L156.25,289 Q151.25,289 151.25,294 L151.25,305"/><path class="lcd-arrow" d="M151.25,311 L147.65,304 L154.85,304 Z"/></g></g><g class="lcd-nodes"><g class="lcd-node lcd-actor" data-lc-node="s"><rect class="lcd-shape" x="85.25" y="9" width="120" height="42" rx="21" ry="21"/><text class="lcd-name" x="145.25" y="34.62" text-anchor="middle">Steer arrives</text></g><g class="lcd-node lcd-decision lcd-accent" data-lc-node="q"><path class="lcd-shape" d="M145.25,95 L233.25,123.5 L145.25,152 L57.25,123.5 Z"/><text class="lcd-name" x="145.25" y="128.12" text-anchor="middle">Tool running?</text></g><g class="lcd-node lcd-box" data-lc-node="wait"><rect class="lcd-shape" x="9" y="207" width="136" height="60" rx="8" ry="8"/><text class="lcd-name" x="77" y="232.62" text-anchor="middle">Queue it</text><text class="lcd-sub" x="77" y="251.08" text-anchor="middle">until the tool returns</text></g><g class="lcd-node lcd-box" data-lc-node="now"><rect class="lcd-shape" x="167" y="216" width="93" height="42" rx="8" ry="8"/><text class="lcd-name" x="213.5" y="241.62" text-anchor="middle">Inject now</text></g><g class="lcd-node lcd-box" data-lc-node="next"><rect class="lcd-shape" x="81.75" y="311" width="127" height="42" rx="8" ry="8"/><text class="lcd-name" x="145.25" y="336.62" text-anchor="middle">Next model turn</text></g></g><g class="lcd-labels"><text class="lcd-edge-label" x="83" y="187.58">yes</text><text class="lcd-edge-label" x="219.5" y="192.08">no</text></g></g></svg>
diff --git a/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/decision.light.svg b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/decision.light.svg
new file mode 100644
index 0000000..c3eb0d5
--- /dev/null
+++ b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/decision.light.svg
@@ -0,0 +1,16 @@
+<svg class="lcd-svg" viewBox="0 0 271 416" width="271" height="416" role="img" aria-label="A steer is applied at the next safe point, never mid-tool" focusable="false" xmlns="http://www.w3.org/2000/svg"><style><![CDATA[svg.lcd-svg .lcd-bg { fill: #ffffff; }
+svg.lcd-svg text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; }
+svg.lcd-svg .lcd-title { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 15px; font-weight: 600; fill: #1f2328; }
+svg.lcd-svg .lcd-name { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 13px; font-weight: 600; fill: #1f2328; }
+svg.lcd-svg .lcd-sub { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #59636e; }
+svg.lcd-svg .lcd-edge-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #59636e; }
+svg.lcd-svg .lcd-group-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 600; fill: #59636e; }
+svg.lcd-svg .lcd-shape { fill: #f4f5f6; stroke: #aeb4bb; stroke-width: 1.25px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-accent .lcd-shape { fill: #ddebfb; stroke: #0969da; stroke-width: 2px; }
+svg.lcd-svg .lcd-node .lcd-lid { fill: none; }
+svg.lcd-svg .lcd-group-box { fill: #f8f9fa; stroke: #d5d9de; stroke-width: 1px; }
+svg.lcd-svg .lcd-edge { fill: none; stroke: #7d8590; stroke-width: 1.25px; stroke-linejoin: round; stroke-linecap: round; }
+svg.lcd-svg .lcd-edge.lcd-dashed { stroke-dasharray: 5 4; }
+svg.lcd-svg .lcd-arrow { fill: #7d8590; stroke: #7d8590; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-link-icon { fill: none; stroke: #59636e; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-halo { paint-order: stroke; stroke: #ffffff; stroke-width: 4px; stroke-linejoin: round; }]]></style><rect class="lcd-bg" x="0" y="0" width="271" height="416"/><text class="lcd-title" x="8" y="23.33">A steer is applied at the next safe</text><text class="lcd-title" x="8" y="43.33">point, never mid-tool</text><g transform="translate(0,54)"><g class="lcd-groups"/><g class="lcd-edges"><g class="lcd-edge-g"><path class="lcd-edge" d="M145.25,51 L145.25,89"/><path class="lcd-arrow" d="M145.25,95 L141.65,88 L148.85,88 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M139.25,150.06 L139.25,163 Q139.25,168 134.25,168 L82,168 Q77,168 77,173 L77,201"/><path class="lcd-arrow" d="M77,207 L73.4,200 L80.6,200 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M151.25,150.06 L151.25,163 Q151.25,168 156.25,168 L208.5,168 Q213.5,168 213.5,173 L213.5,210"/><path class="lcd-arrow" d="M213.5,216 L209.9,209 L217.1,209 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M77,267 L77,284 Q77,289 82,289 L134.25,289 Q139.25,289 139.25,294 L139.25,305"/><path class="lcd-arrow" d="M139.25,311 L135.65,304 L142.85,304 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M213.5,258 L213.5,284 Q213.5,289 208.5,289 L156.25,289 Q151.25,289 151.25,294 L151.25,305"/><path class="lcd-arrow" d="M151.25,311 L147.65,304 L154.85,304 Z"/></g></g><g class="lcd-nodes"><g class="lcd-node lcd-actor" data-lc-node="s"><rect class="lcd-shape" x="85.25" y="9" width="120" height="42" rx="21" ry="21"/><text class="lcd-name" x="145.25" y="34.62" text-anchor="middle">Steer arrives</text></g><g class="lcd-node lcd-decision lcd-accent" data-lc-node="q"><path class="lcd-shape" d="M145.25,95 L233.25,123.5 L145.25,152 L57.25,123.5 Z"/><text class="lcd-name" x="145.25" y="128.12" text-anchor="middle">Tool running?</text></g><g class="lcd-node lcd-box" data-lc-node="wait"><rect class="lcd-shape" x="9" y="207" width="136" height="60" rx="8" ry="8"/><text class="lcd-name" x="77" y="232.62" text-anchor="middle">Queue it</text><text class="lcd-sub" x="77" y="251.08" text-anchor="middle">until the tool returns</text></g><g class="lcd-node lcd-box" data-lc-node="now"><rect class="lcd-shape" x="167" y="216" width="93" height="42" rx="8" ry="8"/><text class="lcd-name" x="213.5" y="241.62" text-anchor="middle">Inject now</text></g><g class="lcd-node lcd-box" data-lc-node="next"><rect class="lcd-shape" x="81.75" y="311" width="127" height="42" rx="8" ry="8"/><text class="lcd-name" x="145.25" y="336.62" text-anchor="middle">Next model turn</text></g></g><g class="lcd-labels"><text class="lcd-edge-label" x="83" y="187.58">yes</text><text class="lcd-edge-label" x="219.5" y="192.08">no</text></g></g></svg>
diff --git a/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/jev.dark.svg b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/jev.dark.svg
new file mode 100644
index 0000000..7dc7385
--- /dev/null
+++ b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/jev.dark.svg
@@ -0,0 +1,16 @@
+<svg class="lcd-svg" viewBox="0 0 579 158" width="579" height="158" role="img" aria-label="Jev classifies; your code decides the action" focusable="false" xmlns="http://www.w3.org/2000/svg"><style><![CDATA[svg.lcd-svg .lcd-bg { fill: #1e1f22; }
+svg.lcd-svg text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; }
+svg.lcd-svg .lcd-title { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 15px; font-weight: 600; fill: #d4d7dc; }
+svg.lcd-svg .lcd-name { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 13px; font-weight: 600; fill: #d4d7dc; }
+svg.lcd-svg .lcd-sub { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #9198a1; }
+svg.lcd-svg .lcd-edge-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #9198a1; }
+svg.lcd-svg .lcd-group-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 600; fill: #9198a1; }
+svg.lcd-svg .lcd-shape { fill: #27292d; stroke: #5f666f; stroke-width: 1.25px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-accent .lcd-shape { fill: #1f3350; stroke: #4c9aff; stroke-width: 2px; }
+svg.lcd-svg .lcd-node .lcd-lid { fill: none; }
+svg.lcd-svg .lcd-group-box { fill: #232528; stroke: #3a3e44; stroke-width: 1px; }
+svg.lcd-svg .lcd-edge { fill: none; stroke: #8b929b; stroke-width: 1.25px; stroke-linejoin: round; stroke-linecap: round; }
+svg.lcd-svg .lcd-edge.lcd-dashed { stroke-dasharray: 5 4; }
+svg.lcd-svg .lcd-arrow { fill: #8b929b; stroke: #8b929b; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-link-icon { fill: none; stroke: #9198a1; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-halo { paint-order: stroke; stroke: #1e1f22; stroke-width: 4px; stroke-linejoin: round; }]]></style><rect class="lcd-bg" x="0" y="0" width="579" height="158"/><text class="lcd-title" x="8" y="23.33">Jev classifies; your code decides the action</text><g transform="translate(0,34)"><g class="lcd-groups"/><g class="lcd-edges"><g class="lcd-edge-g"><path class="lcd-edge" d="M158,62 L196,62"/><path class="lcd-arrow" d="M202,62 L195,65.6 L195,58.4 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M337,56 L348,56 Q353,56 353,51 L353,35 Q353,30 358,30 L439.5,30"/><path class="lcd-arrow" d="M445.5,30 L438.5,33.6 L438.5,26.4 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M337,68 L348,68 Q353,68 353,73 L353,89 Q353,94 358,94 L442.5,94"/><path class="lcd-arrow" d="M448.5,94 L441.5,97.6 L441.5,90.4 Z"/></g></g><g class="lcd-nodes"><g class="lcd-node lcd-box" data-lc-node="in"><rect class="lcd-shape" x="9" y="32" width="149" height="60" rx="8" ry="8"/><text class="lcd-name" x="83.5" y="57.62" text-anchor="middle">Customer message</text><text class="lcd-sub" x="83.5" y="76.08" text-anchor="middle">plus account details</text></g><g class="lcd-node lcd-box lcd-accent" data-lc-node="jev"><rect class="lcd-shape" x="202" y="32" width="135" height="60" rx="8" ry="8"/><text class="lcd-name" x="269.5" y="57.62" text-anchor="middle">Jev</text><text class="lcd-sub" x="269.5" y="76.08" text-anchor="middle">returns probabilities</text></g><g class="lcd-node lcd-box" data-lc-node="bill"><rect class="lcd-shape" x="445.5" y="9" width="124" height="42" rx="8" ry="8"/><text class="lcd-name" x="507.5" y="34.62" text-anchor="middle">Route to billing</text></g><g class="lcd-node lcd-box" data-lc-node="rev"><rect class="lcd-shape" x="448.5" y="73" width="118" height="42" rx="8" ry="8"/><text class="lcd-name" x="507.5" y="98.62" text-anchor="middle">Human review</text></g></g><g class="lcd-labels"><text class="lcd-edge-label" x="365" y="21.08">0.90 or more</text><text class="lcd-edge-label" x="379.1" y="85.08">under 0.90</text></g></g></svg>
diff --git a/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/jev.light.svg b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/jev.light.svg
new file mode 100644
index 0000000..f14f203
--- /dev/null
+++ b/extensions/levelcode-ai/test/fixtures/diagrams/snapshots/jev.light.svg
@@ -0,0 +1,16 @@
+<svg class="lcd-svg" viewBox="0 0 579 158" width="579" height="158" role="img" aria-label="Jev classifies; your code decides the action" focusable="false" xmlns="http://www.w3.org/2000/svg"><style><![CDATA[svg.lcd-svg .lcd-bg { fill: #ffffff; }
+svg.lcd-svg text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; }
+svg.lcd-svg .lcd-title { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 15px; font-weight: 600; fill: #1f2328; }
+svg.lcd-svg .lcd-name { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 13px; font-weight: 600; fill: #1f2328; }
+svg.lcd-svg .lcd-sub { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #59636e; }
+svg.lcd-svg .lcd-edge-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 400; fill: #59636e; }
+svg.lcd-svg .lcd-group-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; font-size: 11.5px; font-weight: 600; fill: #59636e; }
+svg.lcd-svg .lcd-shape { fill: #f4f5f6; stroke: #aeb4bb; stroke-width: 1.25px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-accent .lcd-shape { fill: #ddebfb; stroke: #0969da; stroke-width: 2px; }
+svg.lcd-svg .lcd-node .lcd-lid { fill: none; }
+svg.lcd-svg .lcd-group-box { fill: #f8f9fa; stroke: #d5d9de; stroke-width: 1px; }
+svg.lcd-svg .lcd-edge { fill: none; stroke: #7d8590; stroke-width: 1.25px; stroke-linejoin: round; stroke-linecap: round; }
+svg.lcd-svg .lcd-edge.lcd-dashed { stroke-dasharray: 5 4; }
+svg.lcd-svg .lcd-arrow { fill: #7d8590; stroke: #7d8590; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-link-icon { fill: none; stroke: #59636e; stroke-width: 1px; stroke-linejoin: round; }
+svg.lcd-svg .lcd-halo { paint-order: stroke; stroke: #ffffff; stroke-width: 4px; stroke-linejoin: round; }]]></style><rect class="lcd-bg" x="0" y="0" width="579" height="158"/><text class="lcd-title" x="8" y="23.33">Jev classifies; your code decides the action</text><g transform="translate(0,34)"><g class="lcd-groups"/><g class="lcd-edges"><g class="lcd-edge-g"><path class="lcd-edge" d="M158,62 L196,62"/><path class="lcd-arrow" d="M202,62 L195,65.6 L195,58.4 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M337,56 L348,56 Q353,56 353,51 L353,35 Q353,30 358,30 L439.5,30"/><path class="lcd-arrow" d="M445.5,30 L438.5,33.6 L438.5,26.4 Z"/></g><g class="lcd-edge-g"><path class="lcd-edge" d="M337,68 L348,68 Q353,68 353,73 L353,89 Q353,94 358,94 L442.5,94"/><path class="lcd-arrow" d="M448.5,94 L441.5,97.6 L441.5,90.4 Z"/></g></g><g class="lcd-nodes"><g class="lcd-node lcd-box" data-lc-node="in"><rect class="lcd-shape" x="9" y="32" width="149" height="60" rx="8" ry="8"/><text class="lcd-name" x="83.5" y="57.62" text-anchor="middle">Customer message</text><text class="lcd-sub" x="83.5" y="76.08" text-anchor="middle">plus account details</text></g><g class="lcd-node lcd-box lcd-accent" data-lc-node="jev"><rect class="lcd-shape" x="202" y="32" width="135" height="60" rx="8" ry="8"/><text class="lcd-name" x="269.5" y="57.62" text-anchor="middle">Jev</text><text class="lcd-sub" x="269.5" y="76.08" text-anchor="middle">returns probabilities</text></g><g class="lcd-node lcd-box" data-lc-node="bill"><rect class="lcd-shape" x="445.5" y="9" width="124" height="42" rx="8" ry="8"/><text class="lcd-name" x="507.5" y="34.62" text-anchor="middle">Route to billing</text></g><g class="lcd-node lcd-box" data-lc-node="rev"><rect class="lcd-shape" x="448.5" y="73" width="118" height="42" rx="8" ry="8"/><text class="lcd-name" x="507.5" y="98.62" text-anchor="middle">Human review</text></g></g><g class="lcd-labels"><text class="lcd-edge-label" x="365" y="21.08">0.90 or more</text><text class="lcd-edge-label" x="379.1" y="85.08">under 0.90</text></g></g></svg>

From ce025344046f33aac937731e46ce63cbe300bd27 Mon Sep 17 00:00:00 2001
From: Sergii Demianchuk <sergeydemjanchyk@gmail.com>
Date: Mon, 5 Oct 2026 00:28:23 -0400
Subject: [PATCH 6/9] =?UTF-8?q?feat(diagrams):=20render=5Fdiagram=20?=
 =?UTF-8?q?=E2=80=94=20the=20agent=20draws=20in=20the=20chat?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ask the agent how something is put together and it answered with boxes and
arrows made of characters, which break with the font, the theme and the width
of the panel. Now it has a tool. It describes the structure; the editor
validates it, lays it out and paints it in the chat, in the editor's theme,
with nodes that open the code they stand for.

Graph JSON only: phase 1 of the spec. Mermaid, Vega-Lite and raw SVG are not
built, and the rules tell the model to use a table for numbers and a numbered
list for sequences rather than a format the chat would show as source.

The model's side (diagram/tool.js)
  render_diagram   its input schema is the validator's own schema object
  the rules        when a diagram earns its place; never draw with characters;
                   asked for a diagram, draw it here rather than writing a file
                   of diagram source; the title states the takeaway; one
                   accent; split above twelve nodes; link nodes to workspace
                   files. One worked example, itself a valid spec.
  the answer       {"ok":true,"id":"d-1"}, or every error at once
  About 520 tokens of tool and 450 of rules on every request from a client
  that can render — constant for a session, so they sit in the cached prefix.

One conversation's diagrams (diagram/service.js)
  A call that fails validation is sent back ONCE, with every error. A second
  failure is drawn degraded, with a banner naming each loss and a Retry button
  that the user presses, not the editor. Three bounces in one run and every
  later call is final. A diagram still owed its repair when the run ends — the
  model gave up, ran out of steps, was stopped — is settled from its last
  attempt before agentDone, so no placeholder is left waiting. Arguments cut
  off at the token limit are asked for again, never repaired.

In the chat (media/chat.html)
  A placeholder from the moment the call starts, titled as soon as the title
  has streamed; then the picture. The shared modules are inlined into the page
  by diagram/bundle.js under the page's existing nonce: the content security
  policy is unchanged, and the page still loads nothing. Text is measured in
  the real font. A column too narrow for a left-to-right flow turns it
  downward, and it turns back when the column widens. A full-size view with
  zoom and pan. The "auto-fixed" badge and its details; the degraded banner;
  the errors and the source when nothing can be drawn. Copy source, SVG, PNG,
  open as Mermaid, insert into a Markdown file. The title is the accessible
  name, and a text outline is there for screen readers. If painting fails, or
  the modules never loaded, the same diagram is shown as text — drawn by the
  page in the first case and by the host in the second.

What the page may ask of the editor
  openLink, export, retry and ascii. Each names a diagram by id and is looked
  up in the host's own records. A click sends the NODE id; the path comes from
  the record and is resolved again at that moment (diagram/links.js): inside a
  workspace folder once ".." and symlinks are followed, and a file. SVG and PNG
  come back from the page, so they are checked before they are written
  (diagram/exportCheck.js). The spec lists two actions; its own Retry button
  and text fallback need the other two.

Sessions and context
  The final record — spec, status, fixes, what was lost — is stored with the
  turn and replayed when a chat is reopened; nothing is repaired again. A
  session file is input too: a stored spec passes the validator on its way
  back in, in the host and in the page. At compaction a diagram becomes one
  line ("diagram: <title>, 4 nodes, id d-17"), and get_diagram is offered from
  then on. A session export writes each diagram as a fenced Mermaid block.

Who gets it
  A run carries client.render: rich or ascii. Rich is the chat webview, unless
  levelcode.ai.diagrams.enabled is off or the model's catalog row says
  diagrams: false — the switch for a model that fails the eval. An ascii client
  is offered neither the tool nor the rules. Chat mode has no tools and is
  unchanged.

Counters (diagram/stats.js, "AI: Diagram Statistics")
  First-pass valid rate, fixes by rung, error classes per model, render time,
  tokens per diagram, and answers that drew with characters anyway. Kept in
  the editor's own storage and sent nowhere; enums and numbers only, never a
  label, a title or a path.

Providers: onToolStart now carries the call's id, a new onToolInput streams its
arguments, and a turn returns the raw text of arguments that did not parse.
All additive.

Four existing suites change. agentNoWorkspace and sessionsUi pinned the shape
of the tool list in source, and now pin the new shape. authRetryCallers and
sessionExpiredHost slice compactAgentMemory and resumeSession out of
extension.js, and needed the names those now use.

Tests: diagramAgent (22 — the real runAgent with a scripted provider),
diagramSession (12), diagramLinks (9), diagramHost (27 — extension.js's own
functions against a stand-in for vscode), diagramStats (8), diagramUi (11).
---
 extensions/levelcode-ai/agent.js              |  91 ++-
 extensions/levelcode-ai/diagram/bundle.js     |  59 ++
 .../levelcode-ai/diagram/exportCheck.js       |  81 +++
 extensions/levelcode-ai/diagram/links.js      | 103 +++
 extensions/levelcode-ai/diagram/service.js    | 268 +++++++
 extensions/levelcode-ai/diagram/stats.js      | 123 ++++
 extensions/levelcode-ai/diagram/tool.js       | 124 ++++
 extensions/levelcode-ai/extension.js          | 252 ++++++-
 extensions/levelcode-ai/media/chat.html       | 464 ++++++++++++-
 extensions/levelcode-ai/package.json          |  10 +
 .../levelcode-ai/providers/anthropic.js       |  25 +-
 extensions/levelcode-ai/providers/catalog.js  |  17 +-
 extensions/levelcode-ai/providers/index.js    |   8 +-
 .../levelcode-ai/providers/openaiCompat.js    |  11 +-
 .../levelcode-ai/providers/translate.js       |  22 +-
 extensions/levelcode-ai/sessionEvents.js      |  78 ++-
 extensions/levelcode-ai/sessions.js           |  25 +-
 .../test/agentNoWorkspace.test.js             |   8 +-
 .../test/authRetryCallers.test.js             |   4 +
 .../levelcode-ai/test/diagramAgent.test.js    | 364 ++++++++++
 .../levelcode-ai/test/diagramHost.test.js     | 651 ++++++++++++++++++
 .../levelcode-ai/test/diagramLinks.test.js    | 115 ++++
 .../levelcode-ai/test/diagramSession.test.js  | 234 +++++++
 .../levelcode-ai/test/diagramStats.test.js    | 142 ++++
 .../levelcode-ai/test/diagramUi.test.js       | 169 +++++
 .../test/sessionExpiredHost.test.js           |   3 +
 .../levelcode-ai/test/sessionsUi.test.js      |   9 +-
 27 files changed, 3400 insertions(+), 60 deletions(-)
 create mode 100644 extensions/levelcode-ai/diagram/bundle.js
 create mode 100644 extensions/levelcode-ai/diagram/exportCheck.js
 create mode 100644 extensions/levelcode-ai/diagram/links.js
 create mode 100644 extensions/levelcode-ai/diagram/service.js
 create mode 100644 extensions/levelcode-ai/diagram/stats.js
 create mode 100644 extensions/levelcode-ai/diagram/tool.js
 create mode 100644 extensions/levelcode-ai/test/diagramAgent.test.js
 create mode 100644 extensions/levelcode-ai/test/diagramHost.test.js
 create mode 100644 extensions/levelcode-ai/test/diagramLinks.test.js
 create mode 100644 extensions/levelcode-ai/test/diagramSession.test.js
 create mode 100644 extensions/levelcode-ai/test/diagramStats.test.js
 create mode 100644 extensions/levelcode-ai/test/diagramUi.test.js

diff --git a/extensions/levelcode-ai/agent.js b/extensions/levelcode-ai/agent.js
index 1505cdb..59cdcc2 100644
--- a/extensions/levelcode-ai/agent.js
+++ b/extensions/levelcode-ai/agent.js
@@ -21,6 +21,8 @@ const { loadProjectRules } = require('./projectRules');
 const { loadServerConfig, buildAgentTools, toolCountsByServer, classifyMcpTool, explainMcpRefusal, describeMcpCall,
 	isLaunchTrusted, rememberLaunchTrust, describeMcpLaunch } = require('./mcpConfig');
 const { connectAll, getServer } = require('./mcpClient');
+const diagramTool = require('./diagram/tool');
+const diagramRepair = require('./diagram/repair');
 
 const SYSTEM_BASE = [
 	"You are LevelCode's built-in autonomous coding agent. You accomplish the user's goal in their",
@@ -307,6 +309,13 @@ function runCommand(root, command, onChunk, onExit, onStart, timeoutMs) {
 	});
 }
 
+/**
+ * Can the surface on the other end of this run show a diagram? (docs/RICH-DIAGRAMS.md, "Capability
+ * flag".) Asked in two places — when the tools and the prompt are assembled, and again when a call
+ * arrives — and they must agree, or a client could be refused a tool it was offered.
+ */
+function richClient(ctx) { return !!(ctx.diagrams && ctx.client && ctx.client.render === 'rich'); }
+
 /** Execute one tool call; returns a string result for the model. */
 async function runTool(tu, ctx) {
 	const root = ctx.root;
@@ -517,6 +526,22 @@ async function runTool(tu, ctx) {
 			try { return String(ctx.recallSessions(query) || 'No matching past sessions in this project.'); }
 			catch (e) { return 'ERROR: recall failed.'; }
 		}
+		// Rich diagrams (docs/RICH-DIAGRAMS.md). The model describes structure; the host validates it,
+		// climbs the repair ladder and posts what the chat should show. Read-only and instant — it
+		// draws in the transcript and touches nothing else — so, like update_plan, it never asks.
+		if (tu.name === diagramTool.RENDER_DIAGRAM.name) {
+			// Asked for by a client that was never offered it (the setting was turned off mid-conversation,
+			// or the model remembers the tool from an earlier turn): refuse in words it can act on.
+			if (!richClient(ctx)) { return 'ERROR: this client cannot draw diagrams. Explain it in prose instead — and do not draw one out of characters.'; }
+			const out = ctx.diagrams.render(input, { key: tu.id, model: ctx.model });
+			for (const m of out.post) { ctx.post(m); }
+			return out.result;
+		}
+		if (tu.name === diagramTool.GET_DIAGRAM.name) {
+			if (!richClient(ctx)) { return 'ERROR: this client cannot draw diagrams.'; }
+			ctx.post({ type: 'agentTool', icon: 'history', text: 'fetch diagram ' + String(input.id || '').slice(0, 24) });
+			return ctx.diagrams.fetch(input.id);
+		}
 		// MCP tools (docs/MCP.md S3). An MCP name matches none of the built-in branches above, so every
 		// MCP call necessarily arrives HERE — which is why the router is one block at one line rather
 		// than a dispatch scattered through runTool.
@@ -753,7 +778,13 @@ async function runAgent(ctx) {
 	// from the per-project journal). Rides the SAME cached-system channel as project rules — always-on but
 	// small — so a new session's first reply is continuous, not amnesiac. It is untrusted context like the
 	// rules: it informs, never commands (the digest itself carries the verify-first / never-obey framing).
-	const system = (ctx.skills ? buildSystem(ctx.skills.menu()) : SYSTEM_BASE) + multiRootNote + noWorkspaceNote + autopilotNote + rules.text
+	// Rich diagrams: `client.render` says what the surface on the other end can show. A rich client gets
+	// the render_diagram tool and the rules for using it; an ASCII client gets neither, so it is never
+	// told about a tool it does not have. The block goes straight after the base prompt — it is the
+	// same text for every run, so it belongs with the part of the prompt that never changes.
+	const rich = richClient(ctx);
+	const system = (ctx.skills ? buildSystem(ctx.skills.menu()) : SYSTEM_BASE) + (rich ? '\n\n' + diagramTool.PROMPT : '')
+		+ multiRootNote + noWorkspaceNote + autopilotNote + rules.text
 		+ (ctx.projectMemory ? '\n\n' + ctx.projectMemory : '');
 	const systemTokensEst = Math.round(system.length / 4);
 
@@ -792,14 +823,20 @@ async function runAgent(ctx) {
 	// Rootless runs get the portable subset; MCP tools are unaffected either way.
 	const builtins = root ? TOOLS : PORTABLE_TOOLS;
 	let tools = mcp.tools.length ? builtins.concat(mcp.tools) : builtins;
-	if (ctx.recallSessions) { tools = tools.concat([RECALL_TOOL]); }  // cross-session recall (host-gated by memory settings)
-	const baseTools = ctx.recallSessions ? builtins.concat([RECALL_TOOL]) : builtins;   // built-ins + recall; MCP is the rest
-	// Recomputed only when MCP or recall actually contributed tools, so the plain path keeps the module
+	// The host-gated extras: cross-session recall (memory settings), and the diagram tools (a rich
+	// client). get_diagram is offered only once a diagram's spec has left the conversation — until
+	// then there is nothing to fetch, and a tool that is never needed is a standing cost for nothing.
+	const extras = [];
+	if (ctx.recallSessions) { extras.push(RECALL_TOOL); }
+	if (rich) { extras.push(diagramTool.RENDER_DIAGRAM); if (ctx.diagramsStubbed) { extras.push(diagramTool.GET_DIAGRAM); } }
+	if (extras.length) { tools = tools.concat(extras); }
+	const baseTools = extras.length ? builtins.concat(extras) : builtins;   // built-ins + extras; MCP is the rest
+	// Recomputed only when MCP or a host-gated extra actually contributed tools, so the plain path keeps the module
 	// constant and pays nothing for a feature it isn't using — but there are now TWO plain paths, and the
 	// constant has to match the list that was actually sent. Reporting the full cost for a rootless run
 	// was the same mistake as leaving baseTools on TOOLS, one line further down.
 	const builtinsTokensEst = root ? TOOLS_TOKENS_EST : PORTABLE_TOOLS_TOKENS_EST;
-	const toolsTokensEst = (mcp.tools.length || ctx.recallSessions) ? Math.round(JSON.stringify(tools).length / 4) : builtinsTokensEst;
+	const toolsTokensEst = (mcp.tools.length || extras.length) ? Math.round(JSON.stringify(tools).length / 4) : builtinsTokensEst;
 	// The MCP SHARE of that, reported separately so the context popover can show what these servers cost
 	// (docs/MCP.md S5). Every tool schema rides EVERY turn, so a chatty server is a standing tax on the
 	// window rather than a one-off — and until it has its own segment, that cost is invisible.
@@ -812,6 +849,9 @@ async function runAgent(ctx) {
 		: 0;
 
 	const messages = ctx.messages;
+	if (ctx.diagrams) { ctx.diagrams.beginRun(); }   // nothing owed from an earlier run; repair passes reset
+	// tool_use ids whose placeholder already carries its title (the spec streams; the title arrives early)
+	const diagramTitled = new Set();
 	let step = 0;
 	let reason = 'done';
 	let nudges = 0;
@@ -898,12 +938,26 @@ async function runAgent(ctx) {
 				apiKey: ctx.apiKey, model: ctx.model, maxTokens: perTurnMax, system: system,
 				messages, tools: tools, signal: ctx.signal,
 				onText: (t) => { streamed = true; textChars += t.length; ctx.post({ type: 'agentDelta', text: t }); },
-				onToolStart: (name) => {
+				onToolStart: (name, id) => {
 					dbg('tool.start', { name });
 					const verb = name === 'edit_file' || name === 'write_file' ? 'preparing edit (' + name + ')…'
 						: name === 'delete_file' ? 'deleting a file…'
-						: name === 'run_command' ? 'preparing command…' : name === 'update_plan' ? 'planning…' : 'running ' + name + '…';
+						: name === 'run_command' ? 'preparing command…' : name === 'update_plan' ? 'planning…'
+						: name === diagramTool.RENDER_DIAGRAM.name ? 'drawing a diagram…' : 'running ' + name + '…';
 					ctx.post({ type: 'agentStatus', text: verb });
+					// A diagram's place in the answer is held from the moment the model starts writing it.
+					if (rich && id && name === diagramTool.RENDER_DIAGRAM.name) { ctx.post({ type: 'diagramPending', key: id, state: 'drawing', title: '' }); }
+				},
+				// The spec streams in as JSON. Its title is near the front, so the placeholder can say what
+				// is being drawn long before the last node arrives. Posted once per call.
+				onToolInput: (id, name, json) => {
+					if (!rich || !id || name !== diagramTool.RENDER_DIAGRAM.name || diagramTitled.has(id)) { return; }
+					const m = /"title"\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(json);
+					if (!m) { return; }
+					diagramTitled.add(id);
+					let title = m[1];
+					try { title = JSON.parse('"' + m[1] + '"'); } catch (e) { /* show it as written */ }
+					ctx.post({ type: 'diagramPending', key: id, state: 'drawing', title: diagramRepair.cleanText(title).slice(0, 120) });
 				},
 				// A transient upstream 5xx (502/503/504) is retried once before it can fail the run — surface it
 				// as a status rather than a mystery pause, and log it. Nothing has streamed yet when this fires.
@@ -975,7 +1029,22 @@ async function runAgent(ctx) {
 				let cancelled = false;
 				for (const tu of toolUses) {
 					if (cancelled || ctx.signal.aborted) { cancelled = true; dbg('tool.cancelled', { name: tu.name }); results.push({ type: 'tool_result', tool_use_id: tu.id, content: 'Cancelled by the user.' }); continue; }
-					if (turn.malformed && turn.malformed.has(tu.id)) { dbg('tool.malformed', { name: tu.name }); results.push({ type: 'tool_result', tool_use_id: tu.id, content: 'ERROR: your tool arguments were cut off (truncated JSON). Retry with smaller input — for edits use edit_file with a short snippet.' }); continue; }
+					if (turn.malformed && turn.malformed.has(tu.id)) {
+						dbg('tool.malformed', { name: tu.name });
+						// A diagram spec is the one input worth a second look: JSON with a trailing comma or a
+						// comment is a spec, and the lenient parser reads it. A spec that simply STOPS is not —
+						// that is the model hitting its length limit, and it is re-requested, never repaired.
+						if (tu.name === diagramTool.RENDER_DIAGRAM.name && rich) {
+							const rawArgs = turn.raw && turn.raw.get(tu.id);
+							const parsed = (turn.stop_reason !== 'max_tokens' && typeof rawArgs === 'string') ? diagramRepair.parseLenient(rawArgs) : null;
+							const out = (parsed && parsed.ok) ? ctx.diagrams.render(rawArgs, { key: tu.id, model: ctx.model }) : ctx.diagrams.truncated({ key: tu.id, model: ctx.model });
+							for (const m of out.post) { ctx.post(m); }
+							results.push({ type: 'tool_result', tool_use_id: tu.id, content: out.result });
+							continue;
+						}
+						results.push({ type: 'tool_result', tool_use_id: tu.id, content: 'ERROR: your tool arguments were cut off (truncated JSON). Retry with smaller input — for edits use edit_file with a short snippet.' });
+						continue;
+					}
 					dbg('tool.call', { name: tu.name, input: inputPreview(tu.input, !!(ctx.mcpRoutes && ctx.mcpRoutes.has(tu.name))) });
 					const out = await runTool(tu, ctx);
 					dbg('tool.result', { name: tu.name, chars: String(out).length, error: String(out).startsWith('ERROR') });
@@ -995,6 +1064,7 @@ async function runAgent(ctx) {
 
 			// No tool calls this turn.
 			const text = turn.content.filter((c) => c.type === 'text').map((c) => c.text).join('');
+			if (rich && text.trim()) { ctx.diagrams.noteAnswer(text); }   // "ASCII leaks": counted, never acted on
 			if (turn.stop_reason === 'max_tokens') {
 				// The turn was pure prose cut off at the token cap. Ask the model to CONTINUE exactly where it
 				// left off (not switch strategies) so the full answer streams out across turns instead of being
@@ -1059,6 +1129,11 @@ async function runAgent(ctx) {
 		}
 		else { ctx.post({ type: 'agentError', message: msg, code }); reason = 'error'; }
 	} finally {
+		// A diagram sent back for repair that never came back right still owes the user a picture:
+		// draw what can be drawn of it now, before the run is declared over. Never a blank placeholder.
+		if (ctx.diagrams) {
+			try { for (const m of ctx.diagrams.endRun()) { ctx.post(m); } } catch (e) { dbg('diagram.settle.error', { msg: String((e && e.message) || e) }); }
+		}
 		dbg('agent.done', { reason, steps: step - 1, edits: ctx.editCount || 0, costMicros: runCostMicros, creditsLeftMicros: ctx.credits != null ? ctx.credits : null });
 		// [LevelCode] Gateway runs now carry real money: costMicros = what THIS run cost, credits = the
 		// remaining balance — both RETAIL micro-$. BYOK runs send neither (null/0) and the bar omits them.
diff --git a/extensions/levelcode-ai/diagram/bundle.js b/extensions/levelcode-ai/diagram/bundle.js
new file mode 100644
index 0000000..5afeea9
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/bundle.js
@@ -0,0 +1,59 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · the webview's copy  (docs/RICH-DIAGRAMS.md, "Architecture")
+ *
+ *  The chat renders diagrams itself — it has the real font to measure text with and the live theme
+ *  to paint with — using the SAME modules the extension host validates with. There is one copy of
+ *  that code, in this folder; this file hands it to the webview as source text, which extension.js
+ *  inlines into chat.html under the page's own script nonce.
+ *
+ *  Inlined, not linked: every document this extension serves is self-contained (webviewCsp() allows
+ *  no remote anything), and one nonce'd inline block keeps it that way — no extra origin in the CSP,
+ *  no file to fetch, and the page behaves identically in the test harness.
+ *
+ *  Host-only. Never shipped to the webview itself: tool.js (what the model is told), service.js
+ *  (conversation state), stats.js and this file stay on the host side.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const theme = require('./theme');
+
+/** In dependency order: each module's factory reads the ones before it off `LCDiagram`. */
+const FILES = ['theme.js', 'schema.js', 'validate.js', 'repair.js', 'layout.js', 'scene.js', 'text.js', 'ascii.js'];
+
+/**
+ * A script block ends at the first "</script" the HTML parser sees, and "<!--" changes how the rest
+ * is tokenised — whatever JavaScript thinks they are. None of these files contains either; if one
+ * ever does, refuse to build the page rather than ship a script that ends early.
+ */
+const BREAKS_SCRIPT = /<\/script|<!--|<script/i;
+
+let cached = null;
+/** The modules, concatenated, ready to sit inside one <script> element. */
+function webviewSource() {
+	if (cached !== null) { return cached; }
+	const parts = FILES.map((f) => {
+		const src = fs.readFileSync(path.join(__dirname, f), 'utf8');
+		if (BREAKS_SCRIPT.test(src)) { throw new Error('diagram/' + f + ' contains a sequence that would end an inline <script> block'); }
+		return '// ---- diagram/' + f + '\n' + src;
+	});
+	cached = parts.join('\n;\n');
+	return cached;
+}
+/** The stylesheet for the live view: every rule reads an editor theme token. */
+function webviewCss() { return theme.css(); }
+
+/**
+ * Put both into the page. chat.html carries two placeholders; a function replacer is used so no "$"
+ * in the source is read as a replacement pattern.
+ * @param {string} html
+ */
+function inject(html) {
+	return String(html)
+		.replace('/*__LCD_CSS__*/', () => webviewCss())
+		.replace('/*__LCD_JS__*/', () => webviewSource());
+}
+
+module.exports = { FILES, webviewSource, webviewCss, inject, BREAKS_SCRIPT };
diff --git a/extensions/levelcode-ai/diagram/exportCheck.js b/extensions/levelcode-ai/diagram/exportCheck.js
new file mode 100644
index 0000000..241a84c
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/exportCheck.js
@@ -0,0 +1,81 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · what may be written to disk  (docs/RICH-DIAGRAMS.md, FR-7 +
+ *  "Safe rendering")
+ *
+ *  An exported SVG or PNG is produced in the webview — that is where the real font and the live
+ *  theme are, and it is the only way "exports match the rendered view" can be true. So the bytes
+ *  cross the webview boundary, and the host does not take them on trust: before anything is written,
+ *  an SVG must be made of nothing but the painter's own elements and attributes, and a PNG must
+ *  actually be a PNG.
+ *
+ *  This is an allow-list over structure, the same lists the painter draws from — not a search for
+ *  known-bad strings.
+ *
+ *  Host-only, pure.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const scene = require('./scene');
+
+const MAX_SVG = 2 * 1024 * 1024;
+const MAX_PNG = 20 * 1024 * 1024;
+const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+/**
+ * Is this an SVG the painter could have produced?
+ * @param {any} svg
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+function checkSvg(svg) {
+	if (typeof svg !== 'string') { return { ok: false, reason: 'not text' }; }
+	if (svg.length > MAX_SVG) { return { ok: false, reason: 'too large' }; }
+	const src = svg.trim();
+	if (!/^<svg[\s>]/.test(src) || !/<\/svg>$/.test(src)) { return { ok: false, reason: 'not an SVG document' }; }
+	// One stylesheet at most, in CDATA, and it may not reach outside the file.
+	const styles = src.match(/<style>[\s\S]*?<\/style>/g) || [];
+	if (styles.length > 1) { return { ok: false, reason: 'more than one stylesheet' }; }
+	for (const st of styles) {
+		const css = st.replace(/^<style><!\[CDATA\[/, '').replace(/\]\]><\/style>$/, '');
+		if (css === st || /<|\]\]>|@import|url\s*\(|expression\s*\(|javascript:|\\/i.test(css)) { return { ok: false, reason: 'stylesheet is not the painter\'s' }; }
+	}
+	const body = src.replace(/<style>[\s\S]*?<\/style>/g, '<style/>');
+	if (/<!|<\?|\]\]>/.test(body)) { return { ok: false, reason: 'declarations and comments are not allowed' }; }
+	const stack = [];
+	for (const m of body.matchAll(/<[^>]*>/g)) {
+		const tag = m[0];
+		const end = /^<\/([A-Za-z][\w:-]*)>$/.exec(tag);
+		if (end) { if (stack.pop() !== end[1]) { return { ok: false, reason: 'tags do not nest' }; } continue; }
+		const start = /^<([A-Za-z][\w:-]*)((?:\s+[\w:-]+="[^"<>]*")*)\s*(\/?)>$/.exec(tag);
+		if (!start) { return { ok: false, reason: 'malformed tag' }; }
+		if (!scene.TAGS.has(start[1])) { return { ok: false, reason: 'element <' + start[1] + '> is not allowed' }; }
+		for (const a of (start[2].match(/[\w:-]+(?==")/g) || [])) { if (!scene.ATTRS.has(a)) { return { ok: false, reason: 'attribute "' + a + '" is not allowed' }; } }
+		if (!start[3]) { stack.push(start[1]); }
+	}
+	if (stack.length) { return { ok: false, reason: 'unclosed element' }; }
+	if (/<[^>]*$/.test(body)) { return { ok: false, reason: 'unclosed tag' }; }
+	return { ok: true };
+}
+
+/**
+ * Decode a base64 PNG, checking it is one.
+ * @param {any} base64
+ * @returns {{ ok: true, bytes: Buffer } | { ok: false, reason: string }}
+ */
+function checkPng(base64) {
+	if (typeof base64 !== 'string' || !base64) { return { ok: false, reason: 'no image data' }; }
+	const b64 = base64.replace(/^data:image\/png;base64,/, '');
+	if (b64.length > MAX_PNG * 1.4) { return { ok: false, reason: 'too large' }; }
+	if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64)) { return { ok: false, reason: 'not base64' }; }
+	const bytes = Buffer.from(b64, 'base64');
+	if (bytes.length > MAX_PNG) { return { ok: false, reason: 'too large' }; }
+	if (bytes.length < 60 || PNG_MAGIC.some((v, i) => bytes[i] !== v)) { return { ok: false, reason: 'not a PNG image' }; }
+	return { ok: true, bytes };
+}
+
+/** A file name for a diagram, from its title: lowercase words joined by hyphens, never empty. */
+function fileStem(title) {
+	return String(title == null ? '' : title).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60).replace(/-+$/, '') || 'diagram';
+}
+
+module.exports = { checkSvg, checkPng, fileStem, MAX_SVG, MAX_PNG };
diff --git a/extensions/levelcode-ai/diagram/links.js b/extensions/levelcode-ai/diagram/links.js
new file mode 100644
index 0000000..206c417
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/links.js
@@ -0,0 +1,103 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · code links  (docs/RICH-DIAGRAMS.md, "Safe rendering → Link safety")
+ *
+ *  "openLink only resolves paths inside the current workspace, after normalizing `..` segments and
+ *  symlinks. Anything else is shown as plain text."
+ *
+ *  A node's link is model output — possibly copied from a file or a web page the model read — so the
+ *  path in it is a claim, not a location. resolveLink() is the only thing that turns one into a file:
+ *
+ *    • it must be a plain path. Anything with a URL scheme (http:, file:, javascript:, vscode:) is
+ *      refused before the file system is touched;
+ *    • it is resolved against the workspace folders, which collapses every `..`;
+ *    • the result must exist and be a regular file;
+ *    • and its REAL path — every symlink followed — must still be inside the real path of a workspace
+ *      folder. A link inside the repo that points at ~/.ssh is refused here.
+ *
+ *  It runs twice: when a diagram is drawn (a link that fails is dropped, so the node is plain text)
+ *  and again at the moment of a click (the file may have moved, or become a symlink, since).
+ *
+ *  Host-only, vscode-free: the workspace folders and the file system are passed in.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const nodeFs = require('fs');
+const path = require('path');
+
+const inside = (root, p) => p === root || p.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+/** "C:\x" and "C:/x" are paths; "http://x", "file:///x", "javascript:x", "vscode://x" are not. */
+const hasScheme = (s) => /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(s) && !/^[a-zA-Z]:[\\/]/.test(s);
+
+/**
+ * @param {{ path?: any }} link
+ * @param {Array<{ name: string, root: string }>} folders  the workspace folders
+ * @param {{ fs?: any }} [opts]  fs: a stand-in for tests
+ * @returns {{ ok: true, path: string, abs: string } | { ok: false, reason: string }}
+ */
+function resolveLink(link, folders, opts) {
+	const fs = (opts && opts.fs) || nodeFs;
+	const raw = link && typeof link.path === 'string' ? link.path.trim() : '';
+	if (!raw) { return { ok: false, reason: 'no path' }; }
+	if (raw.indexOf('\u0000') >= 0) { return { ok: false, reason: 'not a path' }; }
+	if (hasScheme(raw)) { return { ok: false, reason: 'not a file path' }; }
+	const list = (Array.isArray(folders) ? folders : []).filter((f) => f && typeof f.root === 'string' && f.root);
+	if (!list.length) { return { ok: false, reason: 'no folder is open' }; }
+
+	// The same reading the agent's own file tools give a path: in a multi-root workspace a leading
+	// folder NAME picks that folder; otherwise the first folder that has the file wins.
+	const candidates = [];
+	if (path.isAbsolute(raw)) { candidates.push(path.resolve(raw)); }
+	else {
+		const seg = raw.split(/[\\/]/)[0];
+		const named = list.length > 1 ? list.find((f) => f.name === seg) : null;
+		if (named) { candidates.push(path.resolve(named.root, raw.slice(seg.length).replace(/^[\\/]+/, ''))); }
+		for (const f of list) { candidates.push(path.resolve(f.root, raw)); }
+	}
+	let sawOutside = false;
+	for (const abs of candidates) {
+		const home = list.find((f) => inside(path.resolve(f.root), abs));
+		if (!home) { sawOutside = true; continue; }           // `..` walked out of the workspace
+		let stat;
+		try { stat = fs.statSync(abs); } catch (e) { continue; }
+		if (!stat.isFile()) { continue; }
+		let real;
+		try { real = fs.realpathSync(abs); } catch (e) { continue; }
+		const realHome = list.find((f) => { try { return inside(fs.realpathSync(f.root), real); } catch (e) { return false; } });
+		if (!realHome) { return { ok: false, reason: 'it is a link to somewhere outside this workspace' }; }
+		const rel = path.relative(path.resolve(home.root), abs).split(path.sep).join('/');
+		return { ok: true, path: list.length > 1 ? home.name + '/' + rel : rel, abs };
+	}
+	return { ok: false, reason: sawOutside ? 'outside this workspace' : 'no such file in this workspace' };
+}
+
+/**
+ * Where in a file a symbol is, by plain text search — the fallback when the language has no symbol
+ * provider. Prefers a line that DEFINES the name over one that merely mentions it.
+ * @param {string} content
+ * @param {string} symbol
+ * @returns {number | null}  1-based line, or null
+ */
+function findSymbolLine(content, symbol) {
+	// "Agent.runAgent()" names runAgent. Only identifier characters ever reach the pattern below.
+	const name = String(symbol || '').split(/[^\w$]+/).filter(Boolean).pop();
+	if (!name) { return null; }
+	const lines = String(content).split('\n');
+	const esc = name.replace(/\$/g, '\\$');
+	const word = new RegExp('(^|[^\\w$])' + esc + '($|[^\\w$])');
+	// A definition: a declaring keyword DIRECTLY before the name, the name assigned a function, or a
+	// method written as `name(args) {`. "const x = name" mentions the name; it does not define it.
+	const defines = new RegExp(
+		'\\b(function\\*?|class|def|fn|func|interface|type|struct|enum|module|const|let|var)\\s+\\*?\\s*' + esc + '(?![\\w$])'
+		+ '|(^|[^\\w$.])' + esc + '\\s*[:=]\\s*(async\\s*)?(function\\b|\\(|[\\w$]+\\s*=>)'
+		+ '|^\\s*((async|static|public|private|protected|export)\\s+)*' + esc + '\\s*\\([^)]*\\)\\s*\\{');
+	let first = null;
+	for (let i = 0; i < lines.length; i++) {
+		if (!word.test(lines[i])) { continue; }
+		if (defines.test(lines[i])) { return i + 1; }
+		if (first === null) { first = i + 1; }
+	}
+	return first;
+}
+
+module.exports = { resolveLink, findSymbolLine, hasScheme };
diff --git a/extensions/levelcode-ai/diagram/service.js b/extensions/levelcode-ai/diagram/service.js
new file mode 100644
index 0000000..7702e29
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/service.js
@@ -0,0 +1,268 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · one conversation's diagrams  (docs/RICH-DIAGRAMS.md,
+ *  "Validation and repair → Repair ladder" + "Storage")
+ *
+ *  repair.prepare() climbs the ladder for ONE call. This is what remembers across calls:
+ *
+ *    • whether the model has already had its one repair pass for a diagram — so the second failure
+ *      degrades instead of bouncing again ("no automatic second repair"),
+ *    • that a diagram sent back for repair still owes the user a picture — so if the model never
+ *      answers, the run does not end on an empty placeholder ("no blank output"),
+ *    • every diagram this conversation has drawn, by id — so a node can be clicked, a picture
+ *      exported, a spec fetched back after the conversation is compacted, and a reopened chat shows
+ *      exactly what it showed before, without running the ladder again ("re-opening a chat never
+ *      re-runs repair").
+ *
+ *  vscode-free and deterministic: the host injects how a link is resolved and where numbers go, and
+ *  gets back the tool result to return to the model plus the messages to post to the chat.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const repair = require('./repair');
+const validator = require('./validate');
+const text = require('./text');
+const tool = require('./tool');
+
+/** A model that keeps sending broken specs gets this many repair passes in one run, then no more. */
+const MAX_BOUNCES_PER_RUN = 3;
+/** How much of an undrawable input is kept so the user can see what was sent. */
+const SOURCE_CAP = 8000;
+
+const norm = (s) => String(s == null ? '' : s).toLowerCase().replace(/\s+/g, ' ').trim();
+const idsOf = (input) => {
+	const nodes = input && typeof input === 'object' && Array.isArray(input.nodes) ? input.nodes : [];
+	return nodes.map((n) => norm(n && typeof n === 'object' ? (n.id != null ? n.id : n.label) : n)).filter(Boolean);
+};
+const titleOf = (input) => norm(input && typeof input === 'object' ? input.title : '');
+/** Is this call another go at the same diagram? Same title, or mostly the same nodes. */
+function sameDiagram(a, b) {
+	if (a.title && a.title === b.title) { return true; }
+	if (!a.ids.length || !b.ids.length) { return false; }
+	const set = new Set(a.ids);
+	const shared = b.ids.filter((id) => set.has(id)).length;
+	return shared / Math.max(a.ids.length, b.ids.length) >= 0.5;
+}
+/** The title a (possibly unparseable) input claims, cleaned and bounded — or ''. */
+function titleFrom(input) {
+	let t = input && typeof input === 'object' ? input.title : null;
+	if (typeof input === 'string') { const m = /"title"\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(input); if (m) { try { t = JSON.parse('"' + m[1] + '"'); } catch (e) { t = m[1]; } } }
+	return typeof t === 'string' ? repair.cleanText(t).slice(0, 120) : '';
+}
+const countBy = (items, key) => { const out = {}; for (const it of items) { out[it[key]] = (out[it[key]] || 0) + 1; } return out; };
+function sourceOf(input) {
+	let s;
+	try { s = typeof input === 'string' ? input : JSON.stringify(input, null, 2); } catch (e) { s = String(input); }
+	s = String(s == null ? '' : s);
+	return s.length > SOURCE_CAP ? s.slice(0, SOURCE_CAP) + '\n… (' + (s.length - SOURCE_CAP) + ' more characters)' : s;
+}
+
+/**
+ * @param {{ resolveLink?: (link: {path:string, symbol?:string, line?:number}) => ({ ok: true, path: string } | { ok: false, reason: string }),
+ *           onStat?: (ev: any) => void, now?: () => Date }} [opts]
+ */
+function createDiagrams(opts) {
+	const o = opts || {};
+	const stat = (ev) => { if (typeof o.onStat === 'function') { try { o.onStat(ev); } catch (e) { /* counting must never break drawing */ } } };
+	const iso = () => (o.now ? o.now() : new Date()).toISOString();
+
+	/** @type {Map<string, any>} */
+	const records = new Map();
+	/** @type {Map<string, string>} */
+	const byKey = new Map();
+	let seq = 0;
+	let fresh = [];          // records made since the host last took them (to persist with the turn)
+	let run = { pending: null, bounces: 0, drawn: [] };
+
+	const nextId = () => { let id; do { id = 'd-' + (++seq); } while (records.has(id)); return id; };
+
+	/** Keep only the links the host says may be opened; the rest become plain text. */
+	function resolveLinks(spec) {
+		const unlinked = [];
+		for (const n of spec.nodes) {
+			if (!n.link) { continue; }
+			let r = null;
+			try { r = typeof o.resolveLink === 'function' ? o.resolveLink(n.link) : { ok: false, reason: 'links are unavailable here' }; } catch (e) { r = { ok: false, reason: 'could not be checked' }; }
+			if (r && r.ok) {
+				const link = { path: String(r.path) };
+				if (n.link.symbol) { link.symbol = n.link.symbol; }
+				if (n.link.line) { link.line = n.link.line; }
+				n.link = link;
+			} else {
+				unlinked.push(n.id + ': ' + ((r && r.reason) || 'not a file in this workspace'));
+				delete n.link;
+			}
+		}
+		return unlinked;
+	}
+
+	/** File a finished diagram (drawn, cut down, or failed) and build the message that shows it. */
+	function commit(prepared, meta, extra) {
+		const id = nextId();
+		const record = {
+			id, key: String(meta.key || id), v: prepared.spec ? prepared.spec.v : null, at: iso(),
+			status: prepared.status,
+			spec: prepared.spec || null,
+			fixes: repair.visibleFixes(prepared.fixes).map((f) => (f.pointer || '/') + ': ' + f.message),
+			notes: prepared.notes.slice(),
+			errors: validator.formatErrors(prepared.errors).split('\n').filter(Boolean)
+		};
+		if (meta.model) { record.model = String(meta.model); }
+		if (!prepared.spec) {
+			// Nothing was drawn, so there is no spec to read a title from; keep what the model called it.
+			record.source = sourceOf(extra && extra.input);
+			const t = titleFrom(extra && extra.input);
+			if (t) { record.title = t; }
+		}
+		if (extra && extra.repaired) { record.repaired = true; }           // "the repaired spec is stored and marked as repaired"
+		if (extra && extra.replaces) { record.replaces = extra.replaces; }
+		records.set(id, record);
+		byKey.set(record.key, id);
+		fresh.push(record);
+		const msg = { type: 'diagram', key: record.key, record };
+		if (extra && extra.replacesKey) { msg.replacesKey = extra.replacesKey; }
+		return { record, msg };
+	}
+
+	/** A diagram that was sent back and never came back right: draw what can be drawn of the original. */
+	function settlePending() {
+		const p = run.pending;
+		if (!p) { return []; }
+		run.pending = null;
+		const prepared = repair.prepare(p.input, { final: true });
+		let unlinked = [];
+		if (prepared.spec) { unlinked = resolveLinks(prepared.spec); }
+		if (unlinked.length) { prepared.notes = prepared.notes.concat([unlinked.length + ' link' + (unlinked.length === 1 ? '' : 's') + ' removed: not files in this workspace']); }
+		stat({ type: 'call', model: p.model, format: 'graph', outcome: prepared.status === 'degraded' ? 'degraded' : prepared.status === 'failed' ? 'failed' : 'fixed', errorClasses: validator.errorClasses(prepared.errors), fixClasses: countBy(prepared.fixes, 'cls') });
+		return [commit(prepared, { key: p.key, model: p.model }, { input: p.input }).msg];
+	}
+
+	/** A run begins: nothing is owed, and the model has its repair passes back. */
+	function beginRun() { run = { pending: null, bounces: 0, drawn: [] }; }
+	/** A run ends. Returns the messages that settle anything still owed. */
+	function endRun() { const post = settlePending(); run = { pending: null, bounces: 0, drawn: [] }; return post; }
+
+	/**
+	 * One render_diagram call.
+	 * @param {any} input  the tool call's arguments
+	 * @param {{ key: string, model?: string }} meta  key: the tool_use id (the chat placeholder is keyed by it)
+	 * @returns {{ result: string, post: any[] }}  the tool result for the model, and what to show
+	 */
+	function render(input, meta) {
+		const m = meta || { key: '' };
+		const me = { title: titleOf(input), ids: idsOf(input) };
+		const post = [];
+		let pending = run.pending;
+		// Something else was sent back for repair and the model has moved on to a different diagram:
+		// settle the old one now, so its placeholder does not wait for a call that is not coming.
+		if (pending && !sameDiagram(pending, me)) { for (const msg of settlePending()) { post.push(msg); } pending = null; }
+
+		const isRepair = !!pending;
+		const final = isRepair || run.bounces >= MAX_BOUNCES_PER_RUN;
+		const prepared = repair.prepare(input, { final });
+		const tokens = Math.round(sourceOf(input).length / 4);
+		const classes = { errorClasses: validator.errorClasses(prepared.errors), fixClasses: countBy(prepared.fixes, 'cls') };
+
+		if (prepared.status === 'truncated') {
+			stat(Object.assign({ type: 'call', model: m.model, format: 'graph', outcome: 'truncated', tokens }, classes));
+			return { result: tool.result(prepared), post };   // re-requested, never repaired; whatever was pending stays pending
+		}
+		if (prepared.status === 'errors') {
+			// Rung 2: the model's one repair pass. Remember what it owes, and say so in the chat.
+			run.pending = { key: String(m.key), input, model: m.model, title: me.title, ids: me.ids };
+			run.bounces++;
+			stat(Object.assign({ type: 'call', model: m.model, format: 'graph', outcome: 'bounced', tokens }, classes));
+			post.push({ type: 'diagramPending', key: String(m.key), state: 'repairing', title: typeof (input && input.title) === 'string' ? repair.cleanText(input.title).slice(0, 120) : '' });
+			return { result: tool.result(prepared), post };
+		}
+
+		run.pending = null;
+		let unlinked = [];
+		if (prepared.spec) { unlinked = resolveLinks(prepared.spec); }
+		// A second drawing of the same thing in the same run takes the first one's place in the chat.
+		const earlier = prepared.spec ? run.drawn.find((d) => d.title === me.title && me.title) : null;
+		const { record, msg } = commit(prepared, m, { input, repaired: isRepair && !!prepared.spec, replaces: earlier ? earlier.id : undefined, replacesKey: isRepair ? pending.key : (earlier ? earlier.key : undefined) });
+		if (prepared.spec) { run.drawn = run.drawn.filter((d) => d !== earlier).concat([{ id: record.id, key: record.key, title: me.title }]); }
+		post.push(msg);
+
+		const outcome = prepared.status === 'degraded' || prepared.status === 'failed' ? prepared.status
+			: isRepair ? 'repaired'
+				: prepared.status === 'fixed' ? 'fixed'
+					: prepared.fixes.length ? 'tidied' : 'clean';
+		stat(Object.assign({ type: 'call', model: m.model, format: 'graph', outcome, tokens }, classes));
+		return { result: tool.result(prepared, { id: record.id, unlinked }), post };
+	}
+
+	/** The tool arguments were cut off (malformed JSON at the token cap): re-request, never repair. */
+	function truncated(meta) {
+		stat({ type: 'call', model: meta && meta.model, format: 'graph', outcome: 'truncated' });
+		return { result: tool.result({ status: 'truncated', fixes: [], errors: [], notes: [] }), post: [] };
+	}
+
+	const get = (id) => records.get(String(id)) || null;
+	const byToolUse = (key) => (byKey.has(String(key)) ? records.get(byKey.get(String(key))) : null);
+	const list = () => Array.from(records.values());
+	/** Records made since the last call — what the host persists alongside the turn. */
+	const takeNew = () => { const out = fresh; fresh = []; return out; };
+
+	/**
+	 * A session was reopened: take its stored diagrams back. A record on disk is input too — a session
+	 * file can be edited, cut short or written by an older build — so each spec passes the validator on
+	 * the way in, exactly as a model's does. What the host then acts on (a link to open, a file to
+	 * export, a stub, get_diagram) is only ever a spec that was accepted; one that is not is kept as a
+	 * diagram that was never drawn. Nothing here calls a model, and a valid record comes back unchanged.
+	 */
+	function load(stored) {
+		records.clear(); byKey.clear(); fresh = []; seq = 0;
+		for (const r of (Array.isArray(stored) ? stored : [])) {
+			if (!r || typeof r !== 'object' || typeof r.id !== 'string' || !/^d-\d+$/.test(r.id)) { continue; }
+			let rec = r;
+			if (r.spec != null) {
+				let ok = null;
+				try { ok = repair.accept(r.spec); } catch (e) { ok = null; }
+				rec = Object.assign({}, r, ok && ok.ok ? { spec: ok.spec } : { spec: null, status: 'failed' });
+			}
+			records.set(rec.id, rec);
+			if (rec.key) { byKey.set(String(rec.key), rec.id); }
+			seq = Math.max(seq, Number(rec.id.slice(2)) || 0);
+		}
+		beginRun();
+	}
+	function reset() { records.clear(); byKey.clear(); fresh = []; seq = 0; beginRun(); }
+
+	/** get_diagram: the spec as the model would write it, or a plain reason there is none. */
+	function fetch(id) {
+		const want = String(id == null ? '' : id).trim();
+		const r = get(want);
+		if (!r) {
+			const known = list().filter((x) => x.spec).map((x) => x.id);
+			return 'ERROR: no diagram with id "' + want.slice(0, 40) + '" in this session.' + (known.length ? ' Known ids: ' + validator.listIds(known) + '.' : ' None has been drawn yet.');
+		}
+		if (!r.spec) { return 'ERROR: diagram ' + r.id + ' was never drawn (its spec was invalid). Draw it again with render_diagram.'; }
+		return text.toSource(r.spec);
+	}
+
+	/**
+	 * The one-line stubs for every diagram whose spec is in `messages` — what replaces those specs
+	 * when that stretch of the conversation is compacted. Nothing here runs turn by turn.
+	 */
+	function stubsFor(messages) {
+		const out = [];
+		for (const msg of (Array.isArray(messages) ? messages : [])) {
+			if (!msg || msg.role !== 'assistant' || !Array.isArray(msg.content)) { continue; }
+			for (const b of msg.content) {
+				if (!b || b.type !== 'tool_use' || b.name !== tool.RENDER_DIAGRAM.name) { continue; }
+				const r = byToolUse(b.id);
+				if (r && r.spec) { out.push(text.stub(r)); }
+			}
+		}
+		return out;
+	}
+
+	/** One finished answer to a client that can render: did it draw with characters anyway? */
+	function noteAnswer(answer) { stat({ type: 'answer', asciiArt: tool.looksLikeAsciiArt(answer) }); }
+
+	return { beginRun, endRun, render, truncated, noteAnswer, get, byToolUse, list, takeNew, load, reset, fetch, stubsFor, get pending() { return run.pending ? run.pending.key : null; } };
+}
+
+module.exports = { createDiagrams, sameDiagram, MAX_BOUNCES_PER_RUN, SOURCE_CAP };
diff --git a/extensions/levelcode-ai/diagram/stats.js b/extensions/levelcode-ai/diagram/stats.js
new file mode 100644
index 0000000..8d5aef6
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/stats.js
@@ -0,0 +1,123 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · measurement  (docs/RICH-DIAGRAMS.md, "Telemetry and evaluation")
+ *
+ *  The spec's rollout is gated on numbers: how often a spec is valid first time, how the fixes split
+ *  across the rungs of the ladder, which errors each model makes, how long a render takes, how many
+ *  tokens a diagram costs, and whether an answer ever drew with characters.
+ *
+ *  This is the counter behind those numbers. It is LOCAL — a plain object the host keeps in the
+ *  editor's own storage and shows on request; nothing here is sent anywhere.
+ *
+ *  What it records: formats, outcome classes, error classes, timings and token counts, per model.
+ *  What it never records: a label, a title, a path, a symbol, or any other text from a spec. record()
+ *  takes an event made of enums and numbers, and copies nothing else out of it.
+ *
+ *  Pure: no clock, no storage, no vscode. The host supplies the date and persists the object.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const VERSION = 1;
+/** How one call ended. `clean` is the spec's "first-pass valid": every layer passed with no fix at all. */
+const OUTCOMES = ['clean', 'tidied', 'fixed', 'repaired', 'degraded', 'failed', 'truncated', 'bounced'];
+/** Upper bounds of the histogram buckets (the last bucket is "more"). */
+const TOKEN_BUCKETS = [100, 200, 300, 400, 600, 800, 1200, 2000];
+const MS_BUCKETS = [8, 16, 33, 50, 100, 200, 300, 1000];
+/** A model id is kept as written but bounded, so a pathological id cannot bloat the store. */
+const MAX_MODELS = 40, MAX_CLASSES = 60;
+const CLASS_RE = /^[a-z][a-z0-9-]{0,39}$/;
+
+function empty(since) {
+	return { v: VERSION, since: since || null, calls: 0, byModel: {}, errors: {}, fixes: {}, tokens: TOKEN_BUCKETS.map(() => 0).concat([0]), renderMs: MS_BUCKETS.map(() => 0).concat([0]), rendered: 0, renderFailed: 0, flipped: 0, asciiLeaks: 0, answers: 0, linkClicks: 0, exports: {} };
+}
+const bucket = (bounds, value) => { let i = 0; while (i < bounds.length && value > bounds[i]) { i++; } return i; };
+const inc = (obj, key, cap) => { if (obj[key] !== undefined || Object.keys(obj).length < cap) { obj[key] = (obj[key] || 0) + 1; } };
+
+/**
+ * Fold one event in.
+ *   { type: 'call', model, format, outcome, errorClasses?, fixClasses?, tokens? }
+ *   { type: 'render', ms, ok, flipped? }      reported by the webview once the picture is on screen
+ *   { type: 'answer', asciiArt }              one assistant answer to a rich client
+ *   { type: 'link' } / { type: 'export', format }
+ * Anything it does not recognise is ignored; nothing but the fields named above is ever read.
+ */
+function record(stats, ev) {
+	const s = stats && stats.v === VERSION ? stats : empty(stats && stats.since);
+	if (!ev || typeof ev !== 'object') { return s; }
+	if (ev.type === 'call') {
+		const outcome = OUTCOMES.indexOf(ev.outcome) >= 0 ? ev.outcome : null;
+		if (!outcome) { return s; }
+		s.calls++;
+		const model = String(ev.model || 'unknown').slice(0, 80);
+		if (!s.byModel[model] && Object.keys(s.byModel).length >= MAX_MODELS) { return s; }
+		const m = s.byModel[model] || (s.byModel[model] = { calls: 0, outcomes: {}, errors: {} });
+		m.calls++;
+		m.outcomes[outcome] = (m.outcomes[outcome] || 0) + 1;
+		for (const cls of Object.keys(ev.errorClasses || {})) { if (CLASS_RE.test(cls)) { inc(s.errors, cls, MAX_CLASSES); inc(m.errors, cls, MAX_CLASSES); } }
+		for (const cls of Object.keys(ev.fixClasses || {})) { if (CLASS_RE.test(cls)) { inc(s.fixes, cls, MAX_CLASSES); } }
+		if (Number.isFinite(ev.tokens) && ev.tokens > 0) { s.tokens[bucket(TOKEN_BUCKETS, ev.tokens)]++; }
+	} else if (ev.type === 'render') {
+		if (ev.ok === false) { s.renderFailed++; return s; }
+		s.rendered++;
+		if (ev.flipped) { s.flipped++; }
+		if (Number.isFinite(ev.ms) && ev.ms >= 0) { s.renderMs[bucket(MS_BUCKETS, ev.ms)]++; }
+	} else if (ev.type === 'answer') {
+		s.answers++;
+		if (ev.asciiArt) { s.asciiLeaks++; }
+	} else if (ev.type === 'link') {
+		s.linkClicks++;
+	} else if (ev.type === 'export') {
+		const f = String(ev.format || '');
+		if (['svg', 'png', 'source', 'mermaid', 'markdown'].indexOf(f) >= 0) { s.exports[f] = (s.exports[f] || 0) + 1; }
+	}
+	return s;
+}
+
+/** The value below which `q` of a histogram's samples fall — reported as its bucket's upper bound. */
+function quantile(hist, bounds, q) {
+	const total = hist.reduce((a, b) => a + b, 0);
+	if (!total) { return null; }
+	let seen = 0;
+	for (let i = 0; i < hist.length; i++) {
+		seen += hist[i];
+		if (seen >= total * q) { return i < bounds.length ? bounds[i] : Infinity; }
+	}
+	return Infinity;
+}
+const pct = (num, den) => (den ? Math.round(1000 * num / den) / 10 : null);
+
+/**
+ * The table from the spec's "Telemetry and evaluation", computed. Rates are percentages of the calls
+ * that reached a verdict (a `bounced` call — one sent back for its repair pass — is not a verdict:
+ * the call that answers it is).
+ */
+function summarize(stats) {
+	const s = stats && stats.v === VERSION ? stats : empty();
+	const rows = (map) => {
+		const o = Object.assign({}, map);
+		const verdicts = OUTCOMES.filter((k) => k !== 'bounced' && k !== 'truncated').reduce((a, k) => a + (o[k] || 0), 0);
+		return {
+			verdicts,
+			firstPassValid: pct(o.clean || 0, verdicts),
+			autoFixed: pct((o.tidied || 0) + (o.fixed || 0), verdicts),
+			modelRepaired: pct(o.repaired || 0, verdicts),
+			degraded: pct((o.degraded || 0) + (o.failed || 0), verdicts),
+			truncated: o.truncated || 0
+		};
+	};
+	const all = {};
+	for (const m of Object.values(s.byModel)) { for (const [k, v] of Object.entries(m.outcomes)) { all[k] = (all[k] || 0) + v; } }
+	const top = (map) => Object.entries(map).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 8).map(([cls, count]) => ({ cls, count }));
+	return {
+		since: s.since, calls: s.calls,
+		overall: rows(all),
+		byModel: Object.keys(s.byModel).sort().map((model) => Object.assign({ model, topErrors: top(s.byModel[model].errors) }, rows(s.byModel[model].outcomes))),
+		topErrors: top(s.errors),
+		tokens: { median: quantile(s.tokens, TOKEN_BUCKETS, 0.5), p95: quantile(s.tokens, TOKEN_BUCKETS, 0.95) },
+		renderMs: { p50: quantile(s.renderMs, MS_BUCKETS, 0.5), p95: quantile(s.renderMs, MS_BUCKETS, 0.95), rendered: s.rendered, failed: s.renderFailed, flipped: s.flipped },
+		asciiLeaks: { answers: s.answers, leaks: s.asciiLeaks },
+		linkClicks: s.linkClicks, exports: Object.assign({}, s.exports)
+	};
+}
+
+module.exports = { VERSION, OUTCOMES, TOKEN_BUCKETS, MS_BUCKETS, empty, record, summarize, quantile };
diff --git a/extensions/levelcode-ai/diagram/tool.js b/extensions/levelcode-ai/diagram/tool.js
new file mode 100644
index 0000000..c7324ef
--- /dev/null
+++ b/extensions/levelcode-ai/diagram/tool.js
@@ -0,0 +1,124 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · rich diagrams · what the model is told  (docs/RICH-DIAGRAMS.md, "Diagram spec
+ *  and render_diagram tool" + "Prompting and capability detection")
+ *
+ *  Host-only (never shipped to the webview). Three things live here, and they are the whole of the
+ *  model's side of the feature:
+ *
+ *    RENDER_DIAGRAM   the tool. Its input schema is schema.SCHEMAS[v].house — the same object the
+ *                     validator checks against, so what the model is shown is what it is held to.
+ *    PROMPT           the rules a rich client adds to the system prompt: when a diagram earns its
+ *                     place, that characters are never to be drawn with, and one worked example.
+ *    result()         what a call answers: {"ok":true,"id":"d-1"}, or every error at once.
+ *
+ *  Both cost tokens on every request, so both are kept tight and their size is pinned by a test.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const schema = require('./schema');
+const validator = require('./validate');
+const repair = require('./repair');
+
+/**
+ * The tool definition (Anthropic shape; translate.js renames it for OpenAI-compatible providers).
+ * Read-only and instant — it draws in the chat and touches nothing — so it never asks for approval.
+ */
+const RENDER_DIAGRAM = Object.freeze({
+	name: 'render_diagram',
+	description: 'Draw a diagram in the chat (flow, architecture, pipeline, decision tree, state machine). '
+		+ 'Describe STRUCTURE only — nodes, edges, optional groups, one accent; the editor does layout and style, so never send coordinates, colours or sizes. '
+		+ 'Returns {"ok":true,"id":"d-1"} or a list of problems to fix (then call it once more).',
+	input_schema: schema.SCHEMAS[schema.VERSION].house
+});
+
+/**
+ * Fetch the spec of a diagram drawn earlier. Offered only once a diagram's spec has left the
+ * conversation (after a compaction), so it costs nothing until there is something to fetch.
+ */
+const GET_DIAGRAM = Object.freeze({
+	name: 'get_diagram',
+	description: 'Fetch the full spec of a diagram drawn earlier in this session, by its id (e.g. "d-17"), so you can edit it and call render_diagram again. '
+		+ 'Use it when the conversation only shows a one-line "diagram: …, id d-17" stub.',
+	input_schema: { type: 'object', properties: { id: { type: 'string', description: 'The diagram id from the stub, e.g. "d-17".' } }, required: ['id'] }
+});
+
+/**
+ * The system-prompt block for a client that can render (`client.render === 'rich'`). An ASCII client
+ * gets neither this nor the tool.
+ *
+ * Phase 1 draws boxes-and-arrows only. The block therefore says what to do INSTEAD of a chart or a
+ * sequence diagram — telling a model to emit a format the client would show as raw source would be
+ * worse than not mentioning it.
+ */
+const PROMPT = [
+	'DIAGRAMS. This client renders real diagrams. When STRUCTURE is the point — a flow, an architecture, a pipeline, a routing or decision tree, a state machine — call render_diagram instead of describing it in a wall of prose. When the answer reads fine as prose, draw nothing.',
+	'- NEVER draw boxes, arrows, trees or bars out of characters (no ASCII art, no box-drawing glyphs): they break in this client. render_diagram is the only way to draw.',
+	'- Asked for a diagram, DRAW it here with render_diagram. Writing one into a file instead (a diagram language in a document, an image) is only for when the user asks for a file.',
+	'- The title states the TAKEAWAY ("Jev classifies; your code decides the action"), not the topic. Labels are short — a name plus at most one line; detail goes in the prose around the diagram, not inside it.',
+	'- At most ONE accent: the node the title is about. Same kind of thing, same shape.',
+	'- More than 12 nodes: draw an overview, then one diagram per sub-flow.',
+	'- When the diagram describes code in this workspace, give nodes a link {path, symbol or line} so the user can click through.',
+	'- Numbers to compare go in a Markdown table and steps over time in a numbered list (charts and sequence diagrams are not available yet).',
+	'- After it returns ok the user is looking at the picture: do not restate it as a list. Say what it shows in a sentence and continue.',
+	'Example call: {"title":"Jev classifies; your code decides the action","nodes":[{"id":"in","label":"Customer message","sub":"plus account details"},{"id":"jev","label":"Jev","sub":"returns probabilities","accent":true},{"id":"bill","label":"Route to billing"},{"id":"rev","label":"Human review"}],"edges":[{"from":"in","to":"jev"},{"from":"jev","to":"bill","label":"0.90 or more"},{"from":"jev","to":"rev","label":"under 0.90"}]}'
+].join('\n');
+
+/** How many problem / fix lines one tool result carries. Past this they are counted, not listed. */
+const MAX_LINES = 8;
+const capLines = (lines) => (lines.length > MAX_LINES ? lines.slice(0, MAX_LINES).concat(['… and ' + (lines.length - MAX_LINES) + ' more.']) : lines);
+const fixLine = (f) => (f.pointer || '/') + ': ' + f.message.replace(' (the full text is kept as a tooltip)', '');
+
+/**
+ * The tool result for one prepared call.
+ * @param {ReturnType<typeof repair.prepare>} prepared
+ * @param {{ id?: string, unlinked?: string[] }} [info]  id: the diagram id it was drawn under; unlinked: links that did not resolve
+ * @returns {string}
+ */
+function result(prepared, info) {
+	const i = info || {};
+	const shown = repair.visibleFixes(prepared.fixes).map(fixLine);
+	if (prepared.status === 'ok' || prepared.status === 'fixed') {
+		const out = { ok: true, id: i.id };
+		if (shown.length) { out.fixed = capLines(shown); }
+		if (i.unlinked && i.unlinked.length) { out.unlinked = capLines(i.unlinked); }
+		if (shown.length || (i.unlinked && i.unlinked.length)) { out.note = 'Drawn. Redraw only if one of these changed what you meant.'; }
+		return JSON.stringify(out);
+	}
+	if (prepared.status === 'errors') {
+		const errs = capLines(validator.formatErrors(prepared.errors).split('\n'));
+		const k = prepared.errors.length;
+		return 'ERROR: the diagram was not drawn — ' + k + ' problem' + (k === 1 ? '' : 's') + ' in the spec. Fix ' + (k === 1 ? 'it' : 'them') + ' and call render_diagram once more.\n'
+			+ errs.join('\n')
+			+ (shown.length ? '\nAlso changed to fit (reword them yourself if the wording matters):\n' + capLines(shown).join('\n') : '');
+	}
+	if (prepared.status === 'truncated') {
+		return 'ERROR: the diagram spec was cut off before it was complete (your output hit its length limit). Send the whole spec again, smaller: at most 12 nodes, short labels, no detail in the diagram that belongs in prose.';
+	}
+	if (prepared.status === 'degraded') {
+		return JSON.stringify({ ok: true, id: i.id, degraded: capLines(prepared.notes), note: 'Drawn without the parts that were still invalid; the user can see what was left out and has a Retry button. Do NOT call render_diagram again for this diagram unless the user asks.' });
+	}
+	// failed
+	const first = prepared.errors.length ? validator.formatError(prepared.errors[0]) : 'nothing drawable in the spec';
+	return JSON.stringify({ ok: false, id: i.id, error: 'not drawn: ' + first, note: 'The user sees the source, the error and a Retry button. Do NOT call render_diagram again for this diagram unless the user asks; explain it in prose instead.' });
+}
+
+/**
+ * Did an answer DRAW with characters? The "ASCII leaks" metric: box-drawing glyphs, or frames built
+ * from +---+ and | |, in text sent to a client that can render. Conservative on purpose — a table, a
+ * file tree in a code block and a single "->" are not diagrams.
+ * @param {string} text
+ */
+function looksLikeAsciiArt(text) {
+	const s = String(text || '');
+	const boxGlyphs = (s.match(/[─-╿▶◀▲▼]/g) || []).length;
+	if (boxGlyphs >= 8) { return true; }
+	const lines = s.split('\n');
+	const frames = lines.filter((l) => /\+-{3,}\+/.test(l)).length;
+	const walls = lines.filter((l) => /^\s*\|.*\|\s*(-+>|<-+)?\s*(\|.*\|)?\s*$/.test(l) && !/\|\s*:?-{3,}/.test(l)).length;
+	if (frames >= 2 && walls >= 1) { return true; }
+	const arrows = lines.filter((l) => /(\]|\)|\w)\s*(-{2,}>|={2,}>)\s*(\[|\(|\w)/.test(l) && /[\[(|]/.test(l)).length;
+	return arrows >= 3 && frames >= 1;
+}
+
+module.exports = { RENDER_DIAGRAM, GET_DIAGRAM, PROMPT, result, looksLikeAsciiArt, MAX_LINES };
diff --git a/extensions/levelcode-ai/extension.js b/extensions/levelcode-ai/extension.js
index b759023..b4e7e13 100644
--- a/extensions/levelcode-ai/extension.js
+++ b/extensions/levelcode-ai/extension.js
@@ -37,6 +37,14 @@ const { openCustomize } = require('./customize');
 const { importFromVscode } = require('./importVscode');
 const { reapMcp, listActive, getServer } = require('./mcpClient');
 const { userScopedSetting, isNamespacedToolName, safeCopy, loadServerConfig, summarizeMcp, parseArgv, UNSAFE_KEYS } = require('./mcpConfig');
+const { createDiagrams } = require('./diagram/service');
+const diagramBundle = require('./diagram/bundle');
+const diagramLinks = require('./diagram/links');
+const diagramExport = require('./diagram/exportCheck');
+const diagramText = require('./diagram/text');
+const diagramStats = require('./diagram/stats');
+const diagramTool = require('./diagram/tool');
+const diagramAscii = require('./diagram/ascii');
 
 const SECRET_KEY = 'levelcode.ai.anthropicKey';   // legacy Anthropic key location (kept for back-compat)
 const FILE_EXCLUDES = '{**/node_modules/**,**/.git/**,**/out/**,**/dist/**,**/.vscode-test/**,**/*.map}';
@@ -1025,6 +1033,198 @@ function workspaceMapBlock(allFiles) {
 // /sessions modal + the sidebar view. Everything here is best-effort: a persistence failure must never
 // disturb a chat turn — callers guard, and the manager swallows index errors (the index is a rebuildable
 // cache). Off entirely when levelcode.ai.sessions.enabled is false.
+// ---- Rich diagrams (docs/RICH-DIAGRAMS.md) --------------------------------------------------------
+// The model emits a small spec through `render_diagram`; diagram/service.js validates it, climbs the
+// repair ladder and decides what the chat shows. This block is the editor's half: which files a
+// node may open, where an export is written, and where the numbers are kept.
+
+const DIAGRAM_STATS_KEY = 'levelcode.ai.diagrams.stats';
+let _diagramStats = null, _diagramStatsTimer = null;
+/** The local counters behind the spec's telemetry table. Kept in the editor's own storage; never sent anywhere. */
+function diagramStatsNow() {
+	if (!_diagramStats) {
+		const stored = ctx ? ctx.globalState.get(DIAGRAM_STATS_KEY) : null;
+		_diagramStats = stored && stored.v === diagramStats.VERSION ? stored : diagramStats.empty(new Date().toISOString().slice(0, 10));
+	}
+	return _diagramStats;
+}
+function recordDiagramStat(ev) {
+	_diagramStats = diagramStats.record(diagramStatsNow(), ev);
+	if (ev && ev.type === 'call') { dbg('diagram.call', { outcome: ev.outcome, errors: ev.errorClasses, fixes: ev.fixClasses, tokens: ev.tokens }); }
+	if (_diagramStatsTimer) { return; }
+	_diagramStatsTimer = setTimeout(() => {
+		_diagramStatsTimer = null;
+		try { if (ctx) { ctx.globalState.update(DIAGRAM_STATS_KEY, _diagramStats); } } catch (e) { /* counters are best-effort */ }
+	}, 2000);
+}
+const diagramFolders = () => (vscode.workspace.workspaceFolders || []).map((f) => ({ name: f.name, root: f.uri.fsPath }));
+/** This conversation's diagrams. One for the life of the extension; reset with the conversation. */
+const diagrams = createDiagrams({
+	resolveLink: (link) => diagramLinks.resolveLink(link, diagramFolders()),
+	onStat: recordDiagramStat
+});
+/** True once a diagram's spec has left the model's context (a compaction, or a resume that did not fit) —
+ *  which is the moment `get_diagram` starts being offered. */
+let diagramsStubbed = false;
+
+/**
+ * What the chat on the other end can show: `rich` (it renders diagrams) or `ascii` (it does not).
+ * The chat webview is rich; the setting is the user's way to say otherwise, and a model whose catalog
+ * row opts out of diagrams is treated as an ASCII client — it is given neither the tool nor the rules.
+ */
+function clientRender(providerId, modelId) {
+	if (!aiConfig().get('diagrams.enabled', true)) { return 'ascii'; }
+	return catalog.diagramSupportForModel(providerId, modelId) === 'tool' ? 'rich' : 'ascii';
+}
+
+/** A node was clicked. The webview says WHICH node; the file comes from the host's own record. */
+async function openDiagramLink(id, nodeId) {
+	const record = diagrams.get(id);
+	const node = record && record.spec ? record.spec.nodes.find((n) => n.id === String(nodeId)) : null;
+	if (!node || !node.link) { dbg('diagram.link.unknown', { id }); return; }
+	// Checked again at the moment of the click: the file may have moved, or become a link, since it was drawn.
+	const r = diagramLinks.resolveLink(node.link, diagramFolders());
+	if (!r.ok) { vscode.window.showWarningMessage('LevelCode: that link cannot be opened — ' + r.reason + '.'); dbg('diagram.link.refused', { reason: r.reason }); return; }
+	recordDiagramStat({ type: 'link' });
+	try {
+		const uri = vscode.Uri.file(r.abs);
+		const doc = await vscode.workspace.openTextDocument(uri);
+		let line = Number.isInteger(node.link.line) ? node.link.line : null;
+		if (node.link.symbol) {
+			let found = null;
+			try {
+				const symbols = await vscode.commands.executeCommand('vscode.executeDocumentSymbolProvider', uri);
+				const want = String(node.link.symbol).split(/[^\w$]+/).filter(Boolean).pop();
+				const walk = (list) => { for (const sym of (list || [])) { if (!found && sym && sym.name && String(sym.name).split(/[^\w$]+/).filter(Boolean).pop() === want) { found = sym; } if (!found && sym && sym.children) { walk(sym.children); } } };
+				walk(symbols);
+			} catch (e) { /* no symbol provider for this language */ }
+			if (found) { line = ((found.selectionRange || found.range || (found.location && found.location.range)).start.line) + 1; }
+			else { line = diagramLinks.findSymbolLine(doc.getText(), node.link.symbol) || line; }
+		}
+		const at = new vscode.Position(Math.max(0, Math.min(doc.lineCount - 1, (line || 1) - 1)), 0);
+		await vscode.window.showTextDocument(doc, { preview: false, selection: new vscode.Range(at, at) });
+	} catch (e) { dbg('diagram.link.error', { msg: String((e && e.message) || e) }); }
+}
+
+/**
+ * The fenced Mermaid block for a diagram — what goes into a Markdown file. The fence is one tick
+ * longer than any run of ticks inside, so nothing in a label can close it early. (The tick is built
+ * by code, never typed: a literal one here would be read as a template string by the brace matcher
+ * the host test suites slice this file with.)
+ */
+function diagramMarkdown(record) {
+	const tick = String.fromCharCode(96);
+	const body = diagramText.toMermaid(record.spec).replace(/\n+$/, '');
+	let longest = 0, run = 0;
+	for (const ch of body) { run = ch === tick ? run + 1 : 0; if (run > longest) { longest = run; } }
+	const fence = tick.repeat(Math.max(3, longest + 1));
+	return fence + 'mermaid\n' + body + '\n' + fence + '\n';
+}
+
+/**
+ * Export a diagram. `source`, `mermaid` and `markdown` are produced HERE from the stored spec; only
+ * `svg` and `png` carry bytes from the webview (that is where the real font and theme are), and those
+ * are checked structurally before a single byte is written — see diagram/exportCheck.js.
+ */
+async function exportDiagram(id, format, data) {
+	const record = diagrams.get(id);
+	if (!record || !record.spec) { return; }
+	const fmt = String(format);
+	try {
+		if (fmt === 'source') {
+			await vscode.env.clipboard.writeText(diagramText.toSource(record.spec));
+		} else if (fmt === 'mermaid') {
+			const langs = await vscode.languages.getLanguages();
+			const doc = await vscode.workspace.openTextDocument({ content: diagramText.toMermaid(record.spec), language: langs.includes('mermaid') ? 'mermaid' : 'plaintext' });
+			await vscode.window.showTextDocument(doc, { preview: false });
+		} else if (fmt === 'markdown') {
+			const block = '\n' + diagramMarkdown(record);
+			const ed = vscode.window.activeTextEditor;
+			let target = ed && ed.document.languageId === 'markdown' && isWorkspaceFile(ed.document.uri) ? ed : null;
+			if (!target) {
+				const files = await vscode.workspace.findFiles('**/*.{md,markdown}', FILE_EXCLUDES, 300);
+				if (!files.length) { vscode.window.showInformationMessage('LevelCode: there is no Markdown file in this workspace to insert into. Use “Open as Mermaid” instead.'); return; }
+				const pick = await vscode.window.showQuickPick(files.map((u) => ({ label: vscode.workspace.asRelativePath(u), uri: u })).sort((a, b) => a.label.localeCompare(b.label)), { placeHolder: 'Insert the diagram at the end of…', matchOnDescription: false });
+				if (!pick) { return; }
+				const doc = await vscode.workspace.openTextDocument(pick.uri);
+				target = await vscode.window.showTextDocument(doc, { preview: false });
+				const end = doc.lineAt(doc.lineCount - 1).range.end;
+				target.selection = new vscode.Selection(end, end);
+			}
+			const where = target.selection.active;
+			await target.edit((b) => b.insert(where, block));
+		} else if (fmt === 'svg' || fmt === 'png') {
+			const checked = fmt === 'svg' ? diagramExport.checkSvg(data) : diagramExport.checkPng(data);
+			if (!checked.ok) { dbg('diagram.export.refused', { format: fmt, reason: checked.reason }); vscode.window.showWarningMessage('LevelCode: the diagram could not be exported (' + checked.reason + ').'); return; }
+			// The title becomes a file name, and a title is free text: redact it the way a session export does.
+			const stem = diagramExport.fileStem(sessionMemory.redactSecrets(String(record.spec.title || 'diagram')));
+			const dir = (vscode.workspace.workspaceFolders && vscode.workspace.workspaceFolders[0]) ? vscode.workspace.workspaceFolders[0].uri.fsPath : os.homedir();
+			const target = await vscode.window.showSaveDialog({ filters: fmt === 'svg' ? { 'SVG image': ['svg'] } : { 'PNG image': ['png'] }, defaultUri: vscode.Uri.file(path.join(dir, stem + '.' + fmt)) });
+			if (!target) { return; }
+			await vscode.workspace.fs.writeFile(target, fmt === 'svg' ? Buffer.from(String(data), 'utf8') : checked.bytes);
+			vscode.window.showInformationMessage('Saved ' + path.basename(target.fsPath) + '.');
+		} else { return; }
+		recordDiagramStat({ type: 'export', format: fmt });
+	} catch (e) {
+		dbg('diagram.export.error', { format: fmt, msg: String((e && e.message) || e) });
+		vscode.window.showErrorMessage('LevelCode: could not export the diagram — ' + String((e && e.message) || e));
+	}
+}
+
+/** The Retry button on a degraded or failed diagram: the USER asks for another go. Never automatic. */
+async function retryDiagram(id) {
+	const record = diagrams.get(id);
+	if (!record || abort) { return; }
+	const what = record.spec ? '“' + record.spec.title + '” (id ' + record.id + ')' : 'you tried to draw (id ' + record.id + ')';
+	const problems = (record.errors || []).concat(record.notes || []).slice(0, diagramTool.MAX_LINES);   // the same cap a tool result uses
+	const keep = lastAgentGoal;
+	await agentFlow('Redraw the diagram ' + what + ' with render_diagram.' + (problems.length ? ' The last attempt had these problems:\n- ' + problems.join('\n- ') : '') + '\nSend a corrected, complete spec. Say nothing else unless it fails again.');
+	lastAgentGoal = keep;   // Retry/Continue on the response bar still mean the user's own goal
+}
+
+/**
+ * The chat could not load its renderer. The fallback the spec asks for: "an ASCII rendering generated
+ * from the same spec, so the model never has to draw ASCII itself" — made here, from the host's own
+ * record, by the same layout. Empty when there is nothing to draw; the chat then keeps the source open.
+ */
+function diagramAsciiText(id, cols) {
+	const record = diagrams.get(id);
+	if (!record || !record.spec) { return ''; }
+	// How wide the chat's card is, in characters — the one thing the page knows and the host does not.
+	// A number, bounded; anything else is the default.
+	const maxCols = Math.max(40, Math.min(200, Math.floor(Number(cols)) || 110));
+	// (Every spec the service holds has passed the validator — drawn this session, or checked on load.)
+	try { return diagramAscii.render(record.spec, { maxCols, title: false }); }   // the card already shows the title
+	catch (e) {
+		dbg('diagram.ascii.error', { msg: String((e && e.message) || e) });
+		try { return diagramText.outline(record.spec).text; } catch (e2) { return ''; }   // it still says what connects to what
+	}
+}
+
+/**
+ * The whole of what a diagram may ask of the editor. Each branch looks the diagram up in the host's
+ * own records by id — an id that names no record does nothing (or, for the text fallback, answers
+ * with no text) — and no branch reads a path, a URL or a command from the message.
+ */
+async function handleDiagramAction(msg) {
+	const action = String((msg && msg.action) || '');
+	const id = String((msg && msg.id) || '');
+	if (action === 'openLink') { await openDiagramLink(id, msg.node); }
+	else if (action === 'export') { await exportDiagram(id, msg.format, msg.data); }
+	else if (action === 'retry') { await retryDiagram(id); }
+	else if (action === 'ascii') { post({ type: 'diagramAscii', id, text: diagramAsciiText(id, msg.cols) }); }
+}
+
+/** "LevelCode: AI: Diagram Statistics" — the numbers the rollout gates are read from. */
+async function showDiagramStats() {
+	const summary = diagramStats.summarize(diagramStatsNow());
+	const doc = await vscode.workspace.openTextDocument({ language: 'json', content: JSON.stringify({
+		note: 'Local counters for rich diagrams (docs/RICH-DIAGRAMS.md, "Telemetry and evaluation"). Kept in this editor only; nothing here is sent anywhere, and nothing here is text from a diagram.',
+		summary, raw: diagramStatsNow()
+	}, null, 2) });
+	await vscode.window.showTextDocument(doc, { preview: true });
+}
+
 let _sessionsMgr = null, _sessionsSlug = null;
 function sessionsRoot() {
 	const dir = String(aiConfig().get('sessions.dir', '') || '').trim();
@@ -1347,7 +1547,12 @@ async function exportSession(id) {
 	const m = sessionsManager();
 	if (!m || !id) { return; }
 	const entry = (m.list().find((e) => e.id === id)) || {};
-	const md = sessionEvents.toMarkdown(entry, m.transcript(id), { redact: sessionMemory.redactSecrets });
+	const md = sessionEvents.toMarkdown(entry, m.transcript(id), {
+		redact: sessionMemory.redactSecrets,
+		// A diagram the session drew is exported as a Mermaid block, which a pull request renders.
+		diagrams: m.diagrams(id),
+		diagram: (r) => ({ lang: 'mermaid', body: diagramText.toMermaid(r.spec) })
+	});
 
 	try { await vscode.env.clipboard.writeText(md); }
 	catch (e) {
@@ -1399,9 +1604,15 @@ async function resumeSession(id) {
 	// note so the model KNOWS earlier turns exist (a real head-summary is a later refinement) — the user
 	// still sees the whole transcript in the replay. Ephemeral: never persisted (recordTurn appends only
 	// new turns from the goal onward).
+	// The session's diagrams come back exactly as stored — never re-validated, never re-repaired.
+	diagrams.load(r.diagrams);
+	const omittedHead = (r.plan && r.plan.tier > 1) ? (Array.isArray(r.full) ? r.full : []).slice(0, Math.max(0, (Array.isArray(r.full) ? r.full.length : 0) - agentMessages.length)) : [];
+	const lostDiagrams = diagrams.stubsFor(omittedHead);
+	diagramsStubbed = lostDiagrams.length > 0;
 	if (r.plan && r.plan.tier > 1) {
 		const omitted = Math.max(0, (Array.isArray(r.full) ? r.full.length : 0) - agentMessages.length);
-		agentMessages.unshift({ role: 'user', content: '[Resumed session — the earlier part of this conversation (' + omitted + ' message' + (omitted === 1 ? '' : 's') + ') was omitted to fit the context window. It is shown above in the transcript but not included here; ask if you need details from it.]' });
+		agentMessages.unshift({ role: 'user', content: '[Resumed session — the earlier part of this conversation (' + omitted + ' message' + (omitted === 1 ? '' : 's') + ') was omitted to fit the context window. It is shown above in the transcript but not included here; ask if you need details from it.'
+			+ (lostDiagrams.length ? '\nDiagrams drawn in that part (call get_diagram with the id before editing one):\n- ' + lostDiagrams.join('\n- ') : '') + ']' });
 	}
 	conversation = [];
 	checkpoints.length = 0; currentCheckpoint = null;                       // old file-snapshots can't be restored
@@ -1479,6 +1690,8 @@ function resetConversationState() {
 	clearQuestions();
 	conversation = [];
 	agentMessages = [];
+	diagrams.reset();                      // the next conversation starts at d-1, owing nothing
+	diagramsStubbed = false;
 	checkpoints.length = 0; currentCheckpoint = null;   // drop the per-turn restore stack
 	pendingContext = null;
 	contextFiles = [];
@@ -1849,6 +2062,8 @@ function serializeMsgForSummary(m) {
 	const parts = [];
 	for (const c of m.content) {
 		if (c.type === 'text' && c.text) { parts.push(c.text.slice(0, 4000)); }
+		// A diagram's spec is structure the summarizer cannot use and should not pay for: one line.
+		else if (c.type === 'tool_use' && c.name === diagramTool.RENDER_DIAGRAM.name) { parts.push('[draws a diagram: ' + String((c.input && c.input.title) || 'untitled').slice(0, 120) + ']'); }
 		else if (c.type === 'tool_use') { parts.push('[calls ' + c.name + ' ' + JSON.stringify(c.input || {}).slice(0, 400) + ']'); }
 		else if (c.type === 'tool_result') { const t = typeof c.content === 'string' ? c.content : JSON.stringify(c.content); parts.push('[tool result: ' + String(t).slice(0, 800) + ']'); }
 	}
@@ -1920,10 +2135,18 @@ async function compactAgentMemory() {
 	// is unharmed and the user can compact again once the turn ends.
 	if (agentMessages !== msgs || msgs[cut] !== anchor || abort) { dbg('compact.stale', { cut, running: !!abort }); return { ok: false, reason: 'changed' }; }
 
+	// Rich diagrams: the specs in the head are about to leave the conversation. Each is replaced by a
+	// one-line stub (the full spec stays on file; get_diagram fetches it). This is the ONLY place a
+	// spec is stubbed — at compaction, never turn by turn — so the cached prefix is rebuilt once, here,
+	// along with everything else this splice already invalidates.
+	const stubs = diagrams.stubsFor(msgs.slice(0, cut));
+	if (stubs.length) { diagramsStubbed = true; }
+	const stubNote = stubs.length ? '\n\nDiagrams drawn earlier (their specs are no longer in this conversation — call get_diagram with the id before editing one):\n- ' + stubs.join('\n- ') : '';
+
 	// Replace the head with [summary(user) → ack(assistant)]; the kept tail begins with the user goal at
 	// `cut`, so role alternation (user → assistant → user …) holds across the seam.
 	msgs.splice(0, cut,
-		{ role: 'user', content: '[Summary of the earlier conversation, compacted to save context]\n\n' + summary.trim() },
+		{ role: 'user', content: '[Summary of the earlier conversation, compacted to save context]\n\n' + summary.trim() + stubNote },
 		{ role: 'assistant', content: 'Got it — I have that summary of the work so far and will continue from here.' }
 	);
 	// Drop checkpoints whose goal message was summarized away: restoreCheckpoint can no longer truncate the
@@ -2026,6 +2249,12 @@ async function agentFlow(text, imageBlocks) {
 			sessionExpiredMessage: session.SESSION_EXPIRED_MESSAGE,
 			skills: skillsObj,                  // M6.5: implicit skills (name+desc menu in SYSTEM + use_skill resolver)
 			projectMemory: projectMemoryMarkdown(), // cross-session memory: a verify-first digest of past sessions, injected like project rules
+			// Rich diagrams: what this surface can show, and the service that draws. An `ascii` client is
+			// offered neither the tool nor its rules; `diagramsStubbed` adds get_diagram once a spec has
+			// left the conversation.
+			client: { render: clientRender(req.providerId, capsModel(req.model)) },
+			diagrams: diagrams,
+			diagramsStubbed: diagramsStubbed,
 			// The recall_sessions tool: search past-session outcomes on demand. Off → the tool isn't offered at all.
 			recallSessions: (aiConfig().get('sessions.memory.enabled', true) && aiConfig().get('sessions.memory.recallTool', true)) ? recallSessionsTool : undefined,
 
@@ -2073,7 +2302,9 @@ async function agentFlow(text, imageBlocks) {
 		// into the chat, and never re-throws past this turn's own error.
 		try {
 			const m = sessionsManager();
-			if (m && sessTurnStart >= 0) { m.recordTurn(agentMessages.slice(sessTurnStart), req.model); }
+			// The diagrams drawn this turn are stored with it, as rendered — so reopening the session
+			// replays the same pictures without running the repair ladder again.
+			if (m && sessTurnStart >= 0) { m.recordTurn(agentMessages.slice(sessTurnStart), req.model, { diagrams: diagrams.takeNew() }); }
 		} catch (e) { dbg('sessions.record.error', { msg: String((e && e.message) || e) }); }
 	}
 }
@@ -2882,6 +3113,10 @@ class ChatViewProvider {
 				case 'sessionAction': await handleSessionAction(msg.action, msg.id); break;
 				case 'feedback': dbg('feedback', { value: msg.value, model: msg.model }); await recordFeedback(msg.value, msg.model); break;
 				case 'openFile': await openWorkspaceFile(msg.path); break;
+				// Rich diagrams: the only two things a diagram can ask the editor for are to open a node's
+				// file and to export itself (plus the user's own Retry). Nothing else is routed.
+				case 'diagramAction': await handleDiagramAction(msg); break;
+				case 'diagramRendered': recordDiagramStat({ type: 'render', ok: msg.ok !== false, ms: Number(msg.ms), flipped: !!msg.flipped }); if (msg.ok === false) { dbg('diagram.render.failed', { message: String(msg.message || '').slice(0, 200) }); } break;
 				case 'reviewKeepFile': dbg('review.keep', { id: msg.id }); review.keepFile(msg.id, 'kept'); break;
 				case 'reviewUndoFile': dbg('review.undo', { id: msg.id }); await review.undoFile(msg.id); break;
 				case 'reviewKeepAll': review.keepAll(); break;
@@ -3026,7 +3261,7 @@ function replayLiveTranscript(tag) {
 	const id = m.liveId();
 	if (!id) { return; }                       // nothing said yet — an empty chat is the honest state
 	let turns = [];
-	try { turns = sessionEvents.toDisplayTurns(m.transcript(id)); }
+	try { turns = sessionEvents.toDisplayTurns(m.transcript(id), m.diagrams(id)); }
 	catch (e) { dbg('chat.replay.failed', { msg: String((e && e.message) || e) }); return; }
 	if (!turns.length) { return; }
 	const entry = m.list().find((e) => e.id === id) || {};
@@ -3056,7 +3291,11 @@ function webviewCsp() {
 
 function getHtml() {
 	const { nonce, csp } = webviewCsp();
-	const html = fs.readFileSync(path.join(ctx.extensionPath, 'media', 'chat.html'), 'utf8');
+	let html = fs.readFileSync(path.join(ctx.extensionPath, 'media', 'chat.html'), 'utf8');
+	// Rich diagrams: the renderer is the host's own modules, inlined under this page's nonce — the CSP
+	// above is unchanged, and the page still loads nothing from anywhere. If the bundle cannot be
+	// built the placeholders stay as the comments they are, and the chat falls back to showing source.
+	try { html = diagramBundle.inject(html); } catch (e) { dbg('diagram.bundle.failed', { msg: String((e && e.message) || e) }); }
 	return html.replace(/__CSP__/g, csp).replace(/__NONCE__/g, nonce);
 }
 
@@ -3426,6 +3665,7 @@ function activate(context) {
 		}),
 		vscode.commands.registerCommand('levelcode.import.vscode', () => importFromVscode(context)),
 		vscode.commands.registerCommand('levelcode.ai.newChat', newChat),
+		vscode.commands.registerCommand('levelcode.ai.diagramStats', showDiagramStats),
 		vscode.commands.registerCommand('levelcode.ai.pickModel', pickModel),
 		vscode.commands.registerCommand('levelcode.ai.manageMcp', manageMcpServers),
 		// Wrapped, NOT passed by reference: a menu invocation hands the command its context as the first
diff --git a/extensions/levelcode-ai/media/chat.html b/extensions/levelcode-ai/media/chat.html
index 8c59bf6..dd74a23 100644
--- a/extensions/levelcode-ai/media/chat.html
+++ b/extensions/levelcode-ai/media/chat.html
@@ -1402,6 +1402,81 @@
   .sesscard.pinned [data-act="pin"] { color: var(--cc-accent); border-color: color-mix(in srgb, var(--cc-accent) 45%, var(--cc-line)); }
   .sesscard .ci { width: 14px; height: 14px; }
   @media (prefers-reduced-motion: reduce) { .sesscard { transition: none; } .sesscard:hover, .sesscard:focus-visible, .sesscard:focus-within { transform: none; } }
+  /* ---- rich diagrams (docs/RICH-DIAGRAMS.md) ---------------------------------------------------
+     Two layers, kept apart on purpose.
+     INSIDE the picture: every rule comes from diagram/theme.js — the one module that owns the house
+     style — and is injected over the placeholder below when the page is built. Colours there are
+     editor theme tokens, so switching theme restyles a diagram already on screen; nothing is baked in.
+     AROUND the picture: the card chrome that follows (title, badge, banner, toolbar, placeholder,
+     full-size view). That part is ordinary chat UI and uses the same variables as everything else. */
+  /*__LCD_CSS__*/
+  .lcd { margin: 6px 0 2px; padding: 0; min-width: 0; }
+  .lcd-head { display: flex; align-items: baseline; flex-wrap: wrap; gap: 4px 8px; margin: 0 0 8px; }
+  /* "Title: rendered above the diagram, left-aligned" — and at the title size of the type scale. */
+  .lcd-title-text { font-size: 15px; font-weight: 600; line-height: 20px; color: var(--vscode-foreground); text-wrap: balance; }
+  .lcd-badge {
+    cursor: pointer; font: inherit; font-size: 10.5px; line-height: 1.5; padding: 0 7px; white-space: nowrap;
+    border: 1px solid var(--border); border-radius: 999px; background: transparent; color: var(--muted);
+  }
+  .lcd-badge:hover, .lcd-badge[aria-expanded="true"] { color: var(--vscode-foreground); background: var(--vscode-toolbar-hoverBackground, rgba(127,127,127,.18)); }
+  .lcd-badge:focus-visible, .lcd-btn:focus-visible { outline: 1px solid var(--accent); outline-offset: 1px; }
+  .lcd-pop { margin: 0 0 8px; padding: 6px 9px; font-size: 11.5px; line-height: 1.5; color: var(--muted); border: 1px solid var(--border); border-radius: 6px; overflow-wrap: anywhere; }
+  .lcd-pop[hidden] { display: none; }
+  .lcd-pop div + div { margin-top: 3px; }
+  /* A degraded diagram says what it lost — in the same warning voice the composer uses. */
+  .lcd-banner {
+    display: flex; align-items: center; flex-wrap: wrap; gap: 6px 10px; margin: 0 0 8px; padding: 5px 8px;
+    font-size: 11.5px; line-height: 1.45; border-radius: 6px;
+    color: var(--vscode-inputValidation-warningForeground, var(--vscode-foreground));
+    background: var(--vscode-inputValidation-warningBackground, rgba(224,160,48,.14));
+    border: 1px solid var(--vscode-inputValidation-warningBorder, rgba(224,160,48,.45));
+  }
+  .lcd-banner-text { flex: 1 1 12em; min-width: 0; }
+  .lcd-stage { cursor: zoom-in; border-radius: 8px; outline-offset: 3px; }
+  .lcd-stage:focus-visible { outline: 1px solid var(--accent); }
+  /* "Never wider than the chat column": the picture is laid out to fit, and scales down if the column narrows. */
+  .lcd-stage svg { display: block; max-width: 100%; height: auto; }
+  .lcd-btn {
+    cursor: pointer; font: inherit; font-size: 11px; line-height: 1.4; padding: 2px 8px;
+    border: 1px solid var(--border); border-radius: 6px; background: transparent; color: var(--muted);
+    transition: color .12s, background .12s;
+  }
+  .lcd-btn:hover { color: var(--vscode-foreground); background: var(--vscode-toolbar-hoverBackground, rgba(127,127,127,.18)); }
+  .lcd-btn.done { color: var(--vscode-gitDecoration-addedResourceForeground, #73c991); border-color: var(--vscode-gitDecoration-addedResourceForeground, #73c991); }
+  .lcd-banner .lcd-btn { color: inherit; border-color: currentColor; opacity: .85; }
+  .lcd-banner .lcd-btn:hover { opacity: 1; }
+  /* The toolbar is revealed on hover or keyboard focus, like the Copy button under an answer. */
+  .lcd-tools { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 7px; opacity: 0; transition: opacity .12s; }
+  .lcd:hover .lcd-tools, .lcd:focus-within .lcd-tools { opacity: 1; }
+  @media (hover: none) { .lcd-tools { opacity: 1; } }
+  /* The placeholder that holds a diagram's place while its spec streams in. */
+  .lcd-pending .lcd-title-text { color: var(--muted); }
+  .lcd-skel {
+    display: flex; align-items: center; gap: 10px; height: 64px; padding: 0 14px;
+    border: 1px dashed var(--border); border-radius: 8px; color: var(--muted); font-size: 11.5px;
+  }
+  .lcd-skel-bar {
+    flex: 0 0 72px; height: 3px; border-radius: 2px;
+    background: linear-gradient(90deg, rgba(127,127,127,.14) 25%, rgba(127,127,127,.42) 37%, rgba(127,127,127,.14) 63%);
+    background-size: 300% 100%; animation: imgskel 1.1s ease-in-out infinite;
+  }
+  @media (prefers-reduced-motion: reduce) { .lcd-skel-bar { animation: none; } .lcd-tools, .lcd-btn { transition: none; } }
+  /* The fallbacks: an ASCII drawing when the picture cannot be rendered, the source when nothing can. */
+  .lcd-ascii pre, .lcd-source pre { overflow-x: auto; white-space: pre; font-family: var(--vscode-editor-font-family, ui-monospace, monospace); font-size: 12px; line-height: 1.25; }
+  .lcd-errors { margin: 0 0 8px; padding-left: 18px; font-size: 11.5px; line-height: 1.5; color: var(--muted); overflow-wrap: anywhere; }
+  .lcd-source summary { cursor: pointer; font-size: 11.5px; color: var(--muted); margin-bottom: 6px; }
+  /* The text outline a screen reader gets. Out of sight, never out of the accessibility tree —
+     the same treatment, and the same reason, as `.msg .role`. */
+  .lcd-sr { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }
+  /* Full-size view: zoom, pan, fit. */
+  #lcdZoom { position: fixed; inset: 0; z-index: 60; display: flex; flex-direction: column; background: var(--vscode-editor-background, #1e1e1e); }
+  #lcdZoom[hidden] { display: none; }
+  .lcdz-bar { display: flex; align-items: center; gap: 6px; padding: 8px 12px; border-bottom: 1px solid var(--border); font-size: 12px; }
+  .lcdz-title { font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; }
+  .lcdz-sp { flex: 1; }
+  .lcdz-view { flex: 1; position: relative; overflow: hidden; cursor: grab; touch-action: none; }
+  .lcdz-view.dragging { cursor: grabbing; }
+  .lcdz-view svg { position: absolute; left: 0; top: 0; max-width: none; transform-origin: 0 0; }
 </style>
 </head>
 <body>
@@ -1445,6 +1520,18 @@
 
   <div id="imgzoom" hidden role="dialog" aria-modal="true" aria-label="Attached image"><img alt=""></div>
 
+  <div id="lcdZoom" hidden role="dialog" aria-modal="true" aria-label="Diagram, full size">
+    <div class="lcdz-bar">
+      <span class="lcdz-title"></span><span class="lcdz-sp"></span>
+      <button class="lcd-btn" type="button" data-z="out" title="Zoom out (−)" aria-label="Zoom out">&minus;</button>
+      <button class="lcd-btn" type="button" data-z="in" title="Zoom in (+)" aria-label="Zoom in">+</button>
+      <button class="lcd-btn" type="button" data-z="fit" title="Fit to the window (0)">Fit</button>
+      <button class="lcd-btn" type="button" data-z="one" title="Actual size (1)">100%</button>
+      <button class="lcd-btn" type="button" data-z="close" title="Close (Esc)" aria-label="Close">&#10005;</button>
+    </div>
+    <div class="lcdz-view lcd"></div>
+  </div>
+
   <div id="composer">
     <div id="chips"></div>
     <div id="imgnote" role="status" aria-live="polite" hidden></div>
@@ -1541,6 +1628,10 @@
     </div>
   </div>
 
+<!-- Rich diagrams: the host's own diagram modules (extensions/levelcode-ai/diagram/*.js), inlined when the
+     page is built. Same nonce, same CSP, nothing fetched. If this block is empty the chat shows a
+     diagram's source instead of a picture. -->
+<script nonce="__NONCE__">/*__LCD_JS__*/</script>
 <script nonce="__NONCE__">
   const vscode = acquireVsCodeApi();
   window.onerror = function(msg){
@@ -4177,6 +4268,8 @@
     log.appendChild(banner);
     turnLabeled = false;
     for (const t of (Array.isArray(m.turns) ? m.turns : [])){
+      // A diagram comes back as the record that was stored — drawn again, never repaired again.
+      if (t.role === 'diagram'){ lcdShow({ key: t.key, record: t.record }); continue; }
       add(t.role, t.role === 'user' ? esc(t.text) : render(t.text));
     }
     forceStick();
@@ -4201,6 +4294,369 @@
     document.addEventListener('keydown', (e) => { const o = document.getElementById('sessOverlay'); if (e.key === 'Escape' && o && o.style.display !== 'none'){ e.preventDefault(); closeSessions(); } });
   })();
 
+
+  // ── Rich diagrams (docs/RICH-DIAGRAMS.md) ────────────────────────────────────────────────────────
+  // The host validates a spec and posts the record; this draws it. Layout and painting are the host's
+  // own modules (the files under diagram/, inlined above as LCDiagram) — the chat adds the two things only it
+  // has: the real font to measure text with, and the live theme to paint with.
+  //
+  // SAFETY, in one place: a label reaches the page through LCDiagram.scene.mount(), which creates
+  // SVG elements from a fixed allow-list and sets text with textContent. The card chrome below is
+  // built with createElement + textContent too. Nothing from a spec is ever assigned to innerHTML.
+  const LCD = window.LCDiagram || null;   // null if the modules did not load → the host's text version is shown instead
+  const lcdCards = {};                    // tool-call key → the card that shows (or will show) that diagram
+  let lcdSeq = 0;
+  const lcdCtx = (function(){ try { return document.createElement('canvas').getContext('2d'); } catch (e) { return null; } })();
+  function lcdFont(){ try { return getComputedStyle(document.body).fontFamily || 'sans-serif'; } catch (e) { return 'sans-serif'; } }
+  /** Text width in the diagram's own type. "Width from the MEASURED longest line plus 24." */
+  function lcdMeasure(text, role){
+    const T = LCD.theme.TYPE[role] || LCD.theme.TYPE.sub;
+    if (lcdCtx){
+      lcdCtx.font = T.weight + ' ' + T.size + 'px ' + lcdFont();
+      // A font string the canvas cannot parse leaves it on its previous font — measuring with that
+      // would size every box for the wrong type. Only trust the canvas if it took the size we asked for.
+      if (String(lcdCtx.font).indexOf(T.size + 'px') >= 0){ return Math.ceil(lcdCtx.measureText(String(text)).width * 10) / 10 + 0.6; }
+    }
+    return LCD.theme.approxMeasure(text, role);
+  }
+  function lcdEl(tag, cls, text){ const e = document.createElement(tag); if (cls){ e.className = cls; } if (text != null){ e.textContent = text; } return e; }
+  function lcdBtn(label, title, fn){ const b = lcdEl('button', 'lcd-btn', label); b.type = 'button'; if (title){ b.title = title; } b.onclick = fn; return b; }
+  function lcdFlash(btn, label){ const was = btn.textContent; btn.textContent = label; btn.classList.add('done'); setTimeout(function(){ btn.textContent = was; btn.classList.remove('done'); }, 1200); }
+  function lcdAct(id, action, extra){ vscode.postMessage(Object.assign({ type: 'diagramAction', action: action, id: id }, extra || {})); }
+  /** How many characters of the fallback's monospaced block fit across the card (it is set in 12px). */
+  function lcdCols(card){
+    let cw = 7.3;
+    try {
+      if (lcdCtx){
+        lcdCtx.font = '12px ' + (getComputedStyle(document.body).getPropertyValue('--vscode-editor-font-family') || 'monospace');
+        const w = lcdCtx.measureText('0000000000').width / 10;
+        if (String(lcdCtx.font).indexOf('12px') >= 0 && w > 3 && w < 20){ cw = w; }
+      }
+    } catch (e) { /* keep the estimate */ }
+    return Math.max(40, Math.min(200, Math.floor((lcdAvail(card) - 30) / cw)));
+  }
+  /** How wide the picture may be: the card's own column. */
+  function lcdAvail(card){ const w = card.clientWidth || (log.clientWidth - 48); return w > 0 ? Math.max(240, Math.floor(w)) : 0; }
+  /** A new card, in the assistant's own column, at the point in the answer the model reached. */
+  function lcdHost(key){
+    finishAgentBubble();
+    const body = add('assistant', '');
+    const card = lcdEl('figure', 'lcd');
+    card.dataset.key = key;
+    body.appendChild(card);
+    lcdCards[key] = card;
+    return card;
+  }
+  /** The placeholder: holds the diagram's place from the moment the model starts writing its spec. */
+  function lcdPending(m){
+    if (!m || !m.key){ return; }
+    let card = lcdCards[m.key];
+    if (card && !card.isConnected){ card = null; }
+    if (!card){
+      // The model's repair call takes over the placeholder of the diagram it is repairing.
+      const waiting = Object.keys(lcdCards).map(function(k){ return lcdCards[k]; }).find(function(c){ return c.isConnected && c.dataset.state === 'repairing'; });
+      if (waiting){ card = waiting; lcdCards[m.key] = card; } else { card = lcdHost(m.key); }
+    }
+    if (card.dataset.id){ return; }   // already drawn: a late placeholder must never blank a picture
+    const repairing = m.state === 'repairing' || card.dataset.state === 'repairing';
+    const title = m.title || card.dataset.title || '';
+    card.className = 'lcd lcd-pending';
+    card.dataset.state = repairing ? 'repairing' : 'drawing';
+    card.dataset.title = title;
+    card.setAttribute('role', 'status'); card.setAttribute('aria-live', 'polite');
+    card.textContent = '';
+    const head = lcdEl('div', 'lcd-head'); head.appendChild(lcdEl('span', 'lcd-title-text', title || 'Diagram')); card.appendChild(head);
+    const skel = lcdEl('div', 'lcd-skel');
+    const bar = lcdEl('span', 'lcd-skel-bar'); bar.setAttribute('aria-hidden', 'true'); skel.appendChild(bar);
+    skel.appendChild(lcdEl('span', 'lcd-skel-text', repairing ? 'Fixing the diagram…' : 'Drawing…'));
+    card.appendChild(skel);
+    scrollIfStuck();
+  }
+  /** A finished record from the host: fill the placeholder that was waiting for it, or make a card. */
+  function lcdShow(m){
+    const record = m && m.record; if (!record || !record.id){ return; }
+    const key = m.key || record.key || record.id;
+    let card = lcdCards[key] || (m.replacesKey ? lcdCards[m.replacesKey] : null);
+    if (card && !card.isConnected){ card = null; }
+    if (!card){ card = lcdHost(key); }
+    lcdCards[key] = card;
+    lcdDraw(card, record, false);
+    scrollIfStuck();
+  }
+  /** A details list that a badge or a banner button opens. */
+  function lcdPop(lines){
+    const pop = lcdEl('div', 'lcd-pop'); pop.hidden = true;
+    lines.forEach(function(l){ pop.appendChild(lcdEl('div', '', l)); });
+    return pop;
+  }
+  function lcdToggle(btn, pop){ btn.setAttribute('aria-expanded', 'false'); btn.onclick = function(){ pop.hidden = !pop.hidden; btn.setAttribute('aria-expanded', String(!pop.hidden)); }; }
+  function lcdDraw(card, record, quiet){
+    card.className = 'lcd'; card.textContent = '';
+    card.dataset.id = record.id; card.dataset.status = record.status;
+    delete card.dataset.state; card.removeAttribute('aria-live'); card.setAttribute('role', 'group');
+    card._record = record; card._spec = null; card._geo = null;
+    let spec = null, late = [];
+    if (record.spec && LCD){
+      // The renderer's own last check: whatever sent this record, nothing reaches layout unvalidated.
+      try { const a = LCD.repair.accept(record.spec); if (a.ok){ spec = a.spec; late = a.notes || []; } } catch (e) { spec = null; }
+    }
+    const title = (spec && spec.title) || (record.spec && record.spec.title) || record.title || 'Diagram';
+    card.setAttribute('aria-label', 'Diagram: ' + title);
+    const head = lcdEl('figcaption', 'lcd-head');
+    const tt = lcdEl('span', 'lcd-title-text', title); if (spec && spec.tip){ tt.title = spec.tip; }
+    head.appendChild(tt); card.appendChild(head);
+    if (!spec){
+      if (record.spec && !LCD && !quiet){ vscode.postMessage({ type: 'diagramRendered', id: record.id, ok: false, message: 'the diagram renderer did not load' }); }
+      lcdFailed(card, record);
+      return;
+    }
+
+    const notes = (record.notes || []).concat(late), fixes = record.fixes || [];
+    if (record.status === 'degraded' || late.length){
+      // Degraded: say what was lost, where it cannot be missed, and offer another go.
+      const ban = lcdEl('div', 'lcd-banner'); ban.setAttribute('role', 'note');
+      ban.appendChild(lcdEl('span', 'lcd-banner-text', notes.join(' · ') || 'Drawn without the parts that were not valid.'));
+      const lines = (record.errors || []).concat(fixes);
+      const pop = lcdPop(lines);
+      if (lines.length){ const d = lcdBtn('Details', 'What was wrong with the spec', null); lcdToggle(d, pop); ban.appendChild(d); }
+      ban.appendChild(lcdBtn('Retry', 'Ask for this diagram again', function(){ lcdAct(record.id, 'retry'); }));
+      card.appendChild(ban); card.appendChild(pop);
+    } else if (fixes.length || record.repaired){
+      // Auto-fixed: quiet, and one click from the detail.
+      const badge = lcdEl('button', 'lcd-badge', 'auto-fixed' + (notes.length ? ' · ' + notes[0] : '')); badge.type = 'button';
+      badge.title = 'This diagram needed a fix before it could be drawn. Click for details.';
+      const pop = lcdPop(fixes.length ? fixes : ['The first attempt was not valid; the model corrected it.']);
+      lcdToggle(badge, pop);
+      head.appendChild(badge); card.appendChild(pop);
+    }
+
+    const stage = lcdEl('div', 'lcd-stage'); card.appendChild(stage);
+    const t0 = performance.now();
+    try {
+      const avail = lcdAvail(card);
+      const geo = LCD.layout.layout(spec, { measure: lcdMeasure, maxWidth: avail || undefined });
+      const svg = LCD.scene.mount(LCD.scene.build(spec, geo, {}), document);
+      const descId = 'lcd-desc-' + (++lcdSeq);
+      svg.setAttribute('aria-describedby', descId);
+      stage.appendChild(svg);
+      stage.tabIndex = 0; stage.setAttribute('role', 'button'); stage.setAttribute('aria-label', 'Open the diagram full size'); stage.title = 'Click to open full size';
+      const desc = lcdEl('p', 'lcd-sr', LCD.text.outline(spec).text); desc.id = descId; card.appendChild(desc);
+      card._spec = spec; card._geo = geo;
+      card.appendChild(lcdTools(card, record, false));
+      if (!quiet){ vscode.postMessage({ type: 'diagramRendered', id: record.id, ok: true, ms: Math.round((performance.now() - t0) * 10) / 10, flipped: !!geo.flipped }); }
+    } catch (e) {
+      // Rendering is unavailable. The fallback is an ASCII drawing generated from the same spec —
+      // by the editor, in a monospaced block — so the model never has to draw one itself.
+      stage.className = 'lcd-ascii'; stage.textContent = '';
+      // Say so: an unexplained character drawing looks like the model's doing, and it is not.
+      const why = lcdEl('div', 'lcd-banner'); why.setAttribute('role', 'note');
+      why.appendChild(lcdEl('span', 'lcd-banner-text', 'The picture could not be drawn, so a text version is shown instead.'));
+      card.insertBefore(why, stage);
+      const pre = lcdEl('pre');
+      try { pre.textContent = LCD.ascii.render(spec, { maxCols: lcdCols(card), title: false }); } catch (e2) { pre.textContent = LCD.text.toSource(spec); }
+      stage.appendChild(pre);
+      card._spec = spec;
+      card.appendChild(lcdTools(card, record, true));
+      if (!quiet){ vscode.postMessage({ type: 'diagramRendered', id: record.id, ok: false, message: String((e && e.message) || e) }); }
+    }
+  }
+  /** Nothing drawable: the errors, the source, and a way out. Never a blank space. */
+  function lcdFailed(card, record){
+    card.dataset.status = 'failed';
+    const ban = lcdEl('div', 'lcd-banner'); ban.setAttribute('role', 'note');
+    // No renderer on this side (the modules did not load): the spec is fine, the page is not. The
+    // fallback is the same diagram drawn with characters — by the host, from its own record.
+    const noRenderer = !!(record.spec && !LCD);
+    // A degraded diagram still says what it lost, whichever way it ends up being shown.
+    const lost = noRenderer && (record.notes || []).length ? ' ' + record.notes.join(' · ') : '';
+    ban.appendChild(lcdEl('span', 'lcd-banner-text', noRenderer ? 'The diagram renderer did not load, so a text version is shown instead.' + lost : 'This diagram could not be drawn.'));
+    if (!noRenderer){ ban.appendChild(lcdBtn('Retry', 'Ask for this diagram again', function(){ lcdAct(record.id, 'retry'); })); }
+    card.appendChild(ban);
+    if (noRenderer){
+      const stage = lcdEl('div', 'lcd-ascii'); stage.hidden = true;
+      card._asciiPre = lcdEl('pre'); stage.appendChild(card._asciiPre); card.appendChild(stage);
+      lcdAct(record.id, 'ascii', { cols: lcdCols(card) });
+    }
+    const errs = record.errors || [];
+    if (errs.length){ const ul = lcdEl('ul', 'lcd-errors'); errs.forEach(function(l){ ul.appendChild(lcdEl('li', '', l)); }); card.appendChild(ul); }
+    let source = record.source || '';
+    if (!source && record.spec){ try { source = JSON.stringify(record.spec, null, 2); } catch (e) { source = ''; } }
+    if (source){
+      const det = lcdEl('details', 'lcd-source'); det.open = !errs.length;
+      det.appendChild(lcdEl('summary', '', 'What was sent'));
+      det.appendChild(lcdEl('pre', '', source));
+      card.appendChild(det);
+      const bar = lcdEl('div', 'lcd-tools');
+      const copy = lcdBtn('Copy source', 'Copy what the model sent', function(){ vscode.postMessage({ type: 'copy', text: source }); lcdFlash(copy, 'Copied'); });
+      bar.appendChild(copy); card.appendChild(bar);
+    }
+  }
+  /** The colours on screen right now, as plain values — the only moment a colour is baked in. */
+  function lcdResolved(card){
+    const probe = lcdEl('span'); probe.style.display = 'none'; card.appendChild(probe);
+    const out = {};
+    LCD.theme.TOKEN_NAMES.forEach(function(name){
+      if (name === 'font'){ out.font = lcdFont(); return; }
+      probe.style.color = 'var(--lcd-' + name + ')';
+      let c = getComputedStyle(probe).color;
+      // A canvas normalises any CSS colour (color-mix results included) to #rrggbb or rgba().
+      if (lcdCtx){ lcdCtx.fillStyle = '#000000'; lcdCtx.fillStyle = c; c = lcdCtx.fillStyle; }
+      out[name] = c;
+    });
+    probe.remove();
+    return out;
+  }
+  /** The diagram as a standalone SVG file: same tree as on screen, plus its title, background and colours. */
+  function lcdSvg(card){
+    const vnode = LCD.scene.build(card._spec, card._geo, { title: true, background: true, standalone: true, measure: lcdMeasure, css: LCD.theme.css({ resolved: lcdResolved(card) }) });
+    return { text: LCD.scene.toSvg(vnode), width: vnode.width, height: vnode.height };
+  }
+  function lcdPng(card){
+    return new Promise(function(resolve, reject){
+      const svg = lcdSvg(card);
+      const img = new Image();
+      img.onload = function(){
+        try {
+          const scale = 2, c = document.createElement('canvas');
+          c.width = Math.ceil(svg.width * scale); c.height = Math.ceil(svg.height * scale);
+          const g = c.getContext('2d'); g.scale(scale, scale); g.drawImage(img, 0, 0, svg.width, svg.height);
+          resolve(c.toDataURL('image/png').replace(/^data:image\/png;base64,/, ''));
+        } catch (e) { reject(e); }
+      };
+      img.onerror = function(){ reject(new Error('the picture could not be turned into an image')); };
+      img.src = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(svg.text);
+    });
+  }
+  /** Copy source · SVG · PNG · Open as Mermaid · Insert into Markdown. */
+  function lcdTools(card, record, textOnly){
+    const bar = lcdEl('div', 'lcd-tools');
+    const fail = function(e){ vscode.postMessage({ type: 'notice', text: 'The diagram could not be exported: ' + String((e && e.message) || e) }); };
+    const copy = lcdBtn('Copy source', 'Copy the diagram’s spec', function(){ lcdAct(record.id, 'export', { format: 'source' }); lcdFlash(copy, 'Copied'); });
+    bar.appendChild(copy);
+    if (!textOnly){
+      bar.appendChild(lcdBtn('SVG', 'Save as an SVG image', function(){ try { lcdAct(record.id, 'export', { format: 'svg', data: lcdSvg(card).text }); } catch (e) { fail(e); } }));
+      bar.appendChild(lcdBtn('PNG', 'Save as a PNG image', function(){ lcdPng(card).then(function(b64){ lcdAct(record.id, 'export', { format: 'png', data: b64 }); }, fail); }));
+    }
+    bar.appendChild(lcdBtn('Open as Mermaid', 'Open the same diagram as Mermaid source', function(){ lcdAct(record.id, 'export', { format: 'mermaid' }); }));
+    bar.appendChild(lcdBtn('Insert into Markdown…', 'Insert it into a Markdown file in this workspace', function(){ lcdAct(record.id, 'export', { format: 'markdown' }); }));
+    return bar;
+  }
+  /** The host's answer when the renderer did not load here: the same spec, drawn with characters. */
+  function lcdAscii(m){
+    const text = String((m && m.text) || '');
+    if (!text){ return; }   // nothing to show: the source stays open
+    Object.keys(lcdCards).forEach(function(k){
+      const card = lcdCards[k];
+      if (!card._asciiPre || card.dataset.id !== String(m.id)){ return; }
+      card._asciiPre.textContent = text; card._asciiPre.parentElement.hidden = false;
+      const det = card.querySelector('details.lcd-source'); if (det){ det.open = false; }
+    });
+  }
+  /** A run ended: a placeholder that never got its picture goes (the host settles the ones it owes first). */
+  function lcdSweep(){
+    Object.keys(lcdCards).forEach(function(k){
+      const card = lcdCards[k];
+      if (card.dataset.id){ return; }
+      const body = card.parentElement, msg = body && body.parentElement;
+      card.remove(); delete lcdCards[k];
+      if (body && !body.childElementCount && !body.textContent.trim() && msg && msg.classList.contains('msg')){ msg.remove(); }
+    });
+  }
+  function lcdReset(){ Object.keys(lcdCards).forEach(function(k){ delete lcdCards[k]; }); lcdZoomClose(); }
+
+  // Full-size view: zoom about the pointer, drag to pan, fit and 100%.
+  const lcdZ = { el: document.getElementById('lcdZoom'), view: null, svg: null, card: null, k: 1, x: 0, y: 0, w: 0, h: 0, back: null };
+  lcdZ.view = lcdZ.el.querySelector('.lcdz-view');
+  function lcdZoomApply(){ if (lcdZ.svg){ lcdZ.svg.style.transform = 'translate(' + lcdZ.x + 'px,' + lcdZ.y + 'px) scale(' + lcdZ.k + ')'; } }
+  function lcdZoomFit(){
+    const r = lcdZ.view.getBoundingClientRect();
+    lcdZ.k = Math.max(0.1, Math.min((r.width - 32) / lcdZ.w, (r.height - 32) / lcdZ.h, 2));
+    lcdZ.x = (r.width - lcdZ.w * lcdZ.k) / 2; lcdZ.y = (r.height - lcdZ.h * lcdZ.k) / 2; lcdZoomApply();
+  }
+  function lcdZoomBy(f, cx, cy){
+    const k = Math.max(0.1, Math.min(8, lcdZ.k * f)), r = k / lcdZ.k;
+    lcdZ.x = cx - (cx - lcdZ.x) * r; lcdZ.y = cy - (cy - lcdZ.y) * r; lcdZ.k = k; lcdZoomApply();
+  }
+  function lcdZoomOpen(card){
+    const src = card.querySelector('.lcd-stage svg'); if (!src || !card._geo){ return; }
+    lcdZ.view.textContent = '';
+    const svg = src.cloneNode(true);
+    svg.removeAttribute('aria-describedby');
+    lcdZ.w = card._geo.width; lcdZ.h = card._geo.height; lcdZ.svg = svg; lcdZ.card = card; lcdZ.back = document.activeElement;
+    svg.style.width = lcdZ.w + 'px'; svg.style.height = lcdZ.h + 'px';
+    lcdZ.view.appendChild(svg);
+    lcdZ.el.querySelector('.lcdz-title').textContent = (card._spec && card._spec.title) || 'Diagram';
+    lcdZ.el.hidden = false;
+    lcdZoomFit();
+    const close = lcdZ.el.querySelector('[data-z="close"]'); if (close){ close.focus(); }
+  }
+  function lcdZoomClose(){
+    if (!lcdZ.el || lcdZ.el.hidden){ return; }
+    lcdZ.el.hidden = true; lcdZ.view.textContent = ''; lcdZ.svg = null; lcdZ.card = null;
+    try { if (lcdZ.back && lcdZ.back.focus){ lcdZ.back.focus(); } } catch (e) {}
+  }
+  lcdZ.el.querySelector('.lcdz-bar').addEventListener('click', function(e){
+    const b = e.target.closest && e.target.closest('[data-z]'); if (!b){ return; }
+    const r = lcdZ.view.getBoundingClientRect(), z = b.getAttribute('data-z');
+    if (z === 'close'){ lcdZoomClose(); }
+    else if (z === 'fit'){ lcdZoomFit(); }
+    else if (z === 'one'){ lcdZoomBy(1 / lcdZ.k, r.width / 2, r.height / 2); }
+    else { lcdZoomBy(z === 'in' ? 1.25 : 0.8, r.width / 2, r.height / 2); }
+  });
+  lcdZ.view.addEventListener('wheel', function(e){
+    e.preventDefault();
+    const r = lcdZ.view.getBoundingClientRect();
+    lcdZoomBy(e.deltaY < 0 ? 1.12 : 1 / 1.12, e.clientX - r.left, e.clientY - r.top);
+  }, { passive: false });
+  (function(){
+    let drag = null;
+    lcdZ.view.addEventListener('pointerdown', function(e){ drag = { x: e.clientX, y: e.clientY, moved: 0, target: e.target }; lcdZ.view.setPointerCapture(e.pointerId); lcdZ.view.classList.add('dragging'); });
+    lcdZ.view.addEventListener('pointermove', function(e){ if (!drag){ return; } const dx = e.clientX - drag.x, dy = e.clientY - drag.y; drag.moved += Math.abs(dx) + Math.abs(dy); drag.x = e.clientX; drag.y = e.clientY; lcdZ.x += dx; lcdZ.y += dy; lcdZoomApply(); });
+    lcdZ.view.addEventListener('pointerup', function(e){
+      const d = drag; drag = null; lcdZ.view.classList.remove('dragging');
+      // A press that did not travel is a click — and on a linked node, a click opens its file.
+      const link = d && d.moved < 4 && d.target && d.target.closest ? d.target.closest('[data-lc-link]') : null;
+      if (link && lcdZ.card){ lcdAct(lcdZ.card.dataset.id, 'openLink', { node: link.getAttribute('data-lc-link') }); }
+    });
+    lcdZ.view.addEventListener('pointercancel', function(){ drag = null; lcdZ.view.classList.remove('dragging'); });
+  })();
+  document.addEventListener('keydown', function(e){
+    if (lcdZ.el.hidden){ return; }
+    const r = lcdZ.view.getBoundingClientRect();
+    if (e.key === 'Escape'){ e.stopPropagation(); e.preventDefault(); lcdZoomClose(); }
+    else if (e.key === '+' || e.key === '='){ lcdZoomBy(1.25, r.width / 2, r.height / 2); }
+    else if (e.key === '-'){ lcdZoomBy(0.8, r.width / 2, r.height / 2); }
+    else if (e.key === '0'){ lcdZoomFit(); }
+    else if (e.key === '1'){ lcdZoomBy(1 / lcdZ.k, r.width / 2, r.height / 2); }
+  }, true);
+  // In the transcript: a linked node opens its file; anywhere else on the picture opens it full size.
+  // The webview only ever names the NODE — which file that means is the host's own record.
+  function lcdActivate(e){
+    const t = e.target; if (!t || !t.closest){ return false; }
+    const card = t.closest('.lcd'); if (!card || !card.dataset.id || !log.contains(card)){ return false; }
+    const link = t.closest('[data-lc-link]');
+    if (link){ lcdAct(card.dataset.id, 'openLink', { node: link.getAttribute('data-lc-link') }); return true; }
+    if (t.closest('.lcd-stage')){ lcdZoomOpen(card); return true; }
+    return false;
+  }
+  log.addEventListener('click', function(e){ if (lcdActivate(e)){ e.preventDefault(); } });
+  log.addEventListener('keydown', function(e){ if ((e.key === 'Enter' || e.key === ' ') && e.target && e.target.closest && e.target.closest('[data-lc-link], .lcd-stage') && lcdActivate(e)){ e.preventDefault(); } });
+  // The column changed width: re-lay out any diagram that would now turn (or stop needing to).
+  let lcdResizeT = null;
+  window.addEventListener('resize', function(){
+    clearTimeout(lcdResizeT);
+    lcdResizeT = setTimeout(function(){
+      if (!LCD){ return; }
+      const seen = new Set();
+      Object.keys(lcdCards).forEach(function(k){
+        const c = lcdCards[k];
+        if (seen.has(c) || !c.isConnected || !c._spec || !c._geo){ return; }
+        seen.add(c);
+        try { const g = LCD.layout.layout(c._spec, { measure: lcdMeasure, maxWidth: lcdAvail(c) || undefined }); if (g.direction !== c._geo.direction){ lcdDraw(c, c._record, true); } } catch (e) {}
+      });
+    }, 250);
+  });
+
   window.addEventListener('message', ev => {
     const m = ev.data;
     if (m.type === 'config'){
@@ -4256,6 +4712,9 @@
     else if (m.type === 'agentDelta'){ clearStatus(); setWork('Responding…'); if (!agentBubble){ agentBubble = makeStream(add('assistant', '')); agentRaw = ''; } agentRaw += m.text; streamFeed(agentBubble, agentRaw); }
     else if (m.type === 'agentTurnEnd'){ finishAgentBubble(); }
     else if (m.type === 'agentTool'){ finishAgentBubble(); addAgentLine(m.icon, m.text, m.label, m.kind, m.path); }
+    else if (m.type === 'diagramPending'){ lcdPending(m); }
+    else if (m.type === 'diagram'){ lcdShow(m); }
+    else if (m.type === 'diagramAscii'){ lcdAscii(m); }
     else if (m.type === 'agentApproval'){ addApproval(m); }
     else if (m.type === 'agentQuestions'){ addQuestions(m); }
     else if (m.type === 'termRun'){ addTermRun(m); }
@@ -4290,8 +4749,8 @@
       // then, so a card still asking them to sign in would be wrong.
       if (!m.expired && sessionCard && sessionCard.isConnected){ sessionCard.remove(); sessionCard = null; } renderAccount(m); if (m.open) openAccount(); }
     else if (m.type === 'fileIndex'){ setFileIndex(m.files || []); }
-    else if (m.type === 'agentError'){ clearStatus(); finishAgentBubble(); closeGroup(); const cap = capReachedInfo(m.message); if (isSessionExpired(m)){ addSignInCard(m); } else if (cap){ addUpgradeCard(cap); } else if (isServiceIssue(m)){ addServiceCard(m); } else { add('assistant', '<span class="err">' + esc(m.message) + '</span>'); } }
-    else if (m.type === 'agentDone'){ clearStatus(); finishAgentBubble(); addAgentDone(m.reason, m.edits, m.credits, m.maxSteps, m.costMicros); setStreaming(false); }
+    else if (m.type === 'agentError'){ clearStatus(); finishAgentBubble(); closeGroup(); lcdSweep(); const cap = capReachedInfo(m.message); if (isSessionExpired(m)){ addSignInCard(m); } else if (cap){ addUpgradeCard(cap); } else if (isServiceIssue(m)){ addServiceCard(m); } else { add('assistant', '<span class="err">' + esc(m.message) + '</span>'); } }
+    else if (m.type === 'agentDone'){ clearStatus(); finishAgentBubble(); lcdSweep(); addAgentDone(m.reason, m.edits, m.credits, m.maxSteps, m.costMicros); setStreaming(false); }
     else if (m.type === 'context'){ selLabel = m.label; renderChips(); }
     else if (m.type === 'clearContext'){ selLabel = null; renderChips(); }
     else if (m.type === 'reset'){
@@ -4301,6 +4760,7 @@
       // otherwise groupAppend() appends into a disconnected .groupbody (nothing shows), and a stale
       // turnLabeled makes the first assistant line render as an unlabeled continuation.
       curGroup = null; turnLabeled = false;
+      lcdReset();      // the cards went with the log; drop the references to them
       selLabel = null; ctxFiles = []; renderChips();
       for (const k in editCards) { delete editCards[k]; } for (const k in termCards) { delete termCards[k]; } for (const k in verifyCards) { delete verifyCards[k]; } for (const k in bgTasks) { delete bgTasks[k]; }
       for (const k in editSteps) { delete editSteps[k]; } for (const k in termSteps) { delete termSteps[k]; } for (const k in verifySteps) { delete verifySteps[k]; }   // step maps ride with their cards
diff --git a/extensions/levelcode-ai/package.json b/extensions/levelcode-ai/package.json
index ac75eee..e25a89d 100644
--- a/extensions/levelcode-ai/package.json
+++ b/extensions/levelcode-ai/package.json
@@ -124,6 +124,11 @@
         "title": "AI: Manage MCP Servers…",
         "category": "LevelCode"
       },
+      {
+        "command": "levelcode.ai.diagramStats",
+        "title": "AI: Diagram Statistics",
+        "category": "LevelCode"
+      },
       {
         "command": "levelcode.ai.openChatInEditor",
         "title": "AI: Open Chat in Editor",
@@ -486,6 +491,11 @@
           "default": false,
           "description": "Autopilot: let the agent run commands without asking, and prefer verifying its own work over pausing to ask you. It still stops and asks before anything hard to undo — deleting files, sudo, force-push / history rewrite, piping a remote script into a shell, publishing a package, or writing outside the project. File edits stay reviewable with Keep/Undo either way. Off by default."
         },
+        "levelcode.ai.diagrams.enabled": {
+          "type": "boolean",
+          "default": true,
+          "markdownDescription": "Let the agent draw diagrams in the chat. When structure is the point — a flow, an architecture, a decision tree, a state machine — the model sends a small description (nodes, edges, groups) and the editor lays it out, styles it to your theme and renders it; nodes can link to the code they describe. Turn this off and the agent is not offered the drawing tool at all: it answers in prose. Costs about 1,000 tokens of standing prompt per request while on."
+        },
         "levelcode.ai.skills.enabled": {
           "type": "boolean",
           "default": true,
diff --git a/extensions/levelcode-ai/providers/anthropic.js b/extensions/levelcode-ai/providers/anthropic.js
index cc87d78..31c2103 100644
--- a/extensions/levelcode-ai/providers/anthropic.js
+++ b/extensions/levelcode-ai/providers/anthropic.js
@@ -122,6 +122,10 @@ async function claudeAgentTurn(opts) {
  */
 function finalizeAgentBlocks(blocks) {
 	const malformed = new Set();
+	// The raw argument text of every malformed call, by id. A caller that knows a tool's input is
+	// worth a second look (a diagram spec with a trailing comma) can try a lenient parse; nothing
+	// here does, and the block itself still carries input:{}.
+	const raw = new Map();
 	const content = [];
 	for (const blk of (blocks || [])) {
 		if (!blk) { continue; }
@@ -132,8 +136,8 @@ function finalizeAgentBlocks(blocks) {
 					try {
 						const parsed = JSON.parse(blk._json);
 						if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) { input = parsed; }
-						else { input = {}; malformed.add(blk.id); }   // valid JSON but not a tool-input object
-					} catch { input = {}; malformed.add(blk.id); }    // truncated / corrupt partial JSON
+						else { input = {}; malformed.add(blk.id); raw.set(blk.id, blk._json); }   // valid JSON but not a tool-input object
+					} catch { input = {}; malformed.add(blk.id); raw.set(blk.id, blk._json); }    // truncated / corrupt partial JSON
 				} else { input = {}; }                                // genuinely no args (not "cut off")
 			}
 			content.push({ type: 'tool_use', id: blk.id, name: blk.name, input: input });
@@ -146,7 +150,7 @@ function finalizeAgentBlocks(blocks) {
 			content.push(out);
 		}
 	}
-	return { content, malformed };
+	return { content, malformed, raw };
 }
 
 /**
@@ -154,7 +158,8 @@ function finalizeAgentBlocks(blocks) {
  * and returns the full content + stop_reason for the agent loop.
  * @param {{apiKey:string, model:string, maxTokens:number, system:string,
  *          messages:any[], tools?:any[], signal?:AbortSignal, onText:(t:string)=>void,
- *          onToolStart?:(name:string)=>void}} opts
+ *          onToolStart?:(name:string, id?:string)=>void,
+ *          onToolInput?:(id:string, name:string, partialJson:string)=>void}} opts
  * @returns {Promise<{content:any[], stop_reason:string}>}
  */
 /**
@@ -230,7 +235,7 @@ async function streamClaudeAgentTurn(opts) {
 			const b = ev.content_block || {};
 			if (b.type === 'tool_use') {
 				blocks[ev.index] = { type: 'tool_use', id: b.id, name: b.name, _json: '' };
-				if (opts.onToolStart) { opts.onToolStart(b.name); }
+				if (opts.onToolStart) { opts.onToolStart(b.name, b.id); }
 			} else {
 				blocks[ev.index] = { type: 'text', text: '' };
 			}
@@ -238,7 +243,11 @@ async function streamClaudeAgentTurn(opts) {
 			const blk = blocks[ev.index];
 			if (!blk) { return; }
 			if (ev.delta.type === 'text_delta') { blk.text += ev.delta.text; opts.onText(ev.delta.text); }
-			else if (ev.delta.type === 'input_json_delta') { blk._json += ev.delta.partial_json || ''; }
+			else if (ev.delta.type === 'input_json_delta') {
+				blk._json += ev.delta.partial_json || '';
+				// The arguments so far, for a caller that shows progress while a long input streams.
+				if (opts.onToolInput) { opts.onToolInput(blk.id, blk.name, blk._json); }
+			}
 		} else if (ev.type === 'message_delta') {
 			if (ev.delta && ev.delta.stop_reason) { stopReason = ev.delta.stop_reason; }
 			if (ev.usage && ev.usage.output_tokens) { usage.output_tokens = ev.usage.output_tokens; }
@@ -247,8 +256,8 @@ async function streamClaudeAgentTurn(opts) {
 		}
 	});
 	// Build API-clean content + the malformed-id set in one pass (the only place input is resolved).
-	const { content, malformed } = finalizeAgentBlocks(blocks);
-	return { content: content, stop_reason: stopReason, usage: usage, malformed: malformed };
+	const { content, malformed, raw } = finalizeAgentBlocks(blocks);
+	return { content: content, stop_reason: stopReason, usage: usage, malformed: malformed, raw: raw };
 }
 
 module.exports = { streamClaude, completeClaude, claudeAgentTurn, streamClaudeAgentTurn, finalizeAgentBlocks, withRollingCacheBreakpoint };
diff --git a/extensions/levelcode-ai/providers/catalog.js b/extensions/levelcode-ai/providers/catalog.js
index dc31580..eda0c98 100644
--- a/extensions/levelcode-ai/providers/catalog.js
+++ b/extensions/levelcode-ai/providers/catalog.js
@@ -126,6 +126,21 @@ function supportsToolsForModel(providerId, modelId) {
 	return modelCaps(modelId).tools !== false;
 }
 
+/**
+ * How this provider+model draws diagrams (docs/RICH-DIAGRAMS.md, "Model differences").
+ *
+ *   'tool'  it is offered `render_diagram` — the default for every model the agent can run on.
+ *   'none'  it is not: the model is treated as an ASCII client and answers in prose.
+ *
+ * A model opts out with `diagrams: false` in its CAPS row. That is the registry switch the spec asks
+ * for: a model that fails the diagram eval is turned off here, in one line, without touching code.
+ * (The spec's third state — fenced Mermaid only — arrives with the Mermaid phase.)
+ */
+function diagramSupportForModel(providerId, modelId) {
+	if (!supportsToolsForModel(providerId, modelId)) { return 'none'; }
+	return modelCaps(modelId).diagrams === false ? 'none' : 'tool';
+}
+
 /**
  * Whether an image may be attached for this provider+model.
  *
@@ -280,7 +295,7 @@ async function getModelChoices(providerId, opts) {
 
 module.exports = {
 	CAPS, modelCaps, baseName, heuristicCaps,
-	supportsToolsForModel, supportsVisionForModel, contextWindowFor, fastCompletionModel,
+	supportsToolsForModel, diagramSupportForModel, supportsVisionForModel, contextWindowFor, fastCompletionModel,
 	describeCaps, describeModel,
 	mapOpenRouterModels, mapModelIds, fetchModels, getModelChoices
 };
diff --git a/extensions/levelcode-ai/providers/index.js b/extensions/levelcode-ai/providers/index.js
index bd5df62..7f799df 100644
--- a/extensions/levelcode-ai/providers/index.js
+++ b/extensions/levelcode-ai/providers/index.js
@@ -199,7 +199,8 @@ function supportsTools(id) {
  * {content, stop_reason, usage, malformed} shape for both, so agent.js is provider-agnostic.
  * @param {{providerId:string, apiKey?:string, baseURL?:string, label?:string, model:string, maxTokens?:number,
  *          system:string, messages:any[], tools?:any[], signal?:AbortSignal,
- *          onText?:(t:string)=>void, onToolStart?:(name:string)=>void,
+ *          onText?:(t:string)=>void, onToolStart?:(name:string, id?:string)=>void,
+ *          onToolInput?:(id:string, name:string, partialJson:string)=>void,
  *          onRetry?:(info:{attempt:number,retries:number,status:number})=>void}} o
  */
 async function streamAgentTurn(o) {
@@ -208,13 +209,14 @@ async function streamAgentTurn(o) {
 	if (p.kind === 'anthropic') {
 		return anthropic.streamClaudeAgentTurn({
 			apiKey: o.apiKey, model: o.model, maxTokens: o.maxTokens, system: o.system,
-			messages: o.messages, tools: o.tools, signal: o.signal, onText: o.onText, onToolStart: o.onToolStart
+			messages: o.messages, tools: o.tools, signal: o.signal, onText: o.onText, onToolStart: o.onToolStart,
+			onToolInput: o.onToolInput
 		});
 	}
 	return openai.streamOpenAIAgentTurn({
 		baseURL: o.baseURL || p.baseURL, apiKey: o.apiKey, headers: p.headers, label: o.label || p.label,
 		model: o.model, maxTokens: o.maxTokens, system: o.system, messages: o.messages, tools: o.tools,
-		signal: o.signal, onText: o.onText, onToolStart: o.onToolStart, onRetry: o.onRetry
+		signal: o.signal, onText: o.onText, onToolStart: o.onToolStart, onToolInput: o.onToolInput, onRetry: o.onRetry
 	});
 }
 
diff --git a/extensions/levelcode-ai/providers/openaiCompat.js b/extensions/levelcode-ai/providers/openaiCompat.js
index 54043b0..9c8f818 100644
--- a/extensions/levelcode-ai/providers/openaiCompat.js
+++ b/extensions/levelcode-ai/providers/openaiCompat.js
@@ -250,9 +250,10 @@ async function listOpenAIModels(opts) {
  * to {type:'text'} / {type:'tool_use', id, name, input} blocks.
  * @param {{baseURL:string, apiKey?:string, headers?:object, label?:string, model:string,
  *          maxTokens?:number, system:string, messages:any[], tools?:any[], signal?:AbortSignal,
- *          onText?:(t:string)=>void, onToolStart?:(name:string)=>void,
+ *          onText?:(t:string)=>void, onToolStart?:(name:string, id?:string)=>void,
+ *          onToolInput?:(id:string, name:string, partialJson:string)=>void,
  *          onRetry?:(info:{attempt:number,retries:number,status:number})=>void}} opts
- * @returns {Promise<{content:any[], stop_reason:string, usage:any, malformed:Set<string>}>}
+ * @returns {Promise<{content:any[], stop_reason:string, usage:any, malformed:Set<string>, raw:Map<string,string>}>}
  */
 async function streamOpenAIAgentTurn(opts) {
 	const label = opts.label || 'OpenAI-compatible';
@@ -301,14 +302,14 @@ async function streamOpenAIAgentTurn(opts) {
 		if (!c) { return; }
 		const d = c.delta || {};
 		if (typeof d.content === 'string' && d.content) { text += d.content; if (opts.onText) { opts.onText(d.content); } }
-		if (Array.isArray(d.tool_calls)) { translate.accumulateToolCalls(acc, d.tool_calls, opts.onToolStart); }
+		if (Array.isArray(d.tool_calls)) { translate.accumulateToolCalls(acc, d.tool_calls, opts.onToolStart, opts.onToolInput); }
 		if (c.finish_reason) { finish = c.finish_reason; }
 	});
-	const { content, malformed } = translate.finalizeOpenAIBlocks(text, acc);
+	const { content, malformed, raw } = translate.finalizeOpenAIBlocks(text, acc);
 	// If tool calls were assembled, the effective stop is tool_use even when a provider reports 'stop'.
 	let stopReason = translate.fromOpenAIFinishReason(finish);
 	if (stopReason !== 'max_tokens' && content.some((b) => b.type === 'tool_use')) { stopReason = 'tool_use'; }
-	return { content, stop_reason: stopReason, usage, malformed };
+	return { content, stop_reason: stopReason, usage, malformed, raw };
 }
 
 module.exports = { streamOpenAI, completeOpenAI, listOpenAIModels, streamOpenAIAgentTurn, buildChatBody, deltaFromEvent, isReasoningModel, isAnthropicFamily, splitOutCachedTokens, extractApiError, httpError, postChat };
diff --git a/extensions/levelcode-ai/providers/translate.js b/extensions/levelcode-ai/providers/translate.js
index 89e414d..dd57dee 100644
--- a/extensions/levelcode-ai/providers/translate.js
+++ b/extensions/levelcode-ai/providers/translate.js
@@ -194,9 +194,10 @@ function fromOpenAIFinishReason(reason) {
  * Fold one streamed delta.tool_calls[] fragment array into an accumulator keyed by tool-call index.
  * OpenAI sends id + function.name only on the FIRST fragment per index, then incremental
  * function.arguments string fragments. `acc` is a sparse array indexed by tool-call index.
- * onNew(name) fires the first time an index gains a name (drives onToolStart). Mutates + returns acc.
+ * onNew(name, id) fires the first time an index gains a name (drives onToolStart); onArgs(id, name,
+ * argsSoFar) fires whenever an index's arguments grow (drives onToolInput). Mutates + returns acc.
  */
-function accumulateToolCalls(acc, deltaToolCalls, onNew) {
+function accumulateToolCalls(acc, deltaToolCalls, onNew, onArgs) {
 	for (const tc of (deltaToolCalls || [])) {
 		if (!tc) { continue; }
 		const i = (tc.index != null) ? tc.index : acc.length;
@@ -204,8 +205,11 @@ function accumulateToolCalls(acc, deltaToolCalls, onNew) {
 		if (!slot) { slot = acc[i] = { id: tc.id || '', name: '', args: '' }; }
 		if (tc.id && !slot.id) { slot.id = tc.id; }
 		const fn = tc.function || {};
-		if (fn.name && !slot.name) { slot.name = fn.name; if (onNew) { onNew(fn.name); } }
-		if (typeof fn.arguments === 'string') { slot.args += fn.arguments; }
+		if (fn.name && !slot.name) { slot.name = fn.name; if (onNew) { onNew(fn.name, slot.id); } }
+		if (typeof fn.arguments === 'string') {
+			slot.args += fn.arguments;
+			if (onArgs && fn.arguments && slot.name) { onArgs(slot.id, slot.name, slot.args); }
+		}
 	}
 	return acc;
 }
@@ -216,10 +220,12 @@ function accumulateToolCalls(acc, deltaToolCalls, onNew) {
  * provider-agnostic. Truncated/invalid tool arguments → input:{} and the id is added to `malformed`
  * (the caller answers it with a "retry smaller" error instead of executing it). Empty args (a tool
  * with no inputs) → input:{} and is NOT malformed.
- * @returns {{content:any[], malformed:Set<string>}}
+ * `raw` carries the argument text of each malformed call by id — see anthropic.finalizeAgentBlocks.
+ * @returns {{content:any[], malformed:Set<string>, raw:Map<string,string>}}
  */
 function finalizeOpenAIBlocks(text, acc) {
 	const malformed = new Set();
+	const rawArgs = new Map();
 	const content = [];
 	if (text) { content.push({ type: 'text', text: text }); }
 	let n = 0;
@@ -240,12 +246,12 @@ function finalizeOpenAIBlocks(text, acc) {
 			try {
 				const parsed = JSON.parse(raw);
 				if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) { input = parsed; }
-				else { input = {}; malformed.add(id); }            // valid JSON but not an args object
-			} catch { input = {}; malformed.add(id); }             // truncated / corrupt partial JSON
+				else { input = {}; malformed.add(id); rawArgs.set(id, raw); }            // valid JSON but not an args object
+			} catch { input = {}; malformed.add(id); rawArgs.set(id, raw); }             // truncated / corrupt partial JSON
 		}
 		content.push({ type: 'tool_use', id: id, name: slot.name || '', input: input });
 	}
-	return { content, malformed };
+	return { content, malformed, raw: rawArgs };
 }
 
 module.exports = {
diff --git a/extensions/levelcode-ai/sessionEvents.js b/extensions/levelcode-ai/sessionEvents.js
index 89b8d48..cfb84b6 100644
--- a/extensions/levelcode-ai/sessionEvents.js
+++ b/extensions/levelcode-ai/sessionEvents.js
@@ -59,6 +59,14 @@ function agentTurnEvent(newMessages, model, t) {
 	return { kind: 'agent', t: t || null, model: model || null, messages: msgs, tools, edits };
 }
 
+/**
+ * A diagram the chat drew this turn (docs/RICH-DIAGRAMS.md, "Storage"): the FINAL record — the spec
+ * as it was rendered, after the repair ladder, with its status and what was fixed or lost. Stored so
+ * that reopening the session shows exactly the picture it showed before without validating, fixing or
+ * asking a model again. It carries no `messages`, so it never enters the rebuilt conversation.
+ */
+function diagramEvent(record, t) { return { kind: 'diagram', t: t || null, record: record }; }
+
 function endEvent(state, t) { return { kind: 'end', t: t || null, state: state || 'done' }; }
 function titleEvent(title, t) { return { kind: 'title', t: t || null, title: String(title == null ? '' : title) }; }
 /** A lifecycle/pin change — append-only, so archiving/pinning never rewrites the file (experience §4.9). */
@@ -84,6 +92,22 @@ function eventsToMessages(events) {
 	return out;
 }
 
+/**
+ * Every diagram a session drew, in the order they were drawn. A later record for the same id wins
+ * (append-only: nothing is rewritten, so an update is a second line).
+ */
+function diagramsFromEvents(events) {
+	const byId = new Map();
+	for (const e of (Array.isArray(events) ? events : [])) {
+		const r = e && e.kind === 'diagram' ? e.record : null;
+		if (r && typeof r === 'object' && typeof r.id === 'string') { byId.delete(r.id); byId.set(r.id, r); }
+	}
+	return Array.from(byId.values());
+}
+
+/** The tool whose calls draw diagrams — named here (not imported) so this module stays dependency-free. */
+const DIAGRAM_TOOL = 'render_diagram';
+
 // ── the readable transcript for a resume replay (pure) ───────────────────────────────────────────
 
 /** The human-visible text of a provider message: a string as-is, or the joined `text` blocks of an array. */
@@ -101,16 +125,29 @@ function messageText(content) {
  * prompt and per assistant answer, in order. Tool plumbing is dropped — a user message that is only a
  * `tool_result`, and an assistant turn that is only `tool_use` (no prose) — so the replay reads like the
  * chat did, not like the raw transcript. Pure, so the webview never has to know provider message shapes.
+ *
+ * With `diagrams` (the session's stored records), each diagram comes back as a turn of its own —
+ * `{ role: 'diagram', key, record }` — at the place in the answer where the model drew it. A drawing
+ * that a later one replaced is left out, as it was on screen. Without `diagrams` the result is exactly
+ * what it always was: prose only.
  */
-function toDisplayTurns(messages) {
+function toDisplayTurns(messages, diagrams) {
 	const out = [];
+	const records = Array.isArray(diagrams) ? diagrams : [];
+	const byKey = new Map(records.filter((r) => r && r.key).map((r) => [String(r.key), r]));
+	const replaced = new Set(records.filter((r) => r && r.replaces).map((r) => String(r.replaces)));
 	for (const m of (Array.isArray(messages) ? messages : [])) {
 		if (!m || (m.role !== 'user' && m.role !== 'assistant')) { continue; }
 		// a user message whose content is purely tool_result blocks is plumbing, not something the user typed
 		if (m.role === 'user' && Array.isArray(m.content) && m.content.length && m.content.every((b) => b && b.type === 'tool_result')) { continue; }
 		const text = messageText(m.content);
-		if (!text.trim()) { continue; }   // e.g. an assistant turn that was only tool calls
-		out.push({ role: m.role, text });
+		if (text.trim()) { out.push({ role: m.role, text }); }   // (an assistant turn that was only tool calls has none)
+		if (m.role === 'assistant' && byKey.size && Array.isArray(m.content)) {
+			for (const b of m.content) {
+				const r = b && b.type === 'tool_use' && b.name === DIAGRAM_TOOL ? byKey.get(String(b.id)) : null;
+				if (r && !replaced.has(String(r.id))) { out.push({ role: 'diagram', key: String(r.key), record: r }); }
+			}
+		}
 	}
 	return out;
 }
@@ -140,14 +177,20 @@ function tailFrom(messages, storedCount) {
  * @param {{title?:string, id?:string, model?:string, createdAt?:string, updatedAt?:string,
  *          filesEdited?:string[], turns?:number}} meta  a sessionStore index entry
  * @param {Array<{role:string, content:any}>} messages   the session's messages
- * @param {{redact?:(s:string)=>string, now?:string}} [opts]  `redact` is injected so this module
- *          stays dependency-free and the scrub is visible at the call site rather than implied
+ * DIAGRAMS: a diagram the session drew is exported where it stood, as a fenced block of whatever
+ * `opts.diagram(record)` returns — the caller passes Mermaid, which GitHub and most docs sites render
+ * natively, so a transcript pasted into a pull request shows the picture. It is scrubbed like any
+ * other text: a label is free text too.
+ *
+ * @param {{redact?:(s:string)=>string, now?:string, diagrams?:any[],
+ *          diagram?:(record:any)=>({lang:string, body:string}|null)}} [opts]  `redact` and `diagram`
+ *          are injected so this module stays dependency-free and both are visible at the call site
  */
 function toMarkdown(meta, messages, opts) {
 	const m = meta || {};
 	const o = opts || {};
 	const scrub = typeof o.redact === 'function' ? o.redact : (s) => s;
-	const turns = toDisplayTurns(messages);
+	const turns = toDisplayTurns(messages, o.diagrams).filter((t) => t.role !== 'diagram' || (t.record && t.record.spec));
 
 	const title = scrub(String(m.title || 'Untitled session')).trim() || 'Untitled session';
 	const when = String(m.updatedAt || m.createdAt || '').slice(0, 10);
@@ -157,7 +200,8 @@ function toMarkdown(meta, messages, opts) {
 	// never named a model or touched a file should read as a transcript, not as a form with blanks.
 	const bits = [];
 	if (when) { bits.push(when); }
-	bits.push(turns.length + ' turn' + (turns.length === 1 ? '' : 's'));
+	const spoken = turns.filter((t) => t.role !== 'diagram').length;   // a diagram is part of an answer, not a turn of its own
+	bits.push(spoken + ' turn' + (spoken === 1 ? '' : 's'));
 	if (m.model) { bits.push('`' + scrub(String(m.model)) + '`'); }
 	if (files.length) { bits.push(files.slice(0, 6).map((f) => '`' + f + '`').join(', ')); }
 
@@ -165,6 +209,22 @@ function toMarkdown(meta, messages, opts) {
 	md += '_LevelCode session · ' + bits.join(' · ') + '_\n';
 
 	for (const t of turns) {
+		if (t.role === 'diagram') {
+			// Under the answer it belongs to — no rule, no second speaker label.
+			const title = scrub(String((t.record.spec && t.record.spec.title) || 'Diagram')).replace(/\s+/g, ' ').trim();
+			let block = null;
+			try { block = typeof o.diagram === 'function' ? o.diagram(t.record) : null; } catch (e) { block = null; }
+			if (block && block.body) {
+				const body = scrub(String(block.body)).replace(/\n+$/, '');
+				// a fence one backtick longer than any run inside it, so nothing in a label can close it early
+				const longest = (body.match(/`+/g) || []).reduce((k, run) => Math.max(k, run.length), 0);
+				const fence = '`'.repeat(Math.max(3, longest + 1));
+				md += '\n' + fence + String(block.lang || '').replace(/[^a-z0-9-]/gi, '') + '\n' + body + '\n' + fence + '\n';
+			} else {
+				md += '\n_[diagram: ' + title + ']_\n';
+			}
+			continue;
+		}
 		md += '\n---\n\n**' + (t.role === 'user' ? 'You' : 'LevelCode') + '**\n\n';
 		// Verbatim aside from redaction — NOT trimmed. Trimming changes Markdown semantics: it de-indents a
 		// leading 4-space (indented code block) and eats trailing "  " (a hard line break). The `**role**\n\n`
@@ -179,6 +239,6 @@ function toMarkdown(meta, messages, opts) {
 module.exports = {
 	EDIT_TOOLS,
 	toolStatsFromMessages,
-	userTurnEvent, agentTurnEvent, endEvent, titleEvent, labelEvent,
-	eventsToMessages, messageText, toDisplayTurns, tailFrom, toMarkdown
+	userTurnEvent, agentTurnEvent, diagramEvent, endEvent, titleEvent, labelEvent,
+	eventsToMessages, diagramsFromEvents, DIAGRAM_TOOL, messageText, toDisplayTurns, tailFrom, toMarkdown
 };
diff --git a/extensions/levelcode-ai/sessions.js b/extensions/levelcode-ai/sessions.js
index bf02307..2726dec 100644
--- a/extensions/levelcode-ai/sessions.js
+++ b/extensions/levelcode-ai/sessions.js
@@ -64,18 +64,24 @@ function createSessions(opts) {
 	 * Persist ONE turn — the new messages the loop produced this turn (goal + the agent's messages). The
 	 * leading user message becomes a `user` event (turn count / title / preview); the rest a verbatim
 	 * `agent` event (sparkline + files-edited derive from it). Creates the session on the first turn.
+	 *
+	 * `extras.diagrams` are the diagrams the chat drew this turn (docs/RICH-DIAGRAMS.md, "Storage"):
+	 * each is appended as its own event AFTER the turn it belongs to, as rendered — so a reopened
+	 * session replays the same pictures without running the repair ladder again.
 	 */
-	function recordTurn(turnMessages, model) {
+	function recordTurn(turnMessages, model, extras) {
 		ensure();
 		const msgs = Array.isArray(turnMessages) ? turnMessages : [];
-		if (!msgs.length) { return; }
-		if (msgs[0] && msgs[0].role === 'user') {
+		const drawn = extras && Array.isArray(extras.diagrams) ? extras.diagrams.filter((r) => r && typeof r.id === 'string') : [];
+		if (!msgs.length && !drawn.length) { return; }
+		if (msgs.length && msgs[0] && msgs[0].role === 'user') {
 			store.appendEvent(live.file, events.userTurnEvent(msgs[0], iso()));
 			const rest = msgs.slice(1);
 			if (rest.length) { store.appendEvent(live.file, events.agentTurnEvent(rest, model, iso())); }
-		} else {
+		} else if (msgs.length) {
 			store.appendEvent(live.file, events.agentTurnEvent(msgs, model, iso()));
 		}
+		for (const r of drawn) { store.appendEvent(live.file, events.diagramEvent(r, iso())); }
 		reindex();
 	}
 
@@ -116,8 +122,10 @@ function createSessions(opts) {
 		live = { id, file: store.sessionFile(root, slug, id) };
 		if (state) { try { state.set('liveSessionId', id); } catch (e) { /* convenience */ } }
 		reindexId(id);
+		const drawn = events.diagramsFromEvents(s.events);
 		return { id, meta: s.meta, entry: store.deriveEntry(s.meta, s.events), full, messages, plan,
-			turns: events.toDisplayTurns(full),   // the readable transcript to replay in the webview
+			diagrams: drawn,                               // every diagram it drew, as stored (for links, export, get_diagram)
+			turns: events.toDisplayTurns(full, drawn),     // the readable transcript to replay in the webview, pictures included
 			note: planner.describeResume(plan, turnsSummarized) };
 	}
 
@@ -309,6 +317,11 @@ function createSessions(opts) {
 		try { return events.eventsToMessages(store.readSession(store.sessionFile(root, slug, id)).events); }
 		catch (e) { return []; }
 	}
+	/** The diagrams a session drew, as stored. Read-only; empty on error. */
+	function diagrams(id) {
+		try { return events.diagramsFromEvents(store.readSession(store.sessionFile(root, slug, id)).events); }
+		catch (e) { return []; }
+	}
 	/**
 	 * Replace a session's journal summary with a refined (model-written) outcome — append a superseding line
 	 * for that id (latestBySession then wins) and re-consolidate MEMORY.md. Append-only; best-effort.
@@ -355,7 +368,7 @@ function createSessions(opts) {
 
 	function liveId() { return live ? live.id : null; }
 
-	return { ensure, recordTurn, seal, resume, fork, archive, trash, restore, setPinned, rename, autoArchiveStale, digest, consolidate, transcript, refineSummary, recall, recallFacts, memoryItems, forget, recordFacts, factsList, factAction, supersedeFact, memoryPaths, mediaRoot, sweepMedia, list, liveId };
+	return { ensure, recordTurn, seal, resume, fork, archive, trash, restore, setPinned, rename, autoArchiveStale, digest, consolidate, transcript, diagrams, refineSummary, recall, recallFacts, memoryItems, forget, recordFacts, factsList, factAction, supersedeFact, memoryPaths, mediaRoot, sweepMedia, list, liveId };
 }
 
 module.exports = { createSessions };
diff --git a/extensions/levelcode-ai/test/agentNoWorkspace.test.js b/extensions/levelcode-ai/test/agentNoWorkspace.test.js
index 09874b5..72edb0f 100644
--- a/extensions/levelcode-ai/test/agentNoWorkspace.test.js
+++ b/extensions/levelcode-ai/test/agentNoWorkspace.test.js
@@ -83,8 +83,12 @@ test('the portable subset is what a rootless run actually offers', () => {
 	// popover would bill the user for tools that were never sent.
 	assert.match(agent, /let tools = mcp\.tools\.length \? builtins\.concat\(mcp\.tools\) : builtins;/,
 		'the model is still handed the unfiltered TOOLS');
-	assert.match(agent, /const baseTools = ctx\.recallSessions \? builtins\.concat\(\[RECALL_TOOL\]\) : builtins;/,
+	// `extras` is every host-gated tool (recall, and since rich diagrams the diagram tools). What this
+	// pins is unchanged: baseTools starts from `builtins`, never from the unfiltered TOOLS.
+	assert.match(agent, /const baseTools = extras\.length \? builtins\.concat\(extras\) : builtins;/,
 		'baseTools still counts the full TOOLS — the context popover would report tools that were not sent');
+	assert.match(agent, /if \(ctx\.recallSessions\) \{ extras\.push\(RECALL_TOOL\); \}/,
+		'recall is no longer one of the extras');
 });
 
 test('the context popover is billed for the list that was actually sent', () => {
@@ -96,7 +100,7 @@ test('the context popover is billed for the list that was actually sent', () =>
 		'no rootless token estimate — the popover reports the full tool cost for a list that was not sent');
 	assert.match(agent, /const builtinsTokensEst = root \? TOOLS_TOKENS_EST : PORTABLE_TOOLS_TOKENS_EST;/,
 		'the estimate no longer switches on the root');
-	assert.match(agent, /const toolsTokensEst = \(mcp\.tools\.length \|\| ctx\.recallSessions\)[\s\S]{0,120}: builtinsTokensEst;/,
+	assert.match(agent, /const toolsTokensEst = \(mcp\.tools\.length \|\| extras\.length\)[\s\S]{0,120}: builtinsTokensEst;/,
 		'the plain path still falls back to the full-TOOLS constant');
 
 	// The two constants must actually differ, or the guard above passes on a list that gates nothing —
diff --git a/extensions/levelcode-ai/test/authRetryCallers.test.js b/extensions/levelcode-ai/test/authRetryCallers.test.js
index f41ccef..0d54069 100644
--- a/extensions/levelcode-ai/test/authRetryCallers.test.js
+++ b/extensions/levelcode-ai/test/authRetryCallers.test.js
@@ -101,6 +101,10 @@ const makeHost = new Function('env', [
 	// The prompts themselves are beside the point here.
 	"const OUTCOME_SYSTEM = 'system', OUTCOME_FORMAT = 'format', OUTCOME_SUPERSEDES_FORMAT = '', COMPACT_SYSTEM = 'system', COMPACT_INSTRUCTIONS = 'Summarize:\\n';",
 	'let cloudSignedIn = env.signedIn, abort = null, agentMessages = [];',
+	// Compaction also stubs out the specs of diagrams it summarizes away (docs/RICH-DIAGRAMS.md). No
+	// diagram is drawn in these scenarios, so the stand-in has none to stub; test/diagramHost.test.js
+	// runs the same function with the real service.
+	'let diagramsStubbed = false; const diagrams = { stubsFor: () => [] };',
 	decl('ACCOUNT_TOKEN_KEY'), decl('ACCOUNT_REFRESH_KEY'), decl('ACCOUNT_PROFILE_KEY'), decl('ACCOUNT_EXPIRED_KEY'),
 	decl('sessionQueue'), decl('sessionGeneration'),
 	...HOST_FUNCTIONS.map(extract),
diff --git a/extensions/levelcode-ai/test/diagramAgent.test.js b/extensions/levelcode-ai/test/diagramAgent.test.js
new file mode 100644
index 0000000..16a505f
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramAgent.test.js
@@ -0,0 +1,364 @@
+/*---------------------------------------------------------------------------------------------
+ *  Rich diagrams in the agent loop, EXECUTED — run: node test/diagramAgent.test.js
+ *
+ *  docs/RICH-DIAGRAMS.md: FR-2 (Graph JSON arrives through a `render_diagram` tool call), FR-4 (auto-
+ *  fix, ONE model pass, graceful degrade — no automatic second repair, no blank output) and FR-8 (the
+ *  capability flag is respected in every session).
+ *
+ *  This runs the real runAgent → runTool → diagram service chain, the way agentRunCommand.test.js
+ *  does: `vscode` is a stand-in and the provider is a script of turns. Nothing here asserts from
+ *  source text — a tool that is present in the file but never reached would pass that and fail this.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const Module = require('module');
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lc-diagram-'));
+const vscodeMock = { workspace: { workspaceFolders: [{ uri: { fsPath: root }, name: 'app' }] } };
+const origLoad = Module._load;
+// @ts-ignore — test-only loader shim
+Module._load = function (request, parent, isMain) {
+	if (request === 'vscode') { return vscodeMock; }
+	return origLoad.call(this, request, parent, isMain);
+};
+
+const providers = require('../providers/index');
+let script = [];
+const calls = [];
+providers.streamAgentTurn = async (opts) => {
+	calls.push(opts);
+	const turn = script.shift();
+	if (!turn) { throw new Error('the agent asked for a turn the script does not have'); }
+	return typeof turn === 'function' ? turn(opts) : turn;
+};
+
+const { runAgent } = require('../agent');
+const { createDiagrams } = require('../diagram/service');
+const tool = require('../diagram/tool');
+const stats = require('../diagram/stats');
+
+let n = 0;
+async function testAsync(name, fn) { await fn(); n++; console.log('  ok - ' + name); }
+
+const jev = () => ({
+	title: 'Jev classifies; your code decides the action',
+	nodes: [{ id: 'in', label: 'Customer message', sub: 'plus account details' }, { id: 'jev', label: 'Jev', sub: 'returns probabilities', accent: true }, { id: 'bill', label: 'Route to billing' }, { id: 'rev', label: 'Human review' }],
+	edges: [{ from: 'in', to: 'jev' }, { from: 'jev', to: 'bill', label: '0.90 or more' }, { from: 'jev', to: 'rev', label: 'under 0.90' }]
+});
+const broken = () => { const s = jev(); s.edges[1].to = 'billing'; s.nodes[2].accent = true; return s; };
+const call = (id, input) => ({ stop_reason: 'tool_use', content: [{ type: 'text', text: 'Here is the flow.' }, { type: 'tool_use', id, name: 'render_diagram', input }] });
+const say = (text) => ({ stop_reason: 'end_turn', content: [{ type: 'text', text }] });
+
+/** Run one goal against a script of turns. Returns what was posted, what the model was sent, and the service. */
+async function run(turns, overrides) {
+	script = turns.slice();
+	calls.length = 0;
+	const posted = [], events = [];
+	const diagrams = createDiagrams({
+		resolveLink: (link) => (link.path === 'agent.js' ? { ok: true, path: 'agent.js' } : { ok: false, reason: 'no such file in this workspace' }),
+		onStat: (ev) => events.push(ev)
+	});
+	const ctx = Object.assign({
+		messages: [{ role: 'user', content: 'explain the routing' }],
+		maxSteps: 8, model: 'test-model',
+		post: (m) => posted.push(m),
+		approve: async () => { throw new Error('render_diagram asked for approval — it is read-only'); },
+		diagrams, client: { render: 'rich' },
+		signal: new AbortController().signal
+	}, overrides);
+	await runAgent(ctx);
+	const end = posted.filter((m) => m.type === 'agentError' || m.type === 'agentDone');
+	assert.deepStrictEqual(end.map((m) => m.reason || m.message), ['done'], 'the scripted run did not finish cleanly: ' + JSON.stringify(end));
+	assert.deepStrictEqual(script, [], 'the agent stopped before the script ended');
+	const results = [];
+	for (const m of ctx.messages) { if (m.role === 'user' && Array.isArray(m.content)) { for (const b of m.content) { if (b.type === 'tool_result') { results.push(b); } } } }
+	return { posted, results, diagrams, events, sent: calls.slice(), ctx, shown: posted.filter((m) => m.type === 'diagram' || m.type === 'diagramPending') };
+}
+
+(async () => {
+	try {
+		// ---- capability detection ---------------------------------------------------------------------
+
+		await testAsync('CAPABILITY: a rich client is given the tool and the rules; an ASCII client is given neither', async () => {
+			const rich = await run([say('Done: nothing to draw.')]);
+			const names = rich.sent[0].tools.map((t) => t.name);
+			assert.ok(names.includes('render_diagram'), 'a rich client gets render_diagram');
+			assert.ok(rich.sent[0].system.includes(tool.PROMPT), 'and the rules for using it');
+			assert.ok(!names.includes('get_diagram'), 'get_diagram is not offered until a spec has left the conversation');
+
+			for (const client of [{ render: 'ascii' }, undefined, { render: 'nonsense' }]) {
+				const plain = await run([say('Done: nothing to draw.')], { client });
+				assert.ok(!plain.sent[0].tools.some((t) => /diagram/.test(t.name)), 'an ASCII client must not be offered a tool it cannot show: ' + JSON.stringify(client));
+				assert.ok(!/DIAGRAMS\./.test(plain.sent[0].system) && !/render_diagram/.test(plain.sent[0].system), 'nor told about it');
+			}
+			// the other host-gated tool is untouched by all of this: offered when wired, absent when not
+			assert.ok(!names.includes('recall_sessions'));
+			const recall = await run([say('Done: nothing to draw.')], { recallSessions: () => 'nothing' });
+			assert.deepStrictEqual(recall.sent[0].tools.map((t) => t.name).slice(-2), ['recall_sessions', 'render_diagram'], 'extras keep one stable order, so the cached prefix does not churn');
+			const noService = await run([say('Done: nothing to draw.')], { diagrams: undefined });
+			assert.ok(!noService.sent[0].tools.some((t) => /diagram/.test(t.name)), 'the flag alone is not enough — there must be something to draw with');
+		});
+
+		await testAsync('CAPABILITY: get_diagram appears once a diagram has been stubbed out of the conversation — and only then', async () => {
+			const r = await run([say('Done: ok.')], { diagramsStubbed: true });
+			assert.deepStrictEqual(r.sent[0].tools.map((t) => t.name).filter((x) => /diagram/.test(x)), ['render_diagram', 'get_diagram']);
+			const ascii = await run([say('Done: ok.')], { diagramsStubbed: true, client: { render: 'ascii' } });
+			assert.ok(!ascii.sent[0].tools.some((t) => /diagram/.test(t.name)));
+		});
+
+		await testAsync('CONTEXT METER: the popover is billed for exactly the tools and prompt that were sent', async () => {
+			for (const overrides of [{}, { client: { render: 'ascii' } }, { diagramsStubbed: true }]) {
+				script = [Object.assign(say('Done: ok.'), { usage: { input_tokens: 10, output_tokens: 2 } })];
+				const posted = [];
+				calls.length = 0;
+				await runAgent(Object.assign({ messages: [{ role: 'user', content: 'hi' }], maxSteps: 3, model: 'm', post: (m) => posted.push(m), approve: async () => true, diagrams: createDiagrams(), client: { render: 'rich' }, signal: new AbortController().signal }, overrides));
+				const usage = posted.find((m) => m.type === 'contextUsage');
+				assert.ok(usage, 'usage was reported');
+				assert.strictEqual(usage.tools, Math.round(JSON.stringify(calls[0].tools).length / 4), 'tools estimate for ' + JSON.stringify(overrides));
+				assert.strictEqual(usage.system, Math.round(calls[0].system.length / 4), 'system estimate for ' + JSON.stringify(overrides));
+				assert.strictEqual(usage.mcpTools, 0, 'no MCP server contributed anything');
+			}
+		});
+
+		// ---- the tool -----------------------------------------------------------------------------------
+
+		await testAsync('DRAW: a valid spec is drawn, answered with {"ok":true,"id"}, and asks nobody', async () => {
+			const r = await run([call('toolu_1', jev()), say('Done: the diagram shows the routing.')]);
+			assert.deepStrictEqual(r.results.map((b) => b.content), ['{"ok":true,"id":"d-1"}']);
+			const shown = r.shown.filter((m) => m.type === 'diagram');
+			assert.strictEqual(shown.length, 1);
+			assert.strictEqual(shown[0].key, 'toolu_1', 'keyed by the tool call, so it lands where the model put it');
+			const rec = shown[0].record;
+			assert.strictEqual(rec.id, 'd-1'); assert.strictEqual(rec.status, 'ok'); assert.strictEqual(rec.model, 'test-model');
+			assert.strictEqual(rec.spec.nodes.length, 4); assert.strictEqual(rec.spec.v, 1);
+			assert.deepStrictEqual([rec.fixes, rec.notes, rec.errors], [[], [], []]);
+			assert.strictEqual(r.diagrams.get('d-1'), rec, 'and it is on file for links, export and replay');
+			// the diagram sits between the text before it and the text after it
+			const order = r.posted.filter((m) => m.type === 'diagram' || m.type === 'agentDone').map((m) => m.type);
+			assert.deepStrictEqual(order, ['diagram', 'agentDone']);
+		});
+
+		await testAsync('DRAW: a link that is not a workspace file becomes plain text — and the model is told which', async () => {
+			const spec = jev();
+			spec.nodes[1].link = { path: 'agent.js', symbol: 'runAgent' };
+			spec.nodes[2].link = { path: '../../etc/passwd' };
+			const r = await run([call('toolu_1', spec), say('Done: drawn.')]);
+			const rec = r.shown.find((m) => m.type === 'diagram').record;
+			assert.deepStrictEqual(rec.spec.nodes[1].link, { path: 'agent.js', symbol: 'runAgent' });
+			assert.strictEqual(rec.spec.nodes[2].link, undefined, 'nothing clickable points outside the workspace');
+			const answer = JSON.parse(r.results[0].content);
+			assert.strictEqual(answer.ok, true);
+			assert.deepStrictEqual(answer.unlinked, ['bill: no such file in this workspace']);
+		});
+
+		// ---- the repair ladder, end to end ----------------------------------------------------------------
+
+		await testAsync('LADDER rung 2: errors go back ONCE with every problem listed; the fixed spec takes the placeholder\'s place', async () => {
+			const r = await run([call('toolu_1', broken()), call('toolu_2', jev()), say('Done: drawn.')]);
+			assert.match(r.results[0].content, /^ERROR: the diagram was not drawn — 2 problems in the spec\. Fix them and call render_diagram once more\.\n/);
+			assert.ok(r.results[0].content.includes('/edges/1/to: unknown node "billing". Known ids: in, jev, bill, rev.'), r.results[0].content);
+			assert.ok(r.results[0].content.includes('/nodes: 2 nodes have accent=true, max 1 (jev, bill).'), r.results[0].content);
+			assert.deepStrictEqual(r.shown.map((m) => m.type + ':' + (m.state || m.record.status)), ['diagramPending:repairing', 'diagram:ok']);
+			assert.strictEqual(r.shown[0].title, 'Jev classifies; your code decides the action', 'the placeholder already says what is being drawn');
+			assert.strictEqual(r.shown[1].replacesKey, 'toolu_1', 'the repaired picture lands where the failed attempt was waiting');
+			assert.strictEqual(r.shown[1].record.repaired, true, '"the repaired spec is stored and marked as repaired"');
+			assert.strictEqual(r.results[1].content, '{"ok":true,"id":"d-1"}');
+			assert.strictEqual(r.diagrams.list().length, 1, 'the failed attempt is not on file as a diagram');
+			assert.deepStrictEqual(r.events.filter((e) => e.type === 'call').map((e) => e.outcome), ['bounced', 'repaired']);
+		});
+
+		await testAsync('LADDER rung 3: still broken after the one pass — what is valid is drawn, with what was lost, and no second request', async () => {
+			const r = await run([call('toolu_1', broken()), call('toolu_2', broken()), say('Done: drawn as far as it could be.')]);
+			assert.match(r.results[0].content, /^ERROR:/);
+			const second = JSON.parse(r.results[1].content);
+			assert.strictEqual(second.ok, true);
+			assert.deepStrictEqual(second.degraded, ['1 edge dropped: unknown nodes', '1 extra accent removed']);
+			assert.match(second.note, /Do NOT call render_diagram again/, '"no automatic second repair"');
+			const rec = r.shown[r.shown.length - 1].record;
+			assert.strictEqual(rec.status, 'degraded');
+			assert.strictEqual(rec.spec.edges.length, 2, 'the valid subgraph');
+			assert.deepStrictEqual(rec.notes, ['1 edge dropped: unknown nodes', '1 extra accent removed'], 'the banner');
+			assert.ok(rec.errors.length >= 2, 'and the details behind it');
+			assert.strictEqual(r.sent.length, 3, 'three model turns: the call, the one repair, the answer — never a fourth for this diagram');
+		});
+
+		await testAsync('NO BLANK OUTPUT: the model gives up after the error list — the run still ends with a picture, not a placeholder', async () => {
+			const r = await run([call('toolu_1', broken()), say('Done: I could not draw it; here it is in words.')]);
+			const types = r.posted.filter((m) => /^diagram/.test(m.type) || m.type === 'agentDone').map((m) => m.type + (m.state ? ':' + m.state : m.record ? ':' + m.record.status : ''));
+			assert.deepStrictEqual(types, ['diagramPending:repairing', 'diagram:degraded', 'agentDone'], 'settled BEFORE the run is declared over');
+			const settled = r.shown.find((m) => m.type === 'diagram');
+			assert.strictEqual(settled.key, 'toolu_1', 'it fills the placeholder that was waiting');
+			assert.strictEqual(r.diagrams.pending, null);
+		});
+
+		await testAsync('NO BLANK OUTPUT: a spec with nothing drawable shows its source and its errors — `failed`, never empty', async () => {
+			const r = await run([call('toolu_1', { title: 'Empty', nodes: [], edges: [] }), call('toolu_2', { title: 'Empty', nodes: [], edges: [] }), say('Done: nothing to show.')]);
+			const rec = r.shown[r.shown.length - 1].record;
+			assert.strictEqual(rec.status, 'failed');
+			assert.strictEqual(rec.spec, null);
+			assert.ok(rec.source.includes('"title": "Empty"'), 'the user can see what was sent');
+			assert.deepStrictEqual(rec.errors, ['/nodes: 0 nodes, min 1.']);
+			const answer = JSON.parse(r.results[1].content);
+			assert.strictEqual(answer.ok, false);
+			assert.match(answer.note, /Do NOT call render_diagram again/);
+		});
+
+		await testAsync('LADDER: a different diagram after a failed one settles the first and gets a pass of its own', async () => {
+			const other = { title: 'A second, unrelated picture', nodes: [{ id: 'x', label: 'X' }, { id: 'y', label: 'Y' }], edges: [{ from: 'x', to: 'y' }] };
+			const r = await run([call('toolu_1', broken()), call('toolu_2', other), say('Done: two diagrams.')]);
+			const drawn = r.shown.filter((m) => m.type === 'diagram');
+			assert.deepStrictEqual(drawn.map((m) => m.key + ':' + m.record.status), ['toolu_1:degraded', 'toolu_2:ok'], 'the abandoned one is settled the moment the model moves on');
+			assert.strictEqual(drawn[1].replacesKey, undefined, 'and the new one does not take its place');
+		});
+
+		await testAsync('LADDER: a model that keeps sending broken specs runs out of repair passes', async () => {
+			// five DIFFERENT diagrams (own title, own nodes), each broken — not five goes at one
+			const bad = (k) => ({ title: 'Broken ' + k, nodes: [{ id: 'node' + k, label: 'N' + k }], edges: [{ from: 'node' + k, to: 'ghost' + k }] });
+			const turns = [];
+			for (let k = 1; k <= 5; k++) { turns.push(call('toolu_' + k, bad(k))); }
+			turns.push(say('Done: giving up.'));
+			const r = await run(turns, { maxSteps: 10 });
+			const outcomes = r.results.map((b) => (/^ERROR/.test(b.content) ? 'bounced' : 'drawn'));
+			assert.deepStrictEqual(outcomes, ['bounced', 'bounced', 'bounced', 'drawn', 'drawn'], 'three passes in one run, then every broken spec is simply degraded');
+			assert.ok(r.shown.filter((m) => m.type === 'diagram').every((m) => m.record.status === 'degraded'));
+			assert.strictEqual(r.shown.filter((m) => m.type === 'diagram').length, 5, 'and all five end up drawn — none is left as a placeholder');
+		});
+
+		await testAsync('LADDER: a second go at the SAME diagram is recognised by its nodes even when the title was reworded', async () => {
+			const first = broken(), second = broken();
+			second.title = 'Routing by confidence';
+			const r = await run([call('toolu_1', first), call('toolu_2', second), say('Done: drawn.')]);
+			assert.deepStrictEqual(r.results.map((b) => (/^ERROR/.test(b.content) ? 'bounced' : 'drawn')), ['bounced', 'drawn'], 'the reworded retry is the repair pass, so it degrades instead of bouncing again');
+			assert.strictEqual(r.shown[r.shown.length - 1].replacesKey, 'toolu_1');
+		});
+
+		await testAsync('REDRAW: drawing the same diagram again in one run replaces the first instead of stacking a second', async () => {
+			const again = jev(); again.direction = 'down';
+			const r = await run([call('toolu_1', jev()), call('toolu_2', again), say('Done: redrawn top to bottom.')]);
+			const drawn = r.shown.filter((m) => m.type === 'diagram');
+			assert.strictEqual(drawn[1].replacesKey, 'toolu_1');
+			assert.strictEqual(drawn[1].record.replaces, 'd-1');
+			assert.strictEqual(drawn[1].record.id, 'd-2');
+			assert.strictEqual(drawn[1].record.spec.direction, 'down');
+		});
+
+		// ---- extraction: truncated vs merely sloppy -------------------------------------------------------
+
+		await testAsync('TRUNCATED: a spec cut off at the token cap is re-requested — never repaired, never drawn', async () => {
+			const cut = { stop_reason: 'max_tokens', content: [{ type: 'tool_use', id: 'toolu_1', name: 'render_diagram', input: {} }], malformed: new Set(['toolu_1']), raw: new Map([['toolu_1', '{"title":"Cut off","nodes":[{"id":"a","label":"A"},{"id":"b","la']]) };
+			const r = await run([cut, call('toolu_2', jev()), say('Done: drawn.')]);
+			assert.match(r.results[0].content, /^ERROR: the diagram spec was cut off before it was complete/);
+			assert.match(r.results[0].content, /Send the whole spec again, smaller/);
+			assert.deepStrictEqual(r.shown.filter((m) => m.type === 'diagram').map((m) => m.record.id), ['d-1'], 'only the complete one is drawn');
+			assert.strictEqual(r.results[1].content, '{"ok":true,"id":"d-1"}', 'and the re-request is a FIRST attempt, not the repair pass');
+			assert.deepStrictEqual(r.events.filter((e) => e.type === 'call').map((e) => e.outcome), ['truncated', 'clean']);
+		});
+
+		await testAsync('LENIENT JSON: arguments with a trailing comma are a spec, and are drawn without a model call', async () => {
+			const sloppy = '{"title":"Requests are cached before they are routed","nodes":[{"id":"a","label":"Request"},{"id":"b","label":"Cache"},],"edges":[{"from":"a","to":"b"},],}';
+			const turn = { stop_reason: 'tool_use', content: [{ type: 'tool_use', id: 'toolu_1', name: 'render_diagram', input: {} }], malformed: new Set(['toolu_1']), raw: new Map([['toolu_1', sloppy]]) };
+			const r = await run([turn, say('Done: drawn.')]);
+			assert.strictEqual(r.results[0].content, '{"ok":true,"id":"d-1"}');
+			assert.strictEqual(r.shown.find((m) => m.type === 'diagram').record.spec.nodes.length, 2);
+			assert.deepStrictEqual(r.events.filter((e) => e.type === 'call').map((e) => e.outcome), ['tidied'], 'an auto-fix, counted as one');
+			assert.strictEqual(r.sent.length, 2, 'no extra model turn was spent on it');
+		});
+
+		await testAsync('MALFORMED: any other tool\'s cut-off arguments still get the generic answer', async () => {
+			const cut = { stop_reason: 'max_tokens', content: [{ type: 'tool_use', id: 'toolu_1', name: 'update_plan', input: {} }], malformed: new Set(['toolu_1']), raw: new Map([['toolu_1', '{"todos":[']]) };
+			const r = await run([cut, say('Done: ok.')]);
+			assert.match(r.results[0].content, /^ERROR: your tool arguments were cut off \(truncated JSON\)/);
+		});
+
+		// ---- the placeholder ------------------------------------------------------------------------------
+
+		await testAsync('PLACEHOLDER: the diagram\'s place is held as soon as the model starts writing it, and titled as soon as the title arrives', async () => {
+			const streamed = (opts) => {
+				opts.onToolStart('render_diagram', 'toolu_1');
+				opts.onToolInput('toolu_1', 'render_diagram', '{"ti');
+				opts.onToolInput('toolu_1', 'render_diagram', '{"title": "Jev classifies; your \\"code\\" decides');
+				opts.onToolInput('toolu_1', 'render_diagram', '{"title": "Jev classifies; your \\"code\\" decides", "nodes": [');
+				opts.onToolInput('toolu_1', 'render_diagram', '{"title": "Jev classifies; your \\"code\\" decides", "nodes": [{"id":"a","label":"A"}]');
+				opts.onToolStart('read_file', 'toolu_9');
+				opts.onToolInput('toolu_9', 'read_file', '{"title": "not a diagram"}');
+				return call('toolu_1', jev());
+			};
+			const r = await run([streamed, say('Done: drawn.')]);
+			const pend = r.shown.filter((m) => m.type === 'diagramPending');
+			assert.deepStrictEqual(pend.map((m) => [m.key, m.state, m.title]), [['toolu_1', 'drawing', ''], ['toolu_1', 'drawing', 'Jev classifies; your "code" decides']], 'held at once; titled once, when the title is complete; other tools ignored');
+			assert.strictEqual(r.shown[r.shown.length - 1].type, 'diagram');
+			const ascii = await run([(opts) => { opts.onToolStart('render_diagram', 'toolu_1'); opts.onToolInput('toolu_1', 'render_diagram', '{"title": "x"}'); return say('Done: ok.'); }], { client: { render: 'ascii' } });
+			assert.deepStrictEqual(ascii.shown, [], 'an ASCII client is never shown a placeholder');
+		});
+
+		// ---- an ASCII client, and the leak counter -------------------------------------------------------
+
+		await testAsync('ASCII CLIENT: a call to render_diagram anyway is refused in words the model can act on', async () => {
+			const r = await run([call('toolu_1', jev()), say('Done: explained in prose.')], { client: { render: 'ascii' }, diagrams: undefined });
+			assert.match(r.results[0].content, /^ERROR: this client cannot draw diagrams\. Explain it in prose instead/);
+			assert.deepStrictEqual(r.shown, []);
+		});
+
+		await testAsync('ASCII LEAKS: every answer to a rich client is checked for character drawings, and counted', async () => {
+			const art = ['Here is the flow:', '', '+---------+     +-------+', '| Message | --> |  Jev  |', '+---------+     +-------+'].join('\n');
+			const r = await run([say('Done: ' + art)]);
+			assert.deepStrictEqual(r.events.filter((e) => e.type === 'answer'), [{ type: 'answer', asciiArt: true }]);
+			const clean = await run([say('Done: Jev classifies the message and your code picks the route.')]);
+			assert.deepStrictEqual(clean.events.filter((e) => e.type === 'answer'), [{ type: 'answer', asciiArt: false }]);
+			const ascii = await run([say('Done: ' + art)], { client: { render: 'ascii' } });
+			assert.deepStrictEqual(ascii.events, [], 'a terminal client drawing ASCII is not a leak');
+			let s = stats.empty('2026-10-04');
+			for (const ev of r.events.concat(clean.events)) { s = stats.record(s, ev); }
+			assert.deepStrictEqual(stats.summarize(s).asciiLeaks, { answers: 2, leaks: 1 });
+		});
+
+		await testAsync('GET_DIAGRAM: returns the stored spec for an id, and names the ids it knows when asked for one it does not', async () => {
+			const fetch = (id) => ({ stop_reason: 'tool_use', content: [{ type: 'tool_use', id: 'toolu_g' + id, name: 'get_diagram', input: { id } }] });
+			const r = await run([call('toolu_1', jev()), fetch('d-1'), fetch('d-9'), say('Done: fetched.')], { diagramsStubbed: true });
+			const got = JSON.parse(r.results[1].content);
+			assert.strictEqual(got.title, 'Jev classifies; your code decides the action');
+			assert.strictEqual(got.nodes.length, 4);
+			assert.strictEqual(r.results[2].content, 'ERROR: no diagram with id "d-9" in this session. Known ids: d-1.');
+		});
+
+		// ---- what it costs --------------------------------------------------------------------------------
+
+		await testAsync('BUDGET: the tool and its rules are a standing cost on every request — pinned, so it cannot creep', async () => {
+			const toolTokens = Math.round(JSON.stringify(tool.RENDER_DIAGRAM).length / 4);
+			const promptTokens = Math.round(tool.PROMPT.length / 4);
+			assert.ok(toolTokens <= 520, 'render_diagram schema ≈ ' + toolTokens + ' tokens');
+			assert.ok(promptTokens <= 560, 'prompt block ≈ ' + promptTokens + ' tokens');
+			assert.ok(Math.round(JSON.stringify(tool.GET_DIAGRAM).length / 4) <= 110);
+			// the worked example in the prompt is itself a valid spec — a prompt that teaches an invalid one would be worse than none
+			const example = JSON.parse(tool.PROMPT.slice(tool.PROMPT.indexOf('Example call: ') + 'Example call: '.length));
+			assert.strictEqual(require('../diagram/repair').prepare(example).status, 'ok');
+			assert.deepStrictEqual(require('../diagram/repair').prepare(example).fixes, [], 'and it is clean: no fix of any kind');
+			assert.match(tool.PROMPT, /NEVER draw boxes, arrows, trees or bars out of characters/);
+			// "generate a diagram" means a picture in the chat. Without the tool the old agent wrote a document
+			// full of diagram source instead; with it, that must not be the first thing a model reaches for.
+			assert.match(tool.PROMPT, /Asked for a diagram, DRAW it here with render_diagram\. Writing one into a file instead .* is only for when the user asks for a file\./);
+			assert.ok(!/mermaid|vega/i.test(tool.PROMPT), 'phase 1 must not tell the model to emit a format the client shows as raw source');
+		});
+
+		await testAsync('BUDGET: a diagram is a few hundred tokens (NFR-3: Graph JSON median under 600)', async () => {
+			const gallery = JSON.parse(fs.readFileSync(path.join(__dirname, 'fixtures', 'diagrams', 'gallery.json'), 'utf8'));
+			const sizes = gallery.map((g) => Math.round(JSON.stringify(g.spec).length / 4)).sort((a, b) => a - b);
+			assert.ok(sizes[Math.floor(sizes.length / 2)] < 600, 'median ' + sizes[Math.floor(sizes.length / 2)]);
+			assert.ok(sizes[sizes.length - 1] < 600, 'even the twelve-node one: ' + sizes[sizes.length - 1]);
+		});
+
+		console.log('diagramAgent: ' + n + ' tests passed');
+	} catch (e) {
+		console.error(e);
+		process.exitCode = 1;
+	} finally {
+		// @ts-ignore
+		Module._load = origLoad;
+		try { fs.rmSync(root, { recursive: true, force: true }); } catch (e) { /* temp dir */ }
+	}
+})();
diff --git a/extensions/levelcode-ai/test/diagramHost.test.js b/extensions/levelcode-ai/test/diagramHost.test.js
new file mode 100644
index 0000000..833c1b6
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramHost.test.js
@@ -0,0 +1,651 @@
+/*---------------------------------------------------------------------------------------------
+ *  Rich diagrams — the editor's half, EXECUTED — run: node test/diagramHost.test.js
+ *
+ *  docs/RICH-DIAGRAMS.md, "Safe rendering": the host accepts exactly two things from a diagram —
+ *  `openLink` and `export` — plus the user's own Retry and a request for the text fallback; and
+ *  "Context budget": a spec is stubbed at compaction, never turn by turn.
+ *
+ *  extension.js cannot be required outside the editor, so — as sessionExpiredHost.test.js does — its
+ *  own functions are sliced out of the source and run against a small stand-in for `vscode`, with the
+ *  REAL diagram service, the REAL link resolver and a real directory on disk behind them. A name that
+ *  is out of scope, or a branch that is never reached, fails here; a regex over the source would not.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const vm = require('vm');
+
+const EXT_DIR = path.join(__dirname, '..');
+const src = fs.readFileSync(path.join(EXT_DIR, 'extension.js'), 'utf8');
+const chatHtml = fs.readFileSync(path.join(EXT_DIR, 'media', 'chat.html'), 'utf8');
+const pkg = require('../package.json');
+const catalog = require('../providers/catalog');
+const sessionMemory = require('../sessionMemory');
+const { findCompactionCut, estimateMsgTokens } = require('../agentMemory');
+const { createDiagrams } = require('../diagram/service');
+const bundle = require('../diagram/bundle');
+const diagramLinks = require('../diagram/links');
+const diagramExport = require('../diagram/exportCheck');
+const diagramText = require('../diagram/text');
+const diagramTool = require('../diagram/tool');
+const scene = require('../diagram/scene');
+const layout = require('../diagram/layout');
+const theme = require('../diagram/theme');
+const repair = require('../diagram/repair');
+const ascii = require('../diagram/ascii');
+
+let n = 0;
+async function test(name, fn) { await fn(); n++; console.log('  ok - ' + name); }
+
+// ── slicing (the same brace matcher the other host suites use) ────────────────────────────────────
+function extract(name) {
+	let start = src.indexOf('function ' + name + '(');
+	assert.ok(start >= 0, 'extension.js no longer defines ' + name + '()');
+	const open = src.indexOf('{', start);
+	if (src.slice(start - 6, start) === 'async ') { start -= 6; }
+	let depth = 0, str = '', comment = '';
+	for (let i = open; i < src.length; i++) {
+		const ch = src[i], next = src[i + 1];
+		if (comment === 'line') { if (ch === '\n') { comment = ''; } continue; }
+		if (comment === 'block') { if (ch === '*' && next === '/') { comment = ''; i++; } continue; }
+		if (str) { if (ch === '\\') { i++; } else if (ch === str) { str = ''; } continue; }
+		if (ch === '/' && next === '/') { comment = 'line'; i++; continue; }
+		if (ch === '/' && next === '*') { comment = 'block'; i++; continue; }
+		if (ch === '"' || ch === "'" || ch === '`') { str = ch; continue; }
+		if (ch === '{') { depth++; }
+		else if (ch === '}' && --depth === 0) { return src.slice(start, i + 1); }
+	}
+	assert.fail('no matching closing brace found for ' + name + '()');
+}
+function decl(name) {
+	const m = new RegExp('^(?:const|let) ' + name + ' = [^;\\n]*;', 'm').exec(src);
+	assert.ok(m, 'extension.js no longer declares ' + name);
+	return m[0];
+}
+
+// ── a workspace on disk ───────────────────────────────────────────────────────────────────────────
+const tmp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'lc-dhost-')));
+process.on('exit', () => { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch (e) { /* temp */ } });
+const ws = path.join(tmp, 'app'), outside = path.join(tmp, 'outside');
+fs.mkdirSync(path.join(ws, 'src'), { recursive: true }); fs.mkdirSync(outside);
+fs.writeFileSync(path.join(ws, 'src', 'agent.js'), ['// the loop', 'const x = 1;', 'async function runAgent(ctx) {', '  return x;', '}', 'function runTool() {}', ''].join('\n'));
+fs.writeFileSync(path.join(ws, 'README.md'), '# App\n');
+fs.writeFileSync(path.join(outside, 'secret.env'), 'TOKEN=1\n');
+
+// ── the stand-in for `vscode`: records what the host asks of the editor ───────────────────────────
+function makeVscode() {
+	const ui = { warnings: [], infos: [], errors: [], opened: [], shown: [], written: [], clipboard: [], saveAs: undefined, pick: undefined, symbols: null, active: null, edits: [], untitled: [], langs: ['javascript', 'markdown', 'json'] };
+	class Position { constructor(line, character) { this.line = line; this.character = character; } }
+	class Range { constructor(a, b) { this.start = a; this.end = b; } }
+	class Selection extends Range { get active() { return this.end; } }
+	const docFor = (uri) => { const text = fs.readFileSync(uri.fsPath, 'utf8'); const lines = text.split('\n'); return { uri, languageId: /\.md$/.test(uri.fsPath) ? 'markdown' : 'javascript', lineCount: lines.length, getText: () => text, lineAt: (i) => ({ range: new Range(new Position(i, 0), new Position(i, lines[i].length)) }) }; };
+	const vscode = {
+		Position, Range, Selection,
+		Uri: { file: (p) => ({ fsPath: p, scheme: 'file' }) },
+		workspace: {
+			workspaceFolders: [{ name: 'app', uri: { fsPath: ws } }],
+			openTextDocument: async (arg) => { if (arg && arg.fsPath) { ui.opened.push(arg.fsPath); return docFor(arg); } ui.untitled.push(arg); return { untitled: true, content: arg.content, languageId: arg.language }; },
+			fs: { writeFile: async (uri, bytes) => { ui.written.push({ path: uri.fsPath, bytes: Buffer.from(bytes) }); } },
+			findFiles: async () => [{ fsPath: path.join(ws, 'README.md'), scheme: 'file' }],
+			asRelativePath: (u) => path.relative(ws, u.fsPath),
+			getWorkspaceFolder: (uri) => (uri && String(uri.fsPath).startsWith(ws + path.sep) ? { name: 'app' } : undefined)
+		},
+		window: {
+			get activeTextEditor() { return ui.active; },
+			showWarningMessage: async (m) => { ui.warnings.push(m); },
+			showInformationMessage: async (m) => { ui.infos.push(m); },
+			showErrorMessage: async (m) => { ui.errors.push(m); },
+			showSaveDialog: async (o) => { ui.saveDialog = o; return ui.saveAs ? { fsPath: ui.saveAs } : undefined; },
+			showQuickPick: async (items) => { ui.picks = items; return ui.pick === undefined ? undefined : items[ui.pick]; },
+			showTextDocument: async (doc, opts) => { ui.shown.push({ doc, opts }); const ed = { document: doc, selection: new Selection(new Position(0, 0), new Position(0, 0)), edit: async (fn) => { fn({ insert: (pos, text) => ui.edits.push({ pos, text, file: doc.uri && doc.uri.fsPath }) }); return true; } }; return ed; }
+		},
+		env: { clipboard: { writeText: async (t) => { ui.clipboard.push(t); } } },
+		commands: { executeCommand: async (cmd) => { if (cmd === 'vscode.executeDocumentSymbolProvider') { if (ui.symbols === 'throw') { throw new Error('no provider'); } return ui.symbols; } return undefined; } },
+		languages: { getLanguages: async () => ui.langs }
+	};
+	return { vscode, ui };
+}
+
+const HOST = ['clientRender', 'openDiagramLink', 'diagramMarkdown', 'exportDiagram', 'retryDiagram', 'diagramAsciiText', 'handleDiagramAction', 'serializeMsgForSummary', 'compactAgentMemory', 'resumeSession', 'isWorkspaceFile', 'webviewCsp', 'getHtml'];
+// eslint-disable-next-line no-new-func
+const makeHost = new Function('env', [
+	"'use strict';",
+	'const { vscode, fs, path, os, catalog, sessionMemory, diagrams, diagramLinks, diagramExport, diagramText, diagramTool, diagramBundle, diagramAscii, aiConfig, dbg,',
+	'  recordDiagramStat, agentFlow, findCompactionCut, estimateMsgTokens, meterModel, prepProviderRequest, authRetry, providers, checkpoints, ctx,',
+	'  sessionsManager, currentContextLimit, post, replaySessionExpired, postContextFiles, refreshSessions, focusChatView } = env;',
+	"const COMPACT_SYSTEM = 'system', COMPACT_INSTRUCTIONS = 'Summarize:\\n';",
+	decl('FILE_EXCLUDES'),
+	'let abort = null, agentMessages = [], lastAgentGoal = null, diagramsStubbed = false;',
+	'let conversation = [], currentCheckpoint = null, agentMode = true;',
+	decl('diagramFolders'),
+	...HOST.map(extract),
+	'return { ' + HOST.join(', ') + ',',
+	'  setAbort: (v) => { abort = v; }, setMessages: (m) => { agentMessages = m; }, messages: () => agentMessages,',
+	'  stubbed: () => diagramsStubbed, goal: () => lastAgentGoal, setGoal: (g) => { lastAgentGoal = g; } };'
+].join('\n'));
+
+function boot(over) {
+	const { vscode, ui } = makeVscode();
+	const stats = [], logs = [], flows = [], posted = [];
+	const settings = Object.assign({ 'diagrams.enabled': true }, over && over.settings);
+	const diagrams = createDiagrams({ resolveLink: (link) => diagramLinks.resolveLink(link, [{ name: 'app', root: ws }]), onStat: (ev) => stats.push(ev) });
+	const env = {
+		vscode, fs, path, os, catalog, sessionMemory, diagrams, diagramLinks, diagramExport, diagramText, diagramTool, diagramBundle: bundle,
+		diagramAscii: (over && over.ascii) || ascii,
+		aiConfig: () => ({ get: (k, d) => (k in settings ? settings[k] : d) }),
+		dbg: (label, data) => logs.push({ label, data }),
+		recordDiagramStat: (ev) => stats.push(ev),
+		agentFlow: async (text) => { flows.push(text); host.setGoal(text); },
+		findCompactionCut, estimateMsgTokens, meterModel: () => 'm',
+		prepProviderRequest: async () => ({ ok: true, providerId: 'claude', model: 'm' }),
+		authRetry: async (req, fn) => fn(req),
+		providers: { complete: async () => (over && over.summary) || '- built the routing diagram' },
+		checkpoints: [],
+		ctx: { extensionPath: EXT_DIR },
+		sessionsManager: () => (over && over.sessions) || null,
+		currentContextLimit: () => 200000,
+		post: (m) => posted.push(m),
+		replaySessionExpired: async () => { }, postContextFiles: () => { }, refreshSessions: () => { }, focusChatView: () => { }
+	};
+	const host = makeHost(env);
+	return { host, ui, diagrams, stats, logs, flows, posted };
+}
+const jev = () => ({
+	title: 'Jev classifies; your code decides the action',
+	nodes: [{ id: 'in', label: 'Customer message' }, { id: 'jev', label: 'Jev', accent: true, link: { path: 'src/agent.js', symbol: 'runAgent' } }, { id: 'bill', label: 'Route to billing', link: { path: 'src/agent.js', line: 6 } }],
+	edges: [{ from: 'in', to: 'jev' }, { from: 'jev', to: 'bill', label: '0.90 or more' }]
+});
+function drawn(b, input, key) { b.diagrams.beginRun(); const out = b.diagrams.render(input || jev(), { key: key || 'toolu_1', model: 'm' }); b.diagrams.endRun(); return out.post.find((m) => m.type === 'diagram').record; }
+
+(async () => {
+	try {
+		// ── the page ────────────────────────────────────────────────────────────────────────────────
+
+		await test('BUNDLE: every module that ships to the chat exists, and none can end the script block it is inlined into', async () => {
+			assert.deepStrictEqual(bundle.FILES, ['theme.js', 'schema.js', 'validate.js', 'repair.js', 'layout.js', 'scene.js', 'text.js', 'ascii.js']);
+			for (const f of bundle.FILES) {
+				const text = fs.readFileSync(path.join(EXT_DIR, 'diagram', f), 'utf8');
+				assert.ok(!bundle.BREAKS_SCRIPT.test(text), 'diagram/' + f + ' spells a script tag or an HTML comment opener — even in a comment, that ends the inline block early');
+			}
+			assert.ok(bundle.webviewSource().length > 20000);
+			for (const hostOnly of ['tool.js', 'service.js', 'stats.js', 'bundle.js', 'links.js', 'exportCheck.js']) { assert.ok(!bundle.FILES.includes(hostOnly), hostOnly + ' is the host\'s; it must not be shipped to the webview'); }
+			assert.ok(!/require\('fs'\)|child_process|require\('vscode'\)/.test(bundle.webviewSource()), 'nothing that ships to the page touches the file system or the editor API');
+		});
+
+		await test('BUNDLE: with no `require` and no `module` — a browser — the modules wire themselves up and draw the same picture', async () => {
+			const sandbox = { globalThis: null };
+			sandbox.globalThis = sandbox;
+			vm.createContext(sandbox);
+			vm.runInContext(bundle.webviewSource(), sandbox);
+			const D = sandbox.LCDiagram;
+			assert.deepStrictEqual(Object.keys(D).sort(), ['ascii', 'layout', 'repair', 'scene', 'schema', 'text', 'theme', 'validate']);
+			const spec = repair.prepare(jev()).spec;
+			const inPage = D.layout.layout(D.repair.accept(JSON.parse(JSON.stringify(spec))).spec, {});
+			assert.deepStrictEqual(JSON.parse(JSON.stringify(inPage)), JSON.parse(JSON.stringify(layout.layout(spec, {}))), 'one layout, wherever it runs');
+			assert.strictEqual(D.scene.toSvg(D.scene.build(spec, inPage, {})), scene.toSvg(scene.build(spec, layout.layout(spec, {}), {})));
+			assert.strictEqual(D.theme.css(), theme.css());
+		});
+
+		await test('PAGE: chat.html carries one placeholder for the styles and one for the modules, and the modules load first', async () => {
+			assert.strictEqual(chatHtml.split('/*__LCD_CSS__*/').length, 2);
+			assert.strictEqual(chatHtml.split('/*__LCD_JS__*/').length, 2);
+			assert.ok(chatHtml.indexOf('/*__LCD_CSS__*/') < chatHtml.indexOf('</style>'), 'the stylesheet placeholder is inside the style block');
+			const lib = chatHtml.indexOf('<script nonce="__NONCE__">/*__LCD_JS__*/</' + 'script>');
+			assert.ok(lib > 0, 'the module block carries the page nonce and nothing else');
+			assert.ok(lib < chatHtml.indexOf('const vscode = acquireVsCodeApi();'), 'and comes before the script that uses it');
+			assert.strictEqual((chatHtml.match(/<script/g) || []).length, 2, 'two script blocks: the modules, then the chat');
+			assert.ok(!/<script[^>]*\ssrc=/.test(chatHtml), 'nothing is loaded by URL');
+		});
+
+		await test('PAGE: getHtml() inlines both, under the SAME policy as before — nothing added to the CSP', async () => {
+			const b = boot();
+			const html = b.host.getHtml();
+			assert.ok(!/__LCD_|__CSP__|__NONCE__/.test(html), 'no placeholder survives');
+			assert.ok(html.includes(bundle.webviewSource()), 'the modules are in the page verbatim (a "$" in the source is not read as a pattern)');
+			assert.ok(html.includes(theme.css()), 'and so is the stylesheet');
+			const csp = /<meta http-equiv="Content-Security-Policy" content="([^"]*)">/.exec(html)[1];
+			const nonce = /script-src 'nonce-([^']+)'/.exec(csp)[1];
+			assert.deepStrictEqual(csp.split('; '), ["default-src 'none'", 'img-src data:', "style-src 'unsafe-inline'", "script-src 'nonce-" + nonce + "'"], 'the policy is exactly what it was: no new source, no unsafe-eval, no frame or connect');
+			const scripts = html.match(/<script[^>]*>/g);
+			assert.deepStrictEqual(scripts, ['<script nonce="' + nonce + '">', '<script nonce="' + nonce + '">']);
+			// the whole page still parses as two scripts: nothing in the bundle closed its block early
+			const blocks = html.split('<script nonce="' + nonce + '">').slice(1).map((s) => s.slice(0, s.indexOf('</' + 'script>')));
+			assert.strictEqual(blocks.length, 2);
+			for (const code of blocks) { assert.doesNotThrow(() => new Function(code), 'an inlined block is not valid JavaScript'); }   // eslint-disable-line no-new-func
+			assert.ok(blocks[0].includes('LCDiagram') && blocks[1].includes('acquireVsCodeApi'));
+		});
+
+		// ── the capability flag ───────────────────────────────────────────────────────────────────────
+
+		await test('CAPABILITY: rich by default; the setting or a model that opts out makes it an ASCII client', async () => {
+			assert.strictEqual(pkg.contributes.configuration.properties['levelcode.ai.diagrams.enabled'].default, true);
+			assert.strictEqual(boot().host.clientRender('claude', 'claude-opus-4-8'), 'rich');
+			assert.strictEqual(boot({ settings: { 'diagrams.enabled': false } }).host.clientRender('claude', 'claude-opus-4-8'), 'ascii');
+			assert.strictEqual(boot().host.clientRender('openai', 'o1-mini'), 'ascii', 'a model that cannot call tools cannot draw');
+			assert.strictEqual(catalog.diagramSupportForModel('openrouter', 'vendor/some-unlisted-model'), 'tool');
+			catalog.CAPS['test/no-diagrams'] = { tools: true, diagrams: false };
+			try { assert.strictEqual(boot().host.clientRender('openrouter', 'test/no-diagrams'), 'ascii', 'the registry switch: one line in CAPS'); }
+			finally { delete catalog.CAPS['test/no-diagrams']; }
+		});
+
+		// ── the two actions a diagram may ask for ───────────────────────────────────────────────────
+
+		await test('ROUTING: only openLink, export, retry and ascii are routed — and only for a real diagram id', async () => {
+			const b = boot();
+			const rec = drawn(b);
+			for (const bad of [{ action: 'openLink', id: '../../etc', node: 'jev' }, { action: 'openLink', id: 'd-1; rm -rf', node: 'jev' }, { action: 'openLink', node: 'jev' }, { action: 'runCommand', id: rec.id, command: 'whoami' }, { action: 'eval', id: rec.id }, null, undefined, {}]) {
+				await b.host.handleDiagramAction(bad);
+			}
+			assert.deepStrictEqual([b.ui.opened, b.ui.written, b.ui.clipboard, b.flows, b.posted], [[], [], [], [], []], 'nothing happened');
+			await b.host.handleDiagramAction({ action: 'openLink', id: rec.id, node: 'jev' });
+			assert.deepStrictEqual(b.ui.opened, [path.join(ws, 'src', 'agent.js')]);
+		});
+
+		await test('FALLBACK: a chat with no renderer is sent the same diagram drawn with characters — from the host\'s record, by the same layout', async () => {
+			const b = boot();
+			const rec = drawn(b);
+			// whatever the webview sends along with the request is ignored: the text is made from the record
+			await b.host.handleDiagramAction({ action: 'ascii', id: rec.id, text: 'pwned', spec: { title: 'pwned', nodes: [{ id: 'x', label: 'pwned' }], edges: [] } });
+			assert.strictEqual(b.posted.length, 1);
+			const m = b.posted[0];
+			assert.deepStrictEqual([m.type, m.id], ['diagramAscii', rec.id]);
+			assert.strictEqual(m.text, ascii.render(repair.accept(rec.spec).spec, { maxCols: 110, title: false }), 'exactly what the ASCII renderer makes of the stored spec');
+			for (const label of ['Customer message', 'Jev', 'Route to billing', '0.90 or more']) { assert.ok(m.text.includes(label), label); }
+			assert.ok(!m.text.includes('Jev classifies; your code decides the action'), 'without the title: the card shows it as its heading');
+			assert.ok(/\+-+\+/.test(m.text) && m.text.includes('>'), 'boxes and arrows');
+			assert.ok(!/pwned/.test(m.text));
+			assert.ok(m.text.split('\n').every((l) => l.length <= 110), 'no line wider than the chat can show');
+			assert.ok(/^[\x20-\x7e\n]*$/.test(m.text), 'plain ASCII: it must survive any font');
+		});
+
+		await test('FALLBACK: the page says how many characters fit, and the diagram turns downward to fit them — a number, bounded, and nothing more', async () => {
+			const b = boot();
+			const rec = drawn(b);
+			const ask = async (cols) => { b.posted.length = 0; await b.host.handleDiagramAction({ action: 'ascii', id: rec.id, cols }); return b.posted[0].text; };
+			const widest = (t) => Math.max.apply(null, t.split('\n').map((l) => l.length));
+			const wide = await ask(160), narrow = await ask(48);
+			assert.ok(widest(wide) > 48, 'given room, the flow runs left to right: ' + widest(wide));
+			assert.ok(widest(narrow) <= 48, 'in a narrow panel it fits: ' + widest(narrow));
+			assert.ok(narrow.split('\n').length > wide.split('\n').length, 'by growing downward, as the picture does');
+			const at = (n) => ascii.render(repair.accept(rec.spec).spec, { maxCols: n, title: false });
+			assert.strictEqual(await ask(3), at(40), 'never narrower than 40');
+			assert.strictEqual(await ask(1e9), at(200), 'never wider than 200');
+			for (const junk of [undefined, null, 'wide', NaN, {}, [], '120; rm -rf', -5]) { assert.strictEqual(await ask(junk), junk === -5 ? at(40) : at(110), 'cols = ' + JSON.stringify(junk)); }
+			assert.strictEqual(await ask('72'), at(72), 'a numeric string is a number');
+			assert.strictEqual(await ask(72.9), at(72));
+			// what the renderer is actually handed: a whole number between 40 and 200, whatever the page sent
+			const seen = [];
+			const spy = boot({ ascii: { render: (spec, o) => { seen.push(o); return 'text'; } } });
+			const one = drawn(spy);
+			for (const cols of [3, -5, 0, 39.9, 40, 72.9, '96', 200, 201, 1e9, Infinity, NaN, 'wide', null, undefined, {}, [150], '120; rm -rf']) { await spy.host.handleDiagramAction({ action: 'ascii', id: one.id, cols }); }
+			assert.deepStrictEqual(seen.map((o) => o.maxCols), [40, 40, 110, 40, 40, 72, 96, 200, 200, 200, 200, 110, 110, 110, 110, 110, 150, 110]);
+			assert.ok(seen.every((o) => o.title === false && Object.keys(o).sort().join() === 'maxCols,title'), 'and nothing else from the page rides along');
+		});
+
+		await test('FALLBACK: an unknown id, or a diagram with nothing drawable, answers with no text — the chat keeps the source open', async () => {
+			const b = boot();
+			await b.host.handleDiagramAction({ action: 'ascii', id: 'd-99' });
+			assert.deepStrictEqual(b.posted, [{ type: 'diagramAscii', id: 'd-99', text: '' }]);
+			b.diagrams.beginRun();
+			b.diagrams.render({ title: 'Nothing to draw' }, { key: 't1', model: 'm' });
+			const failed = b.diagrams.render({ title: 'Nothing to draw' }, { key: 't2', model: 'm' }).post.find((x) => x.type === 'diagram').record;
+			b.diagrams.endRun();
+			assert.strictEqual(failed.spec, null);
+			await b.host.handleDiagramAction({ action: 'ascii', id: failed.id });
+			assert.strictEqual(b.posted[1].text, '');
+		});
+
+		await test('FALLBACK: a diagram too awkward for characters still says what connects to what', async () => {
+			const b = boot({ ascii: { render: () => { throw new Error('too wide for a character grid'); } } });
+			const rec = drawn(b);
+			await b.host.handleDiagramAction({ action: 'ascii', id: rec.id });
+			assert.strictEqual(b.posted[0].text, diagramText.outline(repair.accept(rec.spec).spec).text);
+			assert.ok(/Customer message/.test(b.posted[0].text) && /Jev/.test(b.posted[0].text));
+		});
+
+		await test('A SESSION FILE IS INPUT TOO: a stored diagram that is not a valid spec is never acted on — no link, no export, no text, no throw', async () => {
+			const b = boot();
+			const good = drawn(b);
+			const evil = (id, spec) => ({ id, key: 'k-' + id, v: 1, status: 'ok', spec, fixes: [], notes: [], errors: [] });
+			b.diagrams.load([
+				JSON.parse(JSON.stringify(good)),
+				evil('d-2', { title: 'Nodes are not a list', nodes: 'oops', edges: [] }),
+				evil('d-3', { title: 'T', nodes: [{ id: 'a', label: 'A', link: { path: '../outside/secret.env' } }, { id: 'a', label: 'again' }], edges: [{ from: 'a', to: 'ghost' }] }),
+				evil('d-4', 'not even an object'),
+				evil('d-5', { title: 'T', nodes: [{ id: 'x', label: 'X', link: { path: 'src/agent.js' }, onclick: 'alert(1)', shape: 'box' }], edges: [], script: 'alert(1)' })
+			]);
+			assert.strictEqual(b.diagrams.get('d-1').spec.title, good.spec.title, 'a valid record comes back as it was');
+			assert.deepStrictEqual(b.diagrams.get('d-1').spec, good.spec);
+			assert.deepStrictEqual(['d-2', 'd-4'].map((id) => [b.diagrams.get(id).spec, b.diagrams.get(id).status]), [[null, 'failed'], [null, 'failed']], 'nothing drawable: kept as a diagram that was never drawn');
+			// d-3 is salvageable the way a model's would be: the duplicate renamed, the edge to nowhere dropped
+			const d3 = b.diagrams.get('d-3').spec;
+			assert.deepStrictEqual([d3.nodes.length, d3.edges.length, new Set(d3.nodes.map((n) => n.id)).size], [2, 0, 2]);
+			// d-5: the fields the schema does not know are gone before anything can read them
+			assert.deepStrictEqual(Object.keys(b.diagrams.get('d-5').spec).sort(), ['edges', 'nodes', 'title', 'v']);
+			assert.deepStrictEqual(Object.keys(b.diagrams.get('d-5').spec.nodes[0]).sort(), ['id', 'label', 'link', 'shape']);
+			for (const id of ['d-2', 'd-4']) {
+				for (const action of [{ action: 'openLink', node: 'a' }, { action: 'export', format: 'source' }, { action: 'export', format: 'mermaid' }, { action: 'export', format: 'markdown' }, { action: 'ascii', cols: 80 }]) {
+					await b.host.handleDiagramAction(Object.assign({ id }, action));
+				}
+			}
+			assert.deepStrictEqual([b.ui.opened, b.ui.clipboard, b.ui.untitled, b.ui.edits, b.ui.errors], [[], [], [], [], []], 'nothing was opened, copied or written — and nothing threw');
+			assert.deepStrictEqual(b.posted.map((m) => m.text), ['', ''], 'the text fallback has nothing to say about them');
+			// a link in a stored record is resolved at the click like any other: out of the workspace is refused
+			await b.host.handleDiagramAction({ action: 'openLink', id: 'd-3', node: 'a' });
+			assert.deepStrictEqual(b.ui.opened, []);
+			assert.strictEqual(b.ui.warnings.length, 1, 'and the user is told why nothing opened');
+			await b.host.handleDiagramAction({ action: 'openLink', id: 'd-5', node: 'x' });
+			assert.deepStrictEqual(b.ui.opened, [path.join(ws, 'src', 'agent.js')], 'while a real file in a stored record still opens');
+			assert.match(b.diagrams.fetch('d-2'), /^ERROR: diagram d-2 was never drawn/);
+			assert.deepStrictEqual(b.diagrams.stubsFor([{ role: 'assistant', content: [{ type: 'tool_use', id: 'k-d-2', name: 'render_diagram', input: {} }, { type: 'tool_use', id: 'k-d-5', name: 'render_diagram', input: {} }] }]), ['diagram: T, 1 node, id d-5']);
+		});
+
+		await test('OPEN LINK: the webview names a node; the FILE comes from the host\'s own record', async () => {
+			const b = boot();
+			const rec = drawn(b);
+			// a path smuggled in the message is never read — there is no field for one
+			await b.host.handleDiagramAction({ action: 'openLink', id: rec.id, node: 'jev', path: path.join(outside, 'secret.env'), link: { path: '/etc/passwd' } });
+			assert.deepStrictEqual(b.ui.opened, [path.join(ws, 'src', 'agent.js')]);
+			// a node with no link, and a node that does not exist, open nothing
+			await b.host.openDiagramLink(rec.id, 'in'); await b.host.openDiagramLink(rec.id, 'ghost'); await b.host.openDiagramLink('d-99', 'jev');
+			assert.strictEqual(b.ui.opened.length, 1);
+			assert.deepStrictEqual(b.stats.filter((e) => e.type === 'link'), [{ type: 'link' }], 'one click, counted once');
+		});
+
+		await test('OPEN LINK: lands on the symbol — from the language\'s own symbols, else by text, else on the line', async () => {
+			const b = boot();
+			const rec = drawn(b);
+			b.ui.symbols = [{ name: 'Outer', range: { start: { line: 0 } }, children: [{ name: 'runAgent', selectionRange: { start: { line: 2 } }, range: { start: { line: 2 } } }] }];
+			await b.host.openDiagramLink(rec.id, 'jev');
+			assert.strictEqual(b.ui.shown[0].opts.selection.start.line, 2, 'the symbol provider\'s answer (line 3, zero-based 2)');
+			b.ui.symbols = 'throw';   // no provider for this language
+			await b.host.openDiagramLink(rec.id, 'jev');
+			assert.strictEqual(b.ui.shown[1].opts.selection.start.line, 2, 'found by text: `async function runAgent(` is on line 3');
+			await b.host.openDiagramLink(rec.id, 'bill');
+			assert.strictEqual(b.ui.shown[2].opts.selection.start.line, 5, 'a line number is used as given (6 → zero-based 5)');
+			assert.strictEqual(b.ui.shown[2].opts.preview, false);
+		});
+
+		await test('OPEN LINK: checked AGAIN at the click — a file swapped for a link out of the workspace is refused', async () => {
+			const b = boot();
+			const target = path.join(ws, 'src', 'later.js');
+			fs.writeFileSync(target, 'function ok() {}\n');
+			const spec = jev(); spec.nodes[1].link = { path: 'src/later.js' };
+			const rec = drawn(b, spec);
+			assert.deepStrictEqual(rec.spec.nodes[1].link, { path: 'src/later.js' }, 'a real file when it was drawn');
+			fs.rmSync(target);
+			let linked = true;
+			try { fs.symlinkSync(path.join(outside, 'secret.env'), target); } catch (e) { linked = false; }
+			if (!linked) { console.log('    (symlinks unavailable — skipped)'); return; }
+			await b.host.openDiagramLink(rec.id, 'jev');
+			assert.deepStrictEqual(b.ui.opened, [], 'nothing outside the workspace is opened');
+			assert.match(b.ui.warnings[0], /that link cannot be opened — it is a link to somewhere outside this workspace/);
+			assert.deepStrictEqual(b.stats.filter((e) => e.type === 'link'), [], 'and a refused click is not a click');
+			fs.rmSync(target);
+		});
+
+		await test('EXPORT source / Mermaid: made by the host from its own record — whatever data the webview sends is ignored', async () => {
+			const b = boot();
+			const rec = drawn(b);
+			await b.host.handleDiagramAction({ action: 'export', id: rec.id, format: 'source', data: 'IGNORED' });
+			assert.deepStrictEqual(b.ui.clipboard, [diagramText.toSource(rec.spec)]);
+			assert.ok(!b.ui.clipboard[0].includes('IGNORED'));
+			await b.host.handleDiagramAction({ action: 'export', id: rec.id, format: 'mermaid', data: 'IGNORED' });
+			assert.deepStrictEqual(b.ui.untitled, [{ content: diagramText.toMermaid(rec.spec), language: 'plaintext' }]);
+			b.ui.langs.push('mermaid');
+			await b.host.exportDiagram(rec.id, 'mermaid');
+			assert.strictEqual(b.ui.untitled[1].language, 'mermaid', 'as Mermaid when the editor knows the language');
+			assert.deepStrictEqual(b.stats.filter((e) => e.type === 'export').map((e) => e.format), ['source', 'mermaid', 'mermaid']);
+		});
+
+		await test('EXPORT markdown: inserted at the cursor of an open Markdown file, as a fenced Mermaid block', async () => {
+			const b = boot();
+			const rec = drawn(b);
+			const { vscode } = makeVscode();
+			const inserted = [];
+			b.ui.active = { document: { languageId: 'markdown', uri: { fsPath: path.join(ws, 'README.md'), scheme: 'file' } }, selection: { active: new vscode.Position(4, 2) }, edit: async (fn) => { fn({ insert: (pos, text) => inserted.push({ pos, text }) }); return true; } };
+			await b.host.exportDiagram(rec.id, 'markdown');
+			assert.strictEqual(inserted.length, 1);
+			assert.deepStrictEqual([inserted[0].pos.line, inserted[0].pos.character], [4, 2]);
+			assert.match(inserted[0].text, /^\n```mermaid\n---\ntitle: "Jev classifies; your code decides the action"\n---\nflowchart LR\n[\s\S]*\n```\n$/);
+			// no Markdown file in front: pick one, and it goes at the end of that
+			b.ui.active = null; b.ui.pick = 0;
+			await b.host.exportDiagram(rec.id, 'markdown');
+			assert.deepStrictEqual(b.ui.picks.map((p) => p.label), ['README.md']);
+			assert.strictEqual(b.ui.edits.length, 1);
+			assert.strictEqual(b.ui.edits[0].file, path.join(ws, 'README.md'));
+			assert.strictEqual(b.ui.edits[0].pos.line, 1, 'the end of a two-line file');
+			// dismissed picker: nothing is inserted anywhere
+			b.ui.pick = undefined;
+			await b.host.exportDiagram(rec.id, 'markdown');
+			assert.strictEqual(b.ui.edits.length, 1);
+		});
+
+		await test('EXPORT svg / png: bytes from the webview are checked before one is written — and hostile ones are not', async () => {
+			const b = boot();
+			const rec = drawn(b);
+			const geo = layout.layout(rec.spec);
+			const good = scene.toSvg(scene.build(rec.spec, geo, { title: true, background: true, standalone: true, css: theme.css({ resolved: theme.PALETTES.dark }) }));
+			b.ui.saveAs = path.join(tmp, 'out.svg');
+			for (const evil of ['<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</' + 'script></svg>', good.replace('<g', '<g onload="x"'), good.replace('</svg>', '<a href="https://example.invalid"/></svg>'), good.replace('<![CDATA[', '<![CDATA[@import url(//example.invalid);'), '<html></html>', 42, null, { svg: good }]) {
+				await b.host.exportDiagram(rec.id, 'svg', evil);
+			}
+			assert.deepStrictEqual(b.ui.written, [], 'not one byte of any of them was written');
+			assert.strictEqual(b.ui.warnings.length, 8, 'and each refusal is said');
+			assert.strictEqual(b.ui.saveDialog, undefined, 'the save dialog is not even opened for data that failed the check');
+			await b.host.exportDiagram(rec.id, 'svg', good);
+			assert.deepStrictEqual(b.ui.written.map((w) => [w.path, w.bytes.toString('utf8') === good]), [[path.join(tmp, 'out.svg'), true]]);
+			// png
+			b.ui.saveAs = path.join(tmp, 'out.png');
+			for (const junk of ['not base64 !!', Buffer.from('<svg/>').toString('base64'), '', 7]) { await b.host.exportDiagram(rec.id, 'png', junk); }
+			assert.strictEqual(b.ui.written.length, 1, 'something that is not a PNG is not written as one');
+			const png = Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), Buffer.alloc(80, 1)]);
+			await b.host.exportDiagram(rec.id, 'png', png.toString('base64'));
+			assert.ok(b.ui.written[1].bytes.equals(png));
+			// a cancelled dialog writes nothing
+			b.ui.saveAs = undefined;
+			await b.host.exportDiagram(rec.id, 'svg', good);
+			assert.strictEqual(b.ui.written.length, 2);
+			assert.deepStrictEqual(b.stats.filter((e) => e.type === 'export').map((e) => e.format), ['svg', 'png'], 'only what was actually saved is counted');
+		});
+
+		await test('EXPORT: the file name comes from the title — redacted first, like a session export', async () => {
+			const b = boot();
+			const pat = ['ghp', '_', 'abcdefghijklmnopqrstuvwxyz0123456789'].join('');   // split: push protection
+			const spec = jev(); spec.title = 'Deploy with ' + pat + ' safely';
+			const rec = drawn(b, spec);
+			const good = scene.toSvg(scene.build(rec.spec, layout.layout(rec.spec), { standalone: true }));
+			b.ui.saveAs = path.join(tmp, 'x.svg');
+			await b.host.exportDiagram(rec.id, 'svg', good);
+			const suggested = b.ui.saveDialog.defaultUri.fsPath;
+			assert.ok(suggested.startsWith(ws + path.sep), 'offered in the workspace');
+			assert.ok(!/ghp|abcdefghij/i.test(path.basename(suggested)), 'a token in a title cannot leak into the save path: ' + path.basename(suggested));
+			assert.match(path.basename(suggested), /^deploy-with-.*\.svg$/);
+		});
+
+		await test('RETRY: the user asks for another go — never while a run is active, and it does not replace their own goal', async () => {
+			const b = boot();
+			b.diagrams.beginRun();
+			const bad = jev(); bad.edges.push({ from: 'jev', to: 'ghost' });
+			b.diagrams.render(bad, { key: 'k1' });
+			const rec = b.diagrams.endRun()[0].record;
+			assert.strictEqual(rec.status, 'degraded');
+			b.host.setGoal('the user\'s real goal');
+			b.host.setAbort({});   // a run is in flight
+			await b.host.handleDiagramAction({ action: 'retry', id: rec.id });
+			assert.deepStrictEqual(b.flows, [], 'Retry does nothing mid-run');
+			b.host.setAbort(null);
+			await b.host.handleDiagramAction({ action: 'retry', id: rec.id });
+			assert.strictEqual(b.flows.length, 1);
+			assert.match(b.flows[0], /^Redraw the diagram “Jev classifies; your code decides the action” \(id d-1\) with render_diagram\./);
+			assert.ok(b.flows[0].includes('/edges/2/to: unknown node "ghost". Known ids: in, jev, bill.'), 'the model is told what was wrong');
+			assert.ok(b.flows[0].includes('1 edge dropped: unknown nodes'));
+			assert.strictEqual(b.host.goal(), 'the user\'s real goal', 'Retry/Continue on the response bar still mean what the user asked');
+		});
+
+		// ── context budget: stubbed at compaction, never turn by turn ───────────────────────────────
+
+		const longChat = (b, withDiagram) => {
+			const msgs = [];
+			for (let t = 0; t < 8; t++) {
+				msgs.push({ role: 'user', content: 'goal ' + t });
+				if (withDiagram && t === 1) {
+					b.diagrams.beginRun();
+					const out = b.diagrams.render(jev(), { key: 'toolu_d' });
+					b.diagrams.endRun();
+					msgs.push({ role: 'assistant', content: [{ type: 'text', text: 'Here.' }, { type: 'tool_use', id: 'toolu_d', name: 'render_diagram', input: jev() }] });
+					msgs.push({ role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_d', content: out.result }] });
+				}
+				msgs.push({ role: 'assistant', content: 'Done: step ' + t });
+			}
+			return msgs;
+		};
+
+		await test('COMPACTION: a diagram in the summarized stretch becomes one line, with its id — and get_diagram is switched on', async () => {
+			const b = boot();
+			const msgs = longChat(b, true);
+			b.host.setMessages(msgs);
+			assert.strictEqual(b.host.stubbed(), false);
+			const r = await b.host.compactAgentMemory();
+			assert.strictEqual(r.ok, true);
+			const head = b.host.messages()[0].content;
+			assert.match(head, /^\[Summary of the earlier conversation, compacted to save context\]\n\n- built the routing diagram\n\nDiagrams drawn earlier \(their specs are no longer in this conversation — call get_diagram with the id before editing one\):\n- diagram: Jev classifies; your code decides the action, 3 nodes, id d-1$/);
+			assert.strictEqual(b.host.stubbed(), true, 'the next run is offered get_diagram');
+			assert.ok(!JSON.stringify(b.host.messages()).includes('"nodes"'), 'the spec itself is gone from the conversation');
+			assert.strictEqual(JSON.parse(b.diagrams.fetch('d-1')).nodes.length, 3, 'and still on file for get_diagram');
+		});
+
+		await test('COMPACTION: no diagram in the stretch — no note, and no extra tool', async () => {
+			const b = boot();
+			b.host.setMessages(longChat(b, false));
+			const r = await b.host.compactAgentMemory();
+			assert.strictEqual(r.ok, true);
+			assert.strictEqual(b.host.messages()[0].content, '[Summary of the earlier conversation, compacted to save context]\n\n- built the routing diagram');
+			assert.strictEqual(b.host.stubbed(), false);
+		});
+
+		await test('COMPACTION: the summarizer is shown a diagram as one short line, not as its spec', async () => {
+			const b = boot();
+			const line = b.host.serializeMsgForSummary({ role: 'assistant', content: [{ type: 'text', text: 'Here.' }, { type: 'tool_use', id: 't', name: 'render_diagram', input: jev() }] });
+			assert.strictEqual(line, 'Assistant: Here.\n[draws a diagram: Jev classifies; your code decides the action]');
+			const other = b.host.serializeMsgForSummary({ role: 'assistant', content: [{ type: 'tool_use', id: 't', name: 'read_file', input: { path: 'a.js' } }] });
+			assert.strictEqual(other, 'Assistant: [calls read_file {"path":"a.js"}]', 'every other tool is serialized as before');
+		});
+
+		// ── reopening a session ─────────────────────────────────────────────────────────────────────
+
+		const stored = (b) => {
+			// what sessions.resume() hands back: the full conversation, the part that fits, and the stored records
+			// (drawn in an earlier editor session, against the same workspace — so its links resolved)
+			const first = createDiagrams({ resolveLink: (link) => diagramLinks.resolveLink(link, [{ name: 'app', root: ws }]) });
+			first.beginRun(); const out = first.render(jev(), { key: 'toolu_d', model: 'm' }); first.endRun();
+			const records = first.takeNew();
+			const full = [
+				{ role: 'user', content: 'how is it routed?' },
+				{ role: 'assistant', content: [{ type: 'text', text: 'Here.' }, { type: 'tool_use', id: 'toolu_d', name: 'render_diagram', input: jev() }] },
+				{ role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_d', content: out.result }] },
+				{ role: 'assistant', content: 'Done: drawn.' },
+				{ role: 'user', content: 'and then?' },
+				{ role: 'assistant', content: 'Done: then it is billed.' }
+			];
+			return { records, full };
+		};
+		const resumeWith = async (tier) => {
+			const data = stored();
+			const r = { id: 's1', entry: { title: 'Routing' }, full: data.full, messages: tier === 1 ? data.full : data.full.slice(4), plan: { tier }, note: '', diagrams: data.records,
+				turns: require('../sessionEvents').toDisplayTurns(data.full, data.records) };
+			const b = boot({ sessions: { resume: () => r } });
+			await b.host.resumeSession('s1');
+			return { b, r };
+		};
+
+		await test('RESUME: the session\'s diagrams come back as stored — clickable, exportable, replayed in place', async () => {
+			const { b, r } = await resumeWith(1);
+			// Checked on the way in (a session file is input too) — and a valid record comes through that check
+			// equal to what was stored: same spec, same status, same fixes. Nothing is repaired again.
+			assert.deepStrictEqual(b.diagrams.get('d-1'), r.diagrams[0]);
+			assert.strictEqual(JSON.stringify(b.diagrams.get('d-1').spec), JSON.stringify(r.diagrams[0].spec), 'field for field, in the stored order');
+			const resumed = b.posted.find((m) => m.type === 'sessionResumed');
+			assert.deepStrictEqual(resumed.turns.map((t) => t.role), ['user', 'assistant', 'diagram', 'assistant', 'user', 'assistant']);
+			assert.strictEqual(resumed.turns[2].record.id, 'd-1');
+			assert.strictEqual(b.host.stubbed(), false, 'the whole conversation fits: nothing was stubbed, so no get_diagram');
+			assert.deepStrictEqual(b.host.messages(), r.full);
+			await b.host.openDiagramLink('d-1', 'jev');
+			assert.deepStrictEqual(b.ui.opened, [path.join(ws, 'src', 'agent.js')], 'a node clicked after reopening opens its file');
+		});
+
+		await test('RESUME: when the earlier part did not fit, the model is told which diagrams it can no longer see — and how to fetch one', async () => {
+			const { b, r } = await resumeWith(2);
+			const note = b.host.messages()[0];
+			assert.strictEqual(note.role, 'user');
+			assert.match(note.content, /^\[Resumed session — the earlier part of this conversation \(4 messages\) was omitted/);
+			assert.ok(note.content.includes('Diagrams drawn in that part (call get_diagram with the id before editing one):\n- diagram: Jev classifies; your code decides the action, 3 nodes, id d-1]'), note.content);
+			assert.strictEqual(b.host.stubbed(), true, 'so get_diagram is offered on the next run');
+			assert.deepStrictEqual(b.host.messages().slice(1), r.full.slice(4));
+			assert.strictEqual(JSON.parse(b.diagrams.fetch('d-1')).title, 'Jev classifies; your code decides the action');
+			// the user still sees the whole transcript, picture included
+			assert.ok(b.posted.find((m) => m.type === 'sessionResumed').turns.some((t) => t.role === 'diagram'));
+		});
+
+		// ── what may be written to disk ────────────────────────────────────────────────────────────
+
+		await test('EXPORT CHECK: an SVG is accepted only if the painter could have produced it', async () => {
+			const spec = repair.prepare(jev()).spec;
+			const good = scene.toSvg(scene.build(spec, layout.layout(spec), { title: true, background: true, standalone: true, css: theme.css({ resolved: theme.PALETTES.light }) }));
+			assert.deepStrictEqual(diagramExport.checkSvg(good), { ok: true });
+			assert.deepStrictEqual(diagramExport.checkSvg('  ' + good + '\n'), { ok: true }, 'surrounding whitespace is not an attack');
+			const reasons = {
+				'<svg><script>1</script></svg>': 'element <script> is not allowed',
+				'<svg><foreignObject></foreignObject></svg>': 'element <foreignObject> is not allowed',
+				'<svg><image/></svg>': 'element <image> is not allowed',
+				'<svg onload="x"></svg>': 'attribute "onload" is not allowed',
+				'<svg><g style="x"></g></svg>': 'attribute "style" is not allowed',
+				'<svg><g id="x"></g></svg>': 'attribute "id" is not allowed',
+				'<svg><!-- x --></svg>': 'declarations and comments are not allowed',
+				'<?xml version="1.0"?><svg></svg>': 'not an SVG document',
+				'<svg><!DOCTYPE x [<!ENTITY a "b">]></svg>': 'declarations and comments are not allowed',
+				'<svg><g></svg>': 'tags do not nest',
+				'<svg><g>': 'not an SVG document',
+				'<svg><style>a{}</style></svg>': 'stylesheet is not the painter\'s',
+				'<svg><style><![CDATA[a{b:url(x)}]]></style></svg>': 'stylesheet is not the painter\'s',
+				'<svg><style><![CDATA[@import "x";]]></style></svg>': 'stylesheet is not the painter\'s',
+				'<svg><style><![CDATA[a{}]]></style><style><![CDATA[b{}]]></style></svg>': 'more than one stylesheet',
+				'<svg><text a=b>x</text></svg>': 'malformed tag'
+			};
+			for (const [input, reason] of Object.entries(reasons)) { assert.deepStrictEqual(diagramExport.checkSvg(input), { ok: false, reason }, input); }
+			assert.strictEqual(diagramExport.checkSvg('<svg>' + 'x'.repeat(diagramExport.MAX_SVG) + '</svg>').reason, 'too large');
+			for (const junk of [null, undefined, 5, {}, [], Buffer.from(good)]) { assert.strictEqual(diagramExport.checkSvg(junk).reason, 'not text'); }
+		});
+
+		await test('EXPORT CHECK: a PNG is a PNG — by its bytes, not by its name', async () => {
+			const png = Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), Buffer.alloc(100, 7)]);
+			const ok = diagramExport.checkPng(png.toString('base64'));
+			assert.ok(ok.ok && ok.bytes.equals(png));
+			assert.ok(diagramExport.checkPng('data:image/png;base64,' + png.toString('base64')).ok, 'a data-URL prefix is tolerated');
+			assert.strictEqual(diagramExport.checkPng(Buffer.from('GIF89a' + 'x'.repeat(100)).toString('base64')).reason, 'not a PNG image');
+			assert.strictEqual(diagramExport.checkPng(Buffer.from('<svg onload=x>' + ' '.repeat(100)).toString('base64')).reason, 'not a PNG image');
+			assert.strictEqual(diagramExport.checkPng('<svg/>').reason, 'not base64');
+			assert.strictEqual(diagramExport.checkPng(png.slice(0, 20).toString('base64')).reason, 'not a PNG image', 'eight magic bytes and nothing else is not an image');
+			for (const junk of ['', null, undefined, 4, {}]) { assert.strictEqual(diagramExport.checkPng(junk).reason, 'no image data'); }
+		});
+
+		await test('EXPORT CHECK: a file name is plain words — never a path, never empty', async () => {
+			assert.strictEqual(diagramExport.fileStem('Jev classifies; your code decides the action'), 'jev-classifies-your-code-decides-the-action');
+			assert.strictEqual(diagramExport.fileStem('../../etc/passwd'), 'etc-passwd');
+			assert.strictEqual(diagramExport.fileStem('C:\\Windows\\system32'), 'c-windows-system32');
+			assert.strictEqual(diagramExport.fileStem('   '), 'diagram');
+			assert.strictEqual(diagramExport.fileStem(null), 'diagram');
+			assert.ok(diagramExport.fileStem('x'.repeat(300)).length <= 60);
+			assert.ok(!/[\/\\.]/.test(diagramExport.fileStem('a/b\\c.d')));
+		});
+
+		console.log('diagramHost: ' + n + ' tests passed');
+	} catch (e) {
+		console.error(e);
+		process.exitCode = 1;
+	}
+})();
diff --git a/extensions/levelcode-ai/test/diagramLinks.test.js b/extensions/levelcode-ai/test/diagramLinks.test.js
new file mode 100644
index 0000000..5b8feac
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramLinks.test.js
@@ -0,0 +1,115 @@
+/*---------------------------------------------------------------------------------------------
+ *  Rich diagrams — code links — run: node test/diagramLinks.test.js
+ *
+ *  docs/RICH-DIAGRAMS.md, "Link safety": "openLink only resolves paths inside the current workspace,
+ *  after normalizing `..` segments and symlinks. Anything else is shown as plain text."
+ *
+ *  A link is model output. These tests are the attacker's side of it: every way to name a file the
+ *  user did not open — `..`, an absolute path, a URL scheme, a symlink planted inside the repo — run
+ *  against a real directory tree on disk.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { resolveLink, findSymbolLine } = require('../diagram/links');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+// A workspace with one real file, a secret OUTSIDE it, and symlinks that try to reach the secret.
+const tmp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'lc-links-')));
+process.on('exit', () => { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch (e) { /* temp */ } });
+const ws = path.join(tmp, 'app'), other = path.join(tmp, 'lib'), outside = path.join(tmp, 'outside');
+for (const d of [path.join(ws, 'src'), other, outside]) { fs.mkdirSync(d, { recursive: true }); }
+fs.writeFileSync(path.join(ws, 'src', 'agent.js'), 'function runAgent() {}\n');
+fs.writeFileSync(path.join(other, 'util.js'), 'exports.x = 1;\n');
+fs.writeFileSync(path.join(outside, 'secret.env'), 'TOKEN=1\n');
+let symlinks = true;
+try {
+	fs.symlinkSync(path.join(outside, 'secret.env'), path.join(ws, 'src', 'innocent.js'));
+	fs.symlinkSync(outside, path.join(ws, 'vendor'));
+	fs.symlinkSync(path.join(ws, 'src', 'agent.js'), path.join(ws, 'alias.js'));
+} catch (e) { symlinks = false; }
+const one = [{ name: 'app', root: ws }];
+const two = [{ name: 'app', root: ws }, { name: 'lib', root: other }];
+const ok = (r) => { assert.strictEqual(r.ok, true, JSON.stringify(r)); return r; };
+const no = (r) => { assert.strictEqual(r.ok, false, 'should have been refused: ' + JSON.stringify(r)); return r; };
+
+test('INSIDE: a workspace-relative path to a real file resolves, and is reported relative', () => {
+	const r = ok(resolveLink({ path: 'src/agent.js' }, one));
+	assert.strictEqual(r.path, 'src/agent.js');
+	assert.strictEqual(r.abs, path.join(ws, 'src', 'agent.js'));
+	assert.strictEqual(ok(resolveLink({ path: './src/../src/agent.js' }, one)).path, 'src/agent.js', '`..` that stays inside is just normalised');
+	assert.strictEqual(ok(resolveLink({ path: path.join(ws, 'src', 'agent.js') }, one)).path, 'src/agent.js', 'an absolute path INTO the workspace is the same file');
+});
+
+test('OUTSIDE: `..` out of the workspace is refused, however it is dressed', () => {
+	for (const p of ['../outside/secret.env', 'src/../../outside/secret.env', '../../../../../../etc/passwd', 'src/../../../etc/hosts', '..', '../app/../outside/secret.env']) {
+		assert.match(no(resolveLink({ path: p }, one)).reason, /outside this workspace|no such file/, p);
+	}
+});
+
+test('OUTSIDE: an absolute path to anywhere else is refused', () => {
+	for (const p of [path.join(outside, 'secret.env'), '/etc/passwd', os.homedir(), path.join(os.homedir(), '.ssh', 'id_rsa')]) {
+		assert.strictEqual(no(resolveLink({ path: p }, one)).reason, 'outside this workspace', p);
+	}
+});
+
+test('SCHEMES: anything that is a URL is refused before the file system is touched', () => {
+	const touched = [];
+	const spy = { statSync: (p) => { touched.push(p); return fs.statSync(p); }, realpathSync: (p) => { touched.push(p); return fs.realpathSync(p); } };
+	for (const p of ['javascript:alert(1)', 'file:///etc/passwd', 'http://evil.example/x.js', 'https://evil.example/', 'vscode://file/etc/passwd', 'command:workbench.action.terminal.new', 'data:text/html,<script>1</script>', 'JaVaScRiPt:alert(1)', 'ftp://x']) {
+		assert.strictEqual(no(resolveLink({ path: p }, one, { fs: spy })).reason, 'not a file path', p);
+	}
+	assert.deepStrictEqual(touched, [], 'refused on sight');
+});
+
+test('SYMLINKS: a link inside the repo that points outside it is refused — the REAL path decides', () => {
+	if (!symlinks) { console.log('    (symlinks unavailable on this file system — skipped)'); return; }
+	assert.strictEqual(no(resolveLink({ path: 'src/innocent.js' }, one)).reason, 'it is a link to somewhere outside this workspace');
+	assert.strictEqual(no(resolveLink({ path: 'vendor/secret.env' }, one)).reason, 'it is a link to somewhere outside this workspace', 'through a symlinked DIRECTORY too');
+	assert.strictEqual(ok(resolveLink({ path: 'alias.js' }, one)).path, 'alias.js', 'a symlink that stays inside the workspace is fine');
+});
+
+test('SYMLINKS: a workspace that is itself reached through a symlink still works', () => {
+	if (!symlinks) { console.log('    (skipped)'); return; }
+	const via = path.join(tmp, 'via');
+	fs.symlinkSync(ws, via);
+	assert.strictEqual(ok(resolveLink({ path: 'src/agent.js' }, [{ name: 'app', root: via }])).path, 'src/agent.js');
+});
+
+test('FILES ONLY: a directory, a missing file and an empty path are not links', () => {
+	assert.strictEqual(no(resolveLink({ path: 'src' }, one)).reason, 'no such file in this workspace');
+	assert.strictEqual(no(resolveLink({ path: 'src/nope.js' }, one)).reason, 'no such file in this workspace');
+	for (const junk of [{ path: '' }, { path: '   ' }, {}, null, undefined, { path: 42 }, { path: ['src/agent.js'] }]) { assert.strictEqual(no(resolveLink(junk, one)).reason, 'no path'); }
+	assert.strictEqual(no(resolveLink({ path: 'src/agent.js\u0000.png' }, one)).reason, 'not a path');
+	assert.strictEqual(no(resolveLink({ path: 'src/agent.js' }, [])).reason, 'no folder is open');
+	assert.strictEqual(no(resolveLink({ path: 'src/agent.js' }, null)).reason, 'no folder is open');
+});
+
+test('MULTI-ROOT: a folder-name prefix picks that folder, and the answer keeps the prefix', () => {
+	assert.strictEqual(ok(resolveLink({ path: 'lib/util.js' }, two)).path, 'lib/util.js');
+	assert.strictEqual(ok(resolveLink({ path: 'app/src/agent.js' }, two)).path, 'app/src/agent.js');
+	assert.strictEqual(ok(resolveLink({ path: 'util.js' }, two)).path, 'lib/util.js', 'an unprefixed path is found in whichever folder has it');
+	assert.strictEqual(no(resolveLink({ path: 'lib/../../outside/secret.env' }, two)).reason, 'outside this workspace');
+});
+
+test('SYMBOLS: the text fallback finds where a name is defined, not just where it is mentioned', () => {
+	const src = ['// runAgent drives the loop', 'const x = runAgent;', 'async function runAgent(ctx) {', '  return runTool(ctx);', '}', 'const runTool = async (tu) => {};', 'class Planner {}', 'def render_diagram(spec):'].join('\n');
+	assert.strictEqual(findSymbolLine(src, 'runAgent'), 3);
+	assert.strictEqual(findSymbolLine(src, 'runTool'), 6);
+	assert.strictEqual(findSymbolLine(src, 'Planner'), 7);
+	assert.strictEqual(findSymbolLine(src, 'render_diagram'), 8);
+	assert.strictEqual(findSymbolLine(src, 'Agent.runAgent()'), 3, 'a qualified name is matched by its last part');
+	assert.strictEqual(findSymbolLine(src, 'x'), 2);
+	assert.strictEqual(findSymbolLine(src, 'nowhere'), null);
+	assert.strictEqual(findSymbolLine(src, 'run'), null, 'a whole-word match — "run" is not "runAgent"');
+	for (const junk of ['', '   ', '.*', '(', 'a b', null, undefined]) { assert.doesNotThrow(() => findSymbolLine(src, junk)); }
+	assert.strictEqual(findSymbolLine(src, '.*'), null, 'a symbol is never used as a pattern');
+});
+
+console.log('diagramLinks: ' + n + ' tests passed');
diff --git a/extensions/levelcode-ai/test/diagramSession.test.js b/extensions/levelcode-ai/test/diagramSession.test.js
new file mode 100644
index 0000000..0abac9b
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramSession.test.js
@@ -0,0 +1,234 @@
+/*---------------------------------------------------------------------------------------------
+ *  Rich diagrams — stored with the session — run: node test/diagramSession.test.js
+ *
+ *  docs/RICH-DIAGRAMS.md, "Storage": "The repaired spec is stored and marked as repaired, so
+ *  re-opening a chat never re-runs repair." And NFR-4: old chats keep rendering.
+ *
+ *  A diagram is the FINAL record — what was drawn, after the ladder — appended to the session as its
+ *  own event. Reopening the session hands those records back untouched and replays each one at the
+ *  place in the answer where the model drew it. Nothing here validates, fixes, or asks a model.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const E = require('../sessionEvents');
+const store = require('../sessionStore');
+const { createSessions } = require('../sessions');
+const { createDiagrams } = require('../diagram/service');
+const tool = require('../diagram/tool');
+const text = require('../diagram/text');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+const jev = () => ({
+	title: 'Jev classifies; your code decides the action',
+	nodes: [{ id: 'in', label: 'Customer message' }, { id: 'jev', label: 'Jev', accent: true }, { id: 'bill', label: 'Route to billing' }],
+	edges: [{ from: 'in', to: 'jev' }, { from: 'jev', to: 'bill', label: '0.90 or more' }]
+});
+const broken = () => { const s = jev(); s.edges.push({ from: 'jev', to: 'ghost' }); return s; };
+
+/** A turn as the agent loop leaves it: prose, a diagram call, its result, more prose. */
+function turnWith(calls) {
+	const msgs = [{ role: 'user', content: 'how is a message routed?' }];
+	for (const c of calls) {
+		msgs.push({ role: 'assistant', content: [{ type: 'text', text: c.before }, { type: 'tool_use', id: c.id, name: 'render_diagram', input: c.input }] });
+		msgs.push({ role: 'user', content: [{ type: 'tool_result', tool_use_id: c.id, content: c.result }] });
+	}
+	msgs.push({ role: 'assistant', content: [{ type: 'text', text: 'Done: that is the whole route.' }] });
+	return msgs;
+}
+function fresh() {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lc-dsess-'));
+	let t = Date.parse('2026-10-04T10:00:00Z');
+	const m = createSessions({ root, slug: 'proj', projectPath: '/proj', memory: false, now: () => new Date(t += 1000) });
+	return { root, m };
+}
+/** Draw with the real service, so the records are exactly what the host would store. */
+function draw(service, specs) {
+	service.beginRun();
+	const calls = specs.map((input, i) => {
+		const id = 'toolu_' + (i + 1);
+		const out = service.render(input, { key: id, model: 'test-model' });
+		return { id, input, result: out.result, before: 'Here is diagram ' + (i + 1) + '.' };
+	});
+	service.endRun();
+	return calls;
+}
+
+test('NAME: the session replay looks for the same tool the agent offers', () => {
+	assert.strictEqual(E.DIAGRAM_TOOL, tool.RENDER_DIAGRAM.name);
+});
+
+test('STORE: a turn\'s diagrams are appended after it, and the conversation itself is untouched', () => {
+	const { root, m } = fresh();
+	const service = createDiagrams();
+	const msgs = turnWith(draw(service, [jev()]));
+	const records = service.takeNew();
+	assert.strictEqual(records.length, 1);
+	m.recordTurn(msgs, 'test-model', { diagrams: records });
+	const id = m.liveId();
+	const parsed = store.readSession(store.sessionFile(root, 'proj', id));
+	assert.deepStrictEqual(parsed.events.map((e) => e.kind), ['user', 'agent', 'diagram']);
+	assert.deepStrictEqual(E.eventsToMessages(parsed.events), msgs, 'the rebuilt messages are exactly the conversation — no diagram record leaks into what the model is sent');
+	assert.deepStrictEqual(m.diagrams(id), JSON.parse(JSON.stringify(records)));
+	const entry = store.deriveEntry(parsed.meta, parsed.events);
+	assert.strictEqual(entry.turns, 1, 'a diagram is not a turn');
+	assert.strictEqual(entry.title, 'how is a message routed?');
+	assert.deepStrictEqual(service.takeNew(), [], 'taken once');
+});
+
+test('REPLAY: reopening shows each diagram where the model drew it — between the prose before and after', () => {
+	const { m } = fresh();
+	const service = createDiagrams();
+	const two = { title: 'A second picture', nodes: [{ id: 'x', label: 'X' }, { id: 'y', label: 'Y' }], edges: [{ from: 'x', to: 'y' }] };
+	const msgs = turnWith(draw(service, [jev(), two]));
+	m.recordTurn(msgs, 'test-model', { diagrams: service.takeNew() });
+	const id = m.liveId();
+	m.seal('done');
+	const r = m.resume(id);
+	assert.deepStrictEqual(r.turns.map((t) => t.role + (t.text ? ':' + t.text : ':' + t.record.id)), [
+		'user:how is a message routed?',
+		'assistant:Here is diagram 1.', 'diagram:d-1',
+		'assistant:Here is diagram 2.', 'diagram:d-2',
+		'assistant:Done: that is the whole route.'
+	]);
+	assert.strictEqual(r.turns[2].key, 'toolu_1');
+	assert.deepStrictEqual(r.diagrams.map((d) => d.id), ['d-1', 'd-2']);
+	assert.deepStrictEqual(E.toDisplayTurns(r.full), r.turns.filter((t) => t.role !== 'diagram'), 'without the records the replay is exactly the prose it always was');
+});
+
+test('REPLAY: never re-runs repair — a stored record comes back exactly as stored, whatever today\'s rules say', () => {
+	const { m } = fresh();
+	// A record as an OLDER build might have stored it: degraded, with a note, and a field this build does not know.
+	const old = { id: 'd-1', key: 'toolu_1', v: 1, at: '2026-01-01T00:00:00.000Z', status: 'degraded', repaired: false,
+		spec: { v: 1, title: 'Drawn long ago', direction: 'right', nodes: Array.from({ length: 15 }, (_, i) => ({ id: 'n' + i, label: 'Step ' + i })), edges: [] },
+		fixes: [], notes: ['15 nodes — over the 12-node limit, drawn anyway'], errors: ['/nodes: 15 nodes, max 12.'], legacyField: 'kept' };
+	const msgs = turnWith([{ id: 'toolu_1', input: old.spec, result: '{"ok":true,"id":"d-1"}', before: 'Here.' }]);
+	m.recordTurn(msgs, 'm', { diagrams: [old] });
+	const id = m.liveId(); m.seal('done');
+	const r = m.resume(id);
+	assert.deepStrictEqual(r.diagrams, [old], 'byte for byte');
+	assert.deepStrictEqual(r.turns.find((t) => t.role === 'diagram').record, old);
+});
+
+test('REPLAY: a repaired diagram is shown once, at the call that got it right; a failed first try leaves nothing behind', () => {
+	const { m } = fresh();
+	const service = createDiagrams();
+	const msgs = turnWith(draw(service, [broken(), jev()]));
+	const records = service.takeNew();
+	assert.deepStrictEqual(records.map((r) => [r.key, r.status, !!r.repaired]), [['toolu_2', 'ok', true]], 'one record: the repaired one, marked as repaired');
+	m.recordTurn(msgs, 'm', { diagrams: records });
+	const id = m.liveId(); m.seal('done');
+	const turns = m.resume(id).turns;
+	assert.deepStrictEqual(turns.filter((t) => t.role === 'diagram').map((t) => t.key), ['toolu_2']);
+	const at = turns.findIndex((t) => t.role === 'diagram');
+	assert.strictEqual(turns[at - 1].text, 'Here is diagram 2.', 'under the prose of the call that drew it');
+});
+
+test('REPLAY: a drawing that a later one replaced is not replayed — the chat never showed both', () => {
+	const { m } = fresh();
+	const service = createDiagrams();
+	const down = jev(); down.direction = 'down';
+	const msgs = turnWith(draw(service, [jev(), down]));
+	const records = service.takeNew();
+	assert.strictEqual(records[1].replaces, 'd-1');
+	m.recordTurn(msgs, 'm', { diagrams: records });
+	const id = m.liveId(); m.seal('done');
+	const r = m.resume(id);
+	assert.deepStrictEqual(r.turns.filter((t) => t.role === 'diagram').map((t) => t.record.id), ['d-2']);
+	assert.deepStrictEqual(r.diagrams.map((d) => d.id), ['d-1', 'd-2'], 'but both stay on file — the store is append-only');
+});
+
+test('REPLAY: a diagram the run had to settle on its own (the model never answered) is stored and replayed too', () => {
+	const { m } = fresh();
+	const service = createDiagrams();
+	service.beginRun();
+	const out = service.render(broken(), { key: 'toolu_1', model: 'm' });
+	assert.match(out.result, /^ERROR/);
+	const settled = service.endRun();
+	assert.strictEqual(settled[0].record.status, 'degraded');
+	const msgs = [{ role: 'user', content: 'draw it' },
+		{ role: 'assistant', content: [{ type: 'text', text: 'Drawing.' }, { type: 'tool_use', id: 'toolu_1', name: 'render_diagram', input: broken() }] },
+		{ role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_1', content: out.result }] },
+		{ role: 'assistant', content: [{ type: 'text', text: 'Done: in words instead.' }] }];
+	m.recordTurn(msgs, 'm', { diagrams: service.takeNew() });
+	const id = m.liveId(); m.seal('done');
+	const turns = m.resume(id).turns;
+	assert.deepStrictEqual(turns.map((t) => t.role), ['user', 'assistant', 'diagram', 'assistant']);
+	assert.deepStrictEqual(turns[2].record.notes, ['1 edge dropped: unknown nodes']);
+});
+
+test('RELOAD: the service takes the stored records back — ids carry on, links and get_diagram work', () => {
+	const { m } = fresh();
+	const first = createDiagrams();
+	m.recordTurn(turnWith(draw(first, [jev()])), 'm', { diagrams: first.takeNew() });
+	const id = m.liveId(); m.seal('done');
+	const second = createDiagrams();
+	second.load(m.resume(id).diagrams);
+	assert.strictEqual(second.get('d-1').spec.title, 'Jev classifies; your code decides the action');
+	assert.strictEqual(second.byToolUse('toolu_1').id, 'd-1');
+	assert.strictEqual(JSON.parse(second.fetch('d-1')).nodes.length, 3);
+	second.beginRun();
+	assert.strictEqual(JSON.parse(second.render({ title: 'Next', nodes: [{ id: 'a', label: 'A' }], edges: [] }, { key: 'toolu_9' }).result).id, 'd-2', 'a new diagram does not reuse an id');
+	assert.deepStrictEqual(second.takeNew().map((r) => r.id), ['d-2'], 'and only the new one is new');
+	second.load([{ id: 'not-an-id' }, null, { id: 'd-7', key: 'k', spec: null, status: 'failed' }]);
+	assert.deepStrictEqual(second.list().map((r) => r.id), ['d-7'], 'junk in a session file is skipped, not trusted');
+	assert.match(second.fetch('d-7'), /^ERROR: diagram d-7 was never drawn/);
+});
+
+test('FORK: a forked session carries its diagrams with it', () => {
+	const { m } = fresh();
+	const service = createDiagrams();
+	m.recordTurn(turnWith(draw(service, [jev()])), 'm', { diagrams: service.takeNew() });
+	const id = m.liveId(); m.seal('done');
+	const forked = m.fork(id);
+	assert.ok(forked && forked !== id);
+	assert.deepStrictEqual(m.diagrams(forked).map((d) => d.id), ['d-1']);
+	assert.deepStrictEqual(m.diagrams(id).map((d) => d.id), ['d-1'], 'the original is untouched');
+});
+
+test('STUBS: at compaction a spec is replaced by one line — and only for diagrams that were drawn', () => {
+	const service = createDiagrams();
+	const msgs = turnWith(draw(service, [jev(), { title: 'Nothing', nodes: [], edges: [] }]));
+	assert.deepStrictEqual(service.stubsFor(msgs), ['diagram: Jev classifies; your code decides the action, 3 nodes, id d-1']);
+	assert.deepStrictEqual(service.stubsFor(msgs.slice(0, 1)), [], 'none in a stretch with no diagram');
+	assert.deepStrictEqual(service.stubsFor(null), []);
+});
+
+test('EXPORT: a session copied as Markdown carries each diagram as a Mermaid block, where it stood — and scrubbed', () => {
+	const service = createDiagrams();
+	const secret = jev(); secret.nodes[0].label = 'key sk-live-1234567890';
+	const msgs = turnWith(draw(service, [secret]));
+	const md = E.toMarkdown({ title: 'Routing', updatedAt: '2026-10-04T10:00:00Z' }, msgs, {
+		diagrams: service.list(),
+		diagram: (r) => ({ lang: 'mermaid', body: text.toMermaid(r.spec) }),
+		redact: (s) => s.replace(/sk-live-\d+/g, '[redacted]')
+	});
+	assert.match(md, /_LevelCode session · 2026-10-04 · 3 turns_/, 'the diagram is part of an answer, not a turn');
+	const at = md.indexOf('```mermaid\n');
+	assert.ok(at > md.indexOf('Here is diagram 1.') && at < md.indexOf('Done: that is the whole route.'), 'between the prose before and after');
+	assert.match(md, /```mermaid\n---\ntitle: "Jev classifies; your code decides the action"\n---\nflowchart LR\n/);
+	assert.ok(md.includes('in["key [redacted]"]'), 'a label is free text: it is scrubbed like the rest');
+	assert.ok(!md.includes('sk-live-1234567890'));
+	assert.strictEqual((md.match(/^```/gm) || []).length, 2, 'one fence opens, one closes');
+	// without a renderer, the diagram is still named rather than silently dropped
+	assert.match(E.toMarkdown({ title: 'R' }, msgs, { diagrams: service.list() }), /\n_\[diagram: Jev classifies; your code decides the action\]_\n/);
+	// and without the records at all, the export is the prose it always was
+	assert.ok(!/mermaid|diagram:/.test(E.toMarkdown({ title: 'R' }, msgs)));
+});
+
+test('EXPORT: nothing in a label can close the fence early', () => {
+	const service = createDiagrams();
+	const msgs = turnWith(draw(service, [jev()]));
+	const md = E.toMarkdown({ title: 'R' }, msgs, { diagrams: service.list(), diagram: () => ({ lang: 'mermaid', body: 'flowchart LR\n  a["```` four backticks"]' }) });
+	assert.match(md, /\n`````mermaid\nflowchart LR\n {2}a\["```` four backticks"\]\n`````\n/, 'the fence is one backtick longer than the longest run inside');
+	const odd = E.toMarkdown({ title: 'R' }, msgs, { diagrams: service.list(), diagram: () => ({ lang: 'mer maid`\n# x', body: 'x' }) });
+	assert.match(odd, /\n```mermaidx\nx\n```\n/, 'and the language tag is reduced to a plain word');
+});
+
+console.log('diagramSession: ' + n + ' tests passed');
diff --git a/extensions/levelcode-ai/test/diagramStats.test.js b/extensions/levelcode-ai/test/diagramStats.test.js
new file mode 100644
index 0000000..99db139
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramStats.test.js
@@ -0,0 +1,142 @@
+/*---------------------------------------------------------------------------------------------
+ *  Rich diagrams — the counters behind the rollout gates — run: node test/diagramStats.test.js
+ *
+ *  docs/RICH-DIAGRAMS.md, "Telemetry and evaluation": first-pass valid rate, fix share by rung, top
+ *  error classes, render time, diagram tokens, ASCII leaks, code-link use — "Telemetry records
+ *  formats, error classes, timings and token counts; never labels, paths or code."
+ *
+ *  These counters are local (the host keeps them in the editor's own storage). The tests pin the
+ *  arithmetic the gates are read from, and the one promise that matters more than the arithmetic:
+ *  nothing a diagram SAYS can end up in them.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const S = require('../diagram/stats');
+const { createDiagrams } = require('../diagram/service');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+const call = (model, outcome, extra) => Object.assign({ type: 'call', model, format: 'graph', outcome }, extra);
+const fold = (events) => events.reduce((s, ev) => S.record(s, ev), S.empty('2026-10-04'));
+
+test('RATES: first-pass valid, auto-fixed, model-repaired and degraded — as shares of the calls that reached a verdict', () => {
+	const events = [];
+	for (let i = 0; i < 90; i++) { events.push(call('model-a', 'clean', { tokens: 250 })); }
+	for (let i = 0; i < 4; i++) { events.push(call('model-a', 'tidied')); }
+	for (let i = 0; i < 2; i++) { events.push(call('model-a', 'fixed')); }
+	for (let i = 0; i < 3; i++) { events.push(call('model-a', 'bounced', { errorClasses: { 'accent-count': 1 } })); events.push(call('model-a', 'repaired')); }
+	events.push(call('model-a', 'bounced', { errorClasses: { 'unknown-node': 2 } }), call('model-a', 'degraded', { errorClasses: { 'unknown-node': 2 } }));
+	const sum = S.summarize(fold(events));
+	assert.strictEqual(sum.calls, 104, 'every call is counted');
+	assert.strictEqual(sum.overall.verdicts, 100, 'a bounce is not a verdict — the call that answers it is');
+	assert.deepStrictEqual([sum.overall.firstPassValid, sum.overall.autoFixed, sum.overall.modelRepaired, sum.overall.degraded], [90, 6, 3, 1]);
+	assert.deepStrictEqual(sum.topErrors, [{ cls: 'accent-count', count: 3 }, { cls: 'unknown-node', count: 2 }], 'classes are counted once per call they appear in, most frequent first');
+	assert.deepStrictEqual(sum.byModel.map((m) => m.model), ['model-a']);
+});
+
+test('RATES: kept per model — the eval compares models, not an average of them', () => {
+	const sum = S.summarize(fold([call('good', 'clean'), call('good', 'clean'), call('weak', 'bounced', { errorClasses: { count: 1 } }), call('weak', 'degraded', { errorClasses: { count: 1 } }), call('weak', 'failed')]));
+	const by = Object.fromEntries(sum.byModel.map((m) => [m.model, m]));
+	assert.strictEqual(by.good.firstPassValid, 100);
+	assert.strictEqual(by.weak.firstPassValid, 0);
+	assert.strictEqual(by.weak.degraded, 100, 'failed counts with degraded: both ended without the diagram the model meant');
+	assert.deepStrictEqual(by.weak.topErrors, [{ cls: 'count', count: 2 }]);
+	assert.deepStrictEqual(by.good.topErrors, []);
+	assert.strictEqual(S.summarize(S.empty()).overall.firstPassValid, null, 'no calls, no rate — not 0%, and not 100%');
+});
+
+test('TOKENS and RENDER TIME: histograms, read back as the bucket a quantile falls in', () => {
+	const events = [];
+	for (const t of [120, 180, 240, 260, 310, 330, 350, 380, 420, 1500]) { events.push(call('m', 'clean', { tokens: t })); }
+	for (const ms of [3, 4, 5, 6, 7, 9, 12, 14, 40, 280]) { events.push({ type: 'render', ok: true, ms }); }
+	events.push({ type: 'render', ok: false, message: 'boom' }, { type: 'render', ok: true, ms: 5, flipped: true });
+	const sum = S.summarize(fold(events));
+	assert.deepStrictEqual(sum.tokens, { median: 400, p95: 2000 }, 'median in the 301–400 bucket; the outlier sets p95');
+	assert.strictEqual(sum.renderMs.p50, 8);
+	assert.strictEqual(sum.renderMs.p95, 300);
+	assert.deepStrictEqual([sum.renderMs.rendered, sum.renderMs.failed, sum.renderMs.flipped], [11, 1, 1]);
+	assert.strictEqual(S.quantile([0, 0, 0], [1, 2], 0.5), null);
+	assert.strictEqual(S.quantile([0, 0, 5], [1, 2], 0.5), Infinity, 'past the last bound is "more", not a made-up number');
+});
+
+test('LEAKS, LINKS, EXPORTS: counted', () => {
+	const sum = S.summarize(fold([{ type: 'answer', asciiArt: false }, { type: 'answer', asciiArt: true }, { type: 'answer', asciiArt: false }, { type: 'link' }, { type: 'link' }, { type: 'export', format: 'svg' }, { type: 'export', format: 'png' }, { type: 'export', format: 'svg' }, { type: 'export', format: 'exe' }]));
+	assert.deepStrictEqual(sum.asciiLeaks, { answers: 3, leaks: 1 });
+	assert.strictEqual(sum.linkClicks, 2);
+	assert.deepStrictEqual(sum.exports, { svg: 2, png: 1 }, 'an unknown format is not a format');
+});
+
+test('PRIVACY: nothing a diagram says can reach the counters — whatever the event carries', () => {
+	const secret = 'ACME-INTERNAL-payments-ledger';
+	const nosy = call('m', 'degraded', {
+		title: secret, labels: [secret], path: '/Users/x/' + secret + '.rb', spec: { title: secret, nodes: [{ id: 'a', label: secret }] }, source: secret, message: secret,
+		errorClasses: { 'unknown-node': 1, [secret]: 1, ['unknown node "' + secret + '"']: 1, 'UPPER': 1, 'a b': 1 },
+		fixClasses: { length: 1, [secret + '.rb']: 1 },
+		tokens: 300
+	});
+	let s = fold([nosy, { type: 'render', ok: false, message: secret }, { type: 'export', format: secret }, { type: 'answer', asciiArt: true, text: secret }, { type: 'link', path: secret, node: secret }]);
+	const dump = JSON.stringify(s) + JSON.stringify(S.summarize(s));
+	assert.ok(!dump.includes(secret), 'the title/label/path leaked into the stats');
+	assert.ok(!/ACME|payments|ledger/i.test(dump));
+	assert.deepStrictEqual(Object.keys(s.errors), ['unknown-node'], 'only class names shaped like class names are kept');
+	assert.deepStrictEqual(Object.keys(s.fixes), ['length']);
+	// and the real service sends nothing but enums and numbers in the first place
+	const events = [];
+	const service = createDiagrams({ onStat: (ev) => events.push(ev) });
+	service.beginRun();
+	service.render({ title: secret, nodes: [{ id: 'a', label: secret, link: { path: secret + '.rb' } }], edges: [{ from: 'a', to: 'nowhere-' + secret }] }, { key: 'k', model: 'm' });
+	service.endRun();
+	service.noteAnswer('A plain answer mentioning ' + secret);
+	assert.ok(events.length >= 3);
+	assert.ok(!JSON.stringify(events).includes(secret), 'an event from the service carried text: ' + JSON.stringify(events));
+	for (const ev of events) { for (const [k, v] of Object.entries(ev)) { assert.ok(['string', 'number', 'boolean', 'undefined'].includes(typeof v) || k === 'errorClasses' || k === 'fixClasses', k + ' is a ' + typeof v); } }
+});
+
+test('BOUNDED: a flood of model ids or class names cannot grow the store without limit', () => {
+	let s = S.empty();
+	for (let i = 0; i < 500; i++) { s = S.record(s, call('model-' + i, 'clean', { errorClasses: { ['cls-' + i]: 1 } })); }
+	assert.ok(Object.keys(s.byModel).length <= 40, String(Object.keys(s.byModel).length));
+	assert.ok(Object.keys(s.errors).length <= 60);
+	s = S.record(S.empty(), call('x'.repeat(5000), 'clean'));
+	assert.ok(Object.keys(s.byModel)[0].length <= 80);
+	assert.ok(JSON.stringify(s).length < 2000);
+});
+
+test('ROBUST: junk events are ignored; an unknown outcome is not counted; an old store starts over', () => {
+	let s = S.empty('2026-10-04');
+	for (const junk of [null, undefined, 3, 'call', {}, { type: 'call' }, { type: 'call', outcome: 'exploded' }, { type: 'render', ms: NaN }, { type: 'render', ms: -4 }, { type: 'nope' }]) { s = S.record(s, junk); }
+	assert.strictEqual(s.calls, 0);
+	assert.strictEqual(s.rendered, 2, 'a render with a nonsense duration still happened; only the duration is dropped');
+	assert.strictEqual(s.renderMs.reduce((a, b) => a + b, 0), 0);
+	const old = { v: 0, since: '2025-01-01', calls: 99, byModel: 'corrupt' };
+	const fresh = S.record(old, call('m', 'clean'));
+	assert.strictEqual(fresh.v, S.VERSION); assert.strictEqual(fresh.calls, 1); assert.strictEqual(fresh.since, '2025-01-01');
+	assert.doesNotThrow(() => S.summarize(null)); assert.doesNotThrow(() => S.summarize({ v: 99 }));
+});
+
+test('END TO END: what the service reports adds up to the spec\'s table', () => {
+	let s = S.empty('2026-10-04');
+	const service = createDiagrams({ onStat: (ev) => { s = S.record(s, ev); } });
+	const good = { title: 'T', nodes: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }], edges: [{ from: 'a', to: 'b' }] };
+	const sloppy = { title: 'T2', rankdir: 'LR', nodes: [{ id: 'a', label: 'A', shape: 'diamond' }], edges: [] };
+	const long = { title: 'T3', nodes: [{ id: 'a', label: 'A label that is far longer than twenty-eight characters' }], edges: [] };
+	const bad = { title: 'T4', nodes: [{ id: 'x', label: 'X' }], edges: [{ from: 'x', to: 'ghost' }] };
+	service.beginRun(); service.render(good, { key: '1', model: 'm' }); service.endRun();
+	service.beginRun(); service.render(sloppy, { key: '2', model: 'm' }); service.endRun();
+	service.beginRun(); service.render(long, { key: '3', model: 'm' }); service.endRun();
+	service.beginRun(); service.render(bad, { key: '4', model: 'm' }); service.render(Object.assign({}, bad, { edges: [] }), { key: '5', model: 'm' }); service.endRun();   // bounced, then repaired
+	service.beginRun(); service.render(bad, { key: '6', model: 'm' }); service.render(bad, { key: '7', model: 'm' }); service.endRun();                                   // bounced, then degraded
+	service.beginRun(); service.render(bad, { key: '8', model: 'm' }); service.endRun();                                                                                    // bounced, never answered → settled
+	const sum = S.summarize(s);
+	const m = s.byModel.m.outcomes;
+	assert.deepStrictEqual(m, { clean: 1, tidied: 1, fixed: 1, bounced: 3, repaired: 1, degraded: 2 });
+	assert.strictEqual(sum.overall.verdicts, 6);
+	assert.deepStrictEqual([sum.overall.firstPassValid, sum.overall.autoFixed, sum.overall.modelRepaired, sum.overall.degraded], [16.7, 33.3, 16.7, 33.3]);
+	assert.strictEqual(sum.topErrors[0].cls, 'unknown-node');
+	assert.ok(sum.tokens.median <= 100, 'these are tiny specs: ' + sum.tokens.median);
+});
+
+console.log('diagramStats: ' + n + ' tests passed');
diff --git a/extensions/levelcode-ai/test/diagramUi.test.js b/extensions/levelcode-ai/test/diagramUi.test.js
new file mode 100644
index 0000000..00f2034
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramUi.test.js
@@ -0,0 +1,169 @@
+/*---------------------------------------------------------------------------------------------
+ *  Rich diagrams — the chat page's part — run: node test/diagramUi.test.js
+ *
+ *  The page cannot be booted here (no DOM), so what CAN be pinned from the source is pinned: that
+ *  the diagram code in media/chat.html has no way to turn a label into markup, asks the host for
+ *  exactly the actions the spec allows, validates before it lays out, and falls back instead of
+ *  going blank. `scripts/diagram-browser-check.js` is the other half — it loads this same page in
+ *  headless Chrome and checks what actually happens.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const html = fs.readFileSync(path.join(__dirname, '..', 'media', 'chat.html'), 'utf8');
+const css = html.slice(html.indexOf('<style'), html.indexOf('</style>'));
+const scriptOpen = html.lastIndexOf('<script');
+const script = html.slice(html.indexOf('>', scriptOpen) + 1, html.indexOf('</script>', scriptOpen));
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+/** The diagram code: from its banner comment to the message listener that follows it. */
+const start = script.indexOf('// ── Rich diagrams (docs/RICH-DIAGRAMS.md)');
+const end = script.indexOf("window.addEventListener('message'", start);
+assert.ok(start > 0 && end > start, 'the diagram block is no longer where this suite looks for it');
+const block = script.slice(start, end);
+/** Code only — comments say things like "never innerHTML", and must not trip the checks below. */
+// Line comments first: one of them may mention a glob, and a block-comment pattern run first would
+// take that as an opener and swallow real code up to the next closer.
+const code = block.replace(/^\s*\/\/.*$/gm, '').replace(/([;{}),])\s*\/\/[^\n]*$/gm, '$1').replace(/\/\*[\s\S]*?\*\//g, '');
+const fn = (name) => {
+	const at = code.indexOf('function ' + name + '(');
+	assert.ok(at >= 0, name + '() is gone');
+	const next = code.indexOf('\n  function ', at + 10);
+	return code.slice(at, next > at ? next : code.length);
+};
+
+test('SAFE: nothing in the diagram code can turn text into markup, or run it', () => {
+	for (const sink of ['innerHTML', 'outerHTML', 'insertAdjacentHTML', 'document.write', 'eval(', 'new Function', 'srcdoc', 'DOMParser', 'createContextualFragment', 'setHTML']) {
+		assert.ok(code.indexOf(sink) < 0, 'the diagram code uses ' + sink + ' — a label must only ever reach the page as a text node');
+	}
+	assert.ok(!/\.(href|action|formAction)\s*=/.test(code), 'it assigns a URL to something');
+	assert.ok(!/location\s*[.=]|window\.open|fetch\(|XMLHttpRequest|WebSocket|importScripts|navigator\.sendBeacon/.test(code), 'it can navigate or reach the network');
+	assert.ok(!/setAttribute\(\s*['"]on/i.test(code), 'it sets an event-handler attribute');
+	assert.ok(code.length > 6000, 'the block under test is the real one');
+});
+
+test('SAFE: the picture is built by the painter alone — the page never creates an SVG element itself', () => {
+	assert.ok(code.indexOf('createElementNS') < 0, 'only scene.mount() creates SVG elements; it is the one with the allow-list');
+	assert.match(fn('lcdDraw'), /LCD\.scene\.mount\(LCD\.scene\.build\(spec, geo, \{\}\), document\)/);
+	assert.match(fn('lcdEl'), /e\.textContent = text/, 'the card chrome sets text with textContent');
+	// the only image the page loads is the diagram's own SVG, as a data: URL, to rasterise a PNG
+	const srcs = (code.match(/[\w.]+\.src\s*=[^\n]*/g) || []).map((l) => l.trim());
+	assert.deepStrictEqual(srcs, ["img.src = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(svg.text);"]);
+});
+
+test('VALIDATE FIRST: a record is accepted by the validator before anything lays it out (FR-3)', () => {
+	const draw = fn('lcdDraw');
+	const accept = draw.indexOf('LCD.repair.accept(record.spec)'), lay = draw.indexOf('LCD.layout.layout(');
+	assert.ok(accept > 0 && lay > accept, 'layout runs before the spec was accepted');
+	assert.match(draw, /if \(a\.ok\)\{ spec = a\.spec;/, 'only an accepted spec is used');
+	const refused = /if \(!spec\)\{\s*(?:if \(record\.spec && !LCD && !quiet\)\{[^\n]*\}\s*)?lcdFailed\(card, record\);\s*return;\s*\}/.exec(draw);
+	assert.ok(refused, 'a refused spec goes to lcdFailed() and nowhere else');
+	assert.ok(refused.index > accept && refused.index + refused[0].length < lay, 'and that return comes before the renderer is reached');
+});
+
+test('NEVER BLANK: a render that throws becomes an ASCII drawing; a spec that cannot be drawn shows its source', () => {
+	const draw = fn('lcdDraw');
+	assert.match(draw, /catch \(e\) \{[\s\S]*LCD\.ascii\.render\(spec, \{ maxCols: lcdCols\(card\), title: false \}\)[\s\S]*catch \(e2\) \{ pre\.textContent = LCD\.text\.toSource\(spec\); \}/, 'picture → ASCII → source');
+	assert.match(draw, /catch \(e\) \{[\s\S]*'The picture could not be drawn, so a text version is shown instead\.'[\s\S]*card\.insertBefore\(why, stage\);/, 'and the card says that is what happened');
+	const failed = fn('lcdFailed');
+	assert.match(failed, /'Retry'/); assert.match(failed, /lcd-errors/); assert.match(failed, /'What was sent'/);
+	assert.match(code, /const LCD = window\.LCDiagram \|\| null;/, 'the page survives the modules not loading');
+});
+
+test('FALLBACK: with no renderer in the page, the host is asked for a text version of the same diagram — and the source stays until it comes', () => {
+	const failed = fn('lcdFailed');
+	assert.match(failed, /const noRenderer = !!\(record\.spec && !LCD\);/, 'the spec is fine and the page is not: that is the one case');
+	assert.match(failed, /if \(noRenderer\)\{[\s\S]*?lcdAct\(record\.id, 'ascii', \{ cols: lcdCols\(card\) \}\);\s*\}/, 'asked for by id, with the width of the card in characters and nothing else');
+	assert.match(fn('lcdCols'), /return Math\.max\(40, Math\.min\(200, Math\.floor\(/, 'a whole number in a sane range, whatever the page measured');
+	assert.match(failed, /stage\.hidden = true;/, 'the empty block takes no room while the answer is on its way');
+	assert.match(failed, /det\.open = !errs\.length;/, 'until then the source is what is shown — never a blank card');
+	assert.match(failed, /record\.notes\.join\(' · '\)/, 'a degraded diagram still says what it lost');
+	assert.match(failed, /if \(!noRenderer\)\{ ban\.appendChild\(lcdBtn\('Retry'/, 'no Retry here: asking the model again would not load the renderer');
+	const show = fn('lcdAscii');
+	assert.match(show, /if \(!text\)\{ return; \}/, 'no text from the host: leave the source open');
+	assert.match(show, /card\._asciiPre\.textContent = text;/, 'the text goes in as text');
+	assert.match(show, /card\.dataset\.id !== String\(m\.id\)/, 'into the card it was asked for, and no other');
+	assert.match(show, /det\.open = false;/, 'and the source folds away once there is something better to read');
+	assert.match(fn('lcdDraw'), /if \(record\.spec && !LCD && !quiet\)\{ vscode\.postMessage\(\{ type: 'diagramRendered', id: record\.id, ok: false,/, 'and it is counted as a render that failed');
+});
+
+test('HOST ACTIONS: the page can ask for exactly openLink, export, retry and the text fallback — and a link is named by its node', () => {
+	const actions = new Set();
+	for (const m of code.matchAll(/lcdAct\([^,]+,\s*'([a-zA-Z]+)'/g)) { actions.add(m[1]); }
+	assert.deepStrictEqual(Array.from(actions).sort(), ['ascii', 'export', 'openLink', 'retry']);
+	for (const m of code.matchAll(/lcdAct\(([^)]*)'retry'([^)]*)\)/g)) { assert.strictEqual(m[2], '', 'retry carries an id and nothing else: ' + m[0]); }
+	const links = code.match(/'openLink',\s*\{[^}]*\}/g) || [];
+	assert.ok(links.length >= 2);
+	for (const l of links) { assert.match(l, /^'openLink',\s*\{ node: link\.getAttribute\('data-lc-link'\) \}$/, 'an openLink carries the node id and nothing else: ' + l); }
+	// every message type the block posts
+	const types = new Set();
+	for (const m of code.matchAll(/type:\s*'([a-zA-Z]+)'/g)) { types.add(m[1]); }
+	assert.deepStrictEqual(Array.from(types).sort(), ['copy', 'diagramAction', 'diagramRendered', 'notice']);
+	// only an image export carries bytes; the rest are produced by the host from its own record
+	const withData = (code.match(/format:\s*'([a-z]+)',\s*data:/g) || []).map((s) => /'([a-z]+)'/.exec(s)[1]).sort();
+	assert.deepStrictEqual(withData, ['png', 'svg']);
+	for (const f of ['source', 'mermaid', 'markdown']) { assert.match(code, new RegExp("\\{ format: '" + f + "' \\}"), f + ' is requested without data'); }
+});
+
+test('WIRED: placeholder, picture, the end of a run, a reset and a replayed session all reach the diagram code', () => {
+	assert.match(script, /else if \(m\.type === 'diagramPending'\)\{ lcdPending\(m\); \}/);
+	assert.match(script, /else if \(m\.type === 'diagram'\)\{ lcdShow\(m\); \}/);
+	assert.match(script, /else if \(m\.type === 'diagramAscii'\)\{ lcdAscii\(m\); \}/);
+	assert.match(script, /m\.type === 'agentDone'\)\{ clearStatus\(\); finishAgentBubble\(\); lcdSweep\(\);/, 'a placeholder that never got its picture is removed when the run ends');
+	assert.match(script, /m\.type === 'agentError'\)\{ clearStatus\(\); finishAgentBubble\(\); closeGroup\(\); lcdSweep\(\);/, '…and when it fails');
+	assert.match(script, /curGroup = null; turnLabeled = false;\s*\n\s*lcdReset\(\);/, 'New chat drops the references to cards that went with the log');
+	assert.match(script, /if \(t\.role === 'diagram'\)\{ lcdShow\(\{ key: t\.key, record: t\.record \}\); continue; \}/, 'a resumed session replays its diagrams from the stored records');
+	assert.match(fn('lcdPending'), /if \(card\.dataset\.id\)\{ return; \}/, 'a late placeholder can never blank a finished picture');
+	assert.match(fn('lcdHost'), /finishAgentBubble\(\);\s*const body = add\('assistant', ''\);/, 'a diagram sits in the answer, where the model put it');
+});
+
+test('STYLE: the title is the type scale\'s 15 semibold, the picture never outgrows the column, and motion is optional', () => {
+	assert.ok(css.includes('/*__LCD_CSS__*/'), 'the house style is injected here from diagram/theme.js');
+	assert.match(css, /\.lcd-title-text \{ font-size: 15px; font-weight: 600; line-height: 20px;/);
+	assert.match(css, /\.lcd-stage svg \{ display: block; max-width: 100%; height: auto; \}/);
+	assert.match(css, /@media \(prefers-reduced-motion: reduce\) \{ \.lcd-skel-bar \{ animation: none; \}/);
+	assert.match(css, /#lcdZoom\[hidden\] \{ display: none; \}/);
+	assert.match(html, /<div id="lcdZoom" hidden role="dialog" aria-modal="true" aria-label="Diagram, full size">/);
+	// no colour of its own inside the card chrome except the two neutral fallbacks every card in this file uses
+	const chrome = css.slice(css.indexOf('/*__LCD_CSS__*/'), css.length);
+	for (const m of chrome.matchAll(/#[0-9a-fA-F]{3,8}\b/g)) { assert.ok(['#73c991', '#1e1e1e'].includes(m[0]), 'a literal colour in the diagram chrome: ' + m[0]); }
+});
+
+test('ACCESSIBLE: the outline is hidden from sight but NOT from a screen reader; pictures and nodes are reachable', () => {
+	const rule = /\.lcd-sr \{([^}]*)\}/.exec(css);
+	assert.ok(rule, '.lcd-sr is gone');
+	assert.match(rule[1], /clip-path: inset\(50%\)/);
+	assert.ok(!/display:\s*none|visibility:\s*hidden/.test(rule[1]), 'display:none / visibility:hidden would take the outline out of the accessibility tree too');
+	const draw = fn('lcdDraw');
+	assert.match(draw, /svg\.setAttribute\('aria-describedby', descId\)/);
+	assert.match(draw, /lcdEl\('p', 'lcd-sr', LCD\.text\.outline\(spec\)\.text\)/);
+	assert.match(draw, /card\.setAttribute\('aria-label', 'Diagram: ' \+ title\)/);
+	assert.match(draw, /stage\.tabIndex = 0; stage\.setAttribute\('role', 'button'\)/, 'the picture can be opened from the keyboard');
+	assert.match(code, /e\.key === 'Enter' \|\| e\.key === ' '/, 'and so can a linked node');
+	assert.match(fn('lcdPending'), /card\.setAttribute\('role', 'status'\); card\.setAttribute\('aria-live', 'polite'\)/);
+	assert.match(code, /e\.key === 'Escape'\)\{ e\.stopPropagation\(\); e\.preventDefault\(\); lcdZoomClose\(\); \}/);
+});
+
+test('THEME: export is the only moment a colour is baked in — the live picture keeps its tokens', () => {
+	const resolved = fn('lcdResolved');
+	assert.match(resolved, /probe\.style\.color = 'var\(--lcd-' \+ name \+ '\)'/);
+	assert.match(fn('lcdSvg'), /css: LCD\.theme\.css\(\{ resolved: lcdResolved\(card\) \}\)/);
+	assert.match(fn('lcdDraw'), /LCD\.scene\.build\(spec, geo, \{\}\)/, 'no stylesheet and no resolved colours go into the picture on screen');
+	assert.ok(!/matchMedia|vscode-dark|vscode-light|onDidChangeTheme/.test(code), 'nothing re-renders on a theme change: the tokens do it');
+});
+
+test('MEASURED: boxes are sized with the real font, and never with a font the canvas refused', () => {
+	const m = fn('lcdMeasure');
+	assert.match(m, /lcdCtx\.font = T\.weight \+ ' ' \+ T\.size \+ 'px ' \+ lcdFont\(\);/);
+	assert.match(m, /if \(String\(lcdCtx\.font\)\.indexOf\(T\.size \+ 'px'\) >= 0\)/, 'a rejected font string must not be measured with');
+	assert.match(m, /return LCD\.theme\.approxMeasure\(text, role\);/, 'the fallback errs wide');
+	assert.match(fn('lcdDraw'), /LCD\.layout\.layout\(spec, \{ measure: lcdMeasure, maxWidth: avail \|\| undefined \}\)/, 'and laid out to the width of the column');
+});
+
+console.log('diagramUi: ' + n + ' tests passed');
diff --git a/extensions/levelcode-ai/test/sessionExpiredHost.test.js b/extensions/levelcode-ai/test/sessionExpiredHost.test.js
index 12502d3..b0f3834 100644
--- a/extensions/levelcode-ai/test/sessionExpiredHost.test.js
+++ b/extensions/levelcode-ai/test/sessionExpiredHost.test.js
@@ -110,6 +110,9 @@ const makeHost = new Function('env', [
 	"const SYSTEM_PROMPT = 'system';",
 	'let activeWebview = env.webview, cloudSignedIn = env.signedIn, agentMode = false, conversation = [], pendingContext = null, conversationEpoch = 0, abort = null;',
 	'let agentMessages = [], currentCheckpoint = null, lastAgentGoal = null;',
+	// resumeSession also hands a session's stored diagrams back to the diagram service
+	// (docs/RICH-DIAGRAMS.md). These sessions have none; test/diagramHost.test.js runs it with the real one.
+	'let diagramsStubbed = false; const diagrams = { load: () => {}, stubsFor: () => [] };',
 	decl('ACCOUNT_TOKEN_KEY'), decl('ACCOUNT_REFRESH_KEY'), decl('ACCOUNT_PROFILE_KEY'), decl('ACCOUNT_EXPIRED_KEY'),
 	decl('sessionQueue'), decl('sessionGeneration'), decl('SESSION_CHECK_EVERY_MS'), decl('lastSessionCheck'),
 	...FUNCTIONS.map(extract),
diff --git a/extensions/levelcode-ai/test/sessionsUi.test.js b/extensions/levelcode-ai/test/sessionsUi.test.js
index 09a6812..63f76ad 100644
--- a/extensions/levelcode-ai/test/sessionsUi.test.js
+++ b/extensions/levelcode-ai/test/sessionsUi.test.js
@@ -179,7 +179,9 @@ test('MEMORY (enrichment): a cheap-lane model call refines the journal outcome w
 test('MEMORY (recall): a recall_sessions agent tool searches past-session outcomes on demand', () => {
 	const agentSrc = fs.readFileSync(path.join(__dirname, '..', 'agent.js'), 'utf8');
 	assert.match(agentSrc, /name: 'recall_sessions'/, 'the tool schema exists');
-	assert.match(agentSrc, /if \(ctx\.recallSessions\) \{ tools = tools\.concat\(\[RECALL_TOOL\]\)/, 'offered ONLY when the host wires it (host-gated)');
+	// (recall is one of the run's host-gated `extras` since rich diagrams added two more;
+	//  test/diagramAgent.test.js runs the loop and checks the tool list that is actually sent)
+	assert.match(agentSrc, /if \(ctx\.recallSessions\) \{ extras\.push\(RECALL_TOOL\); \}/, 'offered ONLY when the host wires it (host-gated)');
 	assert.match(agentSrc, /tu\.name === 'recall_sessions'/, 'and dispatched to ctx.recallSessions');
 	assert.match(ext, /function recallSessionsTool/, 'extension.js provides the recall callback');
 	assert.match(ext, /recallSessions: \(aiConfig\(\)\.get\('sessions\.memory\.enabled'.*recallTool/, 'gated by enabled + recallTool');
@@ -290,7 +292,10 @@ test('ACTIONS: below the label threshold the buttons fall back to an ICON, not t
 });
 
 test('EXPORT: the body is scrubbed on the way out, and the save-dialog filename is redacted too', () => {
-	assert.match(ext, /toMarkdown\(entry, m\.transcript\(id\), \{ redact: sessionMemory\.redactSecrets \}\)/, 'the exported body is scrubbed');
+	// The options object grew (an export now carries the session's diagrams); what is pinned is that
+	// the scrub is still the first thing handed to toMarkdown. That a DIAGRAM's text is scrubbed too
+	// is exercised, not pattern-matched, in test/diagramSession.test.js.
+	assert.match(ext, /toMarkdown\(entry, m\.transcript\(id\), \{\s*redact: sessionMemory\.redactSecrets\b/, 'the exported body is scrubbed');
 	assert.match(ext, /redactSecrets\(String\(entry\.title[\s\S]{0,140}stem/, 'and the default filename is redacted BEFORE the save path (a title token cannot leak into the dialog)');
 });
 

From 822cfc277763a30721137fdb08ba1b502228e5dd Mon Sep 17 00:00:00 2001
From: Sergii Demianchuk <sergeydemjanchyk@gmail.com>
Date: Mon, 5 Oct 2026 00:28:56 -0400
Subject: [PATCH 7/9] test(diagrams): the chat in a browser, the feature in the
 real editor, and an eval for models
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three scripts for the three things the suites cannot show. None is in the
gate, which is plain Node and stays that way.

scripts/diagram-browser-check.js — the shipped chat.html in headless Chrome,
built the way the host builds it (the same bundle, the same policy) and fed
records made by the real service. 155 checks across both themes: every diagram
is an SVG of the painter's elements only; hostile labels are on the page as
text and nothing ran; no policy violation and no request; the placeholder, the
badge, the banner, the failed view; a click names a node, never a path; SVG
and PNG export pass the host's own check; and a painter that throws, or a page
with no diagram modules at all, both end in the text fallback. Each step waits
for its result, not for a length of time: the first version waited, and failed
one run in three.

scripts/diagram-editor-check.js — the real editor. A second, throwaway instance
of the dev build (its own profile, sessions folder and workspace) loads THIS
checkout's extension in place of the built-in one, talks to a stand-in provider
on localhost, and is driven through the DevTools protocol. 17 checks: the tool
and its rules reach the model; the diagram is painted in the real webview in
the editor's colours; a wider column re-lays it out; a linked node opens its
file at the symbol; the session on disk holds the diagram; and the answer
around it, which quotes a code fence, is one paragraph (the chat fix earlier in
this branch).

It exists because of a mistake worth writing down. The feature was first called
done having only ever run in a browser, with instructions for trying it that
could not have worked: the work sat uncommitted in a git worktree, and a
worktree has no vscode/ — run-dev.sh runs the extensions of the checkout that
does. The editor that was then tried was develop's, with no diagrams in it.
What does work, by hand, from the checkout that has vscode/:

  ./scripts/run-dev.sh --extensionDevelopmentPath=<checkout>/extensions/levelcode-ai

scripts/diagram-eval.js — the spec's eval: 30 prompts that should produce a
diagram and 10 that should not (fixtures/diagrams/eval-prompts.json), each run
through the real agent loop and scored on format choice, first-pass validity,
fixes by rung, degraded rate, error classes, tokens, node-count overruns, title
quality and answers that drew with characters. --dry-run uses a scripted model
and no network. --run makes billed calls on your key, says how many before the
first one, and is refused without a model and a key; the workspace is an empty
temporary folder and every approval is answered no.

It has not been run against any model. That is the next thing this feature
needs: nothing here says how often a real model's first attempt is valid, or
whether it reaches for the tool at all.

diagramEval (16 tests) holds the harness to its own arithmetic: a scripted
model whose mistakes are known comes out at exactly the numbers its script
implies, and nothing is sent without --run, a model and a key.
---
 .../scripts/diagram-browser-check.js          | 459 ++++++++++++++++++
 .../scripts/diagram-editor-check.js           | 293 +++++++++++
 .../levelcode-ai/scripts/diagram-eval.js      | 319 ++++++++++++
 .../levelcode-ai/test/diagramEval.test.js     | 249 ++++++++++
 .../test/fixtures/diagrams/eval-prompts.json  |  45 ++
 5 files changed, 1365 insertions(+)
 create mode 100755 extensions/levelcode-ai/scripts/diagram-browser-check.js
 create mode 100755 extensions/levelcode-ai/scripts/diagram-editor-check.js
 create mode 100755 extensions/levelcode-ai/scripts/diagram-eval.js
 create mode 100644 extensions/levelcode-ai/test/diagramEval.test.js
 create mode 100644 extensions/levelcode-ai/test/fixtures/diagrams/eval-prompts.json

diff --git a/extensions/levelcode-ai/scripts/diagram-browser-check.js b/extensions/levelcode-ai/scripts/diagram-browser-check.js
new file mode 100755
index 0000000..4fa3b8a
--- /dev/null
+++ b/extensions/levelcode-ai/scripts/diagram-browser-check.js
@@ -0,0 +1,459 @@
+#!/usr/bin/env node
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — rich diagrams, checked in a real browser  (docs/RICH-DIAGRAMS.md, acceptance criteria)
+ *
+ *  The unit suites prove the pieces: the validator, the ladder, the layout's geometry, the painter's
+ *  allow-lists. What they cannot prove is the thing the spec actually asks for — that in the CHAT, in
+ *  a browser, under the page's real Content-Security-Policy, a diagram is drawn, looks right in both
+ *  themes, and that a hostile spec executes nothing and fetches nothing.
+ *
+ *  So this loads the shipped media/chat.html in headless Chrome exactly as the editor would build it
+ *  (the same bundle injection, the same CSP, a stand-in for acquireVsCodeApi), plays host messages at
+ *  it — records made by the real diagram service — and then asks the page what happened:
+ *
+ *    • every diagram became an <svg> made only of the painter's elements; no script, link, image or
+ *      foreignObject exists anywhere inside a diagram card, and no element carries an event handler
+ *    • the hostile labels are on the page AS TEXT
+ *    • zero CSP violations, zero resource requests, zero uncaught errors
+ *    • the placeholder → picture swap, the auto-fixed badge, the degraded banner, the failed view
+ *    • a clicked node asks the host to open a link by NODE ID only
+ *    • SVG and PNG export produce data the host's own structural check accepts
+ *    • with the diagram modules MISSING from the page, each diagram is shown as the host's text
+ *      version of the same spec — the spec's fallback — and still nothing runs
+ *
+ *  …and it writes a screenshot per theme, because "house style in light and dark" is finally a thing
+ *  someone has to look at.
+ *
+ *  RUN:    node extensions/levelcode-ai/scripts/diagram-browser-check.js [--out <dir>]
+ *  NEEDS:  Google Chrome or Chromium (set CHROME=/path/to/binary if it is somewhere unusual).
+ *  EXIT:   0 all checks pass · 1 a check failed · 2 no browser found (nothing was checked).
+ *
+ *  Not part of scripts/test-extensions.sh: that gate is plain Node, and stays that way.
+ *--------------------------------------------------------------------------------------------*/
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const cp = require('child_process');
+
+const EXT = path.join(__dirname, '..');
+const bundle = require(path.join(EXT, 'diagram', 'bundle'));
+const { createDiagrams } = require(path.join(EXT, 'diagram', 'service'));
+const exportCheck = require(path.join(EXT, 'diagram', 'exportCheck'));
+const repair = require(path.join(EXT, 'diagram', 'repair'));
+const ascii = require(path.join(EXT, 'diagram', 'ascii'));
+
+function findChrome() {
+	const candidates = [process.env.CHROME,
+		'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium',
+		'/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
+	return candidates.find((c) => c && fs.existsSync(c)) || null;
+}
+
+// ---- the records, made by the real service ------------------------------------------------------
+const gallery = JSON.parse(fs.readFileSync(path.join(EXT, 'test', 'fixtures', 'diagrams', 'gallery.json'), 'utf8'));
+const specOf = (name) => JSON.parse(JSON.stringify(gallery.find((g) => g.name === name).spec));
+const HOSTILE = {
+	title: '</title><script>window.__pwned = 1</script>',
+	nodes: [
+		{ id: 'a', label: '<img src=x onerror="window.__pwned=2">', sub: '"><script>window.__pwned=3</script>' },
+		{ id: 'b', label: "'><svg onload=window.__pwned=4>", link: { path: 'javascript:window.__pwned=5' } },
+		{ id: 'c', label: '</text><foreignObject>', sub: '<a href="https://example.invalid/x">x</a>', link: { path: 'agent.js' } },
+		{ id: 'd', label: '<iframe src=//example.invalid>', shape: 'decision' }
+	],
+	edges: [{ from: 'a', to: 'b', label: '<style>*{display:none}' }, { from: 'b', to: 'c', label: '" onmouseover="x' }, { from: 'c', to: 'd' }],
+	groups: [{ id: 'g', label: '<object data=//example.invalid>' }]
+};
+HOSTILE.nodes[0].group = 'g';
+
+function makeRecords() {
+	const service = createDiagrams({ resolveLink: (link) => (/^(agent\.js|providers\/index\.js)$/.test(link.path) ? { ok: true, path: link.path } : { ok: false, reason: 'not a file in this workspace' }) });
+	const out = {};
+	let k = 0;
+	const draw = (name, input, twice) => {
+		service.beginRun();
+		let msgs = service.render(input, { key: 'key-' + name, model: 'check' }).post;
+		if (twice) { msgs = msgs.concat(service.render(input, { key: 'key-' + name + '-again', model: 'check' }).post); }
+		msgs = msgs.concat(service.endRun());
+		out[name] = msgs.filter((m) => m.type === 'diagram').pop();
+		k++;
+	};
+	draw('jev', specOf('jev'));
+	draw('arch', specOf('arch'));
+	draw('decision', specOf('decision'));
+	draw('twelve', specOf('twelve'));
+	const long = specOf('jev'); long.title = 'Long labels are shortened, never rejected'; long.nodes[0].label = 'Customer message with the whole account history'; long.nodes[2].shape = 'hexagon';
+	draw('fixed', long);
+	const bad = specOf('jev'); bad.title = 'A diagram that lost an edge'; bad.edges[1].to = 'billing'; bad.nodes[2].accent = true;
+	draw('degraded', bad, true);
+	draw('failed', { title: 'Nothing to draw', nodes: [], edges: [] }, true);
+	draw('hostile', HOSTILE);
+	draw('unpaintable', specOf('pipeline'));   // sent only after the painter has been made to fail
+	return out;
+}
+
+// ---- the page -------------------------------------------------------------------------------------
+const THEMES = {
+	light: { '--vscode-foreground': '#3b3b3b', '--vscode-editor-background': '#ffffff', '--vscode-descriptionForeground': '#6b6b6b', '--vscode-focusBorder': '#005fb8', '--vscode-textLink-foreground': '#005fb8', '--vscode-input-background': '#ffffff', '--vscode-input-border': '#cecece', '--vscode-panel-border': '#e5e5e5', '--vscode-toolbar-hoverBackground': 'rgba(184,184,184,.31)', '--vscode-button-background': '#005fb8', '--vscode-button-foreground': '#ffffff', '--vscode-editorWidget-background': '#f8f8f8', '--vscode-inputValidation-warningBackground': '#fff4ce', '--vscode-inputValidation-warningBorder': '#bf8803', '--vscode-inputValidation-warningForeground': '#3b3b3b' },
+	dark: { '--vscode-foreground': '#cccccc', '--vscode-editor-background': '#1f1f1f', '--vscode-descriptionForeground': '#9d9d9d', '--vscode-focusBorder': '#0078d4', '--vscode-textLink-foreground': '#4daafc', '--vscode-input-background': '#313131', '--vscode-input-border': '#3c3c3c', '--vscode-panel-border': '#2b2b2b', '--vscode-toolbar-hoverBackground': 'rgba(90,93,94,.31)', '--vscode-button-background': '#0078d4', '--vscode-button-foreground': '#ffffff', '--vscode-editorWidget-background': '#202020', '--vscode-inputValidation-warningBackground': '#352a05', '--vscode-inputValidation-warningBorder': '#b89500', '--vscode-inputValidation-warningForeground': '#cccccc' }
+};
+
+/**
+ * @param {{ bare?: boolean, driver?: Function, asciiById?: Record<string,string> }} [opts]
+ *        bare: leave the diagram modules OUT, as getHtml() does when the bundle cannot be built.
+ *        asciiById: what the stand-in host answers an `ascii` request with (the real host's text).
+ */
+function buildPage(theme, records, opts) {
+	const o = opts || {};
+	const nonce = 'checknonce';
+	// Exactly what extension.js webviewCsp() + getHtml() produce.
+	const csp = ["default-src 'none'", 'img-src data:', "style-src 'unsafe-inline'", "script-src 'nonce-" + nonce + "'"].join('; ');
+	const raw = fs.readFileSync(path.join(EXT, 'media', 'chat.html'), 'utf8');
+	let html = o.bare ? raw : bundle.inject(raw);
+	html = html.replace(/__CSP__/g, csp).replace(/__NONCE__/g, nonce);
+	const vars = Object.entries(THEMES[theme]).map(([k, v]) => k + ':' + v).join(';');
+	const themeCss = '<style>html{' + vars + ';--vscode-font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;--vscode-font-size:13px;--vscode-editor-font-family:Menlo,Consolas,monospace;background:var(--vscode-editor-background);color:var(--vscode-foreground)}</style>';
+	html = html.replace('</head>', themeCss + '</head>');
+	const stub = '<script nonce="' + nonce + '">'
+		+ 'window.__posted=[];window.__report={csp:[],errors:[]};'
+		+ 'document.addEventListener("securitypolicyviolation",function(e){window.__report.csp.push(e.violatedDirective+" "+e.blockedURI);});'
+		+ 'window.addEventListener("error",function(e){window.__report.errors.push(String(e.message));});'
+		+ 'window.__ascii=' + JSON.stringify(o.asciiById || {}).replace(/</g, '\\u003c') + ';'
+		// The stand-in host: it records what it is asked, and answers the one request that has an answer.
+		+ 'window.acquireVsCodeApi=function(){return{postMessage:function(m){window.__posted.push(m);'
+		+ 'if(m&&m.type==="diagramAction"&&m.action==="ascii"){setTimeout(function(){window.postMessage({type:"diagramAscii",id:m.id,text:window.__ascii[m.id]||""},"*");},0);}'
+		+ '},getState:function(){return null;},setState:function(){}};};'
+		+ '</' + 'script>';
+	const at = html.indexOf('<script nonce="' + nonce + '">');
+	html = html.slice(0, at) + stub + html.slice(at);
+	const driver = '<script nonce="' + nonce + '">(' + (o.driver || drive).toString() + ')(' + JSON.stringify(records).replace(/</g, '\\u003c') + ');</' + 'script>';
+	return html.replace('</body>', driver + '</body>');
+}
+
+/** Runs IN THE PAGE that has no diagram modules. Plays three records and reports what was shown. */
+function driveBare(R) {
+	const say = (m) => window.postMessage(m, '*');
+	const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+	// Wait for a RESULT, never for an amount of time: messages are delivered when the browser gets to them.
+	const until = async (cond) => { for (let i = 0; i < 600; i++) { if (cond()) { return true; } await wait(10); } return false; };
+	const report = window.__report;
+	(async function () {
+		try {
+			report.hasRenderer = !!window.LCDiagram;
+			say({ type: 'config', provider: 'claude', model: 'claude-opus-4-8', providerLabel: 'Claude', contextLimit: 200000, groupActivity: true });
+			say({ type: 'agentStart' });
+			say({ type: 'agentDelta', text: 'Here is how a message is routed.' });
+			say({ type: 'diagramPending', key: R.jev.key, state: 'drawing', title: 'Jev classifies; your code decides the action' });
+			say(R.jev);
+			say({ type: 'agentTurnEnd' });
+			say(R.hostile);
+			say(R.degraded);
+			say(R.failed);
+			say({ type: 'agentDone', reason: 'done', edits: 0 });
+			// four cards, and the host's answer has arrived for each of the three it was asked about
+			report.settled = await until(() => document.querySelectorAll('figure.lcd').length === 4 && Array.from(document.querySelectorAll('figure.lcd .lcd-ascii pre')).filter((p) => p.textContent).length === 3);
+			const cards = Array.from(document.querySelectorAll('figure.lcd'));
+			report.cards = cards.map((c) => {
+				const pre = c.querySelector('.lcd-ascii pre'), det = c.querySelector('details.lcd-source');
+				return {
+					id: c.dataset.id, status: c.dataset.status, title: c.querySelector('.lcd-title-text').textContent,
+					svg: !!c.querySelector('svg'), banner: (c.querySelector('.lcd-banner-text') || {}).textContent || null,
+					ascii: pre ? pre.textContent : null, asciiShown: pre ? !pre.parentElement.hidden && pre.getBoundingClientRect().height > 0 : false,
+					mono: pre ? /mono|Menlo|Consolas|Courier/i.test(getComputedStyle(pre).fontFamily) : null, pre: pre ? getComputedStyle(pre).whiteSpace : null,
+					sourceOpen: det ? det.open : null, source: !!c.querySelector('.lcd-source pre'),
+					retry: !!Array.from(c.querySelectorAll('.lcd-btn')).find((b) => b.textContent === 'Retry'),
+					tools: Array.from(c.querySelectorAll('.lcd-tools .lcd-btn')).map((b) => b.textContent)
+				};
+			});
+			report.asked = window.__posted.filter((m) => m.type === 'diagramAction').map((m) => ({ action: m.action, id: m.id, keys: Object.keys(m).sort().join() }));
+			report.askedCols = window.__posted.filter((m) => m.type === 'diagramAction').map((m) => m.cols);
+			report.renderReports = window.__posted.filter((m) => m.type === 'diagramRendered').map((m) => ({ id: m.id, ok: m.ok, message: m.message }));
+			const bad = [];
+			cards.forEach((c) => {
+				c.querySelectorAll('script, iframe, object, embed, foreignObject, image, img, a, link, use, style, svg').forEach((el) => bad.push(c.dataset.id + ': <' + el.localName + '>'));
+				c.querySelectorAll('*').forEach((el) => { for (const a of Array.from(el.attributes)) { if (/^on/i.test(a.name) || /^(href|src|xlink:href|style)$/i.test(a.name)) { bad.push(c.dataset.id + ': ' + el.localName + '[' + a.name + ']'); } } });
+			});
+			report.forbidden = bad;
+			report.pwned = window.__pwned === undefined ? null : window.__pwned;
+			report.pending = document.querySelectorAll('figure.lcd.lcd-pending').length;
+			report.resources = performance.getEntriesByType('resource').map((e) => e.name);
+		} catch (e) {
+			report.errors.push('driver: ' + (e && e.stack ? e.stack : e));
+		}
+		const pre = document.createElement('pre'); pre.id = 'lcd-report'; pre.hidden = true; pre.textContent = JSON.stringify(report);
+		document.body.appendChild(pre);
+	})();
+}
+
+/** Runs IN THE PAGE. Plays host messages, then reports what the page did. */
+function drive(R) {
+	const say = (m) => window.postMessage(m, '*');
+	const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+	// Wait for a RESULT, never for an amount of time: messages are delivered when the browser gets to them.
+	const until = async (cond) => { for (let i = 0; i < 600; i++) { if (cond()) { return true; } await wait(10); } return false; };
+	const stalled = [];
+	const need = async (what, cond) => { if (!(await until(cond))) { stalled.push(what); } };
+	const report = window.__report;
+	(async function () {
+		try {
+			say({ type: 'config', provider: 'claude', model: 'claude-opus-4-8', providerLabel: 'Claude', contextLimit: 200000, groupActivity: true });
+			say({ type: 'agentStart' });
+			say({ type: 'agentDelta', text: 'Here is how a message is routed.' });
+			say({ type: 'diagramPending', key: R.jev.key, state: 'drawing', title: '' });
+			say({ type: 'diagramPending', key: R.jev.key, state: 'drawing', title: 'Jev classifies; your code decides the action' });
+			await need('the titled placeholder', () => { const p = document.querySelector('figure.lcd.lcd-pending .lcd-title-text'); return !!p && p.textContent !== 'Diagram'; });
+			const ph = document.querySelector('figure.lcd.lcd-pending');
+			report.placeholder = ph ? { title: ph.querySelector('.lcd-title-text').textContent, text: ph.querySelector('.lcd-skel-text').textContent, live: ph.getAttribute('aria-live') } : null;
+			say(R.jev);
+			say({ type: 'agentDelta', text: 'Jev only scores the message; the threshold lives in your code.' });
+			say({ type: 'agentTurnEnd' });
+			for (const name of ['arch', 'decision', 'twelve', 'fixed', 'degraded', 'failed', 'hostile']) {
+				say({ type: 'agentDelta', text: 'Next: ' + name + '.' });
+				say({ type: 'diagramPending', key: 'placeholder-' + name, state: 'drawing', title: '' });
+				say(Object.assign({}, R[name], { replacesKey: 'placeholder-' + name }));
+			}
+			// one placeholder whose diagram never arrives: it must be gone when the run ends
+			say({ type: 'diagramPending', key: 'orphan', state: 'drawing', title: 'Never drawn' });
+			await need('eight drawn cards and the orphan placeholder', () => document.querySelectorAll('figure.lcd[data-id]').length === 8 && document.querySelectorAll('figure.lcd.lcd-pending').length === 1);
+			report.pendingBeforeDone = document.querySelectorAll('figure.lcd.lcd-pending').length;
+			say({ type: 'agentDone', reason: 'done', edits: 0 });
+			await need('the run to end', () => document.querySelectorAll('figure.lcd.lcd-pending').length === 0);
+
+			const cards = Array.from(document.querySelectorAll('figure.lcd'));
+			report.renderReports = window.__posted.filter((m) => m.type === 'diagramRendered').map((m) => ({ id: m.id, ok: m.ok, ms: m.ms }));
+			report.pendingAfterDone = document.querySelectorAll('figure.lcd.lcd-pending').length;
+			report.cards = cards.map((c) => {
+				const svg = c.querySelector('.lcd-stage svg');
+				const tags = {};
+				if (svg) { svg.querySelectorAll('*').forEach((el) => { tags[el.localName] = (tags[el.localName] || 0) + 1; }); }
+				const col = c.parentElement.getBoundingClientRect();
+				return {
+					id: c.dataset.id, status: c.dataset.status, title: c.querySelector('.lcd-title-text').textContent,
+					svg: !!svg, tags, role: svg ? svg.getAttribute('role') : null, described: svg ? !!document.getElementById(svg.getAttribute('aria-describedby')) : false,
+					fits: svg ? svg.getBoundingClientRect().width <= col.width + 0.5 : null,
+					width: svg ? Math.round(svg.getBoundingClientRect().width) : 0,
+					badge: (c.querySelector('.lcd-badge') || {}).textContent || null,
+					banner: (c.querySelector('.lcd-banner-text') || {}).textContent || null,
+					retry: !!Array.from(c.querySelectorAll('.lcd-btn')).find((b) => b.textContent === 'Retry'),
+					tools: Array.from(c.querySelectorAll('.lcd-tools .lcd-btn')).map((b) => b.textContent),
+					links: c.querySelectorAll('[data-lc-link]').length,
+					source: !!c.querySelector('.lcd-source pre'), errors: Array.from(c.querySelectorAll('.lcd-errors li')).map((li) => li.textContent)
+				};
+			});
+
+			// Safety: nothing executable or fetchable inside any diagram card, and no handler attributes anywhere in one.
+			const bad = [];
+			cards.forEach((c) => {
+				c.querySelectorAll('script, iframe, object, embed, foreignObject, image, img, a, link, use, style').forEach((el) => bad.push(c.dataset.id + ': <' + el.localName + '>'));
+				c.querySelectorAll('*').forEach((el) => { for (const a of Array.from(el.attributes)) { if (/^on/i.test(a.name) || /^(href|src|xlink:href|style)$/i.test(a.name)) { bad.push(c.dataset.id + ': ' + el.localName + '[' + a.name + ']'); } } });
+			});
+			report.forbidden = bad;
+			report.pwned = window.__pwned === undefined ? null : window.__pwned;
+			const hostile = cards.find((c) => c.dataset.id === R.hostile.record.id);
+			report.hostileText = hostile ? Array.from(hostile.querySelectorAll('svg text')).map((t) => t.textContent) : [];
+			report.hostileTitle = hostile ? hostile.querySelector('.lcd-title-text').textContent : null;
+			report.resources = performance.getEntriesByType('resource').map((e) => e.name);
+
+			// A click on a linked node asks the host for a NODE, never a path.
+			window.__posted.length = 0;
+			const arch = cards.find((c) => c.dataset.id === R.arch.record.id);
+			const linked = arch.querySelector('[data-lc-link]');
+			linked.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
+			report.linkClick = window.__posted.filter((m) => m.type === 'diagramAction');
+			const hostileLink = hostile.querySelector('[data-lc-link]');
+			window.__posted.length = 0;
+			if (hostileLink) { hostileLink.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true })); }
+			report.hostileLinkClick = window.__posted.filter((m) => m.type === 'diagramAction');
+			report.hostileLinks = Array.from(hostile.querySelectorAll('[data-lc-link]')).map((el) => el.getAttribute('data-lc-link'));
+
+			// Full-size view opens on a click on the picture, and closes on Escape.
+			arch.querySelector('.lcd-stage').dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
+			const z = document.getElementById('lcdZoom');
+			report.zoomOpen = !z.hidden && !!z.querySelector('.lcdz-view svg');
+			report.zoomTitle = z.querySelector('.lcdz-title').textContent;
+			document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+			report.zoomClosed = z.hidden;
+
+			// Export: SVG text, and a PNG rasterised from it.
+			const jev = cards.find((c) => c.dataset.id === R.jev.record.id);
+			const btn = (card, label) => Array.from(card.querySelectorAll('.lcd-tools .lcd-btn')).find((b) => b.textContent === label);
+			window.__posted.length = 0;
+			btn(jev, 'SVG').click(); btn(jev, 'PNG').click(); btn(jev, 'Copy source').click(); btn(jev, 'Open as Mermaid').click();
+			// (the PNG is rasterised asynchronously; a failure reports itself as a notice)
+			await need('four exports', () => window.__posted.filter((m) => m.type === 'diagramAction' && m.action === 'export').length === 4 || window.__posted.some((m) => m.type === 'notice'));
+			report.exports = window.__posted.filter((m) => m.type === 'diagramAction' && m.action === 'export').map((m) => ({ format: m.format, id: m.id, data: m.data || null }));
+			report.notices = window.__posted.filter((m) => m.type === 'notice').map((m) => m.text);
+
+			// The badge opens its details.
+			const fixed = cards.find((c) => c.dataset.id === R.fixed.record.id);
+			const badge = fixed.querySelector('.lcd-badge'); badge.click();
+			report.popover = Array.from(fixed.querySelectorAll('.lcd-pop:not([hidden]) div')).map((d) => d.textContent);
+			badge.click();
+
+			// Last: the painter itself fails. The card must fall back to a text drawing of the same spec.
+			const realMount = window.LCDiagram.scene.mount;
+			window.LCDiagram.scene.mount = function () { throw new Error('painter unavailable'); };
+			window.__posted.length = 0;
+			say({ type: 'agentStart' });
+			say(R.unpaintable);
+			say({ type: 'agentDone', reason: 'done', edits: 0 });
+			await need('the unpaintable diagram', () => !!Array.from(document.querySelectorAll('figure.lcd')).find((c) => c.dataset.id === R.unpaintable.record.id && c.querySelector('.lcd-ascii pre')));
+			window.LCDiagram.scene.mount = realMount;
+			const un = Array.from(document.querySelectorAll('figure.lcd')).find((c) => c.dataset.id === R.unpaintable.record.id);
+			const unPre = un ? un.querySelector('.lcd-ascii pre') : null;
+			report.unpaintable = un ? {
+				svg: !!un.querySelector('svg'), text: unPre ? unPre.textContent : null,
+				banner: (un.querySelector('.lcd-banner-text') || {}).textContent || null,
+				bannerFirst: !!(un.querySelector('.lcd-banner') && unPre && (un.querySelector('.lcd-banner').compareDocumentPosition(unPre) & Node.DOCUMENT_POSITION_FOLLOWING)),
+				widest: unPre ? Math.max.apply(null, unPre.textContent.split('\n').map((l) => l.length)) : 0,
+				fits: unPre ? unPre.scrollWidth <= unPre.clientWidth + 1 : false,
+				tools: Array.from(un.querySelectorAll('.lcd-tools .lcd-btn')).map((b) => b.textContent),
+				reports: window.__posted.filter((m) => m.type === 'diagramRendered').map((m) => ({ ok: m.ok, message: m.message })),
+				asked: window.__posted.filter((m) => m.type === 'diagramAction').length
+			} : null;
+			report.stalled = stalled;
+		} catch (e) {
+			report.errors.push('driver: ' + (e && e.stack ? e.stack : e));
+		}
+		const pre = document.createElement('pre'); pre.id = 'lcd-report'; pre.hidden = true; pre.textContent = JSON.stringify(report);
+		document.body.appendChild(pre);
+	})();
+}
+
+// ---- run ------------------------------------------------------------------------------------------
+function chrome(bin, args) {
+	return cp.spawnSync(bin, ['--headless=new', '--disable-gpu', '--hide-scrollbars', '--no-first-run', '--disable-extensions', '--virtual-time-budget=8000'].concat(args), { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+}
+
+function main() {
+	const bin = findChrome();
+	if (!bin) { console.error('No Chrome or Chromium found (set CHROME=/path/to/binary). Nothing was checked.'); process.exit(2); }
+	const outArg = process.argv.indexOf('--out');
+	const out = outArg > 0 ? path.resolve(process.argv[outArg + 1]) : fs.mkdtempSync(path.join(os.tmpdir(), 'lc-diagram-check-'));
+	fs.mkdirSync(out, { recursive: true });
+	const records = makeRecords();
+	const failures = [];
+	let passed = 0;
+	const check = (theme, name, ok, detail) => { if (ok) { passed++; } else { failures.push(theme + ' · ' + name + (detail ? ' — ' + detail : '')); } };
+
+	/** Load one page in the browser, screenshot it, and read back what it reported. */
+	const visit = (name, html, size) => {
+		const page = path.join(out, name + '.html');
+		fs.writeFileSync(page, html);
+		chrome(bin, ['--window-size=' + size, '--screenshot=' + path.join(out, name + '.png'), 'file://' + page]);
+		const dom = chrome(bin, ['--window-size=' + size, '--dump-dom', 'file://' + page]).stdout || '';
+		const m = /<pre id="lcd-report"[^>]*>([\s\S]*?)<\/pre>/.exec(dom);
+		if (!m) { return null; }
+		const r = JSON.parse(m[1].replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&amp;/g, '&'));
+		fs.writeFileSync(path.join(out, name.replace('chat', 'report') + '.json'), JSON.stringify(r, null, 2));
+		return r;
+	};
+
+	for (const theme of ['light', 'dark']) {
+		const r = visit('chat-' + theme, buildPage(theme, records), '900,3900');
+		if (!r) { failures.push(theme + ' · the page never reported (did the script run?)'); continue; }
+		const card = (name) => (r.cards || []).find((c) => c.id === records[name].record.id) || {};
+
+		check(theme, 'no uncaught error in the page', r.errors.length === 0, r.errors.join(' | '));
+		check(theme, 'every step of the script saw its result arrive', (r.stalled || ['?']).length === 0, 'never happened: ' + (r.stalled || ['the script did not finish']).join(', '));
+		check(theme, 'zero CSP violations', r.csp.length === 0, r.csp.join(' | '));
+		check(theme, 'zero resource requests', (r.resources || []).length === 0, (r.resources || []).join(' | '));
+		check(theme, 'nothing from a label ever ran', r.pwned === null, 'window.__pwned = ' + r.pwned);
+		check(theme, 'no script/link/image/foreignObject/handler inside any diagram card', (r.forbidden || []).length === 0, (r.forbidden || []).slice(0, 6).join(' | '));
+		check(theme, 'the hostile labels are on the page as text', (r.hostileText || []).includes('</text><foreignObject>') && (r.hostileText || []).some((t) => t.indexOf('<img src=x') === 0), JSON.stringify(r.hostileText));
+		check(theme, 'the hostile title is text', r.hostileTitle === '</title><script>window.__pwned = 1</script>', r.hostileTitle);
+		check(theme, 'a javascript: link was dropped; only the real file is clickable', JSON.stringify(r.hostileLinks) === '["c"]', JSON.stringify(r.hostileLinks));
+		check(theme, 'the placeholder holds the place, titled, and announces politely', r.placeholder && r.placeholder.title === 'Jev classifies; your code decides the action' && r.placeholder.text === 'Drawing…' && r.placeholder.live === 'polite', JSON.stringify(r.placeholder));
+		check(theme, 'a placeholder whose diagram never came is removed when the run ends', r.pendingBeforeDone === 1 && r.pendingAfterDone === 0, r.pendingBeforeDone + ' → ' + r.pendingAfterDone);
+		check(theme, 'eight cards, one per diagram', (r.cards || []).length === 8, String((r.cards || []).length));
+		for (const name of ['jev', 'arch', 'decision', 'twelve', 'fixed', 'degraded', 'hostile']) {
+			const c = card(name);
+			check(theme, name + ': drawn as an SVG image with a description', c.svg && c.role === 'img' && c.described, JSON.stringify({ svg: c.svg, role: c.role, described: c.described }));
+			check(theme, name + ': made only of the painter\'s elements', c.tags && Object.keys(c.tags).every((t) => ['g', 'rect', 'path', 'text', 'title'].includes(t)), JSON.stringify(c.tags));
+			check(theme, name + ': never wider than the chat column', c.fits === true, 'width ' + c.width);
+			check(theme, name + ': has its toolbar', JSON.stringify(c.tools) === JSON.stringify(['Copy source', 'SVG', 'PNG', 'Open as Mermaid', 'Insert into Markdown…']), JSON.stringify(c.tools));
+		}
+		check(theme, 'the title is HTML above the picture', card('jev').title === 'Jev classifies; your code decides the action');
+		check(theme, 'a clean diagram has no badge and no banner', card('jev').badge === null && card('jev').banner === null);
+		check(theme, 'auto-fixed: a quiet badge', /^auto-fixed/.test(card('fixed').badge || '') && card('fixed').banner === null, card('fixed').badge);
+		check(theme, 'auto-fixed: the badge opens the details', (r.popover || []).length >= 2 && r.popover.some((l) => /shortened/.test(l)), JSON.stringify(r.popover));
+		check(theme, 'degraded: a banner that says what was lost, and Retry', /1 edge dropped: unknown nodes/.test(card('degraded').banner || '') && card('degraded').retry, card('degraded').banner);
+		check(theme, 'failed: the errors, the source and Retry — never blank', card('failed').status === 'failed' && !card('failed').svg && card('failed').source && card('failed').retry && card('failed').errors.length === 1, JSON.stringify(card('failed')));
+		check(theme, 'arch: its two linked nodes are clickable', card('arch').links === 2, String(card('arch').links));
+		check(theme, 'a click on a node names the NODE, never a path', JSON.stringify(r.linkClick) === JSON.stringify([{ type: 'diagramAction', action: 'openLink', id: records.arch.record.id, node: 'agent' }]), JSON.stringify(r.linkClick));
+		check(theme, 'the hostile diagram\'s one link also only names its node', JSON.stringify(r.hostileLinkClick) === JSON.stringify([{ type: 'diagramAction', action: 'openLink', id: records.hostile.record.id, node: 'c' }]), JSON.stringify(r.hostileLinkClick));
+		check(theme, 'full-size view opens on click with the title, and closes on Escape', r.zoomOpen && r.zoomClosed && r.zoomTitle === 'The agent talks to providers through one registry', JSON.stringify([r.zoomOpen, r.zoomClosed, r.zoomTitle]));
+		const reports = r.renderReports || [];
+		check(theme, 'each of the seven pictures reported its render once, as a success', reports.length === 7 && reports.every((x) => x.ok === true && typeof x.ms === 'number'), JSON.stringify(reports));
+		// (Render TIME is not checked here: under --virtual-time-budget the page's clock does not advance
+		//  while script runs, so every measurement reads 0. Layout time is measured for real in
+		//  test/diagramLayout.test.js; time-to-picture in the editor is what "Diagram Statistics" records.)
+		check(theme, 'the failed card keeps the title the model gave it', card('failed').title === 'Nothing to draw', card('failed').title);
+		const ex = (f) => (r.exports || []).find((e) => e.format === f) || {};
+		check(theme, 'export: four actions reached the host', (r.exports || []).map((e) => e.format).sort().join() === 'mermaid,png,source,svg', JSON.stringify((r.exports || []).map((e) => e.format)) + ' ' + JSON.stringify(r.notices));
+		const svgCheck = exportCheck.checkSvg(ex('svg').data);
+		check(theme, 'export: the SVG passes the host\'s structural check', svgCheck.ok, svgCheck.reason);
+		check(theme, 'export: the SVG carries its title, a background and resolved colours', /class="lcd-title"/.test(ex('svg').data || '') && /class="lcd-bg"/.test(ex('svg').data || '') && !/var\(/.test(ex('svg').data || ''));
+		const pngCheck = exportCheck.checkPng(ex('png').data);
+		check(theme, 'export: the PNG is a real PNG', pngCheck.ok, pngCheck.reason);
+		check(theme, 'export: source and Mermaid carry no data from the webview', ex('source').data === null && ex('mermaid').data === null);
+		const un = r.unpaintable || {};
+		const unSpec = records.unpaintable.record.spec;
+		check(theme, 'a picture that cannot be painted becomes a text drawing of the same spec — no SVG, every label present', un.svg === false && typeof un.text === 'string' && unSpec.nodes.every((n) => un.text.includes(n.label)) && /\+-+\+/.test(un.text), JSON.stringify(un).slice(0, 300));
+		check(theme, 'the text drawing fits the card without scrolling sideways', un.fits === true && un.widest > 20, 'widest line ' + un.widest);
+		check(theme, 'and the card says why it is text, above the drawing', un.banner === 'The picture could not be drawn, so a text version is shown instead.' && un.bannerFirst === true, JSON.stringify([un.banner, un.bannerFirst]));
+		check(theme, 'its toolbar offers what still works — no image export', JSON.stringify(un.tools) === JSON.stringify(['Copy source', 'Open as Mermaid', 'Insert into Markdown…']), JSON.stringify(un.tools));
+		check(theme, 'it is counted as a render that failed, and the host is asked for nothing', (un.reports || []).length === 1 && un.reports[0].ok === false && /painter unavailable/.test(un.reports[0].message) && un.asked === 0, JSON.stringify([un.reports, un.asked]));
+		if (svgCheck.ok) { fs.writeFileSync(path.join(out, 'export-' + theme + '.svg'), ex('svg').data); }
+		if (pngCheck.ok) { fs.writeFileSync(path.join(out, 'export-' + theme + '.png'), pngCheck.bytes); }
+	}
+
+	// ---- the page WITHOUT its diagram modules: the fallback (docs/RICH-DIAGRAMS.md, "UX → Fallback") ----
+	{
+		const theme = 'no renderer';
+		// What extension.js diagramAsciiText() answers — test/diagramHost.test.js pins that it is exactly this.
+		// (The stand-in answers at one fixed width; the real host fits the column count the page sends.)
+		const textOf = (rec) => (rec.spec ? ascii.render(repair.accept(rec.spec).spec, { maxCols: 110, title: false }) : '');
+		const asciiById = {};
+		for (const name of ['jev', 'hostile', 'degraded', 'failed']) { asciiById[records[name].record.id] = textOf(records[name].record); }
+		const r = visit('chat-no-renderer', buildPage('light', records, { bare: true, driver: driveBare, asciiById }), '900,1500');
+		if (!r) { failures.push(theme + ' · the page never reported (did the script run?)'); }
+		else {
+			const card = (name) => (r.cards || []).find((c) => c.id === records[name].record.id) || {};
+			check(theme, 'the page really has no renderer', r.hasRenderer === false, String(r.hasRenderer));
+			check(theme, 'the host\'s answers arrived', r.settled === true, 'the page never showed all three text versions');
+			check(theme, 'no uncaught error in the page', r.errors.length === 0, r.errors.join(' | '));
+			check(theme, 'zero CSP violations', r.csp.length === 0, r.csp.join(' | '));
+			check(theme, 'zero resource requests', (r.resources || []).length === 0, (r.resources || []).join(' | '));
+			check(theme, 'nothing from a label ever ran', r.pwned === null, 'window.__pwned = ' + r.pwned);
+			check(theme, 'no element made from a spec, and no SVG', (r.forbidden || []).length === 0, (r.forbidden || []).slice(0, 6).join(' | '));
+			check(theme, 'four cards, and no placeholder left behind', (r.cards || []).length === 4 && r.pending === 0, (r.cards || []).length + ' cards, ' + r.pending + ' pending');
+			for (const name of ['jev', 'hostile', 'degraded']) {
+				const c = card(name);
+				check(theme, name + ': says a text version is shown', (c.banner || '').indexOf('The diagram renderer did not load, so a text version is shown instead.') === 0, c.banner);
+				check(theme, name + ': shows the host\'s text version of the same spec, visibly', c.ascii === asciiById[records[name].record.id] && c.ascii.length > 40 && c.asciiShown === true, JSON.stringify({ shown: c.asciiShown, got: (c.ascii || '').slice(0, 80) }));
+				check(theme, name + ': in a monospaced block that keeps its columns', c.mono === true && c.pre === 'pre', JSON.stringify([c.mono, c.pre]));
+				check(theme, name + ': the source is still there, folded away', c.source === true && c.sourceOpen === false, JSON.stringify([c.source, c.sourceOpen]));
+				check(theme, name + ': no Retry — asking the model again would not help', c.retry === false);
+			}
+			check(theme, 'the hostile labels are in the text version as text', /<img src=x onerror="window\.\.\./.test(card('hostile').ascii || '') && /<iframe src=\/\/example/.test(card('hostile').ascii || '') && /<\/text><foreignObject>/.test(card('hostile').ascii || ''), (card('hostile').ascii || '').slice(0, 200));
+			check(theme, 'a diagram with nothing drawable is unchanged: the error, the source, Retry', card('failed').banner === 'This diagram could not be drawn.' && card('failed').retry && card('failed').ascii === null && card('failed').source, JSON.stringify(card('failed')));
+			check(theme, 'a clean diagram\'s banner says only that', card('jev').banner === 'The diagram renderer did not load, so a text version is shown instead.', card('jev').banner);
+			check(theme, 'a degraded diagram still says what it lost', /shown instead\. 1 edge dropped: unknown nodes/.test(card('degraded').banner || ''), card('degraded').banner);
+			const want = ['jev', 'hostile', 'degraded'].map((n) => ({ action: 'ascii', id: records[n].record.id, keys: 'action,cols,id,type' }));
+			check(theme, 'the host was asked for text by id, once per drawable diagram, with a column count and nothing else', JSON.stringify(r.asked) === JSON.stringify(want), JSON.stringify(r.asked));
+			// a 900px window: the card is about 850px wide, and 12px monospace is about 7px a character
+			check(theme, 'the column count is what fits the card', (r.askedCols || []).length === 3 && r.askedCols.every((c) => Number.isInteger(c) && c >= 90 && c <= 130), JSON.stringify(r.askedCols));
+			check(theme, 'the card does not repeat its own title inside the text', !(card('jev').ascii || '').includes('Jev classifies; your code decides the action'));
+			check(theme, 'each is counted as a render that failed', (r.renderReports || []).length === 3 && r.renderReports.every((x) => x.ok === false && /did not load/.test(x.message)), JSON.stringify(r.renderReports));
+		}
+	}
+
+	console.log(passed + ' checks passed' + (failures.length ? ', ' + failures.length + ' FAILED:' : '.'));
+	for (const f of failures) { console.log('  ✗ ' + f); }
+	console.log('Screenshots and reports: ' + out);
+	process.exit(failures.length ? 1 : 0);
+}
+
+main();
diff --git a/extensions/levelcode-ai/scripts/diagram-editor-check.js b/extensions/levelcode-ai/scripts/diagram-editor-check.js
new file mode 100755
index 0000000..688cc5f
--- /dev/null
+++ b/extensions/levelcode-ai/scripts/diagram-editor-check.js
@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — rich diagrams, checked in the REAL editor  (docs/RICH-DIAGRAMS.md, "How to check it")
+ *
+ *  The unit suites run the pieces; diagram-browser-check.js runs the chat page in a plain browser.
+ *  Neither is the editor. This one is: it starts the dev build (vscode/.build/electron) as a second,
+ *  throwaway instance — its own profile, its own sessions folder, an empty workspace — with THIS
+ *  checkout's extension loaded in place of the built-in one, points it at a stand-in for a provider
+ *  running on localhost, and drives the chat through the DevTools protocol. Then it asks the real
+ *  webview what it drew.
+ *
+ *  What it proves, end to end, with no key and no cost:
+ *    • the editor is running this checkout's extension, and the chat page has its renderer
+ *    • the model is offered render_diagram, with the rules, and gets {"ok":true,"id":…} back
+ *    • the diagram is painted in the real webview, in the editor's theme, from the painter's elements
+ *    • a linked node opens its file at the symbol; the session on disk holds the diagram
+ *    • a wider column re-lays the diagram out; nothing throws in the page
+ *    • the answer around it renders as Markdown — including backticks quoted inside backticks,
+ *      which used to shred the paragraph one streamed fragment per line
+ *
+ *  It exists because of a mistake: the feature was first reported "done" having only ever run in a
+ *  browser, with instructions for trying it that could not have worked. A checkout that is not the
+ *  one holding vscode/ (a git worktree, say) cannot be launched with run-dev.sh — but its extension
+ *  can be loaded into the build that is there, which is all this script and the tip below do.
+ *
+ *  RUN:   node extensions/levelcode-ai/scripts/diagram-editor-check.js [--vscode <dir>] [--out <dir>] [--keep]
+ *         --vscode  the built vscode/ checkout (default: <repo>/vscode, else $LEVELCODE_VSCODE_DIR).
+ *                   From a worktree, pass the main checkout's:  --vscode ../../../vscode
+ *         --keep    leave the editor open afterwards, to look around (its profile is a temp folder)
+ *  NEEDS: the dev build (./scripts/run-dev.sh has been run once), macOS or Linux, Node 22+.
+ *  NOTE:  an editor window opens on your screen for about a minute. It is a separate instance: it does
+ *         not join an editor you already have open, and it touches neither your profile nor your sessions.
+ *  EXIT:  0 all checks pass · 1 a check failed · 2 could not run (no build, no window).
+ *
+ *  TO TRY IT BY HAND with your own account or key, from the checkout that has vscode/:
+ *    ./scripts/run-dev.sh --extensionDevelopmentPath=/absolute/path/to/this/checkout/extensions/levelcode-ai
+ *  (quit a dev editor that is already open first — a running one is joined, not replaced).
+ *
+ *  Not part of scripts/test-extensions.sh: that gate is plain Node, and stays that way.
+ *--------------------------------------------------------------------------------------------*/
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+const cp = require('child_process');
+
+const EXT = path.join(__dirname, '..');
+const REPO = path.join(EXT, '..', '..');
+const argv = process.argv.slice(2);
+const opt = (name) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; };
+const VSCODE_DIR = path.resolve(opt('--vscode') || process.env.LEVELCODE_VSCODE_DIR || path.join(REPO, 'vscode'));
+const OUT = path.resolve(opt('--out') || fs.mkdtempSync(path.join(os.tmpdir(), 'lc-diagram-editor-')));
+const KEEP = argv.includes('--keep');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const T = String.fromCharCode(96);
+
+/** What the stand-in model draws, and says. The answer quotes three backticks inside four — the text from the report. */
+const SPEC = {
+	title: 'Jev classifies; your code decides the action',
+	nodes: [{ id: 'in', label: 'Customer message', sub: 'plus account details' }, { id: 'jev', label: 'Jev', sub: 'returns probabilities', accent: true, link: { path: 'src/router.js', symbol: 'route' } }, { id: 'bill', label: 'Route to billing' }, { id: 'rev', label: 'Human review' }],
+	edges: [{ from: 'in', to: 'jev' }, { from: 'jev', to: 'bill', label: '0.90 or more' }, { from: 'jev', to: 'rev', label: 'under 0.90' }]
+};
+const ANSWER = 'Done: Jev only scores the message; the 0.90 threshold lives in ' + T + 'src/router.js' + T + '. A fence is closed by a plain ' + T.repeat(4) + ' ' + T.repeat(3) + ' ' + T.repeat(4) + '. The rest of this sentence used to arrive one fragment per line.';
+
+// ---- the stand-in provider: OpenAI-compatible, streams one render_diagram call, then the answer ----
+const requests = [];
+function startProvider() {
+	return new Promise((resolve) => {
+		const server = http.createServer((req, res) => {
+			let body = '';
+			req.on('data', (c) => { body += c; });
+			req.on('end', () => {
+				let j = {}; try { j = JSON.parse(body || '{}'); } catch (e) { /* not JSON */ }
+				const msgs = Array.isArray(j.messages) ? j.messages : [];
+				const sys = msgs.filter((m) => m.role === 'system').map((m) => (typeof m.content === 'string' ? m.content : JSON.stringify(m.content))).join('\n');
+				const lastTool = msgs.filter((m) => m.role === 'tool').pop();
+				requests.push({ stream: !!j.stream, tools: (j.tools || []).map((t) => t.function && t.function.name), rules: /DIAGRAMS\. This client renders real diagrams/.test(sys), toolResult: lastTool ? String(lastTool.content) : null });
+				if (req.method === 'GET') { res.writeHead(200, { 'content-type': 'application/json' }); res.end(JSON.stringify({ data: [{ id: 'stand-in' }] })); return; }
+				if (!j.stream) { res.writeHead(200, { 'content-type': 'application/json' }); res.end(JSON.stringify({ choices: [{ message: { role: 'assistant', content: 'Message routing' }, finish_reason: 'stop' }], usage: { prompt_tokens: 10, completion_tokens: 3 } })); return; }
+				res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
+				const send = (o) => res.write('data: ' + JSON.stringify(o) + '\n\n');
+				const chunk = (delta, finish) => send({ id: 'c1', object: 'chat.completion.chunk', model: j.model, choices: [{ index: 0, delta, finish_reason: finish || null }] });
+				(async () => {
+					if (lastTool) {
+						// a few characters at a time, as a model streams — the way the shredded paragraph arrived
+						for (let i = 0; i < ANSWER.length; i += 7) { chunk({ content: ANSWER.slice(i, i + 7) }); await sleep(8); }
+						chunk({}, 'stop');
+					} else {
+						for (const t of ['Here is how a message ', 'is routed.']) { chunk({ content: t }); await sleep(30); }
+						const args = JSON.stringify(SPEC);
+						chunk({ tool_calls: [{ index: 0, id: 'call_diagram_1', type: 'function', function: { name: 'render_diagram', arguments: '' } }] });
+						for (let i = 0; i < args.length; i += 40) { chunk({ tool_calls: [{ index: 0, function: { arguments: args.slice(i, i + 40) } }] }); await sleep(20); }
+						chunk({}, 'tool_calls');
+					}
+					send({ id: 'c1', object: 'chat.completion.chunk', model: j.model, choices: [], usage: { prompt_tokens: 1200, completion_tokens: 150 } });
+					res.write('data: [DONE]\n\n'); res.end();
+				})();
+			});
+		});
+		server.listen(0, '127.0.0.1', () => resolve(server));
+	});
+}
+
+// ---- a minimal DevTools-protocol client (Node's own WebSocket and fetch) ----
+function connect(wsUrl) {
+	return new Promise((resolve, reject) => {
+		const ws = new WebSocket(wsUrl);
+		let id = 0; const pending = new Map(); const events = [];
+		ws.onopen = () => resolve({
+			send: (method, params) => new Promise((res, rej) => { const i = ++id; pending.set(i, { res, rej }); ws.send(JSON.stringify({ id: i, method, params: params || {} })); }),
+			events, close: () => { try { ws.close(); } catch (e) { /* closed */ } }
+		});
+		ws.onerror = () => reject(new Error('could not connect to ' + wsUrl));
+		ws.onmessage = (m) => {
+			const o = JSON.parse(m.data);
+			if (o.id && pending.has(o.id)) { const p = pending.get(o.id); pending.delete(o.id); if (o.error) { p.rej(new Error(o.error.message)); } else { p.res(o.result); } }
+			else if (o.method) { events.push(o); }
+		};
+	});
+}
+async function evalIn(c, expression) {
+	const r = await c.send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true });
+	if (r.exceptionDetails) { throw new Error('the page threw: ' + ((r.exceptionDetails.exception && r.exceptionDetails.exception.description) || r.exceptionDetails.text)); }
+	return r.result.value;
+}
+const targets = async (port) => { try { return await (await fetch('http://127.0.0.1:' + port + '/json/list')).json(); } catch (e) { return []; } };
+/** Wait for a RESULT, with a deadline — never for a length of time. */
+async function until(what, fn, ms) {
+	const end = Date.now() + (ms || 30000);
+	for (;;) { const v = await fn(); if (v) { return v; } if (Date.now() > end) { throw new Error('timed out waiting for ' + what); } await sleep(200); }
+}
+
+async function main() {
+	if (typeof WebSocket !== 'function' || typeof fetch !== 'function') { console.error('Needs Node 22 or newer (for its built-in WebSocket).'); return 2; }
+	let product;
+	try { product = JSON.parse(fs.readFileSync(path.join(VSCODE_DIR, 'product.json'), 'utf8')); }
+	catch (e) { console.error('No editor build at ' + VSCODE_DIR + '.\nRun ./scripts/run-dev.sh once in the checkout that has vscode/, then pass that folder with --vscode (a git worktree has none of its own).'); return 2; }
+	const exe = process.platform === 'darwin'
+		? path.join(VSCODE_DIR, '.build', 'electron', product.nameLong + '.app', 'Contents', 'MacOS', product.nameShort)
+		: path.join(VSCODE_DIR, '.build', 'electron', product.applicationName);
+	if (!fs.existsSync(exe)) { console.error('The editor has not been built yet (' + exe + ' is missing). Run ./scripts/run-dev.sh once.'); return 2; }
+
+	fs.mkdirSync(OUT, { recursive: true });
+	const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lc-editor-check-'));
+	const profile = path.join(tmp, 'profile'), exts = path.join(tmp, 'extensions'), workspace = path.join(tmp, 'workspace'), sessions = path.join(tmp, 'sessions');
+	for (const d of [path.join(profile, 'User'), exts, path.join(workspace, 'src'), sessions]) { fs.mkdirSync(d, { recursive: true }); }
+	fs.writeFileSync(path.join(workspace, 'src', 'router.js'), '// routing\nfunction score(m) { return 0.5; }\n\nfunction route(message) {\n  return score(message) >= 0.9 ? "billing" : "review";\n}\nmodule.exports = { route };\n');
+	const provider = await startProvider();
+	fs.writeFileSync(path.join(profile, 'User', 'settings.json'), JSON.stringify({
+		'levelcode.ai.providerMode': 'byok', 'levelcode.ai.provider': 'custom', 'levelcode.ai.baseURL': 'http://127.0.0.1:' + provider.address().port + '/v1', 'levelcode.ai.model': 'stand-in',
+		'levelcode.ai.sessions.dir': sessions, 'workbench.startupEditor': 'none', 'telemetry.telemetryLevel': 'off', 'window.restoreWindows': 'none'
+	}, null, 2));
+	const debugPort = 9300 + Math.floor(Math.random() * 600);
+	const args = ['.', '--user-data-dir=' + profile, '--extensions-dir=' + exts, '--extensionDevelopmentPath=' + EXT, '--remote-debugging-port=' + debugPort,
+		'--disable-extension=GitHub.copilot-chat', '--disable-extension=vscode.vscode-api-tests', '--new-window', '--skip-welcome', '--skip-release-notes', '--disable-workspace-trust',
+		// keep painting when the window is behind others: the screenshots come from the page, not the screen
+		'--disable-backgrounding-occluded-windows', '--disable-renderer-backgrounding', '--disable-features=CalculateNativeWinOcclusion', workspace];
+	console.log('Starting the editor (a window will open): ' + path.relative(process.cwd(), exe));
+	const child = cp.spawn(exe, args, { cwd: VSCODE_DIR, env: Object.assign({}, process.env, { NODE_ENV: 'development', VSCODE_DEV: '1', VSCODE_CLI: '1' }), stdio: 'ignore' });
+
+	const failures = []; let passed = 0;
+	const check = (name, ok, detail) => { if (ok) { passed++; } else { failures.push(name + (detail ? ' — ' + detail : '')); } };
+	let wb = null, wv = null, code = 0;
+	try {
+		const page = await until('the editor window', async () => (await targets(debugPort)).find((t) => t.type === 'page' && /workbench/.test(t.url)), 120000);
+		wb = await connect(page.webSocketDebuggerUrl);
+		await wb.send('Runtime.enable'); await wb.send('Page.enable');
+		await until('the workbench', () => evalIn(wb, '!!document.querySelector(".monaco-workbench .part.editor")'), 60000);
+
+		// the chat: it opens by itself in a new profile; ask for it (Ctrl+Cmd+I / Ctrl+Alt+I) if it has not
+		const findChat = async () => {
+			for (const t of (await targets(debugPort)).filter((x) => /^vscode-webview:/.test(x.url))) {
+				let c; try { c = await connect(t.webSocketDebuggerUrl); } catch (e) { continue; }
+				try {
+					await c.send('Runtime.enable');
+					if (await evalIn(c, '(() => { const f = document.getElementById("active-frame"); const d = f && f.contentDocument; return !!(d && d.getElementById("input") && d.getElementById("log")); })()')) { return c; }
+				} catch (e) { /* not ready yet */ }
+				c.close();
+			}
+			return null;
+		};
+		let asked = 0;
+		wv = await until('the chat', async () => {
+			const c = await findChat(); if (c) { return c; }
+			if (asked++ % 10 === 9) { for (const type of ['keyDown', 'keyUp']) { await wb.send('Input.dispatchKeyEvent', { type, modifiers: process.platform === 'darwin' ? 6 : 3, key: 'i', code: 'KeyI', windowsVirtualKeyCode: 73 }); } }
+			return null;
+		}, 90000);
+		const D = 'document.getElementById("active-frame").contentDocument', W = 'document.getElementById("active-frame").contentWindow';
+
+		const pageInfo = await evalIn(wv, `(() => { const w = ${W}, d = ${D}; return { modules: w.LCDiagram ? Object.keys(w.LCDiagram).sort() : null, mode: (d.getElementById('modeLabel') || {}).textContent, csp: (d.querySelector('meta[http-equiv="Content-Security-Policy"]') || {}).content || '' }; })()`);
+		check('the editor is running THIS checkout\'s extension — the chat page has the diagram renderer', Array.isArray(pageInfo.modules) && pageInfo.modules.join() === 'ascii,layout,repair,scene,schema,text,theme,validate', JSON.stringify(pageInfo.modules));
+		check('the chat page\'s policy still allows no network and only its own scripts', /default-src 'none'/.test(pageInfo.csp) && /script-src 'nonce-[^']+'$/.test(pageInfo.csp.trim()) && !/https?:|connect-src|\*/.test(pageInfo.csp), pageInfo.csp);
+		check('the chat opens in Agent mode', pageInfo.mode === 'Agent', pageInfo.mode);
+
+		await evalIn(wv, `(() => { const d = ${D}; const i = d.getElementById('input'); i.focus(); i.value = 'How is a customer message routed?'; i.dispatchEvent(new Event('input', { bubbles: true })); d.getElementById('send').click(); return true; })()`);
+		// a new profile has no key: the editor asks for one, and gets a stand-in (kept in the temp profile only)
+		const first = await until('the key prompt, or the first request', async () => {
+			if (requests.some((r) => r.stream)) { return 'request'; }
+			return (await evalIn(wb, '(() => { const q = document.querySelector(".quick-input-widget"); return !!(q && q.style.display !== "none" && q.querySelector("input")); })()')) ? 'prompt' : null;
+		}, 30000);
+		if (first === 'prompt') {
+			// Something else may take the focus while this happens (a new profile opens its Welcome page
+			// when it feels like it), so: focus the box, type if it is empty, press Enter, and look —
+			// until the box has gone.
+			const box = '(() => { const q = document.querySelector(".quick-input-widget"); const i = q && q.style.display !== "none" ? q.querySelector("input") : null; if (!i) { return null; } i.focus(); return { typed: i.value.length, focused: document.activeElement === i }; })()';
+			await until('the key to be accepted', async () => {
+				const state = await evalIn(wb, box);
+				if (!state) { return true; }
+				if (!state.typed) { await wb.send('Input.insertText', { text: 'stand-in-key-for-a-local-provider' }); await sleep(200); return false; }
+				for (const type of ['keyDown', 'keyUp']) { await wb.send('Input.dispatchKeyEvent', { type, key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 36, text: type === 'keyDown' ? '\r' : undefined }); }
+				await sleep(500);
+				return false;
+			}, 30000);
+		}
+
+		await until('the diagram', () => evalIn(wv, `(() => !!${D}.querySelector('figure.lcd[data-id]'))()`), 60000);
+		await until('the answer', async () => requests.filter((r) => r.stream).length >= 2 && await evalIn(wv, `(() => /one fragment per line/.test(${D}.getElementById('log').innerText) && !!${D}.querySelector('.msgcopy'))()`), 45000);
+
+		const first1 = requests.filter((r) => r.stream)[0] || {}, second = requests.filter((r) => r.stream)[1] || {};
+		check('the model is offered render_diagram', (first1.tools || []).includes('render_diagram'), JSON.stringify(first1.tools));
+		check('…together with the rules for using it', first1.rules === true);
+		check('the call is answered with the diagram\'s id', second.toolResult === '{"ok":true,"id":"d-1"}', String(second.toolResult));
+
+		// bring the chat's tab forward if it is an editor tab, so the pictures below show it
+		const tab = await evalIn(wb, `(() => { const t = Array.from(document.querySelectorAll('.tabs-container .tab')).find((e) => /LevelCode AI/.test(e.getAttribute('aria-label') || e.textContent || '')); if (!t) { return null; } const r = t.getBoundingClientRect(); return { x: Math.round(r.x + r.width / 2), y: Math.round(r.y + r.height / 2) }; })()`);
+		const narrow = await evalIn(wv, `(() => { const d = ${D}; const s = d.querySelector('figure.lcd .lcd-stage svg'); return { column: d.documentElement.clientWidth, box: s ? s.getAttribute('viewBox') : null }; })()`);
+		if (tab) { for (const type of ['mousePressed', 'mouseReleased']) { await wb.send('Input.dispatchMouseEvent', { type, x: tab.x, y: tab.y, button: 'left', clickCount: 1 }); } }
+		await until('the chat to be in view', () => evalIn(wv, `(() => ${D}.visibilityState === 'visible' && ${D}.documentElement.clientWidth > 0)()`), 20000).catch(() => null);
+		await sleep(1200);
+
+		const chat = await evalIn(wv, `(() => {
+			const d = ${D};
+			const c = d.querySelector('figure.lcd'); const svg = c && c.querySelector('.lcd-stage svg'); const tags = {};
+			if (svg) { svg.querySelectorAll('*').forEach((el) => { tags[el.localName] = (tags[el.localName] || 0) + 1; }); }
+			const r = svg ? svg.getBoundingClientRect() : null;
+			const last = Array.from(d.querySelectorAll('.msg.assistant')).pop();
+			const paras = last ? Array.from(last.querySelectorAll('p')).map((p) => p.innerHTML) : [];
+			return { column: d.documentElement.clientWidth, id: c && c.dataset.id, status: c && c.dataset.status, pending: d.querySelectorAll('figure.lcd.lcd-pending').length, title: c && (c.querySelector('.lcd-title-text') || {}).textContent,
+				svg: !!svg, tags, width: r ? Math.round(r.width) : 0, box: svg ? svg.getAttribute('viewBox') : null, texts: svg ? Array.from(svg.querySelectorAll('text')).map((t) => t.textContent) : [],
+				links: c ? c.querySelectorAll('[data-lc-link]').length : 0, textColour: svg ? getComputedStyle(svg.querySelector('text')).fill : '', accentStroke: svg && svg.querySelector('.lcd-accent rect') ? getComputedStyle(svg.querySelector('.lcd-accent rect')).stroke : '',
+				paras, pres: last ? last.querySelectorAll('pre').length : -1, divs: last ? last.querySelectorAll('div').length : -1 };
+		})()`);
+		check('the diagram is drawn: one card, finished, titled', chat.id === 'd-1' && chat.status === 'ok' && chat.pending === 0 && chat.title === SPEC.title, JSON.stringify({ id: chat.id, status: chat.status, pending: chat.pending, title: chat.title }));
+		check('…as an SVG made only of the painter\'s elements', chat.svg && Object.keys(chat.tags).every((t) => ['g', 'rect', 'path', 'text', 'title'].includes(t)), JSON.stringify(chat.tags));
+		check('…with every label on it', ['Customer message', 'plus account details', 'Jev', 'returns probabilities', 'Route to billing', 'Human review', '0.90 or more', 'under 0.90'].every((t) => chat.texts.includes(t)), JSON.stringify(chat.texts));
+		check('…in the editor\'s colours (the theme\'s text colour, and an accent)', /^rgb|^color/.test(chat.textColour) && chat.accentStroke && chat.accentStroke !== chat.textColour && chat.accentStroke !== 'none', JSON.stringify([chat.textColour, chat.accentStroke]));
+		check('…never wider than the chat column', chat.width > 0 && chat.width <= chat.column, chat.width + ' in ' + chat.column);
+		check('a wider column re-lays it out (it was drawn for ' + narrow.column + 'px, the column is now ' + chat.column + 'px)', chat.column <= narrow.column + 40 || chat.box !== narrow.box, narrow.box + ' → ' + chat.box);
+		const answer = chat.paras.find((p) => /Done: Jev only scores/.test(p)) || '';
+		check('the answer is ONE paragraph, with the quoted fence as inline code — not a code block, not a line per fragment', chat.pres === 0 && /closed by a plain <code>```<\/code>\. The rest of this sentence used to arrive one fragment per line\.$/.test(answer), JSON.stringify({ pres: chat.pres, answer: answer.slice(0, 260) }));
+
+		const shot = async (name) => { const s = await wb.send('Page.captureScreenshot', { format: 'png' }); fs.writeFileSync(path.join(OUT, name), Buffer.from(s.data, 'base64')); };
+		await shot('editor-chat.png');
+
+		// a click on the linked node: the editor opens the file at the symbol
+		await evalIn(wv, `(() => { const d = ${D}; const n = d.querySelector('figure.lcd [data-lc-link]'); if (!n) { return false; } n.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, view: d.defaultView })); return true; })()`);
+		const opened = await until('router.js to open', () => evalIn(wb, '(() => { const t = Array.from(document.querySelectorAll(".tabs-container .tab")).map((e) => (e.getAttribute("aria-label") || e.textContent || "").trim()); if (!t.some((x) => /router\\.js/.test(x))) { return null; } const s = document.querySelector(".statusbar [id=\\"status.editor.selection\\"]"); return { tabs: t, cursor: s ? s.textContent.trim() : "" }; })()'), 20000).catch(() => null);
+		check('clicking the linked node opens src/router.js', !!opened, 'no router.js tab appeared');
+		const cursor = opened ? await until('the cursor', () => evalIn(wb, '(() => { const s = document.querySelector(".statusbar [id=\\"status.editor.selection\\"]"); const t = s ? s.textContent.trim() : ""; return /Ln \\d+/.test(t) ? t : null; })()'), 10000).catch(() => '') : '';
+		check('…at the symbol: line 4, where function route begins', /^Ln 4,/.test(cursor), JSON.stringify(cursor));
+		await sleep(500);
+		await shot('editor-link.png');
+
+		const files = []; (function walk(dir) { for (const f of fs.readdirSync(dir)) { const p = path.join(dir, f); if (fs.statSync(p).isDirectory()) { walk(p); } else { files.push(p); } } })(sessions);
+		const kinds = files.filter((f) => /\.jsonl$/.test(f)).map((f) => fs.readFileSync(f, 'utf8').trim().split('\n').map((l) => { try { return JSON.parse(l).kind; } catch (e) { return '?'; } }));
+		check('the session on disk holds the diagram, after the turn that drew it', kinds.length === 1 && kinds[0].indexOf('diagram') > kinds[0].indexOf('agent') && kinds[0].indexOf('agent') > 0, JSON.stringify(kinds));
+		const thrown = wv.events.filter((e) => e.method === 'Runtime.exceptionThrown').map((e) => ((e.params.exceptionDetails.exception && e.params.exceptionDetails.exception.description) || e.params.exceptionDetails.text).slice(0, 200));
+		check('nothing threw in the chat page', thrown.length === 0, thrown.join(' | '));
+		fs.writeFileSync(path.join(OUT, 'report.json'), JSON.stringify({ pageInfo, chat, narrow, opened, cursor, kinds, requests }, null, 2));
+	} catch (e) {
+		failures.push('the run did not finish: ' + (e && e.message || e));
+		try { if (wb) { const s = await wb.send('Page.captureScreenshot', { format: 'png' }); fs.writeFileSync(path.join(OUT, 'editor-failed.png'), Buffer.from(s.data, 'base64')); } } catch (e2) { /* no picture */ }
+		if (!wb) { code = 2; }
+	} finally {
+		try { if (wv) { wv.close(); } if (wb) { wb.close(); } } catch (e) { /* closed */ }
+		if (KEEP) { console.log('--keep: the editor is left open. Its profile, sessions and workspace are in ' + tmp); }
+		else {
+			try { child.kill('SIGTERM'); } catch (e) { /* gone */ }
+			await sleep(1500);
+			try { child.kill('SIGKILL'); } catch (e) { /* gone */ }
+			try { fs.rmSync(tmp, { recursive: true, force: true }); } catch (e) { /* a temp folder */ }
+		}
+		provider.close();
+	}
+	console.log(passed + ' checks passed' + (failures.length ? ', ' + failures.length + ' FAILED:' : '.'));
+	for (const f of failures) { console.log('  ✗ ' + f); }
+	console.log('Screenshots and report: ' + OUT);
+	return failures.length ? (code || 1) : 0;
+}
+
+main().then((c) => process.exit(c), (e) => { console.error(e); process.exit(2); });
diff --git a/extensions/levelcode-ai/scripts/diagram-eval.js b/extensions/levelcode-ai/scripts/diagram-eval.js
new file mode 100755
index 0000000..91a0508
--- /dev/null
+++ b/extensions/levelcode-ai/scripts/diagram-eval.js
@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — the diagram eval  (docs/RICH-DIAGRAMS.md, "Telemetry and evaluation")
+ *
+ *  "For each registry model, 30 prompts that should produce a diagram and 10 that should not, scored
+ *  on format choice, first-pass validity, node count and title quality. Models below the bar get the
+ *  fallback."
+ *
+ *  This runs the REAL agent loop — the same system prompt, the same tool list, the same repair
+ *  ladder — once per prompt in test/fixtures/diagrams/eval-prompts.json, and reports the spec's table
+ *  for the model: first-pass valid rate, fix share by rung, degraded rate, top error classes, tokens
+ *  per diagram, ASCII leaks — plus whether it drew when it should have and stayed quiet when it
+ *  should not. The numbers come from the same counters the editor keeps (diagram/stats.js).
+ *
+ *  USAGE
+ *    node extensions/levelcode-ai/scripts/diagram-eval.js --dry-run
+ *        No network, no key. A scripted "model" drives the loop, to check the harness itself.
+ *    node extensions/levelcode-ai/scripts/diagram-eval.js --run --model <id> [--provider <id>] [--limit N] [--json out.json]
+ *        Calls the provider. --provider defaults to openrouter; the key is read from DIAGRAM_EVAL_KEY,
+ *        else the provider's usual variable (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY …).
+ *
+ *  COST: --run makes real, billed calls on your key — up to MAX_STEPS (6) model turns per prompt, 40
+ *  prompts by default (so at most 240; a model that answers directly uses about 70), each carrying the
+ *  agent's full system prompt and tool list. It prints the plan and the model before the first call.
+ *  Use --limit to try a few first. Nothing is sent without --run.
+ *
+ *  It never runs a command or edits a file: the workspace is an empty temporary folder, and every
+ *  approval is answered "no".
+ *
+ *  EXIT: 0 the model meets the bar · 1 it does not · 2 usage or configuration error.
+ *--------------------------------------------------------------------------------------------*/
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const Module = require('module');
+
+const EXT = path.join(__dirname, '..');
+
+/** Model turns one prompt may use. Enough to look around, draw, take one repair pass and answer. */
+const MAX_STEPS = 6;
+/** One prompt may take this long before it is stopped and counted as an error. */
+const PROMPT_TIMEOUT_MS = 180000;
+
+/** The bar a model has to clear to be given the tool (the spec's proposed targets). */
+const BAR = Object.freeze({ firstPassValid: 90, degraded: 2, formatChoice: 90, asciiLeaks: 0 });
+
+/**
+ * Does a title name a TOPIC rather than state a takeaway? The style guide's first rule is the
+ * opposite ("Every steer has two routes into the run", not "Steering"). A heuristic, reported as a
+ * rate — it is a signal for the prompt examples, not a gate.
+ */
+function looksLikeTopic(title) {
+	const t = String(title || '').trim();
+	const words = t.split(/\s+/).filter(Boolean);
+	if (words.length <= 3) { return true; }
+	return /\b(flow|diagram|architecture|overview|lifecycle|pipeline|process|structure|states?|components?|pattern)\s*$/i.test(t) && words.length <= 6;
+}
+
+/**
+ * agent.js outside the editor: `vscode` becomes an empty workspace in a temporary folder. Loaded once
+ * per process — the module keeps the `vscode` it was first given, so the folder has to outlive it.
+ */
+let host = null;
+function loadAgent() {
+	if (host) { return host; }
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lc-diagram-eval-'));
+	process.on('exit', () => { try { fs.rmSync(root, { recursive: true, force: true }); } catch (e) { /* a temp folder */ } });
+	const vscodeMock = { workspace: { workspaceFolders: [{ uri: { fsPath: root }, name: 'eval' }], findFiles: async () => [], asRelativePath: (u) => String(u && u.fsPath || u) }, env: { appRoot: root } };
+	const origLoad = Module._load;
+	// @ts-ignore — a loader shim, for the two requires below only
+	Module._load = function (request, parent, isMain) { return request === 'vscode' ? vscodeMock : origLoad.call(this, request, parent, isMain); };
+	try {
+		host = { providers: require(path.join(EXT, 'providers', 'index')), runAgent: require(path.join(EXT, 'agent')).runAgent, root };
+	} finally {
+		// @ts-ignore
+		Module._load = origLoad;
+	}
+	return host;
+}
+
+/**
+ * Run the eval.
+ * @param {{ prompts: Array<{id:string, expect:'draw'|'none', text:string}>, model: string, providerId?: string, apiKey?: string, baseURL?: string,
+ *           turn?: (opts:any, prompt:any) => Promise<any>, onProgress?: (row:any) => void, maxSteps?: number }} o
+ *        turn: a stand-in for the provider (dry run / tests). Without it the real provider is called.
+ */
+async function evaluate(o) {
+	const { createDiagrams } = require(path.join(EXT, 'diagram', 'service'));
+	const stats = require(path.join(EXT, 'diagram', 'stats'));
+	const { providers, runAgent } = loadAgent();
+	const realTurn = providers.streamAgentTurn;
+	let s = stats.empty(new Date().toISOString().slice(0, 10));
+	const rows = [];
+	let current = null, modelTurns = 0;
+	// agent.js calls providers.streamAgentTurn through the module, so this is the one seam needed: it
+	// counts the turns (the cost) and, in a dry run, answers them.
+	providers.streamAgentTurn = async (opts) => {
+		modelTurns++;
+		return o.turn ? o.turn(opts, current) : realTurn(opts);
+	};
+	try {
+		for (const p of o.prompts) {
+			current = p;
+			const events = [];
+			const diagrams = createDiagrams({ resolveLink: () => ({ ok: false, reason: 'no workspace in the eval' }), onStat: (ev) => { events.push(ev); s = stats.record(s, ev); } });
+			const posted = [];
+			const before = modelTurns;
+			const ac = new AbortController();
+			let timedOut = false;
+			const timer = setTimeout(() => { timedOut = true; ac.abort(); }, o.timeoutMs || PROMPT_TIMEOUT_MS);
+			try {
+				await runAgent({
+					messages: [{ role: 'user', content: p.text }],
+					providerId: o.providerId || 'openrouter', apiKey: o.apiKey || '', baseURL: o.baseURL, model: o.model,
+					maxSteps: o.maxSteps || MAX_STEPS, maxTokens: 2048,
+					post: (m) => posted.push(m), approve: async () => false, ask: async () => null,
+					applyEdit: async () => false, applyDelete: async () => false,
+					diagrams, client: { render: 'rich' }, signal: ac.signal
+				});
+			} finally { clearTimeout(timer); }
+			const records = diagrams.list();
+			const calls = events.filter((e) => e.type === 'call');
+			const verdict = calls.map((e) => e.outcome).filter((x) => x !== 'bounced' && x !== 'truncated').pop() || null;
+			const drew = records.some((r) => r.spec);
+			const leaked = events.some((e) => e.type === 'answer' && e.asciiArt);
+			const last = records.filter((r) => r.spec).pop();
+			const error = posted.find((m) => m.type === 'agentError');
+			const done = posted.filter((m) => m.type === 'agentDone').pop();
+			const row = {
+				id: p.id, expect: p.expect, drew, leaked,
+				formatOk: p.expect === 'draw' ? drew : (!drew && !leaked),
+				firstAttempt: calls.length ? calls[0].outcome : null, verdict,
+				nodes: last ? last.spec.nodes.length : null,
+				overLimit: calls.some((e) => e.errorClasses && e.errorClasses.count),
+				title: last ? last.spec.title : null,
+				titleIsTopic: last ? looksLikeTopic(last.spec.title) : null,
+				turns: modelTurns - before,
+				ended: done ? done.reason : null,
+				error: timedOut ? 'timed out' : error ? String(error.message).slice(0, 200) : null
+			};
+			rows.push(row);
+			if (o.onProgress) { o.onProgress(row); }
+		}
+	} finally {
+		providers.streamAgentTurn = realTurn;
+	}
+	const sum = stats.summarize(s);
+	const pct = (a, b) => (b ? Math.round(1000 * a / b) / 10 : null);
+	const drawn = rows.filter((r) => r.drew);
+	const report = {
+		model: o.model, prompts: rows.length, errors: rows.filter((r) => r.error).length, modelTurns,
+		formatChoice: pct(rows.filter((r) => r.formatOk).length, rows.length),
+		drewWhenItShould: pct(rows.filter((r) => r.expect === 'draw' && r.drew).length, rows.filter((r) => r.expect === 'draw').length),
+		quietWhenItShould: pct(rows.filter((r) => r.expect === 'none' && !r.drew && !r.leaked).length, rows.filter((r) => r.expect === 'none').length),
+		firstPassValid: sum.overall.firstPassValid, autoFixed: sum.overall.autoFixed, modelRepaired: sum.overall.modelRepaired, degraded: sum.overall.degraded,
+		topErrors: sum.topErrors, tokens: sum.tokens, asciiLeaks: sum.asciiLeaks.leaks,
+		overLimit: rows.filter((r) => r.overLimit).length,
+		largest: drawn.reduce((a, r) => Math.max(a, r.nodes), 0),
+		titlesThatAreTopics: pct(drawn.filter((r) => r.titleIsTopic).length, drawn.length),
+		rows
+	};
+	const misses = [];
+	if (report.firstPassValid === null || report.firstPassValid < BAR.firstPassValid) { misses.push('first-pass valid ' + report.firstPassValid + '% (bar: ' + BAR.firstPassValid + '%)'); }
+	if (report.degraded === null || report.degraded >= BAR.degraded) { misses.push('degraded ' + report.degraded + '% (bar: under ' + BAR.degraded + '%)'); }
+	if (report.formatChoice < BAR.formatChoice) { misses.push('format choice ' + report.formatChoice + '% (bar: ' + BAR.formatChoice + '%)'); }
+	if (report.asciiLeaks > BAR.asciiLeaks) { misses.push(report.asciiLeaks + ' ASCII leak(s) (bar: 0)'); }
+	if (report.errors) { misses.push(report.errors + ' prompt(s) ended in an error — the run is incomplete'); }
+	report.misses = misses;
+	report.meetsBar = misses.length === 0;
+	return report;
+}
+
+/**
+ * The dry run's "model": deterministic, offline. It draws for prompts that expect a drawing — cleanly
+ * for most, with one of the usual mistakes for a few so every rung of the ladder is walked — and
+ * answers in prose for the rest (once, wrongly, with an ASCII box).
+ */
+function scriptedModel() {
+	const state = new Map();
+	const spec = (p, flaw) => {
+		const s = { title: 'The ' + p.id + ' path has three steps and one decision', nodes: [{ id: 'a', label: 'Start', shape: 'actor' }, { id: 'b', label: 'Check', shape: 'decision', accent: true }, { id: 'c', label: 'Do the work' }, { id: 'd', label: 'Done' }], edges: [{ from: 'a', to: 'b' }, { from: 'b', to: 'c', label: 'yes' }, { from: 'b', to: 'd', label: 'no' }, { from: 'c', to: 'd' }] };
+		if (flaw === 'long') { s.nodes[2].label = 'Do all of the work that this step is responsible for'; }
+		if (flaw === 'synonym') { s.nodes[1].shape = 'diamond'; }
+		if (flaw === 'ghost') { s.edges.push({ from: 'c', to: 'nowhere' }); }
+		if (flaw === 'accents') { s.nodes[2].accent = true; }
+		if (flaw === 'topic') { s.title = 'Checkout flow'; }
+		return s;
+	};
+	const FLAWS = { 'pr-states': 'long', 'ci-pipeline': 'synonym', 'dead-letter': 'ghost', 'k8s-objects': 'accents', 'three-tier': 'topic' };
+	// The flaws the editor cannot fix on its own get a second attempt. How many of the two still carry
+	// the flaw: one → put right on the repair pass; both → drawn degraded.
+	const STILL_WRONG = { ghost: 1, accents: 2 };
+	return async (opts, p) => {
+		const n = (state.get(p.id) || 0) + 1; state.set(p.id, n);
+		const usage = { input_tokens: 1000, output_tokens: 200 };
+		if (p.expect !== 'draw') {
+			const text = p.id === 'http-409' ? 'Done: it means a conflict.\n+-------+     +-------+\n| PUT a | --> |  409  |\n+-------+     +-------+' : 'Done: here is the answer in a sentence.';
+			return { stop_reason: 'end_turn', content: [{ type: 'text', text }], usage };
+		}
+		const flaw = FLAWS[p.id];
+		const twoTries = Object.prototype.hasOwnProperty.call(STILL_WRONG, flaw);
+		if (n <= (twoTries ? 2 : 1)) {
+			const carries = twoTries ? n <= STILL_WRONG[flaw] : true;
+			return { stop_reason: 'tool_use', content: [{ type: 'text', text: 'Here it is.' }, { type: 'tool_use', id: 'toolu_' + p.id + '_' + n, name: 'render_diagram', input: spec(p, carries ? flaw : null) }], usage };
+		}
+		return { stop_reason: 'end_turn', content: [{ type: 'text', text: 'Done: the diagram shows the path.' }], usage };
+	};
+}
+
+/**
+ * The first `limit` prompts of a trial run, keeping the file's mix: three that should draw for each
+ * one that should not. (The file lists the 30 first, so a plain slice would never test restraint.)
+ */
+function sample(prompts, limit) {
+	if (!limit || limit >= prompts.length) { return prompts.slice(); }
+	const draw = prompts.filter((p) => p.expect === 'draw'), none = prompts.filter((p) => p.expect !== 'draw');
+	const out = [];
+	while (out.length < limit && (draw.length || none.length)) {
+		const wantNone = out.length % 4 === 3;
+		const next = (wantNone ? none.shift() || draw.shift() : draw.shift() || none.shift());
+		out.push(next);
+	}
+	return out;
+}
+
+function printReport(r) {
+	const line = (k, v) => console.log('  ' + (k + ':').padEnd(30) + v);
+	const n = (v, unit) => (v === null || v === undefined ? 'n/a' : v + (unit || ''));
+	console.log('\nDiagram eval — ' + r.model + ' — ' + r.prompts + ' prompts, ' + r.modelTurns + ' model turns');
+	line('format choice', n(r.formatChoice, '%') + '   (drew when it should: ' + n(r.drewWhenItShould, '%') + ', stayed quiet when it should: ' + n(r.quietWhenItShould, '%') + ')');
+	line('first-pass valid', n(r.firstPassValid, '%'));
+	line('fixed without a model call', n(r.autoFixed, '%'));
+	line('needed the repair pass', n(r.modelRepaired, '%'));
+	line('degraded or failed', n(r.degraded, '%'));
+	line('top error classes', r.topErrors.length ? r.topErrors.map((e) => e.cls + ' ×' + e.count).join(', ') : 'none');
+	line('tokens per diagram', r.tokens.median === null ? 'n/a' : 'median ≤ ' + r.tokens.median + ', p95 ≤ ' + r.tokens.p95);
+	line('asked for too much', r.overLimit + ' prompt(s) went over a count limit; the largest drawn has ' + r.largest + ' nodes');
+	line('titles that are topics', n(r.titlesThatAreTopics, '%'));
+	line('ASCII leaks', String(r.asciiLeaks));
+	const wrong = r.rows.filter((x) => !x.formatOk || x.error);
+	if (wrong.length) {
+		console.log('\n  Misjudged or failed prompts:');
+		for (const x of wrong) { console.log('    ' + x.id + ' (expected ' + x.expect + '): ' + (x.error ? 'error — ' + x.error : x.drew ? 'drew a diagram' : x.leaked ? 'drew with characters' : x.ended === 'limit' ? 'ran out of turns without drawing' : 'did not draw')); }
+	}
+	console.log('\n' + (r.meetsBar ? '  MEETS THE BAR.' : '  BELOW THE BAR: ' + r.misses.join('; ') + '.'));
+}
+
+const USAGE = [
+	'Usage:',
+	'  diagram-eval.js --dry-run [--limit N]',
+	'  diagram-eval.js --run --model <id> [--provider <id>] [--limit N] [--json out.json]',
+	'',
+	'--dry-run uses a scripted model: no network, no key.',
+	'--run makes billed calls on your key: up to ' + MAX_STEPS + ' model turns per prompt.',
+	'Key: DIAGRAM_EVAL_KEY, else the provider\'s own variable (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, …).',
+	'Base URL override (required for --provider custom): DIAGRAM_EVAL_BASE.'
+].join('\n');
+
+/** The environment variable each provider's key is conventionally kept in. */
+const KEY_VARS = { openrouter: 'OPENROUTER_API_KEY', claude: 'ANTHROPIC_API_KEY', openai: 'OPENAI_API_KEY', groq: 'GROQ_API_KEY', deepseek: 'DEEPSEEK_API_KEY', mistral: 'MISTRAL_API_KEY', xai: 'XAI_API_KEY', together: 'TOGETHER_API_KEY', fireworks: 'FIREWORKS_API_KEY' };
+
+/**
+ * Work out what a command line asks for, WITHOUT doing it. Returns { mode: 'dry' | 'run' | 'usage', … }.
+ * Split from main() so the "nothing is sent without --run, a model and a key" rule can be tested.
+ */
+function plan(argv, env, providerOf) {
+	const flag = (name) => argv.includes(name);
+	const value = (name) => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : undefined; };
+	const limit = value('--limit') === undefined ? null : Number(value('--limit'));
+	if (limit !== null && !(Number.isInteger(limit) && limit > 0)) { return { mode: 'usage', problem: '--limit takes a whole number above zero.' }; }
+	if (flag('--dry-run') && flag('--run')) { return { mode: 'usage', problem: 'Pick one of --dry-run and --run.' }; }
+	if (flag('--dry-run')) { return { mode: 'dry', limit }; }
+	if (!flag('--run')) { return { mode: 'usage' }; }
+	const model = value('--model');
+	if (!model) { return { mode: 'usage', problem: '--run needs --model <id>.' }; }
+	const providerId = value('--provider') || 'openrouter';
+	const p = providerOf(providerId);
+	if (!p) { return { mode: 'usage', problem: 'Unknown provider "' + providerId + '".' }; }
+	const baseURL = env.DIAGRAM_EVAL_BASE || undefined;
+	if (!p.baseURL && p.kind !== 'anthropic' && !baseURL) { return { mode: 'usage', problem: 'Provider "' + providerId + '" has no base URL of its own: set DIAGRAM_EVAL_BASE.' }; }
+	const apiKey = env.DIAGRAM_EVAL_KEY || env[KEY_VARS[providerId] || ''] || '';
+	if (!apiKey && !p.noKey) { return { mode: 'usage', problem: 'No API key: set DIAGRAM_EVAL_KEY' + (KEY_VARS[providerId] ? ' or ' + KEY_VARS[providerId] : '') + '.' }; }
+	return { mode: 'run', model, providerId, apiKey, baseURL, limit, json: value('--json') || null };
+}
+
+async function main() {
+	const all = JSON.parse(fs.readFileSync(path.join(EXT, 'test', 'fixtures', 'diagrams', 'eval-prompts.json'), 'utf8')).prompts;
+	// The registry is plain data; reading it needs no editor.
+	const todo = plan(process.argv.slice(2), process.env, (id) => require(path.join(EXT, 'providers', 'index')).getProvider(id));
+	if (todo.mode === 'usage') {
+		if (todo.problem) { console.error(todo.problem + '\n'); }
+		console.error(USAGE);
+		return 2;
+	}
+	const prompts = sample(all, todo.limit);
+	if (todo.mode === 'dry') {
+		const r = await evaluate({ prompts, model: 'scripted (dry run)', turn: scriptedModel() });
+		printReport(r);
+		console.log('\n  Dry run: a scripted model, no network. It makes the usual mistakes ON PURPOSE so every rung of\n  the repair ladder is walked — the verdict above describes the script, not a model.');
+		return 0;
+	}
+	console.log('About to run ' + prompts.length + ' prompts on ' + todo.providerId + ' / ' + todo.model + ' — up to ' + prompts.length * MAX_STEPS + ' billed model turns on your key.');
+	const r = await evaluate({
+		prompts, model: todo.model, providerId: todo.providerId, apiKey: todo.apiKey, baseURL: todo.baseURL,
+		onProgress: (row) => console.log('  ' + (row.error ? '!' : row.formatOk ? '✓' : '✗') + ' ' + row.id.padEnd(22) + (row.error ? 'ERROR ' + row.error : row.drew ? row.verdict + ', ' + row.nodes + ' nodes' : row.leaked ? 'ASCII art' : 'prose'))
+	});
+	printReport(r);
+	if (!r.meetsBar) { console.log('  To withhold the tool from this model, add `diagrams: false` to its row in providers/catalog.js CAPS.'); }
+	if (todo.json) { fs.writeFileSync(path.resolve(todo.json), JSON.stringify(r, null, 2)); console.log('\n  Written to ' + todo.json); }
+	return r.meetsBar ? 0 : 1;
+}
+
+if (require.main === module) {
+	main().then((code) => process.exit(code), (e) => { console.error(e); process.exit(2); });
+}
+
+module.exports = { evaluate, scriptedModel, looksLikeTopic, plan, sample, BAR, MAX_STEPS };
diff --git a/extensions/levelcode-ai/test/diagramEval.test.js b/extensions/levelcode-ai/test/diagramEval.test.js
new file mode 100644
index 0000000..d163981
--- /dev/null
+++ b/extensions/levelcode-ai/test/diagramEval.test.js
@@ -0,0 +1,249 @@
+/*---------------------------------------------------------------------------------------------
+ *  The diagram eval harness — run: node test/diagramEval.test.js
+ *
+ *  docs/RICH-DIAGRAMS.md, "Telemetry and evaluation": "For each registry model, 30 prompts that should
+ *  produce a diagram and 10 that should not, scored on format choice, first-pass validity, node count
+ *  and title quality. Models below the bar get the fallback."
+ *
+ *  scripts/diagram-eval.js is that eval. It decides whether a model is given the tool, and a --run
+ *  spends money, so two things are pinned here: the SCORE is right (a scripted model whose mistakes
+ *  are known, run through the real agent loop, must come out at exactly the numbers its script
+ *  implies), and NOTHING IS SENT unless --run, a model and a key were all given.
+ *
+ *  No network: every model here is a script.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ev = require('../scripts/diagram-eval');
+const providers = require('../providers/index');
+
+const SCRIPT = path.join(__dirname, '..', 'scripts', 'diagram-eval.js');
+const prompts = JSON.parse(fs.readFileSync(path.join(__dirname, 'fixtures', 'diagrams', 'eval-prompts.json'), 'utf8')).prompts;
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+async function testAsync(name, fn) { await fn(); n++; console.log('  ok - ' + name); }
+
+const good = (p) => ({ title: 'A request is checked once, then served', nodes: [{ id: 'a', label: 'Client' }, { id: 'b', label: 'Gate', accent: true }, { id: 'c', label: 'Service' }], edges: [{ from: 'a', to: 'b' }, { from: 'b', to: 'c', label: p.id.slice(0, 12) }] });
+const draws = (id, input) => ({ stop_reason: 'tool_use', content: [{ type: 'tool_use', id, name: 'render_diagram', input }], usage: { input_tokens: 10, output_tokens: 10 } });
+const says = (text) => ({ stop_reason: 'end_turn', content: [{ type: 'text', text }], usage: { input_tokens: 10, output_tokens: 10 } });
+/** A model that does everything right: draws once when it should, answers in a sentence otherwise. */
+const perfect = () => { const seen = new Set(); return async (opts, p) => { if (p.expect === 'draw' && !seen.has(p.id)) { seen.add(p.id); return draws('t_' + p.id, good(p)); } return says('Done: that is the answer.'); }; };
+const plan = (args, env) => ev.plan(args, env || {}, providers.getProvider);
+
+(async () => {
+	try {
+		test('the prompt set is the one the spec asks for: 30 that should draw, 10 that should not', () => {
+			assert.strictEqual(prompts.filter((p) => p.expect === 'draw').length, 30);
+			assert.strictEqual(prompts.filter((p) => p.expect === 'none').length, 10);
+			assert.strictEqual(new Set(prompts.map((p) => p.id)).size, 40, 'ids are unique');
+			assert.strictEqual(new Set(prompts.map((p) => p.text)).size, 40, 'so are the prompts');
+			for (const p of prompts) { assert.ok(/^[a-z0-9-]+$/.test(p.id) && p.text.length > 15, p.id); }
+			// a prompt that SAYS "diagram" tests obedience, not judgement — the set should be mostly the other kind
+			const told = prompts.filter((p) => p.expect === 'draw' && /\b(diagram|draw)\b/i.test(p.text)).length;
+			assert.ok(told <= 3, told + ' of the 30 ask for a diagram by name');
+		});
+
+		test('NOTHING IS SENT without --run, a model and a key', () => {
+			assert.strictEqual(plan([]).mode, 'usage');
+			assert.strictEqual(plan(['--model', 'x/y'], { OPENROUTER_API_KEY: 'k' }).mode, 'usage', 'a model and a key, but no --run');
+			assert.strictEqual(plan(['--run'], { OPENROUTER_API_KEY: 'k' }).mode, 'usage', 'no model');
+			assert.strictEqual(plan(['--run', '--model'], { OPENROUTER_API_KEY: 'k' }).mode, 'usage');
+			assert.strictEqual(plan(['--run', '--model', '--json'], { OPENROUTER_API_KEY: 'k' }).mode, 'usage', 'a flag is not a model id');
+			assert.match(plan(['--run', '--model', 'x/y'], {}).problem, /No API key: set DIAGRAM_EVAL_KEY or OPENROUTER_API_KEY/);
+			assert.match(plan(['--run', '--model', 'x', '--provider', 'claude'], { OPENROUTER_API_KEY: 'k' }).problem, /ANTHROPIC_API_KEY/, 'another provider\'s key is not borrowed');
+			assert.match(plan(['--run', '--model', 'x', '--provider', 'nope'], { DIAGRAM_EVAL_KEY: 'k' }).problem, /Unknown provider "nope"/);
+			assert.match(plan(['--run', '--model', 'x', '--provider', 'custom'], { DIAGRAM_EVAL_KEY: 'k' }).problem, /set DIAGRAM_EVAL_BASE/);
+			assert.strictEqual(plan(['--run', '--dry-run', '--model', 'x'], { DIAGRAM_EVAL_KEY: 'k' }).mode, 'usage', 'both at once is a mistake, not a run');
+			for (const bad of ['0', '-3', '2.5', 'ten']) { assert.strictEqual(plan(['--dry-run', '--limit', bad]).mode, 'usage', '--limit ' + bad); }
+		});
+
+		test('a complete command line is a run, on the provider and key it names', () => {
+			assert.deepStrictEqual(plan(['--run', '--model', 'x/y'], { OPENROUTER_API_KEY: 'k1' }), { mode: 'run', model: 'x/y', providerId: 'openrouter', apiKey: 'k1', baseURL: undefined, limit: null, json: null });
+			assert.strictEqual(plan(['--run', '--model', 'x/y'], { OPENROUTER_API_KEY: 'k1', DIAGRAM_EVAL_KEY: 'k2' }).apiKey, 'k2', 'the eval\'s own variable wins');
+			const c = plan(['--run', '--model', 'm', '--provider', 'claude', '--limit', '8', '--json', 'out.json'], { ANTHROPIC_API_KEY: 'k3' });
+			assert.deepStrictEqual([c.providerId, c.apiKey, c.limit, c.json], ['claude', 'k3', 8, 'out.json']);
+			assert.strictEqual(plan(['--run', '--model', 'llama', '--provider', 'ollama'], {}).mode, 'run', 'a local provider needs no key');
+			assert.strictEqual(plan(['--run', '--model', 'm', '--provider', 'custom'], { DIAGRAM_EVAL_KEY: 'k', DIAGRAM_EVAL_BASE: 'http://localhost:9/v1' }).baseURL, 'http://localhost:9/v1');
+			assert.deepStrictEqual(plan(['--dry-run']), { mode: 'dry', limit: null });
+		});
+
+		test('a trial run keeps the mix: three that should draw for each one that should not', () => {
+			const eight = ev.sample(prompts, 8);
+			assert.deepStrictEqual(eight.map((p) => p.expect), ['draw', 'draw', 'draw', 'none', 'draw', 'draw', 'draw', 'none']);
+			assert.strictEqual(ev.sample(prompts, null).length, 40);
+			assert.strictEqual(ev.sample(prompts, 400).length, 40);
+			assert.strictEqual(new Set(ev.sample(prompts, 39).map((p) => p.id)).size, 39, 'never the same prompt twice');
+		});
+
+		await testAsync('THE SCORE: a scripted model with known mistakes comes out at exactly the numbers its script implies', async () => {
+			const r = await ev.evaluate({ prompts, model: 'scripted', turn: ev.scriptedModel() });
+			// 30 drawings: 26 clean (one of them with a topic for a title), 2 the editor fixed alone (a long
+			// label, a shape synonym), 1 the model put right on its repair pass, 1 still wrong → degraded.
+			assert.strictEqual(r.firstPassValid, 86.7);
+			assert.strictEqual(r.autoFixed, 6.7);
+			assert.strictEqual(r.modelRepaired, 3.3);
+			assert.strictEqual(r.degraded, 3.3);
+			assert.deepStrictEqual(r.topErrors, [{ cls: 'accent-count', count: 2 }, { cls: 'unknown-node', count: 1 }]);
+			// 10 that should not draw: 9 answered in prose, 1 drew a box out of characters
+			assert.strictEqual(r.drewWhenItShould, 100);
+			assert.strictEqual(r.quietWhenItShould, 90);
+			assert.strictEqual(r.formatChoice, 97.5);
+			assert.strictEqual(r.asciiLeaks, 1);
+			assert.deepStrictEqual(r.rows.filter((x) => !x.formatOk).map((x) => x.id), ['http-409']);
+			assert.strictEqual(r.titlesThatAreTopics, 3.3, 'one title of thirty names a topic');
+			// the cost: 30 × (draw + answer) + 2 second attempts + 10 answers
+			assert.strictEqual(r.modelTurns, 72);
+			assert.strictEqual(r.rows.find((x) => x.id === 'dead-letter').turns, 3);
+			assert.deepStrictEqual([r.rows.find((x) => x.id === 'dead-letter').firstAttempt, r.rows.find((x) => x.id === 'dead-letter').verdict], ['bounced', 'repaired']);
+			assert.strictEqual(r.rows.find((x) => x.id === 'k8s-objects').verdict, 'degraded');
+			assert.strictEqual(r.meetsBar, false);
+			assert.strictEqual(r.misses.length, 3, r.misses.join(' | '));
+		});
+
+		await testAsync('a model that does everything right meets the bar', async () => {
+			const r = await ev.evaluate({ prompts, model: 'perfect', turn: perfect() });
+			assert.deepStrictEqual([r.formatChoice, r.firstPassValid, r.degraded, r.asciiLeaks, r.errors], [100, 100, 0, 0, 0]);
+			assert.deepStrictEqual(r.misses, []);
+			assert.strictEqual(r.meetsBar, true);
+			assert.strictEqual(r.modelTurns, 70);
+			assert.strictEqual(r.titlesThatAreTopics, 0);
+		});
+
+		await testAsync('a model that never draws is below the bar — "no diagrams, so none invalid" is not a pass', async () => {
+			const r = await ev.evaluate({ prompts, model: 'prose-only', turn: async () => says('Done: here it is in words.') });
+			assert.strictEqual(r.drewWhenItShould, 0);
+			assert.strictEqual(r.quietWhenItShould, 100);
+			assert.strictEqual(r.formatChoice, 25);
+			assert.strictEqual(r.firstPassValid, null, 'no verdicts, so no rate');
+			assert.strictEqual(r.meetsBar, false);
+			assert.ok(r.misses.some((m) => /first-pass valid/.test(m)) && r.misses.some((m) => /format choice 25%/.test(m)), r.misses.join(' | '));
+		});
+
+		await testAsync('a model that draws for everything fails on format choice alone', async () => {
+			const seen = new Set();
+			const r = await ev.evaluate({ prompts, model: 'draws-always', turn: async (opts, p) => { if (!seen.has(p.id)) { seen.add(p.id); return draws('t_' + p.id, good(p)); } return says('Done.'); } });
+			assert.deepStrictEqual([r.drewWhenItShould, r.quietWhenItShould, r.formatChoice, r.firstPassValid], [100, 0, 75, 100]);
+			assert.deepStrictEqual(r.misses, ['format choice 75% (bar: 90%)']);
+		});
+
+		await testAsync('a spec over the node limit is counted as asking for too much, whatever is drawn in the end', async () => {
+			const big = (p) => { const s = good(p); for (let i = 0; i < 12; i++) { s.nodes.push({ id: 'x' + i, label: 'Extra ' + i }); } return s; };
+			const tries = new Map();
+			const r = await ev.evaluate({ prompts: prompts.slice(0, 2), model: 'sprawling', turn: async (opts, p) => { const k = (tries.get(p.id) || 0) + 1; tries.set(p.id, k); return k === 1 ? draws('t1_' + p.id, big(p)) : k === 2 ? draws('t2_' + p.id, good(p)) : says('Done.'); } });
+			assert.strictEqual(r.overLimit, 2);
+			assert.strictEqual(r.largest, 3, 'the redraw is what is on screen');
+			assert.strictEqual(r.modelRepaired, 100);
+			assert.deepStrictEqual(r.topErrors, [{ cls: 'count', count: 2 }]);
+		});
+
+		await testAsync('a call that puts no picture on screen is not a drawing', async () => {
+			// nothing drawable, twice: the user is shown the source and the error, not a diagram
+			const tries = new Map();
+			const r = await ev.evaluate({ prompts: prompts.slice(0, 1), model: 'empty-handed', turn: async (opts, p) => { const k = (tries.get(p.id) || 0) + 1; tries.set(p.id, k); return k <= 2 ? draws('t' + k, { title: 'Nothing to see' }) : says('Done.'); } });
+			assert.deepStrictEqual([r.rows[0].firstAttempt, r.rows[0].verdict, r.rows[0].drew, r.rows[0].formatOk], ['bounced', 'failed', false, false]);
+			assert.strictEqual(r.drewWhenItShould, 0);
+			assert.strictEqual(r.degraded, 100, 'and it counts against the degraded rate');
+		});
+
+		await testAsync('a provider error is reported per prompt, the run goes on, and the result is not called a pass', async () => {
+			const inner = perfect();
+			const r = await ev.evaluate({ prompts: prompts.slice(0, 4), model: 'flaky', turn: async (opts, p) => { if (p.id === prompts[1].id) { throw new Error('HTTP 429: rate limited'); } return inner(opts, p); } });
+			assert.strictEqual(r.errors, 1);
+			assert.match(r.rows[1].error, /429/);
+			assert.strictEqual(r.rows[2].drew, true, 'the prompt after the failure still ran');
+			assert.strictEqual(r.meetsBar, false);
+			assert.ok(r.misses.some((m) => /ended in an error — the run is incomplete/.test(m)));
+		});
+
+		await testAsync('a prompt that hangs is stopped, and counted as an error rather than as "did not draw"', async () => {
+			const r = await ev.evaluate({ prompts: prompts.slice(0, 1), model: 'stuck', timeoutMs: 40, turn: (opts) => new Promise((resolve, reject) => { opts.signal.addEventListener('abort', () => reject(new Error('aborted'))); }) });
+			assert.strictEqual(r.rows[0].error, 'timed out');
+			assert.strictEqual(r.errors, 1);
+		});
+
+		await testAsync('the eval gives the model the same tool and rules the editor does, and can run nothing', async () => {
+			let sent = null;
+			await ev.evaluate({ prompts: prompts.slice(0, 1), model: 'peek', turn: async (opts) => { sent = sent || opts; return says('Done.'); } });
+			assert.ok(sent.tools.some((t) => t.name === 'render_diagram'), 'the tool is offered');
+			assert.ok(String(sent.system).includes(require('../diagram/tool').PROMPT), 'with the shipped prompt block, not a copy of it');
+			assert.strictEqual(sent.messages[0].content, prompts[0].text, 'and the prompt is sent as written, with no coaching added');
+			// a model that asks to run a command or write a file is told no — the eval approves nothing
+			const mark = path.join(os.tmpdir(), 'lc-eval-ran-' + process.pid);
+			const told = [];
+			let step = 0;
+			const r = await ev.evaluate({
+				prompts: prompts.slice(0, 1), model: 'runs-things', turn: async (opts) => {
+					step++;
+					if (step === 1) { return { stop_reason: 'tool_use', content: [{ type: 'tool_use', id: 't1', name: 'run_command', input: { command: 'touch ' + mark } }, { type: 'tool_use', id: 't2', name: 'write_file', input: { path: 'x.txt', content: 'hi' } }], usage: {} }; }
+					told.push(opts.messages[opts.messages.length - 1].content);
+					return says('Done.');
+				}
+			});
+			assert.strictEqual(r.rows[0].turns, 2);
+			assert.strictEqual(fs.existsSync(mark), false, 'the command did not run');
+			assert.match(told[0][0].content, /^User skipped this command/);
+			assert.match(told[0][1].content, /^ERROR: could not write x\.txt/);
+		});
+
+		await testAsync('the provider seam is put back afterwards', async () => {
+			const before = providers.streamAgentTurn;
+			await ev.evaluate({ prompts: prompts.slice(0, 1), model: 'x', turn: async () => says('Done.') });
+			assert.strictEqual(providers.streamAgentTurn, before);
+			await ev.evaluate({ prompts: prompts.slice(0, 1), model: 'x', turn: async () => { throw new Error('boom'); } });
+			assert.strictEqual(providers.streamAgentTurn, before, 'also when a prompt failed');
+		});
+
+		test('title quality: a topic is told from a takeaway', () => {
+			for (const t of ['Steering', 'Checkout flow', 'Request lifecycle', 'OAuth 2.0 PKCE authorization flow', 'System architecture overview', 'Kubernetes objects', 'The agent loop', 'Two-phase commit']) { assert.strictEqual(ev.looksLikeTopic(t), true, t); }
+			for (const t of ['Every steer has two routes into the run', 'Jev classifies; your code decides the action', 'A miss fills the cache on the way back', 'Traffic switches at the router, not the servers']) { assert.strictEqual(ev.looksLikeTopic(t), false, t); }
+		});
+
+		test('THE COMMAND LINE: a dry run finishes with the network refused; a bare call and a keyless --run exit 2 having sent nothing', () => {
+			// Every way out of the process is replaced by something that fails loudly.
+			const guard = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'lc-eval-guard-')), 'nonet.js');
+			fs.writeFileSync(guard, [
+				"const die = (what) => { process.stderr.write('NETWORK USED: ' + what + '\\n'); process.exit(97); };",
+				"globalThis.fetch = () => die('fetch');",
+				"const net = require('net'); net.Socket.prototype.connect = function () { die('net.connect'); };",
+				"const dns = require('dns'); dns.lookup = () => die('dns.lookup');",
+				"for (const m of ['http', 'https']) { const mod = require(m); mod.request = () => die(m + '.request'); mod.get = () => die(m + '.get'); }"
+			].join('\n'));
+			const env = Object.assign({}, process.env);
+			for (const k of Object.keys(env)) { if (/_API_KEY$|^DIAGRAM_EVAL_/.test(k)) { delete env[k]; } }
+			const run = (args) => spawnSync(process.execPath, ['-r', guard, SCRIPT].concat(args), { env, encoding: 'utf8' });
+			try {
+				const dry = run(['--dry-run']);
+				assert.strictEqual(dry.status, 0, dry.stderr);
+				assert.match(dry.stdout, /40 prompts, 72 model turns/);
+				assert.match(dry.stdout, /Dry run: a scripted model, no network/);
+				assert.ok(!/NETWORK USED/.test(dry.stderr));
+				const bare = run([]);
+				assert.strictEqual(bare.status, 2);
+				assert.match(bare.stderr, /--run makes billed calls on your key/);
+				const keyless = run(['--run', '--model', 'some/model']);
+				assert.strictEqual(keyless.status, 2);
+				assert.match(keyless.stderr, /No API key/);
+				assert.ok(!/NETWORK USED/.test(keyless.stderr + bare.stderr));
+				// and the guard itself works — a real --run against it is stopped at the first request
+				const live = spawnSync(process.execPath, ['-r', guard, SCRIPT, '--run', '--model', 'some/model', '--limit', '1'], { env: Object.assign({}, env, { DIAGRAM_EVAL_KEY: 'not-a-key' }), encoding: 'utf8' });
+				assert.strictEqual(live.status, 97, 'the guard should have fired: ' + live.stdout + live.stderr);
+				assert.match(live.stdout, /About to run 1 prompts on openrouter \/ some\/model — up to 6 billed model turns on your key\./, 'the plan is printed before the first call');
+			} finally {
+				try { fs.rmSync(path.dirname(guard), { recursive: true, force: true }); } catch (e) { /* temp dir */ }
+			}
+		});
+
+		console.log('diagramEval: ' + n + ' tests passed');
+	} catch (e) {
+		console.error(e);
+		process.exitCode = 1;
+	}
+})();
diff --git a/extensions/levelcode-ai/test/fixtures/diagrams/eval-prompts.json b/extensions/levelcode-ai/test/fixtures/diagrams/eval-prompts.json
new file mode 100644
index 0000000..f0f58c7
--- /dev/null
+++ b/extensions/levelcode-ai/test/fixtures/diagrams/eval-prompts.json
@@ -0,0 +1,45 @@
+{
+	"note": "The diagram eval (docs/RICH-DIAGRAMS.md, 'Telemetry and evaluation'): 30 prompts that should produce a diagram and 10 that should not. Run with scripts/diagram-eval.js. Edit freely — the harness reads whatever is here; the suite only checks the 30/10 split and that ids are unique.",
+	"prompts": [
+		{ "id": "rails-request", "expect": "draw", "text": "Explain how a request flows through a typical Rails app, from the router to the database and back." },
+		{ "id": "oauth-pkce", "expect": "draw", "text": "How does the OAuth 2.0 authorization code flow with PKCE work? Show me the parties and what passes between them." },
+		{ "id": "pr-states", "expect": "draw", "text": "Show the states a pull request goes through from draft to merged, including the ways it can go back." },
+		{ "id": "three-tier", "expect": "draw", "text": "What does the architecture of a typical three-tier web app look like?" },
+		{ "id": "ci-pipeline", "expect": "draw", "text": "Walk me through how a CI/CD pipeline goes from a push to a production deploy." },
+		{ "id": "load-balancer", "expect": "draw", "text": "How does a load balancer with health checks decide where to send a request?" },
+		{ "id": "api-style-choice", "expect": "draw", "text": "Give me a decision tree for choosing between REST, GraphQL and gRPC for a new service." },
+		{ "id": "cache-aside", "expect": "draw", "text": "How does the cache-aside pattern handle a read, and what happens on a miss?" },
+		{ "id": "dead-letter", "expect": "draw", "text": "Show how a message moves through a queue that has retries and a dead-letter queue." },
+		{ "id": "url-in-browser", "expect": "draw", "text": "At a high level, what happens between typing a URL into a browser and seeing the page?" },
+		{ "id": "git-flow", "expect": "draw", "text": "Explain the git branching flow for a release: feature branches, develop, a release branch and main." },
+		{ "id": "k8s-objects", "expect": "draw", "text": "How do the pieces of a Kubernetes deployment relate: Deployment, ReplicaSet, Pod, Service and Ingress?" },
+		{ "id": "tcp-lifecycle", "expect": "draw", "text": "Show the lifecycle of a TCP connection as a state machine." },
+		{ "id": "webhook-retries", "expect": "draw", "text": "How does a webhook delivery system retry failed deliveries and eventually give up?" },
+		{ "id": "db-transaction", "expect": "draw", "text": "Explain how a database transaction moves between begin, commit and rollback." },
+		{ "id": "checkout-services", "expect": "draw", "text": "Map out a microservices checkout: cart, payment, inventory, shipping and notifications, and who calls whom." },
+		{ "id": "token-refresh", "expect": "draw", "text": "How does a client handle an access token that expires in the middle of a request, using a refresh token?" },
+		{ "id": "event-sourcing", "expect": "draw", "text": "Show the flow of an event-sourced system: commands, the event store, projections and the read model." },
+		{ "id": "blue-green", "expect": "draw", "text": "What does a blue-green deployment look like, and where does traffic switch?" },
+		{ "id": "order-states", "expect": "draw", "text": "Draw the state machine for an order: placed, paid, shipped, delivered, cancelled and refunded." },
+		{ "id": "dns-resolution", "expect": "draw", "text": "How does DNS resolution work, from the stub resolver to the authoritative server?" },
+		{ "id": "pub-sub", "expect": "draw", "text": "Explain the publish/subscribe pattern: who knows about whom?" },
+		{ "id": "token-bucket", "expect": "draw", "text": "How does a token-bucket rate limiter decide whether to allow or reject a request?" },
+		{ "id": "redux-flow", "expect": "draw", "text": "Show how data flows in a Redux-style front end." },
+		{ "id": "etl-stages", "expect": "draw", "text": "What are the stages of an ETL pipeline that feeds an analytics warehouse?" },
+		{ "id": "feature-flag", "expect": "draw", "text": "How does a feature flag service decide which variant a given user gets?" },
+		{ "id": "image-upload", "expect": "draw", "text": "Which components are involved when a user uploads an image that is resized in the background?" },
+		{ "id": "two-phase-commit", "expect": "draw", "text": "How does two-phase commit coordinate its participants, including the failure path?" },
+		{ "id": "saga-booking", "expect": "draw", "text": "Explain the saga pattern for a trip booking that spans flights, hotels and payments, including compensation." },
+		{ "id": "agent-loop", "expect": "draw", "text": "Generate a diagram of how an LLM agent loop works: the model, a tool call, the tool result, and when it stops." },
+		{ "id": "rebase-i", "expect": "none", "text": "What does `git rebase -i` do?" },
+		{ "id": "let-const", "expect": "none", "text": "What is the difference between `let` and `const` in JavaScript?" },
+		{ "id": "loc-oneliner", "expect": "none", "text": "Give me a one-line shell command to count the lines of code in a repository." },
+		{ "id": "http-409", "expect": "none", "text": "What does HTTP status 409 mean, and when should an API return it?" },
+		{ "id": "phone-regex", "expect": "none", "text": "Write a regular expression that matches a US phone number." },
+		{ "id": "latency-numbers", "expect": "none", "text": "Three databases answered in 12 ms, 48 ms and 7 ms. Which is fastest, and by how much?" },
+		{ "id": "semver", "expect": "none", "text": "Summarise what semantic versioning means in two sentences." },
+		{ "id": "name-a-function", "expect": "none", "text": "What is a good name for a function that validates an email address?" },
+		{ "id": "null-vs-undefined", "expect": "none", "text": "When should I use null and when undefined in TypeScript?" },
+		{ "id": "commit-message", "expect": "none", "text": "Write a commit message for a change that fixes an off-by-one error in pagination." }
+	]
+}

From db68f680be0ad3d6d21374346fca0c650f9ac37f Mon Sep 17 00:00:00 2001
From: Sergii Demianchuk <sergeydemjanchyk@gmail.com>
Date: Mon, 5 Oct 2026 00:29:46 -0400
Subject: [PATCH 8/9] docs(diagrams): what was built, where it departs from the
 spec, and how to check it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs/RICH-DIAGRAMS.md is the implementation record for the Rich Diagrams spec
(2026-10-04), under the spec's own section names, because the code cites them.
Per section: the rule, what the code does about it, and each place the build
chose differently, with the reason, so the choice can be argued again. A status
per requirement; the known limits with their measured rates; what is verified
and what is not — no live model has drawn a diagram yet, and the eval has not
been run.

It is not the spec. The spec is a private document; its links, and one line
about pricing, are left out of a public repository.

CLAUDE.md gains the feature's entry and three conventions that cost time to
learn: the shared diagram modules are pasted into a script block and must never
spell a script tag or an HTML comment opener; the host suites' brace matcher
cannot read a backtick inside a regex literal; and work in a worktree is not in
the editor until it is loaded with --extensionDevelopmentPath.

test/fixtures/diagrams/README.md says what each fixture is for, and how to add
a real broken spec to the corpus.
---
 CLAUDE.md                                     |  29 ++
 docs/RICH-DIAGRAMS.md                         | 450 ++++++++++++++++++
 .../test/fixtures/diagrams/README.md          |  48 ++
 3 files changed, 527 insertions(+)
 create mode 100644 docs/RICH-DIAGRAMS.md
 create mode 100644 extensions/levelcode-ai/test/fixtures/diagrams/README.md

diff --git a/CLAUDE.md b/CLAUDE.md
index a4849db..6f15df8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -164,6 +164,26 @@ big-file mode badge. Files: extension.js + fileOps/lineOps/columnOps/encodingEol
 - `aiEdit.js` — **edit-with-diff**: select code → `Cmd+Alt+E` → instruction → side-by-side diff → ✓ Keep / ✗ Discard
   buttons on the diff toolbar (gated on `levelcode.ai.diffActive`).
 - `inlineReview.js` — **dead code** (an inline per-hunk Keep/Undo attempt that was reverted; nothing imports it).
+- `diagram/` — **rich diagrams, phase 1** (`docs/RICH-DIAGRAMS.md`). The agent calls a `render_diagram` tool with
+  STRUCTURE only (nodes, edges, groups, one accent — never coordinates or colours); the editor validates it, lays it
+  out in one house style and paints it in the chat, themed, with nodes that link to code. Graph JSON only — Mermaid,
+  Vega-Lite and raw SVG are later phases and are **not built**. Not yet run in the packaged editor or against a live
+  model; the eval (`scripts/diagram-eval.js`) exists and has not been run.
+  - Shared UMD modules (`theme` `schema` `validate` `repair` `layout` `scene` `text` `ascii`) run in Node AND are
+    inlined into `chat.html` by `diagram/bundle.js` under the page's existing nonce — the CSP is unchanged. Host-only:
+    `tool` (tool + prompt block + result text), `service` (ids, the one repair pass, records, stubs), `links`,
+    `exportCheck`, `stats`.
+  - Repair ladder: lossless auto-fix → every error back to the model ONCE → degrade with a banner, or source + Retry.
+    Never a blank card, never a second automatic repair. Records are stored in the session log and re-validated (not
+    re-repaired) on reopen, by the host and by the page.
+  - Layout is in-house (layered + orthogonal routing), **not ELK** (EPL-2.0, ~1.5 MB, no build step here);
+    `layout.layout()` is the one swap point. The validator is a small JSON-Schema-subset interpreter, not Ajv.
+  - Gated per run by `client.render` (`rich`|`ascii`): off via `levelcode.ai.diagrams.enabled`, or per model with
+    `diagrams: false` in `providers/catalog.js` `CAPS`. Costs ~970 tokens of tool + prompt per request while on.
+  - Checks: `test/diagram*.test.js` (in the gate), `scripts/diagram-browser-check.js` (real page in headless Chrome,
+    not in the gate), `scripts/diagram-editor-check.js` (the REAL editor: a throwaway instance of the dev build with
+    this checkout's extension and a stand-in provider), `scripts/diagram-eval.js --dry-run`. Local counters: command
+    `AI: Diagram Statistics`.
 
 ## Deferred / known limits (don't waste time re-hitting these)
 
@@ -189,4 +209,13 @@ big-file mode badge. Files: extension.js + fileOps/lineOps/columnOps/encodingEol
 - `// @ts-check` + JSDoc at top of JS files.
 - Test JS logic with `node --check` and small unit snippets before wiring into the editor.
 - After any change, `./scripts/run-dev.sh` to verify; package with `./scripts/build-macos.sh`.
+- `run-dev.sh` runs the extensions of the checkout that HAS `vscode/`. A git worktree has none, so work in a worktree
+  is not in the editor until you load it: `./scripts/run-dev.sh --extensionDevelopmentPath=<worktree>/extensions/levelcode-ai`
+  (from the main checkout; the dev extension replaces the built-in one). Uncommitted work is not "on the branch" —
+  checking the branch out somewhere else gets none of it. Run it in the editor before telling anyone to try it.
 - Commit `extensions/`, `patches/`, `branding/`, `scripts/`, `docs/`, `PLAN.md`, `CLAUDE.md`. Never commit `vscode/`.
+- `extensions/levelcode-ai/diagram/` modules listed in `bundle.FILES` are pasted INTO a script block in `chat.html`.
+  They must never contain the text of a script tag or an HTML comment opener — not even in a comment — or the block
+  ends early; `bundle.js` refuses to build if one does. Keep them dependency-free and free of `require('vscode')`/`fs`.
+- Host suites slice functions out of `extension.js` with a brace matcher (`extract()` in `test/*Host.test.js`). It
+  does not understand a backtick inside a regex literal: write `String.fromCharCode(96)` there instead.
diff --git a/docs/RICH-DIAGRAMS.md b/docs/RICH-DIAGRAMS.md
new file mode 100644
index 0000000..d7d96bc
--- /dev/null
+++ b/docs/RICH-DIAGRAMS.md
@@ -0,0 +1,450 @@
+# Rich diagrams — the model describes, the editor draws
+
+**Status:** phase 1 is built (Graph JSON through a `render_diagram` tool call). It is verified by
+unit and property suites, by the real agent loop against a scripted provider, by the real
+`chat.html` in headless Chrome under the real CSP, and in the real editor (the dev build) against a
+stand-in provider. It has **not** been run against a live model, and the diagram eval has not been
+run on any model — see [What is and is not verified](#what-is-and-is-not-verified). Mermaid,
+Vega-Lite and raw SVG (phases 2–4) are not built.
+
+This is the implementation record for the *LevelCode Rich Diagrams Spec* (2026-10-04), the third
+companion to the Context Budget and Mid-Run Messaging specs. It keeps the spec's section names,
+because the code cites them (`docs/RICH-DIAGRAMS.md, "Validation and repair"`). Under each heading:
+the rule, what the code does about it, and every place the build chose differently — with the reason,
+so the choice can be re-argued.
+
+## Overview
+
+The agent used to draw flows and routing trees with box-drawing characters. They break when the
+font or the panel width changes, cannot follow the theme, cannot be clicked and cannot be exported.
+
+Now the model sends a small description of **structure** — nodes, edges, optional groups, one
+accent — and never a coordinate, a colour or a size. The editor validates it, lays it out in one
+house style and paints it. Quality comes from the renderer, so it is the same whichever model drew.
+
+One diagram, start to finish:
+
+1. A rich client's request carries the `render_diagram` tool and a short block of rules.
+2. The model calls the tool. While its arguments stream, the chat shows a placeholder card with the
+   title as soon as the title is known.
+3. The host runs the repair ladder's first rung and validates the result. Valid: a record is stored
+   and sent to the webview. Invalid: every error goes back as the tool result, once.
+4. The webview validates the record again, measures the text in the real font, lays it out and
+   paints it from allow-lists.
+5. If the model's one repair pass does not produce a valid spec, the editor draws what is valid and
+   says what it left out — or shows the source, the error and Retry. Never an empty card.
+
+## Requirements
+
+| ID | Requirement | Status | Pinned by |
+| --- | --- | --- | --- |
+| FR-1 | Graph JSON, Mermaid, Vega-Lite, opt-in raw SVG | **Graph JSON only.** The other three are phases 2–4 | — |
+| FR-2 | Graph JSON arrives through `render_diagram`; schema validated on every call | Done | `diagramAgent`, `diagramSchema` |
+| FR-3 | No unvalidated spec reaches the renderer | Done — validated in the host before a record exists, again when a session's records are read back from disk, and again in the webview before anything is drawn | `diagramRepair`, `diagramHost`, `diagramUi`, browser check |
+| FR-4 | Auto-fix, one model pass, graceful degrade; no automatic second repair; no blank output | Done, with one deliberate reordering — see [Validation and repair](#validation-and-repair) | `diagramRepair`, `diagramAgent` |
+| FR-5 | House style in light and dark | Done | `diagramScene` snapshots in both palettes; browser check in both themes |
+| FR-6 | Nodes link to files and symbols | Done | `diagramLinks`, `diagramHost` |
+| FR-7 | Export SVG, PNG and source | Done, plus Mermaid and "insert into a Markdown file" | `diagramHost`, `diagramText`, browser check |
+| FR-8 | Terminal clients get ASCII; rich clients never do | Done for the one client that exists (the chat webview is rich); the flag and the ASCII renderer are in place, and the renderer is what the chat falls back to | `diagramAgent`, `diagramText`, `diagramHost` |
+| NFR-1 | Sanitized; no script, no network | Done — the page's CSP is unchanged and nothing model-written is ever parsed as markup | `diagramScene`, `diagramUi`, browser check |
+| NFR-2 | Render under 300 ms p95 at 12 nodes | **Layout measured, time-to-picture not.** Layout of the 12-node gallery diagram: p95 under 1 ms in Node once warm (the suite asserts under 50 ms); the slowest of 6,000 random specs took 7 ms. The webview reports its own layout-and-paint time to the local counters; there is no figure from a real editor yet, and nothing measures the hop from host to page | `diagramLayout` |
+| NFR-3 | Graph JSON median under 600 tokens | Done — gallery diagrams are 21–309 tokens, the twelve-node one included (characters ÷ 4) | `diagramAgent` |
+| NFR-4 | Old chats keep rendering after schema changes | Mechanism done: a versioned schema and `migrate`; a stored record that still validates is drawn as stored, and one that no longer does is cut down by the deterministic rungs instead of being refused. Only version 1 exists, so there is nothing yet to migrate from | `diagramSchema`, `diagramRepair`, `diagramSession` |
+
+## Output formats
+
+Phase 1 draws boxes and arrows only. The spec's five-step format rule therefore ships as two
+steps — structure → `render_diagram`; reads fine as prose → no diagram — plus an instruction for the
+shapes that have no renderer yet: numbers to compare go in a Markdown table, steps over time in a
+numbered list. Telling a model to emit Mermaid or Vega-Lite that the chat would show as raw source
+would be worse than not mentioning them; a test fails if the prompt names either.
+
+## Architecture
+
+Everything lives in `extensions/levelcode-ai/diagram/`. The modules are plain UMD: Node `require`s
+them, and `bundle.js` inlines the shared ones into `chat.html` under the page's existing nonce.
+
+| Module | Runs in | Job |
+| --- | --- | --- |
+| `theme.js` | both | The style guide as numbers and CSS: type scale, box metrics, spacing, theme tokens, the two export palettes |
+| `schema.js` | both | The versioned schema and a small interpreter for it. The object the model is shown **is** the object it is validated against |
+| `validate.js` | both | Schema, then semantics. Every error at once, each with a JSON Pointer |
+| `repair.js` | both | The ladder: `normalize` (rung 1), `degrade` (rung 3), `prepare` (the whole trip), `accept` (re-validation of a stored record) |
+| `layout.js` | both | Layered layout with orthogonal routing, and `inspect`, which lists anything overlapping or out of frame |
+| `scene.js` | both | The painter: a tree of elements built from two allow-lists; `mount` (DOM) and `toSvg` (string) |
+| `text.js` | both | The screen-reader outline, the one-line stub, Mermaid and source export |
+| `ascii.js` | both | The fallback: the same layout drawn on a character grid |
+| `tool.js` | host | The tool definition, the system-prompt block, the tool-result text |
+| `service.js` | host | One conversation's diagrams: ids, the one repair pass, records, stubs |
+| `links.js` | host | Resolving a node's link inside the workspace, or refusing |
+| `exportCheck.js` | host | Checking an SVG or PNG the webview hands back before it is written to disk |
+| `stats.js` | host | The local counters |
+| `bundle.js` | host | Inlining the shared modules into the page |
+
+**Where rendering runs** (an open question in the spec). Validation and the repair ladder run in
+the extension host. Layout and painting run in the chat webview itself — not in a worker or a
+second frame — because layout needs to measure text in the real font, and because the Graph JSON
+painter executes nothing the model wrote: it creates elements from a fixed list and sets text with
+`textContent`. Isolation buys nothing there. It will matter for Mermaid and Vega, which run large
+third-party parsers over model text; those should get the sandboxed frame the spec describes.
+
+**Layout engine: not ELK.** The spec names ELK.js. The build uses its own layered (Sugiyama-style)
+layout: rank assignment, crossing reduction, coordinate assignment by constraints, one port per
+edge, per-gap track assignment for orthogonal connectors, and label placement scored against
+nodes, lines and other labels. Reasons: ELK is EPL-2.0 in a repository that is otherwise MIT-clean;
+it is about 1.5 MB; and extensions here have no build step. The spec's own open question asks
+whether a simpler layered layout is needed as a fallback — this is that layout, as the only one.
+`layout.layout(spec, opts)` is the single entry point, so ELK can replace it without touching the
+painter. What the trade costs is listed under [Known limits](#known-limits).
+
+**Validator: not Ajv.** Same reasons, smaller scale. `schema.js` interprets the subset of JSON
+Schema the diagram schema uses, and produces the spec's error format directly.
+
+**Host ↔ webview messages**
+
+| Direction | Message | Meaning |
+| --- | --- | --- |
+| host → webview | `diagramPending {key, state, title}` | A call has started (`drawing`) or was sent back (`repairing`) |
+| host → webview | `diagram {key, replacesKey?, record}` | The final record for a call; `replacesKey` when it redraws the attempt before it |
+| webview → host | `diagramAction {action: 'openLink', id, node}` | A linked node was clicked. The node **id** — never a path |
+| webview → host | `diagramAction {action: 'export', id, format, data?}` | Copy or save. `data` only for SVG and PNG, and it is checked before use |
+| webview → host | `diagramAction {action: 'retry', id}` | Retry on a degraded or failed diagram |
+| webview → host | `diagramAction {action: 'ascii', id, cols}` | The page has no renderer: send the text version. `cols` is how many characters fit the card, clamped to 40–200 |
+| host → webview | `diagramAscii {id, text}` | The answer — empty when there is nothing drawable |
+| webview → host | `diagramRendered {id, ok, ms, flipped}` | Layout-and-paint time, or a failure, for the local counters |
+
+## Diagram spec and render_diagram tool
+
+The fields are the spec's. Two tiers of limits apply: the **house** tier is what the model is held
+to; the **hard** tier is what the renderer will draw when a diagram is degraded, so that a
+thirteen-node diagram loses nothing rather than everything.
+
+| Field | House limit | Hard limit |
+| --- | --- | --- |
+| `title` | 80 characters | 80 |
+| `nodes` | 1–12 | 24 |
+| `edges` | 30 | 48 |
+| `groups` | 8, nested 2 deep | 12, nested 2 deep |
+| node `label` / `sub` | 28 / 32 | same; the full text survives as a tooltip |
+| edge `label` | 20 | same |
+| `accent` | at most one node | one |
+
+Differences from the spec's tables:
+
+- **`v` is optional on the wire.** The tool schema leaves it out to save tokens on every request;
+  the host stamps `v: 1` on the stored record. A call that names a version the editor does not know
+  is refused.
+- **Edges and groups have counts.** The spec caps nodes only. An uncapped edge list is an easy way
+  to produce an unreadable picture, so edges stop at 30 and groups at 8.
+- **`tip` exists.** It is the renderer's field: the full text of a label that had to be shortened,
+  shown on hover and read in the outline. A `tip` the model sends is kept as hover text (cleaned,
+  400 characters at most); it is not in the model-facing schema.
+- **Unknown fields are ignored, not errors.** A model that adds `color` or `x` is not sent back for
+  it — the fields are dropped and counted. The same goes for a stored record: whatever else it
+  carries, only declared fields reach the renderer, the exports and `get_diagram`.
+
+The tool returns `{"ok":true,"id":"d-1"}`, optionally with what was changed to fit and which links
+did not resolve; or the error list; or, when the diagram was drawn degraded, what was left out and
+an instruction not to redraw it unprompted.
+
+**Cost of offering it.** The tool definition is about 520 tokens and the prompt block about 450, on
+every request from a rich client. Both are constant for a session, so they sit in the cached prefix
+where the provider caches. `get_diagram` (about 100 tokens) is offered only once a diagram has been
+stubbed.
+
+## Style guide
+
+`theme.js` is the one place the numbers live: title 15, node name 13 semibold, second lines and
+edge labels 11.5, nothing below 10.5; corner radius 8, border 1.25, padding 12; the accent is a
+low-opacity fill plus a 2 px border; groups inset their children by 16. Colours are editor theme
+tokens (`--vscode-*` behind `--lcd-*`), so a theme switch repaints with no re-render and nothing is
+baked in. Shapes: box, diamond, cylinder, pill.
+
+- Width is the measured longest line plus 24. Text is measured in the page's real font in the
+  webview; Node-side tests use a calibrated estimate.
+- Connectors are orthogonal and run in the gaps between ranks; labels sit beside their line. When
+  no clear position exists the label gets a background halo instead of being dropped.
+- A diagram never grows wider than the chat column: a `right` flow that does not fit is laid out
+  `down` instead. If it is still too wide it is scaled to fit, and opens full-panel with zoom and
+  pan.
+- A group's name sits in the top-left of its frame, and no connector runs through it. When the
+  flow runs down that corner is exactly where lines come in, so the layout works through three
+  answers in order. Slide the name along the frame to the nearest clear stretch — free. If the
+  frame has none and the lines have less than 72 px to move, move them to the far side of the name
+  — the frame gets that much wider, and only if the drawing still fits its column. Otherwise leave
+  the name where it is and draw it over the line with a halo, so the line reads as passing behind
+  the word.
+- Exported SVG and PNG carry one of two fixed palettes (light or dark, picked from the theme at the
+  moment of export), because a file cannot read the editor's variables.
+
+The spec's chart rules have nothing to apply to until the Vega-Lite phase.
+
+## Validation and repair
+
+**Layers as built**
+
+| Layer | Checks | Where |
+| --- | --- | --- |
+| Extraction | The call's arguments are complete. Output cut off by `max_tokens` is re-requested with a "send it again, smaller" result — never repaired | `agent.js`, `service.truncated` |
+| Syntax | The arguments parse — leniently: comments, trailing commas, single or smart quotes, bare keys, Python literals, a stray code fence | `repair.parseLenient` |
+| Schema | Fields, types, enums, lengths, counts | `schema.check` |
+| Semantics | Edge ends exist, ids unique, one accent, groups known, acyclic and at most 2 deep | `validate.js` |
+| Layout | Nothing overlaps, overflows or leaves the frame, and no line runs through a node or a group's name. Renderer-only fixes: grow a node, wrap to two lines, flip the direction, halo a label, slide or back a group's name | `layout.js`, `layout.inspect` |
+
+**The ladder, and the one place it departs from the spec.** The spec's first rung lists "dedupe
+ids" and "drop edges to unknown nodes with a warning" among the deterministic fixes — while its own
+layer table says semantic errors are fixed by the model, "because intent is needed". Both cannot
+hold: an edge to `billing` when the node is called `bill` is a typo the model can fix in one pass,
+and dropping it silently changes what the diagram says.
+
+The build resolves it with one rule: **an auto-fixed diagram never says something different from
+what the model wrote; a degraded one always says what it lost.**
+
+1. **Auto-fix, no model — lossless only.** Lenient parsing; synonyms (`diamond` → `decision`,
+   `source`/`target` → `from`/`to`, `rankdir: LR` → `right`); ids slugged; an edge that names a
+   node's *label* pointed at that node's id; long labels shortened with the full text kept as a
+   tooltip. Silent when it changes nothing visible; a quiet "auto-fixed" badge when it does.
+2. **One model pass.** Anything else — an unknown node, a duplicate id, two accents, too many
+   nodes — returns every error at once as the tool result, in the spec's format
+   (`/edges/1/to: unknown node "billing". Known ids: in, jev, bill, rev.`).
+3. **Degrade, never loop.** If the second attempt is still invalid, the lossy fixes run *now*: edges
+   to unknown nodes are dropped, duplicates renamed, the first accent kept, deep groups flattened,
+   counts allowed up to the hard tier. The diagram is drawn with a banner listing each loss, and a
+   Retry button. If nothing drawable remains, the card shows the errors, the source and Retry.
+
+"No automatic second repair" is enforced per diagram (one bounce, then the verdict is final) and
+per run (three bounces across all diagrams, after which every call is final). A diagram still
+waiting on its repair when the run ends — the model gave up, hit its step limit, or was stopped — is
+settled from its last attempt before `agentDone`, so no placeholder is left spinning.
+
+**Storage.** The final record — spec, status, fixes, notes — is written to the session's event log
+after the turn. Reopening a chat replays records; no model is asked anything, and a valid record
+comes back exactly as it was stored.
+
+A session file is input too — it can be edited, cut short, or written by an older build — so a
+stored spec is checked like a model's: by the host when the session is loaded (before a link can be
+opened or a file exported from it) and by the webview before it is drawn. The check is
+`repair.accept`: validate against the hard tier and hand on only the fields the schema declares;
+if that fails, run the deterministic rungs alone and draw what is left with its banner; if nothing
+is left, treat it as a diagram that was never drawn and show the source.
+
+**Strict tool schemas** are not enabled. Which providers enforce them well enough is an open
+question the eval should answer first; semantic rules stay in the validator either way.
+
+**Fence mode, JSON Patch repair, the cheap repair model** belong to the Mermaid and Vega-Lite
+phases and are not built.
+
+## Safe rendering
+
+Graph JSON is the easy case, and the build keeps it easy: there is no sanitizer because there is
+nothing to sanitize. The painter creates elements from a fixed list (`svg g rect path text title
+style`) with attributes from a fixed list that has no `href`, no `style`, no `id` and no event
+handlers, and model text goes in through `textContent`. Text is also stripped of control,
+zero-width and bidirectional-override characters before it is stored.
+
+- The page's CSP is unchanged: `default-src 'none'`, scripts by nonce only, no network origin.
+- The inlined modules must never contain the text of a script tag or an HTML comment opener, in
+  code or comments, or they would end the inline block they live in. `bundle.js` refuses to build
+  if one does, and a suite checks it.
+- A linked node carries `data-lc-link` = its node id. A click sends that id; the host looks the
+  path up in its own record and resolves it again. A path is never taken from the page.
+
+**The host accepts four actions, not two.** The spec lists `openLink` and `export`. Its own UX
+section also puts a Retry button on degraded diagrams and promises a text fallback when rendering
+is unavailable, which need a third and a fourth (`retry`, `ascii`). All four name a diagram by id
+and are looked up in the host's own records; none carries a path, a URL or a command. The only
+other value read from the page is the fallback's column count, used as a clamped number.
+
+**Link safety.** `links.js` resolves a link against the workspace folders at draw time *and again
+at click time*: schemes are refused, `..` is normalized, the real path (symlinks followed) must
+still be inside a workspace folder, and the target must be a file. A link that fails is removed
+from the node — it is drawn as plain text — and the model is told which ones did not resolve.
+
+**Exports.** Source, Mermaid and Markdown are generated in the host from the stored spec. SVG and
+PNG are produced in the webview (PNG needs a canvas), so the host checks them before writing: the
+SVG against the painter's own allow-lists, the PNG by signature and size. File names come from the
+title after secret redaction.
+
+## UX
+
+| Spec item | As built |
+| --- | --- |
+| While streaming | A placeholder card appears when the call starts; the title fills in as soon as it has streamed; the picture replaces it |
+| Code links | A small file icon; click or Enter opens the file at the symbol (document symbols, then a text search, then the line); hover shows the path |
+| Zoom and pan | Diagrams larger than the column are scaled to fit; click opens a full-panel view with zoom, pan, fit and Esc |
+| Toolbar | Copy source, save SVG, save PNG, open as Mermaid, insert into a Markdown file |
+| Repair states | "auto-fixed" badge with a details popover; degraded banner listing each loss, plus Retry |
+| Theme switch | Instant — colours are CSS variables |
+| Accessibility | The title is the accessible name; a text outline (nodes, then edges, in reading order) is attached for screen readers; linked nodes are focusable |
+| Fallback | Two ways rendering can be unavailable, one answer. If painting throws, the page draws the spec with characters itself. If the diagram modules never loaded, the page asks the host, which draws it from its own record. Either way it is the same layout on a character grid, fitted to the card's width, in a monospaced block, under a line saying that a text version is being shown. Source stays one click away |
+
+The text fallback is made of plain ASCII — a shortened label ends in three dots there, not an
+ellipsis — and it counts East Asian wide characters and emoji as two cells and combining marks as
+none, so a box with a Japanese label still closes on one column.
+
+Dragging nodes is not built (an open question in the spec).
+
+## Prompting and capability detection
+
+**Capability flag.** Each agent run carries `client.render`: `rich` or `ascii`. A rich client gets
+the tool and the rules; an ASCII client gets neither. Today the chat webview is the only client and
+it is rich, unless `levelcode.ai.diagrams.enabled` is off or the model's catalog row says
+`diagrams: false`.
+
+**The prompt block** (`tool.PROMPT`) says when a diagram earns its place, that characters are never
+to be drawn with, that a request for a diagram means drawing it in the chat rather than writing a
+file of diagram source, that the title states the takeaway, at most one accent, split above 12
+nodes, link nodes to workspace files, and not to restate the picture as a list afterwards. It carries one worked
+example — the spec's Jev flow — and a suite checks that the example is itself a valid, fix-free spec.
+
+**Model differences.** `providers/catalog.js` `diagramSupportForModel` is the registry switch: a
+model that fails the eval is turned off with `diagrams: false` in its `CAPS` row. The spec's third
+state, "fenced Mermaid only", arrives with the Mermaid phase; until then a switched-off model simply
+answers in prose.
+
+**Chat mode is unchanged.** Diagrams are a tool, and only the agent has tools.
+
+## Context budget and cost
+
+- **Collapsing old diagrams.** At compaction — never turn by turn — a diagram call in the
+  summarized range becomes `[draws a diagram: <title>]` in the summary input, and the summary is
+  followed by one stub line per diagram (`diagram: <title>, 4 nodes, id d-17`). From then on the
+  model is also offered `get_diagram`, which returns the full spec by id. Resuming a session whose
+  history was shortened does the same.
+- **Retention** (an open question). A spec is kept as long as its session file is. There is no
+  separate expiry.
+- **Repair tokens.** The repair pass is an ordinary agent turn, so it is counted, metered and
+  capped like one.
+- **Read-only.** A diagram call touches nothing and never asks for approval.
+- **Mid-run updates.** Mid-run steering is not in this branch. Nothing in the diagram path cancels
+  a call that is streaming; when steering lands, the rule in the spec (the diagram renders, the model
+  may redraw) needs no change here.
+
+## Telemetry and evaluation
+
+**Local counters, not telemetry.** `stats.js` keeps the spec's table — first-pass valid rate, fix
+share by rung, error classes per model, render time, tokens per diagram, ASCII leaks, link clicks,
+exports — in the editor's own storage. `AI: Diagram Statistics` shows it. Nothing is sent anywhere.
+It records enums and numbers only; `record()` copies nothing else out of an event, and a suite
+checks that no label, title or path can reach the store.
+
+**Golden corpus.** `test/fixtures/diagrams/corpus.json` holds 39 broken specs with the exact
+outcome of each attempt. They are **seeded** — written from the failure modes models are known
+for — not field data. Real broken specs should be added unchanged as they are found.
+
+**Diagram eval.** `scripts/diagram-eval.js` runs the real agent loop over
+`test/fixtures/diagrams/eval-prompts.json` (30 prompts that should draw, 10 that should not) and
+scores format choice, first-pass validity, fix share by rung, degraded rate, error classes, tokens,
+node-count overruns, title quality and ASCII leaks against the spec's proposed bars (first-pass
+valid ≥ 90%, degraded < 2%, no leaks). `--dry-run` uses a scripted model and no network. `--run`
+makes billed calls on your key and says how many before the first one. **It has not been run
+against any model yet.**
+
+**Acceptance criteria**
+
+- [x] Visual regression snapshots pass in light and dark themes
+- [x] Zero script execution or network requests in the security checks — for Graph JSON, the only
+      format built
+- [ ] Degraded rate under 2% across the diagram eval on default models — the eval exists; not run
+- [ ] No ASCII diagrams in rich-client answers over one week of internal use — the counter exists;
+      the week has not happened
+
+## Rollout and open questions
+
+Phase 1 — Graph JSON — is what is built, and by the spec it alone retires ASCII for flows and
+architecture. The spec's rollout figure (four phases, three gates) is not reproduced here. What
+stands between this build and calling phase 1 done is the two unchecked boxes above: run the eval
+on the default models, then use it for a week and read the counters.
+
+| Open question | Where it stands |
+| --- | --- |
+| Which models handle strict tool schemas well enough? | Open. Run the eval per model; strict mode is not enabled |
+| Where does rendering run? | Decided for Graph JSON: the chat webview. Revisit for Mermaid and Vega |
+| Is ELK fast enough, or is a simpler layered layout needed? | Sidestepped: the simpler layout is the only one. Sub-millisecond at 12 nodes |
+| Should users drag nodes? | Not built |
+| A simplified chart schema instead of full Vega-Lite? | Open — phase 3 |
+| How long are stubbed specs kept? | As long as the session file |
+
+## Known limits
+
+- **Dense labelled fan-ins.** Over 6,000 adversarial random graphs, 6.5% of specs have at least one
+  edge label that falls back to a halo over a line (4.5% of all labels) — 2% of flows that run
+  right, 11% of flows that run down, where many labelled edges enter one node. Nothing overlaps a
+  node. The house-size gallery has none. The suite fails above 9%.
+- **Lane swaps.** In 0.3% of the same specs two connectors in one gap cross where a perfect router
+  would not have crossed them. The suite fails above 0.5%.
+- **Backed group names.** Of the random specs that have groups, 0.5% of those flowing right and
+  4.9% of those flowing down end with a connector passing behind a group's name — long names over
+  narrow frames. None has a line *through* an unbacked name, and none of the gallery diagrams needs
+  a backing at any width from 320 px up. Making room instead costs width: grouped top-to-bottom
+  random specs are 0.6% wider on average and at most 121 px. The suite fails above 10% backed.
+- **Text fallback width.** Character widths follow the common Unicode ranges, not the whole
+  standard; an unusual script or a font with its own ideas can still put a box edge one cell out.
+- **Time to picture is unmeasured in a real editor.** Layout is fast; font loading, DOM work and
+  the webview's message hop are not in any number here.
+- **The corpus is seeded** and the eval has not been run, so the first-pass and degraded rates for
+  real models are unknown.
+- **One renderer.** A terminal client does not exist yet, so `client.render = ascii` is exercised
+  only through the setting, the catalog switch and tests.
+
+## What is and is not verified
+
+Verified:
+
+- 12 suites, 251 tests (`test/diagram*.test.js`), including a 1,500-spec layout fuzz, the corpus,
+  SVG snapshots in both palettes, the gallery at chat-panel widths, the real `runAgent` loop with a
+  scripted provider, and the host functions sliced out of `extension.js` against a `vscode`
+  stand-in.
+- The whole gate (`./scripts/test-extensions.sh`, 62 suite files) on macOS arm64 with Node 24, and
+  on Linux (Ubuntu 22.04 arm64, Node 18) in a container with no network and a read-only checkout.
+  The diagram suites also pass with every timer delayed by 15 ms.
+- `scripts/diagram-browser-check.js`: the real `chat.html` in headless Chrome under the real CSP —
+  light and dark, hostile labels, links, exports, a painter that throws, and the page with no
+  diagram modules at all — 155 checks, with no CSP violation and no resource request. Each step
+  waits for its result rather than for a length of time.
+- Mutation testing: 147 single-edit defects seeded across the modules, the host glue, the page and
+  the eval harness, each run against the suite that should notice (and only after that suite
+  passed on the unmutated copy). Ten survived at first: three were redundant code (removed or
+  simplified), seven were gaps in the suites (closed). All 144 that still apply are caught.
+
+- `scripts/diagram-editor-check.js`: the real editor. A second, throwaway instance of the dev build
+  loads this checkout's extension, talks to a stand-in provider on localhost, and is driven through
+  the DevTools protocol — 17 checks: the tool and its rules reach the model, the diagram is painted
+  in the real webview in the editor's theme, a linked node opens its file at the symbol, the session
+  on disk holds the diagram, a wider column re-lays it out, and the answer around it renders as
+  Markdown. (Added after the feature was first called done without ever having run in the editor.)
+
+Not verified:
+
+- Any live model. No provider call was made while building this; the editor check's "model" is a
+  script. What a real model does with the tool is what the eval is for.
+- The gate on CI's own runner (ubuntu-latest, x64, Node 24) — it runs there on the pull request.
+
+## How to check it
+
+```bash
+./scripts/test-extensions.sh                                        # every suite, the release gate
+node extensions/levelcode-ai/scripts/diagram-browser-check.js       # the real page in headless Chrome
+node extensions/levelcode-ai/scripts/diagram-editor-check.js        # the real editor, a stand-in provider
+node extensions/levelcode-ai/scripts/diagram-eval.js --dry-run      # the eval harness, offline
+UPDATE_SNAPSHOTS=1 node extensions/levelcode-ai/test/diagramScene.test.js   # after a deliberate style change
+```
+
+The editor check opens a window for about a minute. It is a separate instance with its own
+profile, so it neither joins an editor that is already open nor touches your settings or sessions.
+
+**To try it by hand.** In the checkout that has `vscode/`, `./scripts/run-dev.sh` runs the
+extension that is checked out there. From anywhere else — a git worktree has no `vscode/` of its
+own — load that checkout's extension into the build that exists:
+
+```bash
+./scripts/run-dev.sh --extensionDevelopmentPath=/absolute/path/to/worktree/extensions/levelcode-ai
+```
+
+Run it from the checkout that has `vscode/`, and quit a dev editor that is already open first (a
+running one is joined, not replaced). The window's title says `[Extension Development Host]`.
+Then, in agent mode, ask something whose answer is structure — "how does a request flow through
+this app?". The editor check takes the same route (`--vscode <that checkout>/vscode`).
+
+To measure a model: `node extensions/levelcode-ai/scripts/diagram-eval.js --run --model <id> --limit 8`
+first, then without `--limit`.
diff --git a/extensions/levelcode-ai/test/fixtures/diagrams/README.md b/extensions/levelcode-ai/test/fixtures/diagrams/README.md
new file mode 100644
index 0000000..d6350fa
--- /dev/null
+++ b/extensions/levelcode-ai/test/fixtures/diagrams/README.md
@@ -0,0 +1,48 @@
+# Diagram fixtures
+
+Inputs for the rich-diagram suites (`test/diagram*.test.js`). See `docs/RICH-DIAGRAMS.md`.
+
+## `corpus.json` — the golden corpus of broken specs
+
+Each entry is one way a model gets a `render_diagram` spec wrong, with what the repair ladder must
+do about it:
+
+| field | meaning |
+| --- | --- |
+| `name`, `why` | what the case is, and why it is in the corpus |
+| `input` | exactly what arrived — an object, or a string when the JSON itself is the problem |
+| `first` | the first attempt: `status`, the exact `errors` returned to the model, the fixes `shown` to the user, and the classes of silent tidy-up (`tidied`) |
+| `final` | the same input once the model's one repair pass is spent: `status`, the banner `notes`, and how much was `drawn` |
+
+**The rule the suite enforces: a fix to the validator or the auto-fixer must keep every case here
+green.** If a change is meant to alter an outcome, the entry is edited in the same commit and the
+diff says why.
+
+These cases are *seeded* — written by hand from the failure modes models are known for (JSON5
+syntax, Mermaid vocabulary, labels over the limit, edges that name a label). They are not yet
+field data. The spec calls for real broken specs collected locally or from opted-in users; when
+those exist, add them here unchanged: paste the raw input, run the ladder once, review the outcome
+by eye, and record it.
+
+Never put anything in an entry that came from a private workspace: labels are free text.
+
+## `eval-prompts.json` — the diagram eval
+
+Thirty prompts whose answer is structure and ten whose answer is not, for
+`scripts/diagram-eval.js`. Almost none of the thirty says "diagram": the eval measures whether a
+model *chooses* to draw, not whether it obeys. Edit freely — the harness reads whatever is here;
+`test/diagramEval.test.js` holds the set to its 30/10 split and unique ids.
+
+## `gallery.json` — realistic diagrams
+
+Well-formed specs of the shapes the feature exists for (a routing flow, an architecture with
+groups, a decision tree, a state machine with a loop, a twelve-node system). The layout suite
+requires each to lay out with nothing flagged at all — nothing overlapping, every label clear of
+every line, no connector through a group's name — at its natural width and at the widths a chat
+panel really has (560, 420 and 320 px), where most of them turn top-to-bottom.
+
+## `snapshots/` — rendered SVG, light and dark
+
+The exact SVG the painter produces for three gallery diagrams under each palette. A change to the
+style module, the layout or the painter shows up here as a diff. Regenerate deliberately with
+`UPDATE_SNAPSHOTS=1 node test/diagramScene.test.js`, and look at the result before committing it.

From a317a4519b1c6ef6d997984f3655f76002073374 Mon Sep 17 00:00:00 2001
From: Sergii Demianchuk <sergeydemjanchyk@gmail.com>
Date: Mon, 5 Oct 2026 00:46:41 -0400
Subject: [PATCH 9/9] =?UTF-8?q?fix(diagrams):=20#104=20review=20=E2=80=94?=
 =?UTF-8?q?=20an=20emoji=20is=20measured=20as=20wide=20as=20it=20was=20mea?=
 =?UTF-8?q?nt=20to=20be;=20a=20dead=20store=20goes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two findings from the code-quality review. Both are right.

theme.js, charEm() — "the condition c > 0xffff is always false". The width
estimate used where there is no canvas asked "CJK and other full-width scripts"
(U+2E80 and up, 1.0 em) before "emoji / astral" (above U+FFFF, 1.1 em). Every
code point above U+FFFF is above U+2E80 too, so the second question was never
reached and an emoji was measured at 1.0 em. The estimate is meant to err wide
— the failure that matters is text overflowing its box — so the questions are
now asked the other way round.

Nothing on screen changes. The chat measures with the real font, and no fixture
contains a character beyond the basic plane, so no snapshot moves. What changes
is the fallback when the canvas refuses the font, and the estimates made in
Node.

layout.js — "the value assigned to span here is unused". When several
connectors share a side too short for them, the node grows to hold exactly what
they need; span was recomputed afterwards and never read. The recompute is
gone and span is a const. it.cs, set on the same line, IS read later, and
stays. 6,000 random layouts and the nine gallery diagrams are byte-identical to
the code before.

diagramLayout gains a test for the estimate's classes: narrow, ordinary and
wide letters, digits and capitals, a CJK character at a full em, an emoji at
1.1 em and counted as one character. It fails on the old order, on exactly the
condition the review named.

62 suite files pass on macOS and in a Linux container.
---
 docs/RICH-DIAGRAMS.md                              |  2 +-
 extensions/levelcode-ai/diagram/layout.js          |  4 ++--
 extensions/levelcode-ai/diagram/theme.js           |  2 +-
 extensions/levelcode-ai/test/diagramLayout.test.js | 13 +++++++++++++
 4 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/docs/RICH-DIAGRAMS.md b/docs/RICH-DIAGRAMS.md
index d7d96bc..5bd13e0 100644
--- a/docs/RICH-DIAGRAMS.md
+++ b/docs/RICH-DIAGRAMS.md
@@ -391,7 +391,7 @@ on the default models, then use it for a week and read the counters.
 
 Verified:
 
-- 12 suites, 251 tests (`test/diagram*.test.js`), including a 1,500-spec layout fuzz, the corpus,
+- 12 suites, 252 tests (`test/diagram*.test.js`), including a 1,500-spec layout fuzz, the corpus,
   SVG snapshots in both palettes, the gallery at chat-panel widths, the real `runAgent` loop with a
   scripted provider, and the host functions sliced out of `extension.js` against a `vscode`
   stand-in.
diff --git a/extensions/levelcode-ai/diagram/layout.js b/extensions/levelcode-ai/diagram/layout.js
index 5b8ad86..92c9d59 100644
--- a/extensions/levelcode-ai/diagram/layout.js
+++ b/extensions/levelcode-ai/diagram/layout.js
@@ -381,7 +381,7 @@
 				const lane = S.labelLane != null ? S.labelLane : T.edge.line + S.labelGap + 2;
 				const floor = labelled ? lane : (S.portMin != null ? S.portMin : 6);
 				let gap = Math.max(S.portGap, labelled ? floor : 0);
-				let span = portSpan(it.node, it.cs, S);
+				const span = portSpan(it.node, it.cs, S);
 				if (n > 1 && (n - 1) * gap > span) {
 					gap = Math.max(floor, span / (n - 1));
 					if ((n - 1) * gap > span + 1e-6) {
@@ -389,7 +389,7 @@
 						const need = (n - 1) * gap;
 						const grow = it.node.shape === 'decision' ? need / 0.5 : it.node.shape === 'actor' ? need / 0.55 : need + 2 * S.portInset;
 						if (right) { it.node.h = Math.ceil(grow); } else { it.node.w = Math.ceil(grow); }
-						it.cs = cs(it.node); span = portSpan(it.node, it.cs, S);
+						it.cs = cs(it.node);   // (the node now holds exactly `need`: there is nothing left to re-measure)
 					}
 				}
 				ends.forEach((en, i) => {
diff --git a/extensions/levelcode-ai/diagram/theme.js b/extensions/levelcode-ai/diagram/theme.js
index 7beb8b2..f9227c8 100644
--- a/extensions/levelcode-ai/diagram/theme.js
+++ b/extensions/levelcode-ai/diagram/theme.js
@@ -178,8 +178,8 @@
 		const c = ch.codePointAt(0) || 0;
 		if (c >= 0x30 && c <= 0x39) { return 0.60; }          // digits
 		if (c >= 0x41 && c <= 0x5a) { return 0.69; }          // A–Z
+		if (c > 0xffff) { return 1.1; }                       // emoji and everything else beyond the basic plane — asked first: all of it is above U+2E80 too
 		if (c >= 0x2e80) { return 1.0; }                      // CJK and other full-width scripts
-		if (c > 0xffff) { return 1.1; }                       // emoji / astral
 		return 0.57;
 	}
 	/**
diff --git a/extensions/levelcode-ai/test/diagramLayout.test.js b/extensions/levelcode-ai/test/diagramLayout.test.js
index 93c23ad..628644e 100644
--- a/extensions/levelcode-ai/test/diagramLayout.test.js
+++ b/extensions/levelcode-ai/test/diagramLayout.test.js
@@ -305,6 +305,19 @@ test('PORTS: connectors that share a side each get their own point on it — and
 	assert.ok(byId(big, 'h').h > byId(big, 't0').h, 'the hub grew along its side');
 });
 
+test('MEASURE: the estimate used where there is no canvas errs WIDE, class by class — an emoji is wider than a CJK character', () => {
+	// Regular weight at 11.5px, so the numbers are plain multiples of the em.
+	const px = (t) => theme.approxMeasure(t, 'sub');
+	assert.ok(px('i') < px('a') && px('a') < px('m'), 'narrow, ordinary and wide letters');
+	assert.ok(px('7') > px('a') && px('A') > px('7'), 'digits and capitals are wider than lower case');
+	assert.strictEqual(px('\u65e5'), 11.5, 'a CJK character is a full em');
+	assert.strictEqual(px('\u{1f680}'), 12.7, 'an emoji is 1.1 em — the widest class, not lumped in with CJK');
+	assert.ok(px('\u{1f680}') > px('\u65e5'));
+	assert.strictEqual(px('\u{1f680}\u{1f680}'), 25.3, 'and it is ONE character, though it is two code units');
+	assert.strictEqual(px('\u{20000}'), 12.7, 'anything else beyond the basic plane is measured the same generous way');
+	assert.strictEqual(px(''), 0); assert.strictEqual(px(null), 0);
+});
+
 test('SHAPES: size comes from the measured text — and a connector stops ON a diamond\'s outline', () => {
 	const double = (t, role) => theme.approxMeasure(t, role) * 2;
 	const s = R.prepare({ title: 'T', nodes: [{ id: 'a', label: 'A fairly long label' }], edges: [] }).spec;