@@ -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.
 
@@ -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 };
@@ -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 };