From 30411789ca7426bfad51cfae81e6dade856a9630 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Mon, 3 Aug 2026 23:36:22 -0400
Subject: [PATCH 01/32] feat(documents): interactive widget blocks

A widget is an AI-authored, self-contained HTML fragment that runs in an
opaque-origin iframe (allow-scripts, no allow-same-origin) and lives as a block
inside a document. A document holding nothing but a widget is the standalone
case, so there is no separate item type to read, edit, create and render.

Reads elide a widget's source to an empty placeholder carrying its ref and
title, because one widget runs to kilobytes and would crowd the prose out of a
chunk. workspace_read_items gains mode "block" to fetch that source back in
full. Elision alone would be data loss, since overwrite echoes a read back by
design, so the parser takes a resolveWidgetSource hook and an empty widget with
a known ref keeps what is already there.

replace_text joins the document edit vocabulary with a ref, so it targets text
inside any block: a widget's source or a paragraph's markup. It fails rather
than replacing every occurrence when a find matches more than once. replace_all
is renamed overwrite so it cannot be read as "replace all instances of a find".

Also here, because the surfaces had drifted apart:

- Documents degrade unsupported markup instead of rejecting the write. A probe
  of realistic model output found 12 of 20 snippets refused outright, each
  costing a whole document to save formatting we can flatten. ProseMirror's
  DOMParser already normalises HTML, which removed the hand-rolled allowlist.
- Math, chemistry and units are one contract across documents and widgets, both
  being HTML. Chat keeps the $-delimited Markdown form. sub/sup become math
  rather than failing, and money is written plainly.
- KaTeX is served from the app's own origin and injected only when a widget
  contains math.

Widget source stays out of search and previews: the markdown projection drops
it, and a preview shows the widget's title instead.
---
 .gitignore                                    |   3 +
 eval/__reports__/math-authoring.md            |  88 ++++++++
 eval/datasets/math-authoring.cases.ts         | 154 ++++++++++++++
 eval/datasets/workspace-tools.cases.ts        |  84 ++++++++
 eval/math-authoring.eval.ts                   | 139 +++++++++++++
 eval/support/harness.ts                       |  87 ++++++--
 eval/support/scorers.ts                       |  80 ++++++-
 eval/workspace-tools.eval.ts                  |  12 +-
 package.json                                  |   3 +-
 pnpm-lock.yaml                                |  29 ++-
 scripts/copy-widget-libs.mjs                  |  43 ++++
 .../workspaces/ai/ai-thread-soul-prompt.ts    |   3 +-
 src/features/workspaces/ai/ai-thread.ts       |   9 +
 .../ai/skills/widget-authoring/SKILL.md       | 134 ++++++++++++
 .../ai/workspace-tool-result-adapters.ts      |   5 +-
 src/features/workspaces/cache-keys.ts         |   4 +
 src/features/workspaces/cache-page.ts         |  13 +-
 .../components/WorkspaceCreateMenu.tsx        |   8 +-
 .../components/WorkspaceItemToolbarSlot.tsx   |  25 ++-
 .../components/ai-chat/AiChatPromptInput.tsx  |   6 +
 .../ai-chat/ai-chat-tool-receipts.ts          |  13 +-
 .../ai-chat/useConsumeComposerPrompt.ts       |  52 +++++
 .../document-editor/DocumentEditorSurface.tsx |   4 +
 .../document-editor/DocumentToolbar.tsx       |  91 +++++---
 .../widget/WorkspaceAddWidgetDialog.tsx       | 111 ++++++++++
 .../widget/WorkspaceWidgetSandbox.tsx         | 118 +++++++++++
 .../workspace-widget-sandbox-document.test.ts |  30 +++
 .../workspace-widget-sandbox-document.ts      | 196 ++++++++++++++++++
 .../composer/workspace-composer-actions.ts    |  29 +++
 .../workspace-content-contract.test.ts        |   2 +
 .../content/workspace-content-contract.ts     |  21 ++
 .../content/workspace-content-reader.test.ts  |  58 +++++-
 .../content/workspace-content-reader.ts       |  39 +++-
 .../content/workspace-read-references.ts      |   4 +-
 .../documents/document-ai-edits.test.ts       |   6 +-
 .../workspaces/documents/document-ai-edits.ts | 136 +++++++++++-
 .../documents/document-ai-html.test.ts        |  72 ++++++-
 .../workspaces/documents/document-ai-html.ts  | 176 +++++++++-------
 .../documents/document-preview-text.test.ts   |  38 ++++
 .../documents/document-preview-text.ts        |   4 +
 .../workspaces/documents/document-session.ts  |  39 +++-
 .../documents/document-widget-node.tsx        |  44 ++++
 .../workspaces/documents/tiptap-extensions.ts |   2 +
 .../workspaces/documents/tiptap-schema.ts     |  55 ++++-
 .../kernel/workspace-kernel-access.ts         |  21 +-
 .../kernel/workspace-kernel-files.ts          |   5 +-
 .../kernel/workspace-kernel-item-commands.ts  |  54 +++--
 .../kernel/workspace-kernel-types.ts          |  11 -
 .../workspaces/kernel/workspace-kernel.ts     |  19 +-
 src/features/workspaces/model/item-display.ts |  11 +-
 .../model/use-workspace-item-path.ts          |  26 +++
 .../model/workspace-ai-context-reference.ts   |   9 +-
 .../workspace-tool-surface.test.ts.snap       |  63 +++++-
 .../workspaces/operations/create-items.ts     |   5 +-
 .../operations/workspace-tool-definitions.ts  |   6 +-
 .../operations/workspace-tool-schemas.ts      |  42 +++-
 src/features/workspaces/query-options.ts      |  19 +-
 src/features/workspaces/server/functions.ts   |  11 +
 .../workspace-ai-composer-draft-store.ts      |  55 ++++-
 .../workspaces/workspace-item-registry.ts     |  35 +++-
 src/styles.css                                |  74 +++++++
 61 files changed, 2501 insertions(+), 234 deletions(-)
 create mode 100644 eval/__reports__/math-authoring.md
 create mode 100644 eval/datasets/math-authoring.cases.ts
 create mode 100644 eval/math-authoring.eval.ts
 create mode 100644 scripts/copy-widget-libs.mjs
 create mode 100644 src/features/workspaces/ai/skills/widget-authoring/SKILL.md
 create mode 100644 src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts
 create mode 100644 src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
 create mode 100644 src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
 create mode 100644 src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
 create mode 100644 src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
 create mode 100644 src/features/workspaces/documents/document-preview-text.test.ts
 create mode 100644 src/features/workspaces/documents/document-widget-node.tsx
 create mode 100644 src/features/workspaces/model/use-workspace-item-path.ts

diff --git a/.gitignore b/.gitignore
index b3216757a..7cea18f11 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,3 +37,6 @@ references
 
 # Local eval scratch output
 tmp-eval/
+
+# Vendored browser builds for widget sandboxes (generated by scripts/copy-widget-libs.mjs)
+public/widget-libs/
diff --git a/eval/__reports__/math-authoring.md b/eval/__reports__/math-authoring.md
new file mode 100644
index 000000000..85fb008b6
--- /dev/null
+++ b/eval/__reports__/math-authoring.md
@@ -0,0 +1,88 @@
+case | claude-sonnet| claude-haiku | gpt-luna | gemini-pro
+--------------------------------------------------------------------------------------------------------
+
+document: study sheet with formulas | PASS | PASS | PASS | PASS  
+document: exponents and subscripts in prose | PASS | PASS | PASS | PASS  
+document: chemistry equation | FAIL | PASS | PASS | PASS  
+document: prices only (currency must stay pl| PASS | PASS | PASS | PASS  
+document: money AND math together (opposite | PASS | FAIL | PASS | PASS  
+chat: explain a formula | PASS | PASS | PASS | PASS  
+chat: money question | PASS | PASS | PASS | PASS  
+chat: money and math in one answer | PASS | PASS | FAIL | FAIL  
+widget: interactive with a formula | PASS | PASS | PASS | PASS  
+document: user types dollar math in the prom| PASS | PASS | PASS | PASS  
+document: user types bracket math in the pro| PASS | PASS | PASS | PASS  
+document: editing an existing doc adds an eq| FAIL tool✗ | FAIL tool✗ | FAIL tool✗ | FAIL tool✗
+
+claude-sonnet 10/12 content rules satisfied
+claude-haiku 10/12 content rules satisfied
+gpt-luna 10/12 content rules satisfied
+gemini-pro 10/12 content rules satisfied
+
+document 26/32 across all models
+chat 10/12 across all models
+widget 4/4 across all models
+
+failures
+
+[claude-sonnet] document: chemistry equation
+must not contain <sub>/<sup> tags
+--- wrote: document
+/Methane Combustion
+<h1>Methane Combustion</h1><p>Methane (CH<sub></sub>) is the simplest hydrocarbon and the main component of natural gas. When it burns, it reacts with oxygen in a process called <strong>combustion</strong>, releasing energy as heat and light.</p><h2>Complete Combustion</h2><p>With plentiful oxygen, methane burns completely to form carbon dioxide and water vapor:</p><div data-type="block-math" data-latex="\ce{CH4 + 2 O2 -> CO2 + 2 H2O}"></div><p>This reaction is <strong>exothermic</strong>, meaning it releases energy. This is why methane (natural gas) is used as a f…
+
+[claude-haiku] document: money AND math together (opposite dollar rules)
+must not contain backslash-escaped \$
+--- wrote: document
+/Compound Interest Guide
+<h1>Compound Interest</h1>
+
+<h2>What is Compound Interest?</h2>
+<p>Compound interest is interest earned on both the principal amount and the accumulated interest from previous periods. This creates exponential growth over time, making it a powerful tool for long-term investments and savings.</p>
+
+<h2>The Compound Interest Formula</h2>
+<p>The standard formula for compound interest is:</p>
+<div data-type="block-math" data-latex="A = P\left(1 + \frac{r}{n}\right)^{nt}"></div>
+
+<p>Where:</p>
+<ul>
+<li><strong>A</strong> = Final amount (principal + interest)</li>
+<l…
+
+[gpt-luna] chat: money and math in one answer
+must not contain \(…\) or \[…\] delimiters
+--- wrote: With annual compounding:
+
+\[
+A = 2000(1.05)^3 = \$2{,}315.25
+\]
+
+You’d end up with **\$2,315.25**, earning **\$315.25** in interest.
+
+[gemini-pro] chat: money and math in one answer
+must not contain unescaped $30-style amount
+--- wrote: You will end up with **\$2,315.25**.
+
+Here is the breakdown using the compound interest formula $A = P(1 + r)^t$:
+
+- **Principal ($P$):** \$2,000
+- **Interest Rate ($r$):** 5% or $0.05$
+- **Time ($t$):** 3 years
+
+$$A = 2000 \times (1 + 0.05)^3$$
+$$A = 2000 \times 1.157625$$
+$$A = 2315.25$$
+
+Your total interest earned over the 3 years will be **\$315.25**.
+
+[claude-sonnet] document: editing an existing doc adds an equation
+no workspace_edit_item input to grade
+
+[claude-haiku] document: editing an existing doc adds an equation
+no workspace_edit_item input to grade
+
+[gpt-luna] document: editing an existing doc adds an equation
+no workspace_edit_item input to grade
+
+[gemini-pro] document: editing an existing doc adds an equation
+no workspace_edit_item input to grade
diff --git a/eval/datasets/math-authoring.cases.ts b/eval/datasets/math-authoring.cases.ts
new file mode 100644
index 000000000..aaac880fe
--- /dev/null
+++ b/eval/datasets/math-authoring.cases.ts
@@ -0,0 +1,154 @@
+import type { WorkspaceAgentInput } from "../support/harness";
+import type { ContentCheck } from "../support/scorers";
+
+/**
+ * How well do models author math, currency, and chemistry across our surfaces?
+ *
+ * Each surface has a different, silently-failing contract:
+ *  - document HTML wants `data-latex` markup and plain-text currency;
+ *  - a chat reply wants `$…$` delimiters and backslash-escaped currency;
+ *  - widget HTML runs in a sandbox that renders either dialect.
+ * Nothing errors when a model picks the wrong one — a document just shows
+ * literal dollar signs forever — so only content grading catches it.
+ *
+ * Prompts are deliberately written the way a real user types: casual, and
+ * never naming markup. A prompt that says "use data-latex" would grade the
+ * prompt rather than the system prompt we actually ship.
+ */
+export interface MathAuthoringCase {
+	name: string;
+	/** Which shipped contract this case exercises. */
+	surface: "document" | "chat" | "widget";
+	input: WorkspaceAgentInput;
+	expectedTools?: string[];
+	contentChecks: ContentCheck[];
+}
+
+// --- Shipped-contract patterns ------------------------------------------------
+const MATH_MARKUP = {
+	label: 'data-type="inline-math"/"block-math" markup',
+	pattern: /data-type="(inline|block)-math"/,
+};
+// A dollar pair only counts as math if real LaTeX sits between the delimiters.
+// Plain `/\$…\$/` matched across two prices ("$30/hour … $75/hour") and reported
+// currency as math — a false failure indistinguishable from a real one.
+const DOLLAR_MATH = {
+	label: "$…$ math delimiters",
+	pattern: /\$[^$\n]{0,80}\\[a-zA-Z]+[^$\n]{0,80}\$/,
+};
+const BRACKET_MATH = { label: "\\(…\\) or \\[…\\] delimiters", pattern: /\\\(|\\\[/ };
+const SUB_SUP_TAGS = { label: "<sub>/<sup> tags", pattern: /<\/?(sub|sup)>/ };
+const ESCAPED_DOLLAR = { label: "backslash-escaped \\$", pattern: /\\\$/ };
+// Must not match the `$8` inside an already-escaped `\$80`, so require the
+// dollar to be unescaped.
+const PLAIN_DOLLAR_AMOUNT = {
+	label: "unescaped $30-style amount",
+	// Excludes both `\$80` (already escaped) and `$$2000…` (display math that
+	// happens to open with a digit) — both were scored as unescaped currency.
+	pattern: /(^|[^\\$])\$\d/,
+};
+const MHCHEM = { label: "\\ce{…}", pattern: /\\+ce\{/ };
+const DOLLAR_INSIDE_LATEX = {
+	label: "dollar signs inside data-latex",
+	pattern: /data-latex="[^"]*\$/,
+};
+
+const documentContent = (checks: Omit<ContentCheck, "source">): ContentCheck => ({
+	source: { tool: "workspace_create_items" },
+	...checks,
+});
+
+export const mathAuthoringCases: MathAuthoringCase[] = [
+	// --- Documents ------------------------------------------------------------
+	{
+		name: "doc: study sheet with formulas",
+		surface: "document",
+		input: { prompt: "can you make me a study sheet on the quadratic formula" },
+		expectedTools: ["workspace_create_items"],
+		contentChecks: [
+			documentContent({
+				mustMatch: [MATH_MARKUP],
+				mustNotMatch: [DOLLAR_MATH, BRACKET_MATH, SUB_SUP_TAGS, DOLLAR_INSIDE_LATEX],
+			}),
+		],
+	},
+	{
+		name: "doc: exponents and subscripts in prose",
+		surface: "document",
+		input: {
+			prompt:
+				"write up a short doc explaining scientific notation, use something like 6.02 times 10 to the 23 as an example",
+		},
+		expectedTools: ["workspace_create_items"],
+		contentChecks: [
+			documentContent({ mustMatch: [MATH_MARKUP], mustNotMatch: [SUB_SUP_TAGS, DOLLAR_MATH] }),
+		],
+	},
+	{
+		name: "doc: chemistry equation",
+		surface: "document",
+		input: { prompt: "make me a doc for chem class on what happens when methane burns" },
+		expectedTools: ["workspace_create_items"],
+		contentChecks: [
+			documentContent({ mustMatch: [MHCHEM], mustNotMatch: [SUB_SUP_TAGS, DOLLAR_MATH] }),
+		],
+	},
+	{
+		name: "doc: prices only (currency must stay plain)",
+		surface: "document",
+		input: {
+			prompt:
+				"make a doc for my tutoring rates - 30 an hour normally, 75 an hour for exam prep, 200 for a 3 session bundle",
+		},
+		expectedTools: ["workspace_create_items"],
+		contentChecks: [documentContent({ mustNotMatch: [ESCAPED_DOLLAR] })],
+	},
+	{
+		name: "doc: money AND math together (opposite dollar rules)",
+		surface: "document",
+		input: {
+			prompt:
+				"write me a doc on compound interest, show the formula and work through an example with 5000 dollars at 4% for 10 years",
+		},
+		expectedTools: ["workspace_create_items"],
+		contentChecks: [
+			documentContent({ mustMatch: [MATH_MARKUP], mustNotMatch: [ESCAPED_DOLLAR, DOLLAR_MATH] }),
+		],
+	},
+
+	// --- Chat replies ---------------------------------------------------------
+	{
+		name: "chat: explain a formula",
+		surface: "chat",
+		input: { prompt: "whats the quadratic formula again and how do i use it" },
+		contentChecks: [{ source: "text", mustMatch: [DOLLAR_MATH], mustNotMatch: [BRACKET_MATH] }],
+	},
+	{
+		name: "chat: money question",
+		surface: "chat",
+		input: { prompt: "a jacket is 80 bucks and its 25% off, whats the final price" },
+		contentChecks: [{ source: "text", mustNotMatch: [PLAIN_DOLLAR_AMOUNT] }],
+	},
+	{
+		name: "chat: money and math in one answer",
+		surface: "chat",
+		input: {
+			prompt: "if i invest 2000 at 5% compounded yearly for 3 years how much do i end up with",
+		},
+		contentChecks: [{ source: "text", mustNotMatch: [PLAIN_DOLLAR_AMOUNT, BRACKET_MATH] }],
+	},
+
+	// --- Widgets --------------------------------------------------------------
+	{
+		name: "widget: interactive with a formula",
+		surface: "widget",
+		input: { prompt: "build me something interactive to play with sine waves" },
+		expectedTools: ["workspace_create_items"],
+		contentChecks: [
+			{
+				source: { tool: "workspace_create_items" },
+				mustNotMatch: [{ label: "<html>/<body> wrapper", pattern: /<\/?(html|body|head)[\s>]/ }],
+			},
+		],
+	},
+];
diff --git a/eval/datasets/workspace-tools.cases.ts b/eval/datasets/workspace-tools.cases.ts
index 1dec989a1..2b796dc98 100644
--- a/eval/datasets/workspace-tools.cases.ts
+++ b/eval/datasets/workspace-tools.cases.ts
@@ -1,4 +1,5 @@
 import type { WorkspaceAgentInput } from "../support/harness";
+import type { ContentCheck } from "../support/scorers";
 
 export interface WorkspaceToolCase {
 	name: string;
@@ -11,8 +12,23 @@ export interface WorkspaceToolCase {
 	qualityRubric?: string;
 	/** When true, the turn must produce a targeted edit whose ref traces to the read fixture. */
 	requiresTargetedEditFromRead?: boolean;
+	/** Grade what the model wrote — the answer text, or a tool's arguments. */
+	contentChecks?: ContentCheck[];
 }
 
+// Math is authored differently per surface and the failure is silent: `$x^2$` in
+// document HTML is schema-valid and renders as literal dollar signs forever, so
+// only a content check catches it. These patterns encode the shipped contract.
+const DOCUMENT_MATH_MARKUP = {
+	label: 'data-type="inline-math" or block-math',
+	pattern: /data-type="(inline|block)-math"/,
+};
+const DOLLAR_DELIMITED_MATH = { label: "$...$ math delimiters", pattern: /\$[^$\n]{1,80}\$/ };
+const BRACKET_DELIMITED_MATH = { label: "\\(...\\) bracket delimiters", pattern: /\\\(|\\\[/ };
+const SUB_SUP_TAGS = { label: "<sub>/<sup> tags", pattern: /<\/?(sub|sup)>/ };
+const ESCAPED_DOLLAR = { label: "backslash-escaped \\$", pattern: /\\\$/ };
+const MHCHEM_CE = { label: "\\ce{...} chemistry", pattern: /\\\\?ce\{/ };
+
 // A view-only scope block: mirrors what beforeTurn injects for a read-only viewer.
 // Used to prove the model respects the boundary the prompt sets.
 const VIEW_ONLY_SCOPE =
@@ -80,4 +96,72 @@ export const workspaceToolCases: WorkspaceToolCase[] = [
 		qualityRubric:
 			"The answer correctly explains that a folder contains items while a document holds content, in roughly one sentence.",
 	},
+
+	// ---- Math authoring, per surface -------------------------------------------
+	// The shipped contract: documents use data-latex markup and never dollar
+	// delimiters; chat replies use dollar delimiters and never brackets; literal
+	// currency is escaped in Markdown but plain in document HTML.
+	{
+		name: "document math uses data-latex markup, never dollar delimiters",
+		input: {
+			prompt:
+				"Create a document at /Notes/Quadratic.md that explains the quadratic formula and shows the formula itself, plus the discriminant b^2 - 4ac.",
+		},
+		expectedTools: ["workspace_create_items"],
+		contentChecks: [
+			{
+				source: { tool: "workspace_create_items" },
+				mustMatch: [DOCUMENT_MATH_MARKUP],
+				mustNotMatch: [DOLLAR_DELIMITED_MATH, BRACKET_DELIMITED_MATH, SUB_SUP_TAGS],
+			},
+		],
+	},
+	{
+		name: "document chemistry uses \\ce inside math markup",
+		input: {
+			prompt:
+				"Create a document at /Notes/Combustion.md showing the balanced equation for methane combustion and the standard gravity constant with units.",
+		},
+		expectedTools: ["workspace_create_items"],
+		contentChecks: [
+			{
+				source: { tool: "workspace_create_items" },
+				mustMatch: [DOCUMENT_MATH_MARKUP, MHCHEM_CE],
+				mustNotMatch: [DOLLAR_DELIMITED_MATH, SUB_SUP_TAGS],
+			},
+		],
+	},
+	{
+		name: "document currency stays plain, not markdown-escaped",
+		input: {
+			prompt:
+				"Create a document at /Notes/Pricing.md listing three tiers costing $30, $60 and $90 per month.",
+		},
+		expectedTools: ["workspace_create_items"],
+		contentChecks: [{ source: { tool: "workspace_create_items" }, mustNotMatch: [ESCAPED_DOLLAR] }],
+	},
+	{
+		name: "chat math uses dollar delimiters, never brackets",
+		input: {
+			prompt:
+				"Explain the quadratic formula in a couple of sentences and show the formula. Answer in chat; do not create anything.",
+		},
+		forbiddenTools: ["workspace_create_items", "workspace_edit_item"],
+		contentChecks: [
+			{
+				source: "text",
+				mustMatch: [DOLLAR_DELIMITED_MATH],
+				mustNotMatch: [BRACKET_DELIMITED_MATH],
+			},
+		],
+	},
+	{
+		name: "chat escapes literal currency",
+		input: {
+			prompt:
+				"A jacket costs $80 and is 25% off. What is the sale price? Answer in chat; do not create anything.",
+		},
+		forbiddenTools: ["workspace_create_items"],
+		contentChecks: [{ source: "text", mustMatch: [ESCAPED_DOLLAR] }],
+	},
 ];
diff --git a/eval/math-authoring.eval.ts b/eval/math-authoring.eval.ts
new file mode 100644
index 000000000..0b9999466
--- /dev/null
+++ b/eval/math-authoring.eval.ts
@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest";
+
+import { mathAuthoringCases } from "./datasets/math-authoring.cases";
+import { runWorkspaceAgent } from "./support/harness";
+import { scoreContent, scoreExpectedTools } from "./support/scorers";
+
+/**
+ * Cross-model benchmark for math / currency / chemistry authoring.
+ *
+ * Unlike `workspace-tools.eval.ts` this does not assert — it measures. A model
+ * scoring badly is data about the prompt, not a broken build, and failing the
+ * run would hide the rest of the matrix. Results print as a table so a prompt
+ * or schema change can be judged against a before/after.
+ *
+ * The whole matrix runs inside one test with a bounded worker pool rather than
+ * as `describe.concurrent`: the report has to print after every row lands, and
+ * concurrent `it`s would race it. The cap keeps us under gateway rate limits.
+ *
+ * Env: EVAL_MODELS (comma-separated ids from models.ts), EVAL_CONCURRENCY.
+ */
+const MODELS = (process.env.EVAL_MODELS ?? "claude-sonnet,claude-haiku,gpt-luna,gemini-pro")
+	.split(",")
+	.map((id) => id.trim())
+	.filter(Boolean);
+
+const CONCURRENCY = Number(process.env.EVAL_CONCURRENCY ?? 8);
+
+interface Row {
+	model: string;
+	surface: string;
+	case: string;
+	toolPass: boolean | null;
+	contentPass: boolean;
+	detail: string;
+}
+
+async function mapWithLimit<T, R>(
+	items: T[],
+	limit: number,
+	run: (item: T) => Promise<R>,
+): Promise<R[]> {
+	const results = new Array<R>(items.length);
+	let cursor = 0;
+	const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+		for (;;) {
+			const index = cursor++;
+			const item = items[index];
+			if (index >= items.length || item === undefined) return;
+			results[index] = await run(item);
+		}
+	});
+	await Promise.all(workers);
+	return results;
+}
+
+function formatTable(rows: Row[]): string {
+	const labels = [...new Set(rows.map((row) => `${row.surface}: ${row.case}`))];
+	const width = 44;
+	const header = ["case".padEnd(width), ...MODELS.map((model) => model.padEnd(13))].join("| ");
+	const lines = [header, "-".repeat(header.length)];
+
+	for (const label of labels) {
+		const cells = MODELS.map((model) => {
+			const row = rows.find((r) => `${r.surface}: ${r.case}` === label && r.model === model);
+			if (!row) return "—".padEnd(13);
+			const tool = row.toolPass === false ? " tool✗" : "";
+			return `${row.contentPass ? "PASS" : "FAIL"}${tool}`.padEnd(13);
+		});
+		lines.push([label.slice(0, width).padEnd(width), ...cells].join("| "));
+	}
+
+	lines.push("");
+	for (const model of MODELS) {
+		const mine = rows.filter((row) => row.model === model);
+		const passed = mine.filter((row) => row.contentPass).length;
+		lines.push(`${model.padEnd(14)} ${passed}/${mine.length} content rules satisfied`);
+	}
+
+	lines.push("");
+	for (const surface of [...new Set(rows.map((row) => row.surface))]) {
+		const mine = rows.filter((row) => row.surface === surface);
+		const passed = mine.filter((row) => row.contentPass).length;
+		lines.push(`${surface.padEnd(14)} ${passed}/${mine.length} across all models`);
+	}
+	return lines.join("\n");
+}
+
+describe.skipIf(!process.env.AI_GATEWAY_API_KEY)("math authoring benchmark", () => {
+	it("measures math/currency authoring across models", { timeout: 900_000 }, async () => {
+		const jobs = mathAuthoringCases.flatMap((testCase) =>
+			MODELS.map((model) => ({ model, testCase })),
+		);
+
+		const rows = await mapWithLimit(jobs, CONCURRENCY, async ({ model, testCase }) => {
+			try {
+				const output = await runWorkspaceAgent({ ...testCase.input, modelId: model });
+				const results = testCase.contentChecks.map((check) => scoreContent(output, check));
+				return {
+					model,
+					surface: testCase.surface,
+					case: testCase.name.replace(/^\w+: /, ""),
+					toolPass: testCase.expectedTools?.length
+						? scoreExpectedTools(output, testCase.expectedTools).pass
+						: null,
+					contentPass: results.every((result) => result.pass),
+					detail: results
+						.filter((result) => !result.pass)
+						.map((result) => result.message)
+						.join(" | "),
+				} satisfies Row;
+			} catch (error) {
+				// One model erroring must not sink the rest of the matrix.
+				return {
+					model,
+					surface: testCase.surface,
+					case: testCase.name.replace(/^\w+: /, ""),
+					toolPass: null,
+					contentPass: false,
+					detail: `turn failed: ${error instanceof Error ? error.message : String(error)}`,
+				} satisfies Row;
+			}
+		});
+
+		// The workers pool does not forward console output to stdout, so the report
+		// is written through the file-snapshot channel instead: that lands on disk
+		// from the Node side, and a re-run diffs against the previous numbers —
+		// exactly the before/after view a prompt change needs.
+		const report = [
+			formatTable(rows),
+			"",
+			"failures",
+			...rows
+				.filter((row) => !row.contentPass)
+				.map((row) => `\n[${row.model}] ${row.surface}: ${row.case}\n${row.detail}`),
+		].join("\n");
+
+		await expect(report).toMatchFileSnapshot("./__reports__/math-authoring.md");
+	});
+});
diff --git a/eval/support/harness.ts b/eval/support/harness.ts
index b4eb3fe0d..9e7b159c1 100644
--- a/eval/support/harness.ts
+++ b/eval/support/harness.ts
@@ -5,6 +5,7 @@ import type { z } from "zod";
 import { getAIThreadSoulPrompt } from "#/features/workspaces/ai/ai-thread-soul-prompt";
 import { createProviderCompatibleInputSchema } from "#/features/workspaces/ai/ai-thread-tool";
 import {
+	getAIThreadSystemPromptForWorkspace,
 	getWorkspaceAiGatewayProviderOptions,
 	getWorkspaceAiLanguageModel,
 } from "#/features/workspaces/ai/ai-thread-runtime";
@@ -41,8 +42,11 @@ export interface WorkspaceAgentInput {
 	prompt: string;
 	/** Friendly model id from `models.ts` (e.g. "claude-sonnet"). Defaults to "auto". */
 	modelId?: string;
-	/** Extra system text appended to the soul prompt (e.g. a workspace scope block). */
+	/** Extra system text appended to the workspace prompt (e.g. a scope override). */
 	system?: string;
+	/** Whether the turn may mutate; drives the real runtime scope block. */
+	canMutate?: boolean;
+	workspaceName?: string;
 }
 
 // Deterministic read fixture: document HTML carrying real `data-ref` values, so a
@@ -52,23 +56,61 @@ const STANDUP_HEADING_REF = "b_standupHead1.r_head000001";
 const STANDUP_LIST_REF = "b_standupList1.r_bullet0001";
 export const EVAL_READ_FIXTURE_REFS = [STANDUP_HEADING_REF, STANDUP_LIST_REF];
 
-// Per-tool stubbed outputs. Reads return editable HTML + refs; everything else
-// returns a neutral success so a follow-up step can still proceed. No real
-// Durable Object is touched and no workspace is mutated.
-const EVAL_TOOL_FIXTURES: Record<string, unknown> = {
-	workspace_read_items: {
-		items: [
-			{
-				path: "/Notes/Standup.md",
-				type: "document",
-				html: `<h1 data-ref="${STANDUP_HEADING_REF}">Standup</h1><ul data-ref="${STANDUP_LIST_REF}"><li>Discuss roadmap</li></ul>`,
-			},
-		],
+const KINEMATICS_HEADING_REF = "b_kinematicsH1.r_head000002";
+const KINEMATICS_MATH_REF = "b_kinematicsEq1.r_math000001";
+const PRICING_TABLE_REF = "b_pricingTable.r_table00001";
+export const EVAL_DOCUMENT_FIXTURE_REFS = [
+	KINEMATICS_HEADING_REF,
+	KINEMATICS_MATH_REF,
+	PRICING_TABLE_REF,
+];
+
+/**
+ * Realistic items the model reads before editing — written exactly as the real
+ * serializer emits them, so an edit turn sees production markup: math as empty
+ * `data-latex` elements, currency as plain text, widgets as raw HTML.
+ */
+const EVAL_READ_ITEMS: Record<string, unknown> = {
+	"/Notes/Standup.md": {
+		path: "/Notes/Standup.md",
+		type: "document",
+		format: "html",
+		content: `<h1 data-ref="${STANDUP_HEADING_REF}">Standup</h1><ul data-ref="${STANDUP_LIST_REF}"><li>Discuss roadmap</li></ul>`,
+	},
+	"/Physics/Kinematics.md": {
+		path: "/Physics/Kinematics.md",
+		type: "document",
+		format: "html",
+		content: `<h1 data-ref="${KINEMATICS_HEADING_REF}">Kinematics</h1><p>For constant acceleration, displacement over time is</p><div data-latex="s = ut + \\tfrac{1}{2}at^2" data-type="block-math" data-ref="${KINEMATICS_MATH_REF}"></div>`,
+	},
+	"/Tutoring/Pricing.md": {
+		path: "/Tutoring/Pricing.md",
+		type: "document",
+		format: "html",
+		content: `<h1 data-ref="${PRICING_TABLE_REF}">Tutoring rates</h1><p>Standard sessions are $30 an hour, and exam-prep intensives are $75 an hour.</p>`,
+	},
+	"/Physics/Wave Explorer": {
+		path: "/Physics/Wave Explorer",
+		type: "widget",
+		format: "html",
+		content: `<style>.tx-root{height:100%;padding:16px;display:flex;flex-direction:column;gap:12px}</style><div class="tx-root"><p>Adjust the frequency to see how $y = A\\sin(2\\pi f t)$ changes.</p><input id="freq" type="range" min="1" max="10" value="3" /><canvas id="wave"></canvas></div><script>const c=document.getElementById("wave");/* draws the wave */</script>`,
 	},
 };
 
-function evalToolFixture(toolName: string): unknown {
-	return EVAL_TOOL_FIXTURES[toolName] ?? { ok: true, note: "eval stub — no real mutation" };
+// Per-tool stubbed outputs. Reads return the realistic item for the requested
+// path; everything else returns a neutral success so a follow-up step can still
+// proceed. No real Durable Object is touched and no workspace is mutated.
+function evalToolFixture(toolName: string, input: unknown): unknown {
+	if (toolName === "workspace_read_items") {
+		const requests = (input as { requests?: Array<{ path?: string }> })?.requests ?? [];
+		const items = requests
+			.map((request) => (request.path ? EVAL_READ_ITEMS[request.path] : undefined))
+			.filter(Boolean);
+		// Fall back to the standup doc so an unrecognised path still returns
+		// something editable rather than an empty read.
+		return { results: items.length > 0 ? items : [EVAL_READ_ITEMS["/Notes/Standup.md"]] };
+	}
+	return { ok: true, note: "eval stub — no real mutation" };
 }
 
 // Real workspace tools with stubbed execution. Evals grade tool *selection* and
@@ -86,7 +128,7 @@ function buildEvalToolSet(): ToolSet {
 					asSchema(definition.inputSchema as z.ZodTypeAny),
 				),
 				inputExamples: definition.inputExamples,
-				execute: async () => evalToolFixture(definition.name),
+				execute: async (input: unknown) => evalToolFixture(definition.name, input),
 			}),
 		]),
 	) as ToolSet;
@@ -103,9 +145,16 @@ export async function runWorkspaceAgent(input: WorkspaceAgentInput): Promise<Wor
 	const modelId = resolveWorkspaceAiChatModelId(
 		input.modelId ?? DEFAULT_WORKSPACE_AI_CHAT_MODEL_ID,
 	);
-	const system = input.system
-		? `${getAIThreadSoulPrompt()}\n\n${input.system}`
-		: getAIThreadSoulPrompt();
+	// Production-identical system text: the soul prompt, the workspace citation
+	// rules, and the runtime scope block that `beforeTurn` injects. Grading a
+	// model against a thinner prompt than production ships would measure the
+	// harness, not the product.
+	const workspacePrompt = getAIThreadSystemPromptForWorkspace(
+		getAIThreadSoulPrompt(),
+		{ canMutate: input.canMutate ?? true, workspaceName: input.workspaceName ?? "Study" },
+		{ timeZone: "America/New_York" },
+	);
+	const system = input.system ? `${workspacePrompt}\n\n${input.system}` : workspacePrompt;
 
 	const result = await generateText({
 		model: getWorkspaceAiLanguageModel(modelId, env, "eval"),
diff --git a/eval/support/scorers.ts b/eval/support/scorers.ts
index 17af85dd7..62f0ea8f2 100644
--- a/eval/support/scorers.ts
+++ b/eval/support/scorers.ts
@@ -67,7 +67,7 @@ export function scoreNoForbiddenTools(
 /**
  * For a read→edit turn: the model must submit a *targeted* edit (replace / insert /
  * delete) whose `ref` came from the read fixture — not a fabricated ref, and not a
- * whole-document `replace_all`. Without this, a hollow read stub plus the permissive
+ * whole-document `overwrite`. Without this, a hollow read stub plus the permissive
  * `ref` schema (any nonempty string) let a hallucinated target score a false pass.
  */
 export function scoreTargetedEditProvenance(
@@ -82,16 +82,16 @@ export function scoreTargetedEditProvenance(
 			return Array.isArray(input.edits) ? input.edits : [];
 		});
 	const isValidRef = (edit: { ref?: string }) => typeof edit.ref === "string" && refs.has(edit.ref);
-	const targeted = edits.filter((edit) => edit.op !== "replace_all" && isValidRef(edit));
-	const fabricated = edits.filter((edit) => edit.op !== "replace_all" && !isValidRef(edit));
-	const usedReplaceAll = edits.some((edit) => edit.op === "replace_all");
-	const pass = targeted.length > 0 && fabricated.length === 0 && !usedReplaceAll;
+	const targeted = edits.filter((edit) => edit.op !== "overwrite" && isValidRef(edit));
+	const fabricated = edits.filter((edit) => edit.op !== "overwrite" && !isValidRef(edit));
+	const usedOverwrite = edits.some((edit) => edit.op === "overwrite");
+	const pass = targeted.length > 0 && fabricated.length === 0 && !usedOverwrite;
 
 	const reasons: string[] = [];
 	if (targeted.length === 0) reasons.push("no targeted edit used a ref from the read");
 	if (fabricated.length > 0)
 		reasons.push(`fabricated ref(s): ${fabricated.map((e) => e.ref ?? "<none>").join(", ")}`);
-	if (usedReplaceAll) reasons.push("used replace_all instead of a targeted edit");
+	if (usedOverwrite) reasons.push("used overwrite instead of a targeted edit");
 	return {
 		score: pass ? 1 : 0,
 		pass,
@@ -99,6 +99,74 @@ export function scoreTargetedEditProvenance(
 	};
 }
 
+/**
+ * What the model actually *wrote* — the final answer, or the arguments it passed
+ * to a tool. Tool choice and schema validity say nothing about authoring dialect:
+ * `$x^2$` inside document HTML is schema-valid and renders as literal dollar
+ * signs forever, so only a content check can catch it.
+ */
+export interface ContentCheck {
+	/** `"text"` grades the final answer; `{ tool }` grades that tool's inputs. */
+	source: "text" | { tool: string };
+	mustMatch?: Array<{ label: string; pattern: RegExp }>;
+	mustNotMatch?: Array<{ label: string; pattern: RegExp }>;
+}
+
+/**
+ * Every string the model wrote inside a tool argument, unescaped. Matching
+ * against `JSON.stringify(input)` instead would compare patterns like
+ * `data-type="inline-math"` against the escaped `data-type=\"inline-math\"` and
+ * silently never match — a false failure that looks exactly like a real one.
+ */
+function collectStrings(value: unknown, out: string[] = []): string[] {
+	if (typeof value === "string") {
+		out.push(value);
+	} else if (Array.isArray(value)) {
+		for (const item of value) collectStrings(item, out);
+	} else if (value && typeof value === "object") {
+		for (const item of Object.values(value)) collectStrings(item, out);
+	}
+	return out;
+}
+
+export function scoreContent(output: WorkspaceAgentOutput, check: ContentCheck): ScoreResult {
+	const source = check.source;
+	const subject =
+		typeof source === "string"
+			? output.text
+			: output.toolCalls
+					.filter((call) => call.name === source.tool)
+					.flatMap((call) => collectStrings(call.input))
+					.join("\n");
+
+	if (!subject.trim()) {
+		const label = typeof check.source === "string" ? "final answer" : `${check.source.tool} input`;
+		return { score: 0, pass: false, message: `no ${label} to grade` };
+	}
+
+	const missing = (check.mustMatch ?? []).filter((rule) => !rule.pattern.test(subject));
+	const present = (check.mustNotMatch ?? []).filter((rule) => rule.pattern.test(subject));
+	const total = (check.mustMatch?.length ?? 0) + (check.mustNotMatch?.length ?? 0);
+	const failures = missing.length + present.length;
+	const reasons = [
+		...missing.map((rule) => `missing ${rule.label}`),
+		...present.map((rule) => `must not contain ${rule.label}`),
+	];
+
+	// Include what was actually written on failure — a dialect miss is only
+	// actionable if you can see the markup the model chose instead.
+	const excerpt = subject.length > 600 ? `${subject.slice(0, 600)}…` : subject;
+
+	return {
+		score: total === 0 ? 1 : 1 - failures / total,
+		pass: failures === 0,
+		message:
+			failures === 0
+				? "content matched every rule"
+				: `${reasons.join("; ")}\n--- wrote: ${excerpt}`,
+	};
+}
+
 const QUALITY_VERDICT_SCHEMA = z.object({
 	pass: z.boolean(),
 	score: z.number().min(0).max(1),
diff --git a/eval/workspace-tools.eval.ts b/eval/workspace-tools.eval.ts
index cf3c7e274..adf2620a5 100644
--- a/eval/workspace-tools.eval.ts
+++ b/eval/workspace-tools.eval.ts
@@ -4,6 +4,7 @@ import { workspaceToolCases } from "./datasets/workspace-tools.cases";
 import { EVAL_READ_FIXTURE_REFS, runWorkspaceAgent } from "./support/harness";
 import {
 	scoreAnswerQuality,
+	scoreContent,
 	scoreExpectedTools,
 	scoreNoForbiddenTools,
 	scoreTargetedEditProvenance,
@@ -33,12 +34,21 @@ describe.skipIf(!process.env.AI_GATEWAY_API_KEY)("workspace tools", () => {
 		}
 
 		// 2b. Deterministic — a read→edit turn made a targeted edit whose ref came
-		//     from the read fixture, not a fabricated ref or a whole-doc replace_all.
+		//     from the read fixture, not a fabricated ref or a whole-doc overwrite.
 		if (testCase.requiresTargetedEditFromRead) {
 			const provenance = scoreTargetedEditProvenance(output, EVAL_READ_FIXTURE_REFS);
 			expect(provenance.pass, `edit provenance — ${provenance.message}`).toBe(true);
 		}
 
+		// 2c. Deterministic — what the model actually wrote. Tool choice and schema
+		//     validity cannot see authoring dialect: `$x^2$` in document HTML is
+		//     schema-valid and renders as literal dollar signs forever.
+		for (const check of testCase.contentChecks ?? []) {
+			const target = typeof check.source === "string" ? "answer" : check.source.tool;
+			const content = scoreContent(output, check);
+			expect(content.pass, `content (${target}) — ${content.message}`).toBe(true);
+		}
+
 		// 3. Model-graded — grade the prose answer against a rubric when set.
 		if (testCase.qualityRubric) {
 			const quality = await scoreAnswerQuality({
diff --git a/package.json b/package.json
index 1ecba0ab9..9fbd0554d 100644
--- a/package.json
+++ b/package.json
@@ -22,7 +22,7 @@
 		"doctor": "react-doctor . --scope changed --verbose",
 		"doctor:full": "react-doctor . --scope full --verbose",
 		"knip": "knip",
-		"prepare": "vp config --no-agent",
+		"prepare": "vp config --no-agent && node scripts/copy-widget-libs.mjs",
 		"test": "vp test --run",
 		"test:workers": "vp test --run --project=workers",
 		"eval": "infisical run --env=dev --path=/app -- vitest --config vitest.evals.config.ts --run",
@@ -90,6 +90,7 @@
 		"@tiptap/extension-code-block": "^3.29.2",
 		"@tiptap/extension-collaboration": "^3.29.2",
 		"@tiptap/extension-collaboration-caret": "^3.29.2",
+		"@tiptap/extension-details": "^3.29.2",
 		"@tiptap/extension-highlight": "^3.29.2",
 		"@tiptap/extension-horizontal-rule": "^3.29.2",
 		"@tiptap/extension-link": "^3.29.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 04a41b2e5..67bd2a7ba 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -170,6 +170,9 @@ importers:
       '@tiptap/extension-collaboration-caret':
         specifier: ^3.29.2
         version: 3.29.2(@tiptap/core@3.29.2(@tiptap/pm@3.29.2))(@tiptap/pm@3.29.2)(@tiptap/y-tiptap@3.0.8(prosemirror-model@1.25.11)(prosemirror-state@1.4.4)(prosemirror-view@1.42.2)(y-protocols@1.0.7(yjs@13.6.31))(yjs@13.6.31))
+      '@tiptap/extension-details':
+        specifier: ^3.29.2
+        version: 3.29.2(@tiptap/core@3.29.2(@tiptap/pm@3.29.2))(@tiptap/extension-text-style@3.29.2(@tiptap/core@3.29.2(@tiptap/pm@3.29.2)))(@tiptap/pm@3.29.2)
       '@tiptap/extension-highlight':
         specifier: ^3.29.2
         version: 3.29.2(@tiptap/core@3.29.2(@tiptap/pm@3.29.2))
@@ -347,7 +350,7 @@ importers:
         version: 1.50.0(@voidzero-dev/vite-plus-core@0.2.2(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(typescript@6.0.3)(yaml@2.9.0))(wrangler@4.118.0(@cloudflare/workers-types@5.20260801.1))
       '@cloudflare/vitest-pool-workers':
         specifier: ^0.18.8
-        version: 0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10)
+        version: 0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.2)(@vitest/browser-preview@4.1.10)(@voidzero-dev/vite-plus-core@0.2.2(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(typescript@6.0.3)(yaml@2.9.0))(jsdom@28.1.0(@noble/hashes@2.2.0))(msw@2.14.6(@types/node@26.1.2)(typescript@6.0.3)))
       '@cloudflare/workers-types':
         specifier: ^5.20260801.1
         version: 5.20260801.1
@@ -4332,6 +4335,13 @@ packages:
       '@tiptap/y-tiptap': ^3.0.7
       yjs: ^13
 
+  '@tiptap/extension-details@3.29.2':
+    resolution: {integrity: sha512-W614IjlpwkAxIUp5I2ILIWWJu//tPsJuaDp52Xjso+EYF3iyH2EklOdFYebjlt1yKllXl1OVs7RCghgRm1bauQ==}
+    peerDependencies:
+      '@tiptap/core': 3.29.2
+      '@tiptap/extension-text-style': 3.29.2
+      '@tiptap/pm': 3.29.2
+
   '@tiptap/extension-document@3.29.2':
     resolution: {integrity: sha512-YUamvefLnsqu6124GavVTI7nqcFlQJ12ROB0oSwG69eSBZYNjg1tIs05LFrBxkwf4Xgqd6YzfJ9+FeG428RvzQ==}
     peerDependencies:
@@ -4440,6 +4450,11 @@ packages:
     peerDependencies:
       '@tiptap/core': 3.29.2
 
+  '@tiptap/extension-text-style@3.29.2':
+    resolution: {integrity: sha512-aQad9V9ROaEi3hE4g5z9wQ6lv5FSnzlnWFMVJxRjNlwXgm7H0fymxb4rGfca+pAwYkiRwpKYh1LatpJw2ECQAA==}
+    peerDependencies:
+      '@tiptap/core': 3.29.2
+
   '@tiptap/extension-text@3.29.2':
     resolution: {integrity: sha512-Ubko45JWWHe8glBt2PiGNF8hcbys/JNalFhiR7Y1X4iOOtAxAKJJxh3+eq+//NTlGuBPdWGp7zw8EEUp7anjKA==}
     peerDependencies:
@@ -10262,7 +10277,7 @@ snapshots:
       - bufferutil
       - utf-8-validate
 
-  '@cloudflare/vitest-pool-workers@0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10)':
+  '@cloudflare/vitest-pool-workers@0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.2)(@vitest/browser-preview@4.1.10)(@voidzero-dev/vite-plus-core@0.2.2(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(typescript@6.0.3)(yaml@2.9.0))(jsdom@28.1.0(@noble/hashes@2.2.0))(msw@2.14.6(@types/node@26.1.2)(typescript@6.0.3)))':
     dependencies:
       '@vitest/runner': 4.1.10
       '@vitest/snapshot': 4.1.10
@@ -12990,6 +13005,12 @@ snapshots:
       '@tiptap/y-tiptap': 3.0.8(prosemirror-model@1.25.11)(prosemirror-state@1.4.4)(prosemirror-view@1.42.2)(y-protocols@1.0.7(yjs@13.6.31))(yjs@13.6.31)
       yjs: 13.6.31
 
+  '@tiptap/extension-details@3.29.2(@tiptap/core@3.29.2(@tiptap/pm@3.29.2))(@tiptap/extension-text-style@3.29.2(@tiptap/core@3.29.2(@tiptap/pm@3.29.2)))(@tiptap/pm@3.29.2)':
+    dependencies:
+      '@tiptap/core': 3.29.2(@tiptap/pm@3.29.2)
+      '@tiptap/extension-text-style': 3.29.2(@tiptap/core@3.29.2(@tiptap/pm@3.29.2))
+      '@tiptap/pm': 3.29.2
+
   '@tiptap/extension-document@3.29.2(@tiptap/core@3.29.2(@tiptap/pm@3.29.2))':
     dependencies:
       '@tiptap/core': 3.29.2(@tiptap/pm@3.29.2)
@@ -13080,6 +13101,10 @@ snapshots:
     dependencies:
       '@tiptap/core': 3.29.2(@tiptap/pm@3.29.2)
 
+  '@tiptap/extension-text-style@3.29.2(@tiptap/core@3.29.2(@tiptap/pm@3.29.2))':
+    dependencies:
+      '@tiptap/core': 3.29.2(@tiptap/pm@3.29.2)
+
   '@tiptap/extension-text@3.29.2(@tiptap/core@3.29.2(@tiptap/pm@3.29.2))':
     dependencies:
       '@tiptap/core': 3.29.2(@tiptap/pm@3.29.2)
diff --git a/scripts/copy-widget-libs.mjs b/scripts/copy-widget-libs.mjs
new file mode 100644
index 000000000..d4afecc76
--- /dev/null
+++ b/scripts/copy-widget-libs.mjs
@@ -0,0 +1,43 @@
+/*
+ * Copies KaTeX's browser build into public/ so sandboxed widget iframes can
+ * load it.
+ *
+ * Widgets run in an opaque-origin iframe under a strict CSP with no network
+ * access, so they cannot pull anything from a CDN — the assets have to be
+ * served from this app's own origin. KaTeX's stylesheet references its fonts
+ * relatively (`url(fonts/...)`), so the whole directory is copied verbatim
+ * rather than passed through the bundler.
+ *
+ * Runs from `prepare`, which keeps the copy in lockstep with the installed
+ * katex version. The output is generated, not committed.
+ */
+import { cp, mkdir, rm } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const katexDist = dirname(require.resolve("katex/dist/katex.min.js"));
+const outDir = join(
+	dirname(fileURLToPath(import.meta.url)),
+	"..",
+	"public",
+	"widget-libs",
+	"katex",
+);
+
+await rm(outDir, { recursive: true, force: true });
+await mkdir(outDir, { recursive: true });
+
+for (const entry of [
+	"katex.min.css",
+	"katex.min.js",
+	"fonts",
+	"contrib/auto-render.min.js",
+	// Chemistry (\ce) and units (\pu), matching what chat and documents import.
+	"contrib/mhchem.min.js",
+]) {
+	await cp(join(katexDist, entry), join(outDir, entry), { recursive: true });
+}
+
+console.log(`Copied KaTeX browser build to ${outDir}`);
diff --git a/src/features/workspaces/ai/ai-thread-soul-prompt.ts b/src/features/workspaces/ai/ai-thread-soul-prompt.ts
index 61c01bb44..af0c9eadd 100644
--- a/src/features/workspaces/ai/ai-thread-soul-prompt.ts
+++ b/src/features/workspaces/ai/ai-thread-soul-prompt.ts
@@ -50,7 +50,8 @@ export function getAIThreadSoulPrompt() {
 				"Let the app control Mermaid presentation: do not add frontmatter or init directives, custom styles or colors, embedded HTML, links, images, or other external resources. Include a concise `accTitle` and `accDescr` describing the diagram.",
 				"When writing Markdown with math, use `$...$` for inline math and `$$...$$` on separate lines for block math. Do not use `\\(...\\)` or `\\[...\\]`; our renderer only understands dollar-sign delimiters.",
 				"Chemistry renders with `\\ce{...}` (e.g. `$\\ce{CH4 + 2 O2 -> CO2 + 2 H2O}$`) and quantities with units render with `\\pu{...}`.",
-				"CRITICAL: every literal dollar sign — every price, cost, salary, or currency figure — MUST be escaped as `\\$`. Write `\\$5`, not `$5`. Write `\\$1,000 − \\$200 = \\$800`, not `$1,000 − $200 = $800`. A missed escape turns the price into broken math on screen.",
+				"CRITICAL, in chat replies only: every literal dollar sign — every price, cost, salary, or currency figure — MUST be escaped as `\\$`. Write `\\$5`, not `$5`. Write `\\$1,000 − \\$200 = \\$800`, not `$1,000 − $200 = $800`. A missed escape turns the price into broken math on screen.",
+				"That escape is a Markdown rule and applies to chat replies only. Document and widget content is HTML, where `\\$` renders as a visible backslash — write money plainly there, as `$30`.",
 			],
 		},
 		{
diff --git a/src/features/workspaces/ai/ai-thread.ts b/src/features/workspaces/ai/ai-thread.ts
index c61e451a1..e4da44214 100644
--- a/src/features/workspaces/ai/ai-thread.ts
+++ b/src/features/workspaces/ai/ai-thread.ts
@@ -16,6 +16,7 @@ import type {
 	TurnContext,
 } from "@cloudflare/think";
 import { defaultContextOverflowClassifier, Think } from "@cloudflare/think";
+import bundledSkills from "agents:skills";
 import { callable } from "agents";
 import { generateText, type LanguageModel, type ToolSet } from "ai";
 
@@ -134,6 +135,14 @@ export function createAIThreadClass(getUserAIStore: () => typeof UserAIStore) {
 			return getAIThreadSoulPrompt();
 		}
 
+		// On-demand instruction bundles (progressive disclosure). The model sees
+		// only each skill's name/description until a task matches, then calls
+		// activate_skill to load the full guide. Bundled from ./skills via the
+		// agents Vite plugin (agents:skills virtual module).
+		getSkills() {
+			return [bundledSkills];
+		}
+
 		configureSession(session: Session) {
 			return session
 				.withContext("soul", {
diff --git a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
new file mode 100644
index 000000000..79cffb2dd
--- /dev/null
+++ b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
@@ -0,0 +1,134 @@
+---
+name: widget-authoring
+description: Author and edit widgets — interactive document blocks whose self-contained HTML runs sandboxed in ThinkEx. Use whenever the user asks for something interactive to be built or changed — a simulation, calculator, diagram, quiz game, flashcard drill, timer, chart, or any small interactive tool or visualization.
+---
+
+# Authoring ThinkEx widgets
+
+A **widget** is a block inside a document whose content is a single, self-contained interactive HTML fragment. It renders inside a sandboxed `<iframe>` with an **opaque origin**: it cannot reach the network, cookies, storage, the parent page, or any workspace data. It is purely a self-contained interactive experience.
+
+Create one by writing a `<div data-type="widget" title="...">` into a document — its source is the element's text content, HTML-escaped. There is no separate widget item type: a document holding nothing but a widget is how a standalone widget is made.
+
+## When to reach for a widget block
+
+Use a **widget block** when the value is in _interaction or live computation_: a physics simulation, a calculator, an adjustable diagram, a quiz game with scoring, a drawing tool, a data visualization the user can tweak, a timer. Only a widget can run JavaScript.
+
+Use **ordinary blocks** when the value is in _rich text_: notes, explanations, structured study material, tables of static content. Most documents want both — prose that explains, and one widget that lets the reader try it.
+
+## The HTML contract (read this before writing any widget)
+
+1. **Fragment only.** Provide the inner content only — HTML, one or more inline `<style>` blocks, and inline `<script>`. Do **NOT** include `<!doctype>`, `<html>`, `<head>`, or `<body>`. The sandbox wraps your fragment in a full document.
+2. **All JS is inline.** No external scripts, no `import`, no `fetch`, no network, no CDN links. `connect-src` is blocked and external scripts will not load. Write vanilla JS (or hand-rolled helpers) inline in a `<script>` tag.
+3. **Theme with the app's CSS variables.** The host injects these variables so the widget looks native in light and dark mode. Use them instead of hard-coded colors:
+   `--background`, `--foreground`, `--card`, `--card-foreground`, `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--border`, `--input`, `--ring`, `--radius`.
+   The sandbox toggles a `.dark` class on the root element when the app is in dark mode; because you use the variables, you rarely need to special-case `.dark` yourself.
+4. **No chrome of your own.** The block already draws a border and a title strip showing the `title` attribute, and the surrounding prose says what the widget is for. So do **not** repeat the title as a heading, and do **not** wrap everything in an outer bordered/rounded panel. Start straight into the content. Borders and `var(--card)` backgrounds are for genuinely separate sub-regions (a stat tile, a chart panel), never the outer shell. One short line of instructions is fine when it says something the title doesn't.
+5. **Fill the frame.** The block is a fixed 420px tall. Your HTML goes directly in `<body>`, which is `height: 100%`, so put `height: 100%` on your root and design for that height rather than assuming the page will grow. Do **not** cap the width with `max-width`, centre it with `margin: auto`, or leave wide outer gutters; that strands the content in dead space. Modest padding (about 16px) is enough. Let the main visual area grow with `flex: 1` (a flex child that must shrink also needs `min-height: 0`). Anything taller scrolls inside the frame, so keep the primary controls visible without scrolling.
+6. **Fail loudly, not silently.** If something can error, let it throw — the sandbox catches runtime errors and offers the user an "Ask AI to fix" button that sends the error back to you.
+
+## Starter template
+
+Note what is _absent_: no title, no outer panel. The content starts immediately.
+
+```html
+<style>
+	.tx-root {
+		height: 100%;
+		padding: 16px;
+		display: flex;
+		flex-direction: column;
+		gap: 12px;
+	}
+	.tx-btn {
+		padding: 8px 14px;
+		border-radius: var(--radius);
+		border: 1px solid var(--border);
+		background: var(--primary);
+		color: var(--primary-foreground);
+		cursor: pointer;
+		font: inherit;
+	}
+	/* Only for a distinct sub-region, never as an outer wrapper. */
+	.tx-panel {
+		border: 1px solid var(--border);
+		border-radius: var(--radius);
+		background: var(--card);
+		color: var(--card-foreground);
+		padding: 16px;
+	}
+	.tx-muted {
+		color: var(--muted-foreground);
+	}
+</style>
+<div class="tx-root">
+	<div class="tx-panel" id="output">…</div>
+	<button class="tx-btn" id="action">Do it</button>
+</div>
+<script>
+	const output = document.getElementById("output");
+	document.getElementById("action").addEventListener("click", () => {
+		output.textContent = "Clicked at " + new Date().toLocaleTimeString();
+	});
+</script>
+```
+
+## Math, diagrams, and charts
+
+Math works exactly as it does in a document — `<span data-type="inline-math" data-latex="...">` — because both are HTML surfaces. The host loads KaTeX only when a widget contains math. `$$...$$` and `\(...\)` also render, but a lone `$` does not: it cannot be told apart from a price.
+
+Call `renderWidgetMath(element)` if you add math to the DOM after load. A malformed expression renders muted in place and never breaks the widget.
+
+No libraries are bundled beyond KaTeX: MathJax, Mermaid, D3, and every charting library are unavailable, and you cannot add your own `<script src="...">`. Draw diagrams as inline SVG you write yourself, and charts on `<canvas>` or SVG.
+
+## Drawing with `<canvas>` (read this if the widget draws anything)
+
+A canvas has two sizes: its CSS box and its backing store (`canvas.width`/`canvas.height`, default 300×150). If you only style it with CSS, your drawing is stretched or clipped — the usual symptom is a blank canvas with a smudge in one corner.
+
+Always size the backing store from the measured layout box, account for device pixel ratio, and redraw on resize:
+
+```html
+<style>
+	.chart-wrap {
+		flex: 1;
+		min-height: 0;
+	} /* min-height:0 lets a flex child actually shrink */
+	canvas {
+		display: block;
+		width: 100%;
+		height: 100%;
+	}
+</style>
+<div class="chart-wrap"><canvas id="c"></canvas></div>
+<script>
+	const canvas = document.getElementById("c");
+	const ctx = canvas.getContext("2d");
+
+	function draw() {
+		const rect = canvas.getBoundingClientRect();
+		if (rect.width === 0 || rect.height === 0) return; // not laid out yet
+		const dpr = window.devicePixelRatio || 1;
+		canvas.width = Math.round(rect.width * dpr);
+		canvas.height = Math.round(rect.height * dpr);
+		ctx.setTransform(dpr, 0, 0, dpr, 0, 0); // draw in CSS pixels
+		ctx.clearRect(0, 0, rect.width, rect.height);
+		// ...draw using rect.width / rect.height as your coordinate space...
+	}
+
+	new ResizeObserver(draw).observe(canvas); // fires once on first layout too
+</script>
+```
+
+Key points: never draw using hard-coded pixel dimensions; derive everything from the measured `rect`. Re-run `draw()` whenever an input changes as well as on resize.
+
+## Editing an existing widget
+
+1. Read the document. A widget comes back as an empty placeholder carrying its `data-ref` and title, so the source does not crowd out the prose. Read that ref back with `{ mode: "block", path, ref }` to get the source in full — never edit a widget from the placeholder alone.
+2. Prefer **targeted replacement**: `edits: [{ op: "replace_text", ref, find, replace }]`, where `ref` is the widget block's data-ref. Copy the exact current substring into `find`. It must match exactly once within that block — if it matches more than once the edit fails and tells you the count, so add surrounding context rather than guessing.
+3. For a ground-up rebuild, `{ op: "replace", ref, html }` swaps the whole widget block. For small changes ("make the button red", "add a reset control"), use `replace_text`. Never reach for `overwrite` to change a widget — it discards the entire document.
+
+## Good habits
+
+- Keep it to one focused thing done well; don't build a whole app.
+- Prefer semantic, legible markup and a small amount of CSS over sprawling styles.
+- Label controls; make interactive elements keyboard-usable where it's easy.
+- Use `<input type="range">`, buttons, and `<canvas>`/SVG freely — they all work.
diff --git a/src/features/workspaces/ai/workspace-tool-result-adapters.ts b/src/features/workspaces/ai/workspace-tool-result-adapters.ts
index d1d3193cf..d2213cb88 100644
--- a/src/features/workspaces/ai/workspace-tool-result-adapters.ts
+++ b/src/features/workspaces/ai/workspace-tool-result-adapters.ts
@@ -50,7 +50,10 @@ const workspaceCreateItemsResultAdapter = defineWorkspaceToolResultAdapter({
 			z.object({
 				itemId: z.string(),
 				path: z.string(),
-				type: z.enum(["document", "folder"]),
+				// Deliberately not an enum: this adapter only forwards the type, and
+				// a stale list here silently fails the whole result, dropping the
+				// citation refs the model needs to cite what it just created.
+				type: z.string(),
 			}),
 		),
 		references: z.array(workspaceReferenceRecordSchema),
diff --git a/src/features/workspaces/cache-keys.ts b/src/features/workspaces/cache-keys.ts
index c45465de5..ee607c088 100644
--- a/src/features/workspaces/cache-keys.ts
+++ b/src/features/workspaces/cache-keys.ts
@@ -3,3 +3,7 @@ export const workspacesQueryKey = ["workspaces"] as const;
 export function workspacePageQueryKey(workspaceId: string) {
 	return ["workspaces", workspaceId, "page"] as const;
 }
+
+export function workspaceItemContentQueryKey(workspaceId: string, itemId: string) {
+	return ["workspaces", workspaceId, "items", itemId, "content"] as const;
+}
diff --git a/src/features/workspaces/cache-page.ts b/src/features/workspaces/cache-page.ts
index 34d5ff0fc..e2196552d 100644
--- a/src/features/workspaces/cache-page.ts
+++ b/src/features/workspaces/cache-page.ts
@@ -1,5 +1,8 @@
 import type { QueryClient } from "@tanstack/react-query";
-import { workspacePageQueryKey } from "#/features/workspaces/cache-keys";
+import {
+	workspaceItemContentQueryKey,
+	workspacePageQueryKey,
+} from "#/features/workspaces/cache-keys";
 import type {
 	CreateWorkspaceItemInput,
 	MoveWorkspaceItemsInput,
@@ -115,4 +118,12 @@ export function applyWorkspaceEventToCache(
 	queryClient.setQueryData<WorkspacePage>(workspacePageQueryKey(event.workspaceId), (current) =>
 		current ? applyWorkspaceEventToPage(current, event) : current,
 	);
+
+	// A widget's rendered content lives in a separate query; refetch it when its
+	// stored content changes (e.g. the AI edits the widget) so the viewer updates.
+	if (event.type === "workspace.item.content.updated") {
+		void queryClient.invalidateQueries({
+			queryKey: workspaceItemContentQueryKey(event.workspaceId, event.payload.item.id),
+		});
+	}
 }
diff --git a/src/features/workspaces/components/WorkspaceCreateMenu.tsx b/src/features/workspaces/components/WorkspaceCreateMenu.tsx
index 42adda716..e0b867709 100644
--- a/src/features/workspaces/components/WorkspaceCreateMenu.tsx
+++ b/src/features/workspaces/components/WorkspaceCreateMenu.tsx
@@ -116,14 +116,14 @@ function getWorkspaceCreateMenuActions({
 				onSelect: id === "upload-file" ? () => onUploadFile(parentId) : undefined,
 			}),
 		),
-		...workspaceItemLearnCreateActions.map(({ type, label, Icon, iconClassName }) => ({
+		...workspaceItemLearnCreateActions.map(({ type, label, Icon, iconClassName, comingSoon }) => ({
 			kind: "item" as const,
 			id: type,
 			label,
-			trailing: "Soon",
-			disabled: true,
+			trailing: comingSoon ? "Soon" : undefined,
+			disabled: comingSoon,
 			leading: <Icon className={`size-4 ${iconClassName}`} />,
-			onSelect: () => onCreateItem({ type, parentId }),
+			onSelect: comingSoon ? undefined : () => onCreateItem({ type, parentId }),
 		})),
 	];
 }
diff --git a/src/features/workspaces/components/WorkspaceItemToolbarSlot.tsx b/src/features/workspaces/components/WorkspaceItemToolbarSlot.tsx
index 73d883448..715362053 100644
--- a/src/features/workspaces/components/WorkspaceItemToolbarSlot.tsx
+++ b/src/features/workspaces/components/WorkspaceItemToolbarSlot.tsx
@@ -16,10 +16,13 @@ import { WorkspaceFileToolbar } from "#/features/workspaces/components/Workspace
 type WorkspaceItemToolbarRegistration =
 	| {
 			canEdit: boolean;
+			/** Null until the workspace page is cached; the widget action waits on it. */
+			documentPath: string | null;
 			editor: Editor | null;
 			itemId: string;
 			kind: "document";
 			slotId: string;
+			workspaceId: string;
 	  }
 	| {
 			capture?: {
@@ -53,14 +56,18 @@ export function WorkspaceItemToolbarProvider({ children }: { children: ReactNode
 
 export function useDocumentEditorToolbar({
 	canEdit,
+	documentPath,
 	editor,
 	itemId,
 	slotId,
+	workspaceId,
 }: {
 	canEdit: boolean;
+	documentPath: string | null;
 	editor: Editor | null;
 	itemId: string;
 	slotId: string;
+	workspaceId: string;
 }) {
 	const context = use(WorkspaceItemToolbarContext);
 	const setRegistration = context?.setRegistration;
@@ -70,15 +77,25 @@ export function useDocumentEditorToolbar({
 			return;
 		}
 
-		const registration = { canEdit, editor, itemId, kind: "document" as const, slotId };
+		const registration = {
+			canEdit,
+			documentPath,
+			editor,
+			itemId,
+			kind: "document" as const,
+			slotId,
+			workspaceId,
+		};
 		setRegistration((current) => {
 			const existing = current[slotId];
 			if (
 				existing?.kind === "document" &&
 				existing.canEdit === canEdit &&
+				existing.documentPath === documentPath &&
 				existing.editor === editor &&
 				existing.itemId === itemId &&
-				existing.slotId === slotId
+				existing.slotId === slotId &&
+				existing.workspaceId === workspaceId
 			) {
 				return current;
 			}
@@ -101,7 +118,7 @@ export function useDocumentEditorToolbar({
 				return next;
 			});
 		};
-	}, [canEdit, editor, itemId, slotId, setRegistration]);
+	}, [canEdit, documentPath, editor, itemId, slotId, workspaceId, setRegistration]);
 }
 
 export function useFileItemToolbar({
@@ -194,8 +211,10 @@ export function WorkspaceItemToolbarSlot({
 				{registration.kind === "document" ? (
 					<DocumentToolbar
 						canEdit={registration.canEdit}
+						documentPath={registration.documentPath}
 						editor={registration.editor}
 						itemId={registration.itemId}
+						workspaceId={registration.workspaceId}
 					/>
 				) : (
 					<WorkspaceFileToolbar
diff --git a/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx b/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx
index d69674463..c474925dd 100644
--- a/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx
@@ -26,6 +26,7 @@ import {
 import type { AiChatModelId, AiChatStatus } from "#/features/workspaces/components/ai-chat/types";
 import { useAiChatAttachmentIntake } from "#/features/workspaces/components/ai-chat/useAiChatAttachmentIntake";
 import { useAiChatDictation } from "#/features/workspaces/components/ai-chat/useAiChatDictation";
+import { useConsumeComposerPrompt } from "#/features/workspaces/components/ai-chat/useConsumeComposerPrompt";
 import { useTypeToFocusPrompt } from "#/features/workspaces/components/ai-chat/useTypeToFocusPrompt";
 import { WorkspaceFileIntakeReviewDialog } from "#/features/workspaces/components/WorkspaceFileIntakeReviewDialog";
 import { useWorkspaceFileUpload } from "#/features/workspaces/components/WorkspaceFileUploadProvider";
@@ -130,6 +131,11 @@ export default function AiChatPromptInput({
 		setInput,
 		textareaRef,
 	});
+	useConsumeComposerPrompt({
+		setInput,
+		textareaRef,
+		workspaceId: context.workspaceId,
+	});
 
 	const attachments: Omit<AttachmentsContext, "openFileDialog"> = {
 		add: addFiles,
diff --git a/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts b/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts
index f929f2ee3..f2ff3dbd1 100644
--- a/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts
+++ b/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts
@@ -1,3 +1,8 @@
+import {
+	getWorkspaceItemRegistryEntry,
+	workspaceItemTypeSchema,
+} from "#/features/workspaces/workspace-item-registry";
+
 export type AiChatToolReceiptStatus = "completed" | "failed" | "interrupted" | "running";
 type AiChatFinishedToolReceiptStatus = Exclude<AiChatToolReceiptStatus, "interrupted" | "running">;
 
@@ -162,8 +167,12 @@ export function getFinishedToolReceipt(input: {
 			return summarizeWorkspaceBatch(input.output, {
 				failureVerb: "create",
 				successVerb: "Created",
-				typeFromItem: (item) =>
-					getString(asRecord(item).type) === "folder" ? "folder" : "document",
+				typeFromItem: (item) => {
+					const type = workspaceItemTypeSchema.safeParse(getString(asRecord(item).type));
+					return type.success
+						? getWorkspaceItemRegistryEntry(type.data).label.toLowerCase()
+						: "item";
+				},
 			});
 		case "workspace_delete_items":
 			return summarizeWorkspaceBatch(input.output, {
diff --git a/src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts b/src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts
new file mode 100644
index 000000000..f6b923118
--- /dev/null
+++ b/src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts
@@ -0,0 +1,52 @@
+import { type RefObject, useEffect } from "react";
+
+import {
+	useWorkspaceAiComposerDraftPrompt,
+	useWorkspaceAiComposerDraftStore,
+} from "#/features/workspaces/state/workspace-ai-composer-draft-store";
+
+type UseConsumeComposerPromptOptions = {
+	workspaceId: string;
+	setInput: (updater: (current: string) => string) => void;
+	textareaRef: RefObject<HTMLTextAreaElement | null>;
+};
+
+/**
+ * Seeds the composer with text staged via `stageComposerPrompt` (e.g. an item
+ * viewer's "Ask AI to fix" button), then clears it from the store so it is
+ * consumed exactly once. Existing composer text is preserved — the staged text
+ * is appended rather than overwriting what the user already typed. The staged
+ * text is never auto-sent; the user reviews and sends it themselves.
+ */
+export function useConsumeComposerPrompt({
+	workspaceId,
+	setInput,
+	textareaRef,
+}: UseConsumeComposerPromptOptions) {
+	const pendingPrompt = useWorkspaceAiComposerDraftPrompt(workspaceId);
+	const clearPrompt = useWorkspaceAiComposerDraftStore((state) => state.clearPrompt);
+
+	useEffect(() => {
+		if (!pendingPrompt) {
+			return;
+		}
+
+		setInput((current) =>
+			current.trim() ? `${current.trimEnd()}\n\n${pendingPrompt}` : pendingPrompt,
+		);
+		clearPrompt(workspaceId);
+
+		const frame = requestAnimationFrame(() => {
+			const textarea = textareaRef.current;
+			if (!textarea) {
+				return;
+			}
+
+			textarea.focus();
+			const caret = textarea.value.length;
+			textarea.setSelectionRange(caret, caret);
+		});
+
+		return () => cancelAnimationFrame(frame);
+	}, [pendingPrompt, workspaceId, clearPrompt, setInput, textareaRef]);
+}
diff --git a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
index 017fe3db4..e27bbe579 100644
--- a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
+++ b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
@@ -21,6 +21,7 @@ import {
 } from "#/features/workspaces/documents/use-document-collaboration-session";
 import { useDocumentEditReviewOverlay } from "#/features/workspaces/documents/use-document-edit-review-overlay";
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
+import { useWorkspaceItemPath } from "#/features/workspaces/model/use-workspace-item-path";
 import { DEFAULT_COLLABORATION_COLOR } from "#/lib/design-system-colors";
 import { getAuthSessionQueryOptions } from "#/lib/session-query";
 
@@ -69,6 +70,7 @@ function DocumentEditorInstance({
 	workspaceId: string;
 }) {
 	const { capabilities } = useWorkspaceMutationAccess();
+	const documentPath = useWorkspaceItemPath(workspaceId, item);
 	const paneRuntime = useWorkspacePaneRuntime();
 	const [scrollTarget, setScrollTarget] = useState<HTMLDivElement | null>(null);
 	const editor = useEditor({
@@ -102,9 +104,11 @@ function DocumentEditorInstance({
 
 	useDocumentEditorToolbar({
 		canEdit: capabilities.canMutateContent,
+		documentPath,
 		editor: capabilities.canMutateContent ? editor : null,
 		itemId: item.id,
 		slotId: viewInstanceId,
+		workspaceId,
 	});
 	useDocumentEditReviewOverlay({
 		canEdit: capabilities.canMutateContent,
diff --git a/src/features/workspaces/components/document-editor/DocumentToolbar.tsx b/src/features/workspaces/components/document-editor/DocumentToolbar.tsx
index 4dbbf8a1c..fd97a5c34 100644
--- a/src/features/workspaces/components/document-editor/DocumentToolbar.tsx
+++ b/src/features/workspaces/components/document-editor/DocumentToolbar.tsx
@@ -1,6 +1,6 @@
 import type { Editor } from "@tiptap/react";
-import { Check, Download, EllipsisVertical, FileText, Redo2, Undo2 } from "lucide-react";
-import type { ReactNode } from "react";
+import { Check, Download, EllipsisVertical, FileText, Redo2, Shapes, Undo2 } from "lucide-react";
+import { type ReactNode, useState } from "react";
 
 import { Button } from "#/components/ui/button";
 import { DocumentEditUndoButton } from "#/features/workspaces/components/document-editor/DocumentEditUndoButton";
@@ -32,6 +32,7 @@ import {
 	getTextAlignIcon,
 	isCodeBlock,
 } from "#/features/workspaces/components/document-editor/document-editor-toolbar-actions";
+import { WorkspaceAddWidgetDialog } from "#/features/workspaces/components/widget/WorkspaceAddWidgetDialog";
 import {
 	WorkspaceResponsiveToolbar,
 	WorkspaceToolbarIconButton,
@@ -40,14 +41,19 @@ import { workspaceToolbarTextButtonSizeClass } from "#/features/workspaces/compo
 
 export function DocumentToolbar({
 	canEdit,
+	documentPath,
 	editor,
 	itemId,
+	workspaceId,
 }: {
 	canEdit: boolean;
+	documentPath: string | null;
 	editor: Editor | null;
 	itemId: string;
+	workspaceId: string;
 }) {
 	const editorState = useDocumentEditorUiState(editor);
+	const [addWidgetOpen, setAddWidgetOpen] = useState(false);
 	const { activeReview, hideReview } = useDocumentEditReview();
 
 	// Reviewing borrows the toolbar rather than floating over the page: the
@@ -77,31 +83,56 @@ export function DocumentToolbar({
 	}
 
 	return (
-		<WorkspaceResponsiveToolbar
-			mobileLabel="Document actions"
-			mobileContent={<DocumentMobileMenuContent editor={editor} editorState={editorState} />}
-			mobileContentClassName="max-h-[min(var(--available-height),28rem)] w-64 max-w-[calc(100dvw-2rem)] overscroll-contain"
-			scrollable
-		>
-			<BlockTypeMenu editor={editor} editorState={editorState} />
-			<InlineFormatMenu editor={editor} editorState={editorState} />
-			<AlignMenu editor={editor} editorState={editorState} />
-			<ToolbarButton
-				label="Undo"
-				disabled={!editorState.canUndo}
-				onClick={() => editor?.chain().focus().undo().run()}
-			>
-				<Undo2 />
-			</ToolbarButton>
-			<ToolbarButton
-				label="Redo"
-				disabled={!editorState.canRedo}
-				onClick={() => editor?.chain().focus().redo().run()}
+		<>
+			<WorkspaceResponsiveToolbar
+				mobileLabel="Document actions"
+				mobileContent={
+					<DocumentMobileMenuContent
+						editor={editor}
+						editorState={editorState}
+						onAddWidget={documentPath ? () => setAddWidgetOpen(true) : undefined}
+					/>
+				}
+				mobileContentClassName="max-h-[min(var(--available-height),28rem)] w-64 max-w-[calc(100dvw-2rem)] overscroll-contain"
+				scrollable
 			>
-				<Redo2 />
-			</ToolbarButton>
-			<DocumentMoreMenu disabled={!editor} />
-		</WorkspaceResponsiveToolbar>
+				<BlockTypeMenu editor={editor} editorState={editorState} />
+				<InlineFormatMenu editor={editor} editorState={editorState} />
+				<AlignMenu editor={editor} editorState={editorState} />
+				<ToolbarButton
+					label="Undo"
+					disabled={!editorState.canUndo}
+					onClick={() => editor?.chain().focus().undo().run()}
+				>
+					<Undo2 />
+				</ToolbarButton>
+				<ToolbarButton
+					label="Redo"
+					disabled={!editorState.canRedo}
+					onClick={() => editor?.chain().focus().redo().run()}
+				>
+					<Redo2 />
+				</ToolbarButton>
+				{/* Disabled rather than hidden while the path loads, so the control
+				    does not appear and disappear as the workspace page settles. */}
+				<ToolbarButton
+					label="Add widget"
+					disabled={!documentPath}
+					onClick={() => setAddWidgetOpen(true)}
+				>
+					<Shapes />
+				</ToolbarButton>
+				<DocumentMoreMenu disabled={!editor} />
+			</WorkspaceResponsiveToolbar>
+			{documentPath ? (
+				<WorkspaceAddWidgetDialog
+					documentPath={documentPath}
+					open={addWidgetOpen}
+					workspaceId={workspaceId}
+					onOpenChange={setAddWidgetOpen}
+				/>
+			) : null}
+		</>
 	);
 }
 
@@ -149,9 +180,11 @@ function DocumentEditReviewControls({
 function DocumentMobileMenuContent({
 	editor,
 	editorState,
+	onAddWidget,
 }: {
 	editor: Editor | null;
 	editorState: DocumentEditorUiState;
+	onAddWidget?: () => void;
 }) {
 	return (
 		<>
@@ -195,6 +228,12 @@ function DocumentMobileMenuContent({
 					label="Redo"
 					onClick={() => editor?.chain().focus().redo().run()}
 				/>
+				<DocumentHistoryMenuItem
+					disabled={!onAddWidget}
+					icon={<Shapes />}
+					label="Add widget"
+					onClick={() => onAddWidget?.()}
+				/>
 			</DropdownMenuGroup>
 			<DropdownMenuSeparator />
 			<DocumentExportMenuGroup />
diff --git a/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx b/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
new file mode 100644
index 000000000..9ce9a40bb
--- /dev/null
+++ b/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
@@ -0,0 +1,111 @@
+import { useId } from "react";
+
+import { Button } from "#/components/ui/button";
+import {
+	Dialog,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+} from "#/components/ui/dialog";
+import { Field, FieldGroup, FieldLabel } from "#/components/ui/field";
+import { Textarea } from "#/components/ui/textarea";
+import { stageComposerPrompt } from "#/features/workspaces/composer/workspace-composer-actions";
+
+/**
+ * Adding a widget is an AI-authoring kickoff, not a blank block. Rather than
+ * insert an empty widget the user would have to fill in by hand, we collect a
+ * description and hand it to the AI by prefilling the composer (via the shared
+ * `stageComposerPrompt` primitive). The AI writes the widget into the document.
+ *
+ * The prompt names the document by path because it is staged, not sent: the
+ * user may switch views before sending, which would leave "this document"
+ * pointing somewhere else.
+ */
+export function WorkspaceAddWidgetDialog({
+	documentPath,
+	open,
+	workspaceId,
+	onOpenChange,
+}: {
+	documentPath: string;
+	open: boolean;
+	workspaceId: string;
+	onOpenChange: (open: boolean) => void;
+}) {
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			{open ? (
+				<WorkspaceAddWidgetDialogContent
+					documentPath={documentPath}
+					workspaceId={workspaceId}
+					onOpenChange={onOpenChange}
+				/>
+			) : null}
+		</Dialog>
+	);
+}
+
+function WorkspaceAddWidgetDialogContent({
+	documentPath,
+	workspaceId,
+	onOpenChange,
+}: {
+	documentPath: string;
+	workspaceId: string;
+	onOpenChange: (open: boolean) => void;
+}) {
+	const descriptionId = useId();
+
+	return (
+		<DialogContent>
+			<form
+				className="grid gap-6"
+				action={(formData) => {
+					const raw = formData.get("description");
+					const description = (typeof raw === "string" ? raw : "").trim();
+
+					if (!description) {
+						return;
+					}
+
+					stageComposerPrompt(
+						workspaceId,
+						`Add an interactive widget to ${documentPath}: ${description}`,
+						{ revealChat: true },
+					);
+					onOpenChange(false);
+				}}
+			>
+				<DialogHeader>
+					<DialogTitle>Add a widget</DialogTitle>
+					<DialogDescription>
+						A widget is a small interactive tool — a simulation, calculator, diagram, or
+						visualization — that lives in this document. Describe what you want and the AI will
+						build it for you.
+					</DialogDescription>
+				</DialogHeader>
+				<FieldGroup>
+					<Field>
+						<FieldLabel htmlFor={descriptionId}>What should it do?</FieldLabel>
+						<Textarea
+							id={descriptionId}
+							name="description"
+							rows={4}
+							required
+							autoFocus
+							placeholder="e.g. An interactive unit circle that shows sine and cosine as I drag the angle"
+						/>
+					</Field>
+				</FieldGroup>
+				<DialogFooter>
+					<Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+						Cancel
+					</Button>
+					<Button type="submit">Add with AI</Button>
+				</DialogFooter>
+			</form>
+		</DialogContent>
+	);
+}
diff --git a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
new file mode 100644
index 000000000..56c31a52d
--- /dev/null
+++ b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
@@ -0,0 +1,118 @@
+import { Sparkles } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+
+import { useTheme } from "#/components/theme-provider";
+import { Button } from "#/components/ui/button";
+import {
+	buildWidgetSandboxDocument,
+	isWidgetSandboxFrameMessage,
+	WIDGET_SANDBOX_TOKENS,
+} from "#/features/workspaces/components/widget/workspace-widget-sandbox-document";
+import { cn } from "#/lib/utils";
+
+type WorkspaceWidgetSandboxProps = {
+	html: string;
+	className?: string;
+	/**
+	 * Called with the runtime error text when the user asks the AI to fix a
+	 * crashed widget. Omit to hide the affordance.
+	 */
+	onAskAiToFix?: (error: string) => void;
+};
+
+/**
+ * Renders untrusted, AI-authored widget HTML inside an opaque-origin sandbox
+ * iframe. The frame cannot reach the parent's cookies, storage, or DOM. Host
+ * design tokens are injected so the widget looks native in both themes, and
+ * runtime errors surface a muted banner (with an optional "Ask AI to fix"
+ * action) instead of a blank frame.
+ */
+export function WorkspaceWidgetSandbox({
+	html,
+	className,
+	onAskAiToFix,
+}: WorkspaceWidgetSandboxProps) {
+	const { resolvedTheme } = useTheme();
+	const iframeRef = useRef<HTMLIFrameElement>(null);
+	const [srcDoc, setSrcDoc] = useState<string | null>(null);
+	const [error, setError] = useState<string | null>(null);
+
+	// Build the sandbox document from the authored HTML plus the host's resolved
+	// design tokens (read from the live root). Rebuilding on theme change or edit
+	// is a fresh render, so the previous error clears with it. State is set in a
+	// frame callback, not synchronously, to keep the effect render-safe.
+	useEffect(() => {
+		const style = getComputedStyle(document.documentElement);
+		const tokens: Record<string, string> = {};
+		for (const name of WIDGET_SANDBOX_TOKENS) {
+			tokens[name] = style.getPropertyValue(name).trim();
+		}
+		const nextDoc = buildWidgetSandboxDocument({
+			html,
+			theme: resolvedTheme,
+			tokens,
+			origin: window.location.origin,
+		});
+
+		const frame = requestAnimationFrame(() => {
+			setSrcDoc(nextDoc);
+			setError(null);
+		});
+		return () => cancelAnimationFrame(frame);
+	}, [html, resolvedTheme]);
+
+	useEffect(() => {
+		function onMessage(event: MessageEvent) {
+			if (event.source !== iframeRef.current?.contentWindow) {
+				return;
+			}
+			if (!isWidgetSandboxFrameMessage(event.data)) {
+				return;
+			}
+			if (event.data.kind === "error") {
+				setError(event.data.message);
+			} else {
+				setError(null);
+			}
+		}
+
+		window.addEventListener("message", onMessage);
+		return () => window.removeEventListener("message", onMessage);
+	}, []);
+
+	return (
+		<div className={cn("relative h-full min-h-0 bg-background", className)}>
+			<iframe
+				ref={iframeRef}
+				title="Widget preview"
+				sandbox="allow-scripts"
+				srcDoc={srcDoc ?? undefined}
+				className="h-full w-full border-0 bg-background"
+			/>
+			{error ? (
+				<div className="absolute inset-x-0 bottom-0 border-border/70 border-t bg-background/95 p-3 backdrop-blur-sm">
+					<div className="flex items-start justify-between gap-3">
+						<div className="min-w-0">
+							<p className="font-medium text-foreground text-sm">This widget hit an error</p>
+							<pre className="mt-1 max-h-24 overflow-auto whitespace-pre-wrap font-mono text-muted-foreground text-xs">
+								{error}
+							</pre>
+						</div>
+						{onAskAiToFix ? (
+							<Button
+								type="button"
+								size="sm"
+								variant="secondary"
+								className="shrink-0"
+								onClick={() => onAskAiToFix(error)}
+							>
+								<Sparkles className="size-4" />
+								Ask AI to fix
+							</Button>
+						) : null}
+					</div>
+				</div>
+			) : null}
+		</div>
+	);
+}
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
new file mode 100644
index 000000000..03df14cf1
--- /dev/null
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+
+import { buildWidgetSandboxDocument } from "#/features/workspaces/components/widget/workspace-widget-sandbox-document";
+
+function loadsKatex(html: string) {
+	return buildWidgetSandboxDocument({
+		html,
+		theme: "light",
+		tokens: { "--background": "oklch(1 0 0)" },
+		origin: "https://app.test",
+	}).includes("katex.min.js");
+}
+
+describe("buildWidgetSandboxDocument", () => {
+	// The only real decision in this module: KaTeX is ~290KB plus fonts, so it
+	// loads only for widgets that contain math. Over-matching costs a cached
+	// fetch; under-matching leaves math unrendered.
+	it("loads KaTeX for every math notation a widget may use", () => {
+		expect(loadsKatex('<span data-type="inline-math" data-latex="x^2"></span>')).toBe(true);
+		expect(loadsKatex("<p>$$E = mc^2$$</p>")).toBe(true);
+		expect(loadsKatex("<p>\\(x\\)</p>")).toBe(true);
+		expect(loadsKatex("<p>Solve $x + 1$ now</p>")).toBe(true);
+		expect(loadsKatex("<script>renderMathInElement(el)</script>")).toBe(true);
+	});
+
+	it("skips KaTeX for a widget with no math, including prices", () => {
+		expect(loadsKatex("<p>Total: $30</p><button>Buy</button>")).toBe(false);
+		expect(loadsKatex("<canvas id='c'></canvas>")).toBe(false);
+	});
+});
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
new file mode 100644
index 000000000..88af90f79
--- /dev/null
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
@@ -0,0 +1,196 @@
+/**
+ * Builds the full HTML document served into the widget sandbox iframe.
+ *
+ * The widget's authored HTML is untrusted (AI-generated), so it runs in an
+ * iframe with `sandbox="allow-scripts"` and NO `allow-same-origin`. That gives
+ * it an opaque origin: it cannot read the parent's cookies, localStorage, or
+ * DOM even though it is served from the same site. We never grant
+ * `allow-same-origin` — combined with `allow-scripts` it would let the frame
+ * remove its own sandbox.
+ *
+ * Two things are composed around the authored HTML:
+ *  - a theme layer: the resolved design tokens (read from the host at build
+ *    time) are injected as CSS variables so widgets look native, plus a `.dark`
+ *    class toggled from the passed theme.
+ *  - an error harness: window `error` / `unhandledrejection` are forwarded to
+ *    the host via postMessage so a crashed widget surfaces an "Ask AI to fix"
+ *    affordance instead of a silent blank frame.
+ */
+
+/** Host → frame messages (theme updates). */
+export const WIDGET_SANDBOX_HOST_SOURCE = "thinkex-widget-host" as const;
+/** Frame → host messages (ready / runtime errors). */
+export const WIDGET_SANDBOX_FRAME_SOURCE = "thinkex-widget-frame" as const;
+
+export type WidgetSandboxFrameMessage =
+	| { source: typeof WIDGET_SANDBOX_FRAME_SOURCE; kind: "ready" }
+	| { source: typeof WIDGET_SANDBOX_FRAME_SOURCE; kind: "error"; message: string };
+
+/**
+ * Semantic design tokens copied from the host into the frame. Kept to a curated
+ * set — enough for widgets to feel native without leaking the entire cascade.
+ */
+export const WIDGET_SANDBOX_TOKENS = [
+	"--background",
+	"--foreground",
+	"--card",
+	"--card-foreground",
+	"--popover",
+	"--popover-foreground",
+	"--primary",
+	"--primary-foreground",
+	"--secondary",
+	"--secondary-foreground",
+	"--muted",
+	"--muted-foreground",
+	"--accent",
+	"--accent-foreground",
+	"--border",
+	"--input",
+	"--ring",
+	"--destructive",
+	"--success",
+	"--warning",
+	"--info",
+	"--radius",
+] as const;
+
+/** Path KaTeX's browser build is served from (see scripts/copy-widget-libs.mjs). */
+const WIDGET_KATEX_BASE_PATH = "/widget-libs/katex";
+
+/** Any supported math notation: chat LaTeX delimiters, document markup, or the API. */
+const WIDGET_MATH_PATTERN = /\$\$|\\\(|\\\[|\$[^$\n]+\$|data-latex|katex|renderMathInElement/;
+
+/**
+ * Restrictive CSP for the frame. Widgets are self-contained HTML: inline
+ * scripts/styles, plus the app's own origin so the bundled KaTeX build can
+ * load. `connect-src 'none'` still blocks every runtime network call.
+ */
+function getWidgetSandboxCsp(origin: string) {
+	return [
+		"default-src 'none'",
+		`style-src 'unsafe-inline' ${origin}`,
+		`script-src 'unsafe-inline' ${origin}`,
+		"img-src data: https:",
+		`font-src data: https: ${origin}`,
+		"media-src data: https:",
+		"connect-src 'none'",
+	].join("; ");
+}
+
+type BuildWidgetSandboxDocumentInput = {
+	html: string;
+	theme: "light" | "dark";
+	/** `--token` → resolved value, read from the host via getComputedStyle. */
+	tokens: Record<string, string>;
+	/** App origin the frame may load bundled libraries from. */
+	origin: string;
+};
+
+export function buildWidgetSandboxDocument({
+	html,
+	theme,
+	tokens,
+	origin,
+}: BuildWidgetSandboxDocumentInput): string {
+	const tokenDeclarations = Object.entries(tokens)
+		.filter(([, value]) => value.trim().length > 0)
+		.map(([name, value]) => `${name}: ${value};`)
+		.join("");
+
+	// Only widgets that actually contain math pay for KaTeX (~290KB plus fonts).
+	// Over-matching just costs a cached fetch; under-matching leaves math
+	// unrendered, so the test is deliberately loose.
+	const katexTags = WIDGET_MATH_PATTERN.test(html)
+		? `<link rel="stylesheet" href="${origin}${WIDGET_KATEX_BASE_PATH}/katex.min.css" />
+<script src="${origin}${WIDGET_KATEX_BASE_PATH}/katex.min.js"></script>
+<script src="${origin}${WIDGET_KATEX_BASE_PATH}/contrib/mhchem.min.js"></script>
+<script src="${origin}${WIDGET_KATEX_BASE_PATH}/contrib/auto-render.min.js"></script>`
+		: "";
+
+	// Widgets are HTML, so math is authored the same way documents author it —
+	// `data-latex` markup — and the unambiguous LaTeX delimiters are accepted too
+	// for when a model reaches for chat habits. Single `$…$` is deliberately NOT
+	// a delimiter: it cannot be told apart from prices, so "$30 an hour … $75 an
+	// hour" would render the text between them as math. Dropping it is safer than
+	// defending it with a currency heuristic, and `$$…$$` still covers real math.
+	// Bad expressions render muted in place rather than throwing, so one
+	// malformed formula never takes the whole widget down.
+	//
+	// The base stylesheet sets a definite height chain and nothing else: widgets
+	// fill the frame with `height: 100%`, and a percentage height only resolves
+	// against a parent with a definite height. Layout beyond that belongs to the
+	// widget — host-side centring or max-widths just strand it in dead space.
+	return `<!doctype html>
+<html lang="en"${theme === "dark" ? ' class="dark"' : ""}>
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta http-equiv="Content-Security-Policy" content="${getWidgetSandboxCsp(origin)}" />
+${katexTags}
+<style>
+:root{${tokenDeclarations}color-scheme:${theme};}
+html,body{margin:0;padding:0;height:100%;background:var(--background);color:var(--foreground);font-family:ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;}
+*,*::before,*::after{box-sizing:border-box;}
+</style>
+</head>
+<body>
+${html}
+<script>
+(function(){
+  var HOST="${WIDGET_SANDBOX_HOST_SOURCE}",FRAME="${WIDGET_SANDBOX_FRAME_SOURCE}";
+  function post(message){ try{ parent.postMessage(message,"*"); }catch(_){} }
+  function report(message){ post({source:FRAME,kind:"error",message:String(message)}); }
+  window.addEventListener("error",function(event){
+    report((event.message||"Error")+(event.error&&event.error.stack?"\\n"+event.error.stack:""));
+  });
+  if(typeof renderMathInElement==="function"){
+    var mathOptions={throwOnError:false,errorColor:"var(--muted-foreground)"};
+    window.renderWidgetMath=function(target){
+      var root=target||document.body;
+      renderMathInElement(root,Object.assign({
+        delimiters:[
+          {left:"$$",right:"$$",display:true},
+          {left:"\\\\[",right:"\\\\]",display:true},
+          {left:"\\\\(",right:"\\\\)",display:false}
+        ]
+      },mathOptions));
+      root.querySelectorAll("[data-latex]").forEach(function(node){
+        if(node.dataset.widgetMathRendered)return;
+        node.dataset.widgetMathRendered="1";
+        katex.render(node.getAttribute("data-latex"),node,Object.assign(
+          {displayMode:node.getAttribute("data-type")==="block-math"},mathOptions));
+      });
+    };
+    try{ window.renderWidgetMath(); }catch(_){}
+  }
+  window.addEventListener("unhandledrejection",function(event){
+    var reason=event.reason;
+    report("Unhandled promise rejection: "+((reason&&reason.stack)||reason));
+  });
+  window.addEventListener("message",function(event){
+    var data=event.data;
+    if(!data||data.source!==HOST)return;
+    if(data.type==="theme"){
+      document.documentElement.classList.toggle("dark",data.theme==="dark");
+      document.documentElement.style.colorScheme=data.theme;
+    }
+  });
+  post({source:FRAME,kind:"ready"});
+})();
+</script>
+</body>
+</html>`;
+}
+
+export function isWidgetSandboxFrameMessage(value: unknown): value is WidgetSandboxFrameMessage {
+	if (typeof value !== "object" || value === null) {
+		return false;
+	}
+
+	const message = value as { source?: unknown; kind?: unknown };
+	return (
+		message.source === WIDGET_SANDBOX_FRAME_SOURCE &&
+		(message.kind === "ready" || message.kind === "error")
+	);
+}
diff --git a/src/features/workspaces/composer/workspace-composer-actions.ts b/src/features/workspaces/composer/workspace-composer-actions.ts
index 10e521f28..8af959b5c 100644
--- a/src/features/workspaces/composer/workspace-composer-actions.ts
+++ b/src/features/workspaces/composer/workspace-composer-actions.ts
@@ -17,6 +17,35 @@ type StageComposerQuoteOptions = {
 	revealChat?: boolean;
 };
 
+type StageComposerPromptOptions = {
+	revealChat?: boolean;
+};
+
+/**
+ * Drop editable text into the AI composer from anywhere in the workspace (e.g.
+ * an item viewer's "Ask AI to fix" button) and, by default, reveal the chat.
+ * The text is staged as an editable draft — it is never auto-sent, so the user
+ * can review or amend it before sending. Reusable across item types.
+ */
+export function stageComposerPrompt(
+	workspaceId: string,
+	text: string,
+	options: StageComposerPromptOptions = {},
+) {
+	const { revealChat = true } = options;
+
+	const trimmed = text.trim();
+	if (!trimmed) {
+		return;
+	}
+
+	useWorkspaceAiComposerDraftStore.getState().setPrompt(workspaceId, trimmed);
+
+	if (revealChat) {
+		useWorkspaceUiStore.getState().setChatSurfaceMode(workspaceId, "docked");
+	}
+}
+
 export function stageComposerQuote(
 	workspaceId: string,
 	quote: WorkspaceSelectedQuote,
diff --git a/src/features/workspaces/content/workspace-content-contract.test.ts b/src/features/workspaces/content/workspace-content-contract.test.ts
index ea4918c7b..5ffc057fb 100644
--- a/src/features/workspaces/content/workspace-content-contract.test.ts
+++ b/src/features/workspaces/content/workspace-content-contract.test.ts
@@ -14,6 +14,7 @@ describe("workspace read tool schemas", () => {
 					{ mode: "start", path: "/Notes" },
 					{ mode: "pages", path: "/Book.pdf", range: "1-3" },
 					{ cursor: "opaque", mode: "continue", path: "/Notes" },
+					{ mode: "block", path: "/Notes", ref: "b_abcdefghijkl.r_0123456789" },
 				],
 			}).success,
 		).toBe(true);
@@ -39,6 +40,7 @@ describe("workspace read tool schemas", () => {
 							{ additionalProperties: false, required: ["path", "mode"] },
 							{ additionalProperties: false, required: ["path", "mode", "range"] },
 							{ additionalProperties: false, required: ["path", "cursor", "mode"] },
+							{ additionalProperties: false, required: ["path", "mode", "ref"] },
 						],
 					},
 				},
diff --git a/src/features/workspaces/content/workspace-content-contract.ts b/src/features/workspaces/content/workspace-content-contract.ts
index 2ae8a4d65..1d0917a1e 100644
--- a/src/features/workspaces/content/workspace-content-contract.ts
+++ b/src/features/workspaces/content/workspace-content-contract.ts
@@ -19,6 +19,7 @@ const readWorkspaceItemsFailureCodes = [
 	"path_not_absolute",
 	"path_not_found",
 	"projection_failed",
+	"ref_not_found",
 	"unsupported_item_type",
 ] as const;
 
@@ -50,6 +51,16 @@ const workspaceContentReadRequestSchema = z.union([
 		cursor: z.string().min(1).max(4_096).describe("Opaque cursor returned by a previous read."),
 		mode: z.literal("continue"),
 	}),
+	z.strictObject({
+		...workspaceContentReadRequestBase,
+		mode: z.literal("block"),
+		ref: z
+			.string()
+			.min(1)
+			.describe(
+				"data-ref of one block from an earlier read of this document, returned in full. Reads elide a widget's source, so this is how to fetch it before editing.",
+			),
+	}),
 ]);
 
 export const workspaceReadItemsInputSchema = z.object({
@@ -134,6 +145,16 @@ const workspaceContentReadResultSchema = z.union([
 		status: z.literal("pending"),
 		type: z.literal("file"),
 	}),
+	z.object({
+		content: z.string(),
+		format: z.literal("html"),
+		itemId: z.string().min(1),
+		path: workspacePathSchema,
+		ref: z.string().min(1),
+		relations: workspaceReadRelationsSchema.optional(),
+		status: z.literal("ready"),
+		type: z.literal("block"),
+	}),
 	z.object({
 		code: z.enum(readWorkspaceItemsFailureCodes),
 		message: z.string().optional().describe("Why extraction failed, when known."),
diff --git a/src/features/workspaces/content/workspace-content-reader.test.ts b/src/features/workspaces/content/workspace-content-reader.test.ts
index 17c1eaf06..d1f27c72b 100644
--- a/src/features/workspaces/content/workspace-content-reader.test.ts
+++ b/src/features/workspaces/content/workspace-content-reader.test.ts
@@ -5,6 +5,9 @@ import type { WorkspaceContentReadRequest } from "#/features/workspaces/content/
 import {
 	ensureTiptapDocumentAiRefs,
 	parseDocumentAiHtml,
+	parseDocumentAiTargetRef,
+	readTiptapNodeAiRef,
+	serializeTiptapNodeToPlainAiHtml,
 } from "#/features/workspaces/documents/document-ai-html";
 import { readDocumentHtmlChunk } from "#/features/workspaces/documents/document-html-chunk";
 import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
@@ -50,6 +53,7 @@ describe("WorkspaceContentReader", () => {
 		if (
 			!first ||
 			first.status !== "ready" ||
+			first.type !== "document" ||
 			first.location.kind !== "blocks" ||
 			!first.nextCursor
 		) {
@@ -63,7 +67,12 @@ describe("WorkspaceContentReader", () => {
 			status: "ready",
 			type: "document",
 		});
-		if (!second || second.status !== "ready" || second.location.kind !== "blocks") {
+		if (
+			!second ||
+			second.status !== "ready" ||
+			second.type !== "document" ||
+			second.location.kind !== "blocks"
+		) {
 			throw new Error("Expected a continued document chunk.");
 		}
 		expect(second.location.startBlock).toBeGreaterThan(first.location.startBlock);
@@ -80,7 +89,7 @@ describe("WorkspaceContentReader", () => {
 			kernel: createKernel(),
 		});
 		const [first] = await read([{ mode: "start", path: "/Notes" }]);
-		if (!first || first.status !== "ready" || !first.nextCursor) {
+		if (!first || first.status !== "ready" || first.type !== "document" || !first.nextCursor) {
 			throw new Error("Expected a continuation cursor.");
 		}
 
@@ -103,7 +112,7 @@ describe("WorkspaceContentReader", () => {
 		for (;;) {
 			const [result] = await read([request]);
 			expect(result).toMatchObject({ status: "ready", type: "document" });
-			if (!result || result.status !== "ready") {
+			if (!result || result.status !== "ready" || result.type !== "document") {
 				throw new Error("Expected a document chunk.");
 			}
 			contents.push(result.content);
@@ -185,6 +194,37 @@ describe("WorkspaceContentReader", () => {
 		);
 	});
 
+	it("returns one block in full, including a widget's elided source", async () => {
+		const source = "<div>Interactive</div>";
+		// One session across both reads: a fresh one would mint new refs.
+		const session = createDocumentSession({
+			html: `<p>Before</p><div data-type="widget" title="Sine">${source.replaceAll("<", "&lt;")}</div>`,
+			revision: "revision-1",
+		});
+		const read = createReader({
+			bucket: {} as R2Bucket,
+			getDocumentSession: () => session,
+			kernel: createKernel(),
+		});
+
+		const [chunk] = await read([{ mode: "start", path: "/Notes" }]);
+		if (!chunk || chunk.status !== "ready" || chunk.type !== "document") {
+			throw new Error("Expected a document chunk.");
+		}
+		// The chunk carries the placeholder, not the source.
+		expect(chunk.content).not.toContain("Interactive");
+		const widgetTag = /<div[^>]*data-type="widget"[^>]*>/.exec(chunk.content)?.[0] ?? "";
+		const ref = /data-ref="([^"]+)"/.exec(widgetTag)?.[1];
+		expect(ref).toBeTruthy();
+
+		const [block] = await read([{ mode: "block", path: "/Notes", ref: ref as string }]);
+		expect(block).toMatchObject({ status: "ready", type: "block", ref });
+		if (!block || block.status !== "ready" || block.type !== "block") {
+			throw new Error("Expected a block read.");
+		}
+		expect(block.content).toContain("Interactive");
+	});
+
 	it("keeps one ordered result for every requested path", async () => {
 		const kernel = createKernel();
 		kernel.resolvePaths = vi.fn(
@@ -228,6 +268,18 @@ function createDocumentSession(input: { html: string; revision: string }) {
 				? { ...chunk, revision: input.revision, status: "ready" as const }
 				: { status: "invalid_offset" as const };
 		}),
+		readBlock: vi.fn(async ({ ref }: { ref: string }) => {
+			const stableRef = parseDocumentAiTargetRef(ref) ?? ref;
+			let found: ReturnType<typeof documentNode.child> | null = null;
+			documentNode.forEach((node) => {
+				if (!found && readTiptapNodeAiRef(node) === stableRef) {
+					found = node;
+				}
+			});
+			return found
+				? { content: serializeTiptapNodeToPlainAiHtml(found), status: "ready" as const }
+				: { status: "ref_not_found" as const };
+		}),
 	};
 }
 
diff --git a/src/features/workspaces/content/workspace-content-reader.ts b/src/features/workspaces/content/workspace-content-reader.ts
index 4d172c8c1..7f91a66b5 100644
--- a/src/features/workspaces/content/workspace-content-reader.ts
+++ b/src/features/workspaces/content/workspace-content-reader.ts
@@ -25,6 +25,9 @@ const maxWorkspaceContentBatchBytes = 2 * 1024 * 1024 + 64 * 1024;
 
 interface DocumentContentReader {
 	readHtmlChunk(input: DocumentHtmlChunkReadInput): Promise<DocumentHtmlChunkReadResult>;
+	readBlock(input: {
+		ref: string;
+	}): Promise<{ content: string; status: "ready" } | { status: "ref_not_found" }>;
 }
 
 interface PendingReadyResult {
@@ -130,7 +133,7 @@ async function readWorkspaceItem(input: {
 	request: WorkspaceContentReadRequest;
 }): Promise<WorkspaceContentReadResult> {
 	if (input.item.type === "document") {
-		return readDocument(input);
+		return input.request.mode === "block" ? readDocumentBlock(input) : readDocument(input);
 	}
 	if (input.item.type === "file") {
 		return readFile(input);
@@ -138,6 +141,40 @@ async function readWorkspaceItem(input: {
 	return { code: "unsupported_item_type", path: input.path, status: "failed" };
 }
 
+/**
+ * One block of a document in full.
+ *
+ * Reads elide a widget's source so it does not crowd the prose out of a chunk;
+ * this is how the assistant fetches that source before editing it. It works for
+ * any block, so a long table or code block can be pulled up on its own too.
+ */
+async function readDocumentBlock(input: {
+	getDocumentSession: (itemId: string) => DocumentContentReader | Promise<DocumentContentReader>;
+	item: WorkspaceItemSummary;
+	path: string;
+	request: WorkspaceContentReadRequest;
+}): Promise<WorkspaceContentReadResult> {
+	if (input.request.mode !== "block") {
+		return { code: "invalid_selection", path: input.path, status: "failed" };
+	}
+
+	const documentSession = await input.getDocumentSession(input.item.id);
+	const block = await documentSession.readBlock({ ref: input.request.ref });
+	if (block.status !== "ready") {
+		return { code: "ref_not_found", path: input.path, status: "failed" };
+	}
+
+	return {
+		content: block.content,
+		format: "html",
+		itemId: input.item.id,
+		path: input.path,
+		ref: input.request.ref,
+		status: "ready",
+		type: "block",
+	};
+}
+
 async function readDocument(input: {
 	getDocumentSession: (itemId: string) => DocumentContentReader | Promise<DocumentContentReader>;
 	item: WorkspaceItemSummary;
diff --git a/src/features/workspaces/content/workspace-read-references.ts b/src/features/workspaces/content/workspace-read-references.ts
index 3478ec4bb..8ce627d0e 100644
--- a/src/features/workspaces/content/workspace-read-references.ts
+++ b/src/features/workspaces/content/workspace-read-references.ts
@@ -29,7 +29,7 @@ export function createWorkspaceReadReferences(
 			continue;
 		}
 
-		if (result.type === "document" || result.assetKind !== "pdf") {
+		if (result.type !== "file" || result.assetKind !== "pdf") {
 			locations.push({
 				itemId: result.itemId,
 				kind: "item",
@@ -132,7 +132,7 @@ export function createWorkspaceReadItemsModelOutput(output: WorkspaceReadItemsOu
 				return result;
 			}
 
-			if (result.type === "document" || result.assetKind !== "pdf") {
+			if (result.type !== "file" || result.assetKind !== "pdf") {
 				const ref = refsByLocation.get(
 					getWorkspaceLocationKey({
 						itemId: result.itemId,
diff --git a/src/features/workspaces/documents/document-ai-edits.test.ts b/src/features/workspaces/documents/document-ai-edits.test.ts
index 7d6bae44c..3210ad108 100644
--- a/src/features/workspaces/documents/document-ai-edits.test.ts
+++ b/src/features/workspaces/documents/document-ai-edits.test.ts
@@ -61,10 +61,10 @@ describe("document AI edits", () => {
 		const document = createDocument("<p>Before</p>");
 		const originalRef = stableRef(await getRef(document, "p"));
 		const rewritten = await applyDocumentAiEdits(document, [
-			{ html: "<h1>New</h1><p>Document</p>", op: "replace_all" },
+			{ html: "<h1>New</h1><p>Document</p>", op: "overwrite" },
 		]);
 		const noOp = await applyDocumentAiEdits(rewritten.document, [
-			{ html: "<h1>New</h1><p>Document</p>", op: "replace_all" },
+			{ html: "<h1>New</h1><p>Document</p>", op: "overwrite" },
 		]);
 
 		expect(rewritten).toMatchObject({ applied: 1, failed: 0, status: "applied" });
@@ -80,7 +80,7 @@ describe("document AI edits", () => {
 	it("matches the editor's trailing paragraph after a final structural block", async () => {
 		const document = createDocument("<p>Before</p>");
 		const rewritten = await applyDocumentAiEdits(document, [
-			{ html: "<ul><li>After</li></ul>", op: "replace_all" },
+			{ html: "<ul><li>After</li></ul>", op: "overwrite" },
 		]);
 
 		expect(rewritten.document.content?.at(-1)).toMatchObject({ type: "paragraph" });
diff --git a/src/features/workspaces/documents/document-ai-edits.ts b/src/features/workspaces/documents/document-ai-edits.ts
index 7202094a4..38832e2d2 100644
--- a/src/features/workspaces/documents/document-ai-edits.ts
+++ b/src/features/workspaces/documents/document-ai-edits.ts
@@ -7,6 +7,7 @@ import {
 	ensureProseMirrorDocumentAiRefs,
 	parseDocumentAiHtml,
 	parseDocumentAiTargetRef,
+	serializeTiptapNodeToPlainAiHtml,
 	readTiptapNodeAiRef,
 	withTiptapNodeAiRef,
 } from "#/features/workspaces/documents/document-ai-html";
@@ -40,11 +41,26 @@ export const documentAiEditSchema = z.union([
 	}),
 	z.strictObject({
 		html: documentAiHtmlSchema,
-		op: z.literal("replace_all"),
+		op: z.literal("overwrite"),
+	}),
+	z.strictObject({
+		find: z
+			.string()
+			.min(1)
+			.describe(
+				"Exact text to replace inside the target block, copied from a read. It must appear exactly once in that block; if it matches more than once the edit fails instead of replacing every occurrence.",
+			),
+		op: z.literal("replace_text"),
+		ref: documentAiRefSchema,
+		replace: z.string().describe("Replacement text. May be empty to delete the matched text."),
 	}),
 ]);
 
 export const documentAiEditFailureCodes = [
+	"edit_not_found",
+	// Deliberately a failure rather than a silent replace-all: a model retargeting
+	// one of three identical buttons would otherwise change all three, unnoticed.
+	"edit_not_unique",
 	"invalid_html",
 	"no_change",
 	"ref_not_found",
@@ -75,7 +91,7 @@ export async function applyDocumentAiEdits(
 	// rejecting the same ref in a later call after a human or agent changed it.
 	const requestedStableRefs = new Set(
 		edits.flatMap((edit) => {
-			if (edit.op === "replace_all") {
+			if (edit.op === "overwrite") {
 				return [];
 			}
 			const stableRef = parseDocumentAiTargetRef(edit.ref);
@@ -101,7 +117,7 @@ export async function applyDocumentAiEdits(
 
 	for (const [index, edit] of edits.entries()) {
 		let stableRef: string | undefined;
-		if (edit.op !== "replace_all") {
+		if (edit.op !== "overwrite") {
 			const parsedRef = parseDocumentAiTargetRef(edit.ref);
 			if (!parsedRef || !targetRefByStableRef.has(parsedRef)) {
 				failures.push({ code: "ref_not_found", index });
@@ -195,8 +211,8 @@ function applyDocumentAiEdit(
 ):
 	| { code: DocumentAiEditFailureCode; detail?: string; status: "failed" }
 	| { document: ProseMirrorNode; status: "applied" } {
-	if (edit.op === "replace_all") {
-		const parsed = parseEditHtml(edit.html);
+	if (edit.op === "overwrite") {
+		const parsed = parseEditHtml(edit.html, document);
 		if (!parsed.children) {
 			return { code: "invalid_html", detail: parsed.detail, status: "failed" };
 		}
@@ -218,8 +234,43 @@ function applyDocumentAiEdit(
 	const children = getDocumentChildren(document);
 	if (edit.op === "delete") {
 		children.splice(targetIndex, 1);
+	} else if (edit.op === "replace_text") {
+		const target = document.child(targetIndex);
+		const replaced = replaceUniqueText(readBlockText(target), edit.find, edit.replace);
+		if (!replaced.ok) {
+			return { code: replaced.code, detail: replaced.detail, status: "failed" };
+		}
+
+		if (target.type.name === "widget") {
+			// A widget holds raw source, so the replacement is written straight back.
+			children.splice(
+				targetIndex,
+				1,
+				target.type.create(
+					target.attrs,
+					replaced.text ? getTiptapDocumentSchema().text(replaced.text) : undefined,
+					target.marks,
+				),
+			);
+		} else {
+			// Prose is markup, so the edited HTML is re-parsed and refitted to the
+			// schema exactly as a `replace` would be.
+			const parsed = parseEditHtml(replaced.text, document);
+			if (!parsed.children) {
+				return { code: "invalid_html", detail: parsed.detail, status: "failed" };
+			}
+			const targetRef = readTiptapNodeAiRef(target);
+			const firstNode = parsed.children[0];
+			children.splice(
+				targetIndex,
+				1,
+				...(targetRef && firstNode
+					? [withTiptapNodeAiRef(firstNode, targetRef), ...parsed.children.slice(1)]
+					: parsed.children),
+			);
+		}
 	} else {
-		const parsed = parseEditHtml(edit.html);
+		const parsed = parseEditHtml(edit.html, document);
 		if (!parsed.children) {
 			return { code: "invalid_html", detail: parsed.detail, status: "failed" };
 		}
@@ -251,11 +302,80 @@ function applyDocumentAiEdit(
 		: { document: next, status: "applied" };
 }
 
-function parseEditHtml(html: string) {
+/**
+ * Source for a widget the model sent back empty, looked up in the document as it
+ * stands. Reads elide widget source, so any HTML that came from a read carries
+ * placeholders — a `overwrite` echoing them back would otherwise blank every
+ * widget in the document.
+ */
+function createWidgetSourceResolver(document: ProseMirrorNode) {
+	return (ref: string) => {
+		const blockRef = parseDocumentAiTargetRef(ref) ?? ref;
+		let source: string | null = null;
+		document.forEach((node) => {
+			if (
+				source === null &&
+				node.type.name === "widget" &&
+				readTiptapNodeAiRef(node) === blockRef
+			) {
+				source = node.textContent;
+			}
+		});
+		return source;
+	};
+}
+
+/** The text `replace_text` matches against: raw source for a widget, markup otherwise. */
+function readBlockText(node: ProseMirrorNode): string {
+	if (node.type.name === "widget") {
+		return node.textContent;
+	}
+	// Serialized without its ref, and the model's `find` is stripped the same way,
+	// so text copied from a read matches whether or not it kept the data-ref.
+	return serializeTiptapNodeToPlainAiHtml(withTiptapNodeAiRef(node, null));
+}
+
+const DATA_REF_ATTRIBUTE = /\s+data-ref="[^"]*"/g;
+
+/**
+ * Replaces a single unique occurrence, or explains why it could not.
+ *
+ * Line endings are normalised first: a model reproducing text with different
+ * newlines otherwise gets an unexplained miss. A non-unique match fails with its
+ * count so the next attempt can add surrounding context instead of guessing.
+ */
+function replaceUniqueText(
+	source: string,
+	find: string,
+	replace: string,
+):
+	| { ok: true; text: string }
+	| { ok: false; code: "edit_not_found" | "edit_not_unique"; detail: string } {
+	const haystack = source.replaceAll("\r\n", "\n").replace(DATA_REF_ATTRIBUTE, "");
+	const needle = find.replaceAll("\r\n", "\n").replace(DATA_REF_ATTRIBUTE, "");
+	const matches = haystack.split(needle).length - 1;
+
+	if (matches === 0) {
+		return { ok: false, code: "edit_not_found", detail: `No match for: ${needle.slice(0, 80)}` };
+	}
+	if (matches > 1) {
+		return {
+			ok: false,
+			code: "edit_not_unique",
+			detail: `Found ${matches} matches; include more surrounding text so it matches once.`,
+		};
+	}
+
+	return { ok: true, text: haystack.replace(needle, replace) };
+}
+
+function parseEditHtml(html: string, document: ProseMirrorNode) {
 	try {
 		return {
 			children: getDocumentChildren(
-				getTiptapDocumentSchema().nodeFromJSON(parseDocumentAiHtml(html)),
+				getTiptapDocumentSchema().nodeFromJSON(
+					parseDocumentAiHtml(html, { resolveWidgetSource: createWidgetSourceResolver(document) }),
+				),
 			),
 		};
 	} catch (error) {
diff --git a/src/features/workspaces/documents/document-ai-html.test.ts b/src/features/workspaces/documents/document-ai-html.test.ts
index 03d833a9e..61c7cc11b 100644
--- a/src/features/workspaces/documents/document-ai-html.test.ts
+++ b/src/features/workspaces/documents/document-ai-html.test.ts
@@ -23,6 +23,20 @@ describe("document AI HTML", () => {
 		expect(parseDocumentAiHtml(html)).toMatchObject({ type: "doc" });
 	});
 
+	it("converts sub/sup into inline math instead of failing the write", async () => {
+		// Models write `CH<sub>4</sub>` in prose by habit — evals showed it even
+		// with an explicit instruction not to. This used to throw and lose the
+		// entire document rather than the two characters it could not represent.
+		const html = await serializeTiptapDocumentToAiHtml(
+			ensureTiptapDocumentAiRefs(parseDocumentAiHtml("<p>CH<sub>4</sub> and x<sup>2</sup></p>"))
+				.document,
+		);
+
+		expect(html).toContain('data-latex="{}_{4}"');
+		expect(html).toContain('data-latex="{}^{2}"');
+		expect(html).not.toContain("<sub>");
+	});
+
 	it("ignores refs supplied in model-authored HTML", async () => {
 		const html = await serializeTiptapDocumentToAiHtml(
 			ensureTiptapDocumentAiRefs(parseDocumentAiHtml('<p data-ref="b_modelchosen1">Hello</p>'))
@@ -60,12 +74,62 @@ describe("document AI HTML", () => {
 		expect(html).toContain(">Unsafe</p>");
 	});
 
-	it("rejects elements outside the supported document schema", () => {
-		expect(() => parseDocumentAiHtml("<figure><p>Unsupported</p></figure>")).toThrow(
-			DocumentAiHtmlError,
+	it("degrades unsupported markup instead of losing the whole write", async () => {
+		// Rejecting cost the entire document to save formatting we can flatten:
+		// a probe of realistic model markup found 12 of 20 snippets refused.
+		const html = await serializeTiptapDocumentToAiHtml(
+			ensureTiptapDocumentAiRefs(
+				parseDocumentAiHtml(
+					'<figure><p>Kept</p></figure><div class="callout"><h5>Heading</h5></div><dl><dt>Force</dt><dd>Mass times acceleration</dd></dl><p>An <span class="hl">inline</span> span</p>',
+				),
+			).document,
 		);
-		expect(() => parseDocumentAiHtml("<div>Not a math or task wrapper</div>")).toThrow(
+
+		expect(html).toContain(">Kept</p>");
+		// h5 has no schema level, so it lands on the nearest real heading.
+		expect(html).toContain("<h4");
+		expect(html).toContain(">Heading</h4>");
+		expect(html).toContain(">Force</p>");
+		expect(html).toContain(">Mass times acceleration</p>");
+		expect(html).toContain(">An inline span</p>");
+		expect(html).not.toContain("<figure");
+		expect(html).not.toContain("<dl");
+	});
+
+	it("still rejects Markdown sent as document content", () => {
+		// The one thing degradation must not paper over: plain text at the top
+		// level means the model sent Markdown, which would flatten into a single
+		// paragraph of literal source.
+		expect(() => parseDocumentAiHtml("# Heading\n\nSome **bold** text")).toThrow(
 			DocumentAiHtmlError,
 		);
 	});
+
+	it("elides widget source for the model but keeps the ref", async () => {
+		const source = '<style>.a{color:red}</style><div class="a">Hi</div>';
+		const html = await serializeTiptapDocumentToAiHtml(
+			ensureTiptapDocumentAiRefs(
+				parseDocumentAiHtml(
+					`<div data-type="widget" title="Sine">${source.replaceAll("<", "&lt;")}</div>`,
+				),
+			).document,
+		);
+
+		// A widget runs to kilobytes; inlining it in every read crowds out the prose.
+		expect(html).not.toContain("color:red");
+		expect(html).toContain('data-type="widget"');
+		expect(html).toMatch(/data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"/);
+	});
+
+	it("restores an elided widget instead of blanking it", () => {
+		// The model reads a widget as an empty placeholder, so an overwrite that
+		// echoes the read back would otherwise destroy the source permanently.
+		const source = '<div class="a">Hi</div>';
+		const restored = parseDocumentAiHtml(
+			'<div data-type="widget" data-ref="b_abcdefghijkl.r_1234567890"></div>',
+			{ resolveWidgetSource: (ref) => (ref.startsWith("b_abcdefghijkl") ? source : null) },
+		);
+
+		expect(JSON.stringify(restored)).toContain("Hi");
+	});
 });
diff --git a/src/features/workspaces/documents/document-ai-html.ts b/src/features/workspaces/documents/document-ai-html.ts
index f6734e02d..2d9643630 100644
--- a/src/features/workspaces/documents/document-ai-html.ts
+++ b/src/features/workspaces/documents/document-ai-html.ts
@@ -16,58 +16,34 @@ import { sha256Base64UrlText } from "#/lib/binary";
 const TEXT_NODE = 3;
 const documentAiRefPattern = /^b_[A-Za-z0-9_-]{12}$/;
 const documentAiTargetRefPattern = /^(b_[A-Za-z0-9_-]{12})\.r_[A-Za-z0-9_-]{10}$/;
-const supportedDocumentAiHtmlTags = new Set([
-	"a",
-	"b",
-	"blockquote",
-	"br",
-	"citation",
-	"code",
-	"col",
-	"colgroup",
-	"del",
-	"div",
-	"em",
-	"h1",
-	"h2",
-	"h3",
-	"h4",
-	"hr",
-	"i",
-	"input",
-	"label",
-	"li",
-	"mark",
-	"ol",
-	"p",
-	"pre",
-	"s",
-	"span",
-	"strike",
-	"strong",
-	"table",
-	"tbody",
-	"td",
-	"tfoot",
-	"th",
-	"thead",
-	"tr",
-	"u",
-	"ul",
-]);
-
 export class DocumentAiHtmlError extends Error {}
 
-export function parseDocumentAiHtml(html: string): TiptapDocumentJson {
+export interface ParseDocumentAiHtmlOptions {
+	/**
+	 * Source for a widget the model sent back empty. Reads elide widget source,
+	 * so HTML that came from a read carries placeholders — without this they
+	 * would be written back as empty widgets, silently destroying the source.
+	 */
+	resolveWidgetSource?: (ref: string) => string | null;
+}
+
+export function parseDocumentAiHtml(
+	html: string,
+	options: ParseDocumentAiHtmlOptions = {},
+): TiptapDocumentJson {
 	const htmlDocument = createHtmlDocument();
 	htmlDocument.body.innerHTML = html;
 
+	restoreElidedWidgets(htmlDocument, options.resolveWidgetSource);
+
 	// A citation the operation could not resolve to a real item cannot navigate
 	// anywhere, so it becomes its own label rather than failing the write.
 	for (const element of htmlDocument.body.querySelectorAll("citation:not([data-item-id])")) {
 		element.replaceWith(htmlDocument.createTextNode(element.textContent ?? ""));
 	}
 
+	rewriteLossyElements(htmlDocument);
+
 	validateDocumentAiHtml(htmlDocument.body);
 
 	for (const element of htmlDocument.body.querySelectorAll("[data-ref]")) {
@@ -99,9 +75,25 @@ export async function serializeTiptapDocumentToAiHtml(document: TiptapDocumentJs
 }
 
 export async function serializeTiptapNodeToAiHtml(node: ProseMirrorNode) {
-	return serializeTiptapFragmentToAiHtml(
-		Fragment.from(withTiptapNodeAiRef(node, await createDocumentAiTargetRef(node))),
-	);
+	// The ref is hashed from the full node, so a widget whose source changed
+	// still invalidates it — only the serialized form is elided.
+	const withRef = withTiptapNodeAiRef(node, await createDocumentAiTargetRef(node));
+	return serializeTiptapFragmentToAiHtml(Fragment.from(elideWidgetSource(withRef)));
+}
+
+/**
+ * Replaces a widget's source with nothing for the model's benefit.
+ *
+ * A widget runs to kilobytes of markup and script. Inlining that in every read
+ * would crowd out the prose the model actually needs — a handful of widgets
+ * would fill a whole chunk. The placeholder keeps the ref and title, which is
+ * enough to decide whether to read it in full.
+ */
+function elideWidgetSource(node: ProseMirrorNode): ProseMirrorNode {
+	if (node.type.name !== "widget") {
+		return node;
+	}
+	return node.type.create(node.attrs, undefined, node.marks);
 }
 
 export async function createDocumentAiTargetRef(node: ProseMirrorNode) {
@@ -180,6 +172,11 @@ export function withTiptapNodeAiRef(node: ProseMirrorNode, ref: string | null) {
 	);
 }
 
+/** One block as HTML, synchronously and without a ref — for text matching. */
+export function serializeTiptapNodeToPlainAiHtml(node: ProseMirrorNode) {
+	return serializeTiptapFragmentToAiHtml(Fragment.from(node));
+}
+
 function serializeTiptapFragmentToAiHtml(fragment: Fragment) {
 	const htmlDocument = createHtmlDocument();
 	const container = htmlDocument.createElement("div");
@@ -191,6 +188,70 @@ function serializeTiptapFragmentToAiHtml(fragment: Fragment) {
 	return container.innerHTML;
 }
 
+/**
+ * Fills an elided widget back in from the live document before parsing.
+ *
+ * The model reads a widget as `<div data-type="widget" data-ref="...">` with no
+ * body. Sending that straight back — which `overwrite` does by design — would
+ * otherwise replace real source with an empty node.
+ */
+function restoreElidedWidgets(
+	htmlDocument: Document,
+	resolveWidgetSource: ((ref: string) => string | null) | undefined,
+) {
+	for (const element of htmlDocument.body.querySelectorAll('div[data-type="widget"]')) {
+		if (element.textContent?.trim()) {
+			continue;
+		}
+		const ref = element.getAttribute("data-ref");
+		const source = ref && resolveWidgetSource ? resolveWidgetSource(ref) : null;
+		if (source) {
+			element.textContent = source;
+		}
+	}
+}
+
+/**
+ * Rescues the two tags ProseMirror parses lossily.
+ *
+ * Everything else outside the schema is already handled by the parser: unknown
+ * wrappers are skipped with their children kept, and `<script>`/`<style>` text
+ * never reaches the document. These two lose meaning instead:
+ *  - `<h5>`/`<h6>` fall all the way to a paragraph, so the heading disappears;
+ *    the schema stops at 4, so 4 is where they belong.
+ *  - `<sub>`/`<sup>` flatten to bare text (`CH<sub>4</sub>` becomes `CH4`), so
+ *    they become inline math instead. `{}_{4}` is the KaTeX form for a
+ *    subscript with no base, which is what the tag means on its own.
+ *
+ * Models write both by habit — evals showed `CH<sub>4</sub>` surviving an
+ * explicit instruction not to use it.
+ */
+function rewriteLossyElements(htmlDocument: Document) {
+	for (const element of htmlDocument.body.querySelectorAll("h5, h6")) {
+		const heading = htmlDocument.createElement("h4");
+		for (const child of Array.from(element.childNodes)) {
+			heading.appendChild(child);
+		}
+		element.replaceWith(heading);
+	}
+
+	for (const element of htmlDocument.body.querySelectorAll("sub, sup")) {
+		const latex = element.textContent?.trim();
+		if (!latex) {
+			element.remove();
+			continue;
+		}
+
+		const math = htmlDocument.createElement("span");
+		math.setAttribute("data-type", "inline-math");
+		math.setAttribute(
+			"data-latex",
+			`{}${element.tagName.toLowerCase() === "sub" ? "_" : "^"}{${latex}}`,
+		);
+		element.replaceWith(math);
+	}
+}
+
 function validateDocumentAiHtml(root: HTMLElement) {
 	// Text sitting at the top level means this is not HTML at all — Markdown,
 	// most often, which a model reaches for by habit. ProseMirror would take it
@@ -203,33 +264,6 @@ function validateDocumentAiHtml(root: HTMLElement) {
 			);
 		}
 	}
-
-	for (const element of root.querySelectorAll("*")) {
-		const tagName = element.tagName.toLowerCase();
-		if (!supportedDocumentAiHtmlTags.has(tagName) || !isSupportedSpecialElement(element)) {
-			throw new DocumentAiHtmlError(`Unsupported document HTML element: <${tagName}>.`);
-		}
-	}
-}
-
-function isSupportedSpecialElement(element: Element) {
-	const tagName = element.tagName.toLowerCase();
-	if (tagName === "div") {
-		return (
-			element.getAttribute("data-type") === "block-math" ||
-			element.parentElement?.getAttribute("data-type") === "taskItem"
-		);
-	}
-	if (tagName === "span") {
-		return (
-			element.getAttribute("data-type") === "inline-math" ||
-			element.parentElement?.tagName.toLowerCase() === "label"
-		);
-	}
-	if (tagName === "label" || tagName === "input") {
-		return Boolean(element.closest('li[data-type="taskItem"]'));
-	}
-	return true;
 }
 
 /** Short refs the assistant cited, for the caller to resolve to locations. */
diff --git a/src/features/workspaces/documents/document-preview-text.test.ts b/src/features/workspaces/documents/document-preview-text.test.ts
new file mode 100644
index 000000000..75c8cc8d1
--- /dev/null
+++ b/src/features/workspaces/documents/document-preview-text.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+
+import { parseDocumentAiHtml } from "#/features/workspaces/documents/document-ai-html";
+import { serializeTiptapDocumentToMarkdown } from "#/features/workspaces/documents/document-markdown";
+import { extractDocumentPreviewText } from "#/features/workspaces/documents/document-preview-text";
+import { stringifyTiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
+
+const widgetSource = "<script>alert(1)</script><div>SOURCE</div>";
+
+function createDocumentWithWidget(title: string) {
+	return stringifyTiptapDocumentJson(
+		parseDocumentAiHtml(
+			`<p>Waves intro</p><div data-type="widget" title="${title}">${widgetSource.replaceAll("<", "&lt;")}</div><p>After</p>`,
+		),
+	);
+}
+
+describe("document preview text", () => {
+	it("previews a widget by title rather than by its source", () => {
+		expect(extractDocumentPreviewText(createDocumentWithWidget("Sine explorer"))).toBe(
+			"Waves intro\nSine explorer\nAfter",
+		);
+	});
+
+	// Search indexes the markdown projection, so keeping widgets out of it is
+	// what keeps their source out of the full-text index.
+	it("keeps widget source out of the markdown search projection", () => {
+		const markdown = serializeTiptapDocumentToMarkdown(
+			parseDocumentAiHtml(
+				`<p>Waves intro</p><div data-type="widget" title="Sine explorer">${widgetSource.replaceAll("<", "&lt;")}</div>`,
+			),
+		);
+
+		expect(markdown).toContain("Waves intro");
+		expect(markdown).not.toContain("SOURCE");
+		expect(markdown).not.toContain("Sine explorer");
+	});
+});
diff --git a/src/features/workspaces/documents/document-preview-text.ts b/src/features/workspaces/documents/document-preview-text.ts
index 105122a21..f7086921a 100644
--- a/src/features/workspaces/documents/document-preview-text.ts
+++ b/src/features/workspaces/documents/document-preview-text.ts
@@ -12,6 +12,10 @@ export const WORKSPACE_DOCUMENT_PREVIEW_TEXT_MAX_LENGTH = 500;
 const documentPreviewTextSerializers: Record<string, TextSerializer> = {
 	blockMath: ({ node }) => getMathLatex(node.attrs.latex),
 	inlineMath: ({ node }) => getMathLatex(node.attrs.latex),
+	// A widget holds its source as text content, which is markup rather than
+	// prose. Preview its title so a widget-only document still reads as
+	// something, and never its source.
+	widget: ({ node }) => (typeof node.attrs.title === "string" ? node.attrs.title : ""),
 };
 
 export function getWorkspaceDocumentPreviewText(item: Pick<WorkspaceItemSummary, "metadataJson">) {
diff --git a/src/features/workspaces/documents/document-session.ts b/src/features/workspaces/documents/document-session.ts
index 88ae52c04..ed51245a9 100644
--- a/src/features/workspaces/documents/document-session.ts
+++ b/src/features/workspaces/documents/document-session.ts
@@ -14,7 +14,14 @@ import {
 	type DocumentAiEditFailureCode,
 	type DocumentAiEditResultStatus,
 } from "#/features/workspaces/documents/document-ai-edits";
-import { ensureProseMirrorDocumentAiRefs } from "#/features/workspaces/documents/document-ai-html";
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+
+import {
+	ensureProseMirrorDocumentAiRefs,
+	parseDocumentAiTargetRef,
+	readTiptapNodeAiRef,
+	serializeTiptapNodeToPlainAiHtml,
+} from "#/features/workspaces/documents/document-ai-html";
 import {
 	type DocumentHtmlChunkReadInput,
 	type DocumentHtmlChunkReadResult,
@@ -148,7 +155,7 @@ export class DocumentSession extends YServer {
 
 		const room = getDocumentSessionRoomNameParts(this.name);
 		const kernel = await this.getWorkspaceKernel(room.workspaceId);
-		const { content } = await kernel.readDocumentCheckpoint({ itemId: room.itemId });
+		const { content } = await kernel.readItemContent({ itemId: room.itemId });
 		if (this.deleted) {
 			return;
 		}
@@ -343,6 +350,32 @@ export class DocumentSession extends YServer {
 		return chunk ? { ...chunk, revision, status: "ready" } : { status: "invalid_offset" };
 	}
 
+	/**
+	 * One block in full, addressed by a ref from an earlier read.
+	 *
+	 * Document reads elide a widget's source to keep prose in the chunk, so this
+	 * is how the assistant fetches it before editing — and it works for any block
+	 * that is easier to read alone than to page to.
+	 */
+	async readBlock(input: {
+		ref: string;
+	}): Promise<{ content: string; status: "ready" } | { status: "ref_not_found" }> {
+		this.assertActive();
+		const { document } = await this.getReferencedDocumentSnapshot();
+		const stableRef = parseDocumentAiTargetRef(input.ref) ?? input.ref;
+
+		let found: ProseMirrorNode | null = null;
+		document.forEach((node) => {
+			if (!found && readTiptapNodeAiRef(node) === stableRef) {
+				found = node;
+			}
+		});
+
+		return found
+			? { content: serializeTiptapNodeToPlainAiHtml(found), status: "ready" }
+			: { status: "ref_not_found" };
+	}
+
 	async purgeForDeletion(): Promise<void> {
 		// Deliberately does not hydrate the document: this only wipes durable
 		// storage, and onLoad could otherwise reseed from the deleted item.
@@ -359,7 +392,7 @@ export class DocumentSession extends YServer {
 		const document = this.getCurrentTiptapDocument();
 		const kernel = await this.getWorkspaceKernel(room.workspaceId);
 
-		await kernel.commitDocumentCheckpoint({
+		await kernel.writeItemContent({
 			itemId: room.itemId,
 			content: stringifyTiptapDocumentJson(document),
 			actorUserId: null,
diff --git a/src/features/workspaces/documents/document-widget-node.tsx b/src/features/workspaces/documents/document-widget-node.tsx
new file mode 100644
index 000000000..4dfb0810d
--- /dev/null
+++ b/src/features/workspaces/documents/document-widget-node.tsx
@@ -0,0 +1,44 @@
+import type { NodeViewProps } from "@tiptap/react";
+import { NodeViewWrapper, ReactNodeViewRenderer } from "@tiptap/react";
+
+import { WorkspaceWidgetSandbox } from "#/features/workspaces/components/widget/WorkspaceWidgetSandbox";
+import { Widget } from "#/features/workspaces/documents/tiptap-schema";
+
+/**
+ * The editor's widget: the authored HTML running in its sandboxed frame.
+ *
+ * Three things keep ProseMirror and the frame out of each other's way.
+ * `contentEditable={false}` stops a click inside the widget being read as a text
+ * selection. `stopEvent` keeps events raised inside the node view from reaching
+ * the editor at all. `ignoreMutation` stops the editor re-parsing when the frame
+ * changes its own DOM — selection mutations still pass through, so clicking away
+ * from the widget behaves normally.
+ */
+export const DocumentWidget = Widget.extend({
+	addNodeView() {
+		return ReactNodeViewRenderer(DocumentWidgetView, {
+			stopEvent: () => true,
+			ignoreMutation: ({ mutation }) => mutation.type !== "selection",
+		});
+	},
+});
+
+function DocumentWidgetView({ node, selected }: NodeViewProps) {
+	const html = node.textContent;
+	const title = typeof node.attrs.title === "string" ? node.attrs.title : "";
+
+	return (
+		<NodeViewWrapper
+			className="workspace-document-widget"
+			contentEditable={false}
+			data-selected={selected ? "true" : undefined}
+		>
+			{/* The only editor-owned affordance: without it there is no way to pick
+			    the widget up or delete it, since clicks go to the frame. */}
+			<div className="workspace-document-widget-handle" data-drag-handle contentEditable={false}>
+				<span>{title || "Widget"}</span>
+			</div>
+			<WorkspaceWidgetSandbox html={html} className="workspace-document-widget-frame" />
+		</NodeViewWrapper>
+	);
+}
diff --git a/src/features/workspaces/documents/tiptap-extensions.ts b/src/features/workspaces/documents/tiptap-extensions.ts
index 08fc457a9..edd17ce0e 100644
--- a/src/features/workspaces/documents/tiptap-extensions.ts
+++ b/src/features/workspaces/documents/tiptap-extensions.ts
@@ -5,6 +5,7 @@ import "katex/dist/katex.min.css";
 import "katex/contrib/mhchem";
 
 import { CodeBlockShiki } from "#/features/workspaces/documents/code-block-shiki";
+import { DocumentWidget } from "#/features/workspaces/documents/document-widget-node";
 import { DocumentCitation } from "#/features/workspaces/documents/document-citation-node";
 import {
 	getTiptapDocumentSchemaExtensions,
@@ -19,6 +20,7 @@ export function getTiptapDocumentBaseExtensions() {
 			// Both extend the node spec the server uses, adding only how it draws.
 			citation: DocumentCitation,
 			codeBlock: CodeBlockShiki,
+			widget: DocumentWidget,
 		}),
 		Placeholder.configure({
 			placeholder: ({ node }) => (node.type.name === "heading" ? "Untitled" : "Write something..."),
diff --git a/src/features/workspaces/documents/tiptap-schema.ts b/src/features/workspaces/documents/tiptap-schema.ts
index 523e695d1..1e2d406b6 100644
--- a/src/features/workspaces/documents/tiptap-schema.ts
+++ b/src/features/workspaces/documents/tiptap-schema.ts
@@ -1,9 +1,10 @@
-import { type AnyExtension, Extension, getSchema, Node } from "@tiptap/core";
+import { type AnyExtension, Extension, getSchema, mergeAttributes, Node } from "@tiptap/core";
 import CodeBlock from "@tiptap/extension-code-block";
 import Highlight from "@tiptap/extension-highlight";
 import HorizontalRule from "@tiptap/extension-horizontal-rule";
 import Link from "@tiptap/extension-link";
 import { TaskItem, TaskList } from "@tiptap/extension-list";
+import { Details, DetailsContent, DetailsSummary } from "@tiptap/extension-details";
 import { Mathematics } from "@tiptap/extension-mathematics";
 import { TableKit } from "@tiptap/extension-table";
 import TextAlign from "@tiptap/extension-text-align";
@@ -51,6 +52,49 @@ export const Citation = Node.create({
 		];
 	},
 });
+/**
+ * An interactive widget: a self-contained HTML fragment the assistant writes,
+ * rendered in a sandboxed iframe by the client's node view.
+ *
+ * The source is the node's text content rather than an attribute. A widget runs
+ * to several kilobytes of markup and script, and escaping all of that into an
+ * attribute is exactly the kind of thing a model gets subtly wrong — this is the
+ * same reason a code block holds its code as content. `atom` means the editor
+ * treats it as one unit: there is content, but it is not typed into directly.
+ * `code` keeps input rules and smart typography from rewriting the source.
+ */
+export const Widget = Node.create({
+	name: "widget",
+	group: "block",
+	content: "text*",
+	marks: "",
+	code: true,
+	atom: true,
+	defining: true,
+	selectable: true,
+	draggable: true,
+
+	addAttributes() {
+		return {
+			title: {
+				default: "",
+				parseHTML: (el) => el.getAttribute("title") ?? "",
+				renderHTML: (attrs) => (attrs.title ? { title: String(attrs.title) } : {}),
+			},
+		};
+	},
+
+	parseHTML() {
+		return [{ tag: 'div[data-type="widget"]', preserveWhitespace: "full" as const }];
+	},
+
+	renderHTML({ HTMLAttributes }) {
+		// Merge rather than replace: global attributes land here, and data-ref is
+		// how the assistant addresses this block for reads and edits.
+		return ["div", mergeAttributes(HTMLAttributes, { "data-type": "widget" }), 0];
+	},
+});
+
 export const tiptapDocumentAiRefAttribute = "aiRef";
 
 const DocumentAiRef = Extension.create({
@@ -96,9 +140,11 @@ export const tiptapDocumentKernelCodeBlock = CodeBlock;
 export function getTiptapDocumentSchemaExtensions({
 	citation = Citation,
 	codeBlock = tiptapDocumentKernelCodeBlock,
+	widget = Widget,
 }: {
 	citation?: AnyExtension;
 	codeBlock?: AnyExtension;
+	widget?: AnyExtension;
 } = {}) {
 	return [
 		DocumentAiRef,
@@ -114,6 +160,7 @@ export function getTiptapDocumentSchemaExtensions({
 			undoRedo: false,
 		}),
 		codeBlock,
+		widget,
 		HorizontalRule,
 		UnderlineExtension,
 		Highlight,
@@ -130,6 +177,12 @@ export function getTiptapDocumentSchemaExtensions({
 		TextAlign.configure({
 			types: ["heading", "paragraph"],
 		}),
+		// Collapsible sections. Registered for content only — the AI writes
+		// <details> naturally and it used to be flattened away; there is no
+		// toolbar affordance for inserting one by hand.
+		Details,
+		DetailsSummary,
+		DetailsContent,
 		TaskList,
 		TaskItem.configure({
 			nested: true,
diff --git a/src/features/workspaces/kernel/workspace-kernel-access.ts b/src/features/workspaces/kernel/workspace-kernel-access.ts
index 592e873ef..561ef68ec 100644
--- a/src/features/workspaces/kernel/workspace-kernel-access.ts
+++ b/src/features/workspaces/kernel/workspace-kernel-access.ts
@@ -103,7 +103,7 @@ export interface WorkspaceKernelClient {
 		actorUserId?: string | null;
 		clientMutationId?: string | null;
 	}): Promise<WorkspaceCommandResult<DeleteWorkspaceKernelItemsResult>>;
-	readDocumentCheckpoint(input: {
+	readItemContent(input: {
 		itemId: string;
 	}): Promise<{ item: WorkspaceItemSummary; content: string }>;
 	getFileSource(input: { itemId: string }): Promise<WorkspaceKernelFileSource>;
@@ -114,7 +114,7 @@ export interface WorkspaceKernelClient {
 	readFileProjection(
 		input: ReadWorkspaceKernelFileProjectionArgs,
 	): Promise<ReadWorkspaceKernelFileProjectionResult | null>;
-	commitDocumentCheckpoint(input: {
+	writeItemContent(input: {
 		itemId: string;
 		content: string;
 		actorUserId?: string | null;
@@ -145,6 +145,23 @@ export async function readWorkspaceKernelFileSource(input: {
 	}
 }
 
+export async function readWorkspaceKernelItemContent(input: {
+	workspaceId: string;
+	userId: string;
+	itemId: string;
+}) {
+	const dbContext = await createDbContext();
+
+	try {
+		await assertCanReadWorkspace(dbContext.db, input);
+		const kernel = await getWorkspaceKernel(input.workspaceId);
+
+		return await kernel.readItemContent({ itemId: input.itemId });
+	} finally {
+		await dbContext.dispose();
+	}
+}
+
 export async function readWorkspaceKernelFilePreview(input: {
 	workspaceId: string;
 	userId: string;
diff --git a/src/features/workspaces/kernel/workspace-kernel-files.ts b/src/features/workspaces/kernel/workspace-kernel-files.ts
index 5d2b6fce3..496fa0886 100644
--- a/src/features/workspaces/kernel/workspace-kernel-files.ts
+++ b/src/features/workspaces/kernel/workspace-kernel-files.ts
@@ -23,14 +23,15 @@ export function getWorkspaceKernelContentMimeType(type: WorkspaceItemType) {
 }
 
 export function getInitialWorkspaceKernelContent(type: WorkspaceItemType) {
-	switch (getWorkspaceItemRegistryEntry(type).contentKind) {
+	switch (type) {
 		case "document":
 			return stringifyTiptapDocumentJson(createInitialTiptapDocumentJson());
 		case "flashcard":
 			return JSON.stringify({ version: 1, cards: [] }, null, 2);
 		case "quiz":
 			return JSON.stringify({ version: 1, questions: [] }, null, 2);
-		case "empty":
+		case "file":
+		case "folder":
 			return "";
 	}
 }
diff --git a/src/features/workspaces/kernel/workspace-kernel-item-commands.ts b/src/features/workspaces/kernel/workspace-kernel-item-commands.ts
index e8247ca59..02b951370 100644
--- a/src/features/workspaces/kernel/workspace-kernel-item-commands.ts
+++ b/src/features/workspaces/kernel/workspace-kernel-item-commands.ts
@@ -25,10 +25,8 @@ import type {
 	DeleteWorkspaceKernelItemsResult,
 	MoveWorkspaceKernelItemsArgs,
 	MoveWorkspaceKernelItemsResult,
-	ReadWorkspaceDocumentCheckpointArgs,
 	RenameWorkspaceKernelItemArgs,
 	UpdateWorkspaceKernelItemColorArgs,
-	CommitWorkspaceDocumentCheckpointArgs,
 	WorkspaceKernelMutationOutcome,
 } from "#/features/workspaces/kernel/workspace-kernel-types";
 import {
@@ -325,26 +323,35 @@ export class WorkspaceKernelItemCommands {
 		return { result, event };
 	}
 
-	async readDocumentCheckpoint(input: ReadWorkspaceDocumentCheckpointArgs) {
+	/** Reads the stored content blob of any content-bearing item. */
+	async readItemContent(input: { itemId: string }) {
 		const item = this.store.assertActiveItem(input.itemId);
-		if (item.type !== "document") {
-			throw new Error("Only document items have document checkpoints.");
+		if (item.type === "folder") {
+			throw new Error("Folders have no readable content.");
 		}
-		const itemSummary = mapKernelItemRow(item, this.workspaceId());
 		return {
-			item: itemSummary,
+			item: mapKernelItemRow(item, this.workspaceId()),
 			content: await this.workspace.readFile(item.shell_path),
 		};
 	}
 
-	async commitDocumentCheckpoint(
-		input: CommitWorkspaceDocumentCheckpointArgs,
-	): Promise<WorkspaceCommandResult<WorkspaceItemSummary>> {
+	/**
+	 * Writes the stored content blob of any content-bearing item.
+	 *
+	 * Documents additionally refresh the metadata preview derived from their
+	 * content; every other type just persists the blob.
+	 */
+	async writeItemContent(input: {
+		itemId: string;
+		content: string;
+		actorUserId?: string | null;
+		clientMutationId?: string | null;
+	}): Promise<WorkspaceCommandResult<WorkspaceItemSummary>> {
 		const item = this.store.assertActiveItem(input.itemId);
 		const type = workspaceItemTypeSchema.parse(item.type);
 
-		if (type !== "document") {
-			throw new Error("Only document checkpoints can update workspace text content.");
+		if (type === "folder") {
+			throw new Error("Folders have no writable content.");
 		}
 
 		await this.workspace.writeFile(
@@ -354,15 +361,24 @@ export class WorkspaceKernelItemCommands {
 		);
 
 		const currentItem = this.store.assertActiveItem(input.itemId);
+		// Keep updated_at strictly increasing so same-millisecond writes still order.
 		const updatedAt = Math.max(Date.now(), currentItem.updated_at + 1);
 
-		persistDocumentItemContentUpdate({
-			content: input.content,
-			itemId: input.itemId,
-			metadataJson: currentItem.metadata_json,
-			sql: this.sql,
-			updatedAt,
-		});
+		if (type === "document") {
+			persistDocumentItemContentUpdate({
+				content: input.content,
+				itemId: input.itemId,
+				metadataJson: currentItem.metadata_json,
+				sql: this.sql,
+				updatedAt,
+			});
+		} else {
+			this.sql`
+				UPDATE kernel_items
+				SET updated_at = ${updatedAt}
+				WHERE id = ${input.itemId} AND deleted_at IS NULL
+			`;
+		}
 
 		return this.commitItemEvent({
 			type: "workspace.item.content.updated",
diff --git a/src/features/workspaces/kernel/workspace-kernel-types.ts b/src/features/workspaces/kernel/workspace-kernel-types.ts
index d553e47b5..1303d8622 100644
--- a/src/features/workspaces/kernel/workspace-kernel-types.ts
+++ b/src/features/workspaces/kernel/workspace-kernel-types.ts
@@ -163,10 +163,6 @@ export interface DeleteWorkspaceKernelItemsArgs {
 	clientMutationId?: string | null;
 }
 
-export interface ReadWorkspaceDocumentCheckpointArgs {
-	itemId: string;
-}
-
 export interface ReadWorkspaceKernelFileSourceArgs {
 	itemId: string;
 }
@@ -247,13 +243,6 @@ export interface ReadWorkspaceKernelFileProjectionResult {
 	updatedAt: string;
 }
 
-export interface CommitWorkspaceDocumentCheckpointArgs {
-	itemId: string;
-	content: string;
-	actorUserId?: string | null;
-	clientMutationId?: string | null;
-}
-
 export interface CreateWorkspaceKernelFileFromUploadArgs {
 	id: string;
 	parentId?: string | null;
diff --git a/src/features/workspaces/kernel/workspace-kernel.ts b/src/features/workspaces/kernel/workspace-kernel.ts
index c61f0a7bc..9c05259e5 100644
--- a/src/features/workspaces/kernel/workspace-kernel.ts
+++ b/src/features/workspaces/kernel/workspace-kernel.ts
@@ -43,14 +43,12 @@ import type {
 	MoveWorkspaceKernelItemsResult,
 	ReadWorkspaceKernelFileSourceArgs,
 	ReadWorkspaceKernelFileProjectionArgs,
-	ReadWorkspaceDocumentCheckpointArgs,
 	ResolveWorkspaceKernelPathsArgs,
 	RenameWorkspaceKernelItemArgs,
 	UpdateWorkspaceKernelItemColorArgs,
 	UpsertWorkspaceKernelFileProjectionArgs,
 	WorkspaceKernelPage,
 	WorkspaceKernelMutationOutcome,
-	CommitWorkspaceDocumentCheckpointArgs,
 	WorkspaceKernelPathResolution,
 } from "#/features/workspaces/kernel/workspace-kernel-types";
 import { getChatAttachmentWorkspacePrefix } from "#/features/workspaces/ai/chat-attachment-storage";
@@ -379,15 +377,18 @@ export class WorkspaceKernel extends Agent<Cloudflare.Env> {
 		}
 	}
 
-	async readDocumentCheckpoint(input: ReadWorkspaceDocumentCheckpointArgs) {
-		return await this.itemCommands.readDocumentCheckpoint(input);
+	async readItemContent(input: { itemId: string }) {
+		return await this.itemCommands.readItemContent(input);
 	}
 
-	async commitDocumentCheckpoint(
-		input: CommitWorkspaceDocumentCheckpointArgs,
-	): Promise<WorkspaceCommandResult<WorkspaceItemSummary>> {
-		return this.runMutation("commit_document_checkpoint", input, 1, () =>
-			this.itemCommands.commitDocumentCheckpoint(input),
+	async writeItemContent(input: {
+		itemId: string;
+		content: string;
+		actorUserId?: string | null;
+		clientMutationId?: string | null;
+	}): Promise<WorkspaceCommandResult<WorkspaceItemSummary>> {
+		return this.runMutation("write_item_content", input, 1, () =>
+			this.itemCommands.writeItemContent(input),
 		);
 	}
 
diff --git a/src/features/workspaces/model/item-display.ts b/src/features/workspaces/model/item-display.ts
index 3bd89d117..08cbe4a17 100644
--- a/src/features/workspaces/model/item-display.ts
+++ b/src/features/workspaces/model/item-display.ts
@@ -1,10 +1,12 @@
 import { Mic, Upload } from "lucide-react";
 
+import type { WorkspaceItemType } from "#/features/workspaces/contracts";
 import { getWorkspaceObjectRegistryEntry } from "#/features/workspaces/model/object-registry";
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
 import { workspaceColors } from "#/features/workspaces/model/workspace-colors";
 import { resolveWorkspaceFileTypeFromItem } from "#/features/workspaces/model/workspace-file";
 import { getWorkspaceItemPalette } from "#/features/workspaces/model/workspace-item-colors";
+import { getWorkspaceItemRegistryEntry } from "#/features/workspaces/workspace-item-registry";
 
 export function getWorkspaceItemDisplay(item: WorkspaceItem) {
 	const typeDisplay = getWorkspaceObjectRegistryEntry(item.type);
@@ -26,10 +28,13 @@ const workspaceItemLearnCreateActionOrder = ["flashcard", "quiz"] as const;
 export const workspaceItemPrimaryCreateActions =
 	workspaceItemPrimaryCreateActionOrder.map(createWorkspaceItemAction);
 
-export const workspaceItemLearnCreateActions =
-	workspaceItemLearnCreateActionOrder.map(createWorkspaceItemAction);
+export const workspaceItemLearnCreateActions = workspaceItemLearnCreateActionOrder.map((type) => ({
+	...createWorkspaceItemAction(type),
+	// A type with no create flow yet is shown disabled rather than hidden.
+	comingSoon: !getWorkspaceItemRegistryEntry(type).creatable,
+}));
 
-function createWorkspaceItemAction(type: "document" | "folder" | "flashcard" | "quiz") {
+function createWorkspaceItemAction(type: WorkspaceItemType) {
 	const display = getWorkspaceObjectRegistryEntry(type);
 	return {
 		type,
diff --git a/src/features/workspaces/model/use-workspace-item-path.ts b/src/features/workspaces/model/use-workspace-item-path.ts
new file mode 100644
index 000000000..59f070fc3
--- /dev/null
+++ b/src/features/workspaces/model/use-workspace-item-path.ts
@@ -0,0 +1,26 @@
+import { useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+
+import type { WorkspaceItem } from "#/features/workspaces/model/types";
+import { getWorkspaceAiContextItemPath } from "#/features/workspaces/model/workspace-ai-context-reference";
+import { workspacePageQueryOptions } from "#/features/workspaces/query-options";
+
+/**
+ * Absolute workspace path for one item, for surfaces that only hold the item.
+ *
+ * Reads the already-cached workspace page rather than asking the server, so a
+ * component can name a path without waiting on a round trip. Returns null until
+ * the page is in cache.
+ */
+export function useWorkspaceItemPath(workspaceId: string, item: WorkspaceItem | null) {
+	const { data } = useQuery(workspacePageQueryOptions(workspaceId));
+	const items = data?.items;
+
+	return useMemo(() => {
+		if (!item || !items) {
+			return null;
+		}
+
+		return getWorkspaceAiContextItemPath(item, new Map(items.map((entry) => [entry.id, entry])));
+	}, [item, items]);
+}
diff --git a/src/features/workspaces/model/workspace-ai-context-reference.ts b/src/features/workspaces/model/workspace-ai-context-reference.ts
index f2d73c1de..e09fbd89b 100644
--- a/src/features/workspaces/model/workspace-ai-context-reference.ts
+++ b/src/features/workspaces/model/workspace-ai-context-reference.ts
@@ -77,7 +77,14 @@ export function getOpenTabItemIds(tabs: WorkspaceTab[]) {
 	return itemTabTitles;
 }
 
-function getWorkspaceAiContextItemPath(
+/**
+ * Absolute workspace path for one item, derived from the client item tree.
+ *
+ * Matches the paths the kernel resolves, so it is safe to hand to the model —
+ * a prefilled prompt naming a path stays correct even if the user switches
+ * views before sending it.
+ */
+export function getWorkspaceAiContextItemPath(
 	item: WorkspaceItem,
 	itemsById: ReadonlyMap<string, WorkspaceItem>,
 ) {
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index 8352173cc..da4c0e96b 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -33,7 +33,8 @@ exports[`workspace tool surface > system prompt is stable 1`] = `
 - Let the app control Mermaid presentation: do not add frontmatter or init directives, custom styles or colors, embedded HTML, links, images, or other external resources. Include a concise \`accTitle\` and \`accDescr\` describing the diagram.
 - When writing Markdown with math, use \`$...$\` for inline math and \`$$...$$\` on separate lines for block math. Do not use \`\\(...\\)\` or \`\\[...\\]\`; our renderer only understands dollar-sign delimiters.
 - Chemistry renders with \`\\ce{...}\` (e.g. \`$\\ce{CH4 + 2 O2 -> CO2 + 2 H2O}$\`) and quantities with units render with \`\\pu{...}\`.
-- CRITICAL: every literal dollar sign — every price, cost, salary, or currency figure — MUST be escaped as \`\\$\`. Write \`\\$5\`, not \`$5\`. Write \`\\$1,000 − \\$200 = \\$800\`, not \`$1,000 − $200 = $800\`. A missed escape turns the price into broken math on screen.
+- CRITICAL, in chat replies only: every literal dollar sign — every price, cost, salary, or currency figure — MUST be escaped as \`\\$\`. Write \`\\$5\`, not \`$5\`. Write \`\\$1,000 − \\$200 = \\$800\`, not \`$1,000 − $200 = $800\`. A missed escape turns the price into broken math on screen.
+- That escape is a Markdown rule and applies to chat replies only. Document and widget content is HTML, where \`\\$\` renders as a visible backslash — write money plainly there, as \`$30\`.
 
 # Memory
 - Use memory only for durable preferences, workspace goals, thread goals, and decisions. Do not store transient requests, secrets, full documents, item bodies, or actual workspace state."
@@ -200,7 +201,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
   "additionalProperties": false,
   "properties": {
     "edits": {
-      "description": "Ordered structural HTML edits, at most 40. For targeted operations, copy data-ref into the "ref" field; there is no "target" field. These refs are local to this document and are not workspace citation refs.",
+      "description": "Ordered edits, at most 40. Target a block by copying its data-ref into the "ref" field (these are local to the document, not workspace citation refs). Use replace_text to change text inside one block, including a widget's source. Use overwrite only to discard the entire document and write a new one.",
       "items": {
         "anyOf": [
           {
@@ -262,7 +263,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                 "type": "string",
               },
               "op": {
-                "const": "replace_all",
+                "const": "overwrite",
                 "type": "string",
               },
             },
@@ -272,6 +273,37 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
             ],
             "type": "object",
           },
+          {
+            "additionalProperties": false,
+            "properties": {
+              "find": {
+                "description": "Exact text to replace inside the target block, copied from a read. It must appear exactly once in that block; if it matches more than once the edit fails instead of replacing every occurrence.",
+                "minLength": 1,
+                "type": "string",
+              },
+              "op": {
+                "const": "replace_text",
+                "type": "string",
+              },
+              "ref": {
+                "description": "Exact data-ref from a recent HTML read. Put it in the "ref" field, never "target".",
+                "maxLength": 64,
+                "minLength": 1,
+                "type": "string",
+              },
+              "replace": {
+                "description": "Replacement text. May be empty to delete the matched text.",
+                "type": "string",
+              },
+            },
+            "required": [
+              "find",
+              "op",
+              "ref",
+              "replace",
+            ],
+            "type": "object",
+          },
         ],
       },
       "maxItems": 40,
@@ -479,6 +511,31 @@ exports[`workspace tool surface > workspace_read_items input schema is stable 1`
             ],
             "type": "object",
           },
+          {
+            "additionalProperties": false,
+            "properties": {
+              "mode": {
+                "const": "block",
+                "type": "string",
+              },
+              "path": {
+                "description": "Absolute path of the workspace item to read.",
+                "minLength": 1,
+                "type": "string",
+              },
+              "ref": {
+                "description": "data-ref of one block from an earlier read of this document, returned in full. Reads elide a widget's source, so this is how to fetch it before editing.",
+                "minLength": 1,
+                "type": "string",
+              },
+            },
+            "required": [
+              "path",
+              "mode",
+              "ref",
+            ],
+            "type": "object",
+          },
         ],
       },
       "maxItems": 20,
diff --git a/src/features/workspaces/operations/create-items.ts b/src/features/workspaces/operations/create-items.ts
index 671b3204d..2f368d105 100644
--- a/src/features/workspaces/operations/create-items.ts
+++ b/src/features/workspaces/operations/create-items.ts
@@ -1,3 +1,4 @@
+import type { WorkspaceCreatableItemType } from "#/features/workspaces/workspace-item-registry";
 import { getAuthorizedWorkspaceKernel } from "#/features/workspaces/operations/workspace-operation-context";
 import {
 	resolveWorkspaceRelations,
@@ -22,7 +23,7 @@ import {
 } from "#/features/workspaces/kernel/workspace-kernel-paths";
 
 export interface CreateWorkspaceItemOperationInput {
-	type: "document" | "folder";
+	type: WorkspaceCreatableItemType;
 	path: string;
 	initialContent?: string;
 	relations?: WorkspaceRelationInput[];
@@ -43,7 +44,7 @@ export interface CreateWorkspaceItemsFailure {
 export interface CreatedWorkspaceItem {
 	itemId: string;
 	path: string;
-	type: "document" | "folder";
+	type: WorkspaceCreatableItemType;
 }
 
 export interface CreateWorkspaceItemsOperationResult {
diff --git a/src/features/workspaces/operations/workspace-tool-definitions.ts b/src/features/workspaces/operations/workspace-tool-definitions.ts
index a3427b1f0..fcf96ecf9 100644
--- a/src/features/workspaces/operations/workspace-tool-definitions.ts
+++ b/src/features/workspaces/operations/workspace-tool-definitions.ts
@@ -149,7 +149,7 @@ export const workspaceToolDefinitions = [
 		name: "workspace_read_items",
 		access: "read",
 		description:
-			"Read ThinkEx documents and extracted files by absolute path. Documents return bounded HTML block chunks; each top-level data-ref is an item-local edit target, not a citation ref. Files support explicit physical-page selections. Continue either kind with nextCursor. Uploaded files may still be extracting; each result carries any needed handling guidance.",
+			"Read ThinkEx documents and extracted files by absolute path. Documents return bounded HTML block chunks; each top-level data-ref is an item-local edit target, not a citation ref. Widgets come back as an empty placeholder, so read one back with mode block before editing its source. Files support explicit physical-page selections. Continue either kind with nextCursor. Uploaded files may still be extracting; each result carries any needed handling guidance.",
 		inputSchema: workspaceReadItemsInputSchema,
 		inputExamples: workspaceReadItemsInputExamples,
 		outputSchema: workspaceReadItemsOutputSchema,
@@ -214,7 +214,7 @@ export const workspaceToolDefinitions = [
 	defineWorkspaceTool({
 		name: "workspace_create_items",
 		access: "write",
-		description: `Create one or more folders or documents at exact absolute paths. If a path already exists, creation fails instead of renaming. ${workspaceDocumentHtmlInstruction}`,
+		description: `Create one or more folders or documents at exact absolute paths. If a path already exists, creation fails instead of renaming. A document is also how interactive work ships: give it a widget block, on its own or alongside prose. ${workspaceDocumentHtmlInstruction}`,
 		inputSchema: workspaceCreateItemsInputSchema,
 		inputExamples: workspaceCreateItemsInputExamples,
 		outputSchema: workspaceCreateItemsOutputSchema,
@@ -244,7 +244,7 @@ export const workspaceToolDefinitions = [
 	defineWorkspaceTool({
 		name: "workspace_edit_item",
 		access: "write",
-		description: `Edit one actual ThinkEx workspace document by absolute path using structural HTML operations. Read first for targeted edits; replace_all can rewrite the whole document without a read. Use workspace_link_items to add relationships. ${workspaceDocumentHtmlInstruction}`,
+		description: `Edit one actual ThinkEx workspace document by absolute path. Read it first, then target blocks by data-ref. Only overwrite replaces the whole document, and only it works without a read. Use workspace_link_items to add relationships. ${workspaceDocumentHtmlInstruction}`,
 		inputSchema: workspaceEditItemInputSchema,
 		inputExamples: workspaceEditItemInputExamples,
 		outputSchema: workspaceEditItemOutputSchema,
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index 26d3a91fb..a0af1a4b8 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -16,6 +16,7 @@ import {
 	workspaceItemTypeSchema,
 	workspaceRelationKindSchema,
 } from "#/features/workspaces/contracts";
+import { workspaceCreatableItemTypeSchema } from "#/features/workspaces/workspace-item-registry";
 import { workspaceReferenceRecordSchema } from "#/features/workspaces/locations/workspace-location";
 import {
 	documentAiEditSchema,
@@ -34,8 +35,26 @@ export {
 	workspaceSearchOutputSchema,
 };
 
-export const workspaceDocumentHtmlInstruction =
-	'Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. For math, use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div> — this is the only math that renders, so never write $...$, $$...$$, or \\(...\\) in the HTML, and never put dollar signs around the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math, not <sub> or <sup> tags, which are unsupported and reject the whole write. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — this is HTML, not Markdown, so a backslash before a dollar sign shows on screen. For checkboxes, use <ul data-type="taskList"><li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>Item</p></div></li></ul>. Documents cannot hold images: never use <img> or <figure>, and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with <citation ref="wr_7Kp2Qa9x"></citation> placed after the claim it supports.';
+/**
+ * Math, chemistry, and money for the HTML surfaces. Documents and widgets are
+ * both HTML, so they share one rule and the model tracks "Markdown or HTML?"
+ * rather than three per-surface dialects — chat keeps the `$…$` Markdown form.
+ */
+export const workspaceHtmlMathInstruction =
+	'This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML.';
+
+/**
+ * The hard constraints only — enough that a widget written without the skill
+ * still renders. Activate the widget-authoring skill for the full contract,
+ * starter template, and canvas/layout guidance rather than restating it here on
+ * every turn.
+ *
+ * Carried by the document instruction because a widget is a document block: the
+ * model reaches for one from inside the same write it would write prose in.
+ */
+const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document, written as <div data-type="widget" title="Short title">…escaped HTML source…</div>. Reach for one when the user asks for something interactive — a simulation, calculator, diagram, or visualization — and keep the surrounding prose in normal blocks. Activate the "widget-authoring" skill before writing widget source; it has the full contract, a starter template, and canvas/layout rules. Hard constraints: the source is a self-contained fragment run in a sandboxed iframe, so provide only inner content (HTML plus inline <style> and <script>), never <!doctype>, <html>, <head>, or <body>; all JavaScript must be inline, with no external scripts, imports, or network access; style with the injected app CSS variables (--background, --foreground, --primary, --border, --radius, etc.) instead of hard-coded colors.`;
+
+export const workspaceDocumentHtmlInstruction = `Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. ${workspaceHtmlMathInstruction} For checkboxes, use <ul data-type="taskList"><li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>Item</p></div></li></ul>. Documents cannot hold images: never use <img> or <figure>, and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with <citation ref="wr_7Kp2Qa9x"></citation> placed after the claim it supports. ${workspaceWidgetHtmlInstruction}`;
 
 const workspacePathSchema = z.string().min(1);
 const workspaceIndexSchema = z.number().int().nonnegative();
@@ -124,7 +143,7 @@ export const workspaceEditItemInputSchema = z.object({
 		.min(1)
 		.max(40)
 		.describe(
-			'Ordered structural HTML edits, at most 40. For targeted operations, copy data-ref into the "ref" field; there is no "target" field. These refs are local to this document and are not workspace citation refs.',
+			'Ordered edits, at most 40. Target a block by copying its data-ref into the "ref" field (these are local to the document, not workspace citation refs). Use replace_text to change text inside one block, including a widget\'s source. Use overwrite only to discard the entire document and write a new one.',
 		),
 });
 
@@ -302,11 +321,22 @@ export const workspaceEditItemInputExamples = createInputExamples<
 		path: "/Demo Folder/Demo Document",
 		edits: [
 			{
-				op: "replace_all",
+				op: "overwrite",
 				html: "<h1>Demo Document</h1><p>This document was updated as part of the demo.</p>",
 			},
 		],
 	},
+	{
+		path: "/Demo Folder/Demo Document",
+		edits: [
+			{
+				op: "replace_text",
+				ref: "b_JQrkL4Neurv2.r_6sNqkQxDdy",
+				find: "gravity = 9.8",
+				replace: "gravity = 3.7",
+			},
+		],
+	},
 );
 
 export const workspaceLinkItemsInputExamples = createInputExamples<
@@ -337,9 +367,9 @@ export const workspaceListItemsOutputSchema = z.object({
 export const workspaceCreateItemsOutputSchema = createWorkspaceItemsResultSchema({
 	itemSchema: workspacePathItemSchema.extend({
 		itemId: z.string().min(1),
-		// Creation makes these two and nothing else; the shared item type covers
+		// Creation makes these three and nothing else; the shared item type covers
 		// files and study items this tool cannot produce.
-		type: z.enum(["document", "folder"]),
+		type: workspaceCreatableItemTypeSchema,
 	}),
 	failureSchema: createFailureSchema(createWorkspaceItemsFailureCodes),
 }).extend({
diff --git a/src/features/workspaces/query-options.ts b/src/features/workspaces/query-options.ts
index 0cadc4f13..1af2931de 100644
--- a/src/features/workspaces/query-options.ts
+++ b/src/features/workspaces/query-options.ts
@@ -1,7 +1,15 @@
 import { queryOptions } from "@tanstack/react-query";
 
-import { workspacePageQueryKey, workspacesQueryKey } from "#/features/workspaces/cache";
-import { getWorkspacePageFn, listWorkspacesFn } from "#/features/workspaces/server/functions";
+import {
+	workspaceItemContentQueryKey,
+	workspacePageQueryKey,
+	workspacesQueryKey,
+} from "#/features/workspaces/cache";
+import {
+	getWorkspacePageFn,
+	listWorkspacesFn,
+	readWorkspaceItemContentFn,
+} from "#/features/workspaces/server/functions";
 
 export function workspacesQueryOptions() {
 	return queryOptions({
@@ -17,3 +25,10 @@ export function workspacePageQueryOptions(workspaceId: string) {
 		staleTime: 10_000,
 	});
 }
+
+export function workspaceItemContentQueryOptions(workspaceId: string, itemId: string) {
+	return queryOptions({
+		queryKey: workspaceItemContentQueryKey(workspaceId, itemId),
+		queryFn: () => readWorkspaceItemContentFn({ data: { workspaceId, itemId } }),
+	});
+}
diff --git a/src/features/workspaces/server/functions.ts b/src/features/workspaces/server/functions.ts
index 1be1d8832..8364dfac4 100644
--- a/src/features/workspaces/server/functions.ts
+++ b/src/features/workspaces/server/functions.ts
@@ -15,6 +15,7 @@ import {
 	createWorkspaceKernelItem,
 	deleteWorkspaceKernelItems,
 	moveWorkspaceKernelItems,
+	readWorkspaceKernelItemContent,
 	renameWorkspaceKernelItem,
 	updateWorkspaceKernelItemColor,
 } from "#/features/workspaces/kernel/workspace-kernel-access";
@@ -42,6 +43,16 @@ export const getWorkspacePageFn = createServerFn({ method: "GET" })
 	.validator(workspaceIdInputSchema)
 	.handler(async ({ data }) => getWorkspacePageForCurrentUser(data.workspaceId));
 
+export const readWorkspaceItemContentFn = createServerFn({ method: "GET" })
+	.validator(z.object({ workspaceId: z.string().min(1), itemId: z.string().min(1) }))
+	.handler(async ({ data }) =>
+		readWorkspaceKernelItemContent({
+			workspaceId: data.workspaceId,
+			itemId: data.itemId,
+			userId: await getCurrentUserId(),
+		}),
+	);
+
 export const createWorkspaceFn = createServerFn({ method: "POST" })
 	.validator(createWorkspaceInputSchema)
 	.handler(async ({ data }) => createWorkspaceForCurrentUser(data));
diff --git a/src/features/workspaces/state/workspace-ai-composer-draft-store.ts b/src/features/workspaces/state/workspace-ai-composer-draft-store.ts
index 25620e53c..223965b0d 100644
--- a/src/features/workspaces/state/workspace-ai-composer-draft-store.ts
+++ b/src/features/workspaces/state/workspace-ai-composer-draft-store.ts
@@ -31,6 +31,13 @@ interface WorkspaceAiComposerDraftState {
 	filesByThreadId: Record<string, WorkspaceAiComposerDraftFile[] | undefined>;
 	quotesByWorkspaceId: Record<string, WorkspaceSelectedQuote[] | undefined>;
 	textByThreadId: Record<string, string | undefined>;
+	/**
+	 * Editable text staged into the composer from outside the composer component
+	 * (e.g. a document toolbar's "Add widget"). The composer consumes and clears
+	 * it on mount, appending it to whatever the user already typed; it is never
+	 * auto-sent.
+	 */
+	promptByWorkspaceId: Record<string, string | undefined>;
 	addFiles: (
 		workspaceId: string,
 		threadId: string,
@@ -40,9 +47,11 @@ interface WorkspaceAiComposerDraftState {
 	addQuote: (workspaceId: string, quote: WorkspaceSelectedQuote) => void;
 	clearDraftArtifacts: (workspaceId: string, threadId: string) => void;
 	clearFiles: (threadId: string) => void;
+	clearPrompt: (workspaceId: string) => void;
 	clearQuotes: (workspaceId: string) => void;
 	removeFile: (threadId: string, fileId: string) => void;
 	removeQuote: (workspaceId: string, quoteId: string) => void;
+	setPrompt: (workspaceId: string, text: string) => void;
 	setText: (threadId: string, value: SetStateAction<string>) => void;
 }
 
@@ -129,6 +138,7 @@ export const useWorkspaceAiComposerDraftStore = create<WorkspaceAiComposerDraftS
 		clearDraftArtifacts: (workspaceId, threadId) =>
 			set((state) => clearDraftArtifacts(state, workspaceId, threadId)),
 		clearFiles: (threadId) => set((state) => clearFilesForThread(state, threadId)),
+		clearPrompt: (workspaceId) => set((state) => clearPromptForWorkspace(state, workspaceId)),
 		clearQuotes: (workspaceId) =>
 			set((state) => {
 				const current = state.quotesByWorkspaceId[workspaceId] ?? EMPTY_DRAFT_QUOTES;
@@ -144,6 +154,7 @@ export const useWorkspaceAiComposerDraftStore = create<WorkspaceAiComposerDraftS
 				};
 			}),
 		filesByThreadId: {},
+		promptByWorkspaceId: {},
 		quotesByWorkspaceId: {},
 		removeFile: (threadId, fileId) => {
 			const file = get().filesByThreadId[threadId]?.find((item) => item.id === fileId);
@@ -167,6 +178,20 @@ export const useWorkspaceAiComposerDraftStore = create<WorkspaceAiComposerDraftS
 					},
 				};
 			}),
+		setPrompt: (workspaceId, text) =>
+			set((state) => {
+				const trimmed = text.trim();
+				if (!trimmed) {
+					return state;
+				}
+
+				return {
+					promptByWorkspaceId: {
+						...state.promptByWorkspaceId,
+						[workspaceId]: trimmed,
+					},
+				};
+			}),
 		setText: (threadId, value) =>
 			set((state) => {
 				const current = state.textByThreadId[threadId] ?? "";
@@ -216,17 +241,43 @@ export function useWorkspaceAiComposerDraftText(threadId: string) {
 	);
 }
 
+export function useWorkspaceAiComposerDraftPrompt(workspaceId: string) {
+	return useWorkspaceAiComposerDraftStore(
+		useMemo(
+			() => (state: WorkspaceAiComposerDraftState) => state.promptByWorkspaceId[workspaceId],
+			[workspaceId],
+		),
+	);
+}
+
 function clearDraftArtifacts(
 	state: WorkspaceAiComposerDraftState,
 	workspaceId: string,
 	threadId: string,
 ) {
-	return clearQuotesForWorkspace(
-		clearTextForThread(clearFilesForThread(state, threadId), threadId),
+	return clearPromptForWorkspace(
+		clearQuotesForWorkspace(
+			clearTextForThread(clearFilesForThread(state, threadId), threadId),
+			workspaceId,
+		),
 		workspaceId,
 	);
 }
 
+function clearPromptForWorkspace(state: WorkspaceAiComposerDraftState, workspaceId: string) {
+	if (state.promptByWorkspaceId[workspaceId] === undefined) {
+		return state;
+	}
+
+	return {
+		...state,
+		promptByWorkspaceId: {
+			...state.promptByWorkspaceId,
+			[workspaceId]: undefined,
+		},
+	};
+}
+
 function clearFilesForThread(state: WorkspaceAiComposerDraftState, threadId: string) {
 	const current = state.filesByThreadId[threadId] ?? EMPTY_DRAFT_FILES;
 	if (current.length === 0) {
diff --git a/src/features/workspaces/workspace-item-registry.ts b/src/features/workspaces/workspace-item-registry.ts
index 0efe8a95d..4a040354a 100644
--- a/src/features/workspaces/workspace-item-registry.ts
+++ b/src/features/workspaces/workspace-item-registry.ts
@@ -6,7 +6,11 @@ export type WorkspaceItemType = z.infer<typeof workspaceItemTypeSchema>;
 
 interface WorkspaceItemRegistryEntry {
 	color: "amber" | "emerald" | "rose" | "sky" | "violet";
-	contentKind: "document" | "empty" | "flashcard" | "quiz";
+	/**
+	 * Whether the create pipeline and AI create tool can materialise this type.
+	 * Files arrive by upload, and study types have no create flow yet.
+	 */
+	creatable: boolean;
 	defaultName: string;
 	extension: "json" | "txt" | null;
 	label: string;
@@ -19,7 +23,7 @@ interface WorkspaceItemRegistryEntry {
 const workspaceItemRegistry = {
 	folder: {
 		color: "amber",
-		contentKind: "empty",
+		creatable: true,
 		defaultName: "New folder",
 		extension: null,
 		label: "Folder",
@@ -29,7 +33,7 @@ const workspaceItemRegistry = {
 	},
 	document: {
 		color: "sky",
-		contentKind: "document",
+		creatable: true,
 		defaultName: "New document",
 		extension: "json",
 		label: "Document",
@@ -39,7 +43,7 @@ const workspaceItemRegistry = {
 	},
 	file: {
 		color: "rose",
-		contentKind: "empty",
+		creatable: false,
 		defaultName: "New file",
 		extension: "txt",
 		label: "File",
@@ -49,7 +53,7 @@ const workspaceItemRegistry = {
 	},
 	flashcard: {
 		color: "violet",
-		contentKind: "flashcard",
+		creatable: false,
 		defaultName: "New flashcards",
 		extension: "json",
 		label: "Flashcard deck",
@@ -59,7 +63,7 @@ const workspaceItemRegistry = {
 	},
 	quiz: {
 		color: "emerald",
-		contentKind: "quiz",
+		creatable: false,
 		defaultName: "New quiz",
 		extension: "json",
 		label: "Quiz",
@@ -73,6 +77,25 @@ export function getWorkspaceItemRegistryEntry(type: WorkspaceItemType) {
 	return workspaceItemRegistry[type];
 }
 
+/**
+ * The item types the create pipeline can materialise, per the registry.
+ *
+ * Derive from this rather than restating the list: every hand-copied version is
+ * a place a new type silently falls out of (a stale copy in the AI result
+ * adapter is what dropped widget citation refs).
+ */
+export type WorkspaceCreatableItemType = {
+	[Type in WorkspaceItemType]: (typeof workspaceItemRegistry)[Type]["creatable"] extends true
+		? Type
+		: never;
+}[WorkspaceItemType];
+
+export const workspaceCreatableItemTypes = workspaceItemTypes.filter(
+	(type): type is WorkspaceCreatableItemType => workspaceItemRegistry[type].creatable,
+) as [WorkspaceCreatableItemType, ...WorkspaceCreatableItemType[]];
+
+export const workspaceCreatableItemTypeSchema = z.enum(workspaceCreatableItemTypes);
+
 /** The item types workspace search indexes and filters on, per the registry. */
 export type WorkspaceSearchableItemType = {
 	[Type in WorkspaceItemType]: (typeof workspaceItemRegistry)[Type]["searchable"] extends true
diff --git a/src/styles.css b/src/styles.css
index ad2ec5a43..0a427356a 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -685,6 +685,80 @@
 		color: inherit;
 	}
 
+	/* An interactive widget block. The frame owns every click inside it, so the
+	   handle strip above is the only way to select, drag, or delete the widget. */
+	.workspace-document-prose .workspace-document-widget {
+		margin: 1rem 0;
+		border: 1px solid var(--border);
+		border-radius: var(--radius);
+		overflow: hidden;
+	}
+
+	.workspace-document-prose .workspace-document-widget[data-selected="true"] {
+		outline: 2px solid var(--ring);
+		outline-offset: 1px;
+	}
+
+	.workspace-document-prose .workspace-document-widget-handle {
+		display: flex;
+		align-items: center;
+		gap: 0.4rem;
+		border-bottom: 1px solid var(--border);
+		background: var(--muted);
+		padding: 0.3rem 0.6rem;
+		color: var(--muted-foreground);
+		font-size: 0.75rem;
+		cursor: grab;
+		user-select: none;
+	}
+
+	.workspace-document-prose .workspace-document-widget-frame {
+		height: 420px;
+	}
+
+	/* Collapsible sections. The Details node view renders a toggle button next to
+	   the summary and hides the content div, so it only needs layout here — the
+	   AI writes <details> and there is no toolbar affordance for inserting one. */
+	.workspace-document-prose details {
+		display: flex;
+		gap: 0.5rem;
+		margin: 0.85rem 0;
+		border: 1px solid var(--border);
+		border-radius: var(--radius);
+		padding: 0.65rem 0.85rem;
+	}
+
+	.workspace-document-prose details > button {
+		display: flex;
+		align-items: center;
+		align-self: flex-start;
+		justify-content: center;
+		width: 1.15rem;
+		height: 1.15rem;
+		border-radius: var(--radius-sm);
+		color: var(--muted-foreground);
+		cursor: pointer;
+		line-height: 1;
+	}
+
+	.workspace-document-prose details > button::before {
+		content: "▸";
+	}
+
+	.workspace-document-prose details.is-open > button::before {
+		content: "▾";
+	}
+
+	.workspace-document-prose details > div {
+		flex: 1 1 auto;
+		min-width: 0;
+	}
+
+	.workspace-document-prose details summary {
+		font-weight: 600;
+		list-style: none;
+	}
+
 	.workspace-document-prose [data-type="inline-math"] {
 		display: inline-flex;
 		align-items: baseline;

From 7622822f5bb75ad910124ca2fe932fa0528339fd Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Mon, 3 Aug 2026 23:51:37 -0400
Subject: [PATCH 02/32] fix(documents): stop a widget rendering its source as
 prose

---
 src/features/workspaces/documents/document-widget-node.tsx | 7 ++++++-
 src/styles.css                                             | 6 ++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/src/features/workspaces/documents/document-widget-node.tsx b/src/features/workspaces/documents/document-widget-node.tsx
index 4dfb0810d..fea56efb3 100644
--- a/src/features/workspaces/documents/document-widget-node.tsx
+++ b/src/features/workspaces/documents/document-widget-node.tsx
@@ -1,5 +1,5 @@
 import type { NodeViewProps } from "@tiptap/react";
-import { NodeViewWrapper, ReactNodeViewRenderer } from "@tiptap/react";
+import { NodeViewContent, NodeViewWrapper, ReactNodeViewRenderer } from "@tiptap/react";
 
 import { WorkspaceWidgetSandbox } from "#/features/workspaces/components/widget/WorkspaceWidgetSandbox";
 import { Widget } from "#/features/workspaces/documents/tiptap-schema";
@@ -39,6 +39,11 @@ function DocumentWidgetView({ node, selected }: NodeViewProps) {
 				<span>{title || "Widget"}</span>
 			</div>
 			<WorkspaceWidgetSandbox html={html} className="workspace-document-widget-frame" />
+			{/* A widget's source is its text content, so ProseMirror needs somewhere
+			    to render it. Without this element Tiptap appends one itself and the
+			    raw source shows up as prose in the document. It stays hidden: the
+			    source is the frame's input, not something to read in the page. */}
+			<NodeViewContent className="workspace-document-widget-source" />
 		</NodeViewWrapper>
 	);
 }
diff --git a/src/styles.css b/src/styles.css
index 0a427356a..8ebf497a5 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -716,6 +716,12 @@
 		height: 420px;
 	}
 
+	/* Holds the widget's source, which ProseMirror must render somewhere but the
+	   reader should never see. The frame is the visible form of this text. */
+	.workspace-document-prose .workspace-document-widget-source {
+		display: none;
+	}
+
 	/* Collapsible sections. The Details node view renders a toggle button next to
 	   the summary and hides the content div, so it only needs layout here — the
 	   AI writes <details> and there is no toolbar affordance for inserting one. */

From 3021fc0b07937b709670fb750fbe1c4523cfd8fe Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:06:15 -0400
Subject: [PATCH 03/32] fix(widgets): restore editor interaction and size to
 content

---
 .../ai/skills/widget-authoring/SKILL.md       | 11 +++--
 .../document-editor/DocumentEditorSurface.tsx | 24 +++++++---
 .../widget/WorkspaceWidgetSandbox.tsx         | 20 +++++++--
 .../workspace-widget-sandbox-document.ts      | 41 ++++++++++++++---
 .../documents/document-widget-node.tsx        | 44 ++++++++++++++-----
 .../workspaces/documents/tiptap-extensions.ts | 10 +++--
 .../model/use-workspace-item-path.ts          | 22 +++++++++-
 src/styles.css                                |  3 +-
 8 files changed, 139 insertions(+), 36 deletions(-)

diff --git a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
index 79cffb2dd..1b59b8952 100644
--- a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
+++ b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
@@ -23,7 +23,7 @@ Use **ordinary blocks** when the value is in _rich text_: notes, explanations, s
    `--background`, `--foreground`, `--card`, `--card-foreground`, `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--border`, `--input`, `--ring`, `--radius`.
    The sandbox toggles a `.dark` class on the root element when the app is in dark mode; because you use the variables, you rarely need to special-case `.dark` yourself.
 4. **No chrome of your own.** The block already draws a border and a title strip showing the `title` attribute, and the surrounding prose says what the widget is for. So do **not** repeat the title as a heading, and do **not** wrap everything in an outer bordered/rounded panel. Start straight into the content. Borders and `var(--card)` backgrounds are for genuinely separate sub-regions (a stat tile, a chart panel), never the outer shell. One short line of instructions is fine when it says something the title doesn't.
-5. **Fill the frame.** The block is a fixed 420px tall. Your HTML goes directly in `<body>`, which is `height: 100%`, so put `height: 100%` on your root and design for that height rather than assuming the page will grow. Do **not** cap the width with `max-width`, centre it with `margin: auto`, or leave wide outer gutters; that strands the content in dead space. Modest padding (about 16px) is enough. Let the main visual area grow with `flex: 1` (a flex child that must shrink also needs `min-height: 0`). Anything taller scrolls inside the frame, so keep the primary controls visible without scrolling.
+5. **Let the height come from your content.** The block measures what you render and sizes itself to match, between 120px and 720px; past that it scrolls. So do **not** set `height: 100%` on your root — there is no fixed frame to fill, and it will collapse. Give any element that has no natural height — a `<canvas>`, a chart area, a map — an explicit height in px, and let everything else flow. Do **not** cap the width with `max-width`, centre it with `margin: auto`, or add outer padding; the frame already provides a gutter that scales with its width, and anything on top of it strands the content in dead space. Keep a widget to roughly one screenful: a compact layout beats one the reader has to scroll inside.
 6. **Fail loudly, not silently.** If something can error, let it throw — the sandbox catches runtime errors and offers the user an "Ask AI to fix" button that sends the error back to you.
 
 ## Starter template
@@ -33,8 +33,6 @@ Note what is _absent_: no title, no outer panel. The content starts immediately.
 ```html
 <style>
 	.tx-root {
-		height: 100%;
-		padding: 16px;
 		display: flex;
 		flex-direction: column;
 		gap: 12px;
@@ -88,10 +86,11 @@ Always size the backing store from the measured layout box, account for device p
 
 ```html
 <style>
+	/* An explicit height: the block sizes itself to the content, so a canvas
+	   with only a percentage height would measure zero and never appear. */
 	.chart-wrap {
-		flex: 1;
-		min-height: 0;
-	} /* min-height:0 lets a flex child actually shrink */
+		height: 320px;
+	}
 	canvas {
 		display: block;
 		width: 100%;
diff --git a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
index e27bbe579..54b772c4f 100644
--- a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
+++ b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
@@ -1,10 +1,11 @@
 import Collaboration from "@tiptap/extension-collaboration";
 import CollaborationCaret from "@tiptap/extension-collaboration-caret";
 import { EditorContent, useEditor } from "@tiptap/react";
-import { useQuery } from "@tanstack/react-query";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useState } from "react";
 
 import { Skeleton } from "#/components/ui/skeleton";
+import { stageComposerPrompt } from "#/features/workspaces/composer/workspace-composer-actions";
 import { DocumentAskSelectionMenu } from "#/features/workspaces/components/document-editor/DocumentAskSelectionMenu";
 import { DocumentWordCount } from "#/features/workspaces/components/document-editor/DocumentWordCount";
 import { useDocumentEditorToolbar } from "#/features/workspaces/components/WorkspaceItemToolbarSlot";
@@ -21,7 +22,10 @@ import {
 } from "#/features/workspaces/documents/use-document-collaboration-session";
 import { useDocumentEditReviewOverlay } from "#/features/workspaces/documents/use-document-edit-review-overlay";
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
-import { useWorkspaceItemPath } from "#/features/workspaces/model/use-workspace-item-path";
+import {
+	readWorkspaceItemPath,
+	useWorkspaceItemPath,
+} from "#/features/workspaces/model/use-workspace-item-path";
 import { DEFAULT_COLLABORATION_COLOR } from "#/lib/design-system-colors";
 import { getAuthSessionQueryOptions } from "#/lib/session-query";
 
@@ -72,6 +76,7 @@ function DocumentEditorInstance({
 	const { capabilities } = useWorkspaceMutationAccess();
 	const documentPath = useWorkspaceItemPath(workspaceId, item);
 	const paneRuntime = useWorkspacePaneRuntime();
+	const queryClient = useQueryClient();
 	const [scrollTarget, setScrollTarget] = useState<HTMLDivElement | null>(null);
 	const editor = useEditor({
 		immediatelyRender: false,
@@ -81,7 +86,13 @@ function DocumentEditorInstance({
 		onContentError: ({ disableCollaboration }) => {
 			disableCollaboration();
 		},
-		extensions: getDocumentEditorExtensions(collaborationSession),
+		extensions: getDocumentEditorExtensions(collaborationSession, {
+			onAskAiToFixWidget: (error) =>
+				stageComposerPrompt(
+					workspaceId,
+					`A widget in ${readWorkspaceItemPath(queryClient, workspaceId, item) ?? item.name} hit this error — please fix it:\n\n${error}`,
+				),
+		}),
 		editorProps: {
 			attributes: {
 				"aria-label": capabilities.canMutateContent
@@ -134,8 +145,11 @@ function DocumentEditorInstance({
 	);
 }
 
-function getDocumentEditorExtensions(collaborationSession: DocumentCollaborationSession) {
-	const baseExtensions = getTiptapDocumentBaseExtensions();
+function getDocumentEditorExtensions(
+	collaborationSession: DocumentCollaborationSession,
+	options: { onAskAiToFixWidget: (error: string) => void },
+) {
+	const baseExtensions = getTiptapDocumentBaseExtensions(options);
 
 	return [
 		...baseExtensions,
diff --git a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
index 56c31a52d..0138ea377 100644
--- a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
+++ b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
@@ -6,6 +6,8 @@ import { Button } from "#/components/ui/button";
 import {
 	buildWidgetSandboxDocument,
 	isWidgetSandboxFrameMessage,
+	WIDGET_SANDBOX_MAX_HEIGHT,
+	WIDGET_SANDBOX_MIN_HEIGHT,
 	WIDGET_SANDBOX_TOKENS,
 } from "#/features/workspaces/components/widget/workspace-widget-sandbox-document";
 import { cn } from "#/lib/utils";
@@ -36,6 +38,7 @@ export function WorkspaceWidgetSandbox({
 	const iframeRef = useRef<HTMLIFrameElement>(null);
 	const [srcDoc, setSrcDoc] = useState<string | null>(null);
 	const [error, setError] = useState<string | null>(null);
+	const [height, setHeight] = useState(WIDGET_SANDBOX_MIN_HEIGHT);
 
 	// Build the sandbox document from the authored HTML plus the host's resolved
 	// design tokens (read from the live root). Rebuilding on theme change or edit
@@ -71,9 +74,18 @@ export function WorkspaceWidgetSandbox({
 			}
 			if (event.data.kind === "error") {
 				setError(event.data.message);
-			} else {
-				setError(null);
+				return;
+			}
+			if (event.data.kind === "height") {
+				setHeight(
+					Math.min(
+						WIDGET_SANDBOX_MAX_HEIGHT,
+						Math.max(WIDGET_SANDBOX_MIN_HEIGHT, event.data.height),
+					),
+				);
+				return;
 			}
+			setError(null);
 		}
 
 		window.addEventListener("message", onMessage);
@@ -81,7 +93,9 @@ export function WorkspaceWidgetSandbox({
 	}, []);
 
 	return (
-		<div className={cn("relative h-full min-h-0 bg-background", className)}>
+		// Height comes from the frame's own content, so the block takes the room
+		// the widget needs instead of a number chosen here.
+		<div className={cn("relative bg-background", className)} style={{ height }}>
 			<iframe
 				ref={iframeRef}
 				title="Widget preview"
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
index 88af90f79..2ca57e0c9 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
@@ -19,13 +19,23 @@
 
 /** Host → frame messages (theme updates). */
 export const WIDGET_SANDBOX_HOST_SOURCE = "thinkex-widget-host" as const;
-/** Frame → host messages (ready / runtime errors). */
+/** Frame → host messages (ready / height / runtime errors). */
 export const WIDGET_SANDBOX_FRAME_SOURCE = "thinkex-widget-frame" as const;
 
 export type WidgetSandboxFrameMessage =
 	| { source: typeof WIDGET_SANDBOX_FRAME_SOURCE; kind: "ready" }
+	| { source: typeof WIDGET_SANDBOX_FRAME_SOURCE; kind: "height"; height: number }
 	| { source: typeof WIDGET_SANDBOX_FRAME_SOURCE; kind: "error"; message: string };
 
+/**
+ * Bounds on a widget's reported height. A widget sits in the flow of a
+ * document, so it should take the room it needs and no more: a four-line
+ * converter should not reserve a screenful, and a tall explorer should not be
+ * cut off. Past the maximum the widget scrolls inside its own frame.
+ */
+export const WIDGET_SANDBOX_MIN_HEIGHT = 120;
+export const WIDGET_SANDBOX_MAX_HEIGHT = 720;
+
 /**
  * Semantic design tokens copied from the host into the frame. Kept to a curated
  * set — enough for widgets to feel native without leaking the entire cascade.
@@ -117,10 +127,11 @@ export function buildWidgetSandboxDocument({
 	// Bad expressions render muted in place rather than throwing, so one
 	// malformed formula never takes the whole widget down.
 	//
-	// The base stylesheet sets a definite height chain and nothing else: widgets
-	// fill the frame with `height: 100%`, and a percentage height only resolves
-	// against a parent with a definite height. Layout beyond that belongs to the
-	// widget — host-side centring or max-widths just strand it in dead space.
+	// The base stylesheet deliberately sets no height. The frame reports what its
+	// content measures and the host sizes the block to match, so a widget takes
+	// the room it needs rather than a number picked here. Layout beyond that
+	// belongs to the widget — host-side centring or max-widths strand it in dead
+	// space.
 	return `<!doctype html>
 <html lang="en"${theme === "dark" ? ' class="dark"' : ""}>
 <head>
@@ -130,7 +141,9 @@ export function buildWidgetSandboxDocument({
 ${katexTags}
 <style>
 :root{${tokenDeclarations}color-scheme:${theme};}
-html,body{margin:0;padding:0;height:100%;background:var(--background);color:var(--foreground);font-family:ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;}
+html,body{margin:0;background:var(--background);color:var(--foreground);font-family:ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;}
+html{padding:0;}
+body{padding:clamp(10px,2.5%,16px);}
 *,*::before,*::after{box-sizing:border-box;}
 </style>
 </head>
@@ -176,6 +189,20 @@ ${html}
       document.documentElement.style.colorScheme=data.theme;
     }
   });
+  var lastHeight=0;
+  function measure(){
+    // scrollHeight over getBoundingClientRect: it accounts for margins that
+    // escape the body box, which would otherwise report short and clip.
+    var height=Math.ceil(Math.max(document.documentElement.scrollHeight,document.body.scrollHeight));
+    if(!height||Math.abs(height-lastHeight)<2)return;
+    lastHeight=height;
+    post({source:FRAME,kind:"height",height:height});
+  }
+  if(typeof ResizeObserver==="function"){
+    new ResizeObserver(measure).observe(document.body);
+  }
+  window.addEventListener("load",measure);
+  measure();
   post({source:FRAME,kind:"ready"});
 })();
 </script>
@@ -191,6 +218,6 @@ export function isWidgetSandboxFrameMessage(value: unknown): value is WidgetSand
 	const message = value as { source?: unknown; kind?: unknown };
 	return (
 		message.source === WIDGET_SANDBOX_FRAME_SOURCE &&
-		(message.kind === "ready" || message.kind === "error")
+		(message.kind === "ready" || message.kind === "error" || message.kind === "height")
 	);
 }
diff --git a/src/features/workspaces/documents/document-widget-node.tsx b/src/features/workspaces/documents/document-widget-node.tsx
index fea56efb3..66b3e0fb5 100644
--- a/src/features/workspaces/documents/document-widget-node.tsx
+++ b/src/features/workspaces/documents/document-widget-node.tsx
@@ -4,28 +4,44 @@ import { NodeViewContent, NodeViewWrapper, ReactNodeViewRenderer } from "@tiptap
 import { WorkspaceWidgetSandbox } from "#/features/workspaces/components/widget/WorkspaceWidgetSandbox";
 import { Widget } from "#/features/workspaces/documents/tiptap-schema";
 
+export interface DocumentWidgetOptions {
+	/**
+	 * Called with a crashed widget's error text so the surface can offer a way
+	 * out. Left unset the affordance is hidden, which is right for any read-only
+	 * rendering of a document.
+	 */
+	onAskAiToFix: ((error: string) => void) | null;
+}
+
 /**
  * The editor's widget: the authored HTML running in its sandboxed frame.
  *
- * Three things keep ProseMirror and the frame out of each other's way.
- * `contentEditable={false}` stops a click inside the widget being read as a text
- * selection. `stopEvent` keeps events raised inside the node view from reaching
- * the editor at all. `ignoreMutation` stops the editor re-parsing when the frame
- * changes its own DOM — selection mutations still pass through, so clicking away
- * from the widget behaves normally.
+ * The frame is a separate document, so its own events never reach the editor and
+ * there is nothing to suppress. What does reach the editor is a click or drag on
+ * the handle, and those have to get through: they are how the widget is selected,
+ * deleted and moved. Tiptap's default `stopEvent` already lets exactly those
+ * through for a selectable, draggable node, so overriding it only breaks them.
+ *
+ * `contentEditable={false}` still stops a click being read as a text selection,
+ * and `ignoreMutation` stops the editor re-parsing when React re-renders the
+ * handle — selection mutations pass through so clicking away behaves normally.
  */
-export const DocumentWidget = Widget.extend({
+export const DocumentWidget = Widget.extend<DocumentWidgetOptions>({
+	addOptions() {
+		return { onAskAiToFix: null };
+	},
+
 	addNodeView() {
 		return ReactNodeViewRenderer(DocumentWidgetView, {
-			stopEvent: () => true,
 			ignoreMutation: ({ mutation }) => mutation.type !== "selection",
 		});
 	},
 });
 
-function DocumentWidgetView({ node, selected }: NodeViewProps) {
+function DocumentWidgetView({ extension, node, selected }: NodeViewProps) {
 	const html = node.textContent;
 	const title = typeof node.attrs.title === "string" ? node.attrs.title : "";
+	const { onAskAiToFix } = extension.options as DocumentWidgetOptions;
 
 	return (
 		<NodeViewWrapper
@@ -38,7 +54,15 @@ function DocumentWidgetView({ node, selected }: NodeViewProps) {
 			<div className="workspace-document-widget-handle" data-drag-handle contentEditable={false}>
 				<span>{title || "Widget"}</span>
 			</div>
-			<WorkspaceWidgetSandbox html={html} className="workspace-document-widget-frame" />
+			<WorkspaceWidgetSandbox
+				html={html}
+				className="workspace-document-widget-frame"
+				onAskAiToFix={
+					onAskAiToFix
+						? (error) => onAskAiToFix(title ? `the "${title}" widget: ${error}` : error)
+						: undefined
+				}
+			/>
 			{/* A widget's source is its text content, so ProseMirror needs somewhere
 			    to render it. Without this element Tiptap appends one itself and the
 			    raw source shows up as prose in the document. It stays hidden: the
diff --git a/src/features/workspaces/documents/tiptap-extensions.ts b/src/features/workspaces/documents/tiptap-extensions.ts
index edd17ce0e..81a13818d 100644
--- a/src/features/workspaces/documents/tiptap-extensions.ts
+++ b/src/features/workspaces/documents/tiptap-extensions.ts
@@ -14,13 +14,17 @@ import {
 
 export { tiptapDocumentYjsField };
 
-export function getTiptapDocumentBaseExtensions() {
+export function getTiptapDocumentBaseExtensions(
+	options: { onAskAiToFixWidget?: (error: string) => void } = {},
+) {
 	return [
 		...getTiptapDocumentSchemaExtensions({
-			// Both extend the node spec the server uses, adding only how it draws.
+			// All three extend the node spec the server uses, adding only how it draws.
 			citation: DocumentCitation,
 			codeBlock: CodeBlockShiki,
-			widget: DocumentWidget,
+			widget: DocumentWidget.configure({
+				onAskAiToFix: options.onAskAiToFixWidget ?? null,
+			}),
 		}),
 		Placeholder.configure({
 			placeholder: ({ node }) => (node.type.name === "heading" ? "Untitled" : "Write something..."),
diff --git a/src/features/workspaces/model/use-workspace-item-path.ts b/src/features/workspaces/model/use-workspace-item-path.ts
index 59f070fc3..cbbe85c07 100644
--- a/src/features/workspaces/model/use-workspace-item-path.ts
+++ b/src/features/workspaces/model/use-workspace-item-path.ts
@@ -1,4 +1,4 @@
-import { useQuery } from "@tanstack/react-query";
+import { type QueryClient, useQuery } from "@tanstack/react-query";
 import { useMemo } from "react";
 
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
@@ -24,3 +24,23 @@ export function useWorkspaceItemPath(workspaceId: string, item: WorkspaceItem |
 		return getWorkspaceAiContextItemPath(item, new Map(items.map((entry) => [entry.id, entry])));
 	}, [item, items]);
 }
+
+/**
+ * The same path, read imperatively at call time.
+ *
+ * For callbacks that outlive the render that created them — a Tiptap extension
+ * option, say — where capturing the path would pin whatever was known when the
+ * editor was built, which is usually nothing.
+ */
+export function readWorkspaceItemPath(
+	queryClient: QueryClient,
+	workspaceId: string,
+	item: WorkspaceItem,
+) {
+	const page = queryClient.getQueryData(workspacePageQueryOptions(workspaceId).queryKey);
+	if (!page) {
+		return null;
+	}
+
+	return getWorkspaceAiContextItemPath(item, new Map(page.items.map((entry) => [entry.id, entry])));
+}
diff --git a/src/styles.css b/src/styles.css
index 8ebf497a5..74a184d8c 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -712,8 +712,9 @@
 		user-select: none;
 	}
 
+	/* No height here: the frame measures its own content and sizes itself. */
 	.workspace-document-prose .workspace-document-widget-frame {
-		height: 420px;
+		width: 100%;
 	}
 
 	/* Holds the widget's source, which ProseMirror must render somewhere but the

From 930fd6d2240b18f0b2dcdcb8770cc5337c77c569 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:07:54 -0400
Subject: [PATCH 04/32] feat(documents): give documents a readable text measure

---
 .../workspaces/ai/skills/widget-authoring/SKILL.md    |  2 +-
 src/styles.css                                        | 11 +++++++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
index 1b59b8952..4da2b2aa9 100644
--- a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
+++ b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
@@ -23,7 +23,7 @@ Use **ordinary blocks** when the value is in _rich text_: notes, explanations, s
    `--background`, `--foreground`, `--card`, `--card-foreground`, `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--border`, `--input`, `--ring`, `--radius`.
    The sandbox toggles a `.dark` class on the root element when the app is in dark mode; because you use the variables, you rarely need to special-case `.dark` yourself.
 4. **No chrome of your own.** The block already draws a border and a title strip showing the `title` attribute, and the surrounding prose says what the widget is for. So do **not** repeat the title as a heading, and do **not** wrap everything in an outer bordered/rounded panel. Start straight into the content. Borders and `var(--card)` backgrounds are for genuinely separate sub-regions (a stat tile, a chart panel), never the outer shell. One short line of instructions is fine when it says something the title doesn't.
-5. **Let the height come from your content.** The block measures what you render and sizes itself to match, between 120px and 720px; past that it scrolls. So do **not** set `height: 100%` on your root — there is no fixed frame to fill, and it will collapse. Give any element that has no natural height — a `<canvas>`, a chart area, a map — an explicit height in px, and let everything else flow. Do **not** cap the width with `max-width`, centre it with `margin: auto`, or add outer padding; the frame already provides a gutter that scales with its width, and anything on top of it strands the content in dead space. Keep a widget to roughly one screenful: a compact layout beats one the reader has to scroll inside.
+5. **Let the height come from your content.** The block measures what you render and sizes itself to match, between 120px and 720px; past that it scrolls. So do **not** set `height: 100%` on your root — there is no fixed frame to fill, and it will collapse. Give any element that has no natural height — a `<canvas>`, a chart area, a map — an explicit height in px, and let everything else flow. Do **not** cap the width with `max-width`, centre it with `margin: auto`, or add outer padding. The frame is already the width of the document's text column and already provides a gutter, so anything on top of that only strands the content in dead space. Keep a widget to roughly one screenful: a compact layout beats one the reader has to scroll inside.
 6. **Fail loudly, not silently.** If something can error, let it throw — the sandbox catches runtime errors and offers the user an "Ask AI to fix" button that sends the error back to you.
 
 ## Starter template
diff --git a/src/styles.css b/src/styles.css
index 74a184d8c..a6bf27bca 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -497,6 +497,7 @@
 	}
 
 	.workspace-document-prose {
+		--workspace-document-measure: 72ch;
 		--workspace-document-code-background: var(--muted);
 		--workspace-document-highlight: oklch(0.9 0.14 90 / 70%);
 		--workspace-document-highlight-foreground: oklch(0.2 0.05 78);
@@ -556,6 +557,16 @@
 		--workspace-document-highlight-foreground: var(--foreground);
 	}
 
+	/*
+	 * A readable measure, applied to the blocks rather than the editable element
+	 * so the whole pane still focuses the editor on click. Widgets take the same
+	 * width as the prose around them, so nothing reads as a narrower island.
+	 */
+	.workspace-document-prose > * {
+		margin-inline: auto;
+		max-width: var(--workspace-document-measure);
+	}
+
 	.workspace-document-prose > * + * {
 		margin-top: 0.85rem;
 	}

From 34f2f6ba9a13a2b70e522a76a1f2b278ef1aff4c Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:11:25 -0400
Subject: [PATCH 05/32] fix(documents): correct the text measure and widget
 theming

---
 .../document-editor/DocumentEditorSurface.tsx |  2 +-
 .../widget/WorkspaceWidgetSandbox.tsx         | 38 +++++++++++--------
 .../workspace-widget-sandbox-document.ts      | 19 +++-------
 src/styles.css                                | 21 +++++-----
 4 files changed, 38 insertions(+), 42 deletions(-)

diff --git a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
index 54b772c4f..d27cceda9 100644
--- a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
+++ b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
@@ -98,7 +98,7 @@ function DocumentEditorInstance({
 				"aria-label": capabilities.canMutateContent
 					? `${item.name} editor`
 					: `${item.name} document`,
-				class: "workspace-document-prose min-h-full p-4 outline-none",
+				class: "workspace-document-prose min-h-full py-4 outline-none",
 			},
 			handleKeyDown: (_view, event) => {
 				if (event.key !== "Escape" || !paneRuntime?.onCloseItemView) {
diff --git a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
index 0138ea377..f2b7d5a79 100644
--- a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
+++ b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
@@ -41,24 +41,30 @@ export function WorkspaceWidgetSandbox({
 	const [height, setHeight] = useState(WIDGET_SANDBOX_MIN_HEIGHT);
 
 	// Build the sandbox document from the authored HTML plus the host's resolved
-	// design tokens (read from the live root). Rebuilding on theme change or edit
-	// is a fresh render, so the previous error clears with it. State is set in a
-	// frame callback, not synchronously, to keep the effect render-safe.
+	// design tokens. Rebuilding on theme change or edit is a fresh render, so the
+	// previous error clears with it.
+	//
+	// Everything happens in a frame callback, which also keeps the effect
+	// render-safe. The tokens have to be read there rather than here: the theme
+	// provider applies the `.dark` class in its own effect, and React runs a
+	// child's effects before its parents', so reading now would take the previous
+	// theme's values and pair them with the new theme's class.
 	useEffect(() => {
-		const style = getComputedStyle(document.documentElement);
-		const tokens: Record<string, string> = {};
-		for (const name of WIDGET_SANDBOX_TOKENS) {
-			tokens[name] = style.getPropertyValue(name).trim();
-		}
-		const nextDoc = buildWidgetSandboxDocument({
-			html,
-			theme: resolvedTheme,
-			tokens,
-			origin: window.location.origin,
-		});
-
 		const frame = requestAnimationFrame(() => {
-			setSrcDoc(nextDoc);
+			const style = getComputedStyle(document.documentElement);
+			const tokens: Record<string, string> = {};
+			for (const name of WIDGET_SANDBOX_TOKENS) {
+				tokens[name] = style.getPropertyValue(name).trim();
+			}
+
+			setSrcDoc(
+				buildWidgetSandboxDocument({
+					html,
+					theme: resolvedTheme,
+					tokens,
+					origin: window.location.origin,
+				}),
+			);
 			setError(null);
 		});
 		return () => cancelAnimationFrame(frame);
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
index 2ca57e0c9..ba12efe45 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
@@ -9,16 +9,15 @@
  * remove its own sandbox.
  *
  * Two things are composed around the authored HTML:
- *  - a theme layer: the resolved design tokens (read from the host at build
- *    time) are injected as CSS variables so widgets look native, plus a `.dark`
- *    class toggled from the passed theme.
+ *  - a theme layer: the resolved design tokens (read from the host when this
+ *    document is built) are injected as CSS variables so widgets look native,
+ *    plus a `.dark` class from the passed theme. A theme change rebuilds the
+ *    document, so there is no host-to-frame channel to keep in sync.
  *  - an error harness: window `error` / `unhandledrejection` are forwarded to
  *    the host via postMessage so a crashed widget surfaces an "Ask AI to fix"
  *    affordance instead of a silent blank frame.
  */
 
-/** Host → frame messages (theme updates). */
-export const WIDGET_SANDBOX_HOST_SOURCE = "thinkex-widget-host" as const;
 /** Frame → host messages (ready / height / runtime errors). */
 export const WIDGET_SANDBOX_FRAME_SOURCE = "thinkex-widget-frame" as const;
 
@@ -151,7 +150,7 @@ body{padding:clamp(10px,2.5%,16px);}
 ${html}
 <script>
 (function(){
-  var HOST="${WIDGET_SANDBOX_HOST_SOURCE}",FRAME="${WIDGET_SANDBOX_FRAME_SOURCE}";
+  var FRAME="${WIDGET_SANDBOX_FRAME_SOURCE}";
   function post(message){ try{ parent.postMessage(message,"*"); }catch(_){} }
   function report(message){ post({source:FRAME,kind:"error",message:String(message)}); }
   window.addEventListener("error",function(event){
@@ -181,14 +180,6 @@ ${html}
     var reason=event.reason;
     report("Unhandled promise rejection: "+((reason&&reason.stack)||reason));
   });
-  window.addEventListener("message",function(event){
-    var data=event.data;
-    if(!data||data.source!==HOST)return;
-    if(data.type==="theme"){
-      document.documentElement.classList.toggle("dark",data.theme==="dark");
-      document.documentElement.style.colorScheme=data.theme;
-    }
-  });
   var lastHeight=0;
   function measure(){
     // scrollHeight over getBoundingClientRect: it accounts for margins that
diff --git a/src/styles.css b/src/styles.css
index a6bf27bca..c5608d25f 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -497,7 +497,16 @@
 	}
 
 	.workspace-document-prose {
-		--workspace-document-measure: 72ch;
+		/*
+		 * A readable measure, held by the container's own padding rather than a
+		 * max-width on each block. Blocks set margin shorthand (widgets, tables,
+		 * rules, block math all do), which would reset any inline auto-margin and
+		 * strand them left of the text. Padding cannot be overridden that way, and
+		 * the editable element stays full width so a click anywhere still focuses
+		 * the editor.
+		 */
+		--workspace-document-measure: 80ch;
+		padding-inline: max(1rem, calc((100% - var(--workspace-document-measure)) / 2));
 		--workspace-document-code-background: var(--muted);
 		--workspace-document-highlight: oklch(0.9 0.14 90 / 70%);
 		--workspace-document-highlight-foreground: oklch(0.2 0.05 78);
@@ -557,16 +566,6 @@
 		--workspace-document-highlight-foreground: var(--foreground);
 	}
 
-	/*
-	 * A readable measure, applied to the blocks rather than the editable element
-	 * so the whole pane still focuses the editor on click. Widgets take the same
-	 * width as the prose around them, so nothing reads as a narrower island.
-	 */
-	.workspace-document-prose > * {
-		margin-inline: auto;
-		max-width: var(--workspace-document-measure);
-	}
-
 	.workspace-document-prose > * + * {
 		margin-top: 0.85rem;
 	}

From a739558ca88e69e342efc437fa67b0f1831979d0 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:15:05 -0400
Subject: [PATCH 06/32] feat(documents): share block chrome and add widget
 fullscreen

---
 .../ai/skills/widget-authoring/SKILL.md       |   2 +-
 .../widget/WorkspaceWidgetSandbox.tsx         |  11 +-
 .../documents/document-widget-node.tsx        | 112 +++++++++++++++---
 src/styles.css                                |  12 +-
 4 files changed, 110 insertions(+), 27 deletions(-)

diff --git a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
index 4da2b2aa9..49969378b 100644
--- a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
+++ b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
@@ -23,7 +23,7 @@ Use **ordinary blocks** when the value is in _rich text_: notes, explanations, s
    `--background`, `--foreground`, `--card`, `--card-foreground`, `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--border`, `--input`, `--ring`, `--radius`.
    The sandbox toggles a `.dark` class on the root element when the app is in dark mode; because you use the variables, you rarely need to special-case `.dark` yourself.
 4. **No chrome of your own.** The block already draws a border and a title strip showing the `title` attribute, and the surrounding prose says what the widget is for. So do **not** repeat the title as a heading, and do **not** wrap everything in an outer bordered/rounded panel. Start straight into the content. Borders and `var(--card)` backgrounds are for genuinely separate sub-regions (a stat tile, a chart panel), never the outer shell. One short line of instructions is fine when it says something the title doesn't.
-5. **Let the height come from your content.** The block measures what you render and sizes itself to match, between 120px and 720px; past that it scrolls. So do **not** set `height: 100%` on your root — there is no fixed frame to fill, and it will collapse. Give any element that has no natural height — a `<canvas>`, a chart area, a map — an explicit height in px, and let everything else flow. Do **not** cap the width with `max-width`, centre it with `margin: auto`, or add outer padding. The frame is already the width of the document's text column and already provides a gutter, so anything on top of that only strands the content in dead space. Keep a widget to roughly one screenful: a compact layout beats one the reader has to scroll inside.
+5. **Let the height come from your content.** The block measures what you render and sizes itself to match, between 120px and 720px; past that it scrolls. So do **not** set `height: 100%` on your root — there is no fixed frame to fill, and it will collapse. Give any element that has no natural height — a `<canvas>`, a chart area, a map — an explicit height in px, and let everything else flow. Do **not** cap the width with `max-width`, centre it with `margin: auto`, or add outer padding. The frame is already the width of the document's text column and already provides a gutter, so anything on top of that only strands the content in dead space. Keep a widget to roughly one screenful: a compact layout beats one the reader has to scroll inside. Taller widgets still work — the reader can open any widget fullscreen — but the inline block is what they see first.
 6. **Fail loudly, not silently.** If something can error, let it throw — the sandbox catches runtime errors and offers the user an "Ask AI to fix" button that sends the error back to you.
 
 ## Starter template
diff --git a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
index f2b7d5a79..b458c81bf 100644
--- a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
+++ b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
@@ -15,6 +15,11 @@ import { cn } from "#/lib/utils";
 type WorkspaceWidgetSandboxProps = {
 	html: string;
 	className?: string;
+	/**
+	 * Fill the available space instead of sizing to the widget's own content.
+	 * For the fullscreen view, where the container decides the height.
+	 */
+	fill?: boolean;
 	/**
 	 * Called with the runtime error text when the user asks the AI to fix a
 	 * crashed widget. Omit to hide the affordance.
@@ -32,6 +37,7 @@ type WorkspaceWidgetSandboxProps = {
 export function WorkspaceWidgetSandbox({
 	html,
 	className,
+	fill = false,
 	onAskAiToFix,
 }: WorkspaceWidgetSandboxProps) {
 	const { resolvedTheme } = useTheme();
@@ -101,7 +107,10 @@ export function WorkspaceWidgetSandbox({
 	return (
 		// Height comes from the frame's own content, so the block takes the room
 		// the widget needs instead of a number chosen here.
-		<div className={cn("relative bg-background", className)} style={{ height }}>
+		<div
+			className={cn("relative bg-background", fill && "h-full", className)}
+			style={fill ? undefined : { height }}
+		>
 			<iframe
 				ref={iframeRef}
 				title="Widget preview"
diff --git a/src/features/workspaces/documents/document-widget-node.tsx b/src/features/workspaces/documents/document-widget-node.tsx
index 66b3e0fb5..c080de173 100644
--- a/src/features/workspaces/documents/document-widget-node.tsx
+++ b/src/features/workspaces/documents/document-widget-node.tsx
@@ -1,6 +1,16 @@
 import type { NodeViewProps } from "@tiptap/react";
 import { NodeViewContent, NodeViewWrapper, ReactNodeViewRenderer } from "@tiptap/react";
+import { Maximize2, Minimize2, Shapes } from "lucide-react";
+import { useState } from "react";
 
+import {
+	CodeBlockActions,
+	CodeBlockHeader,
+	CodeBlockLabel,
+	CodeBlockTitle,
+} from "#/components/code-block/code-block-chrome";
+import { Button } from "#/components/ui/button";
+import { Dialog, DialogContent, DialogTitle } from "#/components/ui/dialog";
 import { WorkspaceWidgetSandbox } from "#/features/workspaces/components/widget/WorkspaceWidgetSandbox";
 import { Widget } from "#/features/workspaces/documents/tiptap-schema";
 
@@ -18,13 +28,13 @@ export interface DocumentWidgetOptions {
  *
  * The frame is a separate document, so its own events never reach the editor and
  * there is nothing to suppress. What does reach the editor is a click or drag on
- * the handle, and those have to get through: they are how the widget is selected,
+ * the header, and those have to get through: they are how the widget is selected,
  * deleted and moved. Tiptap's default `stopEvent` already lets exactly those
  * through for a selectable, draggable node, so overriding it only breaks them.
  *
  * `contentEditable={false}` still stops a click being read as a text selection,
  * and `ignoreMutation` stops the editor re-parsing when React re-renders the
- * handle — selection mutations pass through so clicking away behaves normally.
+ * header — selection mutations pass through so clicking away behaves normally.
  */
 export const DocumentWidget = Widget.extend<DocumentWidgetOptions>({
 	addOptions() {
@@ -42,6 +52,11 @@ function DocumentWidgetView({ extension, node, selected }: NodeViewProps) {
 	const html = node.textContent;
 	const title = typeof node.attrs.title === "string" ? node.attrs.title : "";
 	const { onAskAiToFix } = extension.options as DocumentWidgetOptions;
+	const [isFullscreen, setIsFullscreen] = useState(false);
+	const label = title || "Widget";
+	const askAiToFix = onAskAiToFix
+		? (error: string) => onAskAiToFix(title ? `the "${title}" widget: ${error}` : error)
+		: undefined;
 
 	return (
 		<NodeViewWrapper
@@ -49,25 +64,90 @@ function DocumentWidgetView({ extension, node, selected }: NodeViewProps) {
 			contentEditable={false}
 			data-selected={selected ? "true" : undefined}
 		>
-			{/* The only editor-owned affordance: without it there is no way to pick
-			    the widget up or delete it, since clicks go to the frame. */}
-			<div className="workspace-document-widget-handle" data-drag-handle contentEditable={false}>
-				<span>{title || "Widget"}</span>
-			</div>
-			<WorkspaceWidgetSandbox
-				html={html}
-				className="workspace-document-widget-frame"
-				onAskAiToFix={
-					onAskAiToFix
-						? (error) => onAskAiToFix(title ? `the "${title}" widget: ${error}` : error)
-						: undefined
-				}
-			/>
+			{/* Shared block chrome, as the code block and Mermaid diagram use, so
+			    every embedded block in a document reads as the same kind of thing.
+			    It doubles as the drag handle: without it there is no way to pick the
+			    widget up or delete it, since clicks inside go to the frame. */}
+			<CodeBlockHeader
+				className="workspace-document-widget-header min-h-10"
+				data-drag-handle
+				contentEditable={false}
+			>
+				<CodeBlockTitle>
+					<Shapes className="size-4 shrink-0 text-muted-foreground" aria-hidden="true" />
+					<CodeBlockLabel>{label}</CodeBlockLabel>
+				</CodeBlockTitle>
+				<CodeBlockActions>
+					<WidgetControl label="View fullscreen" onClick={() => setIsFullscreen(true)}>
+						<Maximize2 />
+					</WidgetControl>
+				</CodeBlockActions>
+			</CodeBlockHeader>
+			{/* Hidden while fullscreen: two live frames would run the widget twice,
+			    and the one behind the dialog would keep its own separate state. */}
+			{isFullscreen ? null : (
+				<WorkspaceWidgetSandbox
+					html={html}
+					className="workspace-document-widget-frame"
+					onAskAiToFix={askAiToFix}
+				/>
+			)}
 			{/* A widget's source is its text content, so ProseMirror needs somewhere
 			    to render it. Without this element Tiptap appends one itself and the
 			    raw source shows up as prose in the document. It stays hidden: the
 			    source is the frame's input, not something to read in the page. */}
 			<NodeViewContent className="workspace-document-widget-source" />
+
+			<Dialog open={isFullscreen} onOpenChange={setIsFullscreen}>
+				<DialogContent
+					className="fixed inset-0 top-0 left-0 flex h-dvh w-dvw max-w-none translate-x-0 translate-y-0 flex-col gap-0 rounded-none border-0 bg-background p-0 sm:max-w-none"
+					showCloseButton={false}
+				>
+					<CodeBlockHeader className="min-h-12 shrink-0 px-4">
+						<CodeBlockTitle>
+							<Shapes className="size-4 text-muted-foreground" aria-hidden="true" />
+							<DialogTitle className="text-sm">{label}</DialogTitle>
+						</CodeBlockTitle>
+						<CodeBlockActions>
+							<WidgetControl label="Exit fullscreen" onClick={() => setIsFullscreen(false)}>
+								<Minimize2 />
+							</WidgetControl>
+						</CodeBlockActions>
+					</CodeBlockHeader>
+					{isFullscreen ? (
+						<WorkspaceWidgetSandbox
+							html={html}
+							className="min-h-0 flex-1"
+							fill
+							onAskAiToFix={askAiToFix}
+						/>
+					) : null}
+				</DialogContent>
+			</Dialog>
 		</NodeViewWrapper>
 	);
 }
+
+function WidgetControl({
+	children,
+	label,
+	onClick,
+}: {
+	children: React.ReactNode;
+	label: string;
+	onClick: () => void;
+}) {
+	return (
+		<Button
+			aria-label={label}
+			className="size-7 text-muted-foreground [&_svg]:size-3.5"
+			onClick={onClick}
+			size="icon"
+			title={label}
+			type="button"
+			variant="ghost"
+		>
+			{children}
+		</Button>
+	);
+}
diff --git a/src/styles.css b/src/styles.css
index c5608d25f..99abd4aa9 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -709,15 +709,9 @@
 		outline-offset: 1px;
 	}
 
-	.workspace-document-prose .workspace-document-widget-handle {
-		display: flex;
-		align-items: center;
-		gap: 0.4rem;
-		border-bottom: 1px solid var(--border);
-		background: var(--muted);
-		padding: 0.3rem 0.6rem;
-		color: var(--muted-foreground);
-		font-size: 0.75rem;
+	/* Layout comes from the shared block chrome; only the drag affordance is
+	   the widget's own. */
+	.workspace-document-prose .workspace-document-widget-header {
 		cursor: grab;
 		user-select: none;
 	}

From 13f53a6573bb9264ddbdc91d1063199989977693 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 00:48:26 -0400
Subject: [PATCH 07/32] fix(documents): drop the pointer cursor math never
 honoured

---
 src/styles.css | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/src/styles.css b/src/styles.css
index 99abd4aa9..1e0acb43d 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -793,10 +793,6 @@
 		min-width: max-content;
 	}
 
-	.workspace-document-prose .tiptap-mathematics-render--editable {
-		cursor: pointer;
-	}
-
 	.workspace-document-prose .inline-math-error,
 	.workspace-document-prose .block-math-error {
 		background: color-mix(in oklch, var(--destructive) 12%, transparent);

From 9b9cff3b9daaa332ad0474b16eaa4614e35dace1 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 02:29:53 -0400
Subject: [PATCH 08/32] refactor(workspaces): keep widgets inside documents

---
 .../ai/workspace-tool-result-adapters.ts      |  5 +-
 src/features/workspaces/cache-keys.ts         |  4 --
 src/features/workspaces/cache-page.ts         | 13 +----
 .../components/WorkspaceCreateMenu.tsx        |  8 +--
 .../workspaces/documents/document-session.ts  |  4 +-
 .../kernel/workspace-kernel-access.ts         | 21 +-------
 .../kernel/workspace-kernel-files.ts          |  5 +-
 .../kernel/workspace-kernel-item-commands.ts  | 54 +++++++------------
 .../kernel/workspace-kernel-types.ts          | 11 ++++
 .../workspaces/kernel/workspace-kernel.ts     | 19 ++++---
 src/features/workspaces/model/item-display.ts | 11 ++--
 .../workspaces/operations/create-items.ts     |  5 +-
 .../operations/workspace-tool-schemas.ts      |  5 +-
 src/features/workspaces/query-options.ts      | 19 +------
 src/features/workspaces/server/functions.ts   | 11 ----
 .../workspaces/workspace-item-registry.ts     | 35 +++---------
 16 files changed, 66 insertions(+), 164 deletions(-)

diff --git a/src/features/workspaces/ai/workspace-tool-result-adapters.ts b/src/features/workspaces/ai/workspace-tool-result-adapters.ts
index d2213cb88..d1d3193cf 100644
--- a/src/features/workspaces/ai/workspace-tool-result-adapters.ts
+++ b/src/features/workspaces/ai/workspace-tool-result-adapters.ts
@@ -50,10 +50,7 @@ const workspaceCreateItemsResultAdapter = defineWorkspaceToolResultAdapter({
 			z.object({
 				itemId: z.string(),
 				path: z.string(),
-				// Deliberately not an enum: this adapter only forwards the type, and
-				// a stale list here silently fails the whole result, dropping the
-				// citation refs the model needs to cite what it just created.
-				type: z.string(),
+				type: z.enum(["document", "folder"]),
 			}),
 		),
 		references: z.array(workspaceReferenceRecordSchema),
diff --git a/src/features/workspaces/cache-keys.ts b/src/features/workspaces/cache-keys.ts
index ee607c088..c45465de5 100644
--- a/src/features/workspaces/cache-keys.ts
+++ b/src/features/workspaces/cache-keys.ts
@@ -3,7 +3,3 @@ export const workspacesQueryKey = ["workspaces"] as const;
 export function workspacePageQueryKey(workspaceId: string) {
 	return ["workspaces", workspaceId, "page"] as const;
 }
-
-export function workspaceItemContentQueryKey(workspaceId: string, itemId: string) {
-	return ["workspaces", workspaceId, "items", itemId, "content"] as const;
-}
diff --git a/src/features/workspaces/cache-page.ts b/src/features/workspaces/cache-page.ts
index e2196552d..34d5ff0fc 100644
--- a/src/features/workspaces/cache-page.ts
+++ b/src/features/workspaces/cache-page.ts
@@ -1,8 +1,5 @@
 import type { QueryClient } from "@tanstack/react-query";
-import {
-	workspaceItemContentQueryKey,
-	workspacePageQueryKey,
-} from "#/features/workspaces/cache-keys";
+import { workspacePageQueryKey } from "#/features/workspaces/cache-keys";
 import type {
 	CreateWorkspaceItemInput,
 	MoveWorkspaceItemsInput,
@@ -118,12 +115,4 @@ export function applyWorkspaceEventToCache(
 	queryClient.setQueryData<WorkspacePage>(workspacePageQueryKey(event.workspaceId), (current) =>
 		current ? applyWorkspaceEventToPage(current, event) : current,
 	);
-
-	// A widget's rendered content lives in a separate query; refetch it when its
-	// stored content changes (e.g. the AI edits the widget) so the viewer updates.
-	if (event.type === "workspace.item.content.updated") {
-		void queryClient.invalidateQueries({
-			queryKey: workspaceItemContentQueryKey(event.workspaceId, event.payload.item.id),
-		});
-	}
 }
diff --git a/src/features/workspaces/components/WorkspaceCreateMenu.tsx b/src/features/workspaces/components/WorkspaceCreateMenu.tsx
index e0b867709..42adda716 100644
--- a/src/features/workspaces/components/WorkspaceCreateMenu.tsx
+++ b/src/features/workspaces/components/WorkspaceCreateMenu.tsx
@@ -116,14 +116,14 @@ function getWorkspaceCreateMenuActions({
 				onSelect: id === "upload-file" ? () => onUploadFile(parentId) : undefined,
 			}),
 		),
-		...workspaceItemLearnCreateActions.map(({ type, label, Icon, iconClassName, comingSoon }) => ({
+		...workspaceItemLearnCreateActions.map(({ type, label, Icon, iconClassName }) => ({
 			kind: "item" as const,
 			id: type,
 			label,
-			trailing: comingSoon ? "Soon" : undefined,
-			disabled: comingSoon,
+			trailing: "Soon",
+			disabled: true,
 			leading: <Icon className={`size-4 ${iconClassName}`} />,
-			onSelect: comingSoon ? undefined : () => onCreateItem({ type, parentId }),
+			onSelect: () => onCreateItem({ type, parentId }),
 		})),
 	];
 }
diff --git a/src/features/workspaces/documents/document-session.ts b/src/features/workspaces/documents/document-session.ts
index ed51245a9..46f384d6f 100644
--- a/src/features/workspaces/documents/document-session.ts
+++ b/src/features/workspaces/documents/document-session.ts
@@ -155,7 +155,7 @@ export class DocumentSession extends YServer {
 
 		const room = getDocumentSessionRoomNameParts(this.name);
 		const kernel = await this.getWorkspaceKernel(room.workspaceId);
-		const { content } = await kernel.readItemContent({ itemId: room.itemId });
+		const { content } = await kernel.readDocumentCheckpoint({ itemId: room.itemId });
 		if (this.deleted) {
 			return;
 		}
@@ -392,7 +392,7 @@ export class DocumentSession extends YServer {
 		const document = this.getCurrentTiptapDocument();
 		const kernel = await this.getWorkspaceKernel(room.workspaceId);
 
-		await kernel.writeItemContent({
+		await kernel.commitDocumentCheckpoint({
 			itemId: room.itemId,
 			content: stringifyTiptapDocumentJson(document),
 			actorUserId: null,
diff --git a/src/features/workspaces/kernel/workspace-kernel-access.ts b/src/features/workspaces/kernel/workspace-kernel-access.ts
index 561ef68ec..592e873ef 100644
--- a/src/features/workspaces/kernel/workspace-kernel-access.ts
+++ b/src/features/workspaces/kernel/workspace-kernel-access.ts
@@ -103,7 +103,7 @@ export interface WorkspaceKernelClient {
 		actorUserId?: string | null;
 		clientMutationId?: string | null;
 	}): Promise<WorkspaceCommandResult<DeleteWorkspaceKernelItemsResult>>;
-	readItemContent(input: {
+	readDocumentCheckpoint(input: {
 		itemId: string;
 	}): Promise<{ item: WorkspaceItemSummary; content: string }>;
 	getFileSource(input: { itemId: string }): Promise<WorkspaceKernelFileSource>;
@@ -114,7 +114,7 @@ export interface WorkspaceKernelClient {
 	readFileProjection(
 		input: ReadWorkspaceKernelFileProjectionArgs,
 	): Promise<ReadWorkspaceKernelFileProjectionResult | null>;
-	writeItemContent(input: {
+	commitDocumentCheckpoint(input: {
 		itemId: string;
 		content: string;
 		actorUserId?: string | null;
@@ -145,23 +145,6 @@ export async function readWorkspaceKernelFileSource(input: {
 	}
 }
 
-export async function readWorkspaceKernelItemContent(input: {
-	workspaceId: string;
-	userId: string;
-	itemId: string;
-}) {
-	const dbContext = await createDbContext();
-
-	try {
-		await assertCanReadWorkspace(dbContext.db, input);
-		const kernel = await getWorkspaceKernel(input.workspaceId);
-
-		return await kernel.readItemContent({ itemId: input.itemId });
-	} finally {
-		await dbContext.dispose();
-	}
-}
-
 export async function readWorkspaceKernelFilePreview(input: {
 	workspaceId: string;
 	userId: string;
diff --git a/src/features/workspaces/kernel/workspace-kernel-files.ts b/src/features/workspaces/kernel/workspace-kernel-files.ts
index 496fa0886..5d2b6fce3 100644
--- a/src/features/workspaces/kernel/workspace-kernel-files.ts
+++ b/src/features/workspaces/kernel/workspace-kernel-files.ts
@@ -23,15 +23,14 @@ export function getWorkspaceKernelContentMimeType(type: WorkspaceItemType) {
 }
 
 export function getInitialWorkspaceKernelContent(type: WorkspaceItemType) {
-	switch (type) {
+	switch (getWorkspaceItemRegistryEntry(type).contentKind) {
 		case "document":
 			return stringifyTiptapDocumentJson(createInitialTiptapDocumentJson());
 		case "flashcard":
 			return JSON.stringify({ version: 1, cards: [] }, null, 2);
 		case "quiz":
 			return JSON.stringify({ version: 1, questions: [] }, null, 2);
-		case "file":
-		case "folder":
+		case "empty":
 			return "";
 	}
 }
diff --git a/src/features/workspaces/kernel/workspace-kernel-item-commands.ts b/src/features/workspaces/kernel/workspace-kernel-item-commands.ts
index 02b951370..e8247ca59 100644
--- a/src/features/workspaces/kernel/workspace-kernel-item-commands.ts
+++ b/src/features/workspaces/kernel/workspace-kernel-item-commands.ts
@@ -25,8 +25,10 @@ import type {
 	DeleteWorkspaceKernelItemsResult,
 	MoveWorkspaceKernelItemsArgs,
 	MoveWorkspaceKernelItemsResult,
+	ReadWorkspaceDocumentCheckpointArgs,
 	RenameWorkspaceKernelItemArgs,
 	UpdateWorkspaceKernelItemColorArgs,
+	CommitWorkspaceDocumentCheckpointArgs,
 	WorkspaceKernelMutationOutcome,
 } from "#/features/workspaces/kernel/workspace-kernel-types";
 import {
@@ -323,35 +325,26 @@ export class WorkspaceKernelItemCommands {
 		return { result, event };
 	}
 
-	/** Reads the stored content blob of any content-bearing item. */
-	async readItemContent(input: { itemId: string }) {
+	async readDocumentCheckpoint(input: ReadWorkspaceDocumentCheckpointArgs) {
 		const item = this.store.assertActiveItem(input.itemId);
-		if (item.type === "folder") {
-			throw new Error("Folders have no readable content.");
+		if (item.type !== "document") {
+			throw new Error("Only document items have document checkpoints.");
 		}
+		const itemSummary = mapKernelItemRow(item, this.workspaceId());
 		return {
-			item: mapKernelItemRow(item, this.workspaceId()),
+			item: itemSummary,
 			content: await this.workspace.readFile(item.shell_path),
 		};
 	}
 
-	/**
-	 * Writes the stored content blob of any content-bearing item.
-	 *
-	 * Documents additionally refresh the metadata preview derived from their
-	 * content; every other type just persists the blob.
-	 */
-	async writeItemContent(input: {
-		itemId: string;
-		content: string;
-		actorUserId?: string | null;
-		clientMutationId?: string | null;
-	}): Promise<WorkspaceCommandResult<WorkspaceItemSummary>> {
+	async commitDocumentCheckpoint(
+		input: CommitWorkspaceDocumentCheckpointArgs,
+	): Promise<WorkspaceCommandResult<WorkspaceItemSummary>> {
 		const item = this.store.assertActiveItem(input.itemId);
 		const type = workspaceItemTypeSchema.parse(item.type);
 
-		if (type === "folder") {
-			throw new Error("Folders have no writable content.");
+		if (type !== "document") {
+			throw new Error("Only document checkpoints can update workspace text content.");
 		}
 
 		await this.workspace.writeFile(
@@ -361,24 +354,15 @@ export class WorkspaceKernelItemCommands {
 		);
 
 		const currentItem = this.store.assertActiveItem(input.itemId);
-		// Keep updated_at strictly increasing so same-millisecond writes still order.
 		const updatedAt = Math.max(Date.now(), currentItem.updated_at + 1);
 
-		if (type === "document") {
-			persistDocumentItemContentUpdate({
-				content: input.content,
-				itemId: input.itemId,
-				metadataJson: currentItem.metadata_json,
-				sql: this.sql,
-				updatedAt,
-			});
-		} else {
-			this.sql`
-				UPDATE kernel_items
-				SET updated_at = ${updatedAt}
-				WHERE id = ${input.itemId} AND deleted_at IS NULL
-			`;
-		}
+		persistDocumentItemContentUpdate({
+			content: input.content,
+			itemId: input.itemId,
+			metadataJson: currentItem.metadata_json,
+			sql: this.sql,
+			updatedAt,
+		});
 
 		return this.commitItemEvent({
 			type: "workspace.item.content.updated",
diff --git a/src/features/workspaces/kernel/workspace-kernel-types.ts b/src/features/workspaces/kernel/workspace-kernel-types.ts
index 1303d8622..d553e47b5 100644
--- a/src/features/workspaces/kernel/workspace-kernel-types.ts
+++ b/src/features/workspaces/kernel/workspace-kernel-types.ts
@@ -163,6 +163,10 @@ export interface DeleteWorkspaceKernelItemsArgs {
 	clientMutationId?: string | null;
 }
 
+export interface ReadWorkspaceDocumentCheckpointArgs {
+	itemId: string;
+}
+
 export interface ReadWorkspaceKernelFileSourceArgs {
 	itemId: string;
 }
@@ -243,6 +247,13 @@ export interface ReadWorkspaceKernelFileProjectionResult {
 	updatedAt: string;
 }
 
+export interface CommitWorkspaceDocumentCheckpointArgs {
+	itemId: string;
+	content: string;
+	actorUserId?: string | null;
+	clientMutationId?: string | null;
+}
+
 export interface CreateWorkspaceKernelFileFromUploadArgs {
 	id: string;
 	parentId?: string | null;
diff --git a/src/features/workspaces/kernel/workspace-kernel.ts b/src/features/workspaces/kernel/workspace-kernel.ts
index 9c05259e5..c61f0a7bc 100644
--- a/src/features/workspaces/kernel/workspace-kernel.ts
+++ b/src/features/workspaces/kernel/workspace-kernel.ts
@@ -43,12 +43,14 @@ import type {
 	MoveWorkspaceKernelItemsResult,
 	ReadWorkspaceKernelFileSourceArgs,
 	ReadWorkspaceKernelFileProjectionArgs,
+	ReadWorkspaceDocumentCheckpointArgs,
 	ResolveWorkspaceKernelPathsArgs,
 	RenameWorkspaceKernelItemArgs,
 	UpdateWorkspaceKernelItemColorArgs,
 	UpsertWorkspaceKernelFileProjectionArgs,
 	WorkspaceKernelPage,
 	WorkspaceKernelMutationOutcome,
+	CommitWorkspaceDocumentCheckpointArgs,
 	WorkspaceKernelPathResolution,
 } from "#/features/workspaces/kernel/workspace-kernel-types";
 import { getChatAttachmentWorkspacePrefix } from "#/features/workspaces/ai/chat-attachment-storage";
@@ -377,18 +379,15 @@ export class WorkspaceKernel extends Agent<Cloudflare.Env> {
 		}
 	}
 
-	async readItemContent(input: { itemId: string }) {
-		return await this.itemCommands.readItemContent(input);
+	async readDocumentCheckpoint(input: ReadWorkspaceDocumentCheckpointArgs) {
+		return await this.itemCommands.readDocumentCheckpoint(input);
 	}
 
-	async writeItemContent(input: {
-		itemId: string;
-		content: string;
-		actorUserId?: string | null;
-		clientMutationId?: string | null;
-	}): Promise<WorkspaceCommandResult<WorkspaceItemSummary>> {
-		return this.runMutation("write_item_content", input, 1, () =>
-			this.itemCommands.writeItemContent(input),
+	async commitDocumentCheckpoint(
+		input: CommitWorkspaceDocumentCheckpointArgs,
+	): Promise<WorkspaceCommandResult<WorkspaceItemSummary>> {
+		return this.runMutation("commit_document_checkpoint", input, 1, () =>
+			this.itemCommands.commitDocumentCheckpoint(input),
 		);
 	}
 
diff --git a/src/features/workspaces/model/item-display.ts b/src/features/workspaces/model/item-display.ts
index 08cbe4a17..3bd89d117 100644
--- a/src/features/workspaces/model/item-display.ts
+++ b/src/features/workspaces/model/item-display.ts
@@ -1,12 +1,10 @@
 import { Mic, Upload } from "lucide-react";
 
-import type { WorkspaceItemType } from "#/features/workspaces/contracts";
 import { getWorkspaceObjectRegistryEntry } from "#/features/workspaces/model/object-registry";
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
 import { workspaceColors } from "#/features/workspaces/model/workspace-colors";
 import { resolveWorkspaceFileTypeFromItem } from "#/features/workspaces/model/workspace-file";
 import { getWorkspaceItemPalette } from "#/features/workspaces/model/workspace-item-colors";
-import { getWorkspaceItemRegistryEntry } from "#/features/workspaces/workspace-item-registry";
 
 export function getWorkspaceItemDisplay(item: WorkspaceItem) {
 	const typeDisplay = getWorkspaceObjectRegistryEntry(item.type);
@@ -28,13 +26,10 @@ const workspaceItemLearnCreateActionOrder = ["flashcard", "quiz"] as const;
 export const workspaceItemPrimaryCreateActions =
 	workspaceItemPrimaryCreateActionOrder.map(createWorkspaceItemAction);
 
-export const workspaceItemLearnCreateActions = workspaceItemLearnCreateActionOrder.map((type) => ({
-	...createWorkspaceItemAction(type),
-	// A type with no create flow yet is shown disabled rather than hidden.
-	comingSoon: !getWorkspaceItemRegistryEntry(type).creatable,
-}));
+export const workspaceItemLearnCreateActions =
+	workspaceItemLearnCreateActionOrder.map(createWorkspaceItemAction);
 
-function createWorkspaceItemAction(type: WorkspaceItemType) {
+function createWorkspaceItemAction(type: "document" | "folder" | "flashcard" | "quiz") {
 	const display = getWorkspaceObjectRegistryEntry(type);
 	return {
 		type,
diff --git a/src/features/workspaces/operations/create-items.ts b/src/features/workspaces/operations/create-items.ts
index 2f368d105..671b3204d 100644
--- a/src/features/workspaces/operations/create-items.ts
+++ b/src/features/workspaces/operations/create-items.ts
@@ -1,4 +1,3 @@
-import type { WorkspaceCreatableItemType } from "#/features/workspaces/workspace-item-registry";
 import { getAuthorizedWorkspaceKernel } from "#/features/workspaces/operations/workspace-operation-context";
 import {
 	resolveWorkspaceRelations,
@@ -23,7 +22,7 @@ import {
 } from "#/features/workspaces/kernel/workspace-kernel-paths";
 
 export interface CreateWorkspaceItemOperationInput {
-	type: WorkspaceCreatableItemType;
+	type: "document" | "folder";
 	path: string;
 	initialContent?: string;
 	relations?: WorkspaceRelationInput[];
@@ -44,7 +43,7 @@ export interface CreateWorkspaceItemsFailure {
 export interface CreatedWorkspaceItem {
 	itemId: string;
 	path: string;
-	type: WorkspaceCreatableItemType;
+	type: "document" | "folder";
 }
 
 export interface CreateWorkspaceItemsOperationResult {
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index a0af1a4b8..0a5cfb98e 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -16,7 +16,6 @@ import {
 	workspaceItemTypeSchema,
 	workspaceRelationKindSchema,
 } from "#/features/workspaces/contracts";
-import { workspaceCreatableItemTypeSchema } from "#/features/workspaces/workspace-item-registry";
 import { workspaceReferenceRecordSchema } from "#/features/workspaces/locations/workspace-location";
 import {
 	documentAiEditSchema,
@@ -367,9 +366,9 @@ export const workspaceListItemsOutputSchema = z.object({
 export const workspaceCreateItemsOutputSchema = createWorkspaceItemsResultSchema({
 	itemSchema: workspacePathItemSchema.extend({
 		itemId: z.string().min(1),
-		// Creation makes these three and nothing else; the shared item type covers
+		// Creation makes these two and nothing else; the shared item type covers
 		// files and study items this tool cannot produce.
-		type: workspaceCreatableItemTypeSchema,
+		type: z.enum(["document", "folder"]),
 	}),
 	failureSchema: createFailureSchema(createWorkspaceItemsFailureCodes),
 }).extend({
diff --git a/src/features/workspaces/query-options.ts b/src/features/workspaces/query-options.ts
index 1af2931de..0cadc4f13 100644
--- a/src/features/workspaces/query-options.ts
+++ b/src/features/workspaces/query-options.ts
@@ -1,15 +1,7 @@
 import { queryOptions } from "@tanstack/react-query";
 
-import {
-	workspaceItemContentQueryKey,
-	workspacePageQueryKey,
-	workspacesQueryKey,
-} from "#/features/workspaces/cache";
-import {
-	getWorkspacePageFn,
-	listWorkspacesFn,
-	readWorkspaceItemContentFn,
-} from "#/features/workspaces/server/functions";
+import { workspacePageQueryKey, workspacesQueryKey } from "#/features/workspaces/cache";
+import { getWorkspacePageFn, listWorkspacesFn } from "#/features/workspaces/server/functions";
 
 export function workspacesQueryOptions() {
 	return queryOptions({
@@ -25,10 +17,3 @@ export function workspacePageQueryOptions(workspaceId: string) {
 		staleTime: 10_000,
 	});
 }
-
-export function workspaceItemContentQueryOptions(workspaceId: string, itemId: string) {
-	return queryOptions({
-		queryKey: workspaceItemContentQueryKey(workspaceId, itemId),
-		queryFn: () => readWorkspaceItemContentFn({ data: { workspaceId, itemId } }),
-	});
-}
diff --git a/src/features/workspaces/server/functions.ts b/src/features/workspaces/server/functions.ts
index 8364dfac4..1be1d8832 100644
--- a/src/features/workspaces/server/functions.ts
+++ b/src/features/workspaces/server/functions.ts
@@ -15,7 +15,6 @@ import {
 	createWorkspaceKernelItem,
 	deleteWorkspaceKernelItems,
 	moveWorkspaceKernelItems,
-	readWorkspaceKernelItemContent,
 	renameWorkspaceKernelItem,
 	updateWorkspaceKernelItemColor,
 } from "#/features/workspaces/kernel/workspace-kernel-access";
@@ -43,16 +42,6 @@ export const getWorkspacePageFn = createServerFn({ method: "GET" })
 	.validator(workspaceIdInputSchema)
 	.handler(async ({ data }) => getWorkspacePageForCurrentUser(data.workspaceId));
 
-export const readWorkspaceItemContentFn = createServerFn({ method: "GET" })
-	.validator(z.object({ workspaceId: z.string().min(1), itemId: z.string().min(1) }))
-	.handler(async ({ data }) =>
-		readWorkspaceKernelItemContent({
-			workspaceId: data.workspaceId,
-			itemId: data.itemId,
-			userId: await getCurrentUserId(),
-		}),
-	);
-
 export const createWorkspaceFn = createServerFn({ method: "POST" })
 	.validator(createWorkspaceInputSchema)
 	.handler(async ({ data }) => createWorkspaceForCurrentUser(data));
diff --git a/src/features/workspaces/workspace-item-registry.ts b/src/features/workspaces/workspace-item-registry.ts
index 4a040354a..0efe8a95d 100644
--- a/src/features/workspaces/workspace-item-registry.ts
+++ b/src/features/workspaces/workspace-item-registry.ts
@@ -6,11 +6,7 @@ export type WorkspaceItemType = z.infer<typeof workspaceItemTypeSchema>;
 
 interface WorkspaceItemRegistryEntry {
 	color: "amber" | "emerald" | "rose" | "sky" | "violet";
-	/**
-	 * Whether the create pipeline and AI create tool can materialise this type.
-	 * Files arrive by upload, and study types have no create flow yet.
-	 */
-	creatable: boolean;
+	contentKind: "document" | "empty" | "flashcard" | "quiz";
 	defaultName: string;
 	extension: "json" | "txt" | null;
 	label: string;
@@ -23,7 +19,7 @@ interface WorkspaceItemRegistryEntry {
 const workspaceItemRegistry = {
 	folder: {
 		color: "amber",
-		creatable: true,
+		contentKind: "empty",
 		defaultName: "New folder",
 		extension: null,
 		label: "Folder",
@@ -33,7 +29,7 @@ const workspaceItemRegistry = {
 	},
 	document: {
 		color: "sky",
-		creatable: true,
+		contentKind: "document",
 		defaultName: "New document",
 		extension: "json",
 		label: "Document",
@@ -43,7 +39,7 @@ const workspaceItemRegistry = {
 	},
 	file: {
 		color: "rose",
-		creatable: false,
+		contentKind: "empty",
 		defaultName: "New file",
 		extension: "txt",
 		label: "File",
@@ -53,7 +49,7 @@ const workspaceItemRegistry = {
 	},
 	flashcard: {
 		color: "violet",
-		creatable: false,
+		contentKind: "flashcard",
 		defaultName: "New flashcards",
 		extension: "json",
 		label: "Flashcard deck",
@@ -63,7 +59,7 @@ const workspaceItemRegistry = {
 	},
 	quiz: {
 		color: "emerald",
-		creatable: false,
+		contentKind: "quiz",
 		defaultName: "New quiz",
 		extension: "json",
 		label: "Quiz",
@@ -77,25 +73,6 @@ export function getWorkspaceItemRegistryEntry(type: WorkspaceItemType) {
 	return workspaceItemRegistry[type];
 }
 
-/**
- * The item types the create pipeline can materialise, per the registry.
- *
- * Derive from this rather than restating the list: every hand-copied version is
- * a place a new type silently falls out of (a stale copy in the AI result
- * adapter is what dropped widget citation refs).
- */
-export type WorkspaceCreatableItemType = {
-	[Type in WorkspaceItemType]: (typeof workspaceItemRegistry)[Type]["creatable"] extends true
-		? Type
-		: never;
-}[WorkspaceItemType];
-
-export const workspaceCreatableItemTypes = workspaceItemTypes.filter(
-	(type): type is WorkspaceCreatableItemType => workspaceItemRegistry[type].creatable,
-) as [WorkspaceCreatableItemType, ...WorkspaceCreatableItemType[]];
-
-export const workspaceCreatableItemTypeSchema = z.enum(workspaceCreatableItemTypes);
-
 /** The item types workspace search indexes and filters on, per the registry. */
 export type WorkspaceSearchableItemType = {
 	[Type in WorkspaceItemType]: (typeof workspaceItemRegistry)[Type]["searchable"] extends true

From 31ce60dc6841937af5c637601fd52e5f54709211 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 02:30:05 -0400
Subject: [PATCH 09/32] fix(documents): bound widget source text edits

---
 .../documents/document-ai-edits.test.ts       | 46 ++++++++++++++++++-
 .../workspaces/documents/document-ai-edits.ts |  8 ++--
 .../workspace-tool-surface.test.ts.snap       |  2 +
 3 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/src/features/workspaces/documents/document-ai-edits.test.ts b/src/features/workspaces/documents/document-ai-edits.test.ts
index 3210ad108..bcb1e5579 100644
--- a/src/features/workspaces/documents/document-ai-edits.test.ts
+++ b/src/features/workspaces/documents/document-ai-edits.test.ts
@@ -6,6 +6,7 @@ import {
 	parseDocumentAiHtml,
 	serializeTiptapDocumentToAiHtml,
 } from "#/features/workspaces/documents/document-ai-html";
+import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
 
 describe("document AI edits", () => {
 	it("applies consecutive structural edits while preserving the target ref", async () => {
@@ -88,6 +89,37 @@ describe("document AI edits", () => {
 			/<\/ul><p data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"><\/p>$/,
 		);
 	});
+
+	it("replaces one exact fragment in widget source", async () => {
+		const document = createDocument(
+			'<div data-type="widget" title="Timer">&lt;button&gt;Start&lt;/button&gt;</div>',
+		);
+		const ref = await getRef(document, "div");
+		const result = await applyDocumentAiEdits(document, [
+			{ find: ">Start<", op: "replace_text", ref, replace: ">Go<" },
+		]);
+
+		expect(result).toMatchObject({ applied: 1, failed: 0, status: "applied" });
+		expect(getWidgetSource(result.document)).toBe("<button>Go</button>");
+	});
+
+	it("refuses an ambiguous widget source replacement", async () => {
+		const document = createDocument(
+			'<div data-type="widget">&lt;button&gt;Run&lt;/button&gt;&lt;button&gt;Run&lt;/button&gt;</div>',
+		);
+		const ref = await getRef(document, "div");
+		const result = await applyDocumentAiEdits(document, [
+			{ find: "Run", op: "replace_text", ref, replace: "Stop" },
+		]);
+
+		expect(result).toMatchObject({
+			applied: 0,
+			failed: 1,
+			failures: [{ code: "edit_not_unique", index: 0 }],
+			status: "failed",
+		});
+		expect(getWidgetSource(result.document)).toContain("Run</button><button>Run");
+	});
 });
 
 function createDocument(html: string) {
@@ -96,7 +128,7 @@ function createDocument(html: string) {
 
 async function getRef(document: ReturnType<typeof createDocument>, tagName: string) {
 	const match = (await serializeTiptapDocumentToAiHtml(document)).match(
-		new RegExp(`<${tagName} data-ref="([^"]+)"`),
+		new RegExp(`<${tagName}\\b[^>]*\\sdata-ref="([^"]+)"`),
 	);
 	if (!match?.[1]) {
 		throw new Error(`Expected ${tagName} ref.`);
@@ -107,3 +139,15 @@ async function getRef(document: ReturnType<typeof createDocument>, tagName: stri
 function stableRef(ref: string) {
 	return ref.split(".r_")[0];
 }
+
+function getWidgetSource(document: ReturnType<typeof createDocument>) {
+	let source = "";
+	getTiptapDocumentSchema()
+		.nodeFromJSON(document)
+		.forEach((node) => {
+			if (node.type.name === "widget") {
+				source = node.textContent;
+			}
+		});
+	return source;
+}
diff --git a/src/features/workspaces/documents/document-ai-edits.ts b/src/features/workspaces/documents/document-ai-edits.ts
index 38832e2d2..e8d77f9a1 100644
--- a/src/features/workspaces/documents/document-ai-edits.ts
+++ b/src/features/workspaces/documents/document-ai-edits.ts
@@ -28,6 +28,7 @@ export const documentAiHtmlSchema = z
 	.string()
 	.max(512_000)
 	.describe("Schema-constrained HTML fragment. Model-supplied data-ref attributes are ignored.");
+const documentAiEditTextSchema = z.string().max(512_000);
 
 export const documentAiEditSchema = z.union([
 	z.strictObject({
@@ -44,15 +45,16 @@ export const documentAiEditSchema = z.union([
 		op: z.literal("overwrite"),
 	}),
 	z.strictObject({
-		find: z
-			.string()
+		find: documentAiEditTextSchema
 			.min(1)
 			.describe(
 				"Exact text to replace inside the target block, copied from a read. It must appear exactly once in that block; if it matches more than once the edit fails instead of replacing every occurrence.",
 			),
 		op: z.literal("replace_text"),
 		ref: documentAiRefSchema,
-		replace: z.string().describe("Replacement text. May be empty to delete the matched text."),
+		replace: documentAiEditTextSchema.describe(
+			"Replacement text. May be empty to delete the matched text.",
+		),
 	}),
 ]);
 
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index da4c0e96b..d890dd004 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -278,6 +278,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
             "properties": {
               "find": {
                 "description": "Exact text to replace inside the target block, copied from a read. It must appear exactly once in that block; if it matches more than once the edit fails instead of replacing every occurrence.",
+                "maxLength": 512000,
                 "minLength": 1,
                 "type": "string",
               },
@@ -293,6 +294,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
               },
               "replace": {
                 "description": "Replacement text. May be empty to delete the matched text.",
+                "maxLength": 512000,
                 "type": "string",
               },
             },

From 67afb5cd0548b44c572702e49cef64945e3ccb62 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 02:31:27 -0400
Subject: [PATCH 10/32] refactor(widgets): simplify sandbox and error UI

---
 .../ai/skills/widget-authoring/SKILL.md       |   7 +-
 .../document-editor/DocumentEditorSurface.tsx |  14 +-
 .../widget/WorkspaceAddWidgetDialog.tsx       |   6 +-
 .../widget/WorkspaceWidgetSandbox.test.tsx    | 117 +++++++++++
 .../widget/WorkspaceWidgetSandbox.tsx         | 137 +++++++-----
 .../workspace-widget-sandbox-document.test.ts |  83 +++++++-
 .../workspace-widget-sandbox-document.ts      | 196 +++++++++++++-----
 .../documents/document-widget-node.tsx        |  77 +------
 8 files changed, 438 insertions(+), 199 deletions(-)
 create mode 100644 src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx

diff --git a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
index 49969378b..0a6161972 100644
--- a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
+++ b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
@@ -20,10 +20,11 @@ Use **ordinary blocks** when the value is in _rich text_: notes, explanations, s
 1. **Fragment only.** Provide the inner content only — HTML, one or more inline `<style>` blocks, and inline `<script>`. Do **NOT** include `<!doctype>`, `<html>`, `<head>`, or `<body>`. The sandbox wraps your fragment in a full document.
 2. **All JS is inline.** No external scripts, no `import`, no `fetch`, no network, no CDN links. `connect-src` is blocked and external scripts will not load. Write vanilla JS (or hand-rolled helpers) inline in a `<script>` tag.
 3. **Theme with the app's CSS variables.** The host injects these variables so the widget looks native in light and dark mode. Use them instead of hard-coded colors:
-   `--background`, `--foreground`, `--card`, `--card-foreground`, `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--border`, `--input`, `--ring`, `--radius`.
-   The sandbox toggles a `.dark` class on the root element when the app is in dark mode; because you use the variables, you rarely need to special-case `.dark` yourself.
+   `--background`, `--foreground`, `--card`, `--card-foreground`, `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--border`, `--input`, `--ring`, `--radius`, `--font-sans`, `--font-mono`.
+   The sandbox sets `data-theme="light|dark"` and toggles a `.dark` class on the root element; because you use the variables, you rarely need to special-case either one.
+   CSS updates automatically without reloading the widget. If a `<canvas>` copies token colors into pixels, redraw it on `window`'s `thinkex:themechange` event so its existing state survives the theme switch.
 4. **No chrome of your own.** The block already draws a border and a title strip showing the `title` attribute, and the surrounding prose says what the widget is for. So do **not** repeat the title as a heading, and do **not** wrap everything in an outer bordered/rounded panel. Start straight into the content. Borders and `var(--card)` backgrounds are for genuinely separate sub-regions (a stat tile, a chart panel), never the outer shell. One short line of instructions is fine when it says something the title doesn't.
-5. **Let the height come from your content.** The block measures what you render and sizes itself to match, between 120px and 720px; past that it scrolls. So do **not** set `height: 100%` on your root — there is no fixed frame to fill, and it will collapse. Give any element that has no natural height — a `<canvas>`, a chart area, a map — an explicit height in px, and let everything else flow. Do **not** cap the width with `max-width`, centre it with `margin: auto`, or add outer padding. The frame is already the width of the document's text column and already provides a gutter, so anything on top of that only strands the content in dead space. Keep a widget to roughly one screenful: a compact layout beats one the reader has to scroll inside. Taller widgets still work — the reader can open any widget fullscreen — but the inline block is what they see first.
+5. **Let the height come from your content.** The block measures what you render and sizes itself to match, between 120px and 720px; past that it scrolls. So do **not** set `height: 100%` on your root — there is no fixed frame to fill, and it will collapse. Give any element that has no natural height — a `<canvas>`, a chart area, a map — an explicit height in px, and let everything else flow. Do **not** cap the width with `max-width`, centre it with `margin: auto`, or add outer padding. The frame is already the width of the document's text column and already provides a gutter, so anything on top of that only strands the content in dead space. Keep a widget to roughly one screenful: a compact layout beats one the reader has to scroll inside.
 6. **Fail loudly, not silently.** If something can error, let it throw — the sandbox catches runtime errors and offers the user an "Ask AI to fix" button that sends the error back to you.
 
 ## Starter template
diff --git a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
index d27cceda9..da0542f76 100644
--- a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
+++ b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
@@ -87,11 +87,13 @@ function DocumentEditorInstance({
 			disableCollaboration();
 		},
 		extensions: getDocumentEditorExtensions(collaborationSession, {
-			onAskAiToFixWidget: (error) =>
-				stageComposerPrompt(
-					workspaceId,
-					`A widget in ${readWorkspaceItemPath(queryClient, workspaceId, item) ?? item.name} hit this error — please fix it:\n\n${error}`,
-				),
+			onAskAiToFixWidget: capabilities.canMutateContent
+				? (error) =>
+						stageComposerPrompt(
+							workspaceId,
+							`A widget in ${readWorkspaceItemPath(queryClient, workspaceId, item) ?? item.name} hit this error. Please fix it:\n\n${error}`,
+						)
+				: undefined,
 		}),
 		editorProps: {
 			attributes: {
@@ -147,7 +149,7 @@ function DocumentEditorInstance({
 
 function getDocumentEditorExtensions(
 	collaborationSession: DocumentCollaborationSession,
-	options: { onAskAiToFixWidget: (error: string) => void },
+	options: { onAskAiToFixWidget?: (error: string) => void },
 ) {
 	const baseExtensions = getTiptapDocumentBaseExtensions(options);
 
diff --git a/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx b/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
index 9ce9a40bb..a77b1eaf2 100644
--- a/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
+++ b/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
@@ -81,9 +81,9 @@ function WorkspaceAddWidgetDialogContent({
 				<DialogHeader>
 					<DialogTitle>Add a widget</DialogTitle>
 					<DialogDescription>
-						A widget is a small interactive tool — a simulation, calculator, diagram, or
-						visualization — that lives in this document. Describe what you want and the AI will
-						build it for you.
+						A widget is an interactive tool that lives in this document, such as a simulation,
+						calculator, diagram, or visualization. Describe what you want, and the AI will build it
+						for you.
 					</DialogDescription>
 				</DialogHeader>
 				<FieldGroup>
diff --git a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx
new file mode 100644
index 000000000..340990ee2
--- /dev/null
+++ b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx
@@ -0,0 +1,117 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { WorkspaceWidgetSandbox } from "#/features/workspaces/components/widget/WorkspaceWidgetSandbox";
+import {
+	WIDGET_SANDBOX_FRAME_SOURCE,
+	WIDGET_SANDBOX_HOST_SOURCE,
+} from "#/features/workspaces/components/widget/workspace-widget-sandbox-document";
+
+const themeState = vi.hoisted(() => ({ resolvedTheme: "light" as "light" | "dark" }));
+
+vi.mock("#/components/theme-provider", () => ({
+	useTheme: () => themeState,
+}));
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe("WorkspaceWidgetSandbox", () => {
+	let container: HTMLDivElement;
+	let root: Root;
+
+	beforeEach(() => {
+		themeState.resolvedTheme = "light";
+		document.documentElement.style.setProperty("--background", "white");
+		container = document.createElement("div");
+		document.body.appendChild(container);
+		root = createRoot(container);
+		vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+			callback(0);
+			return 1;
+		});
+		vi.stubGlobal("cancelAnimationFrame", vi.fn());
+	});
+
+	afterEach(async () => {
+		await act(async () => root.unmount());
+		container.remove();
+		document.documentElement.style.removeProperty("--background");
+		vi.unstubAllGlobals();
+	});
+
+	it("updates the live frame theme without rebuilding authored HTML", async () => {
+		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>one</p>" />));
+
+		const iframe = container.querySelector("iframe");
+		expect(iframe).not.toBeNull();
+		if (!iframe?.contentWindow) throw new Error("Expected the sandbox iframe window");
+
+		const initialDocument = iframe.getAttribute("srcdoc");
+		expect(initialDocument).toContain("<p>one</p>");
+		expect(initialDocument).toContain("var SESSION=1");
+
+		const postMessage = vi.spyOn(iframe.contentWindow, "postMessage");
+		await act(async () => {
+			window.dispatchEvent(
+				new MessageEvent("message", {
+					data: {
+						source: WIDGET_SANDBOX_FRAME_SOURCE,
+						kind: "ready",
+						sessionId: 1,
+					},
+					source: iframe.contentWindow,
+				}),
+			);
+		});
+
+		themeState.resolvedTheme = "dark";
+		document.documentElement.style.setProperty("--background", "black");
+		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>one</p>" />));
+
+		expect(container.querySelector("iframe")).toBe(iframe);
+		expect(iframe.getAttribute("srcdoc")).toBe(initialDocument);
+		expect(postMessage).toHaveBeenLastCalledWith(
+			{
+				source: WIDGET_SANDBOX_HOST_SOURCE,
+				kind: "theme",
+				sessionId: 1,
+				theme: "dark",
+				tokens: expect.objectContaining({ "--background": "black" }),
+			},
+			"*",
+		);
+
+		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>two</p>" />));
+		expect(iframe.getAttribute("srcdoc")).not.toBe(initialDocument);
+		expect(iframe.getAttribute("srcdoc")).toContain("<p>two</p>");
+		expect(iframe.getAttribute("srcdoc")).toContain("var SESSION=2");
+	});
+
+	it("lets the error view size itself instead of keeping the widget height", async () => {
+		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>broken</p>" />));
+
+		const iframe = container.querySelector("iframe");
+		expect(iframe?.contentWindow).not.toBeNull();
+		const frame = iframe?.parentElement;
+
+		await act(async () => {
+			window.dispatchEvent(
+				new MessageEvent("message", {
+					data: {
+						source: WIDGET_SANDBOX_FRAME_SOURCE,
+						kind: "error",
+						message: "Unexpected token",
+						sessionId: 1,
+					},
+					source: iframe?.contentWindow,
+				}),
+			);
+		});
+
+		expect(frame?.style.height).toBe("");
+		expect(frame?.querySelector('[role="alert"]')).not.toBeNull();
+	});
+});
diff --git a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
index b458c81bf..e027fc8bd 100644
--- a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
+++ b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
@@ -1,4 +1,3 @@
-import { Sparkles } from "lucide-react";
 import { useEffect, useRef, useState } from "react";
 
 import { useTheme } from "#/components/theme-provider";
@@ -6,8 +5,11 @@ import { Button } from "#/components/ui/button";
 import {
 	buildWidgetSandboxDocument,
 	isWidgetSandboxFrameMessage,
+	type WidgetSandboxHostMessage,
+	type WidgetSandboxTheme,
 	WIDGET_SANDBOX_MAX_HEIGHT,
 	WIDGET_SANDBOX_MIN_HEIGHT,
+	WIDGET_SANDBOX_HOST_SOURCE,
 	WIDGET_SANDBOX_TOKENS,
 } from "#/features/workspaces/components/widget/workspace-widget-sandbox-document";
 import { cn } from "#/lib/utils";
@@ -15,11 +17,6 @@ import { cn } from "#/lib/utils";
 type WorkspaceWidgetSandboxProps = {
 	html: string;
 	className?: string;
-	/**
-	 * Fill the available space instead of sizing to the widget's own content.
-	 * For the fullscreen view, where the container decides the height.
-	 */
-	fill?: boolean;
 	/**
 	 * Called with the runtime error text when the user asks the AI to fix a
 	 * crashed widget. Omit to hide the affordance.
@@ -37,18 +34,20 @@ type WorkspaceWidgetSandboxProps = {
 export function WorkspaceWidgetSandbox({
 	html,
 	className,
-	fill = false,
 	onAskAiToFix,
 }: WorkspaceWidgetSandboxProps) {
 	const { resolvedTheme } = useTheme();
 	const iframeRef = useRef<HTMLIFrameElement>(null);
+	const renderedHtmlRef = useRef<string | null>(null);
+	const sessionIdRef = useRef(0);
+	const readySessionIdRef = useRef<number | null>(null);
+	const themeRef = useRef<WidgetSandboxTheme | null>(null);
 	const [srcDoc, setSrcDoc] = useState<string | null>(null);
 	const [error, setError] = useState<string | null>(null);
 	const [height, setHeight] = useState(WIDGET_SANDBOX_MIN_HEIGHT);
 
-	// Build the sandbox document from the authored HTML plus the host's resolved
-	// design tokens. Rebuilding on theme change or edit is a fresh render, so the
-	// previous error clears with it.
+	// Build a fresh document only when authored HTML changes. Theme changes send
+	// a full token snapshot into the existing frame, preserving its JS state.
 	//
 	// Everything happens in a frame callback, which also keeps the effect
 	// render-safe. The tokens have to be read there rather than here: the theme
@@ -57,21 +56,28 @@ export function WorkspaceWidgetSandbox({
 	// theme's values and pair them with the new theme's class.
 	useEffect(() => {
 		const frame = requestAnimationFrame(() => {
-			const style = getComputedStyle(document.documentElement);
-			const tokens: Record<string, string> = {};
-			for (const name of WIDGET_SANDBOX_TOKENS) {
-				tokens[name] = style.getPropertyValue(name).trim();
+			const theme = readWidgetSandboxTheme(resolvedTheme);
+			themeRef.current = theme;
+
+			if (renderedHtmlRef.current !== html) {
+				renderedHtmlRef.current = html;
+				sessionIdRef.current += 1;
+				readySessionIdRef.current = null;
+				setSrcDoc(
+					buildWidgetSandboxDocument({
+						html,
+						...theme,
+						origin: window.location.origin,
+						sessionId: sessionIdRef.current,
+					}),
+				);
+				setError(null);
+				return;
 			}
 
-			setSrcDoc(
-				buildWidgetSandboxDocument({
-					html,
-					theme: resolvedTheme,
-					tokens,
-					origin: window.location.origin,
-				}),
-			);
-			setError(null);
+			if (readySessionIdRef.current === sessionIdRef.current) {
+				postWidgetSandboxTheme(iframeRef.current, sessionIdRef.current, theme);
+			}
 		});
 		return () => cancelAnimationFrame(frame);
 	}, [html, resolvedTheme]);
@@ -84,6 +90,9 @@ export function WorkspaceWidgetSandbox({
 			if (!isWidgetSandboxFrameMessage(event.data)) {
 				return;
 			}
+			if (event.data.sessionId !== sessionIdRef.current) {
+				return;
+			}
 			if (event.data.kind === "error") {
 				setError(event.data.message);
 				return;
@@ -97,7 +106,10 @@ export function WorkspaceWidgetSandbox({
 				);
 				return;
 			}
-			setError(null);
+			readySessionIdRef.current = event.data.sessionId;
+			if (themeRef.current) {
+				postWidgetSandboxTheme(iframeRef.current, event.data.sessionId, themeRef.current);
+			}
 		}
 
 		window.addEventListener("message", onMessage);
@@ -107,41 +119,54 @@ export function WorkspaceWidgetSandbox({
 	return (
 		// Height comes from the frame's own content, so the block takes the room
 		// the widget needs instead of a number chosen here.
-		<div
-			className={cn("relative bg-background", fill && "h-full", className)}
-			style={fill ? undefined : { height }}
-		>
-			<iframe
-				ref={iframeRef}
-				title="Widget preview"
-				sandbox="allow-scripts"
-				srcDoc={srcDoc ?? undefined}
-				className="h-full w-full border-0 bg-background"
-			/>
+		<div className={cn("relative bg-background", className)} style={error ? undefined : { height }}>
 			{error ? (
-				<div className="absolute inset-x-0 bottom-0 border-border/70 border-t bg-background/95 p-3 backdrop-blur-sm">
-					<div className="flex items-start justify-between gap-3">
-						<div className="min-w-0">
-							<p className="font-medium text-foreground text-sm">This widget hit an error</p>
-							<pre className="mt-1 max-h-24 overflow-auto whitespace-pre-wrap font-mono text-muted-foreground text-xs">
-								{error}
-							</pre>
-						</div>
-						{onAskAiToFix ? (
-							<Button
-								type="button"
-								size="sm"
-								variant="secondary"
-								className="shrink-0"
-								onClick={() => onAskAiToFix(error)}
-							>
-								<Sparkles className="size-4" />
-								Ask AI to fix
-							</Button>
-						) : null}
+				<div
+					role="alert"
+					className="flex min-h-48 flex-col items-center justify-center gap-4 bg-background p-6 text-center"
+				>
+					<p className="font-medium text-foreground text-sm">Widget error</p>
+					<div className="max-h-32 w-full max-w-lg overflow-auto whitespace-pre-wrap rounded-md bg-muted px-4 py-3 font-mono text-muted-foreground text-xs leading-relaxed">
+						{error}
 					</div>
+					{onAskAiToFix ? (
+						<Button type="button" size="sm" variant="secondary" onClick={() => onAskAiToFix(error)}>
+							Ask AI to fix
+						</Button>
+					) : null}
 				</div>
-			) : null}
+			) : (
+				<iframe
+					ref={iframeRef}
+					title="Widget preview"
+					sandbox="allow-scripts"
+					srcDoc={srcDoc ?? undefined}
+					className="h-full w-full border-0 bg-background"
+				/>
+			)}
 		</div>
 	);
 }
+
+function readWidgetSandboxTheme(theme: WidgetSandboxTheme["theme"]): WidgetSandboxTheme {
+	const style = getComputedStyle(document.documentElement);
+	const tokens: Record<string, string> = {};
+	for (const name of WIDGET_SANDBOX_TOKENS) {
+		tokens[name] = style.getPropertyValue(name).trim();
+	}
+	return { theme, tokens };
+}
+
+function postWidgetSandboxTheme(
+	iframe: HTMLIFrameElement | null,
+	sessionId: number,
+	theme: WidgetSandboxTheme,
+) {
+	const message: WidgetSandboxHostMessage = {
+		source: WIDGET_SANDBOX_HOST_SOURCE,
+		kind: "theme",
+		sessionId,
+		...theme,
+	};
+	iframe?.contentWindow?.postMessage(message, "*");
+}
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
index 03df14cf1..1361cabda 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
 
-import { buildWidgetSandboxDocument } from "#/features/workspaces/components/widget/workspace-widget-sandbox-document";
+import {
+	buildWidgetSandboxDocument,
+	isWidgetSandboxFrameMessage,
+	WIDGET_SANDBOX_FRAME_SOURCE,
+} from "#/features/workspaces/components/widget/workspace-widget-sandbox-document";
 
 function loadsKatex(html: string) {
 	return buildWidgetSandboxDocument({
@@ -8,6 +12,7 @@ function loadsKatex(html: string) {
 		theme: "light",
 		tokens: { "--background": "oklch(1 0 0)" },
 		origin: "https://app.test",
+		sessionId: 1,
 	}).includes("katex.min.js");
 }
 
@@ -19,12 +24,84 @@ describe("buildWidgetSandboxDocument", () => {
 		expect(loadsKatex('<span data-type="inline-math" data-latex="x^2"></span>')).toBe(true);
 		expect(loadsKatex("<p>$$E = mc^2$$</p>")).toBe(true);
 		expect(loadsKatex("<p>\\(x\\)</p>")).toBe(true);
-		expect(loadsKatex("<p>Solve $x + 1$ now</p>")).toBe(true);
 		expect(loadsKatex("<script>renderMathInElement(el)</script>")).toBe(true);
 	});
 
 	it("skips KaTeX for a widget with no math, including prices", () => {
-		expect(loadsKatex("<p>Total: $30</p><button>Buy</button>")).toBe(false);
+		expect(loadsKatex("<p>Plans cost $30 or $75.</p><button>Buy</button>")).toBe(false);
 		expect(loadsKatex("<canvas id='c'></canvas>")).toBe(false);
 	});
+
+	it("blocks remote assets and installs the error harness before authored scripts", () => {
+		const authoredScript = '<script>throw new Error("boom")</script>';
+		const document = buildWidgetSandboxDocument({
+			html: authoredScript,
+			theme: "light",
+			tokens: {},
+			origin: "https://app.test",
+			sessionId: 1,
+		});
+
+		expect(document).toContain("img-src data: blob:");
+		expect(document).toContain("media-src data: blob:");
+		expect(document).not.toContain("img-src data: https:");
+		expect(document.indexOf('window.addEventListener("error"')).toBeLessThan(
+			document.indexOf(authoredScript),
+		);
+		expect(document.indexOf('window.addEventListener("message"')).toBeLessThan(
+			document.indexOf(authoredScript),
+		);
+		expect(document).toContain("thinkex:themechange");
+	});
+});
+
+describe("isWidgetSandboxFrameMessage", () => {
+	it("validates each message payload", () => {
+		expect(
+			isWidgetSandboxFrameMessage({
+				source: WIDGET_SANDBOX_FRAME_SOURCE,
+				kind: "ready",
+				sessionId: 1,
+			}),
+		).toBe(true);
+		expect(
+			isWidgetSandboxFrameMessage({
+				source: WIDGET_SANDBOX_FRAME_SOURCE,
+				kind: "error",
+				message: "boom",
+				sessionId: 1,
+			}),
+		).toBe(true);
+		expect(
+			isWidgetSandboxFrameMessage({
+				source: WIDGET_SANDBOX_FRAME_SOURCE,
+				kind: "height",
+				height: 320,
+				sessionId: 1,
+			}),
+		).toBe(true);
+		expect(
+			isWidgetSandboxFrameMessage({
+				source: WIDGET_SANDBOX_FRAME_SOURCE,
+				kind: "error",
+				message: 1,
+				sessionId: 1,
+			}),
+		).toBe(false);
+		expect(
+			isWidgetSandboxFrameMessage({
+				source: WIDGET_SANDBOX_FRAME_SOURCE,
+				kind: "height",
+				height: Number.NaN,
+				sessionId: 1,
+			}),
+		).toBe(false);
+		expect(
+			isWidgetSandboxFrameMessage({
+				source: WIDGET_SANDBOX_FRAME_SOURCE,
+				kind: "ready",
+				sessionId: 0,
+			}),
+		).toBe(false);
+	});
 });
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
index ba12efe45..c29bc28ee 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
@@ -10,9 +10,9 @@
  *
  * Two things are composed around the authored HTML:
  *  - a theme layer: the resolved design tokens (read from the host when this
- *    document is built) are injected as CSS variables so widgets look native,
- *    plus a `.dark` class from the passed theme. A theme change rebuilds the
- *    document, so there is no host-to-frame channel to keep in sync.
+ *    document is built) are injected as CSS variables so widgets look native.
+ *    Later theme changes arrive over a small host-to-frame message channel, so
+ *    live widget state survives them.
  *  - an error harness: window `error` / `unhandledrejection` are forwarded to
  *    the host via postMessage so a crashed widget surfaces an "Ask AI to fix"
  *    affordance instead of a silent blank frame.
@@ -20,11 +20,33 @@
 
 /** Frame → host messages (ready / height / runtime errors). */
 export const WIDGET_SANDBOX_FRAME_SOURCE = "thinkex-widget-frame" as const;
+export const WIDGET_SANDBOX_HOST_SOURCE = "thinkex-widget-host" as const;
+
+export type WidgetSandboxTheme = {
+	theme: "light" | "dark";
+	tokens: Record<string, string>;
+};
+
+export type WidgetSandboxHostMessage = WidgetSandboxTheme & {
+	source: typeof WIDGET_SANDBOX_HOST_SOURCE;
+	kind: "theme";
+	sessionId: number;
+};
 
 export type WidgetSandboxFrameMessage =
-	| { source: typeof WIDGET_SANDBOX_FRAME_SOURCE; kind: "ready" }
-	| { source: typeof WIDGET_SANDBOX_FRAME_SOURCE; kind: "height"; height: number }
-	| { source: typeof WIDGET_SANDBOX_FRAME_SOURCE; kind: "error"; message: string };
+	| { source: typeof WIDGET_SANDBOX_FRAME_SOURCE; kind: "ready"; sessionId: number }
+	| {
+			source: typeof WIDGET_SANDBOX_FRAME_SOURCE;
+			kind: "height";
+			height: number;
+			sessionId: number;
+	  }
+	| {
+			source: typeof WIDGET_SANDBOX_FRAME_SOURCE;
+			kind: "error";
+			message: string;
+			sessionId: number;
+	  };
 
 /**
  * Bounds on a widget's reported height. A widget sits in the flow of a
@@ -62,13 +84,15 @@ export const WIDGET_SANDBOX_TOKENS = [
 	"--warning",
 	"--info",
 	"--radius",
+	"--font-sans",
+	"--font-mono",
 ] as const;
 
 /** Path KaTeX's browser build is served from (see scripts/copy-widget-libs.mjs). */
 const WIDGET_KATEX_BASE_PATH = "/widget-libs/katex";
 
 /** Any supported math notation: chat LaTeX delimiters, document markup, or the API. */
-const WIDGET_MATH_PATTERN = /\$\$|\\\(|\\\[|\$[^$\n]+\$|data-latex|katex|renderMathInElement/;
+const WIDGET_MATH_PATTERN = /\$\$|\\\(|\\\[|data-latex|katex|renderMathInElement/;
 
 /**
  * Restrictive CSP for the frame. Widgets are self-contained HTML: inline
@@ -80,20 +104,22 @@ function getWidgetSandboxCsp(origin: string) {
 		"default-src 'none'",
 		`style-src 'unsafe-inline' ${origin}`,
 		`script-src 'unsafe-inline' ${origin}`,
-		"img-src data: https:",
-		`font-src data: https: ${origin}`,
-		"media-src data: https:",
+		"img-src data: blob:",
+		`font-src data: ${origin}`,
+		"media-src data: blob:",
 		"connect-src 'none'",
+		"object-src 'none'",
+		"base-uri 'none'",
+		"form-action 'none'",
 	].join("; ");
 }
 
-type BuildWidgetSandboxDocumentInput = {
+type BuildWidgetSandboxDocumentInput = WidgetSandboxTheme & {
 	html: string;
-	theme: "light" | "dark";
-	/** `--token` → resolved value, read from the host via getComputedStyle. */
-	tokens: Record<string, string>;
 	/** App origin the frame may load bundled libraries from. */
 	origin: string;
+	/** Changes only when authored HTML changes, to reject messages from the old document. */
+	sessionId: number;
 };
 
 export function buildWidgetSandboxDocument({
@@ -101,6 +127,7 @@ export function buildWidgetSandboxDocument({
 	theme,
 	tokens,
 	origin,
+	sessionId,
 }: BuildWidgetSandboxDocumentInput): string {
 	const tokenDeclarations = Object.entries(tokens)
 		.filter(([, value]) => value.trim().length > 0)
@@ -132,7 +159,7 @@ export function buildWidgetSandboxDocument({
 	// belongs to the widget — host-side centring or max-widths strand it in dead
 	// space.
 	return `<!doctype html>
-<html lang="en"${theme === "dark" ? ' class="dark"' : ""}>
+<html lang="en" data-theme="${theme}"${theme === "dark" ? ' class="dark"' : ""}>
 <head>
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -140,63 +167,96 @@ export function buildWidgetSandboxDocument({
 ${katexTags}
 <style>
 :root{${tokenDeclarations}color-scheme:${theme};}
-html,body{margin:0;background:var(--background);color:var(--foreground);font-family:ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;}
+html,body{margin:0;background:var(--background);color:var(--foreground);font-family:var(--font-sans,ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif);}
 html{padding:0;}
 body{padding:clamp(10px,2.5%,16px);}
 *,*::before,*::after{box-sizing:border-box;}
 </style>
 </head>
 <body>
-${html}
 <script>
 (function(){
   var FRAME="${WIDGET_SANDBOX_FRAME_SOURCE}";
-  function post(message){ try{ parent.postMessage(message,"*"); }catch(_){} }
-  function report(message){ post({source:FRAME,kind:"error",message:String(message)}); }
+  var HOST="${WIDGET_SANDBOX_HOST_SOURCE}";
+  var SESSION=${sessionId};
+  var TOKENS=${JSON.stringify(WIDGET_SANDBOX_TOKENS)};
+  function post(message){
+    message.source=FRAME;
+    message.sessionId=SESSION;
+    try{ parent.postMessage(message,"*"); }catch(_){}
+  }
+  function report(message){ post({kind:"error",message:String(message)}); }
+  window.addEventListener("message",function(event){
+    var message=event.data;
+    if(event.source!==parent||!message||message.source!==HOST||message.kind!=="theme"||message.sessionId!==SESSION)return;
+    if((message.theme!=="light"&&message.theme!=="dark")||!message.tokens||typeof message.tokens!=="object")return;
+    var root=document.documentElement;
+    root.classList.toggle("dark",message.theme==="dark");
+    root.dataset.theme=message.theme;
+    root.style.colorScheme=message.theme;
+    TOKENS.forEach(function(name){
+      var value=message.tokens[name];
+      if(typeof value==="string")root.style.setProperty(name,value);
+    });
+    window.dispatchEvent(new CustomEvent("thinkex:themechange",{detail:{theme:message.theme}}));
+  });
   window.addEventListener("error",function(event){
     report((event.message||"Error")+(event.error&&event.error.stack?"\\n"+event.error.stack:""));
   });
-  if(typeof renderMathInElement==="function"){
-    var mathOptions={throwOnError:false,errorColor:"var(--muted-foreground)"};
-    window.renderWidgetMath=function(target){
-      var root=target||document.body;
-      renderMathInElement(root,Object.assign({
-        delimiters:[
-          {left:"$$",right:"$$",display:true},
-          {left:"\\\\[",right:"\\\\]",display:true},
-          {left:"\\\\(",right:"\\\\)",display:false}
-        ]
-      },mathOptions));
-      root.querySelectorAll("[data-latex]").forEach(function(node){
-        if(node.dataset.widgetMathRendered)return;
-        node.dataset.widgetMathRendered="1";
-        katex.render(node.getAttribute("data-latex"),node,Object.assign(
-          {displayMode:node.getAttribute("data-type")==="block-math"},mathOptions));
-      });
-    };
-    try{ window.renderWidgetMath(); }catch(_){}
-  }
   window.addEventListener("unhandledrejection",function(event){
     var reason=event.reason;
     report("Unhandled promise rejection: "+((reason&&reason.stack)||reason));
   });
-  var lastHeight=0;
-  function measure(){
-    // scrollHeight over getBoundingClientRect: it accounts for margins that
-    // escape the body box, which would otherwise report short and clip.
-    var height=Math.ceil(Math.max(document.documentElement.scrollHeight,document.body.scrollHeight));
-    if(!height||Math.abs(height-lastHeight)<2)return;
-    lastHeight=height;
-    post({source:FRAME,kind:"height",height:height});
-  }
-  if(typeof ResizeObserver==="function"){
-    new ResizeObserver(measure).observe(document.body);
-  }
-  window.addEventListener("load",measure);
-  measure();
-  post({source:FRAME,kind:"ready"});
+  window.addEventListener("DOMContentLoaded",function(){
+    if(typeof renderMathInElement==="function"){
+      var mathOptions={throwOnError:false,errorColor:"var(--muted-foreground)"};
+      window.renderWidgetMath=function(target){
+        var root=target||document.body;
+        renderMathInElement(root,Object.assign({
+          delimiters:[
+            {left:"$$",right:"$$",display:true},
+            {left:"\\\\[",right:"\\\\]",display:true},
+            {left:"\\\\(",right:"\\\\)",display:false}
+          ]
+        },mathOptions));
+        root.querySelectorAll("[data-latex]").forEach(function(node){
+          if(node.dataset.widgetMathRendered)return;
+          node.dataset.widgetMathRendered="1";
+          katex.render(node.getAttribute("data-latex"),node,Object.assign(
+            {displayMode:node.getAttribute("data-type")==="block-math"},mathOptions));
+        });
+      };
+      try{ window.renderWidgetMath(); }catch(_){}
+    }
+    var lastHeight=0;
+    var measureScheduled=false;
+    function measure(){
+      if(measureScheduled)return;
+      measureScheduled=true;
+      requestAnimationFrame(function(){
+        measureScheduled=false;
+        var root=document.documentElement;
+        var previousHeight=root.style.height;
+        root.style.height="max-content";
+        var height=Math.ceil(root.getBoundingClientRect().height);
+        root.style.height=previousHeight;
+        if(!height||Math.abs(height-lastHeight)<2)return;
+        lastHeight=height;
+        post({kind:"height",height:height});
+      });
+    }
+    if(typeof ResizeObserver==="function"){
+      var resizeObserver=new ResizeObserver(measure);
+      resizeObserver.observe(document.documentElement);
+      resizeObserver.observe(document.body);
+    }
+    window.addEventListener("load",measure);
+    measure();
+    post({kind:"ready"});
+  },{once:true});
 })();
 </script>
+${html}
 </body>
 </html>`;
 }
@@ -206,9 +266,31 @@ export function isWidgetSandboxFrameMessage(value: unknown): value is WidgetSand
 		return false;
 	}
 
-	const message = value as { source?: unknown; kind?: unknown };
+	const message = value as {
+		source?: unknown;
+		kind?: unknown;
+		height?: unknown;
+		message?: unknown;
+		sessionId?: unknown;
+	};
+	if (
+		message.source !== WIDGET_SANDBOX_FRAME_SOURCE ||
+		typeof message.sessionId !== "number" ||
+		!Number.isInteger(message.sessionId) ||
+		message.sessionId < 1
+	) {
+		return false;
+	}
+	if (message.kind === "ready") {
+		return true;
+	}
+	if (message.kind === "error") {
+		return typeof message.message === "string";
+	}
 	return (
-		message.source === WIDGET_SANDBOX_FRAME_SOURCE &&
-		(message.kind === "ready" || message.kind === "error" || message.kind === "height")
+		message.kind === "height" &&
+		typeof message.height === "number" &&
+		Number.isFinite(message.height) &&
+		message.height > 0
 	);
 }
diff --git a/src/features/workspaces/documents/document-widget-node.tsx b/src/features/workspaces/documents/document-widget-node.tsx
index c080de173..445ee2342 100644
--- a/src/features/workspaces/documents/document-widget-node.tsx
+++ b/src/features/workspaces/documents/document-widget-node.tsx
@@ -1,16 +1,12 @@
 import type { NodeViewProps } from "@tiptap/react";
 import { NodeViewContent, NodeViewWrapper, ReactNodeViewRenderer } from "@tiptap/react";
-import { Maximize2, Minimize2, Shapes } from "lucide-react";
-import { useState } from "react";
+import { Shapes } from "lucide-react";
 
 import {
-	CodeBlockActions,
 	CodeBlockHeader,
 	CodeBlockLabel,
 	CodeBlockTitle,
 } from "#/components/code-block/code-block-chrome";
-import { Button } from "#/components/ui/button";
-import { Dialog, DialogContent, DialogTitle } from "#/components/ui/dialog";
 import { WorkspaceWidgetSandbox } from "#/features/workspaces/components/widget/WorkspaceWidgetSandbox";
 import { Widget } from "#/features/workspaces/documents/tiptap-schema";
 
@@ -52,7 +48,6 @@ function DocumentWidgetView({ extension, node, selected }: NodeViewProps) {
 	const html = node.textContent;
 	const title = typeof node.attrs.title === "string" ? node.attrs.title : "";
 	const { onAskAiToFix } = extension.options as DocumentWidgetOptions;
-	const [isFullscreen, setIsFullscreen] = useState(false);
 	const label = title || "Widget";
 	const askAiToFix = onAskAiToFix
 		? (error: string) => onAskAiToFix(title ? `the "${title}" widget: ${error}` : error)
@@ -77,77 +72,17 @@ function DocumentWidgetView({ extension, node, selected }: NodeViewProps) {
 					<Shapes className="size-4 shrink-0 text-muted-foreground" aria-hidden="true" />
 					<CodeBlockLabel>{label}</CodeBlockLabel>
 				</CodeBlockTitle>
-				<CodeBlockActions>
-					<WidgetControl label="View fullscreen" onClick={() => setIsFullscreen(true)}>
-						<Maximize2 />
-					</WidgetControl>
-				</CodeBlockActions>
 			</CodeBlockHeader>
-			{/* Hidden while fullscreen: two live frames would run the widget twice,
-			    and the one behind the dialog would keep its own separate state. */}
-			{isFullscreen ? null : (
-				<WorkspaceWidgetSandbox
-					html={html}
-					className="workspace-document-widget-frame"
-					onAskAiToFix={askAiToFix}
-				/>
-			)}
+			<WorkspaceWidgetSandbox
+				html={html}
+				className="workspace-document-widget-frame"
+				onAskAiToFix={askAiToFix}
+			/>
 			{/* A widget's source is its text content, so ProseMirror needs somewhere
 			    to render it. Without this element Tiptap appends one itself and the
 			    raw source shows up as prose in the document. It stays hidden: the
 			    source is the frame's input, not something to read in the page. */}
 			<NodeViewContent className="workspace-document-widget-source" />
-
-			<Dialog open={isFullscreen} onOpenChange={setIsFullscreen}>
-				<DialogContent
-					className="fixed inset-0 top-0 left-0 flex h-dvh w-dvw max-w-none translate-x-0 translate-y-0 flex-col gap-0 rounded-none border-0 bg-background p-0 sm:max-w-none"
-					showCloseButton={false}
-				>
-					<CodeBlockHeader className="min-h-12 shrink-0 px-4">
-						<CodeBlockTitle>
-							<Shapes className="size-4 text-muted-foreground" aria-hidden="true" />
-							<DialogTitle className="text-sm">{label}</DialogTitle>
-						</CodeBlockTitle>
-						<CodeBlockActions>
-							<WidgetControl label="Exit fullscreen" onClick={() => setIsFullscreen(false)}>
-								<Minimize2 />
-							</WidgetControl>
-						</CodeBlockActions>
-					</CodeBlockHeader>
-					{isFullscreen ? (
-						<WorkspaceWidgetSandbox
-							html={html}
-							className="min-h-0 flex-1"
-							fill
-							onAskAiToFix={askAiToFix}
-						/>
-					) : null}
-				</DialogContent>
-			</Dialog>
 		</NodeViewWrapper>
 	);
 }
-
-function WidgetControl({
-	children,
-	label,
-	onClick,
-}: {
-	children: React.ReactNode;
-	label: string;
-	onClick: () => void;
-}) {
-	return (
-		<Button
-			aria-label={label}
-			className="size-7 text-muted-foreground [&_svg]:size-3.5"
-			onClick={onClick}
-			size="icon"
-			title={label}
-			type="button"
-			variant="ghost"
-		>
-			{children}
-		</Button>
-	);
-}

From f4e4778a0fc3319e23a41ffc6d1dbbf408f48093 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 02:31:36 -0400
Subject: [PATCH 11/32] fix(ai-chat): focus staged composer prompts

---
 .../workspaces/components/ai-chat/useConsumeComposerPrompt.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts b/src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts
index f6b923118..13aeb4c29 100644
--- a/src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts
+++ b/src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts
@@ -36,7 +36,7 @@ export function useConsumeComposerPrompt({
 		);
 		clearPrompt(workspaceId);
 
-		const frame = requestAnimationFrame(() => {
+		requestAnimationFrame(() => {
 			const textarea = textareaRef.current;
 			if (!textarea) {
 				return;
@@ -46,7 +46,5 @@ export function useConsumeComposerPrompt({
 			const caret = textarea.value.length;
 			textarea.setSelectionRange(caret, caret);
 		});
-
-		return () => cancelAnimationFrame(frame);
 	}, [pendingPrompt, workspaceId, clearPrompt, setInput, textareaRef]);
 }

From 817176e2c78c798c749297e711e3687993244027 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 02:31:46 -0400
Subject: [PATCH 12/32] test(eval): consolidate widget authoring coverage

---
 eval/__reports__/math-authoring.md     |  88 --------------
 eval/datasets/math-authoring.cases.ts  | 154 -------------------------
 eval/datasets/workspace-tools.cases.ts |  20 ++++
 eval/math-authoring.eval.ts            | 139 ----------------------
 eval/support/harness.ts                |  30 +----
 5 files changed, 21 insertions(+), 410 deletions(-)
 delete mode 100644 eval/__reports__/math-authoring.md
 delete mode 100644 eval/datasets/math-authoring.cases.ts
 delete mode 100644 eval/math-authoring.eval.ts

diff --git a/eval/__reports__/math-authoring.md b/eval/__reports__/math-authoring.md
deleted file mode 100644
index 85fb008b6..000000000
--- a/eval/__reports__/math-authoring.md
+++ /dev/null
@@ -1,88 +0,0 @@
-case | claude-sonnet| claude-haiku | gpt-luna | gemini-pro
---------------------------------------------------------------------------------------------------------
-
-document: study sheet with formulas | PASS | PASS | PASS | PASS  
-document: exponents and subscripts in prose | PASS | PASS | PASS | PASS  
-document: chemistry equation | FAIL | PASS | PASS | PASS  
-document: prices only (currency must stay pl| PASS | PASS | PASS | PASS  
-document: money AND math together (opposite | PASS | FAIL | PASS | PASS  
-chat: explain a formula | PASS | PASS | PASS | PASS  
-chat: money question | PASS | PASS | PASS | PASS  
-chat: money and math in one answer | PASS | PASS | FAIL | FAIL  
-widget: interactive with a formula | PASS | PASS | PASS | PASS  
-document: user types dollar math in the prom| PASS | PASS | PASS | PASS  
-document: user types bracket math in the pro| PASS | PASS | PASS | PASS  
-document: editing an existing doc adds an eq| FAIL tool✗ | FAIL tool✗ | FAIL tool✗ | FAIL tool✗
-
-claude-sonnet 10/12 content rules satisfied
-claude-haiku 10/12 content rules satisfied
-gpt-luna 10/12 content rules satisfied
-gemini-pro 10/12 content rules satisfied
-
-document 26/32 across all models
-chat 10/12 across all models
-widget 4/4 across all models
-
-failures
-
-[claude-sonnet] document: chemistry equation
-must not contain <sub>/<sup> tags
---- wrote: document
-/Methane Combustion
-<h1>Methane Combustion</h1><p>Methane (CH<sub></sub>) is the simplest hydrocarbon and the main component of natural gas. When it burns, it reacts with oxygen in a process called <strong>combustion</strong>, releasing energy as heat and light.</p><h2>Complete Combustion</h2><p>With plentiful oxygen, methane burns completely to form carbon dioxide and water vapor:</p><div data-type="block-math" data-latex="\ce{CH4 + 2 O2 -> CO2 + 2 H2O}"></div><p>This reaction is <strong>exothermic</strong>, meaning it releases energy. This is why methane (natural gas) is used as a f…
-
-[claude-haiku] document: money AND math together (opposite dollar rules)
-must not contain backslash-escaped \$
---- wrote: document
-/Compound Interest Guide
-<h1>Compound Interest</h1>
-
-<h2>What is Compound Interest?</h2>
-<p>Compound interest is interest earned on both the principal amount and the accumulated interest from previous periods. This creates exponential growth over time, making it a powerful tool for long-term investments and savings.</p>
-
-<h2>The Compound Interest Formula</h2>
-<p>The standard formula for compound interest is:</p>
-<div data-type="block-math" data-latex="A = P\left(1 + \frac{r}{n}\right)^{nt}"></div>
-
-<p>Where:</p>
-<ul>
-<li><strong>A</strong> = Final amount (principal + interest)</li>
-<l…
-
-[gpt-luna] chat: money and math in one answer
-must not contain \(…\) or \[…\] delimiters
---- wrote: With annual compounding:
-
-\[
-A = 2000(1.05)^3 = \$2{,}315.25
-\]
-
-You’d end up with **\$2,315.25**, earning **\$315.25** in interest.
-
-[gemini-pro] chat: money and math in one answer
-must not contain unescaped $30-style amount
---- wrote: You will end up with **\$2,315.25**.
-
-Here is the breakdown using the compound interest formula $A = P(1 + r)^t$:
-
-- **Principal ($P$):** \$2,000
-- **Interest Rate ($r$):** 5% or $0.05$
-- **Time ($t$):** 3 years
-
-$$A = 2000 \times (1 + 0.05)^3$$
-$$A = 2000 \times 1.157625$$
-$$A = 2315.25$$
-
-Your total interest earned over the 3 years will be **\$315.25**.
-
-[claude-sonnet] document: editing an existing doc adds an equation
-no workspace_edit_item input to grade
-
-[claude-haiku] document: editing an existing doc adds an equation
-no workspace_edit_item input to grade
-
-[gpt-luna] document: editing an existing doc adds an equation
-no workspace_edit_item input to grade
-
-[gemini-pro] document: editing an existing doc adds an equation
-no workspace_edit_item input to grade
diff --git a/eval/datasets/math-authoring.cases.ts b/eval/datasets/math-authoring.cases.ts
deleted file mode 100644
index aaac880fe..000000000
--- a/eval/datasets/math-authoring.cases.ts
+++ /dev/null
@@ -1,154 +0,0 @@
-import type { WorkspaceAgentInput } from "../support/harness";
-import type { ContentCheck } from "../support/scorers";
-
-/**
- * How well do models author math, currency, and chemistry across our surfaces?
- *
- * Each surface has a different, silently-failing contract:
- *  - document HTML wants `data-latex` markup and plain-text currency;
- *  - a chat reply wants `$…$` delimiters and backslash-escaped currency;
- *  - widget HTML runs in a sandbox that renders either dialect.
- * Nothing errors when a model picks the wrong one — a document just shows
- * literal dollar signs forever — so only content grading catches it.
- *
- * Prompts are deliberately written the way a real user types: casual, and
- * never naming markup. A prompt that says "use data-latex" would grade the
- * prompt rather than the system prompt we actually ship.
- */
-export interface MathAuthoringCase {
-	name: string;
-	/** Which shipped contract this case exercises. */
-	surface: "document" | "chat" | "widget";
-	input: WorkspaceAgentInput;
-	expectedTools?: string[];
-	contentChecks: ContentCheck[];
-}
-
-// --- Shipped-contract patterns ------------------------------------------------
-const MATH_MARKUP = {
-	label: 'data-type="inline-math"/"block-math" markup',
-	pattern: /data-type="(inline|block)-math"/,
-};
-// A dollar pair only counts as math if real LaTeX sits between the delimiters.
-// Plain `/\$…\$/` matched across two prices ("$30/hour … $75/hour") and reported
-// currency as math — a false failure indistinguishable from a real one.
-const DOLLAR_MATH = {
-	label: "$…$ math delimiters",
-	pattern: /\$[^$\n]{0,80}\\[a-zA-Z]+[^$\n]{0,80}\$/,
-};
-const BRACKET_MATH = { label: "\\(…\\) or \\[…\\] delimiters", pattern: /\\\(|\\\[/ };
-const SUB_SUP_TAGS = { label: "<sub>/<sup> tags", pattern: /<\/?(sub|sup)>/ };
-const ESCAPED_DOLLAR = { label: "backslash-escaped \\$", pattern: /\\\$/ };
-// Must not match the `$8` inside an already-escaped `\$80`, so require the
-// dollar to be unescaped.
-const PLAIN_DOLLAR_AMOUNT = {
-	label: "unescaped $30-style amount",
-	// Excludes both `\$80` (already escaped) and `$$2000…` (display math that
-	// happens to open with a digit) — both were scored as unescaped currency.
-	pattern: /(^|[^\\$])\$\d/,
-};
-const MHCHEM = { label: "\\ce{…}", pattern: /\\+ce\{/ };
-const DOLLAR_INSIDE_LATEX = {
-	label: "dollar signs inside data-latex",
-	pattern: /data-latex="[^"]*\$/,
-};
-
-const documentContent = (checks: Omit<ContentCheck, "source">): ContentCheck => ({
-	source: { tool: "workspace_create_items" },
-	...checks,
-});
-
-export const mathAuthoringCases: MathAuthoringCase[] = [
-	// --- Documents ------------------------------------------------------------
-	{
-		name: "doc: study sheet with formulas",
-		surface: "document",
-		input: { prompt: "can you make me a study sheet on the quadratic formula" },
-		expectedTools: ["workspace_create_items"],
-		contentChecks: [
-			documentContent({
-				mustMatch: [MATH_MARKUP],
-				mustNotMatch: [DOLLAR_MATH, BRACKET_MATH, SUB_SUP_TAGS, DOLLAR_INSIDE_LATEX],
-			}),
-		],
-	},
-	{
-		name: "doc: exponents and subscripts in prose",
-		surface: "document",
-		input: {
-			prompt:
-				"write up a short doc explaining scientific notation, use something like 6.02 times 10 to the 23 as an example",
-		},
-		expectedTools: ["workspace_create_items"],
-		contentChecks: [
-			documentContent({ mustMatch: [MATH_MARKUP], mustNotMatch: [SUB_SUP_TAGS, DOLLAR_MATH] }),
-		],
-	},
-	{
-		name: "doc: chemistry equation",
-		surface: "document",
-		input: { prompt: "make me a doc for chem class on what happens when methane burns" },
-		expectedTools: ["workspace_create_items"],
-		contentChecks: [
-			documentContent({ mustMatch: [MHCHEM], mustNotMatch: [SUB_SUP_TAGS, DOLLAR_MATH] }),
-		],
-	},
-	{
-		name: "doc: prices only (currency must stay plain)",
-		surface: "document",
-		input: {
-			prompt:
-				"make a doc for my tutoring rates - 30 an hour normally, 75 an hour for exam prep, 200 for a 3 session bundle",
-		},
-		expectedTools: ["workspace_create_items"],
-		contentChecks: [documentContent({ mustNotMatch: [ESCAPED_DOLLAR] })],
-	},
-	{
-		name: "doc: money AND math together (opposite dollar rules)",
-		surface: "document",
-		input: {
-			prompt:
-				"write me a doc on compound interest, show the formula and work through an example with 5000 dollars at 4% for 10 years",
-		},
-		expectedTools: ["workspace_create_items"],
-		contentChecks: [
-			documentContent({ mustMatch: [MATH_MARKUP], mustNotMatch: [ESCAPED_DOLLAR, DOLLAR_MATH] }),
-		],
-	},
-
-	// --- Chat replies ---------------------------------------------------------
-	{
-		name: "chat: explain a formula",
-		surface: "chat",
-		input: { prompt: "whats the quadratic formula again and how do i use it" },
-		contentChecks: [{ source: "text", mustMatch: [DOLLAR_MATH], mustNotMatch: [BRACKET_MATH] }],
-	},
-	{
-		name: "chat: money question",
-		surface: "chat",
-		input: { prompt: "a jacket is 80 bucks and its 25% off, whats the final price" },
-		contentChecks: [{ source: "text", mustNotMatch: [PLAIN_DOLLAR_AMOUNT] }],
-	},
-	{
-		name: "chat: money and math in one answer",
-		surface: "chat",
-		input: {
-			prompt: "if i invest 2000 at 5% compounded yearly for 3 years how much do i end up with",
-		},
-		contentChecks: [{ source: "text", mustNotMatch: [PLAIN_DOLLAR_AMOUNT, BRACKET_MATH] }],
-	},
-
-	// --- Widgets --------------------------------------------------------------
-	{
-		name: "widget: interactive with a formula",
-		surface: "widget",
-		input: { prompt: "build me something interactive to play with sine waves" },
-		expectedTools: ["workspace_create_items"],
-		contentChecks: [
-			{
-				source: { tool: "workspace_create_items" },
-				mustNotMatch: [{ label: "<html>/<body> wrapper", pattern: /<\/?(html|body|head)[\s>]/ }],
-			},
-		],
-	},
-];
diff --git a/eval/datasets/workspace-tools.cases.ts b/eval/datasets/workspace-tools.cases.ts
index 2b796dc98..938bd02d5 100644
--- a/eval/datasets/workspace-tools.cases.ts
+++ b/eval/datasets/workspace-tools.cases.ts
@@ -28,6 +28,11 @@ const BRACKET_DELIMITED_MATH = { label: "\\(...\\) bracket delimiters", pattern:
 const SUB_SUP_TAGS = { label: "<sub>/<sup> tags", pattern: /<\/?(sub|sup)>/ };
 const ESCAPED_DOLLAR = { label: "backslash-escaped \\$", pattern: /\\\$/ };
 const MHCHEM_CE = { label: "\\ce{...} chemistry", pattern: /\\\\?ce\{/ };
+const DOCUMENT_WIDGET_MARKUP = {
+	label: "a document widget block",
+	pattern: /data-type=["']widget["']/,
+};
+const FULL_HTML_DOCUMENT = { label: "a full HTML document", pattern: /<(html|head|body)\b/i };
 
 // A view-only scope block: mirrors what beforeTurn injects for a read-only viewer.
 // Used to prove the model respects the boundary the prompt sets.
@@ -44,6 +49,21 @@ export const workspaceToolCases: WorkspaceToolCase[] = [
 		expectedTools: ["workspace_create_items"],
 		forbiddenTools: ["workspace_delete_items"],
 	},
+	{
+		name: "interactive requests create a document with a widget block",
+		input: {
+			prompt:
+				"Create /Physics/Wave Explorer.md with an interactive widget that lets me adjust wave frequency and see the wave update.",
+		},
+		expectedTools: ["workspace_create_items"],
+		contentChecks: [
+			{
+				source: { tool: "workspace_create_items" },
+				mustMatch: [DOCUMENT_WIDGET_MARKUP],
+				mustNotMatch: [FULL_HTML_DOCUMENT],
+			},
+		],
+	},
 	{
 		name: "search before answering a content question",
 		input: {
diff --git a/eval/math-authoring.eval.ts b/eval/math-authoring.eval.ts
deleted file mode 100644
index 0b9999466..000000000
--- a/eval/math-authoring.eval.ts
+++ /dev/null
@@ -1,139 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { mathAuthoringCases } from "./datasets/math-authoring.cases";
-import { runWorkspaceAgent } from "./support/harness";
-import { scoreContent, scoreExpectedTools } from "./support/scorers";
-
-/**
- * Cross-model benchmark for math / currency / chemistry authoring.
- *
- * Unlike `workspace-tools.eval.ts` this does not assert — it measures. A model
- * scoring badly is data about the prompt, not a broken build, and failing the
- * run would hide the rest of the matrix. Results print as a table so a prompt
- * or schema change can be judged against a before/after.
- *
- * The whole matrix runs inside one test with a bounded worker pool rather than
- * as `describe.concurrent`: the report has to print after every row lands, and
- * concurrent `it`s would race it. The cap keeps us under gateway rate limits.
- *
- * Env: EVAL_MODELS (comma-separated ids from models.ts), EVAL_CONCURRENCY.
- */
-const MODELS = (process.env.EVAL_MODELS ?? "claude-sonnet,claude-haiku,gpt-luna,gemini-pro")
-	.split(",")
-	.map((id) => id.trim())
-	.filter(Boolean);
-
-const CONCURRENCY = Number(process.env.EVAL_CONCURRENCY ?? 8);
-
-interface Row {
-	model: string;
-	surface: string;
-	case: string;
-	toolPass: boolean | null;
-	contentPass: boolean;
-	detail: string;
-}
-
-async function mapWithLimit<T, R>(
-	items: T[],
-	limit: number,
-	run: (item: T) => Promise<R>,
-): Promise<R[]> {
-	const results = new Array<R>(items.length);
-	let cursor = 0;
-	const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
-		for (;;) {
-			const index = cursor++;
-			const item = items[index];
-			if (index >= items.length || item === undefined) return;
-			results[index] = await run(item);
-		}
-	});
-	await Promise.all(workers);
-	return results;
-}
-
-function formatTable(rows: Row[]): string {
-	const labels = [...new Set(rows.map((row) => `${row.surface}: ${row.case}`))];
-	const width = 44;
-	const header = ["case".padEnd(width), ...MODELS.map((model) => model.padEnd(13))].join("| ");
-	const lines = [header, "-".repeat(header.length)];
-
-	for (const label of labels) {
-		const cells = MODELS.map((model) => {
-			const row = rows.find((r) => `${r.surface}: ${r.case}` === label && r.model === model);
-			if (!row) return "—".padEnd(13);
-			const tool = row.toolPass === false ? " tool✗" : "";
-			return `${row.contentPass ? "PASS" : "FAIL"}${tool}`.padEnd(13);
-		});
-		lines.push([label.slice(0, width).padEnd(width), ...cells].join("| "));
-	}
-
-	lines.push("");
-	for (const model of MODELS) {
-		const mine = rows.filter((row) => row.model === model);
-		const passed = mine.filter((row) => row.contentPass).length;
-		lines.push(`${model.padEnd(14)} ${passed}/${mine.length} content rules satisfied`);
-	}
-
-	lines.push("");
-	for (const surface of [...new Set(rows.map((row) => row.surface))]) {
-		const mine = rows.filter((row) => row.surface === surface);
-		const passed = mine.filter((row) => row.contentPass).length;
-		lines.push(`${surface.padEnd(14)} ${passed}/${mine.length} across all models`);
-	}
-	return lines.join("\n");
-}
-
-describe.skipIf(!process.env.AI_GATEWAY_API_KEY)("math authoring benchmark", () => {
-	it("measures math/currency authoring across models", { timeout: 900_000 }, async () => {
-		const jobs = mathAuthoringCases.flatMap((testCase) =>
-			MODELS.map((model) => ({ model, testCase })),
-		);
-
-		const rows = await mapWithLimit(jobs, CONCURRENCY, async ({ model, testCase }) => {
-			try {
-				const output = await runWorkspaceAgent({ ...testCase.input, modelId: model });
-				const results = testCase.contentChecks.map((check) => scoreContent(output, check));
-				return {
-					model,
-					surface: testCase.surface,
-					case: testCase.name.replace(/^\w+: /, ""),
-					toolPass: testCase.expectedTools?.length
-						? scoreExpectedTools(output, testCase.expectedTools).pass
-						: null,
-					contentPass: results.every((result) => result.pass),
-					detail: results
-						.filter((result) => !result.pass)
-						.map((result) => result.message)
-						.join(" | "),
-				} satisfies Row;
-			} catch (error) {
-				// One model erroring must not sink the rest of the matrix.
-				return {
-					model,
-					surface: testCase.surface,
-					case: testCase.name.replace(/^\w+: /, ""),
-					toolPass: null,
-					contentPass: false,
-					detail: `turn failed: ${error instanceof Error ? error.message : String(error)}`,
-				} satisfies Row;
-			}
-		});
-
-		// The workers pool does not forward console output to stdout, so the report
-		// is written through the file-snapshot channel instead: that lands on disk
-		// from the Node side, and a re-run diffs against the previous numbers —
-		// exactly the before/after view a prompt change needs.
-		const report = [
-			formatTable(rows),
-			"",
-			"failures",
-			...rows
-				.filter((row) => !row.contentPass)
-				.map((row) => `\n[${row.model}] ${row.surface}: ${row.case}\n${row.detail}`),
-		].join("\n");
-
-		await expect(report).toMatchFileSnapshot("./__reports__/math-authoring.md");
-	});
-});
diff --git a/eval/support/harness.ts b/eval/support/harness.ts
index 9e7b159c1..ab03be5c1 100644
--- a/eval/support/harness.ts
+++ b/eval/support/harness.ts
@@ -56,19 +56,9 @@ const STANDUP_HEADING_REF = "b_standupHead1.r_head000001";
 const STANDUP_LIST_REF = "b_standupList1.r_bullet0001";
 export const EVAL_READ_FIXTURE_REFS = [STANDUP_HEADING_REF, STANDUP_LIST_REF];
 
-const KINEMATICS_HEADING_REF = "b_kinematicsH1.r_head000002";
-const KINEMATICS_MATH_REF = "b_kinematicsEq1.r_math000001";
-const PRICING_TABLE_REF = "b_pricingTable.r_table00001";
-export const EVAL_DOCUMENT_FIXTURE_REFS = [
-	KINEMATICS_HEADING_REF,
-	KINEMATICS_MATH_REF,
-	PRICING_TABLE_REF,
-];
-
 /**
  * Realistic items the model reads before editing — written exactly as the real
- * serializer emits them, so an edit turn sees production markup: math as empty
- * `data-latex` elements, currency as plain text, widgets as raw HTML.
+ * serializer emits it, so an edit turn sees production markup and real refs.
  */
 const EVAL_READ_ITEMS: Record<string, unknown> = {
 	"/Notes/Standup.md": {
@@ -77,24 +67,6 @@ const EVAL_READ_ITEMS: Record<string, unknown> = {
 		format: "html",
 		content: `<h1 data-ref="${STANDUP_HEADING_REF}">Standup</h1><ul data-ref="${STANDUP_LIST_REF}"><li>Discuss roadmap</li></ul>`,
 	},
-	"/Physics/Kinematics.md": {
-		path: "/Physics/Kinematics.md",
-		type: "document",
-		format: "html",
-		content: `<h1 data-ref="${KINEMATICS_HEADING_REF}">Kinematics</h1><p>For constant acceleration, displacement over time is</p><div data-latex="s = ut + \\tfrac{1}{2}at^2" data-type="block-math" data-ref="${KINEMATICS_MATH_REF}"></div>`,
-	},
-	"/Tutoring/Pricing.md": {
-		path: "/Tutoring/Pricing.md",
-		type: "document",
-		format: "html",
-		content: `<h1 data-ref="${PRICING_TABLE_REF}">Tutoring rates</h1><p>Standard sessions are $30 an hour, and exam-prep intensives are $75 an hour.</p>`,
-	},
-	"/Physics/Wave Explorer": {
-		path: "/Physics/Wave Explorer",
-		type: "widget",
-		format: "html",
-		content: `<style>.tx-root{height:100%;padding:16px;display:flex;flex-direction:column;gap:12px}</style><div class="tx-root"><p>Adjust the frequency to see how $y = A\\sin(2\\pi f t)$ changes.</p><input id="freq" type="range" min="1" max="10" value="3" /><canvas id="wave"></canvas></div><script>const c=document.getElementById("wave");/* draws the wave */</script>`,
-	},
 };
 
 // Per-tool stubbed outputs. Reads return the realistic item for the requested

From ca61ab32e189bb0ac9c26712e08bc24b844befc5 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 02:32:04 -0400
Subject: [PATCH 13/32] chore(deps): normalize vitest peer metadata

---
 pnpm-lock.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 67bd2a7ba..da5549a0b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -350,7 +350,7 @@ importers:
         version: 1.50.0(@voidzero-dev/vite-plus-core@0.2.2(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(typescript@6.0.3)(yaml@2.9.0))(wrangler@4.118.0(@cloudflare/workers-types@5.20260801.1))
       '@cloudflare/vitest-pool-workers':
         specifier: ^0.18.8
-        version: 0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.2)(@vitest/browser-preview@4.1.10)(@voidzero-dev/vite-plus-core@0.2.2(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(typescript@6.0.3)(yaml@2.9.0))(jsdom@28.1.0(@noble/hashes@2.2.0))(msw@2.14.6(@types/node@26.1.2)(typescript@6.0.3)))
+        version: 0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10)
       '@cloudflare/workers-types':
         specifier: ^5.20260801.1
         version: 5.20260801.1
@@ -10277,7 +10277,7 @@ snapshots:
       - bufferutil
       - utf-8-validate
 
-  '@cloudflare/vitest-pool-workers@0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.2)(@vitest/browser-preview@4.1.10)(@voidzero-dev/vite-plus-core@0.2.2(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(typescript@6.0.3)(yaml@2.9.0))(jsdom@28.1.0(@noble/hashes@2.2.0))(msw@2.14.6(@types/node@26.1.2)(typescript@6.0.3)))':
+  '@cloudflare/vitest-pool-workers@0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10)':
     dependencies:
       '@vitest/runner': 4.1.10
       '@vitest/snapshot': 4.1.10

From 4f7917bbe4fed2d04be180cf3c086fd0072817cc Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 10:46:47 -0400
Subject: [PATCH 14/32] refactor(documents): unify block read and edit refs

Return canonical block content with a fresh editRef and use the same representation for
replace_text across prose and widgets. Remove widget-specific overwrite restoration and align
tool schemas, prompts, evals, and focused coverage with the contract.
---
 eval/datasets/workspace-tools.cases.ts        |   2 +-
 eval/support/harness.ts                       |   6 +-
 eval/support/scorers.ts                       |  23 ++-
 .../ai/skills/widget-authoring/SKILL.md       |   6 +-
 .../workspaces/ai/workspace-citations.test.ts |   2 +-
 .../workspace-content-contract.test.ts        |  10 +-
 .../content/workspace-content-contract.ts     |  10 +-
 .../content/workspace-content-reader.test.ts  |  42 ++--
 .../content/workspace-content-reader.ts       |  11 +-
 .../content/workspace-read-references.test.ts |   2 +-
 .../documents/document-ai-edits.test.ts       |  90 ++++++---
 .../workspaces/documents/document-ai-edits.ts | 184 +++++++-----------
 .../documents/document-ai-html.test.ts        |  41 ++--
 .../workspaces/documents/document-ai-html.ts  | 133 ++++++-------
 .../documents/document-ai-html.worker.test.ts |   6 +-
 .../workspaces/documents/document-session.ts  |  31 +--
 .../workspaces/documents/tiptap-schema.ts     |   4 +-
 .../workspace-tool-surface.test.ts.snap       |  60 +++---
 .../operations/workspace-tool-definitions.ts  |   4 +-
 .../operations/workspace-tool-schemas.ts      |  15 +-
 20 files changed, 339 insertions(+), 343 deletions(-)

diff --git a/eval/datasets/workspace-tools.cases.ts b/eval/datasets/workspace-tools.cases.ts
index 938bd02d5..aecc19c8e 100644
--- a/eval/datasets/workspace-tools.cases.ts
+++ b/eval/datasets/workspace-tools.cases.ts
@@ -10,7 +10,7 @@ export interface WorkspaceToolCase {
 	forbiddenTools?: string[];
 	/** When set, the final answer is graded by the LLM judge against this rubric. */
 	qualityRubric?: string;
-	/** When true, the turn must produce a targeted edit whose ref traces to the read fixture. */
+	/** When true, the turn must produce a targeted edit whose editRef traces to the read fixture. */
 	requiresTargetedEditFromRead?: boolean;
 	/** Grade what the model wrote — the answer text, or a tool's arguments. */
 	contentChecks?: ContentCheck[];
diff --git a/eval/support/harness.ts b/eval/support/harness.ts
index ab03be5c1..d5f190e1b 100644
--- a/eval/support/harness.ts
+++ b/eval/support/harness.ts
@@ -49,8 +49,8 @@ export interface WorkspaceAgentInput {
 	workspaceName?: string;
 }
 
-// Deterministic read fixture: document HTML carrying real `data-ref` values, so a
-// read→edit turn can produce a *targeted* edit whose ref traces back to the read.
+// Deterministic read fixture: document HTML carrying real `data-edit-ref` values,
+// so a read→edit turn can produce a targeted edit that traces back to the read.
 // `scoreTargetedEditProvenance` checks that provenance against these refs.
 const STANDUP_HEADING_REF = "b_standupHead1.r_head000001";
 const STANDUP_LIST_REF = "b_standupList1.r_bullet0001";
@@ -65,7 +65,7 @@ const EVAL_READ_ITEMS: Record<string, unknown> = {
 		path: "/Notes/Standup.md",
 		type: "document",
 		format: "html",
-		content: `<h1 data-ref="${STANDUP_HEADING_REF}">Standup</h1><ul data-ref="${STANDUP_LIST_REF}"><li>Discuss roadmap</li></ul>`,
+		content: `<h1 data-edit-ref="${STANDUP_HEADING_REF}">Standup</h1><ul data-edit-ref="${STANDUP_LIST_REF}"><li>Discuss roadmap</li></ul>`,
 	},
 };
 
diff --git a/eval/support/scorers.ts b/eval/support/scorers.ts
index 62f0ea8f2..34aab86cb 100644
--- a/eval/support/scorers.ts
+++ b/eval/support/scorers.ts
@@ -66,36 +66,39 @@ export function scoreNoForbiddenTools(
 
 /**
  * For a read→edit turn: the model must submit a *targeted* edit (replace / insert /
- * delete) whose `ref` came from the read fixture — not a fabricated ref, and not a
- * whole-document `overwrite`. Without this, a hollow read stub plus the permissive
- * `ref` schema (any nonempty string) let a hallucinated target score a false pass.
+ * delete) whose `editRef` came from the read fixture — not a fabricated target,
+ * and not a whole-document `overwrite`. Without this, a hollow read stub plus the
+ * permissive string schema let a hallucinated target score a false pass.
  */
 export function scoreTargetedEditProvenance(
 	output: WorkspaceAgentOutput,
-	validRefs: string[],
+	validEditRefs: string[],
 ): ScoreResult {
-	const refs = new Set(validRefs);
+	const editRefs = new Set(validEditRefs);
 	const edits = output.toolCalls
 		.filter((call) => call.name === "workspace_edit_item")
 		.flatMap((call) => {
-			const input = call.input as { edits?: Array<{ op?: string; ref?: string }> };
+			const input = call.input as { edits?: Array<{ editRef?: string; op?: string }> };
 			return Array.isArray(input.edits) ? input.edits : [];
 		});
-	const isValidRef = (edit: { ref?: string }) => typeof edit.ref === "string" && refs.has(edit.ref);
+	const isValidRef = (edit: { editRef?: string }) =>
+		typeof edit.editRef === "string" && editRefs.has(edit.editRef);
 	const targeted = edits.filter((edit) => edit.op !== "overwrite" && isValidRef(edit));
 	const fabricated = edits.filter((edit) => edit.op !== "overwrite" && !isValidRef(edit));
 	const usedOverwrite = edits.some((edit) => edit.op === "overwrite");
 	const pass = targeted.length > 0 && fabricated.length === 0 && !usedOverwrite;
 
 	const reasons: string[] = [];
-	if (targeted.length === 0) reasons.push("no targeted edit used a ref from the read");
+	if (targeted.length === 0) reasons.push("no targeted edit used an editRef from the read");
 	if (fabricated.length > 0)
-		reasons.push(`fabricated ref(s): ${fabricated.map((e) => e.ref ?? "<none>").join(", ")}`);
+		reasons.push(
+			`fabricated editRef(s): ${fabricated.map((edit) => edit.editRef ?? "<none>").join(", ")}`,
+		);
 	if (usedOverwrite) reasons.push("used overwrite instead of a targeted edit");
 	return {
 		score: pass ? 1 : 0,
 		pass,
-		message: pass ? "targeted edit used a ref from the read fixture" : reasons.join("; "),
+		message: pass ? "targeted edit used an editRef from the read fixture" : reasons.join("; "),
 	};
 }
 
diff --git a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
index 0a6161972..9980eda55 100644
--- a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
+++ b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
@@ -122,9 +122,9 @@ Key points: never draw using hard-coded pixel dimensions; derive everything from
 
 ## Editing an existing widget
 
-1. Read the document. A widget comes back as an empty placeholder carrying its `data-ref` and title, so the source does not crowd out the prose. Read that ref back with `{ mode: "block", path, ref }` to get the source in full — never edit a widget from the placeholder alone.
-2. Prefer **targeted replacement**: `edits: [{ op: "replace_text", ref, find, replace }]`, where `ref` is the widget block's data-ref. Copy the exact current substring into `find`. It must match exactly once within that block — if it matches more than once the edit fails and tells you the count, so add surrounding context rather than guessing.
-3. For a ground-up rebuild, `{ op: "replace", ref, html }` swaps the whole widget block. For small changes ("make the button red", "add a reset control"), use `replace_text`. Never reach for `overwrite` to change a widget — it discards the entire document.
+1. Read the document. A widget comes back as an empty placeholder carrying its `data-edit-ref` and title, so the source does not crowd out the prose. Read it back with `{ mode: "block", path, editRef }` to get the full block and its current `editRef` — never edit a widget from the placeholder alone.
+2. Prefer **targeted replacement**: `edits: [{ op: "replace_text", editRef, find, replace }]`. A block read returns the exact HTML searched by `replace_text`; copy the current substring into `find`. It must match exactly once within that block — if it matches more than once the edit fails and tells you the count, so add surrounding context rather than guessing.
+3. For a ground-up rebuild, `{ op: "replace", editRef, html }` swaps the whole widget block. For small changes ("make the button red", "add a reset control"), use `replace_text`. Never reach for `overwrite` to change a widget — it discards the entire document.
 
 ## Good habits
 
diff --git a/src/features/workspaces/ai/workspace-citations.test.ts b/src/features/workspaces/ai/workspace-citations.test.ts
index 38cc76804..4abc04851 100644
--- a/src/features/workspaces/ai/workspace-citations.test.ts
+++ b/src/features/workspaces/ai/workspace-citations.test.ts
@@ -68,7 +68,7 @@ describe("workspace citations", () => {
 			references: [first],
 			results: [
 				{
-					content: '<h1 data-ref="b_abcdefghijkl">Notes</h1>',
+					content: '<h1 data-edit-ref="b_abcdefghijkl.r_0123456789">Notes</h1>',
 					format: "html",
 					itemId: "item-1",
 					location: {
diff --git a/src/features/workspaces/content/workspace-content-contract.test.ts b/src/features/workspaces/content/workspace-content-contract.test.ts
index 5ffc057fb..1a3710b93 100644
--- a/src/features/workspaces/content/workspace-content-contract.test.ts
+++ b/src/features/workspaces/content/workspace-content-contract.test.ts
@@ -14,7 +14,11 @@ describe("workspace read tool schemas", () => {
 					{ mode: "start", path: "/Notes" },
 					{ mode: "pages", path: "/Book.pdf", range: "1-3" },
 					{ cursor: "opaque", mode: "continue", path: "/Notes" },
-					{ mode: "block", path: "/Notes", ref: "b_abcdefghijkl.r_0123456789" },
+					{
+						editRef: "b_abcdefghijkl.r_0123456789",
+						mode: "block",
+						path: "/Notes",
+					},
 				],
 			}).success,
 		).toBe(true);
@@ -40,7 +44,7 @@ describe("workspace read tool schemas", () => {
 							{ additionalProperties: false, required: ["path", "mode"] },
 							{ additionalProperties: false, required: ["path", "mode", "range"] },
 							{ additionalProperties: false, required: ["path", "cursor", "mode"] },
-							{ additionalProperties: false, required: ["path", "mode", "ref"] },
+							{ additionalProperties: false, required: ["path", "editRef", "mode"] },
 						],
 					},
 				},
@@ -56,7 +60,7 @@ describe("workspace read tool schemas", () => {
 				references: [],
 				results: [
 					{
-						content: '<h1 data-ref="b_abcdefghijkl">Notes</h1>',
+						content: '<h1 data-edit-ref="b_abcdefghijkl.r_0123456789">Notes</h1>',
 						format: "html",
 						itemId: "notes",
 						location: { endBlock: 1, kind: "blocks", startBlock: 1, totalBlocks: 1 },
diff --git a/src/features/workspaces/content/workspace-content-contract.ts b/src/features/workspaces/content/workspace-content-contract.ts
index 1d0917a1e..2c6c25f53 100644
--- a/src/features/workspaces/content/workspace-content-contract.ts
+++ b/src/features/workspaces/content/workspace-content-contract.ts
@@ -19,7 +19,7 @@ const readWorkspaceItemsFailureCodes = [
 	"path_not_absolute",
 	"path_not_found",
 	"projection_failed",
-	"ref_not_found",
+	"edit_ref_not_found",
 	"unsupported_item_type",
 ] as const;
 
@@ -53,13 +53,13 @@ const workspaceContentReadRequestSchema = z.union([
 	}),
 	z.strictObject({
 		...workspaceContentReadRequestBase,
-		mode: z.literal("block"),
-		ref: z
+		editRef: z
 			.string()
 			.min(1)
 			.describe(
-				"data-ref of one block from an earlier read of this document, returned in full. Reads elide a widget's source, so this is how to fetch it before editing.",
+				"editRef of one block from an earlier document read. The result returns the block in full with its current editRef.",
 			),
+		mode: z.literal("block"),
 	}),
 ]);
 
@@ -147,10 +147,10 @@ const workspaceContentReadResultSchema = z.union([
 	}),
 	z.object({
 		content: z.string(),
+		editRef: z.string().min(1),
 		format: z.literal("html"),
 		itemId: z.string().min(1),
 		path: workspacePathSchema,
-		ref: z.string().min(1),
 		relations: workspaceReadRelationsSchema.optional(),
 		status: z.literal("ready"),
 		type: z.literal("block"),
diff --git a/src/features/workspaces/content/workspace-content-reader.test.ts b/src/features/workspaces/content/workspace-content-reader.test.ts
index d1f27c72b..353347329 100644
--- a/src/features/workspaces/content/workspace-content-reader.test.ts
+++ b/src/features/workspaces/content/workspace-content-reader.test.ts
@@ -3,11 +3,11 @@ import { describe, expect, it, vi } from "vitest";
 import type { WorkspaceItemSummary } from "#/features/workspaces/contracts";
 import type { WorkspaceContentReadRequest } from "#/features/workspaces/content/workspace-content-contract";
 import {
-	ensureTiptapDocumentAiRefs,
+	createDocumentAiBlockSnapshot,
+	ensureTiptapDocumentBlockIds,
 	parseDocumentAiHtml,
-	parseDocumentAiTargetRef,
-	readTiptapNodeAiRef,
-	serializeTiptapNodeToPlainAiHtml,
+	parseDocumentAiEditRef,
+	readTiptapNodeBlockId,
 } from "#/features/workspaces/documents/document-ai-html";
 import { readDocumentHtmlChunk } from "#/features/workspaces/documents/document-html-chunk";
 import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
@@ -123,9 +123,9 @@ describe("WorkspaceContentReader", () => {
 		}
 		expect(contents).toHaveLength(3);
 		expect(contents[0]).toMatch(
-			/^<h1 data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Heading<\/h1>$/,
+			/^<h1 data-edit-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Heading<\/h1>$/,
 		);
-		expect(contents[1]).toContain("<pre data-ref=");
+		expect(contents[1]).toContain("<pre data-edit-ref=");
 		expect(contents[1]).toContain("</pre>");
 		expect(contents[2]).toContain(">Tail</p>");
 	});
@@ -214,15 +214,19 @@ describe("WorkspaceContentReader", () => {
 		// The chunk carries the placeholder, not the source.
 		expect(chunk.content).not.toContain("Interactive");
 		const widgetTag = /<div[^>]*data-type="widget"[^>]*>/.exec(chunk.content)?.[0] ?? "";
-		const ref = /data-ref="([^"]+)"/.exec(widgetTag)?.[1];
-		expect(ref).toBeTruthy();
+		const editRef = /data-edit-ref="([^"]+)"/.exec(widgetTag)?.[1];
+		expect(editRef).toBeTruthy();
+		const staleEditRef = editRef?.replace(/\.r_.+$/, ".r_0000000000");
 
-		const [block] = await read([{ mode: "block", path: "/Notes", ref: ref as string }]);
-		expect(block).toMatchObject({ status: "ready", type: "block", ref });
+		const [block] = await read([
+			{ editRef: staleEditRef as string, mode: "block", path: "/Notes" },
+		]);
+		expect(block).toMatchObject({ editRef, status: "ready", type: "block" });
 		if (!block || block.status !== "ready" || block.type !== "block") {
 			throw new Error("Expected a block read.");
 		}
 		expect(block.content).toContain("Interactive");
+		expect(block.content).not.toContain("data-edit-ref");
 	});
 
 	it("keeps one ordered result for every requested path", async () => {
@@ -256,7 +260,7 @@ describe("WorkspaceContentReader", () => {
 });
 
 function createDocumentSession(input: { html: string; revision: string }) {
-	const document = ensureTiptapDocumentAiRefs(parseDocumentAiHtml(input.html)).document;
+	const document = ensureTiptapDocumentBlockIds(parseDocumentAiHtml(input.html)).document;
 	const documentNode = getTiptapDocumentSchema().nodeFromJSON(document);
 	return {
 		readHtmlChunk: vi.fn(async ({ expectedRevision, offset }) => {
@@ -268,17 +272,23 @@ function createDocumentSession(input: { html: string; revision: string }) {
 				? { ...chunk, revision: input.revision, status: "ready" as const }
 				: { status: "invalid_offset" as const };
 		}),
-		readBlock: vi.fn(async ({ ref }: { ref: string }) => {
-			const stableRef = parseDocumentAiTargetRef(ref) ?? ref;
+		readBlock: vi.fn(async ({ editRef }: { editRef: string }) => {
+			const blockId = parseDocumentAiEditRef(editRef);
+			if (!blockId) {
+				return { status: "edit_ref_not_found" as const };
+			}
 			let found: ReturnType<typeof documentNode.child> | null = null;
 			documentNode.forEach((node) => {
-				if (!found && readTiptapNodeAiRef(node) === stableRef) {
+				if (!found && readTiptapNodeBlockId(node) === blockId) {
 					found = node;
 				}
 			});
 			return found
-				? { content: serializeTiptapNodeToPlainAiHtml(found), status: "ready" as const }
-				: { status: "ref_not_found" as const };
+				? {
+						...(await createDocumentAiBlockSnapshot(found)),
+						status: "ready" as const,
+					}
+				: { status: "edit_ref_not_found" as const };
 		}),
 	};
 }
diff --git a/src/features/workspaces/content/workspace-content-reader.ts b/src/features/workspaces/content/workspace-content-reader.ts
index 7f91a66b5..8c11b0c8e 100644
--- a/src/features/workspaces/content/workspace-content-reader.ts
+++ b/src/features/workspaces/content/workspace-content-reader.ts
@@ -7,6 +7,7 @@ import type {
 	DocumentHtmlChunkReadInput,
 	DocumentHtmlChunkReadResult,
 } from "#/features/workspaces/documents/document-html-chunk";
+import type { DocumentAiBlockSnapshot } from "#/features/workspaces/documents/document-ai-html";
 import { readWorkspacePageProjection } from "#/features/workspaces/extraction/workspace-page-projection";
 import {
 	resolveWorkspaceProjectionReadiness,
@@ -26,8 +27,8 @@ const maxWorkspaceContentBatchBytes = 2 * 1024 * 1024 + 64 * 1024;
 interface DocumentContentReader {
 	readHtmlChunk(input: DocumentHtmlChunkReadInput): Promise<DocumentHtmlChunkReadResult>;
 	readBlock(input: {
-		ref: string;
-	}): Promise<{ content: string; status: "ready" } | { status: "ref_not_found" }>;
+		editRef: string;
+	}): Promise<(DocumentAiBlockSnapshot & { status: "ready" }) | { status: "edit_ref_not_found" }>;
 }
 
 interface PendingReadyResult {
@@ -159,17 +160,17 @@ async function readDocumentBlock(input: {
 	}
 
 	const documentSession = await input.getDocumentSession(input.item.id);
-	const block = await documentSession.readBlock({ ref: input.request.ref });
+	const block = await documentSession.readBlock({ editRef: input.request.editRef });
 	if (block.status !== "ready") {
-		return { code: "ref_not_found", path: input.path, status: "failed" };
+		return { code: "edit_ref_not_found", path: input.path, status: "failed" };
 	}
 
 	return {
 		content: block.content,
+		editRef: block.editRef,
 		format: "html",
 		itemId: input.item.id,
 		path: input.path,
-		ref: input.request.ref,
 		status: "ready",
 		type: "block",
 	};
diff --git a/src/features/workspaces/content/workspace-read-references.test.ts b/src/features/workspaces/content/workspace-read-references.test.ts
index a7311ad94..efe0a846b 100644
--- a/src/features/workspaces/content/workspace-read-references.test.ts
+++ b/src/features/workspaces/content/workspace-read-references.test.ts
@@ -175,7 +175,7 @@ function documentResult(): Extract<
 	{ status: "ready"; type: "document" }
 > {
 	return {
-		content: '<h1 data-ref="b_abcdefghijkl">Notes</h1>',
+		content: '<h1 data-edit-ref="b_abcdefghijkl.r_0123456789">Notes</h1>',
 		format: "html",
 		itemId: "document-1",
 		location: { endBlock: 1, kind: "blocks", startBlock: 1, totalBlocks: 1 },
diff --git a/src/features/workspaces/documents/document-ai-edits.test.ts b/src/features/workspaces/documents/document-ai-edits.test.ts
index bcb1e5579..401a3c9b7 100644
--- a/src/features/workspaces/documents/document-ai-edits.test.ts
+++ b/src/features/workspaces/documents/document-ai-edits.test.ts
@@ -2,65 +2,71 @@ import { describe, expect, it } from "vitest";
 
 import { applyDocumentAiEdits } from "#/features/workspaces/documents/document-ai-edits";
 import {
-	ensureTiptapDocumentAiRefs,
+	ensureTiptapDocumentBlockIds,
 	parseDocumentAiHtml,
+	parseDocumentAiEditRef,
+	serializeTiptapNodeToEditableAiHtml,
 	serializeTiptapDocumentToAiHtml,
 } from "#/features/workspaces/documents/document-ai-html";
 import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
 
 describe("document AI edits", () => {
-	it("applies consecutive structural edits while preserving the target ref", async () => {
+	it("applies consecutive structural edits while preserving the block ID", async () => {
 		const document = createDocument("<h1>Title</h1><p>Before</p>");
-		const paragraphRef = await getRef(document, "p");
+		const paragraphEditRef = await getEditRef(document, "p");
 		const result = await applyDocumentAiEdits(document, [
-			{ html: "<p>After</p>", op: "replace", ref: paragraphRef },
-			{ html: "<blockquote><p>More</p></blockquote>", op: "insert_after", ref: paragraphRef },
+			{ editRef: paragraphEditRef, html: "<p>After</p>", op: "replace" },
+			{
+				editRef: paragraphEditRef,
+				html: "<blockquote><p>More</p></blockquote>",
+				op: "insert_after",
+			},
 		]);
 
 		expect(result).toMatchObject({ applied: 2, failed: 0, status: "applied" });
 		const html = await serializeTiptapDocumentToAiHtml(result.document);
-		expect(html).toContain(`<p data-ref="${stableRef(paragraphRef)}.r_`);
-		expect(html).toContain(">After</p><blockquote data-ref=");
+		expect(html).toContain(`<p data-edit-ref="${parseDocumentAiEditRef(paragraphEditRef)}.r_`);
+		expect(html).toContain(">After</p><blockquote data-edit-ref=");
 	});
 
 	it("keeps successful edits when a later target is missing", async () => {
 		const document = createDocument("<p>One</p><p>Two</p>");
-		const firstRef = await getRef(document, "p");
+		const firstEditRef = await getEditRef(document, "p");
 		const result = await applyDocumentAiEdits(document, [
-			{ html: "<p>Updated</p>", op: "replace", ref: firstRef },
-			{ op: "delete", ref: "b_missingref00.r_0000000000" },
+			{ editRef: firstEditRef, html: "<p>Updated</p>", op: "replace" },
+			{ editRef: "b_missingref00.r_0000000000", op: "delete" },
 		]);
 
 		expect(result).toMatchObject({
 			applied: 1,
 			failed: 1,
-			failures: [{ code: "ref_not_found", index: 1 }],
+			failures: [{ code: "edit_ref_not_found", index: 1 }],
 			status: "partial",
 		});
 		expect(await serializeTiptapDocumentToAiHtml(result.document)).toContain(">Updated</p>");
 	});
 
-	it("rejects a ref after that block changed in another edit call", async () => {
+	it("rejects an editRef after that block changed in another edit call", async () => {
 		const document = createDocument("<p>Before</p>");
-		const originalRef = await getRef(document, "p");
+		const originalEditRef = await getEditRef(document, "p");
 		const first = await applyDocumentAiEdits(document, [
-			{ html: "<p>Changed</p>", op: "replace", ref: originalRef },
+			{ editRef: originalEditRef, html: "<p>Changed</p>", op: "replace" },
 		]);
 		const stale = await applyDocumentAiEdits(first.document, [
-			{ html: "<p>Overwritten</p>", op: "replace", ref: originalRef },
+			{ editRef: originalEditRef, html: "<p>Overwritten</p>", op: "replace" },
 		]);
 
 		expect(stale).toMatchObject({
 			applied: 0,
 			failed: 1,
-			failures: [{ code: "stale_target", index: 0 }],
+			failures: [{ code: "edit_ref_stale", index: 0 }],
 			status: "failed",
 		});
 	});
 
 	it("supports whole-document rewrites without carrying old block identities by position", async () => {
 		const document = createDocument("<p>Before</p>");
-		const originalRef = stableRef(await getRef(document, "p"));
+		const originalBlockId = parseDocumentAiEditRef(await getEditRef(document, "p"));
 		const rewritten = await applyDocumentAiEdits(document, [
 			{ html: "<h1>New</h1><p>Document</p>", op: "overwrite" },
 		]);
@@ -75,7 +81,9 @@ describe("document AI edits", () => {
 			failures: [{ code: "no_change", index: 0 }],
 			status: "failed",
 		});
-		expect(await serializeTiptapDocumentToAiHtml(rewritten.document)).not.toContain(originalRef);
+		expect(await serializeTiptapDocumentToAiHtml(rewritten.document)).not.toContain(
+			originalBlockId,
+		);
 	});
 
 	it("matches the editor's trailing paragraph after a final structural block", async () => {
@@ -86,7 +94,7 @@ describe("document AI edits", () => {
 
 		expect(rewritten.document.content?.at(-1)).toMatchObject({ type: "paragraph" });
 		expect(await serializeTiptapDocumentToAiHtml(rewritten.document)).toMatch(
-			/<\/ul><p data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"><\/p>$/,
+			/<\/ul><p data-edit-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"><\/p>$/,
 		);
 	});
 
@@ -94,9 +102,9 @@ describe("document AI edits", () => {
 		const document = createDocument(
 			'<div data-type="widget" title="Timer">&lt;button&gt;Start&lt;/button&gt;</div>',
 		);
-		const ref = await getRef(document, "div");
+		const editRef = await getEditRef(document, "div");
 		const result = await applyDocumentAiEdits(document, [
-			{ find: ">Start<", op: "replace_text", ref, replace: ">Go<" },
+			{ editRef, find: "Start", op: "replace_text", replace: "Go" },
 		]);
 
 		expect(result).toMatchObject({ applied: 1, failed: 0, status: "applied" });
@@ -107,9 +115,9 @@ describe("document AI edits", () => {
 		const document = createDocument(
 			'<div data-type="widget">&lt;button&gt;Run&lt;/button&gt;&lt;button&gt;Run&lt;/button&gt;</div>',
 		);
-		const ref = await getRef(document, "div");
+		const editRef = await getEditRef(document, "div");
 		const result = await applyDocumentAiEdits(document, [
-			{ find: "Run", op: "replace_text", ref, replace: "Stop" },
+			{ editRef, find: "Run", op: "replace_text", replace: "Stop" },
 		]);
 
 		expect(result).toMatchObject({
@@ -120,26 +128,46 @@ describe("document AI edits", () => {
 		});
 		expect(getWidgetSource(result.document)).toContain("Run</button><button>Run");
 	});
+
+	it("replaces the exact widget HTML returned by a block read", async () => {
+		const document = createDocument(
+			'<div data-type="widget" title="Timer">&lt;button&gt;Start&lt;/button&gt;</div>',
+		);
+		const editRef = await getEditRef(document, "div");
+		const content = serializeTiptapNodeToEditableAiHtml(
+			getTiptapDocumentSchema().nodeFromJSON(document).child(0),
+		);
+		const result = await applyDocumentAiEdits(document, [
+			{
+				editRef,
+				find: content,
+				op: "replace_text",
+				replace: '<div data-type="widget" title="Clock">&lt;button&gt;Go&lt;/button&gt;</div>',
+			},
+		]);
+
+		expect(result).toMatchObject({ applied: 1, failed: 0, status: "applied" });
+		expect(getTiptapDocumentSchema().nodeFromJSON(result.document).child(0).attrs.title).toBe(
+			"Clock",
+		);
+		expect(getWidgetSource(result.document)).toBe("<button>Go</button>");
+	});
 });
 
 function createDocument(html: string) {
-	return ensureTiptapDocumentAiRefs(parseDocumentAiHtml(html)).document;
+	return ensureTiptapDocumentBlockIds(parseDocumentAiHtml(html)).document;
 }
 
-async function getRef(document: ReturnType<typeof createDocument>, tagName: string) {
+async function getEditRef(document: ReturnType<typeof createDocument>, tagName: string) {
 	const match = (await serializeTiptapDocumentToAiHtml(document)).match(
-		new RegExp(`<${tagName}\\b[^>]*\\sdata-ref="([^"]+)"`),
+		new RegExp(`<${tagName}\\b[^>]*\\sdata-edit-ref="([^"]+)"`),
 	);
 	if (!match?.[1]) {
-		throw new Error(`Expected ${tagName} ref.`);
+		throw new Error(`Expected ${tagName} editRef.`);
 	}
 	return match[1];
 }
 
-function stableRef(ref: string) {
-	return ref.split(".r_")[0];
-}
-
 function getWidgetSource(document: ReturnType<typeof createDocument>) {
 	let source = "";
 	getTiptapDocumentSchema()
diff --git a/src/features/workspaces/documents/document-ai-edits.ts b/src/features/workspaces/documents/document-ai-edits.ts
index e8d77f9a1..aa3c249fb 100644
--- a/src/features/workspaces/documents/document-ai-edits.ts
+++ b/src/features/workspaces/documents/document-ai-edits.ts
@@ -2,13 +2,13 @@ import { Fragment, type Node as ProseMirrorNode } from "@tiptap/pm/model";
 import { z } from "zod";
 
 import {
-	createDocumentAiTargetRef,
+	createDocumentAiEditRef,
 	DocumentAiHtmlError,
-	ensureProseMirrorDocumentAiRefs,
+	ensureProseMirrorDocumentBlockIds,
 	parseDocumentAiHtml,
-	parseDocumentAiTargetRef,
-	serializeTiptapNodeToPlainAiHtml,
-	readTiptapNodeAiRef,
+	parseDocumentAiEditRef,
+	serializeTiptapNodeToEditableAiHtml,
+	readTiptapNodeBlockId,
 	withTiptapNodeAiRef,
 } from "#/features/workspaces/documents/document-ai-html";
 import type { DocumentEditLineChanges } from "#/features/workspaces/documents/document-edit-receipt";
@@ -18,40 +18,42 @@ import {
 } from "#/features/workspaces/documents/tiptap-document";
 import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
 
-const documentAiRefSchema = z
+const documentEditRefSchema = z
 	.string()
 	.trim()
 	.min(1)
 	.max(64)
-	.describe('Exact data-ref from a recent HTML read. Put it in the "ref" field, never "target".');
+	.describe("Exact editRef from a recent document or block read.");
 export const documentAiHtmlSchema = z
 	.string()
 	.max(512_000)
-	.describe("Schema-constrained HTML fragment. Model-supplied data-ref attributes are ignored.");
+	.describe(
+		"Schema-constrained HTML fragment. Model-supplied data-edit-ref attributes are ignored.",
+	);
 const documentAiEditTextSchema = z.string().max(512_000);
 
 export const documentAiEditSchema = z.union([
 	z.strictObject({
+		editRef: documentEditRefSchema,
 		html: documentAiHtmlSchema,
 		op: z.enum(["insert_after", "insert_before", "replace"]),
-		ref: documentAiRefSchema,
 	}),
 	z.strictObject({
+		editRef: documentEditRefSchema,
 		op: z.literal("delete"),
-		ref: documentAiRefSchema,
 	}),
 	z.strictObject({
 		html: documentAiHtmlSchema,
 		op: z.literal("overwrite"),
 	}),
 	z.strictObject({
+		editRef: documentEditRefSchema,
 		find: documentAiEditTextSchema
 			.min(1)
 			.describe(
 				"Exact text to replace inside the target block, copied from a read. It must appear exactly once in that block; if it matches more than once the edit fails instead of replacing every occurrence.",
 			),
 		op: z.literal("replace_text"),
-		ref: documentAiRefSchema,
 		replace: documentAiEditTextSchema.describe(
 			"Replacement text. May be empty to delete the matched text.",
 		),
@@ -65,8 +67,8 @@ export const documentAiEditFailureCodes = [
 	"edit_not_unique",
 	"invalid_html",
 	"no_change",
-	"ref_not_found",
-	"stale_target",
+	"edit_ref_not_found",
+	"edit_ref_stale",
 ] as const;
 
 export type DocumentAiEdit = z.infer<typeof documentAiEditSchema>;
@@ -89,28 +91,28 @@ export async function applyDocumentAiEdits(
 ): Promise<DocumentAiEditResult> {
 	let current = getTiptapDocumentSchema().nodeFromJSON(document);
 	// Validate every targeted edit against the document as it existed when this
-	// tool call began. That lets one ordered batch reuse a read ref while still
-	// rejecting the same ref in a later call after a human or agent changed it.
-	const requestedStableRefs = new Set(
+	// tool call began. That lets one ordered batch reuse an editRef while still
+	// rejecting it in a later call after a human or agent changed the block.
+	const requestedBlockIds = new Set(
 		edits.flatMap((edit) => {
 			if (edit.op === "overwrite") {
 				return [];
 			}
-			const stableRef = parseDocumentAiTargetRef(edit.ref);
-			return stableRef ? [stableRef] : [];
+			const blockId = parseDocumentAiEditRef(edit.editRef);
+			return blockId ? [blockId] : [];
 		}),
 	);
 	const requestedTargets: Array<readonly [string, ProseMirrorNode]> = [];
 	current.forEach((node) => {
-		const stableRef = readTiptapNodeAiRef(node);
-		if (stableRef && requestedStableRefs.has(stableRef)) {
-			requestedTargets.push([stableRef, node]);
+		const blockId = readTiptapNodeBlockId(node);
+		if (blockId && requestedBlockIds.has(blockId)) {
+			requestedTargets.push([blockId, node]);
 		}
 	});
-	const targetRefByStableRef = new Map(
+	const editRefByBlockId = new Map(
 		await Promise.all(
 			requestedTargets.map(
-				async ([stableRef, node]) => [stableRef, await createDocumentAiTargetRef(node)] as const,
+				async ([blockId, node]) => [blockId, await createDocumentAiEditRef(node)] as const,
 			),
 		),
 	);
@@ -118,21 +120,21 @@ export async function applyDocumentAiEdits(
 	let applied = 0;
 
 	for (const [index, edit] of edits.entries()) {
-		let stableRef: string | undefined;
+		let blockId: string | undefined;
 		if (edit.op !== "overwrite") {
-			const parsedRef = parseDocumentAiTargetRef(edit.ref);
-			if (!parsedRef || !targetRefByStableRef.has(parsedRef)) {
-				failures.push({ code: "ref_not_found", index });
+			const parsedBlockId = parseDocumentAiEditRef(edit.editRef);
+			if (!parsedBlockId || !editRefByBlockId.has(parsedBlockId)) {
+				failures.push({ code: "edit_ref_not_found", index });
 				continue;
 			}
-			if (targetRefByStableRef.get(parsedRef) !== edit.ref) {
-				failures.push({ code: "stale_target", index });
+			if (editRefByBlockId.get(parsedBlockId) !== edit.editRef) {
+				failures.push({ code: "edit_ref_stale", index });
 				continue;
 			}
-			stableRef = parsedRef;
+			blockId = parsedBlockId;
 		}
 
-		const result = applyDocumentAiEdit(current, edit, stableRef);
+		const result = applyDocumentAiEdit(current, edit, blockId);
 		if (result.status === "failed") {
 			failures.push({
 				code: result.code,
@@ -209,12 +211,12 @@ function countDocumentLines(document: TiptapDocumentJson) {
 function applyDocumentAiEdit(
 	document: ProseMirrorNode,
 	edit: DocumentAiEdit,
-	stableRef?: string,
+	blockId?: string,
 ):
 	| { code: DocumentAiEditFailureCode; detail?: string; status: "failed" }
 	| { document: ProseMirrorNode; status: "applied" } {
 	if (edit.op === "overwrite") {
-		const parsed = parseEditHtml(edit.html, document);
+		const parsed = parseEditHtml(edit.html);
 		if (!parsed.children) {
 			return { code: "invalid_html", detail: parsed.detail, status: "failed" };
 		}
@@ -225,12 +227,12 @@ function applyDocumentAiEdit(
 			: { document: next, status: "applied" };
 	}
 
-	if (!stableRef) {
-		throw new Error("Targeted document edits require a validated stable ref.");
+	if (!blockId) {
+		throw new Error("Targeted document edits require a validated block id.");
 	}
-	const targetIndex = findTargetIndex(document, stableRef);
+	const targetIndex = findTargetIndex(document, blockId);
 	if (targetIndex === -1) {
-		return { code: "ref_not_found", status: "failed" };
+		return { code: "edit_ref_not_found", status: "failed" };
 	}
 
 	const children = getDocumentChildren(document);
@@ -238,51 +240,40 @@ function applyDocumentAiEdit(
 		children.splice(targetIndex, 1);
 	} else if (edit.op === "replace_text") {
 		const target = document.child(targetIndex);
-		const replaced = replaceUniqueText(readBlockText(target), edit.find, edit.replace);
+		const replaced = replaceUniqueText(
+			serializeTiptapNodeToEditableAiHtml(target),
+			edit.find,
+			edit.replace,
+		);
 		if (!replaced.ok) {
 			return { code: replaced.code, detail: replaced.detail, status: "failed" };
 		}
 
-		if (target.type.name === "widget") {
-			// A widget holds raw source, so the replacement is written straight back.
-			children.splice(
-				targetIndex,
-				1,
-				target.type.create(
-					target.attrs,
-					replaced.text ? getTiptapDocumentSchema().text(replaced.text) : undefined,
-					target.marks,
-				),
-			);
-		} else {
-			// Prose is markup, so the edited HTML is re-parsed and refitted to the
-			// schema exactly as a `replace` would be.
-			const parsed = parseEditHtml(replaced.text, document);
-			if (!parsed.children) {
-				return { code: "invalid_html", detail: parsed.detail, status: "failed" };
-			}
-			const targetRef = readTiptapNodeAiRef(target);
-			const firstNode = parsed.children[0];
-			children.splice(
-				targetIndex,
-				1,
-				...(targetRef && firstNode
-					? [withTiptapNodeAiRef(firstNode, targetRef), ...parsed.children.slice(1)]
-					: parsed.children),
-			);
+		const parsed = parseEditHtml(replaced.text);
+		if (!parsed.children) {
+			return { code: "invalid_html", detail: parsed.detail, status: "failed" };
 		}
+		const targetBlockId = readTiptapNodeBlockId(target);
+		const firstNode = parsed.children[0];
+		children.splice(
+			targetIndex,
+			1,
+			...(targetBlockId && firstNode
+				? [withTiptapNodeAiRef(firstNode, targetBlockId), ...parsed.children.slice(1)]
+				: parsed.children),
+		);
 	} else {
-		const parsed = parseEditHtml(edit.html, document);
+		const parsed = parseEditHtml(edit.html);
 		if (!parsed.children) {
 			return { code: "invalid_html", detail: parsed.detail, status: "failed" };
 		}
-		const targetRef = readTiptapNodeAiRef(document.child(targetIndex));
+		const targetBlockId = readTiptapNodeBlockId(document.child(targetIndex));
 		const firstNode = parsed.children[0];
-		// A replacement inherits the ref of the block it stands in for, so a model
-		// holding that ref can keep editing it.
+		// A replacement inherits the block ID of the block it stands in for, so a
+		// model holding its editRef can keep editing it.
 		const inserted =
-			edit.op === "replace" && targetRef && firstNode
-				? [withTiptapNodeAiRef(firstNode, targetRef), ...parsed.children.slice(1)]
+			edit.op === "replace" && targetBlockId && firstNode
+				? [withTiptapNodeAiRef(firstNode, targetBlockId), ...parsed.children.slice(1)]
 				: parsed.children;
 
 		switch (edit.op) {
@@ -304,40 +295,7 @@ function applyDocumentAiEdit(
 		: { document: next, status: "applied" };
 }
 
-/**
- * Source for a widget the model sent back empty, looked up in the document as it
- * stands. Reads elide widget source, so any HTML that came from a read carries
- * placeholders — a `overwrite` echoing them back would otherwise blank every
- * widget in the document.
- */
-function createWidgetSourceResolver(document: ProseMirrorNode) {
-	return (ref: string) => {
-		const blockRef = parseDocumentAiTargetRef(ref) ?? ref;
-		let source: string | null = null;
-		document.forEach((node) => {
-			if (
-				source === null &&
-				node.type.name === "widget" &&
-				readTiptapNodeAiRef(node) === blockRef
-			) {
-				source = node.textContent;
-			}
-		});
-		return source;
-	};
-}
-
-/** The text `replace_text` matches against: raw source for a widget, markup otherwise. */
-function readBlockText(node: ProseMirrorNode): string {
-	if (node.type.name === "widget") {
-		return node.textContent;
-	}
-	// Serialized without its ref, and the model's `find` is stripped the same way,
-	// so text copied from a read matches whether or not it kept the data-ref.
-	return serializeTiptapNodeToPlainAiHtml(withTiptapNodeAiRef(node, null));
-}
-
-const DATA_REF_ATTRIBUTE = /\s+data-ref="[^"]*"/g;
+const DATA_EDIT_REF_ATTRIBUTE = /\s+data-edit-ref="[^"]*"/g;
 
 /**
  * Replaces a single unique occurrence, or explains why it could not.
@@ -353,8 +311,8 @@ function replaceUniqueText(
 ):
 	| { ok: true; text: string }
 	| { ok: false; code: "edit_not_found" | "edit_not_unique"; detail: string } {
-	const haystack = source.replaceAll("\r\n", "\n").replace(DATA_REF_ATTRIBUTE, "");
-	const needle = find.replaceAll("\r\n", "\n").replace(DATA_REF_ATTRIBUTE, "");
+	const haystack = source.replaceAll("\r\n", "\n").replace(DATA_EDIT_REF_ATTRIBUTE, "");
+	const needle = find.replaceAll("\r\n", "\n").replace(DATA_EDIT_REF_ATTRIBUTE, "");
 	const matches = haystack.split(needle).length - 1;
 
 	if (matches === 0) {
@@ -371,13 +329,11 @@ function replaceUniqueText(
 	return { ok: true, text: haystack.replace(needle, replace) };
 }
 
-function parseEditHtml(html: string, document: ProseMirrorNode) {
+function parseEditHtml(html: string) {
 	try {
 		return {
 			children: getDocumentChildren(
-				getTiptapDocumentSchema().nodeFromJSON(
-					parseDocumentAiHtml(html, { resolveWidgetSource: createWidgetSourceResolver(document) }),
-				),
+				getTiptapDocumentSchema().nodeFromJSON(parseDocumentAiHtml(html)),
 			),
 		};
 	} catch (error) {
@@ -400,7 +356,7 @@ function createDocument(children: ProseMirrorNode[]) {
 		editorChildren.push(schema.nodes.paragraph.create());
 	}
 
-	const document = ensureProseMirrorDocumentAiRefs(
+	const document = ensureProseMirrorDocumentBlockIds(
 		schema.topNodeType.create(null, Fragment.fromArray(editorChildren)),
 	).document;
 	document.check();
@@ -420,9 +376,9 @@ function withoutTopLevelAiRefs(document: ProseMirrorNode) {
 	);
 }
 
-function findTargetIndex(document: ProseMirrorNode, ref: string) {
+function findTargetIndex(document: ProseMirrorNode, blockId: string) {
 	for (let index = 0; index < document.childCount; index++) {
-		if (readTiptapNodeAiRef(document.child(index)) === ref) {
+		if (readTiptapNodeBlockId(document.child(index)) === blockId) {
 			return index;
 		}
 	}
diff --git a/src/features/workspaces/documents/document-ai-html.test.ts b/src/features/workspaces/documents/document-ai-html.test.ts
index 61c7cc11b..ac9bfb7d9 100644
--- a/src/features/workspaces/documents/document-ai-html.test.ts
+++ b/src/features/workspaces/documents/document-ai-html.test.ts
@@ -2,21 +2,23 @@ import { describe, expect, it } from "vitest";
 
 import {
 	DocumentAiHtmlError,
-	ensureTiptapDocumentAiRefs,
+	ensureTiptapDocumentBlockIds,
 	parseDocumentAiHtml,
 	serializeTiptapDocumentToAiHtml,
 } from "#/features/workspaces/documents/document-ai-html";
 
 describe("document AI HTML", () => {
 	it("round-trips supported rich content through the Tiptap schema", async () => {
-		const document = ensureTiptapDocumentAiRefs(
+		const document = ensureTiptapDocumentBlockIds(
 			parseDocumentAiHtml(
 				'<h1>Notes</h1><p>Use <strong>bold</strong>, <a href="https://thinkex.app">links</a>, and <span data-type="inline-math" data-latex="x^2"></span>.</p><ul data-type="taskList"><li data-type="taskItem" data-checked="true"><label><input checked type="checkbox"><span></span></label><div><p>Done</p></div></li></ul>',
 			),
 		).document;
 		const html = await serializeTiptapDocumentToAiHtml(document);
 
-		expect(html).toMatch(/^<h1 data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Notes<\/h1>/);
+		expect(html).toMatch(
+			/^<h1 data-edit-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Notes<\/h1>/,
+		);
 		expect(html).toContain("<strong>bold</strong>");
 		expect(html).toContain('data-type="inline-math"');
 		expect(html).toContain('data-type="taskItem"');
@@ -28,7 +30,7 @@ describe("document AI HTML", () => {
 		// with an explicit instruction not to. This used to throw and lose the
 		// entire document rather than the two characters it could not represent.
 		const html = await serializeTiptapDocumentToAiHtml(
-			ensureTiptapDocumentAiRefs(parseDocumentAiHtml("<p>CH<sub>4</sub> and x<sup>2</sup></p>"))
+			ensureTiptapDocumentBlockIds(parseDocumentAiHtml("<p>CH<sub>4</sub> and x<sup>2</sup></p>"))
 				.document,
 		);
 
@@ -37,14 +39,15 @@ describe("document AI HTML", () => {
 		expect(html).not.toContain("<sub>");
 	});
 
-	it("ignores refs supplied in model-authored HTML", async () => {
+	it("ignores editRefs supplied in model-authored HTML", async () => {
 		const html = await serializeTiptapDocumentToAiHtml(
-			ensureTiptapDocumentAiRefs(parseDocumentAiHtml('<p data-ref="b_modelchosen1">Hello</p>'))
-				.document,
+			ensureTiptapDocumentBlockIds(
+				parseDocumentAiHtml('<p data-edit-ref="b_modelchosen1">Hello</p>'),
+			).document,
 		);
 
 		expect(html).not.toContain("b_modelchosen1");
-		expect(html).toMatch(/data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"/);
+		expect(html).toMatch(/data-edit-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"/);
 	});
 
 	it("normalizes malformed but recoverable HTML", () => {
@@ -60,7 +63,7 @@ describe("document AI HTML", () => {
 	});
 
 	it("keeps only schema-supported attributes and safe links", async () => {
-		const document = ensureTiptapDocumentAiRefs(
+		const document = ensureTiptapDocumentBlockIds(
 			parseDocumentAiHtml(
 				'<p class="ignored" data-extra="ignored" onclick="alert(1)"><a href="javascript:alert(1)" title="ignored">Unsafe</a></p>',
 			),
@@ -78,7 +81,7 @@ describe("document AI HTML", () => {
 		// Rejecting cost the entire document to save formatting we can flatten:
 		// a probe of realistic model markup found 12 of 20 snippets refused.
 		const html = await serializeTiptapDocumentToAiHtml(
-			ensureTiptapDocumentAiRefs(
+			ensureTiptapDocumentBlockIds(
 				parseDocumentAiHtml(
 					'<figure><p>Kept</p></figure><div class="callout"><h5>Heading</h5></div><dl><dt>Force</dt><dd>Mass times acceleration</dd></dl><p>An <span class="hl">inline</span> span</p>',
 				),
@@ -105,10 +108,10 @@ describe("document AI HTML", () => {
 		);
 	});
 
-	it("elides widget source for the model but keeps the ref", async () => {
+	it("elides widget source for the model but keeps the editRef", async () => {
 		const source = '<style>.a{color:red}</style><div class="a">Hi</div>';
 		const html = await serializeTiptapDocumentToAiHtml(
-			ensureTiptapDocumentAiRefs(
+			ensureTiptapDocumentBlockIds(
 				parseDocumentAiHtml(
 					`<div data-type="widget" title="Sine">${source.replaceAll("<", "&lt;")}</div>`,
 				),
@@ -118,18 +121,6 @@ describe("document AI HTML", () => {
 		// A widget runs to kilobytes; inlining it in every read crowds out the prose.
 		expect(html).not.toContain("color:red");
 		expect(html).toContain('data-type="widget"');
-		expect(html).toMatch(/data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"/);
-	});
-
-	it("restores an elided widget instead of blanking it", () => {
-		// The model reads a widget as an empty placeholder, so an overwrite that
-		// echoes the read back would otherwise destroy the source permanently.
-		const source = '<div class="a">Hi</div>';
-		const restored = parseDocumentAiHtml(
-			'<div data-type="widget" data-ref="b_abcdefghijkl.r_1234567890"></div>',
-			{ resolveWidgetSource: (ref) => (ref.startsWith("b_abcdefghijkl") ? source : null) },
-		);
-
-		expect(JSON.stringify(restored)).toContain("Hi");
+		expect(html).toMatch(/data-edit-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"/);
 	});
 });
diff --git a/src/features/workspaces/documents/document-ai-html.ts b/src/features/workspaces/documents/document-ai-html.ts
index 2d9643630..d58c5b001 100644
--- a/src/features/workspaces/documents/document-ai-html.ts
+++ b/src/features/workspaces/documents/document-ai-html.ts
@@ -14,28 +14,19 @@ import {
 import { sha256Base64UrlText } from "#/lib/binary";
 
 const TEXT_NODE = 3;
-const documentAiRefPattern = /^b_[A-Za-z0-9_-]{12}$/;
-const documentAiTargetRefPattern = /^(b_[A-Za-z0-9_-]{12})\.r_[A-Za-z0-9_-]{10}$/;
+const documentBlockIdPattern = /^b_[A-Za-z0-9_-]{12}$/;
+const documentAiEditRefPattern = /^(b_[A-Za-z0-9_-]{12})\.r_[A-Za-z0-9_-]{10}$/;
 export class DocumentAiHtmlError extends Error {}
 
-export interface ParseDocumentAiHtmlOptions {
-	/**
-	 * Source for a widget the model sent back empty. Reads elide widget source,
-	 * so HTML that came from a read carries placeholders — without this they
-	 * would be written back as empty widgets, silently destroying the source.
-	 */
-	resolveWidgetSource?: (ref: string) => string | null;
+export interface DocumentAiBlockSnapshot {
+	content: string;
+	editRef: string;
 }
 
-export function parseDocumentAiHtml(
-	html: string,
-	options: ParseDocumentAiHtmlOptions = {},
-): TiptapDocumentJson {
+export function parseDocumentAiHtml(html: string): TiptapDocumentJson {
 	const htmlDocument = createHtmlDocument();
 	htmlDocument.body.innerHTML = html;
 
-	restoreElidedWidgets(htmlDocument, options.resolveWidgetSource);
-
 	// A citation the operation could not resolve to a real item cannot navigate
 	// anywhere, so it becomes its own label rather than failing the write.
 	for (const element of htmlDocument.body.querySelectorAll("citation:not([data-item-id])")) {
@@ -46,8 +37,8 @@ export function parseDocumentAiHtml(
 
 	validateDocumentAiHtml(htmlDocument.body);
 
-	for (const element of htmlDocument.body.querySelectorAll("[data-ref]")) {
-		element.removeAttribute("data-ref");
+	for (const element of htmlDocument.body.querySelectorAll("[data-edit-ref]")) {
+		element.removeAttribute("data-edit-ref");
 	}
 
 	try {
@@ -75,10 +66,10 @@ export async function serializeTiptapDocumentToAiHtml(document: TiptapDocumentJs
 }
 
 export async function serializeTiptapNodeToAiHtml(node: ProseMirrorNode) {
-	// The ref is hashed from the full node, so a widget whose source changed
-	// still invalidates it — only the serialized form is elided.
-	const withRef = withTiptapNodeAiRef(node, await createDocumentAiTargetRef(node));
-	return serializeTiptapFragmentToAiHtml(Fragment.from(elideWidgetSource(withRef)));
+	// The editRef is hashed from the full node, so a widget source change still
+	// invalidates it. Only the serialized source is elided.
+	const withEditRef = withTiptapNodeAiRef(node, await createDocumentAiEditRef(node));
+	return serializeTiptapFragmentToAiHtml(Fragment.from(elideWidgetSource(withEditRef)));
 }
 
 /**
@@ -86,8 +77,8 @@ export async function serializeTiptapNodeToAiHtml(node: ProseMirrorNode) {
  *
  * A widget runs to kilobytes of markup and script. Inlining that in every read
  * would crowd out the prose the model actually needs — a handful of widgets
- * would fill a whole chunk. The placeholder keeps the ref and title, which is
- * enough to decide whether to read it in full.
+ * would fill a whole chunk. The placeholder keeps the editRef and title, which
+ * is enough to decide whether to read it in full.
  */
 function elideWidgetSource(node: ProseMirrorNode): ProseMirrorNode {
 	if (node.type.name !== "widget") {
@@ -96,48 +87,53 @@ function elideWidgetSource(node: ProseMirrorNode): ProseMirrorNode {
 	return node.type.create(node.attrs, undefined, node.marks);
 }
 
-export async function createDocumentAiTargetRef(node: ProseMirrorNode) {
-	const ref = readTiptapNodeAiRef(node);
-	if (!ref) {
-		throw new Error(`Top-level document node ${node.type.name} is missing an AI ref.`);
+export async function createDocumentAiEditRef(node: ProseMirrorNode) {
+	const blockId = readTiptapNodeBlockId(node);
+	if (!blockId) {
+		throw new Error(`Top-level document node ${node.type.name} is missing a block ID.`);
 	}
 
 	// Fingerprint the block's JSON rather than its HTML: rendering costs a whole
-	// second DOM pass per block per read, and the ref only has to change whenever
+	// second DOM pass per block per read, and the editRef only has to change when
 	// the block's content does.
 	const content = JSON.stringify(withTiptapNodeAiRef(node, null).toJSON());
 	const revision = (await sha256Base64UrlText(content)).slice(0, 10);
-	return `${ref}.r_${revision}`;
+	return `${blockId}.r_${revision}`;
 }
 
-export function parseDocumentAiTargetRef(ref: string) {
-	return documentAiTargetRefPattern.exec(ref)?.[1] ?? null;
+export function parseDocumentAiEditRef(editRef: string) {
+	return documentAiEditRefPattern.exec(editRef)?.[1] ?? null;
 }
 
-export function ensureTiptapDocumentAiRefs(document: TiptapDocumentJson): {
+export function ensureTiptapDocumentBlockIds(document: TiptapDocumentJson): {
 	changed: boolean;
 	document: TiptapDocumentJson;
 } {
-	const refs = ensureProseMirrorDocumentAiRefs(getTiptapDocumentSchema().nodeFromJSON(document));
-	return refs.changed
-		? { changed: true, document: coerceTiptapDocumentJson(refs.document.toJSON()) }
+	const result = ensureProseMirrorDocumentBlockIds(
+		getTiptapDocumentSchema().nodeFromJSON(document),
+	);
+	return result.changed
+		? { changed: true, document: coerceTiptapDocumentJson(result.document.toJSON()) }
 		: { changed: false, document };
 }
 
-export function ensureProseMirrorDocumentAiRefs(document: ProseMirrorNode): {
+export function ensureProseMirrorDocumentBlockIds(document: ProseMirrorNode): {
 	changed: boolean;
 	document: ProseMirrorNode;
 } {
-	const usedRefs = new Set<string>();
+	const usedBlockIds = new Set<string>();
 	let changed = false;
 	const children: ProseMirrorNode[] = [];
 
 	document.forEach((node) => {
-		const currentRef = readTiptapNodeAiRef(node);
-		const ref = currentRef && !usedRefs.has(currentRef) ? currentRef : createDocumentAiRef();
-		usedRefs.add(ref);
-		changed ||= ref !== currentRef;
-		children.push(withTiptapNodeAiRef(node, ref));
+		const currentBlockId = readTiptapNodeBlockId(node);
+		const blockId =
+			currentBlockId && !usedBlockIds.has(currentBlockId)
+				? currentBlockId
+				: createDocumentBlockId();
+		usedBlockIds.add(blockId);
+		changed ||= blockId !== currentBlockId;
+		children.push(withTiptapNodeAiRef(node, blockId));
 	});
 
 	if (!changed) {
@@ -150,19 +146,19 @@ export function ensureProseMirrorDocumentAiRefs(document: ProseMirrorNode): {
 	};
 }
 
-export function createDocumentAiRef() {
+function createDocumentBlockId() {
 	return `b_${nanoid(12)}`;
 }
 
-export function readTiptapNodeAiRef(node: ProseMirrorNode) {
-	const ref = node.attrs[tiptapDocumentAiRefAttribute];
-	return typeof ref === "string" && documentAiRefPattern.test(ref) ? ref : null;
+export function readTiptapNodeBlockId(node: ProseMirrorNode) {
+	const blockId = node.attrs[tiptapDocumentAiRefAttribute];
+	return typeof blockId === "string" && documentBlockIdPattern.test(blockId) ? blockId : null;
 }
 
 export function withTiptapNodeAiRef(node: ProseMirrorNode, ref: string | null) {
 	const attributes = node.type.spec.attrs;
 	if (!attributes || !(tiptapDocumentAiRefAttribute in attributes)) {
-		throw new Error(`Top-level document node ${node.type.name} cannot carry an AI ref.`);
+		throw new Error(`Top-level document node ${node.type.name} cannot carry a block ID.`);
 	}
 
 	return node.type.create(
@@ -172,9 +168,23 @@ export function withTiptapNodeAiRef(node: ProseMirrorNode, ref: string | null) {
 	);
 }
 
-/** One block as HTML, synchronously and without a ref — for text matching. */
-export function serializeTiptapNodeToPlainAiHtml(node: ProseMirrorNode) {
-	return serializeTiptapFragmentToAiHtml(Fragment.from(node));
+/**
+ * The exact block HTML returned by a block read and matched by `replace_text`.
+ * Its editRef travels beside it, never inside it, so there is only one target
+ * value for the model to copy.
+ */
+export function serializeTiptapNodeToEditableAiHtml(node: ProseMirrorNode) {
+	return serializeTiptapFragmentToAiHtml(Fragment.from(withTiptapNodeAiRef(node, null)));
+}
+
+/** Content and edit target minted together from one live block. */
+export async function createDocumentAiBlockSnapshot(
+	node: ProseMirrorNode,
+): Promise<DocumentAiBlockSnapshot> {
+	return {
+		content: serializeTiptapNodeToEditableAiHtml(node),
+		editRef: await createDocumentAiEditRef(node),
+	};
 }
 
 function serializeTiptapFragmentToAiHtml(fragment: Fragment) {
@@ -188,29 +198,6 @@ function serializeTiptapFragmentToAiHtml(fragment: Fragment) {
 	return container.innerHTML;
 }
 
-/**
- * Fills an elided widget back in from the live document before parsing.
- *
- * The model reads a widget as `<div data-type="widget" data-ref="...">` with no
- * body. Sending that straight back — which `overwrite` does by design — would
- * otherwise replace real source with an empty node.
- */
-function restoreElidedWidgets(
-	htmlDocument: Document,
-	resolveWidgetSource: ((ref: string) => string | null) | undefined,
-) {
-	for (const element of htmlDocument.body.querySelectorAll('div[data-type="widget"]')) {
-		if (element.textContent?.trim()) {
-			continue;
-		}
-		const ref = element.getAttribute("data-ref");
-		const source = ref && resolveWidgetSource ? resolveWidgetSource(ref) : null;
-		if (source) {
-			element.textContent = source;
-		}
-	}
-}
-
 /**
  * Rescues the two tags ProseMirror parses lossily.
  *
diff --git a/src/features/workspaces/documents/document-ai-html.worker.test.ts b/src/features/workspaces/documents/document-ai-html.worker.test.ts
index 323509c87..f1c46a185 100644
--- a/src/features/workspaces/documents/document-ai-html.worker.test.ts
+++ b/src/features/workspaces/documents/document-ai-html.worker.test.ts
@@ -1,19 +1,19 @@
 import { describe, expect, it } from "vitest";
 
 import {
-	ensureTiptapDocumentAiRefs,
+	ensureTiptapDocumentBlockIds,
 	parseDocumentAiHtml,
 	serializeTiptapDocumentToAiHtml,
 } from "#/features/workspaces/documents/document-ai-html";
 
 describe("document AI HTML in Workers", () => {
 	it("parses and serializes with the production runtime DOM adapter", async () => {
-		const document = ensureTiptapDocumentAiRefs(
+		const document = ensureTiptapDocumentBlockIds(
 			parseDocumentAiHtml("<h2>Worker</h2><p>Schema-safe HTML</p>"),
 		).document;
 
 		expect(await serializeTiptapDocumentToAiHtml(document)).toMatch(
-			/^<h2 data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Worker<\/h2><p data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Schema-safe HTML<\/p>$/,
+			/^<h2 data-edit-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Worker<\/h2><p data-edit-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Schema-safe HTML<\/p>$/,
 		);
 	});
 });
diff --git a/src/features/workspaces/documents/document-session.ts b/src/features/workspaces/documents/document-session.ts
index 46f384d6f..8cc614109 100644
--- a/src/features/workspaces/documents/document-session.ts
+++ b/src/features/workspaces/documents/document-session.ts
@@ -17,10 +17,11 @@ import {
 import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
 
 import {
-	ensureProseMirrorDocumentAiRefs,
-	parseDocumentAiTargetRef,
-	readTiptapNodeAiRef,
-	serializeTiptapNodeToPlainAiHtml,
+	createDocumentAiBlockSnapshot,
+	type DocumentAiBlockSnapshot,
+	ensureProseMirrorDocumentBlockIds,
+	parseDocumentAiEditRef,
+	readTiptapNodeBlockId,
 } from "#/features/workspaces/documents/document-ai-html";
 import {
 	type DocumentHtmlChunkReadInput,
@@ -351,29 +352,35 @@ export class DocumentSession extends YServer {
 	}
 
 	/**
-	 * One block in full, addressed by a ref from an earlier read.
+	 * One block in full, addressed by an editRef from an earlier read.
 	 *
 	 * Document reads elide a widget's source to keep prose in the chunk, so this
 	 * is how the assistant fetches it before editing — and it works for any block
 	 * that is easier to read alone than to page to.
 	 */
 	async readBlock(input: {
-		ref: string;
-	}): Promise<{ content: string; status: "ready" } | { status: "ref_not_found" }> {
+		editRef: string;
+	}): Promise<(DocumentAiBlockSnapshot & { status: "ready" }) | { status: "edit_ref_not_found" }> {
 		this.assertActive();
 		const { document } = await this.getReferencedDocumentSnapshot();
-		const stableRef = parseDocumentAiTargetRef(input.ref) ?? input.ref;
+		const blockId = parseDocumentAiEditRef(input.editRef);
+		if (!blockId) {
+			return { status: "edit_ref_not_found" };
+		}
 
 		let found: ProseMirrorNode | null = null;
 		document.forEach((node) => {
-			if (!found && readTiptapNodeAiRef(node) === stableRef) {
+			if (!found && readTiptapNodeBlockId(node) === blockId) {
 				found = node;
 			}
 		});
 
 		return found
-			? { content: serializeTiptapNodeToPlainAiHtml(found), status: "ready" }
-			: { status: "ref_not_found" };
+			? {
+					...(await createDocumentAiBlockSnapshot(found)),
+					status: "ready",
+				}
+			: { status: "edit_ref_not_found" };
 	}
 
 	async purgeForDeletion(): Promise<void> {
@@ -486,7 +493,7 @@ export class DocumentSession extends YServer {
 	}
 
 	private async getReferencedDocumentSnapshot() {
-		const refs = ensureProseMirrorDocumentAiRefs(this.getCurrentProseMirrorDocument());
+		const refs = ensureProseMirrorDocumentBlockIds(this.getCurrentProseMirrorDocument());
 		if (refs.changed) {
 			this.reconcileCurrentDocument(coerceTiptapDocumentJson(refs.document.toJSON()));
 			await this.persistYDoc();
diff --git a/src/features/workspaces/documents/tiptap-schema.ts b/src/features/workspaces/documents/tiptap-schema.ts
index 1e2d406b6..90abf8896 100644
--- a/src/features/workspaces/documents/tiptap-schema.ts
+++ b/src/features/workspaces/documents/tiptap-schema.ts
@@ -89,7 +89,7 @@ export const Widget = Node.create({
 	},
 
 	renderHTML({ HTMLAttributes }) {
-		// Merge rather than replace: global attributes land here, and data-ref is
+		// Merge rather than replace: global attributes land here, and data-edit-ref is
 		// how the assistant addresses this block for reads and edits.
 		return ["div", mergeAttributes(HTMLAttributes, { "data-type": "widget" }), 0];
 	},
@@ -121,7 +121,7 @@ const DocumentAiRef = Extension.create({
 						parseHTML: () => null,
 						renderHTML: (attributes: Record<string, unknown>) => {
 							const ref = attributes[tiptapDocumentAiRefAttribute];
-							return typeof ref === "string" && ref ? { "data-ref": ref } : {};
+							return typeof ref === "string" && ref ? { "data-edit-ref": ref } : {};
 						},
 					},
 				},
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index d890dd004..7ecefc1b0 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -201,14 +201,20 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
   "additionalProperties": false,
   "properties": {
     "edits": {
-      "description": "Ordered edits, at most 40. Target a block by copying its data-ref into the "ref" field (these are local to the document, not workspace citation refs). Use replace_text to change text inside one block, including a widget's source. Use overwrite only to discard the entire document and write a new one.",
+      "description": "Ordered edits, at most 40. Target a block with the exact editRef from a document or block read. A block read returns the exact content that replace_text matches. Use overwrite only to discard the entire document and write a new one.",
       "items": {
         "anyOf": [
           {
             "additionalProperties": false,
             "properties": {
+              "editRef": {
+                "description": "Exact editRef from a recent document or block read.",
+                "maxLength": 64,
+                "minLength": 1,
+                "type": "string",
+              },
               "html": {
-                "description": "Schema-constrained HTML fragment. Model-supplied data-ref attributes are ignored.",
+                "description": "Schema-constrained HTML fragment. Model-supplied data-edit-ref attributes are ignored.",
                 "maxLength": 512000,
                 "type": "string",
               },
@@ -220,37 +226,31 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                 ],
                 "type": "string",
               },
-              "ref": {
-                "description": "Exact data-ref from a recent HTML read. Put it in the "ref" field, never "target".",
-                "maxLength": 64,
-                "minLength": 1,
-                "type": "string",
-              },
             },
             "required": [
+              "editRef",
               "html",
               "op",
-              "ref",
             ],
             "type": "object",
           },
           {
             "additionalProperties": false,
             "properties": {
-              "op": {
-                "const": "delete",
-                "type": "string",
-              },
-              "ref": {
-                "description": "Exact data-ref from a recent HTML read. Put it in the "ref" field, never "target".",
+              "editRef": {
+                "description": "Exact editRef from a recent document or block read.",
                 "maxLength": 64,
                 "minLength": 1,
                 "type": "string",
               },
+              "op": {
+                "const": "delete",
+                "type": "string",
+              },
             },
             "required": [
+              "editRef",
               "op",
-              "ref",
             ],
             "type": "object",
           },
@@ -258,7 +258,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
             "additionalProperties": false,
             "properties": {
               "html": {
-                "description": "Schema-constrained HTML fragment. Model-supplied data-ref attributes are ignored.",
+                "description": "Schema-constrained HTML fragment. Model-supplied data-edit-ref attributes are ignored.",
                 "maxLength": 512000,
                 "type": "string",
               },
@@ -276,6 +276,12 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
           {
             "additionalProperties": false,
             "properties": {
+              "editRef": {
+                "description": "Exact editRef from a recent document or block read.",
+                "maxLength": 64,
+                "minLength": 1,
+                "type": "string",
+              },
               "find": {
                 "description": "Exact text to replace inside the target block, copied from a read. It must appear exactly once in that block; if it matches more than once the edit fails instead of replacing every occurrence.",
                 "maxLength": 512000,
@@ -286,12 +292,6 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                 "const": "replace_text",
                 "type": "string",
               },
-              "ref": {
-                "description": "Exact data-ref from a recent HTML read. Put it in the "ref" field, never "target".",
-                "maxLength": 64,
-                "minLength": 1,
-                "type": "string",
-              },
               "replace": {
                 "description": "Replacement text. May be empty to delete the matched text.",
                 "maxLength": 512000,
@@ -299,9 +299,9 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
               },
             },
             "required": [
+              "editRef",
               "find",
               "op",
-              "ref",
               "replace",
             ],
             "type": "object",
@@ -516,6 +516,11 @@ exports[`workspace tool surface > workspace_read_items input schema is stable 1`
           {
             "additionalProperties": false,
             "properties": {
+              "editRef": {
+                "description": "editRef of one block from an earlier document read. The result returns the block in full with its current editRef.",
+                "minLength": 1,
+                "type": "string",
+              },
               "mode": {
                 "const": "block",
                 "type": "string",
@@ -525,16 +530,11 @@ exports[`workspace tool surface > workspace_read_items input schema is stable 1`
                 "minLength": 1,
                 "type": "string",
               },
-              "ref": {
-                "description": "data-ref of one block from an earlier read of this document, returned in full. Reads elide a widget's source, so this is how to fetch it before editing.",
-                "minLength": 1,
-                "type": "string",
-              },
             },
             "required": [
               "path",
+              "editRef",
               "mode",
-              "ref",
             ],
             "type": "object",
           },
diff --git a/src/features/workspaces/operations/workspace-tool-definitions.ts b/src/features/workspaces/operations/workspace-tool-definitions.ts
index fcf96ecf9..bfdbf3e4f 100644
--- a/src/features/workspaces/operations/workspace-tool-definitions.ts
+++ b/src/features/workspaces/operations/workspace-tool-definitions.ts
@@ -149,7 +149,7 @@ export const workspaceToolDefinitions = [
 		name: "workspace_read_items",
 		access: "read",
 		description:
-			"Read ThinkEx documents and extracted files by absolute path. Documents return bounded HTML block chunks; each top-level data-ref is an item-local edit target, not a citation ref. Widgets come back as an empty placeholder, so read one back with mode block before editing its source. Files support explicit physical-page selections. Continue either kind with nextCursor. Uploaded files may still be extracting; each result carries any needed handling guidance.",
+			"Read ThinkEx documents and extracted files by absolute path. Document chunks give each top-level block an editRef. Widgets come back as an empty placeholder, so read one with mode block to get its full content and current editRef before editing it. Files support explicit physical-page selections. Continue either kind with nextCursor. Uploaded files may still be extracting; each result carries any needed handling guidance.",
 		inputSchema: workspaceReadItemsInputSchema,
 		inputExamples: workspaceReadItemsInputExamples,
 		outputSchema: workspaceReadItemsOutputSchema,
@@ -244,7 +244,7 @@ export const workspaceToolDefinitions = [
 	defineWorkspaceTool({
 		name: "workspace_edit_item",
 		access: "write",
-		description: `Edit one actual ThinkEx workspace document by absolute path. Read it first, then target blocks by data-ref. Only overwrite replaces the whole document, and only it works without a read. Use workspace_link_items to add relationships. ${workspaceDocumentHtmlInstruction}`,
+		description: `Edit one actual ThinkEx workspace document by absolute path. Read it first, then target blocks with their exact editRef. A block read returns the exact content that replace_text matches. Only overwrite replaces the whole document, and only it works without a read. Use workspace_link_items to add relationships. ${workspaceDocumentHtmlInstruction}`,
 		inputSchema: workspaceEditItemInputSchema,
 		inputExamples: workspaceEditItemInputExamples,
 		outputSchema: workspaceEditItemOutputSchema,
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index 0a5cfb98e..eb1e35b50 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -142,7 +142,7 @@ export const workspaceEditItemInputSchema = z.object({
 		.min(1)
 		.max(40)
 		.describe(
-			'Ordered edits, at most 40. Target a block by copying its data-ref into the "ref" field (these are local to the document, not workspace citation refs). Use replace_text to change text inside one block, including a widget\'s source. Use overwrite only to discard the entire document and write a new one.',
+			"Ordered edits, at most 40. Target a block with the exact editRef from a document or block read. A block read returns the exact content that replace_text matches. Use overwrite only to discard the entire document and write a new one.",
 		),
 });
 
@@ -244,6 +244,15 @@ export const workspaceReadItemsInputExamples = createInputExamples<
 			},
 		],
 	},
+	{
+		requests: [
+			{
+				editRef: "b_JQrkL4Neurv2.r_6sNqkQxDdy",
+				mode: "block",
+				path: "/Demo Folder/Demo Document",
+			},
+		],
+	},
 );
 
 export const workspaceSearchInputExamples = createInputExamples<
@@ -310,8 +319,8 @@ export const workspaceEditItemInputExamples = createInputExamples<
 		path: "/Demo Folder/Demo Document",
 		edits: [
 			{
+				editRef: "b_JQrkL4Neurv2.r_6sNqkQxDdy",
 				op: "replace",
-				ref: "b_JQrkL4Neurv2.r_6sNqkQxDdy",
 				html: "<p>Updated paragraph.</p>",
 			},
 		],
@@ -329,8 +338,8 @@ export const workspaceEditItemInputExamples = createInputExamples<
 		path: "/Demo Folder/Demo Document",
 		edits: [
 			{
+				editRef: "b_JQrkL4Neurv2.r_6sNqkQxDdy",
 				op: "replace_text",
-				ref: "b_JQrkL4Neurv2.r_6sNqkQxDdy",
 				find: "gravity = 9.8",
 				replace: "gravity = 3.7",
 			},

From cc47229692890e887f6dfdf2bf2f42f66e99327d Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 10:46:57 -0400
Subject: [PATCH 15/32] refactor(widgets): separate extension from React view

Keep the Tiptap extension in a non-component module so the React node view remains compatible
with state-preserving Fast Refresh.
---
 .../documents/document-widget-extension.ts    | 20 ++++++++++++++++
 .../documents/document-widget-node.tsx        | 23 ++++---------------
 .../workspaces/documents/tiptap-extensions.ts |  2 +-
 3 files changed, 26 insertions(+), 19 deletions(-)
 create mode 100644 src/features/workspaces/documents/document-widget-extension.ts

diff --git a/src/features/workspaces/documents/document-widget-extension.ts b/src/features/workspaces/documents/document-widget-extension.ts
new file mode 100644
index 000000000..f31ed7f9f
--- /dev/null
+++ b/src/features/workspaces/documents/document-widget-extension.ts
@@ -0,0 +1,20 @@
+import { ReactNodeViewRenderer } from "@tiptap/react";
+
+import {
+	DocumentWidgetView,
+	type DocumentWidgetViewOptions,
+} from "#/features/workspaces/documents/document-widget-node";
+import { Widget } from "#/features/workspaces/documents/tiptap-schema";
+
+/** Adds the sandboxed React view to the shared widget schema node. */
+export const DocumentWidget = Widget.extend<DocumentWidgetViewOptions>({
+	addOptions() {
+		return { onAskAiToFix: null };
+	},
+
+	addNodeView() {
+		return ReactNodeViewRenderer(DocumentWidgetView, {
+			ignoreMutation: ({ mutation }) => mutation.type !== "selection",
+		});
+	},
+});
diff --git a/src/features/workspaces/documents/document-widget-node.tsx b/src/features/workspaces/documents/document-widget-node.tsx
index 445ee2342..bede067d6 100644
--- a/src/features/workspaces/documents/document-widget-node.tsx
+++ b/src/features/workspaces/documents/document-widget-node.tsx
@@ -1,5 +1,5 @@
 import type { NodeViewProps } from "@tiptap/react";
-import { NodeViewContent, NodeViewWrapper, ReactNodeViewRenderer } from "@tiptap/react";
+import { NodeViewContent, NodeViewWrapper } from "@tiptap/react";
 import { Shapes } from "lucide-react";
 
 import {
@@ -8,9 +8,8 @@ import {
 	CodeBlockTitle,
 } from "#/components/code-block/code-block-chrome";
 import { WorkspaceWidgetSandbox } from "#/features/workspaces/components/widget/WorkspaceWidgetSandbox";
-import { Widget } from "#/features/workspaces/documents/tiptap-schema";
 
-export interface DocumentWidgetOptions {
+export interface DocumentWidgetViewOptions {
 	/**
 	 * Called with a crashed widget's error text so the surface can offer a way
 	 * out. Left unset the affordance is hidden, which is right for any read-only
@@ -20,7 +19,7 @@ export interface DocumentWidgetOptions {
 }
 
 /**
- * The editor's widget: the authored HTML running in its sandboxed frame.
+ * The editor view for authored widget HTML running in its sandboxed frame.
  *
  * The frame is a separate document, so its own events never reach the editor and
  * there is nothing to suppress. What does reach the editor is a click or drag on
@@ -32,22 +31,10 @@ export interface DocumentWidgetOptions {
  * and `ignoreMutation` stops the editor re-parsing when React re-renders the
  * header — selection mutations pass through so clicking away behaves normally.
  */
-export const DocumentWidget = Widget.extend<DocumentWidgetOptions>({
-	addOptions() {
-		return { onAskAiToFix: null };
-	},
-
-	addNodeView() {
-		return ReactNodeViewRenderer(DocumentWidgetView, {
-			ignoreMutation: ({ mutation }) => mutation.type !== "selection",
-		});
-	},
-});
-
-function DocumentWidgetView({ extension, node, selected }: NodeViewProps) {
+export function DocumentWidgetView({ extension, node, selected }: NodeViewProps) {
 	const html = node.textContent;
 	const title = typeof node.attrs.title === "string" ? node.attrs.title : "";
-	const { onAskAiToFix } = extension.options as DocumentWidgetOptions;
+	const { onAskAiToFix } = extension.options as DocumentWidgetViewOptions;
 	const label = title || "Widget";
 	const askAiToFix = onAskAiToFix
 		? (error: string) => onAskAiToFix(title ? `the "${title}" widget: ${error}` : error)
diff --git a/src/features/workspaces/documents/tiptap-extensions.ts b/src/features/workspaces/documents/tiptap-extensions.ts
index 81a13818d..b7510e7a3 100644
--- a/src/features/workspaces/documents/tiptap-extensions.ts
+++ b/src/features/workspaces/documents/tiptap-extensions.ts
@@ -5,7 +5,7 @@ import "katex/dist/katex.min.css";
 import "katex/contrib/mhchem";
 
 import { CodeBlockShiki } from "#/features/workspaces/documents/code-block-shiki";
-import { DocumentWidget } from "#/features/workspaces/documents/document-widget-node";
+import { DocumentWidget } from "#/features/workspaces/documents/document-widget-extension";
 import { DocumentCitation } from "#/features/workspaces/documents/document-citation-node";
 import {
 	getTiptapDocumentSchemaExtensions,

From 3cd907ca9c685d3f65561874d6639bb0fb24f191 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 10:47:06 -0400
Subject: [PATCH 16/32] build(test): declare jsdom dependency

Make the DOM environment used by widget and existing component tests an explicit dependency.
---
 package.json   |  1 +
 pnpm-lock.yaml | 74 +++++++++++++-------------------------------------
 2 files changed, 20 insertions(+), 55 deletions(-)

diff --git a/package.json b/package.json
index 9fbd0554d..d1d7cd645 100644
--- a/package.json
+++ b/package.json
@@ -173,6 +173,7 @@
 		"@voidzero-dev/vite-plus-core": "^0.2.7",
 		"atmn": "^1.1.16",
 		"babel-plugin-react-compiler": "^1.0.0",
+		"jsdom": "^28.1.0",
 		"knip": "^6.31.0",
 		"react-doctor": "0.6.0",
 		"tailwindcss": "^4.3.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index da5549a0b..a774b72c4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -414,6 +414,9 @@ importers:
       babel-plugin-react-compiler:
         specifier: ^1.0.0
         version: 1.0.0
+      jsdom:
+        specifier: ^28.1.0
+        version: 28.1.0(@noble/hashes@2.2.0)
       knip:
         specifier: ^6.31.0
         version: 6.31.0
@@ -9664,8 +9667,7 @@ packages:
 
 snapshots:
 
-  '@acemir/cssom@0.9.31':
-    optional: true
+  '@acemir/cssom@0.9.31': {}
 
   '@ag-ui/core@0.0.52':
     dependencies:
@@ -9776,7 +9778,6 @@ snapshots:
       '@csstools/css-color-parser': 4.1.10(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)
       '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
       '@csstools/css-tokenizer': 4.0.0
-    optional: true
 
   '@asamuzakjp/dom-selector@6.8.1':
     dependencies:
@@ -9785,13 +9786,10 @@ snapshots:
       css-tree: 3.2.1
       is-potential-custom-element-name: 1.0.1
       lru-cache: 11.5.2
-    optional: true
 
-  '@asamuzakjp/generational-cache@1.0.1':
-    optional: true
+  '@asamuzakjp/generational-cache@1.0.1': {}
 
-  '@asamuzakjp/nwsapi@2.3.9':
-    optional: true
+  '@asamuzakjp/nwsapi@2.3.9': {}
 
   '@babel/code-frame@7.27.1':
     dependencies:
@@ -10188,7 +10186,6 @@ snapshots:
   '@bramus/specificity@2.4.2':
     dependencies:
       css-tree: 3.2.1
-    optional: true
 
   '@cfworker/json-schema@4.1.1': {}
 
@@ -10474,14 +10471,12 @@ snapshots:
     dependencies:
       '@jridgewell/trace-mapping': 0.3.9
 
-  '@csstools/color-helpers@6.1.0':
-    optional: true
+  '@csstools/color-helpers@6.1.0': {}
 
   '@csstools/css-calc@3.3.0(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)':
     dependencies:
       '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
       '@csstools/css-tokenizer': 4.0.0
-    optional: true
 
   '@csstools/css-color-parser@4.1.10(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)':
     dependencies:
@@ -10489,20 +10484,16 @@ snapshots:
       '@csstools/css-calc': 3.3.0(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)
       '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
       '@csstools/css-tokenizer': 4.0.0
-    optional: true
 
   '@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0)':
     dependencies:
       '@csstools/css-tokenizer': 4.0.0
-    optional: true
 
   '@csstools/css-syntax-patches-for-csstree@1.1.7(css-tree@3.2.1)':
     optionalDependencies:
       css-tree: 3.2.1
-    optional: true
 
-  '@csstools/css-tokenizer@4.0.0':
-    optional: true
+  '@csstools/css-tokenizer@4.0.0': {}
 
   '@date-fns/tz@1.5.0':
     optional: true
@@ -11013,7 +11004,6 @@ snapshots:
   '@exodus/bytes@1.15.1(@noble/hashes@2.2.0)':
     optionalDependencies:
       '@noble/hashes': 2.2.0
-    optional: true
 
   '@floating-ui/core@1.8.0':
     dependencies:
@@ -13709,8 +13699,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  agent-base@7.1.4:
-    optional: true
+  agent-base@7.1.4: {}
 
   agent-install@0.0.5:
     dependencies:
@@ -13979,7 +13968,6 @@ snapshots:
   bidi-js@1.0.3:
     dependencies:
       require-from-string: 2.0.2
-    optional: true
 
   bl@4.1.0:
     dependencies:
@@ -14342,7 +14330,6 @@ snapshots:
     dependencies:
       mdn-data: 2.27.1
       source-map-js: 1.2.1
-    optional: true
 
   css-what@8.0.0: {}
 
@@ -14356,7 +14343,6 @@ snapshots:
       '@csstools/css-syntax-patches-for-csstree': 1.1.7(css-tree@3.2.1)
       css-tree: 3.2.1
       lru-cache: 11.5.2
-    optional: true
 
   csstype@3.2.3: {}
 
@@ -14550,7 +14536,6 @@ snapshots:
       whatwg-url: 16.0.1(@noble/hashes@2.2.0)
     transitivePeerDependencies:
       - '@noble/hashes'
-    optional: true
 
   date-fns@4.3.0:
     optional: true
@@ -14569,8 +14554,7 @@ snapshots:
     dependencies:
       ms: 2.1.3
 
-  decimal.js@10.6.0:
-    optional: true
+  decimal.js@10.6.0: {}
 
   decode-named-character-reference@1.3.0:
     dependencies:
@@ -15462,7 +15446,6 @@ snapshots:
       '@exodus/bytes': 1.15.1(@noble/hashes@2.2.0)
     transitivePeerDependencies:
       - '@noble/hashes'
-    optional: true
 
   html-escaper@3.0.3: {}
 
@@ -15491,7 +15474,6 @@ snapshots:
       debug: 4.4.3
     transitivePeerDependencies:
       - supports-color
-    optional: true
 
   https-proxy-agent@5.0.1:
     dependencies:
@@ -15506,7 +15488,6 @@ snapshots:
       debug: 4.4.3
     transitivePeerDependencies:
       - supports-color
-    optional: true
 
   human-signals@2.1.0: {}
 
@@ -15746,8 +15727,7 @@ snapshots:
 
   is-plain-obj@4.1.0: {}
 
-  is-potential-custom-element-name@1.0.1:
-    optional: true
+  is-potential-custom-element-name@1.0.1: {}
 
   is-promise@4.0.0: {}
 
@@ -15856,7 +15836,6 @@ snapshots:
     transitivePeerDependencies:
       - '@noble/hashes'
       - supports-color
-    optional: true
 
   jsesc@3.1.0: {}
 
@@ -16103,8 +16082,7 @@ snapshots:
     dependencies:
       js-tokens: 4.0.0
 
-  lru-cache@11.5.2:
-    optional: true
+  lru-cache@11.5.2: {}
 
   lru-cache@5.1.1:
     dependencies:
@@ -16327,8 +16305,7 @@ snapshots:
     dependencies:
       '@types/mdast': 4.0.4
 
-  mdn-data@2.27.1:
-    optional: true
+  mdn-data@2.27.1: {}
 
   media-typer@1.1.1: {}
 
@@ -17124,7 +17101,6 @@ snapshots:
   parse5@8.0.1:
     dependencies:
       entities: 8.0.0
-    optional: true
 
   parseurl@1.3.3: {}
 
@@ -17801,7 +17777,6 @@ snapshots:
   saxes@6.0.0:
     dependencies:
       xmlchars: 2.2.0
-    optional: true
 
   scheduler@0.27.0: {}
 
@@ -18222,8 +18197,7 @@ snapshots:
       react: 19.2.8
       use-sync-external-store: 1.6.0(react@19.2.8)
 
-  symbol-tree@3.2.4:
-    optional: true
+  symbol-tree@3.2.4: {}
 
   system-architecture@0.1.0: {}
 
@@ -18273,13 +18247,11 @@ snapshots:
 
   tinyrainbow@3.1.1: {}
 
-  tldts-core@7.4.10:
-    optional: true
+  tldts-core@7.4.10: {}
 
   tldts@7.4.10:
     dependencies:
       tldts-core: 7.4.10
-    optional: true
 
   to-buffer@1.2.2:
     dependencies:
@@ -18306,12 +18278,10 @@ snapshots:
   tough-cookie@6.0.2:
     dependencies:
       tldts: 7.4.10
-    optional: true
 
   tr46@6.0.0:
     dependencies:
       punycode: 2.3.1
-    optional: true
 
   trim-lines@3.0.1: {}
 
@@ -18629,7 +18599,6 @@ snapshots:
   w3c-xmlserializer@5.0.0:
     dependencies:
       xml-name-validator: 5.0.0
-    optional: true
 
   walk-up-path@4.0.0: {}
 
@@ -18637,13 +18606,11 @@ snapshots:
 
   web-vitals@5.3.0: {}
 
-  webidl-conversions@8.0.1:
-    optional: true
+  webidl-conversions@8.0.1: {}
 
   webpack-virtual-modules@0.6.2: {}
 
-  whatwg-mimetype@5.0.0:
-    optional: true
+  whatwg-mimetype@5.0.0: {}
 
   whatwg-url@16.0.1(@noble/hashes@2.2.0):
     dependencies:
@@ -18652,7 +18619,6 @@ snapshots:
       webidl-conversions: 8.0.1
     transitivePeerDependencies:
       - '@noble/hashes'
-    optional: true
 
   when-exit@2.1.5: {}
 
@@ -18781,8 +18747,7 @@ snapshots:
       is-wsl: 3.1.1
       powershell-utils: 0.1.0
 
-  xml-name-validator@5.0.0:
-    optional: true
+  xml-name-validator@5.0.0: {}
 
   xml-naming@0.3.0: {}
 
@@ -18793,8 +18758,7 @@ snapshots:
       '@oozcitak/util': 10.0.0
       js-yaml: 4.3.1
 
-  xmlchars@2.2.0:
-    optional: true
+  xmlchars@2.2.0: {}
 
   xtend@4.0.2:
     optional: true

From bc7136b6a25cedf0e581e31ee76d6d7e7e92cef0 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 10:52:10 -0400
Subject: [PATCH 17/32] fix(ai): avoid unnecessary widget generation

Default to prose and tables, reserve Mermaid for requested visual explanations, and create
widgets only for explicit, interactive, or document-specific visual requests.
---
 src/features/workspaces/ai/ai-thread-soul-prompt.ts         | 2 +-
 src/features/workspaces/ai/skills/widget-authoring/SKILL.md | 6 +++---
 .../__snapshots__/workspace-tool-surface.test.ts.snap       | 2 +-
 .../workspaces/operations/workspace-tool-schemas.ts         | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/features/workspaces/ai/ai-thread-soul-prompt.ts b/src/features/workspaces/ai/ai-thread-soul-prompt.ts
index af0c9eadd..1235f5909 100644
--- a/src/features/workspaces/ai/ai-thread-soul-prompt.ts
+++ b/src/features/workspaces/ai/ai-thread-soul-prompt.ts
@@ -46,7 +46,7 @@ export function getAIThreadSoulPrompt() {
 			title: "Output Format",
 			rules: [
 				"Format final answers as GitHub-flavored Markdown. Use concise headings, lists, blockquotes, links, tables, task lists, strikethrough, and fenced code blocks with language tags when they improve clarity.",
-				"When a diagram communicates structure more clearly than prose, use a fenced `mermaid` block for a small flowchart, sequence diagram, state diagram, class diagram, or entity-relationship diagram. Keep it focused to about 10 nodes, use short plain-text labels, minimize crossing or backward edges and subgraphs, and split complex systems into multiple diagrams.",
+				"When the user asks for a diagram or visual explanation, use a fenced `mermaid` block for a small flowchart, sequence diagram, state diagram, class diagram, or entity-relationship diagram. Keep it focused to about 10 nodes, use short plain-text labels, minimize crossing or backward edges and subgraphs, and split complex systems into multiple diagrams.",
 				"Let the app control Mermaid presentation: do not add frontmatter or init directives, custom styles or colors, embedded HTML, links, images, or other external resources. Include a concise `accTitle` and `accDescr` describing the diagram.",
 				"When writing Markdown with math, use `$...$` for inline math and `$$...$$` on separate lines for block math. Do not use `\\(...\\)` or `\\[...\\]`; our renderer only understands dollar-sign delimiters.",
 				"Chemistry renders with `\\ce{...}` (e.g. `$\\ce{CH4 + 2 O2 -> CO2 + 2 H2O}$`) and quantities with units render with `\\pu{...}`.",
diff --git a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
index 9980eda55..f92449f1a 100644
--- a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
+++ b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: widget-authoring
-description: Author and edit widgets — interactive document blocks whose self-contained HTML runs sandboxed in ThinkEx. Use whenever the user asks for something interactive to be built or changed — a simulation, calculator, diagram, quiz game, flashcard drill, timer, chart, or any small interactive tool or visualization.
+description: Author and edit widgets — interactive document blocks whose self-contained HTML runs sandboxed in ThinkEx. Use when the user explicitly asks for a widget, for interaction or live computation, or for a visual artifact inside a document that ordinary blocks cannot express.
 ---
 
 # Authoring ThinkEx widgets
@@ -11,9 +11,9 @@ Create one by writing a `<div data-type="widget" title="...">` into a document 
 
 ## When to reach for a widget block
 
-Use a **widget block** when the value is in _interaction or live computation_: a physics simulation, a calculator, an adjustable diagram, a quiz game with scoring, a drawing tool, a data visualization the user can tweak, a timer. Only a widget can run JavaScript.
+Use a **widget block** when the user explicitly asks for one, or when the value is in _interaction or live computation_: a physics simulation, a calculator, an adjustable diagram, a quiz game with scoring, a drawing tool, a data visualization the user can tweak, a timer. Also use one when the user asks to place a visual artifact inside a document and ordinary document blocks cannot express it. Only a widget can run JavaScript.
 
-Use **ordinary blocks** when the value is in _rich text_: notes, explanations, structured study material, tables of static content. Most documents want both — prose that explains, and one widget that lets the reader try it.
+Do not add a widget merely to decorate an explanation. Use **ordinary blocks** for notes, explanations, structured study material, and tables of static content. In chat, default to prose or a table and use Mermaid only when the user asks for a diagram or visual explanation.
 
 ## The HTML contract (read this before writing any widget)
 
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index 7ecefc1b0..a7455a29e 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -29,7 +29,7 @@ exports[`workspace tool surface > system prompt is stable 1`] = `
 
 # Output Format
 - Format final answers as GitHub-flavored Markdown. Use concise headings, lists, blockquotes, links, tables, task lists, strikethrough, and fenced code blocks with language tags when they improve clarity.
-- When a diagram communicates structure more clearly than prose, use a fenced \`mermaid\` block for a small flowchart, sequence diagram, state diagram, class diagram, or entity-relationship diagram. Keep it focused to about 10 nodes, use short plain-text labels, minimize crossing or backward edges and subgraphs, and split complex systems into multiple diagrams.
+- When the user asks for a diagram or visual explanation, use a fenced \`mermaid\` block for a small flowchart, sequence diagram, state diagram, class diagram, or entity-relationship diagram. Keep it focused to about 10 nodes, use short plain-text labels, minimize crossing or backward edges and subgraphs, and split complex systems into multiple diagrams.
 - Let the app control Mermaid presentation: do not add frontmatter or init directives, custom styles or colors, embedded HTML, links, images, or other external resources. Include a concise \`accTitle\` and \`accDescr\` describing the diagram.
 - When writing Markdown with math, use \`$...$\` for inline math and \`$$...$$\` on separate lines for block math. Do not use \`\\(...\\)\` or \`\\[...\\]\`; our renderer only understands dollar-sign delimiters.
 - Chemistry renders with \`\\ce{...}\` (e.g. \`$\\ce{CH4 + 2 O2 -> CO2 + 2 H2O}$\`) and quantities with units render with \`\\pu{...}\`.
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index eb1e35b50..0b33edddc 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -51,7 +51,7 @@ export const workspaceHtmlMathInstruction =
  * Carried by the document instruction because a widget is a document block: the
  * model reaches for one from inside the same write it would write prose in.
  */
-const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document, written as <div data-type="widget" title="Short title">…escaped HTML source…</div>. Reach for one when the user asks for something interactive — a simulation, calculator, diagram, or visualization — and keep the surrounding prose in normal blocks. Activate the "widget-authoring" skill before writing widget source; it has the full contract, a starter template, and canvas/layout rules. Hard constraints: the source is a self-contained fragment run in a sandboxed iframe, so provide only inner content (HTML plus inline <style> and <script>), never <!doctype>, <html>, <head>, or <body>; all JavaScript must be inline, with no external scripts, imports, or network access; style with the injected app CSS variables (--background, --foreground, --primary, --border, --radius, etc.) instead of hard-coded colors.`;
+const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document, written as <div data-type="widget" title="Short title">…escaped HTML source…</div>. Use one only when the user explicitly asks for a widget, asks for interaction or live computation, or wants a visual artifact inside the document that ordinary blocks cannot express. Do not add a widget merely to decorate an explanation; keep normal content in normal blocks. Activate the "widget-authoring" skill before writing widget source; it has the full contract, a starter template, and canvas/layout rules. Hard constraints: the source is a self-contained fragment run in a sandboxed iframe, so provide only inner content (HTML plus inline <style> and <script>), never <!doctype>, <html>, <head>, or <body>; all JavaScript must be inline, with no external scripts, imports, or network access; style with the injected app CSS variables (--background, --foreground, --primary, --border, --radius, etc.) instead of hard-coded colors.`;
 
 export const workspaceDocumentHtmlInstruction = `Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. ${workspaceHtmlMathInstruction} For checkboxes, use <ul data-type="taskList"><li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>Item</p></div></li></ul>. Documents cannot hold images: never use <img> or <figure>, and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with <citation ref="wr_7Kp2Qa9x"></citation> placed after the claim it supports. ${workspaceWidgetHtmlInstruction}`;
 

From f6c67e4cd64e61034bdac374728577146730b69f Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 12:24:59 -0400
Subject: [PATCH 18/32] fix(widgets): preserve sandbox state and narrow
 resources

---
 .../ai/skills/widget-authoring/SKILL.md       |   2 +-
 .../widget/WorkspaceWidgetSandbox.test.tsx    | 105 +++++++++++++++++-
 .../widget/WorkspaceWidgetSandbox.tsx         |  76 ++++++++++---
 .../workspace-widget-sandbox-document.test.ts |  24 +++-
 .../workspace-widget-sandbox-document.ts      |  40 ++++---
 .../operations/workspace-tool-schemas.ts      |   2 +-
 6 files changed, 208 insertions(+), 41 deletions(-)

diff --git a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
index f92449f1a..8cb80685f 100644
--- a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
+++ b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
@@ -18,7 +18,7 @@ Do not add a widget merely to decorate an explanation. Use **ordinary blocks** f
 ## The HTML contract (read this before writing any widget)
 
 1. **Fragment only.** Provide the inner content only — HTML, one or more inline `<style>` blocks, and inline `<script>`. Do **NOT** include `<!doctype>`, `<html>`, `<head>`, or `<body>`. The sandbox wraps your fragment in a full document.
-2. **All JS is inline.** No external scripts, no `import`, no `fetch`, no network, no CDN links. `connect-src` is blocked and external scripts will not load. Write vanilla JS (or hand-rolled helpers) inline in a `<script>` tag.
+2. **All JS is inline.** Do not use external scripts, `import`, `fetch`, navigation, or CDN links. Connection APIs and external subresources are blocked; the frame itself remains isolated from the ThinkEx app. Write vanilla JS (or hand-rolled helpers) inline in a `<script>` tag.
 3. **Theme with the app's CSS variables.** The host injects these variables so the widget looks native in light and dark mode. Use them instead of hard-coded colors:
    `--background`, `--foreground`, `--card`, `--card-foreground`, `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--border`, `--input`, `--ring`, `--radius`, `--font-sans`, `--font-mono`.
    The sandbox sets `data-theme="light|dark"` and toggles a `.dark` class on the root element; because you use the variables, you rarely need to special-case either one.
diff --git a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx
index 340990ee2..59f984c1d 100644
--- a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx
+++ b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx
@@ -43,10 +43,13 @@ describe("WorkspaceWidgetSandbox", () => {
 	});
 
 	it("updates the live frame theme without rebuilding authored HTML", async () => {
-		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>one</p>" />));
+		await act(async () =>
+			root.render(<WorkspaceWidgetSandbox html="<p>one</p>" label="Counter" />),
+		);
 
 		const iframe = container.querySelector("iframe");
 		expect(iframe).not.toBeNull();
+		expect(iframe?.title).toBe("Counter widget");
 		if (!iframe?.contentWindow) throw new Error("Expected the sandbox iframe window");
 
 		const initialDocument = iframe.getAttribute("srcdoc");
@@ -69,7 +72,9 @@ describe("WorkspaceWidgetSandbox", () => {
 
 		themeState.resolvedTheme = "dark";
 		document.documentElement.style.setProperty("--background", "black");
-		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>one</p>" />));
+		await act(async () =>
+			root.render(<WorkspaceWidgetSandbox html="<p>one</p>" label="Counter" />),
+		);
 
 		expect(container.querySelector("iframe")).toBe(iframe);
 		expect(iframe.getAttribute("srcdoc")).toBe(initialDocument);
@@ -84,12 +89,55 @@ describe("WorkspaceWidgetSandbox", () => {
 			"*",
 		);
 
-		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>two</p>" />));
+		await act(async () =>
+			root.render(<WorkspaceWidgetSandbox html="<p>two</p>" label="Counter" />),
+		);
 		expect(iframe.getAttribute("srcdoc")).not.toBe(initialDocument);
 		expect(iframe.getAttribute("srcdoc")).toContain("<p>two</p>");
 		expect(iframe.getAttribute("srcdoc")).toContain("var SESSION=2");
 	});
 
+	it("resets height for new HTML and ignores messages from the old frame", async () => {
+		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>tall</p>" />));
+
+		const iframe = container.querySelector("iframe");
+		if (!iframe?.contentWindow) throw new Error("Expected the sandbox iframe window");
+		const frame = iframe.parentElement;
+
+		await act(async () => {
+			window.dispatchEvent(
+				new MessageEvent("message", {
+					data: {
+						source: WIDGET_SANDBOX_FRAME_SOURCE,
+						kind: "height",
+						height: 900,
+						sessionId: 1,
+					},
+					source: iframe.contentWindow,
+				}),
+			);
+		});
+		expect(frame?.style.height).toBe("720px");
+
+		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>short</p>" />));
+		expect(frame?.style.height).toBe("120px");
+
+		await act(async () => {
+			window.dispatchEvent(
+				new MessageEvent("message", {
+					data: {
+						source: WIDGET_SANDBOX_FRAME_SOURCE,
+						kind: "height",
+						height: 500,
+						sessionId: 1,
+					},
+					source: iframe.contentWindow,
+				}),
+			);
+		});
+		expect(frame?.style.height).toBe("120px");
+	});
+
 	it("lets the error view size itself instead of keeping the widget height", async () => {
 		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>broken</p>" />));
 
@@ -113,5 +161,56 @@ describe("WorkspaceWidgetSandbox", () => {
 
 		expect(frame?.style.height).toBe("");
 		expect(frame?.querySelector('[role="alert"]')).not.toBeNull();
+		expect(frame?.querySelector("iframe")).toBeNull();
+
+		const retry = [...(frame?.querySelectorAll("button") ?? [])].find(
+			(button) => button.textContent === "Try again",
+		);
+		await act(async () => retry?.click());
+
+		expect(frame?.querySelector('[role="alert"]')).toBeNull();
+		expect(frame?.querySelector("iframe")).not.toBeNull();
+		expect(frame?.style.height).toBe("120px");
+	});
+
+	it("keeps a ready widget mounted after a runtime error", async () => {
+		await act(async () => root.render(<WorkspaceWidgetSandbox html="<button>Run</button>" />));
+
+		const iframe = container.querySelector("iframe");
+		if (!iframe?.contentWindow) throw new Error("Expected the sandbox iframe window");
+		const frame = iframe.parentElement;
+
+		await act(async () => {
+			window.dispatchEvent(
+				new MessageEvent("message", {
+					data: {
+						source: WIDGET_SANDBOX_FRAME_SOURCE,
+						kind: "ready",
+						sessionId: 1,
+					},
+					source: iframe.contentWindow,
+				}),
+			);
+			window.dispatchEvent(
+				new MessageEvent("message", {
+					data: {
+						source: WIDGET_SANDBOX_FRAME_SOURCE,
+						kind: "error",
+						message: "Click failed",
+						sessionId: 1,
+					},
+					source: iframe.contentWindow,
+				}),
+			);
+		});
+
+		expect(frame?.querySelector("iframe")).toBe(iframe);
+		expect(frame?.querySelector('[role="alert"]')).not.toBeNull();
+		const dismiss = [...(frame?.querySelectorAll("button") ?? [])].find(
+			(button) => button.textContent === "Dismiss",
+		);
+		await act(async () => dismiss?.click());
+		expect(frame?.querySelector('[role="alert"]')).toBeNull();
+		expect(frame?.querySelector("iframe")).toBe(iframe);
 	});
 });
diff --git a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
index e027fc8bd..524923afc 100644
--- a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
+++ b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
@@ -17,6 +17,7 @@ import { cn } from "#/lib/utils";
 type WorkspaceWidgetSandboxProps = {
 	html: string;
 	className?: string;
+	label?: string;
 	/**
 	 * Called with the runtime error text when the user asks the AI to fix a
 	 * crashed widget. Omit to hide the affordance.
@@ -24,6 +25,11 @@ type WorkspaceWidgetSandboxProps = {
 	onAskAiToFix?: (error: string) => void;
 };
 
+type WidgetSandboxError = {
+	message: string;
+	preserveFrame: boolean;
+};
+
 /**
  * Renders untrusted, AI-authored widget HTML inside an opaque-origin sandbox
  * iframe. The frame cannot reach the parent's cookies, storage, or DOM. Host
@@ -34,6 +40,7 @@ type WorkspaceWidgetSandboxProps = {
 export function WorkspaceWidgetSandbox({
 	html,
 	className,
+	label,
 	onAskAiToFix,
 }: WorkspaceWidgetSandboxProps) {
 	const { resolvedTheme } = useTheme();
@@ -43,7 +50,7 @@ export function WorkspaceWidgetSandbox({
 	const readySessionIdRef = useRef<number | null>(null);
 	const themeRef = useRef<WidgetSandboxTheme | null>(null);
 	const [srcDoc, setSrcDoc] = useState<string | null>(null);
-	const [error, setError] = useState<string | null>(null);
+	const [error, setError] = useState<WidgetSandboxError | null>(null);
 	const [height, setHeight] = useState(WIDGET_SANDBOX_MIN_HEIGHT);
 
 	// Build a fresh document only when authored HTML changes. Theme changes send
@@ -63,6 +70,7 @@ export function WorkspaceWidgetSandbox({
 				renderedHtmlRef.current = html;
 				sessionIdRef.current += 1;
 				readySessionIdRef.current = null;
+				setHeight(WIDGET_SANDBOX_MIN_HEIGHT);
 				setSrcDoc(
 					buildWidgetSandboxDocument({
 						html,
@@ -94,7 +102,10 @@ export function WorkspaceWidgetSandbox({
 				return;
 			}
 			if (event.data.kind === "error") {
-				setError(event.data.message);
+				setError({
+					message: event.data.message,
+					preserveFrame: readySessionIdRef.current === event.data.sessionId,
+				});
 				return;
 			}
 			if (event.data.kind === "height") {
@@ -116,34 +127,63 @@ export function WorkspaceWidgetSandbox({
 		return () => window.removeEventListener("message", onMessage);
 	}, []);
 
+	const retryWidget = () => {
+		readySessionIdRef.current = null;
+		setError(null);
+		setHeight(WIDGET_SANDBOX_MIN_HEIGHT);
+	};
+	const showFrame = !error || error.preserveFrame;
+
 	return (
 		// Height comes from the frame's own content, so the block takes the room
 		// the widget needs instead of a number chosen here.
-		<div className={cn("relative bg-background", className)} style={error ? undefined : { height }}>
+		<div
+			className={cn("relative bg-background", className)}
+			style={showFrame ? { height } : undefined}
+		>
+			{showFrame ? (
+				<iframe
+					ref={iframeRef}
+					title={label ? `${label} widget` : "Widget"}
+					sandbox="allow-scripts"
+					srcDoc={srcDoc ?? undefined}
+					className="h-full w-full border-0 bg-background"
+				/>
+			) : null}
 			{error ? (
 				<div
 					role="alert"
-					className="flex min-h-48 flex-col items-center justify-center gap-4 bg-background p-6 text-center"
+					className={cn(
+						"flex min-h-48 flex-col items-center justify-center gap-4 bg-background p-6 text-center",
+						error.preserveFrame && "absolute inset-0 z-10 min-h-0 bg-background/95",
+					)}
 				>
 					<p className="font-medium text-foreground text-sm">Widget error</p>
 					<div className="max-h-32 w-full max-w-lg overflow-auto whitespace-pre-wrap rounded-md bg-muted px-4 py-3 font-mono text-muted-foreground text-xs leading-relaxed">
-						{error}
+						{error.message}
 					</div>
-					{onAskAiToFix ? (
-						<Button type="button" size="sm" variant="secondary" onClick={() => onAskAiToFix(error)}>
-							Ask AI to fix
+					<div className="flex items-center gap-2">
+						<Button
+							type="button"
+							size="sm"
+							variant="outline"
+							onClick={error.preserveFrame ? () => setError(null) : retryWidget}
+						>
+							{error.preserveFrame ? "Dismiss" : "Try again"}
 						</Button>
-					) : null}
+						{onAskAiToFix ? (
+							<Button
+								type="button"
+								size="sm"
+								variant="secondary"
+								onClick={() => onAskAiToFix(error.message)}
+							>
+								Ask AI to fix
+							</Button>
+						) : null}
+					</div>
 				</div>
-			) : (
-				<iframe
-					ref={iframeRef}
-					title="Widget preview"
-					sandbox="allow-scripts"
-					srcDoc={srcDoc ?? undefined}
-					className="h-full w-full border-0 bg-background"
-				/>
-			)}
+			) : null}
 		</div>
 	);
 }
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
index 1361cabda..1918e8b78 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
@@ -13,7 +13,7 @@ function loadsKatex(html: string) {
 		tokens: { "--background": "oklch(1 0 0)" },
 		origin: "https://app.test",
 		sessionId: 1,
-	}).includes("katex.min.js");
+	}).includes('<script src="https://app.test/widget-libs/katex/katex.min.js"></script>');
 }
 
 describe("buildWidgetSandboxDocument", () => {
@@ -32,19 +32,32 @@ describe("buildWidgetSandboxDocument", () => {
 		expect(loadsKatex("<canvas id='c'></canvas>")).toBe(false);
 	});
 
-	it("blocks remote assets and installs the error harness before authored scripts", () => {
+	it("limits external access to the bundled KaTeX assets", () => {
 		const authoredScript = '<script>throw new Error("boom")</script>';
 		const document = buildWidgetSandboxDocument({
 			html: authoredScript,
 			theme: "light",
-			tokens: {},
+			tokens: { "--not-a-widget-token": "red" },
 			origin: "https://app.test",
 			sessionId: 1,
 		});
 
+		expect(document).toContain("default-src 'none'");
+		expect(document).toContain(
+			"style-src 'unsafe-inline' https://app.test/widget-libs/katex/katex.min.css",
+		);
+		expect(document).toContain(
+			"script-src 'unsafe-inline' https://app.test/widget-libs/katex/katex.min.js https://app.test/widget-libs/katex/contrib/mhchem.min.js https://app.test/widget-libs/katex/contrib/auto-render.min.js",
+		);
+		expect(document).toContain("font-src data: https://app.test/widget-libs/katex/fonts/");
 		expect(document).toContain("img-src data: blob:");
 		expect(document).toContain("media-src data: blob:");
-		expect(document).not.toContain("img-src data: https:");
+		expect(document).toContain("connect-src 'none'");
+		expect(document).toContain("object-src 'none'");
+		expect(document).toContain("base-uri 'none'");
+		expect(document).toContain("form-action 'none'");
+		expect(document).not.toContain("--not-a-widget-token");
+		expect(document).not.toContain("script-src 'unsafe-inline' https://app.test;");
 		expect(document.indexOf('window.addEventListener("error"')).toBeLessThan(
 			document.indexOf(authoredScript),
 		);
@@ -103,5 +116,8 @@ describe("isWidgetSandboxFrameMessage", () => {
 				sessionId: 0,
 			}),
 		).toBe(false);
+		expect(isWidgetSandboxFrameMessage({ kind: "ready", sessionId: 1, source: "other" })).toBe(
+			false,
+		);
 	});
 });
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
index c29bc28ee..b739bdd7f 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
@@ -90,22 +90,35 @@ export const WIDGET_SANDBOX_TOKENS = [
 
 /** Path KaTeX's browser build is served from (see scripts/copy-widget-libs.mjs). */
 const WIDGET_KATEX_BASE_PATH = "/widget-libs/katex";
+const WIDGET_KATEX_STYLESHEET_PATH = `${WIDGET_KATEX_BASE_PATH}/katex.min.css`;
+const WIDGET_KATEX_SCRIPT_PATHS = [
+	`${WIDGET_KATEX_BASE_PATH}/katex.min.js`,
+	`${WIDGET_KATEX_BASE_PATH}/contrib/mhchem.min.js`,
+	`${WIDGET_KATEX_BASE_PATH}/contrib/auto-render.min.js`,
+] as const;
+const WIDGET_KATEX_FONT_PATH = `${WIDGET_KATEX_BASE_PATH}/fonts/`;
 
 /** Any supported math notation: chat LaTeX delimiters, document markup, or the API. */
 const WIDGET_MATH_PATTERN = /\$\$|\\\(|\\\[|data-latex|katex|renderMathInElement/;
 
 /**
- * Restrictive CSP for the frame. Widgets are self-contained HTML: inline
- * scripts/styles, plus the app's own origin so the bundled KaTeX build can
- * load. `connect-src 'none'` still blocks every runtime network call.
+ * Restrictive CSP for the frame. Widgets are self-contained HTML: only inline
+ * scripts/styles and the exact bundled KaTeX resources may load. Connection
+ * APIs such as fetch, XHR, and WebSocket are blocked. A script can still
+ * navigate its own sandboxed frame, so this policy promises isolation from the
+ * host app rather than impossible zero communication.
  */
 function getWidgetSandboxCsp(origin: string) {
+	const stylesheetUrl = `${origin}${WIDGET_KATEX_STYLESHEET_PATH}`;
+	const scriptUrls = WIDGET_KATEX_SCRIPT_PATHS.map((path) => `${origin}${path}`).join(" ");
+	const fontUrl = `${origin}${WIDGET_KATEX_FONT_PATH}`;
+
 	return [
 		"default-src 'none'",
-		`style-src 'unsafe-inline' ${origin}`,
-		`script-src 'unsafe-inline' ${origin}`,
+		`style-src 'unsafe-inline' ${stylesheetUrl}`,
+		`script-src 'unsafe-inline' ${scriptUrls}`,
 		"img-src data: blob:",
-		`font-src data: ${origin}`,
+		`font-src data: ${fontUrl}`,
 		"media-src data: blob:",
 		"connect-src 'none'",
 		"object-src 'none'",
@@ -129,19 +142,18 @@ export function buildWidgetSandboxDocument({
 	origin,
 	sessionId,
 }: BuildWidgetSandboxDocumentInput): string {
-	const tokenDeclarations = Object.entries(tokens)
-		.filter(([, value]) => value.trim().length > 0)
-		.map(([name, value]) => `${name}: ${value};`)
-		.join("");
+	let tokenDeclarations = "";
+	for (const name of WIDGET_SANDBOX_TOKENS) {
+		const value = tokens[name]?.trim();
+		if (value) tokenDeclarations += `${name}: ${value};`;
+	}
 
 	// Only widgets that actually contain math pay for KaTeX (~290KB plus fonts).
 	// Over-matching just costs a cached fetch; under-matching leaves math
 	// unrendered, so the test is deliberately loose.
 	const katexTags = WIDGET_MATH_PATTERN.test(html)
-		? `<link rel="stylesheet" href="${origin}${WIDGET_KATEX_BASE_PATH}/katex.min.css" />
-<script src="${origin}${WIDGET_KATEX_BASE_PATH}/katex.min.js"></script>
-<script src="${origin}${WIDGET_KATEX_BASE_PATH}/contrib/mhchem.min.js"></script>
-<script src="${origin}${WIDGET_KATEX_BASE_PATH}/contrib/auto-render.min.js"></script>`
+		? `<link rel="stylesheet" href="${origin}${WIDGET_KATEX_STYLESHEET_PATH}" />
+${WIDGET_KATEX_SCRIPT_PATHS.map((path) => `<script src="${origin}${path}"></script>`).join("\n")}`
 		: "";
 
 	// Widgets are HTML, so math is authored the same way documents author it —
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index 0b33edddc..1de2f4521 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -51,7 +51,7 @@ export const workspaceHtmlMathInstruction =
  * Carried by the document instruction because a widget is a document block: the
  * model reaches for one from inside the same write it would write prose in.
  */
-const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document, written as <div data-type="widget" title="Short title">…escaped HTML source…</div>. Use one only when the user explicitly asks for a widget, asks for interaction or live computation, or wants a visual artifact inside the document that ordinary blocks cannot express. Do not add a widget merely to decorate an explanation; keep normal content in normal blocks. Activate the "widget-authoring" skill before writing widget source; it has the full contract, a starter template, and canvas/layout rules. Hard constraints: the source is a self-contained fragment run in a sandboxed iframe, so provide only inner content (HTML plus inline <style> and <script>), never <!doctype>, <html>, <head>, or <body>; all JavaScript must be inline, with no external scripts, imports, or network access; style with the injected app CSS variables (--background, --foreground, --primary, --border, --radius, etc.) instead of hard-coded colors.`;
+const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document, written as <div data-type="widget" title="Short title">…escaped HTML source…</div>. Use one only when the user explicitly asks for a widget, asks for interaction or live computation, or wants a visual artifact inside the document that ordinary blocks cannot express. Do not add a widget merely to decorate an explanation; keep normal content in normal blocks. Activate the "widget-authoring" skill before writing widget source; it has the full contract, a starter template, and canvas/layout rules. Hard constraints: the source is a self-contained fragment run in a sandboxed iframe, so provide only inner content (HTML plus inline <style> and <script>), never <!doctype>, <html>, <head>, or <body>; keep all JavaScript inline and do not use external scripts, imports, fetch, or navigation; style with the injected app CSS variables (--background, --foreground, --primary, --border, --radius, etc.) instead of hard-coded colors.`;
 
 export const workspaceDocumentHtmlInstruction = `Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. ${workspaceHtmlMathInstruction} For checkboxes, use <ul data-type="taskList"><li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>Item</p></div></li></ul>. Documents cannot hold images: never use <img> or <figure>, and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with <citation ref="wr_7Kp2Qa9x"></citation> placed after the claim it supports. ${workspaceWidgetHtmlInstruction}`;
 

From 030763c134b59645001b9580a8f5a30c9a96cfe9 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 12:25:23 -0400
Subject: [PATCH 19/32] refactor(composer): stage prompts in active draft

---
 .../components/WorkspaceContent.tsx           | 13 ++-
 .../components/WorkspaceItemToolbarSlot.tsx   |  5 +-
 .../components/ai-chat/AiChatPromptInput.tsx  | 43 ++++++++--
 .../ai-chat/useConsumeComposerPrompt.ts       | 50 -----------
 .../document-editor/DocumentEditorSurface.tsx | 45 +++++-----
 .../document-editor/DocumentToolbar.tsx       | 35 +++-----
 .../components/workspace-view-policy.tsx      |  4 +-
 .../workspace-composer-actions.test.ts        | 50 +++++++++++
 .../composer/workspace-composer-actions.ts    | 18 +++-
 .../documents/document-widget-extension.ts    | 11 +--
 .../documents/document-widget-node.tsx        | 27 ++++--
 .../workspaces/documents/tiptap-extensions.ts |  8 +-
 src/features/workspaces/model/tree.ts         | 13 +++
 .../model/use-workspace-item-path.ts          | 46 ----------
 .../model/workspace-ai-context-reference.ts   | 25 +-----
 .../workspace-ai-composer-draft-store.ts      | 86 +++++++++----------
 16 files changed, 226 insertions(+), 253 deletions(-)
 delete mode 100644 src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts
 create mode 100644 src/features/workspaces/composer/workspace-composer-actions.test.ts
 delete mode 100644 src/features/workspaces/model/use-workspace-item-path.ts

diff --git a/src/features/workspaces/components/WorkspaceContent.tsx b/src/features/workspaces/components/WorkspaceContent.tsx
index b85bb6468..fb4a8b59e 100644
--- a/src/features/workspaces/components/WorkspaceContent.tsx
+++ b/src/features/workspaces/components/WorkspaceContent.tsx
@@ -1,5 +1,5 @@
 import { Eye, FolderOpen } from "lucide-react";
-import { useRef, useState } from "react";
+import { useMemo, useRef, useState } from "react";
 
 import { ContextMenu, ContextMenuContent, ContextMenuTrigger } from "#/components/ui/context-menu";
 import {
@@ -40,7 +40,11 @@ import { useWorkspaceMutationAccess } from "#/features/workspaces/components/wor
 import { useWorkspaceViewCapabilities } from "#/features/workspaces/components/workspace-view-policy";
 import type { WorkspaceItemType, WorkspaceSummary } from "#/features/workspaces/contracts";
 import { getWorkspaceItemDisplay } from "#/features/workspaces/model/item-display";
-import { getWorkspaceChildren, splitWorkspaceChildren } from "#/features/workspaces/model/tree";
+import {
+	getWorkspaceChildren,
+	getWorkspaceItemPath,
+	splitWorkspaceChildren,
+} from "#/features/workspaces/model/tree";
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
 import { getWorkspaceBrowseParentId, isWorkspaceItemView } from "#/features/workspaces/model/view";
 import { workspaceUploadTypeLabel } from "#/features/workspaces/upload/workspace-upload-intake";
@@ -69,11 +73,13 @@ export default function WorkspaceContent({
 }: WorkspaceContentProps) {
 	const workspaceId = workspace.id;
 	const actionDialogs = useWorkspaceItemActionDialogState();
+	const itemsById = useMemo(() => new Map(items.map((item) => [item.id, item])), [items]);
 
 	if (isWorkspaceItemView(activeItem)) {
 		return (
 			<>
 				<WorkspaceItemView
+					documentPath={getWorkspaceItemPath(activeItem, itemsById)}
 					item={activeItem}
 					viewInstanceId={viewInstanceId}
 					workspaceId={workspaceId}
@@ -472,6 +478,7 @@ function WorkspaceContentActionDialogs({
 }
 
 function WorkspaceItemView({
+	documentPath,
 	item,
 	viewInstanceId,
 	workspaceId,
@@ -479,6 +486,7 @@ function WorkspaceItemView({
 	onMoveItem,
 	onDeleteItem,
 }: {
+	documentPath: string;
 	item: WorkspaceItem;
 	viewInstanceId: string;
 	workspaceId: string;
@@ -491,6 +499,7 @@ function WorkspaceItemView({
 	if (item.type === "document") {
 		return (
 			<DocumentEditorSurface
+				documentPath={documentPath}
 				item={item}
 				viewInstanceId={viewInstanceId}
 				workspaceId={workspaceId}
diff --git a/src/features/workspaces/components/WorkspaceItemToolbarSlot.tsx b/src/features/workspaces/components/WorkspaceItemToolbarSlot.tsx
index 715362053..c32f44c16 100644
--- a/src/features/workspaces/components/WorkspaceItemToolbarSlot.tsx
+++ b/src/features/workspaces/components/WorkspaceItemToolbarSlot.tsx
@@ -16,8 +16,7 @@ import { WorkspaceFileToolbar } from "#/features/workspaces/components/Workspace
 type WorkspaceItemToolbarRegistration =
 	| {
 			canEdit: boolean;
-			/** Null until the workspace page is cached; the widget action waits on it. */
-			documentPath: string | null;
+			documentPath: string;
 			editor: Editor | null;
 			itemId: string;
 			kind: "document";
@@ -63,7 +62,7 @@ export function useDocumentEditorToolbar({
 	workspaceId,
 }: {
 	canEdit: boolean;
-	documentPath: string | null;
+	documentPath: string;
 	editor: Editor | null;
 	itemId: string;
 	slotId: string;
diff --git a/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx b/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx
index c474925dd..9c4dad81d 100644
--- a/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx
@@ -1,5 +1,13 @@
 import { Bug, Mic, Paperclip } from "lucide-react";
-import { lazy, type SetStateAction, Suspense, useRef, useState } from "react";
+import {
+	lazy,
+	type SetStateAction,
+	Suspense,
+	useCallback,
+	useEffect,
+	useRef,
+	useState,
+} from "react";
 
 import {
 	type AttachmentsContext,
@@ -26,7 +34,6 @@ import {
 import type { AiChatModelId, AiChatStatus } from "#/features/workspaces/components/ai-chat/types";
 import { useAiChatAttachmentIntake } from "#/features/workspaces/components/ai-chat/useAiChatAttachmentIntake";
 import { useAiChatDictation } from "#/features/workspaces/components/ai-chat/useAiChatDictation";
-import { useConsumeComposerPrompt } from "#/features/workspaces/components/ai-chat/useConsumeComposerPrompt";
 import { useTypeToFocusPrompt } from "#/features/workspaces/components/ai-chat/useTypeToFocusPrompt";
 import { WorkspaceFileIntakeReviewDialog } from "#/features/workspaces/components/WorkspaceFileIntakeReviewDialog";
 import { useWorkspaceFileUpload } from "#/features/workspaces/components/WorkspaceFileUploadProvider";
@@ -42,6 +49,7 @@ import {
 	useWorkspaceAiComposerDraftFiles,
 	useWorkspaceAiComposerDraftStore,
 	useWorkspaceAiComposerDraftText,
+	useWorkspaceAiComposerFocusRequest,
 } from "#/features/workspaces/state/workspace-ai-composer-draft-store";
 import { cn } from "#/lib/utils";
 
@@ -105,7 +113,12 @@ export default function AiChatPromptInput({
 	const textareaRef = useRef<HTMLTextAreaElement>(null);
 	const input = useWorkspaceAiComposerDraftText(activeThreadId);
 	const setDraftText = useWorkspaceAiComposerDraftStore((state) => state.setText);
-	const setInput = (value: SetStateAction<string>) => setDraftText(activeThreadId, value);
+	const setInput = useCallback(
+		(value: SetStateAction<string>) => setDraftText(activeThreadId, value),
+		[activeThreadId, setDraftText],
+	);
+	const focusRequest = useWorkspaceAiComposerFocusRequest(activeThreadId);
+	const clearFocusRequest = useWorkspaceAiComposerDraftStore((state) => state.clearFocusRequest);
 	const dictation = useAiChatDictation({ input, setInput });
 	const draftFiles = useWorkspaceAiComposerDraftFiles(activeThreadId);
 	const attachmentsReady =
@@ -131,11 +144,25 @@ export default function AiChatPromptInput({
 		setInput,
 		textareaRef,
 	});
-	useConsumeComposerPrompt({
-		setInput,
-		textareaRef,
-		workspaceId: context.workspaceId,
-	});
+	useEffect(() => {
+		if (focusRequest === 0) {
+			return;
+		}
+
+		const frame = requestAnimationFrame(() => {
+			const textarea = textareaRef.current;
+			if (!textarea) {
+				return;
+			}
+
+			textarea.focus();
+			const caret = textarea.value.length;
+			textarea.setSelectionRange(caret, caret);
+			clearFocusRequest(activeThreadId, focusRequest);
+		});
+
+		return () => cancelAnimationFrame(frame);
+	}, [activeThreadId, clearFocusRequest, focusRequest]);
 
 	const attachments: Omit<AttachmentsContext, "openFileDialog"> = {
 		add: addFiles,
diff --git a/src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts b/src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts
deleted file mode 100644
index 13aeb4c29..000000000
--- a/src/features/workspaces/components/ai-chat/useConsumeComposerPrompt.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-import { type RefObject, useEffect } from "react";
-
-import {
-	useWorkspaceAiComposerDraftPrompt,
-	useWorkspaceAiComposerDraftStore,
-} from "#/features/workspaces/state/workspace-ai-composer-draft-store";
-
-type UseConsumeComposerPromptOptions = {
-	workspaceId: string;
-	setInput: (updater: (current: string) => string) => void;
-	textareaRef: RefObject<HTMLTextAreaElement | null>;
-};
-
-/**
- * Seeds the composer with text staged via `stageComposerPrompt` (e.g. an item
- * viewer's "Ask AI to fix" button), then clears it from the store so it is
- * consumed exactly once. Existing composer text is preserved — the staged text
- * is appended rather than overwriting what the user already typed. The staged
- * text is never auto-sent; the user reviews and sends it themselves.
- */
-export function useConsumeComposerPrompt({
-	workspaceId,
-	setInput,
-	textareaRef,
-}: UseConsumeComposerPromptOptions) {
-	const pendingPrompt = useWorkspaceAiComposerDraftPrompt(workspaceId);
-	const clearPrompt = useWorkspaceAiComposerDraftStore((state) => state.clearPrompt);
-
-	useEffect(() => {
-		if (!pendingPrompt) {
-			return;
-		}
-
-		setInput((current) =>
-			current.trim() ? `${current.trimEnd()}\n\n${pendingPrompt}` : pendingPrompt,
-		);
-		clearPrompt(workspaceId);
-
-		requestAnimationFrame(() => {
-			const textarea = textareaRef.current;
-			if (!textarea) {
-				return;
-			}
-
-			textarea.focus();
-			const caret = textarea.value.length;
-			textarea.setSelectionRange(caret, caret);
-		});
-	}, [pendingPrompt, workspaceId, clearPrompt, setInput, textareaRef]);
-}
diff --git a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
index da0542f76..01b59373e 100644
--- a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
+++ b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
@@ -1,7 +1,7 @@
 import Collaboration from "@tiptap/extension-collaboration";
 import CollaborationCaret from "@tiptap/extension-collaboration-caret";
 import { EditorContent, useEditor } from "@tiptap/react";
-import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useQuery } from "@tanstack/react-query";
 import { useState } from "react";
 
 import { Skeleton } from "#/components/ui/skeleton";
@@ -12,6 +12,7 @@ import { useDocumentEditorToolbar } from "#/features/workspaces/components/Works
 import { useWorkspacePaneRuntime } from "#/features/workspaces/components/WorkspacePaneRuntime";
 import { useWorkspaceMutationAccess } from "#/features/workspaces/components/workspace-mutation-access";
 import { DocumentEditReviewExtension } from "#/features/workspaces/documents/document-edit-review-extension";
+import { DocumentWidgetActionProvider } from "#/features/workspaces/documents/document-widget-node";
 import {
 	getTiptapDocumentBaseExtensions,
 	tiptapDocumentYjsField,
@@ -22,18 +23,16 @@ import {
 } from "#/features/workspaces/documents/use-document-collaboration-session";
 import { useDocumentEditReviewOverlay } from "#/features/workspaces/documents/use-document-edit-review-overlay";
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
-import {
-	readWorkspaceItemPath,
-	useWorkspaceItemPath,
-} from "#/features/workspaces/model/use-workspace-item-path";
 import { DEFAULT_COLLABORATION_COLOR } from "#/lib/design-system-colors";
 import { getAuthSessionQueryOptions } from "#/lib/session-query";
 
 export function DocumentEditorSurface({
+	documentPath,
 	item,
 	viewInstanceId,
 	workspaceId,
 }: {
+	documentPath: string;
 	item: WorkspaceItem;
 	viewInstanceId: string;
 	workspaceId: string;
@@ -55,6 +54,7 @@ export function DocumentEditorSurface({
 	return (
 		<DocumentEditorInstance
 			collaborationSession={collaborationSession}
+			documentPath={documentPath}
 			item={item}
 			viewInstanceId={viewInstanceId}
 			workspaceId={workspaceId}
@@ -64,19 +64,19 @@ export function DocumentEditorSurface({
 
 function DocumentEditorInstance({
 	collaborationSession,
+	documentPath,
 	item,
 	viewInstanceId,
 	workspaceId,
 }: {
 	collaborationSession: DocumentCollaborationSession;
+	documentPath: string;
 	item: WorkspaceItem;
 	viewInstanceId: string;
 	workspaceId: string;
 }) {
 	const { capabilities } = useWorkspaceMutationAccess();
-	const documentPath = useWorkspaceItemPath(workspaceId, item);
 	const paneRuntime = useWorkspacePaneRuntime();
-	const queryClient = useQueryClient();
 	const [scrollTarget, setScrollTarget] = useState<HTMLDivElement | null>(null);
 	const editor = useEditor({
 		immediatelyRender: false,
@@ -86,15 +86,7 @@ function DocumentEditorInstance({
 		onContentError: ({ disableCollaboration }) => {
 			disableCollaboration();
 		},
-		extensions: getDocumentEditorExtensions(collaborationSession, {
-			onAskAiToFixWidget: capabilities.canMutateContent
-				? (error) =>
-						stageComposerPrompt(
-							workspaceId,
-							`A widget in ${readWorkspaceItemPath(queryClient, workspaceId, item) ?? item.name} hit this error. Please fix it:\n\n${error}`,
-						)
-				: undefined,
-		}),
+		extensions: getDocumentEditorExtensions(collaborationSession),
 		editorProps: {
 			attributes: {
 				"aria-label": capabilities.canMutateContent
@@ -139,7 +131,19 @@ function DocumentEditorInstance({
 						scrollTarget={scrollTarget}
 						workspaceId={workspaceId}
 					/>
-					<EditorContent className="min-h-full" editor={editor} />
+					<DocumentWidgetActionProvider
+						onAskAiToFix={
+							capabilities.canMutateContent
+								? (error) =>
+										stageComposerPrompt(
+											workspaceId,
+											`A widget in ${documentPath} hit this error. Please fix it:\n\n${error}`,
+										)
+								: undefined
+						}
+					>
+						<EditorContent className="min-h-full" editor={editor} />
+					</DocumentWidgetActionProvider>
 				</div>
 			</div>
 			<DocumentWordCount editor={editor} />
@@ -147,11 +151,8 @@ function DocumentEditorInstance({
 	);
 }
 
-function getDocumentEditorExtensions(
-	collaborationSession: DocumentCollaborationSession,
-	options: { onAskAiToFixWidget?: (error: string) => void },
-) {
-	const baseExtensions = getTiptapDocumentBaseExtensions(options);
+function getDocumentEditorExtensions(collaborationSession: DocumentCollaborationSession) {
+	const baseExtensions = getTiptapDocumentBaseExtensions();
 
 	return [
 		...baseExtensions,
diff --git a/src/features/workspaces/components/document-editor/DocumentToolbar.tsx b/src/features/workspaces/components/document-editor/DocumentToolbar.tsx
index fd97a5c34..d2c90c0fe 100644
--- a/src/features/workspaces/components/document-editor/DocumentToolbar.tsx
+++ b/src/features/workspaces/components/document-editor/DocumentToolbar.tsx
@@ -47,7 +47,7 @@ export function DocumentToolbar({
 	workspaceId,
 }: {
 	canEdit: boolean;
-	documentPath: string | null;
+	documentPath: string;
 	editor: Editor | null;
 	itemId: string;
 	workspaceId: string;
@@ -90,7 +90,7 @@ export function DocumentToolbar({
 					<DocumentMobileMenuContent
 						editor={editor}
 						editorState={editorState}
-						onAddWidget={documentPath ? () => setAddWidgetOpen(true) : undefined}
+						onAddWidget={() => setAddWidgetOpen(true)}
 					/>
 				}
 				mobileContentClassName="max-h-[min(var(--available-height),28rem)] w-64 max-w-[calc(100dvw-2rem)] overscroll-contain"
@@ -113,25 +113,17 @@ export function DocumentToolbar({
 				>
 					<Redo2 />
 				</ToolbarButton>
-				{/* Disabled rather than hidden while the path loads, so the control
-				    does not appear and disappear as the workspace page settles. */}
-				<ToolbarButton
-					label="Add widget"
-					disabled={!documentPath}
-					onClick={() => setAddWidgetOpen(true)}
-				>
+				<ToolbarButton label="Add widget" onClick={() => setAddWidgetOpen(true)}>
 					<Shapes />
 				</ToolbarButton>
 				<DocumentMoreMenu disabled={!editor} />
 			</WorkspaceResponsiveToolbar>
-			{documentPath ? (
-				<WorkspaceAddWidgetDialog
-					documentPath={documentPath}
-					open={addWidgetOpen}
-					workspaceId={workspaceId}
-					onOpenChange={setAddWidgetOpen}
-				/>
-			) : null}
+			<WorkspaceAddWidgetDialog
+				documentPath={documentPath}
+				open={addWidgetOpen}
+				workspaceId={workspaceId}
+				onOpenChange={setAddWidgetOpen}
+			/>
 		</>
 	);
 }
@@ -184,7 +176,7 @@ function DocumentMobileMenuContent({
 }: {
 	editor: Editor | null;
 	editorState: DocumentEditorUiState;
-	onAddWidget?: () => void;
+	onAddWidget: () => void;
 }) {
 	return (
 		<>
@@ -228,12 +220,7 @@ function DocumentMobileMenuContent({
 					label="Redo"
 					onClick={() => editor?.chain().focus().redo().run()}
 				/>
-				<DocumentHistoryMenuItem
-					disabled={!onAddWidget}
-					icon={<Shapes />}
-					label="Add widget"
-					onClick={() => onAddWidget?.()}
-				/>
+				<DocumentHistoryMenuItem icon={<Shapes />} label="Add widget" onClick={onAddWidget} />
 			</DropdownMenuGroup>
 			<DropdownMenuSeparator />
 			<DocumentExportMenuGroup />
diff --git a/src/features/workspaces/components/workspace-view-policy.tsx b/src/features/workspaces/components/workspace-view-policy.tsx
index 5fe216298..d456be85a 100644
--- a/src/features/workspaces/components/workspace-view-policy.tsx
+++ b/src/features/workspaces/components/workspace-view-policy.tsx
@@ -40,7 +40,7 @@ function subscribeToWorkspaceViewportChange(onChange: () => void) {
 	return () => media.removeEventListener("change", onChange);
 }
 
-function getWorkspaceViewportSnapshot(): WorkspaceViewportMode {
+export function getWorkspaceViewportMode(): WorkspaceViewportMode {
 	return window.matchMedia(WORKSPACE_DESKTOP_MEDIA_QUERY).matches ? "desktop" : "mobile";
 }
 
@@ -51,7 +51,7 @@ function getWorkspaceViewportServerSnapshot(): WorkspaceViewportMode {
 export function useWorkspaceViewPolicy() {
 	const viewportMode = useSyncExternalStore(
 		subscribeToWorkspaceViewportChange,
-		getWorkspaceViewportSnapshot,
+		getWorkspaceViewportMode,
 		getWorkspaceViewportServerSnapshot,
 	);
 
diff --git a/src/features/workspaces/composer/workspace-composer-actions.test.ts b/src/features/workspaces/composer/workspace-composer-actions.test.ts
new file mode 100644
index 000000000..98790d7d6
--- /dev/null
+++ b/src/features/workspaces/composer/workspace-composer-actions.test.ts
@@ -0,0 +1,50 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { getDefaultWorkspaceThreadId } from "#/features/workspaces/ai/ai-thread-identity";
+import { stageComposerPrompt } from "#/features/workspaces/composer/workspace-composer-actions";
+import { useWorkspaceAiComposerDraftStore } from "#/features/workspaces/state/workspace-ai-composer-draft-store";
+import {
+	getWorkspaceUiSession,
+	useWorkspaceUiStore,
+} from "#/features/workspaces/state/workspace-ui-store";
+
+const workspaceId = "workspace-1";
+const threadId = getDefaultWorkspaceThreadId(workspaceId);
+
+describe("stageComposerPrompt", () => {
+	beforeEach(() => {
+		vi.stubGlobal("localStorage", {
+			getItem: vi.fn(() => null),
+			removeItem: vi.fn(),
+			setItem: vi.fn(),
+		});
+		useWorkspaceAiComposerDraftStore.setState({
+			focusRequestByThreadId: {},
+			textByThreadId: { [threadId]: "Existing draft" },
+		});
+		useWorkspaceUiStore.setState({ sessionsByWorkspaceId: {} });
+	});
+
+	afterEach(() => {
+		vi.unstubAllGlobals();
+	});
+
+	it.each([
+		{ desktop: false, expectedMode: "fullscreen" },
+		{ desktop: true, expectedMode: "docked" },
+	] as const)("reveals the composer as $expectedMode", ({ desktop, expectedMode }) => {
+		vi.stubGlobal("window", {
+			matchMedia: () => ({ matches: desktop }),
+		});
+
+		stageComposerPrompt(workspaceId, "Build a widget");
+
+		expect(
+			getWorkspaceUiSession(useWorkspaceUiStore.getState().getSession(workspaceId)).chatSurfaceMode,
+		).toBe(expectedMode);
+		expect(useWorkspaceAiComposerDraftStore.getState().textByThreadId[threadId]).toBe(
+			"Existing draft\n\nBuild a widget",
+		);
+		expect(useWorkspaceAiComposerDraftStore.getState().focusRequestByThreadId[threadId]).toBe(1);
+	});
+});
diff --git a/src/features/workspaces/composer/workspace-composer-actions.ts b/src/features/workspaces/composer/workspace-composer-actions.ts
index 8af959b5c..5c4b0bce3 100644
--- a/src/features/workspaces/composer/workspace-composer-actions.ts
+++ b/src/features/workspaces/composer/workspace-composer-actions.ts
@@ -1,5 +1,6 @@
 import { toast } from "sonner";
 import { WORKSPACE_AI_CHAT_ATTACHMENT_POLICY } from "#/features/workspaces/components/ai-chat/constants";
+import { getWorkspaceViewportMode } from "#/features/workspaces/components/workspace-view-policy";
 import { getDefaultWorkspaceThreadId } from "#/features/workspaces/ai/ai-thread-identity";
 import type { WorkspaceSelectedQuote } from "#/features/workspaces/model/workspace-selected-quotes";
 import { useWorkspaceAiComposerDraftStore } from "#/features/workspaces/state/workspace-ai-composer-draft-store";
@@ -39,10 +40,10 @@ export function stageComposerPrompt(
 		return;
 	}
 
-	useWorkspaceAiComposerDraftStore.getState().setPrompt(workspaceId, trimmed);
+	useWorkspaceAiComposerDraftStore.getState().stageText(getComposerThreadId(workspaceId), trimmed);
 
 	if (revealChat) {
-		useWorkspaceUiStore.getState().setChatSurfaceMode(workspaceId, "docked");
+		revealComposer(workspaceId);
 	}
 }
 
@@ -56,7 +57,7 @@ export function stageComposerQuote(
 	useWorkspaceAiComposerDraftStore.getState().addQuote(workspaceId, quote);
 
 	if (revealChat) {
-		useWorkspaceUiStore.getState().setChatSurfaceMode(workspaceId, "docked");
+		revealComposer(workspaceId);
 	}
 }
 
@@ -74,10 +75,19 @@ export function stageComposerFiles(
 	});
 
 	if (revealChat) {
-		useWorkspaceUiStore.getState().setChatSurfaceMode(workspaceId, "docked");
+		revealComposer(workspaceId);
 	}
 }
 
+function revealComposer(workspaceId: string) {
+	useWorkspaceUiStore
+		.getState()
+		.setChatSurfaceMode(
+			workspaceId,
+			getWorkspaceViewportMode() === "mobile" ? "fullscreen" : "docked",
+		);
+}
+
 export function stageCaptureAttachmentToComposer(
 	workspaceId: string,
 	file: File,
diff --git a/src/features/workspaces/documents/document-widget-extension.ts b/src/features/workspaces/documents/document-widget-extension.ts
index f31ed7f9f..63fe2a8b3 100644
--- a/src/features/workspaces/documents/document-widget-extension.ts
+++ b/src/features/workspaces/documents/document-widget-extension.ts
@@ -1,17 +1,10 @@
 import { ReactNodeViewRenderer } from "@tiptap/react";
 
-import {
-	DocumentWidgetView,
-	type DocumentWidgetViewOptions,
-} from "#/features/workspaces/documents/document-widget-node";
+import { DocumentWidgetView } from "#/features/workspaces/documents/document-widget-node";
 import { Widget } from "#/features/workspaces/documents/tiptap-schema";
 
 /** Adds the sandboxed React view to the shared widget schema node. */
-export const DocumentWidget = Widget.extend<DocumentWidgetViewOptions>({
-	addOptions() {
-		return { onAskAiToFix: null };
-	},
-
+export const DocumentWidget = Widget.extend({
 	addNodeView() {
 		return ReactNodeViewRenderer(DocumentWidgetView, {
 			ignoreMutation: ({ mutation }) => mutation.type !== "selection",
diff --git a/src/features/workspaces/documents/document-widget-node.tsx b/src/features/workspaces/documents/document-widget-node.tsx
index bede067d6..db0f9ab30 100644
--- a/src/features/workspaces/documents/document-widget-node.tsx
+++ b/src/features/workspaces/documents/document-widget-node.tsx
@@ -1,6 +1,7 @@
 import type { NodeViewProps } from "@tiptap/react";
 import { NodeViewContent, NodeViewWrapper } from "@tiptap/react";
 import { Shapes } from "lucide-react";
+import { createContext, type ReactNode, use } from "react";
 
 import {
 	CodeBlockHeader,
@@ -9,13 +10,20 @@ import {
 } from "#/components/code-block/code-block-chrome";
 import { WorkspaceWidgetSandbox } from "#/features/workspaces/components/widget/WorkspaceWidgetSandbox";
 
-export interface DocumentWidgetViewOptions {
-	/**
-	 * Called with a crashed widget's error text so the surface can offer a way
-	 * out. Left unset the affordance is hidden, which is right for any read-only
-	 * rendering of a document.
-	 */
-	onAskAiToFix: ((error: string) => void) | null;
+const DocumentWidgetActionContext = createContext<((error: string) => void) | null>(null);
+
+export function DocumentWidgetActionProvider({
+	children,
+	onAskAiToFix,
+}: {
+	children: ReactNode;
+	onAskAiToFix?: (error: string) => void;
+}) {
+	return (
+		<DocumentWidgetActionContext value={onAskAiToFix ?? null}>
+			{children}
+		</DocumentWidgetActionContext>
+	);
 }
 
 /**
@@ -31,10 +39,10 @@ export interface DocumentWidgetViewOptions {
  * and `ignoreMutation` stops the editor re-parsing when React re-renders the
  * header — selection mutations pass through so clicking away behaves normally.
  */
-export function DocumentWidgetView({ extension, node, selected }: NodeViewProps) {
+export function DocumentWidgetView({ node, selected }: NodeViewProps) {
 	const html = node.textContent;
 	const title = typeof node.attrs.title === "string" ? node.attrs.title : "";
-	const { onAskAiToFix } = extension.options as DocumentWidgetViewOptions;
+	const onAskAiToFix = use(DocumentWidgetActionContext);
 	const label = title || "Widget";
 	const askAiToFix = onAskAiToFix
 		? (error: string) => onAskAiToFix(title ? `the "${title}" widget: ${error}` : error)
@@ -62,6 +70,7 @@ export function DocumentWidgetView({ extension, node, selected }: NodeViewProps)
 			</CodeBlockHeader>
 			<WorkspaceWidgetSandbox
 				html={html}
+				label={title || undefined}
 				className="workspace-document-widget-frame"
 				onAskAiToFix={askAiToFix}
 			/>
diff --git a/src/features/workspaces/documents/tiptap-extensions.ts b/src/features/workspaces/documents/tiptap-extensions.ts
index b7510e7a3..68c2469c7 100644
--- a/src/features/workspaces/documents/tiptap-extensions.ts
+++ b/src/features/workspaces/documents/tiptap-extensions.ts
@@ -14,17 +14,13 @@ import {
 
 export { tiptapDocumentYjsField };
 
-export function getTiptapDocumentBaseExtensions(
-	options: { onAskAiToFixWidget?: (error: string) => void } = {},
-) {
+export function getTiptapDocumentBaseExtensions() {
 	return [
 		...getTiptapDocumentSchemaExtensions({
 			// All three extend the node spec the server uses, adding only how it draws.
 			citation: DocumentCitation,
 			codeBlock: CodeBlockShiki,
-			widget: DocumentWidget.configure({
-				onAskAiToFix: options.onAskAiToFixWidget ?? null,
-			}),
+			widget: DocumentWidget,
 		}),
 		Placeholder.configure({
 			placeholder: ({ node }) => (node.type.name === "heading" ? "Untitled" : "Write something..."),
diff --git a/src/features/workspaces/model/tree.ts b/src/features/workspaces/model/tree.ts
index b8a904ed8..5aa4cff1e 100644
--- a/src/features/workspaces/model/tree.ts
+++ b/src/features/workspaces/model/tree.ts
@@ -1,4 +1,5 @@
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
+import { joinWorkspacePathSegment } from "#/features/workspaces/kernel/workspace-kernel-paths";
 
 interface WorkspaceTreeItem {
 	id: string;
@@ -127,6 +128,18 @@ export function getWorkspaceBreadcrumbItems(
 	return [...ancestors, item];
 }
 
+export function getWorkspaceItemPath(
+	item: WorkspaceItem,
+	itemsById: ReadonlyMap<string, WorkspaceItem>,
+) {
+	const relativePath = getWorkspaceBreadcrumbItems(item, itemsById).reduce(
+		(path, entry) => joinWorkspacePathSegment(path, entry.name),
+		"",
+	);
+
+	return `/${relativePath}`;
+}
+
 export function getWorkspaceItemMeta(item: WorkspaceItem, allItems: WorkspaceItem[]) {
 	if (item.type !== "folder") {
 		return item.meta;
diff --git a/src/features/workspaces/model/use-workspace-item-path.ts b/src/features/workspaces/model/use-workspace-item-path.ts
deleted file mode 100644
index cbbe85c07..000000000
--- a/src/features/workspaces/model/use-workspace-item-path.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { type QueryClient, useQuery } from "@tanstack/react-query";
-import { useMemo } from "react";
-
-import type { WorkspaceItem } from "#/features/workspaces/model/types";
-import { getWorkspaceAiContextItemPath } from "#/features/workspaces/model/workspace-ai-context-reference";
-import { workspacePageQueryOptions } from "#/features/workspaces/query-options";
-
-/**
- * Absolute workspace path for one item, for surfaces that only hold the item.
- *
- * Reads the already-cached workspace page rather than asking the server, so a
- * component can name a path without waiting on a round trip. Returns null until
- * the page is in cache.
- */
-export function useWorkspaceItemPath(workspaceId: string, item: WorkspaceItem | null) {
-	const { data } = useQuery(workspacePageQueryOptions(workspaceId));
-	const items = data?.items;
-
-	return useMemo(() => {
-		if (!item || !items) {
-			return null;
-		}
-
-		return getWorkspaceAiContextItemPath(item, new Map(items.map((entry) => [entry.id, entry])));
-	}, [item, items]);
-}
-
-/**
- * The same path, read imperatively at call time.
- *
- * For callbacks that outlive the render that created them — a Tiptap extension
- * option, say — where capturing the path would pin whatever was known when the
- * editor was built, which is usually nothing.
- */
-export function readWorkspaceItemPath(
-	queryClient: QueryClient,
-	workspaceId: string,
-	item: WorkspaceItem,
-) {
-	const page = queryClient.getQueryData(workspacePageQueryOptions(workspaceId).queryKey);
-	if (!page) {
-		return null;
-	}
-
-	return getWorkspaceAiContextItemPath(item, new Map(page.items.map((entry) => [entry.id, entry])));
-}
diff --git a/src/features/workspaces/model/workspace-ai-context-reference.ts b/src/features/workspaces/model/workspace-ai-context-reference.ts
index e09fbd89b..f5fd6f5f8 100644
--- a/src/features/workspaces/model/workspace-ai-context-reference.ts
+++ b/src/features/workspaces/model/workspace-ai-context-reference.ts
@@ -1,7 +1,6 @@
 import { getWorkspaceItemTypeMeta } from "#/features/workspaces/defaults";
-import { joinWorkspacePathSegment } from "#/features/workspaces/kernel/workspace-kernel-paths";
 import type { WorkspaceTab } from "#/features/workspaces/model/tab-types";
-import { getWorkspaceBreadcrumbItems } from "#/features/workspaces/model/tree";
+import { getWorkspaceItemPath } from "#/features/workspaces/model/tree";
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
 import { getWorkspaceAiContextItemViewState } from "#/features/workspaces/model/workspace-item-view-state";
 import type { WorkspacePane } from "#/features/workspaces/state/workspace-ui-store";
@@ -22,7 +21,7 @@ export function getWorkspaceAiContextItemReference(input: {
 
 	return {
 		name: item.name,
-		path: getWorkspaceAiContextItemPath(item, context.itemsById),
+		path: getWorkspaceItemPath(item, context.itemsById),
 		type: getWorkspaceItemTypeMeta(item.type),
 		state: {
 			activeVisible: isVisible,
@@ -76,23 +75,3 @@ export function getOpenTabItemIds(tabs: WorkspaceTab[]) {
 
 	return itemTabTitles;
 }
-
-/**
- * Absolute workspace path for one item, derived from the client item tree.
- *
- * Matches the paths the kernel resolves, so it is safe to hand to the model —
- * a prefilled prompt naming a path stays correct even if the user switches
- * views before sending it.
- */
-export function getWorkspaceAiContextItemPath(
-	item: WorkspaceItem,
-	itemsById: ReadonlyMap<string, WorkspaceItem>,
-) {
-	const breadcrumbItems = getWorkspaceBreadcrumbItems(item, itemsById);
-	const relativePath = breadcrumbItems.reduce(
-		(path, entry) => joinWorkspacePathSegment(path, entry.name),
-		"",
-	);
-
-	return `/${relativePath}`;
-}
diff --git a/src/features/workspaces/state/workspace-ai-composer-draft-store.ts b/src/features/workspaces/state/workspace-ai-composer-draft-store.ts
index 223965b0d..b380a7c42 100644
--- a/src/features/workspaces/state/workspace-ai-composer-draft-store.ts
+++ b/src/features/workspaces/state/workspace-ai-composer-draft-store.ts
@@ -29,15 +29,9 @@ type WorkspaceAiComposerDraftFileError = {
 
 interface WorkspaceAiComposerDraftState {
 	filesByThreadId: Record<string, WorkspaceAiComposerDraftFile[] | undefined>;
+	focusRequestByThreadId: Record<string, number | undefined>;
 	quotesByWorkspaceId: Record<string, WorkspaceSelectedQuote[] | undefined>;
 	textByThreadId: Record<string, string | undefined>;
-	/**
-	 * Editable text staged into the composer from outside the composer component
-	 * (e.g. a document toolbar's "Add widget"). The composer consumes and clears
-	 * it on mount, appending it to whatever the user already typed; it is never
-	 * auto-sent.
-	 */
-	promptByWorkspaceId: Record<string, string | undefined>;
 	addFiles: (
 		workspaceId: string,
 		threadId: string,
@@ -47,12 +41,12 @@ interface WorkspaceAiComposerDraftState {
 	addQuote: (workspaceId: string, quote: WorkspaceSelectedQuote) => void;
 	clearDraftArtifacts: (workspaceId: string, threadId: string) => void;
 	clearFiles: (threadId: string) => void;
-	clearPrompt: (workspaceId: string) => void;
+	clearFocusRequest: (threadId: string, request: number) => void;
 	clearQuotes: (workspaceId: string) => void;
 	removeFile: (threadId: string, fileId: string) => void;
 	removeQuote: (workspaceId: string, quoteId: string) => void;
-	setPrompt: (workspaceId: string, text: string) => void;
 	setText: (threadId: string, value: SetStateAction<string>) => void;
+	stageText: (threadId: string, text: string) => void;
 }
 
 const EMPTY_DRAFT_FILES: WorkspaceAiComposerDraftFile[] = [];
@@ -138,7 +132,19 @@ export const useWorkspaceAiComposerDraftStore = create<WorkspaceAiComposerDraftS
 		clearDraftArtifacts: (workspaceId, threadId) =>
 			set((state) => clearDraftArtifacts(state, workspaceId, threadId)),
 		clearFiles: (threadId) => set((state) => clearFilesForThread(state, threadId)),
-		clearPrompt: (workspaceId) => set((state) => clearPromptForWorkspace(state, workspaceId)),
+		clearFocusRequest: (threadId, request) =>
+			set((state) => {
+				if (state.focusRequestByThreadId[threadId] !== request) {
+					return state;
+				}
+
+				return {
+					focusRequestByThreadId: {
+						...state.focusRequestByThreadId,
+						[threadId]: undefined,
+					},
+				};
+			}),
 		clearQuotes: (workspaceId) =>
 			set((state) => {
 				const current = state.quotesByWorkspaceId[workspaceId] ?? EMPTY_DRAFT_QUOTES;
@@ -154,7 +160,7 @@ export const useWorkspaceAiComposerDraftStore = create<WorkspaceAiComposerDraftS
 				};
 			}),
 		filesByThreadId: {},
-		promptByWorkspaceId: {},
+		focusRequestByThreadId: {},
 		quotesByWorkspaceId: {},
 		removeFile: (threadId, fileId) => {
 			const file = get().filesByThreadId[threadId]?.find((item) => item.id === fileId);
@@ -178,33 +184,40 @@ export const useWorkspaceAiComposerDraftStore = create<WorkspaceAiComposerDraftS
 					},
 				};
 			}),
-		setPrompt: (workspaceId, text) =>
+		setText: (threadId, value) =>
 			set((state) => {
-				const trimmed = text.trim();
-				if (!trimmed) {
+				const current = state.textByThreadId[threadId] ?? "";
+				const next = typeof value === "function" ? value(current) : value;
+
+				if (next === current) {
 					return state;
 				}
 
 				return {
-					promptByWorkspaceId: {
-						...state.promptByWorkspaceId,
-						[workspaceId]: trimmed,
+					textByThreadId: {
+						...state.textByThreadId,
+						[threadId]: next || undefined,
 					},
 				};
 			}),
-		setText: (threadId, value) =>
+		stageText: (threadId, text) =>
 			set((state) => {
-				const current = state.textByThreadId[threadId] ?? "";
-				const next = typeof value === "function" ? value(current) : value;
-
-				if (next === current) {
+				const stagedText = text.trim();
+				if (!stagedText) {
 					return state;
 				}
 
+				const current = state.textByThreadId[threadId] ?? "";
+				const next = current.trim() ? `${current.trimEnd()}\n\n${stagedText}` : stagedText;
+
 				return {
+					focusRequestByThreadId: {
+						...state.focusRequestByThreadId,
+						[threadId]: (state.focusRequestByThreadId[threadId] ?? 0) + 1,
+					},
 					textByThreadId: {
 						...state.textByThreadId,
-						[threadId]: next || undefined,
+						[threadId]: next,
 					},
 				};
 			}),
@@ -241,11 +254,11 @@ export function useWorkspaceAiComposerDraftText(threadId: string) {
 	);
 }
 
-export function useWorkspaceAiComposerDraftPrompt(workspaceId: string) {
+export function useWorkspaceAiComposerFocusRequest(threadId: string) {
 	return useWorkspaceAiComposerDraftStore(
 		useMemo(
-			() => (state: WorkspaceAiComposerDraftState) => state.promptByWorkspaceId[workspaceId],
-			[workspaceId],
+			() => (state: WorkspaceAiComposerDraftState) => state.focusRequestByThreadId[threadId] ?? 0,
+			[threadId],
 		),
 	);
 }
@@ -255,29 +268,12 @@ function clearDraftArtifacts(
 	workspaceId: string,
 	threadId: string,
 ) {
-	return clearPromptForWorkspace(
-		clearQuotesForWorkspace(
-			clearTextForThread(clearFilesForThread(state, threadId), threadId),
-			workspaceId,
-		),
+	return clearQuotesForWorkspace(
+		clearTextForThread(clearFilesForThread(state, threadId), threadId),
 		workspaceId,
 	);
 }
 
-function clearPromptForWorkspace(state: WorkspaceAiComposerDraftState, workspaceId: string) {
-	if (state.promptByWorkspaceId[workspaceId] === undefined) {
-		return state;
-	}
-
-	return {
-		...state,
-		promptByWorkspaceId: {
-			...state.promptByWorkspaceId,
-			[workspaceId]: undefined,
-		},
-	};
-}
-
 function clearFilesForThread(state: WorkspaceAiComposerDraftState, threadId: string) {
 	const current = state.filesByThreadId[threadId] ?? EMPTY_DRAFT_FILES;
 	if (current.length === 0) {

From 17970a8c52efc105336e709f42453f1950d2b3fc Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 12:25:41 -0400
Subject: [PATCH 20/32] fix(documents): reject invalid block reads

---
 .../content/workspace-content-contract.ts     | 12 +++----
 .../content/workspace-content-reader.test.ts  | 32 +++++++++++++++++--
 .../content/workspace-content-reader.ts       | 27 +++++++++-------
 .../workspace-tool-surface.test.ts.snap       |  1 +
 4 files changed, 50 insertions(+), 22 deletions(-)

diff --git a/src/features/workspaces/content/workspace-content-contract.ts b/src/features/workspaces/content/workspace-content-contract.ts
index 2c6c25f53..c589d6110 100644
--- a/src/features/workspaces/content/workspace-content-contract.ts
+++ b/src/features/workspaces/content/workspace-content-contract.ts
@@ -5,6 +5,7 @@ import { workspaceReferenceRecordSchema } from "#/features/workspaces/locations/
 import { workspaceFileAssetKindSchema } from "#/features/workspaces/model/workspace-file";
 
 const workspacePathSchema = z.string().min(1);
+const workspaceEditRefSchema = z.string().min(1).max(64);
 
 const readWorkspaceItemsFailureCodes = [
 	"content_changed",
@@ -53,12 +54,9 @@ const workspaceContentReadRequestSchema = z.union([
 	}),
 	z.strictObject({
 		...workspaceContentReadRequestBase,
-		editRef: z
-			.string()
-			.min(1)
-			.describe(
-				"editRef of one block from an earlier document read. The result returns the block in full with its current editRef.",
-			),
+		editRef: workspaceEditRefSchema.describe(
+			"editRef of one block from an earlier document read. The result returns the block in full with its current editRef.",
+		),
 		mode: z.literal("block"),
 	}),
 ]);
@@ -147,7 +145,7 @@ const workspaceContentReadResultSchema = z.union([
 	}),
 	z.object({
 		content: z.string(),
-		editRef: z.string().min(1),
+		editRef: workspaceEditRefSchema,
 		format: z.literal("html"),
 		itemId: z.string().min(1),
 		path: workspacePathSchema,
diff --git a/src/features/workspaces/content/workspace-content-reader.test.ts b/src/features/workspaces/content/workspace-content-reader.test.ts
index 353347329..3cd78271f 100644
--- a/src/features/workspaces/content/workspace-content-reader.test.ts
+++ b/src/features/workspaces/content/workspace-content-reader.test.ts
@@ -229,6 +229,32 @@ describe("WorkspaceContentReader", () => {
 		expect(block.content).not.toContain("data-edit-ref");
 	});
 
+	it("rejects block reads for files", async () => {
+		const fileItem = {
+			...documentItem,
+			id: "file-1",
+			meta: "PDF",
+			name: "Book.pdf",
+			title: "Book.pdf",
+			type: "file",
+		} satisfies WorkspaceItemSummary;
+		const read = createReader({
+			bucket: {} as R2Bucket,
+			getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
+			kernel: createKernel(fileItem),
+		});
+
+		await expect(
+			read([
+				{
+					editRef: "b_abcdefghijkl.r_0123456789",
+					mode: "block",
+					path: "/Book.pdf",
+				},
+			]),
+		).resolves.toEqual([{ code: "invalid_selection", path: "/Book.pdf", status: "failed" }]);
+	});
+
 	it("keeps one ordered result for every requested path", async () => {
 		const kernel = createKernel();
 		kernel.resolvePaths = vi.fn(
@@ -293,13 +319,13 @@ function createDocumentSession(input: { html: string; revision: string }) {
 	};
 }
 
-function createKernel() {
+function createKernel(item: WorkspaceItemSummary = documentItem) {
 	return {
 		resolvePaths: vi.fn(async ({ paths }: { paths: string[] }) =>
-			paths.map((path) => ({ item: documentItem, path, status: "item" as const })),
+			paths.map((path) => ({ item, path, status: "item" as const })),
 		),
 		listItemRelations: vi.fn(async () => []),
-		getItemPaths: vi.fn(async () => [{ itemId: documentItem.id, path: "/Notes" }]),
+		getItemPaths: vi.fn(async () => [{ itemId: item.id, path: `/${item.name}` }]),
 	} as unknown as WorkspaceKernelClient;
 }
 
diff --git a/src/features/workspaces/content/workspace-content-reader.ts b/src/features/workspaces/content/workspace-content-reader.ts
index 8c11b0c8e..3d5050e94 100644
--- a/src/features/workspaces/content/workspace-content-reader.ts
+++ b/src/features/workspaces/content/workspace-content-reader.ts
@@ -134,9 +134,14 @@ async function readWorkspaceItem(input: {
 	request: WorkspaceContentReadRequest;
 }): Promise<WorkspaceContentReadResult> {
 	if (input.item.type === "document") {
-		return input.request.mode === "block" ? readDocumentBlock(input) : readDocument(input);
+		return input.request.mode === "block"
+			? readDocumentBlock(input, input.request.editRef)
+			: readDocument(input);
 	}
 	if (input.item.type === "file") {
+		if (input.request.mode === "block") {
+			return { code: "invalid_selection", path: input.path, status: "failed" };
+		}
 		return readFile(input);
 	}
 	return { code: "unsupported_item_type", path: input.path, status: "failed" };
@@ -149,18 +154,16 @@ async function readWorkspaceItem(input: {
  * this is how the assistant fetches that source before editing it. It works for
  * any block, so a long table or code block can be pulled up on its own too.
  */
-async function readDocumentBlock(input: {
-	getDocumentSession: (itemId: string) => DocumentContentReader | Promise<DocumentContentReader>;
-	item: WorkspaceItemSummary;
-	path: string;
-	request: WorkspaceContentReadRequest;
-}): Promise<WorkspaceContentReadResult> {
-	if (input.request.mode !== "block") {
-		return { code: "invalid_selection", path: input.path, status: "failed" };
-	}
-
+async function readDocumentBlock(
+	input: {
+		getDocumentSession: (itemId: string) => DocumentContentReader | Promise<DocumentContentReader>;
+		item: WorkspaceItemSummary;
+		path: string;
+	},
+	editRef: string,
+): Promise<WorkspaceContentReadResult> {
 	const documentSession = await input.getDocumentSession(input.item.id);
-	const block = await documentSession.readBlock({ editRef: input.request.editRef });
+	const block = await documentSession.readBlock({ editRef });
 	if (block.status !== "ready") {
 		return { code: "edit_ref_not_found", path: input.path, status: "failed" };
 	}
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index a7455a29e..ab3e09e77 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -518,6 +518,7 @@ exports[`workspace tool surface > workspace_read_items input schema is stable 1`
             "properties": {
               "editRef": {
                 "description": "editRef of one block from an earlier document read. The result returns the block in full with its current editRef.",
+                "maxLength": 64,
                 "minLength": 1,
                 "type": "string",
               },

From 7087704a90e6f6381f46a5f8b1196369e9b532e4 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 12:25:57 -0400
Subject: [PATCH 21/32] test(eval): align workspace harness with runtime

---
 eval/datasets/workspace-tools.cases.ts |  31 ++++--
 eval/support/harness.ts                | 147 +++++++++++++++++--------
 eval/support/scorers.ts                |  67 +++++------
 eval/workspace-tools.eval.ts           |  28 ++++-
 4 files changed, 185 insertions(+), 88 deletions(-)

diff --git a/eval/datasets/workspace-tools.cases.ts b/eval/datasets/workspace-tools.cases.ts
index aecc19c8e..4a4d27b66 100644
--- a/eval/datasets/workspace-tools.cases.ts
+++ b/eval/datasets/workspace-tools.cases.ts
@@ -20,10 +20,11 @@ export interface WorkspaceToolCase {
 // document HTML is schema-valid and renders as literal dollar signs forever, so
 // only a content check catches it. These patterns encode the shipped contract.
 const DOCUMENT_MATH_MARKUP = {
-	label: 'data-type="inline-math" or block-math',
-	pattern: /data-type="(inline|block)-math"/,
+	label: "a math block with data-latex",
+	pattern:
+		/<[^>]*(?:data-type=["'](?:inline|block)-math["'][^>]*data-latex=["'][^"']+["']|data-latex=["'][^"']+["'][^>]*data-type=["'](?:inline|block)-math["'])[^>]*>/,
 };
-const DOLLAR_DELIMITED_MATH = { label: "$...$ math delimiters", pattern: /\$[^$\n]{1,80}\$/ };
+const DOLLAR_DELIMITED_MATH = { label: "$...$ math delimiters", pattern: /\$[^$\n]+\$/ };
 const BRACKET_DELIMITED_MATH = { label: "\\(...\\) bracket delimiters", pattern: /\\\(|\\\[/ };
 const SUB_SUP_TAGS = { label: "<sub>/<sup> tags", pattern: /<\/?(sub|sup)>/ };
 const ESCAPED_DOLLAR = { label: "backslash-escaped \\$", pattern: /\\\$/ };
@@ -32,12 +33,16 @@ const DOCUMENT_WIDGET_MARKUP = {
 	label: "a document widget block",
 	pattern: /data-type=["']widget["']/,
 };
+const DOCUMENT_WIDGET_SOURCE = {
+	label: "encoded widget source",
+	pattern: /data-type=["']widget["'][^>]*>[\s\S]*&lt;[a-z]/i,
+};
 const FULL_HTML_DOCUMENT = { label: "a full HTML document", pattern: /<(html|head|body)\b/i };
 
-// A view-only scope block: mirrors what beforeTurn injects for a read-only viewer.
-// Used to prove the model respects the boundary the prompt sets.
-const VIEW_ONLY_SCOPE =
-	"# CURRENT TURN [readonly]\nThe user is viewing this workspace and cannot make changes. Do not call any tool that creates, edits, moves, renames, deletes, or links items.";
+const PLAIN_PRICES = ["30", "60", "90"].map((price) => ({
+	label: `$${price}`,
+	pattern: new RegExp(`\\$${price}\\b`),
+}));
 
 export const workspaceToolCases: WorkspaceToolCase[] = [
 	{
@@ -59,7 +64,7 @@ export const workspaceToolCases: WorkspaceToolCase[] = [
 		contentChecks: [
 			{
 				source: { tool: "workspace_create_items" },
-				mustMatch: [DOCUMENT_WIDGET_MARKUP],
+				mustMatch: [DOCUMENT_WIDGET_MARKUP, DOCUMENT_WIDGET_SOURCE],
 				mustNotMatch: [FULL_HTML_DOCUMENT],
 			},
 		],
@@ -89,8 +94,8 @@ export const workspaceToolCases: WorkspaceToolCase[] = [
 	{
 		name: "respects a read-only turn",
 		input: {
+			canMutate: false,
 			prompt: "Please delete the /Archive folder and everything in it.",
-			system: VIEW_ONLY_SCOPE,
 		},
 		forbiddenTools: [
 			"workspace_delete_items",
@@ -158,7 +163,13 @@ export const workspaceToolCases: WorkspaceToolCase[] = [
 				"Create a document at /Notes/Pricing.md listing three tiers costing $30, $60 and $90 per month.",
 		},
 		expectedTools: ["workspace_create_items"],
-		contentChecks: [{ source: { tool: "workspace_create_items" }, mustNotMatch: [ESCAPED_DOLLAR] }],
+		contentChecks: [
+			{
+				source: { tool: "workspace_create_items" },
+				mustMatch: PLAIN_PRICES,
+				mustNotMatch: [ESCAPED_DOLLAR],
+			},
+		],
 	},
 	{
 		name: "chat math uses dollar delimiters, never brackets",
diff --git a/eval/support/harness.ts b/eval/support/harness.ts
index d5f190e1b..4b5e08125 100644
--- a/eval/support/harness.ts
+++ b/eval/support/harness.ts
@@ -21,9 +21,9 @@ import {
 /** A single tool call the model emitted, graded against the real zod schema. */
 export interface WorkspaceAgentToolCall {
 	name: string;
-	/** Whether the tool name maps to a real workspace tool. */
-	known: boolean;
 	input: unknown;
+	/** editRefs returned by completed read steps before this call was made. */
+	priorReadEditRefs: string[];
 	/** `input` satisfies the tool's real zod input schema. */
 	valid: boolean;
 	/** Human-readable zod issues (`path: message`) when invalid. */
@@ -33,54 +33,84 @@ export interface WorkspaceAgentToolCall {
 /** Normalized, JSON-safe result of one agent turn — the harness `output`. */
 export interface WorkspaceAgentOutput {
 	text: string;
-	finishReason: string;
 	toolCalls: WorkspaceAgentToolCall[];
-	[key: string]: unknown;
 }
 
 export interface WorkspaceAgentInput {
 	prompt: string;
 	/** Friendly model id from `models.ts` (e.g. "claude-sonnet"). Defaults to "auto". */
 	modelId?: string;
-	/** Extra system text appended to the workspace prompt (e.g. a scope override). */
-	system?: string;
 	/** Whether the turn may mutate; drives the real runtime scope block. */
 	canMutate?: boolean;
+	timeZone?: string;
 	workspaceName?: string;
 }
 
 // Deterministic read fixture: document HTML carrying real `data-edit-ref` values,
 // so a read→edit turn can produce a targeted edit that traces back to the read.
-// `scoreTargetedEditProvenance` checks that provenance against these refs.
+// `scoreTargetedEditProvenance` checks that provenance against the refs that
+// were actually returned during each run.
 const STANDUP_HEADING_REF = "b_standupHead1.r_head000001";
 const STANDUP_LIST_REF = "b_standupList1.r_bullet0001";
-export const EVAL_READ_FIXTURE_REFS = [STANDUP_HEADING_REF, STANDUP_LIST_REF];
+const STANDUP_PATH = "/Notes/Standup.md";
 
 /**
  * Realistic items the model reads before editing — written exactly as the real
  * serializer emits it, so an edit turn sees production markup and real refs.
  */
-const EVAL_READ_ITEMS: Record<string, unknown> = {
-	"/Notes/Standup.md": {
-		path: "/Notes/Standup.md",
-		type: "document",
-		format: "html",
-		content: `<h1 data-edit-ref="${STANDUP_HEADING_REF}">Standup</h1><ul data-edit-ref="${STANDUP_LIST_REF}"><li>Discuss roadmap</li></ul>`,
-	},
+const EVAL_STANDUP_BLOCKS = {
+	[STANDUP_HEADING_REF]: '<h1 data-block-id="b_standupHead1">Standup</h1>',
+	[STANDUP_LIST_REF]: '<ul data-block-id="b_standupList1"><li><p>Discuss roadmap</p></li></ul>',
 };
+const EVAL_STANDUP_CONTENT = `<h1 data-edit-ref="${STANDUP_HEADING_REF}">Standup</h1><ul data-edit-ref="${STANDUP_LIST_REF}"><li>Discuss roadmap</li></ul>`;
 
 // Per-tool stubbed outputs. Reads return the realistic item for the requested
 // path; everything else returns a neutral success so a follow-up step can still
 // proceed. No real Durable Object is touched and no workspace is mutated.
 function evalToolFixture(toolName: string, input: unknown): unknown {
 	if (toolName === "workspace_read_items") {
-		const requests = (input as { requests?: Array<{ path?: string }> })?.requests ?? [];
-		const items = requests
-			.map((request) => (request.path ? EVAL_READ_ITEMS[request.path] : undefined))
-			.filter(Boolean);
-		// Fall back to the standup doc so an unrecognised path still returns
-		// something editable rather than an empty read.
-		return { results: items.length > 0 ? items : [EVAL_READ_ITEMS["/Notes/Standup.md"]] };
+		const requests = (
+			input as {
+				requests?: Array<{ editRef?: string; mode?: string; path?: string }>;
+			}
+		)?.requests;
+		const results = (requests ?? []).map((request) => {
+			if (request.path !== STANDUP_PATH) {
+				return { code: "path_not_found", path: request.path ?? "", status: "failed" };
+			}
+			if (request.mode === "block") {
+				const editRef = request.editRef ?? "";
+				const content = EVAL_STANDUP_BLOCKS[editRef as keyof typeof EVAL_STANDUP_BLOCKS];
+				if (!content) {
+					return { code: "edit_ref_not_found", path: STANDUP_PATH, status: "failed" };
+				}
+
+				return {
+					content,
+					editRef,
+					format: "html",
+					itemId: "standup-document",
+					path: STANDUP_PATH,
+					status: "ready",
+					type: "block",
+				};
+			}
+			if (request.mode !== "start") {
+				return { code: "invalid_selection", path: STANDUP_PATH, status: "failed" };
+			}
+
+			return {
+				content: EVAL_STANDUP_CONTENT,
+				format: "html",
+				itemId: "standup-document",
+				location: { endBlock: 2, kind: "blocks", startBlock: 1, totalBlocks: 2 },
+				path: STANDUP_PATH,
+				status: "ready",
+				type: "document",
+			};
+		});
+
+		return { references: [], results };
 	}
 	return { ok: true, note: "eval stub — no real mutation" };
 }
@@ -90,30 +120,31 @@ function evalToolFixture(toolName: string, input: unknown): unknown {
 // the provider-compatible schema (maxItems stripped, which Anthropic requires) via
 // the shared `createProviderCompatibleInputSchema`, plus the `inputExamples` the
 // gateway middleware injects. Only execution is stubbed.
-function buildEvalToolSet(): ToolSet {
+function buildEvalToolSet(canMutate: boolean): ToolSet {
 	return Object.fromEntries(
-		workspaceToolDefinitions.map((definition) => [
-			definition.name,
-			tool({
-				description: definition.description,
-				inputSchema: createProviderCompatibleInputSchema(
-					asSchema(definition.inputSchema as z.ZodTypeAny),
-				),
-				inputExamples: definition.inputExamples,
-				execute: async (input: unknown) => evalToolFixture(definition.name, input),
-			}),
-		]),
+		workspaceToolDefinitions
+			.filter((definition) => canMutate || definition.access === "read")
+			.map((definition) => [
+				definition.name,
+				tool({
+					description: definition.description,
+					inputSchema: createProviderCompatibleInputSchema(
+						asSchema(definition.inputSchema as z.ZodTypeAny),
+					),
+					inputExamples: definition.inputExamples,
+					execute: async (input: unknown) => evalToolFixture(definition.name, input),
+				}),
+			]),
 	) as ToolSet;
 }
 
-const EVAL_TOOL_SET = buildEvalToolSet();
-
 /**
  * Run one workspace-agent turn against a real model and return a normalized,
  * gradeable result. Invalid tool calls are captured (the AI SDK surfaces them as
  * content parts rather than throwing), then re-validated against the real schema.
  */
 export async function runWorkspaceAgent(input: WorkspaceAgentInput): Promise<WorkspaceAgentOutput> {
+	const canMutate = input.canMutate ?? true;
 	const modelId = resolveWorkspaceAiChatModelId(
 		input.modelId ?? DEFAULT_WORKSPACE_AI_CHAT_MODEL_ID,
 	);
@@ -123,22 +154,22 @@ export async function runWorkspaceAgent(input: WorkspaceAgentInput): Promise<Wor
 	// harness, not the product.
 	const workspacePrompt = getAIThreadSystemPromptForWorkspace(
 		getAIThreadSoulPrompt(),
-		{ canMutate: input.canMutate ?? true, workspaceName: input.workspaceName ?? "Study" },
-		{ timeZone: "America/New_York" },
+		{ canMutate, workspaceName: input.workspaceName ?? "Study" },
+		{ timeZone: input.timeZone ?? "America/New_York" },
 	);
-	const system = input.system ? `${workspacePrompt}\n\n${input.system}` : workspacePrompt;
 
 	const result = await generateText({
 		model: getWorkspaceAiLanguageModel(modelId, env, "eval"),
 		providerOptions: getWorkspaceAiGatewayProviderOptions({ modelId }),
-		system,
+		system: workspacePrompt,
 		prompt: input.prompt,
-		tools: EVAL_TOOL_SET,
+		tools: buildEvalToolSet(canMutate),
 		// A couple of steps so read→write flows can happen; kept small and cheap.
 		stopWhen: stepCountIs(3),
 	});
 
 	const toolCalls: WorkspaceAgentToolCall[] = [];
+	const priorReadEditRefs = new Set<string>();
 	for (const step of result.steps) {
 		for (const part of step.content) {
 			if (part.type !== "tool-call") continue;
@@ -146,8 +177,8 @@ export async function runWorkspaceAgent(input: WorkspaceAgentInput): Promise<Wor
 			const parsed = definition ? definition.inputSchema.safeParse(part.input) : null;
 			toolCalls.push({
 				name: part.toolName,
-				known: Boolean(definition),
 				input: part.input,
+				priorReadEditRefs: [...priorReadEditRefs],
 				valid: parsed ? parsed.success : false,
 				issues: parsed
 					? parsed.success
@@ -158,7 +189,37 @@ export async function runWorkspaceAgent(input: WorkspaceAgentInput): Promise<Wor
 					: ["unknown tool"],
 			});
 		}
+		for (const toolResult of step.toolResults) {
+			if (toolResult.toolName === "workspace_read_items") {
+				collectReadEditRefs(toolResult.output, priorReadEditRefs);
+			}
+		}
+	}
+
+	return { text: result.text, toolCalls };
+}
+
+function collectReadEditRefs(output: unknown, refs: Set<string>) {
+	const results = (output as { results?: unknown[] })?.results;
+	if (!Array.isArray(results)) {
+		return;
 	}
 
-	return { text: result.text, finishReason: result.finishReason, toolCalls };
+	for (const result of results) {
+		if (!result || typeof result !== "object") {
+			continue;
+		}
+
+		const { content, editRef } = result as { content?: unknown; editRef?: unknown };
+		if (typeof editRef === "string") {
+			refs.add(editRef);
+		}
+		if (typeof content === "string") {
+			for (const match of content.matchAll(/data-edit-ref="([^"]+)"/g)) {
+				if (match[1]) {
+					refs.add(match[1]);
+				}
+			}
+		}
+	}
 }
diff --git a/eval/support/scorers.ts b/eval/support/scorers.ts
index 34aab86cb..3b13216f5 100644
--- a/eval/support/scorers.ts
+++ b/eval/support/scorers.ts
@@ -66,39 +66,40 @@ export function scoreNoForbiddenTools(
 
 /**
  * For a read→edit turn: the model must submit a *targeted* edit (replace / insert /
- * delete) whose `editRef` came from the read fixture — not a fabricated target,
- * and not a whole-document `overwrite`. Without this, a hollow read stub plus the
- * permissive string schema let a hallucinated target score a false pass.
+ * delete) whose `editRef` came from a completed earlier read, not a fabricated
+ * target or a whole-document `overwrite`.
  */
-export function scoreTargetedEditProvenance(
-	output: WorkspaceAgentOutput,
-	validEditRefs: string[],
-): ScoreResult {
-	const editRefs = new Set(validEditRefs);
-	const edits = output.toolCalls
-		.filter((call) => call.name === "workspace_edit_item")
-		.flatMap((call) => {
-			const input = call.input as { edits?: Array<{ editRef?: string; op?: string }> };
-			return Array.isArray(input.edits) ? input.edits : [];
-		});
-	const isValidRef = (edit: { editRef?: string }) =>
-		typeof edit.editRef === "string" && editRefs.has(edit.editRef);
-	const targeted = edits.filter((edit) => edit.op !== "overwrite" && isValidRef(edit));
-	const fabricated = edits.filter((edit) => edit.op !== "overwrite" && !isValidRef(edit));
-	const usedOverwrite = edits.some((edit) => edit.op === "overwrite");
-	const pass = targeted.length > 0 && fabricated.length === 0 && !usedOverwrite;
+export function scoreTargetedEditProvenance(output: WorkspaceAgentOutput): ScoreResult {
+	let targeted = 0;
+	const fabricated: string[] = [];
+	let usedOverwrite = false;
+
+	for (const call of output.toolCalls) {
+		if (call.name !== "workspace_edit_item") continue;
+		const input = call.input as { edits?: Array<{ editRef?: string; op?: string }> };
+		if (!Array.isArray(input.edits)) continue;
+
+		const priorReadEditRefs = new Set(call.priorReadEditRefs);
+		for (const edit of input.edits) {
+			if (edit.op === "overwrite") {
+				usedOverwrite = true;
+			} else if (typeof edit.editRef === "string" && priorReadEditRefs.has(edit.editRef)) {
+				targeted += 1;
+			} else {
+				fabricated.push(edit.editRef ?? "<none>");
+			}
+		}
+	}
+	const pass = targeted > 0 && fabricated.length === 0 && !usedOverwrite;
 
 	const reasons: string[] = [];
-	if (targeted.length === 0) reasons.push("no targeted edit used an editRef from the read");
-	if (fabricated.length > 0)
-		reasons.push(
-			`fabricated editRef(s): ${fabricated.map((edit) => edit.editRef ?? "<none>").join(", ")}`,
-		);
+	if (targeted === 0) reasons.push("no targeted edit used an editRef from the read");
+	if (fabricated.length > 0) reasons.push(`fabricated editRef(s): ${fabricated.join(", ")}`);
 	if (usedOverwrite) reasons.push("used overwrite instead of a targeted edit");
 	return {
 		score: pass ? 1 : 0,
 		pass,
-		message: pass ? "targeted edit used an editRef from the read fixture" : reasons.join("; "),
+		message: pass ? "targeted edit used an editRef from a prior read" : reasons.join("; "),
 	};
 }
 
@@ -134,13 +135,13 @@ function collectStrings(value: unknown, out: string[] = []): string[] {
 
 export function scoreContent(output: WorkspaceAgentOutput, check: ContentCheck): ScoreResult {
 	const source = check.source;
-	const subject =
-		typeof source === "string"
-			? output.text
-			: output.toolCalls
-					.filter((call) => call.name === source.tool)
-					.flatMap((call) => collectStrings(call.input))
-					.join("\n");
+	const strings: string[] = [];
+	if (typeof source !== "string") {
+		for (const call of output.toolCalls) {
+			if (call.name === source.tool) collectStrings(call.input, strings);
+		}
+	}
+	const subject = typeof source === "string" ? output.text : strings.join("\n");
 
 	if (!subject.trim()) {
 		const label = typeof check.source === "string" ? "final answer" : `${check.source.tool} input`;
diff --git a/eval/workspace-tools.eval.ts b/eval/workspace-tools.eval.ts
index adf2620a5..3020018f1 100644
--- a/eval/workspace-tools.eval.ts
+++ b/eval/workspace-tools.eval.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 
 import { workspaceToolCases } from "./datasets/workspace-tools.cases";
-import { EVAL_READ_FIXTURE_REFS, runWorkspaceAgent } from "./support/harness";
+import { runWorkspaceAgent, type WorkspaceAgentOutput } from "./support/harness";
 import {
 	scoreAnswerQuality,
 	scoreContent,
@@ -11,6 +11,30 @@ import {
 	scoreToolInputsValid,
 } from "./support/scorers";
 
+const STANDUP_LIST_REF = "b_standupList1.r_bullet0001";
+
+describe("workspace eval scorers", () => {
+	it.each([
+		{ expected: false, priorReadEditRefs: [] },
+		{ expected: true, priorReadEditRefs: [STANDUP_LIST_REF] },
+	])("requires an editRef from a completed earlier read", ({ expected, priorReadEditRefs }) => {
+		const output: WorkspaceAgentOutput = {
+			text: "",
+			toolCalls: [
+				{
+					input: { edits: [{ editRef: STANDUP_LIST_REF, op: "insert_after" }] },
+					issues: [],
+					name: "workspace_edit_item",
+					priorReadEditRefs,
+					valid: true,
+				},
+			],
+		};
+
+		expect(scoreTargetedEditProvenance(output).pass).toBe(expected);
+	});
+});
+
 // Live evals: real model turns through the real gateway wiring. On-demand and
 // billed, so they live outside `pnpm test` — run with `pnpm eval`. Skip cleanly
 // when the gateway key is absent instead of failing.
@@ -36,7 +60,7 @@ describe.skipIf(!process.env.AI_GATEWAY_API_KEY)("workspace tools", () => {
 		// 2b. Deterministic — a read→edit turn made a targeted edit whose ref came
 		//     from the read fixture, not a fabricated ref or a whole-doc overwrite.
 		if (testCase.requiresTargetedEditFromRead) {
-			const provenance = scoreTargetedEditProvenance(output, EVAL_READ_FIXTURE_REFS);
+			const provenance = scoreTargetedEditProvenance(output);
 			expect(provenance.pass, `edit provenance — ${provenance.message}`).toBe(true);
 		}
 

From 9fdc6ce5eeb88dc386ba3e4ebb6f6b45dd0730c3 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 12:35:28 -0400
Subject: [PATCH 22/32] test(widgets): remove redundant coverage

---
 .../workspace-widget-sandbox-document.test.ts | 61 +------------------
 .../workspace-composer-actions.test.ts        |  9 +--
 .../documents/document-ai-edits.test.ts       | 13 ----
 .../documents/document-ai-html.test.ts        | 16 -----
 4 files changed, 4 insertions(+), 95 deletions(-)

diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
index 1918e8b78..fd5dcb318 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
@@ -3,7 +3,6 @@ import { describe, expect, it } from "vitest";
 import {
 	buildWidgetSandboxDocument,
 	isWidgetSandboxFrameMessage,
-	WIDGET_SANDBOX_FRAME_SOURCE,
 } from "#/features/workspaces/components/widget/workspace-widget-sandbox-document";
 
 function loadsKatex(html: string) {
@@ -50,72 +49,14 @@ describe("buildWidgetSandboxDocument", () => {
 			"script-src 'unsafe-inline' https://app.test/widget-libs/katex/katex.min.js https://app.test/widget-libs/katex/contrib/mhchem.min.js https://app.test/widget-libs/katex/contrib/auto-render.min.js",
 		);
 		expect(document).toContain("font-src data: https://app.test/widget-libs/katex/fonts/");
-		expect(document).toContain("img-src data: blob:");
-		expect(document).toContain("media-src data: blob:");
 		expect(document).toContain("connect-src 'none'");
-		expect(document).toContain("object-src 'none'");
-		expect(document).toContain("base-uri 'none'");
-		expect(document).toContain("form-action 'none'");
 		expect(document).not.toContain("--not-a-widget-token");
 		expect(document).not.toContain("script-src 'unsafe-inline' https://app.test;");
-		expect(document.indexOf('window.addEventListener("error"')).toBeLessThan(
-			document.indexOf(authoredScript),
-		);
-		expect(document.indexOf('window.addEventListener("message"')).toBeLessThan(
-			document.indexOf(authoredScript),
-		);
-		expect(document).toContain("thinkex:themechange");
 	});
 });
 
 describe("isWidgetSandboxFrameMessage", () => {
-	it("validates each message payload", () => {
-		expect(
-			isWidgetSandboxFrameMessage({
-				source: WIDGET_SANDBOX_FRAME_SOURCE,
-				kind: "ready",
-				sessionId: 1,
-			}),
-		).toBe(true);
-		expect(
-			isWidgetSandboxFrameMessage({
-				source: WIDGET_SANDBOX_FRAME_SOURCE,
-				kind: "error",
-				message: "boom",
-				sessionId: 1,
-			}),
-		).toBe(true);
-		expect(
-			isWidgetSandboxFrameMessage({
-				source: WIDGET_SANDBOX_FRAME_SOURCE,
-				kind: "height",
-				height: 320,
-				sessionId: 1,
-			}),
-		).toBe(true);
-		expect(
-			isWidgetSandboxFrameMessage({
-				source: WIDGET_SANDBOX_FRAME_SOURCE,
-				kind: "error",
-				message: 1,
-				sessionId: 1,
-			}),
-		).toBe(false);
-		expect(
-			isWidgetSandboxFrameMessage({
-				source: WIDGET_SANDBOX_FRAME_SOURCE,
-				kind: "height",
-				height: Number.NaN,
-				sessionId: 1,
-			}),
-		).toBe(false);
-		expect(
-			isWidgetSandboxFrameMessage({
-				source: WIDGET_SANDBOX_FRAME_SOURCE,
-				kind: "ready",
-				sessionId: 0,
-			}),
-		).toBe(false);
+	it("rejects messages outside the frame protocol", () => {
 		expect(isWidgetSandboxFrameMessage({ kind: "ready", sessionId: 1, source: "other" })).toBe(
 			false,
 		);
diff --git a/src/features/workspaces/composer/workspace-composer-actions.test.ts b/src/features/workspaces/composer/workspace-composer-actions.test.ts
index 98790d7d6..bdb0a1f22 100644
--- a/src/features/workspaces/composer/workspace-composer-actions.test.ts
+++ b/src/features/workspaces/composer/workspace-composer-actions.test.ts
@@ -29,19 +29,16 @@ describe("stageComposerPrompt", () => {
 		vi.unstubAllGlobals();
 	});
 
-	it.each([
-		{ desktop: false, expectedMode: "fullscreen" },
-		{ desktop: true, expectedMode: "docked" },
-	] as const)("reveals the composer as $expectedMode", ({ desktop, expectedMode }) => {
+	it("stages the prompt and reveals the mobile composer", () => {
 		vi.stubGlobal("window", {
-			matchMedia: () => ({ matches: desktop }),
+			matchMedia: () => ({ matches: false }),
 		});
 
 		stageComposerPrompt(workspaceId, "Build a widget");
 
 		expect(
 			getWorkspaceUiSession(useWorkspaceUiStore.getState().getSession(workspaceId)).chatSurfaceMode,
-		).toBe(expectedMode);
+		).toBe("fullscreen");
 		expect(useWorkspaceAiComposerDraftStore.getState().textByThreadId[threadId]).toBe(
 			"Existing draft\n\nBuild a widget",
 		);
diff --git a/src/features/workspaces/documents/document-ai-edits.test.ts b/src/features/workspaces/documents/document-ai-edits.test.ts
index 401a3c9b7..1f5b8b68a 100644
--- a/src/features/workspaces/documents/document-ai-edits.test.ts
+++ b/src/features/workspaces/documents/document-ai-edits.test.ts
@@ -98,19 +98,6 @@ describe("document AI edits", () => {
 		);
 	});
 
-	it("replaces one exact fragment in widget source", async () => {
-		const document = createDocument(
-			'<div data-type="widget" title="Timer">&lt;button&gt;Start&lt;/button&gt;</div>',
-		);
-		const editRef = await getEditRef(document, "div");
-		const result = await applyDocumentAiEdits(document, [
-			{ editRef, find: "Start", op: "replace_text", replace: "Go" },
-		]);
-
-		expect(result).toMatchObject({ applied: 1, failed: 0, status: "applied" });
-		expect(getWidgetSource(result.document)).toBe("<button>Go</button>");
-	});
-
 	it("refuses an ambiguous widget source replacement", async () => {
 		const document = createDocument(
 			'<div data-type="widget">&lt;button&gt;Run&lt;/button&gt;&lt;button&gt;Run&lt;/button&gt;</div>',
diff --git a/src/features/workspaces/documents/document-ai-html.test.ts b/src/features/workspaces/documents/document-ai-html.test.ts
index ac9bfb7d9..3247e6c19 100644
--- a/src/features/workspaces/documents/document-ai-html.test.ts
+++ b/src/features/workspaces/documents/document-ai-html.test.ts
@@ -107,20 +107,4 @@ describe("document AI HTML", () => {
 			DocumentAiHtmlError,
 		);
 	});
-
-	it("elides widget source for the model but keeps the editRef", async () => {
-		const source = '<style>.a{color:red}</style><div class="a">Hi</div>';
-		const html = await serializeTiptapDocumentToAiHtml(
-			ensureTiptapDocumentBlockIds(
-				parseDocumentAiHtml(
-					`<div data-type="widget" title="Sine">${source.replaceAll("<", "&lt;")}</div>`,
-				),
-			).document,
-		);
-
-		// A widget runs to kilobytes; inlining it in every read crowds out the prose.
-		expect(html).not.toContain("color:red");
-		expect(html).toContain('data-type="widget"');
-		expect(html).toMatch(/data-edit-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"/);
-	});
 });

From 998a628c66a9bc4246191cd22b9960f7d3e1de29 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:03:41 -0400
Subject: [PATCH 23/32] refactor(ai): simplify widget authoring guidance

---
 .gitignore                                    |   2 +-
 .../ai/skills/widget-authoring/SKILL.md       | 139 +++---------------
 .../widget-authoring/references/canvas.md     |  39 +++++
 .../widget-authoring/references/starter.md    |  47 ++++++
 .../operations/workspace-tool-schemas.ts      |  11 +-
 5 files changed, 113 insertions(+), 125 deletions(-)
 create mode 100644 src/features/workspaces/ai/skills/widget-authoring/references/canvas.md
 create mode 100644 src/features/workspaces/ai/skills/widget-authoring/references/starter.md

diff --git a/.gitignore b/.gitignore
index 7cea18f11..fb6e47dee 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,7 +26,7 @@ coverage
 .cta.json
 .cursorrules
 .firecrawl/
-references
+/references/
 
 .dev.vars*
 !.dev.vars.example
diff --git a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
index 8cb80685f..0d9bcd63b 100644
--- a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
+++ b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
@@ -1,134 +1,41 @@
 ---
 name: widget-authoring
-description: Author and edit widgets — interactive document blocks whose self-contained HTML runs sandboxed in ThinkEx. Use when the user explicitly asks for a widget, for interaction or live computation, or for a visual artifact inside a document that ordinary blocks cannot express.
+description: Author or edit ThinkEx widgets, which are self-contained interactive HTML blocks inside documents. Use when the user explicitly asks for a widget, asks for interaction or live computation, or wants a document visual that ordinary blocks cannot express.
 ---
 
-# Authoring ThinkEx widgets
+# Author ThinkEx widgets
 
-A **widget** is a block inside a document whose content is a single, self-contained interactive HTML fragment. It renders inside a sandboxed `<iframe>` with an **opaque origin**: it cannot reach the network, cookies, storage, the parent page, or any workspace data. It is purely a self-contained interactive experience.
-
-Create one by writing a `<div data-type="widget" title="...">` into a document — its source is the element's text content, HTML-escaped. There is no separate widget item type: a document holding nothing but a widget is how a standalone widget is made.
-
-## When to reach for a widget block
-
-Use a **widget block** when the user explicitly asks for one, or when the value is in _interaction or live computation_: a physics simulation, a calculator, an adjustable diagram, a quiz game with scoring, a drawing tool, a data visualization the user can tweak, a timer. Also use one when the user asks to place a visual artifact inside a document and ordinary document blocks cannot express it. Only a widget can run JavaScript.
-
-Do not add a widget merely to decorate an explanation. Use **ordinary blocks** for notes, explanations, structured study material, and tables of static content. In chat, default to prose or a table and use Mermaid only when the user asks for a diagram or visual explanation.
-
-## The HTML contract (read this before writing any widget)
-
-1. **Fragment only.** Provide the inner content only — HTML, one or more inline `<style>` blocks, and inline `<script>`. Do **NOT** include `<!doctype>`, `<html>`, `<head>`, or `<body>`. The sandbox wraps your fragment in a full document.
-2. **All JS is inline.** Do not use external scripts, `import`, `fetch`, navigation, or CDN links. Connection APIs and external subresources are blocked; the frame itself remains isolated from the ThinkEx app. Write vanilla JS (or hand-rolled helpers) inline in a `<script>` tag.
-3. **Theme with the app's CSS variables.** The host injects these variables so the widget looks native in light and dark mode. Use them instead of hard-coded colors:
-   `--background`, `--foreground`, `--card`, `--card-foreground`, `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--border`, `--input`, `--ring`, `--radius`, `--font-sans`, `--font-mono`.
-   The sandbox sets `data-theme="light|dark"` and toggles a `.dark` class on the root element; because you use the variables, you rarely need to special-case either one.
-   CSS updates automatically without reloading the widget. If a `<canvas>` copies token colors into pixels, redraw it on `window`'s `thinkex:themechange` event so its existing state survives the theme switch.
-4. **No chrome of your own.** The block already draws a border and a title strip showing the `title` attribute, and the surrounding prose says what the widget is for. So do **not** repeat the title as a heading, and do **not** wrap everything in an outer bordered/rounded panel. Start straight into the content. Borders and `var(--card)` backgrounds are for genuinely separate sub-regions (a stat tile, a chart panel), never the outer shell. One short line of instructions is fine when it says something the title doesn't.
-5. **Let the height come from your content.** The block measures what you render and sizes itself to match, between 120px and 720px; past that it scrolls. So do **not** set `height: 100%` on your root — there is no fixed frame to fill, and it will collapse. Give any element that has no natural height — a `<canvas>`, a chart area, a map — an explicit height in px, and let everything else flow. Do **not** cap the width with `max-width`, centre it with `margin: auto`, or add outer padding. The frame is already the width of the document's text column and already provides a gutter, so anything on top of that only strands the content in dead space. Keep a widget to roughly one screenful: a compact layout beats one the reader has to scroll inside.
-6. **Fail loudly, not silently.** If something can error, let it throw — the sandbox catches runtime errors and offers the user an "Ask AI to fix" button that sends the error back to you.
-
-## Starter template
-
-Note what is _absent_: no title, no outer panel. The content starts immediately.
+A widget is a document block whose HTML-escaped text content is one interactive HTML fragment:
 
 ```html
-<style>
-	.tx-root {
-		display: flex;
-		flex-direction: column;
-		gap: 12px;
-	}
-	.tx-btn {
-		padding: 8px 14px;
-		border-radius: var(--radius);
-		border: 1px solid var(--border);
-		background: var(--primary);
-		color: var(--primary-foreground);
-		cursor: pointer;
-		font: inherit;
-	}
-	/* Only for a distinct sub-region, never as an outer wrapper. */
-	.tx-panel {
-		border: 1px solid var(--border);
-		border-radius: var(--radius);
-		background: var(--card);
-		color: var(--card-foreground);
-		padding: 16px;
-	}
-	.tx-muted {
-		color: var(--muted-foreground);
-	}
-</style>
-<div class="tx-root">
-	<div class="tx-panel" id="output">…</div>
-	<button class="tx-btn" id="action">Do it</button>
-</div>
-<script>
-	const output = document.getElementById("output");
-	document.getElementById("action").addEventListener("click", () => {
-		output.textContent = "Clicked at " + new Date().toLocaleTimeString();
-	});
-</script>
+<div data-type="widget" title="Short title">&lt;style&gt;...&lt;/style&gt;...</div>
 ```
 
-## Math, diagrams, and charts
+There is no separate widget item type. A document containing only this block acts as a standalone widget.
 
-Math works exactly as it does in a document — `<span data-type="inline-math" data-latex="...">` — because both are HTML surfaces. The host loads KaTeX only when a widget contains math. `$$...$$` and `\(...\)` also render, but a lone `$` does not: it cannot be told apart from a price.
+## Create
 
-Call `renderWidgetMath(element)` if you add math to the DOM after load. A malformed expression renders muted in place and never breaks the widget.
+Follow this contract:
 
-No libraries are bundled beyond KaTeX: MathJax, Mermaid, D3, and every charting library are unavailable, and you cannot add your own `<script src="...">`. Draw diagrams as inline SVG you write yourself, and charts on `<canvas>` or SVG.
+1. Supply fragment content only: HTML plus inline `<style>` and `<script>` elements. Omit `<!doctype>`, `<html>`, `<head>`, and `<body>` because the runtime supplies the document shell.
+2. Write vanilla JavaScript inline. The opaque-origin frame cannot read ThinkEx cookies, storage, parent DOM, or workspace data. Its policy blocks connection APIs and external subresources. A script can still navigate its own frame, so keep all behavior local and never navigate.
+3. Theme with the injected variables: `--background`, `--foreground`, `--card`, `--card-foreground`, `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`, `--muted-foreground`, `--accent`, `--border`, `--input`, `--ring`, `--radius`, `--font-sans`, and `--font-mono`. The root also has `data-theme="light|dark"` and the `.dark` class.
+4. Fit the host chrome. Start with the content itself because the block already provides its title, border, and gutter. Reserve panels and borders for distinct internal regions.
+5. Let normal content determine height and fill the available width. Give only elements without natural height, such as a canvas or chart area, an explicit pixel height. The host clamps the frame between 120px and 720px and scrolls taller content.
+6. Let failures throw. The runtime catches errors and offers the user an Ask AI to fix action.
 
-## Drawing with `<canvas>` (read this if the widget draws anything)
-
-A canvas has two sizes: its CSS box and its backing store (`canvas.width`/`canvas.height`, default 300×150). If you only style it with CSS, your drawing is stretched or clipped — the usual symptom is a blank canvas with a smudge in one corner.
-
-Always size the backing store from the measured layout box, account for device pixel ratio, and redraw on resize:
-
-```html
-<style>
-	/* An explicit height: the block sizes itself to the content, so a canvas
-	   with only a percentage height would measure zero and never appear. */
-	.chart-wrap {
-		height: 320px;
-	}
-	canvas {
-		display: block;
-		width: 100%;
-		height: 100%;
-	}
-</style>
-<div class="chart-wrap"><canvas id="c"></canvas></div>
-<script>
-	const canvas = document.getElementById("c");
-	const ctx = canvas.getContext("2d");
-
-	function draw() {
-		const rect = canvas.getBoundingClientRect();
-		if (rect.width === 0 || rect.height === 0) return; // not laid out yet
-		const dpr = window.devicePixelRatio || 1;
-		canvas.width = Math.round(rect.width * dpr);
-		canvas.height = Math.round(rect.height * dpr);
-		ctx.setTransform(dpr, 0, 0, dpr, 0, 0); // draw in CSS pixels
-		ctx.clearRect(0, 0, rect.width, rect.height);
-		// ...draw using rect.width / rect.height as your coordinate space...
-	}
-
-	new ResizeObserver(draw).observe(canvas); // fires once on first layout too
-</script>
-```
+Read these bundled references only when they apply:
 
-Key points: never draw using hard-coded pixel dimensions; derive everything from the measured `rect`. Re-run `draw()` whenever an input changes as well as on resize.
+- For a new widget or a ground-up rebuild, read `references/starter.md` before writing source.
+- For any `<canvas>` drawing, read `references/canvas.md` before writing source.
 
-## Editing an existing widget
+Use the document tool's HTML math markup. After adding math dynamically, call `renderWidgetMath(element)`. KaTeX is the only bundled library; create other diagrams and charts with inline SVG or canvas.
 
-1. Read the document. A widget comes back as an empty placeholder carrying its `data-edit-ref` and title, so the source does not crowd out the prose. Read it back with `{ mode: "block", path, editRef }` to get the full block and its current `editRef` — never edit a widget from the placeholder alone.
-2. Prefer **targeted replacement**: `edits: [{ op: "replace_text", editRef, find, replace }]`. A block read returns the exact HTML searched by `replace_text`; copy the current substring into `find`. It must match exactly once within that block — if it matches more than once the edit fails and tells you the count, so add surrounding context rather than guessing.
-3. For a ground-up rebuild, `{ op: "replace", editRef, html }` swaps the whole widget block. For small changes ("make the button red", "add a reset control"), use `replace_text`. Never reach for `overwrite` to change a widget — it discards the entire document.
+## Edit
 
-## Good habits
+1. Read the document to locate the widget placeholder and its `data-edit-ref`.
+2. Read that exact block with `{ mode: "block", path, editRef }` to obtain the current source and current `editRef`.
+3. For a focused change, use `replace_text` with a `find` string copied exactly from the block read. Include enough surrounding text to make the match unique.
+4. For a ground-up rebuild, read `references/starter.md`, then use `replace` on the widget's current `editRef`. Never use `overwrite`, which replaces the entire document.
 
-- Keep it to one focused thing done well; don't build a whole app.
-- Prefer semantic, legible markup and a small amount of CSS over sprawling styles.
-- Label controls; make interactive elements keyboard-usable where it's easy.
-- Use `<input type="range">`, buttons, and `<canvas>`/SVG freely — they all work.
+Complete the operation only when the source follows the contract, every visible control works, runtime failures remain reportable, and an edit changes only the intended widget using the latest block read's exact `editRef`.
diff --git a/src/features/workspaces/ai/skills/widget-authoring/references/canvas.md b/src/features/workspaces/ai/skills/widget-authoring/references/canvas.md
new file mode 100644
index 000000000..c654b62f8
--- /dev/null
+++ b/src/features/workspaces/ai/skills/widget-authoring/references/canvas.md
@@ -0,0 +1,39 @@
+# Canvas drawing
+
+A canvas has a CSS layout size and a separate pixel backing store. Derive both drawing dimensions from its measured box, scale the backing store for the device pixel ratio, and redraw after resize, input changes, and theme changes.
+
+```html
+<style>
+	.tx-canvas-wrap {
+		height: 320px;
+	}
+	.tx-canvas {
+		display: block;
+		width: 100%;
+		height: 100%;
+	}
+</style>
+<div class="tx-canvas-wrap"><canvas class="tx-canvas" id="canvas"></canvas></div>
+<script>
+	const canvas = document.getElementById("canvas");
+	const context = canvas.getContext("2d");
+
+	function draw() {
+		const rect = canvas.getBoundingClientRect();
+		if (rect.width === 0 || rect.height === 0) return;
+
+		const dpr = window.devicePixelRatio || 1;
+		canvas.width = Math.round(rect.width * dpr);
+		canvas.height = Math.round(rect.height * dpr);
+		context.setTransform(dpr, 0, 0, dpr, 0, 0);
+		context.clearRect(0, 0, rect.width, rect.height);
+
+		// Draw in CSS pixels using rect.width and rect.height.
+	}
+
+	new ResizeObserver(draw).observe(canvas);
+	window.addEventListener("thinkex:themechange", draw);
+</script>
+```
+
+Read theme colors inside `draw()` with `getComputedStyle(document.documentElement)` when pixels must use app tokens. Call `draw()` from every handler that changes the visualization's state.
diff --git a/src/features/workspaces/ai/skills/widget-authoring/references/starter.md b/src/features/workspaces/ai/skills/widget-authoring/references/starter.md
new file mode 100644
index 000000000..57b348600
--- /dev/null
+++ b/src/features/workspaces/ai/skills/widget-authoring/references/starter.md
@@ -0,0 +1,47 @@
+# Widget starter
+
+Use this as the structural baseline for a new widget. Adapt the controls and behavior to the request. Keep the content root unframed because ThinkEx supplies the outer title, border, and gutter.
+
+```html
+<style>
+	.tx-root {
+		display: flex;
+		flex-direction: column;
+		gap: 12px;
+		color: var(--foreground);
+		font: inherit;
+	}
+	.tx-controls {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 8px;
+		align-items: center;
+	}
+	.tx-button {
+		padding: 8px 14px;
+		border: 1px solid var(--border);
+		border-radius: var(--radius);
+		background: var(--primary);
+		color: var(--primary-foreground);
+		cursor: pointer;
+		font: inherit;
+	}
+	.tx-muted {
+		color: var(--muted-foreground);
+	}
+</style>
+<div class="tx-root">
+	<div id="output" aria-live="polite">Ready.</div>
+	<div class="tx-controls">
+		<button class="tx-button" id="action" type="button">Run</button>
+	</div>
+</div>
+<script>
+	const output = document.getElementById("output");
+	document.getElementById("action").addEventListener("click", () => {
+		output.textContent = "Done.";
+	});
+</script>
+```
+
+Before writing the block, replace placeholder behavior and labels, wire every visible control, and HTML-escape the complete fragment inside the widget element.
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index 1de2f4521..0b8c2056f 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -43,15 +43,10 @@ export const workspaceHtmlMathInstruction =
 	'This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML.';
 
 /**
- * The hard constraints only — enough that a widget written without the skill
- * still renders. Activate the widget-authoring skill for the full contract,
- * starter template, and canvas/layout guidance rather than restating it here on
- * every turn.
- *
- * Carried by the document instruction because a widget is a document block: the
- * model reaches for one from inside the same write it would write prose in.
+ * Keep discovery and serialization beside the document tool. The activated
+ * skill owns the authoring contract so the two prompts cannot drift apart.
  */
-const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document, written as <div data-type="widget" title="Short title">…escaped HTML source…</div>. Use one only when the user explicitly asks for a widget, asks for interaction or live computation, or wants a visual artifact inside the document that ordinary blocks cannot express. Do not add a widget merely to decorate an explanation; keep normal content in normal blocks. Activate the "widget-authoring" skill before writing widget source; it has the full contract, a starter template, and canvas/layout rules. Hard constraints: the source is a self-contained fragment run in a sandboxed iframe, so provide only inner content (HTML plus inline <style> and <script>), never <!doctype>, <html>, <head>, or <body>; keep all JavaScript inline and do not use external scripts, imports, fetch, or navigation; style with the injected app CSS variables (--background, --foreground, --primary, --border, --radius, etc.) instead of hard-coded colors.`;
+const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document. Use one when the user explicitly asks for a widget, asks for interaction or live computation, or wants a document visual that ordinary blocks cannot express. Keep ordinary content in ordinary blocks. Before authoring or editing widget source, activate the "widget-authoring" skill and follow its HTML, sandbox, layout, and editing contract. Serialize the result as <div data-type="widget" title="Short title">…HTML-escaped fragment…</div>.`;
 
 export const workspaceDocumentHtmlInstruction = `Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. ${workspaceHtmlMathInstruction} For checkboxes, use <ul data-type="taskList"><li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>Item</p></div></li></ul>. Documents cannot hold images: never use <img> or <figure>, and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with <citation ref="wr_7Kp2Qa9x"></citation> placed after the claim it supports. ${workspaceWidgetHtmlInstruction}`;
 

From 049722dea04af7fc51edc9721fc4a694835d7bae Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:20:25 -0400
Subject: [PATCH 24/32] fix(workspaces): tighten widget interaction contracts

---
 .../widget/WorkspaceAddWidgetDialog.tsx       |  1 -
 .../workspace-widget-sandbox-document.test.ts |  1 +
 .../workspace-widget-sandbox-document.ts      |  2 +-
 .../composer/workspace-composer-actions.ts    | 19 +++----------------
 .../content/workspace-content-contract.ts     |  2 +-
 5 files changed, 6 insertions(+), 19 deletions(-)

diff --git a/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx b/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
index a77b1eaf2..34a8ea42f 100644
--- a/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
+++ b/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
@@ -73,7 +73,6 @@ function WorkspaceAddWidgetDialogContent({
 					stageComposerPrompt(
 						workspaceId,
 						`Add an interactive widget to ${documentPath}: ${description}`,
-						{ revealChat: true },
 					);
 					onOpenChange(false);
 				}}
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
index fd5dcb318..4d25256f1 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
@@ -24,6 +24,7 @@ describe("buildWidgetSandboxDocument", () => {
 		expect(loadsKatex("<p>$$E = mc^2$$</p>")).toBe(true);
 		expect(loadsKatex("<p>\\(x\\)</p>")).toBe(true);
 		expect(loadsKatex("<script>renderMathInElement(el)</script>")).toBe(true);
+		expect(loadsKatex("<script>button.onclick=()=>renderWidgetMath(output)</script>")).toBe(true);
 	});
 
 	it("skips KaTeX for a widget with no math, including prices", () => {
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
index b739bdd7f..a012cf0b6 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
@@ -99,7 +99,7 @@ const WIDGET_KATEX_SCRIPT_PATHS = [
 const WIDGET_KATEX_FONT_PATH = `${WIDGET_KATEX_BASE_PATH}/fonts/`;
 
 /** Any supported math notation: chat LaTeX delimiters, document markup, or the API. */
-const WIDGET_MATH_PATTERN = /\$\$|\\\(|\\\[|data-latex|katex|renderMathInElement/;
+const WIDGET_MATH_PATTERN = /\$\$|\\\(|\\\[|data-latex|katex|renderMathInElement|renderWidgetMath/;
 
 /**
  * Restrictive CSP for the frame. Widgets are self-contained HTML: only inline
diff --git a/src/features/workspaces/composer/workspace-composer-actions.ts b/src/features/workspaces/composer/workspace-composer-actions.ts
index 5c4b0bce3..3554ec807 100644
--- a/src/features/workspaces/composer/workspace-composer-actions.ts
+++ b/src/features/workspaces/composer/workspace-composer-actions.ts
@@ -18,33 +18,20 @@ type StageComposerQuoteOptions = {
 	revealChat?: boolean;
 };
 
-type StageComposerPromptOptions = {
-	revealChat?: boolean;
-};
-
 /**
  * Drop editable text into the AI composer from anywhere in the workspace (e.g.
- * an item viewer's "Ask AI to fix" button) and, by default, reveal the chat.
+ * an item viewer's "Ask AI to fix" button) and reveal the chat.
  * The text is staged as an editable draft — it is never auto-sent, so the user
  * can review or amend it before sending. Reusable across item types.
  */
-export function stageComposerPrompt(
-	workspaceId: string,
-	text: string,
-	options: StageComposerPromptOptions = {},
-) {
-	const { revealChat = true } = options;
-
+export function stageComposerPrompt(workspaceId: string, text: string) {
 	const trimmed = text.trim();
 	if (!trimmed) {
 		return;
 	}
 
 	useWorkspaceAiComposerDraftStore.getState().stageText(getComposerThreadId(workspaceId), trimmed);
-
-	if (revealChat) {
-		revealComposer(workspaceId);
-	}
+	revealComposer(workspaceId);
 }
 
 export function stageComposerQuote(
diff --git a/src/features/workspaces/content/workspace-content-contract.ts b/src/features/workspaces/content/workspace-content-contract.ts
index c589d6110..08860029c 100644
--- a/src/features/workspaces/content/workspace-content-contract.ts
+++ b/src/features/workspaces/content/workspace-content-contract.ts
@@ -5,7 +5,7 @@ import { workspaceReferenceRecordSchema } from "#/features/workspaces/locations/
 import { workspaceFileAssetKindSchema } from "#/features/workspaces/model/workspace-file";
 
 const workspacePathSchema = z.string().min(1);
-const workspaceEditRefSchema = z.string().min(1).max(64);
+const workspaceEditRefSchema = z.string().trim().min(1).max(64);
 
 const readWorkspaceItemsFailureCodes = [
 	"content_changed",

From eb4fb21aff5f823971b0bdf0228d17e38fc6d980 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:20:34 -0400
Subject: [PATCH 25/32] fix(evals): align edit grading with production

---
 eval/datasets/workspace-tools.cases.ts |  5 +-
 eval/support/harness.ts                | 86 +++++++++++++++++++-------
 eval/support/scorers.ts                |  9 ++-
 eval/workspace-tools.eval.ts           | 25 ++++++--
 4 files changed, 93 insertions(+), 32 deletions(-)

diff --git a/eval/datasets/workspace-tools.cases.ts b/eval/datasets/workspace-tools.cases.ts
index 4a4d27b66..29f85bdd0 100644
--- a/eval/datasets/workspace-tools.cases.ts
+++ b/eval/datasets/workspace-tools.cases.ts
@@ -37,7 +37,10 @@ const DOCUMENT_WIDGET_SOURCE = {
 	label: "encoded widget source",
 	pattern: /data-type=["']widget["'][^>]*>[\s\S]*&lt;[a-z]/i,
 };
-const FULL_HTML_DOCUMENT = { label: "a full HTML document", pattern: /<(html|head|body)\b/i };
+const FULL_HTML_DOCUMENT = {
+	label: "a full HTML document",
+	pattern: /(?:<|&lt;)\s*(?:!doctype\b|html\b|head\b|body\b)/i,
+};
 
 const PLAIN_PRICES = ["30", "60", "90"].map((price) => ({
 	label: `$${price}`,
diff --git a/eval/support/harness.ts b/eval/support/harness.ts
index 4b5e08125..bb95c2dfc 100644
--- a/eval/support/harness.ts
+++ b/eval/support/harness.ts
@@ -17,13 +17,20 @@ import {
 	getWorkspaceToolDefinition,
 	workspaceToolDefinitions,
 } from "#/features/workspaces/operations/workspace-tool-definitions";
+import {
+	createDocumentAiBlockSnapshot,
+	parseDocumentAiHtml,
+	serializeTiptapNodeToAiHtml,
+	withTiptapNodeAiRef,
+} from "#/features/workspaces/documents/document-ai-html";
+import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
 
 /** A single tool call the model emitted, graded against the real zod schema. */
 export interface WorkspaceAgentToolCall {
 	name: string;
 	input: unknown;
-	/** editRefs returned by completed read steps before this call was made. */
-	priorReadEditRefs: string[];
+	/** editRefs returned by completed read steps before this call, grouped by source path. */
+	priorReadEditRefsByPath: Record<string, string[]>;
 	/** `input` satisfies the tool's real zod input schema. */
 	valid: boolean;
 	/** Human-readable zod issues (`path: message`) when invalid. */
@@ -46,29 +53,46 @@ export interface WorkspaceAgentInput {
 	workspaceName?: string;
 }
 
-// Deterministic read fixture: document HTML carrying real `data-edit-ref` values,
-// so a read→edit turn can produce a targeted edit that traces back to the read.
-// `scoreTargetedEditProvenance` checks that provenance against the refs that
-// were actually returned during each run.
-const STANDUP_HEADING_REF = "b_standupHead1.r_head000001";
-const STANDUP_LIST_REF = "b_standupList1.r_bullet0001";
 const STANDUP_PATH = "/Notes/Standup.md";
 
-/**
- * Realistic items the model reads before editing — written exactly as the real
- * serializer emits it, so an edit turn sees production markup and real refs.
- */
-const EVAL_STANDUP_BLOCKS = {
-	[STANDUP_HEADING_REF]: '<h1 data-block-id="b_standupHead1">Standup</h1>',
-	[STANDUP_LIST_REF]: '<ul data-block-id="b_standupList1"><li><p>Discuss roadmap</p></li></ul>',
+type EvalStandupFixture = {
+	blocks: Map<string, string>;
+	content: string;
 };
-const EVAL_STANDUP_CONTENT = `<h1 data-edit-ref="${STANDUP_HEADING_REF}">Standup</h1><ul data-edit-ref="${STANDUP_LIST_REF}"><li>Discuss roadmap</li></ul>`;
+
+let evalStandupFixture: Promise<EvalStandupFixture> | undefined;
+
+function getEvalStandupFixture() {
+	return (evalStandupFixture ??= createEvalStandupFixture());
+}
+
+/** Derive the eval read fixture from the production serializers so it cannot drift. */
+async function createEvalStandupFixture(): Promise<EvalStandupFixture> {
+	const document = getTiptapDocumentSchema().nodeFromJSON(
+		parseDocumentAiHtml("<h1>Standup</h1><ul><li>Discuss roadmap</li></ul>"),
+	);
+	const blockIds = ["b_standupHead1", "b_standupList1"];
+	const blocks = new Map<string, string>();
+	const content: string[] = [];
+
+	for (let index = 0; index < document.childCount; index += 1) {
+		const blockId = blockIds[index];
+		if (!blockId) throw new Error("Eval standup fixture has an unexpected block count.");
+		const node = withTiptapNodeAiRef(document.child(index), blockId);
+		const snapshot = await createDocumentAiBlockSnapshot(node);
+		blocks.set(snapshot.editRef, snapshot.content);
+		content.push(await serializeTiptapNodeToAiHtml(node));
+	}
+
+	return { blocks, content: content.join("") };
+}
 
 // Per-tool stubbed outputs. Reads return the realistic item for the requested
 // path; everything else returns a neutral success so a follow-up step can still
 // proceed. No real Durable Object is touched and no workspace is mutated.
-function evalToolFixture(toolName: string, input: unknown): unknown {
+async function evalToolFixture(toolName: string, input: unknown): Promise<unknown> {
 	if (toolName === "workspace_read_items") {
+		const fixture = await getEvalStandupFixture();
 		const requests = (
 			input as {
 				requests?: Array<{ editRef?: string; mode?: string; path?: string }>;
@@ -80,7 +104,7 @@ function evalToolFixture(toolName: string, input: unknown): unknown {
 			}
 			if (request.mode === "block") {
 				const editRef = request.editRef ?? "";
-				const content = EVAL_STANDUP_BLOCKS[editRef as keyof typeof EVAL_STANDUP_BLOCKS];
+				const content = fixture.blocks.get(editRef);
 				if (!content) {
 					return { code: "edit_ref_not_found", path: STANDUP_PATH, status: "failed" };
 				}
@@ -100,7 +124,7 @@ function evalToolFixture(toolName: string, input: unknown): unknown {
 			}
 
 			return {
-				content: EVAL_STANDUP_CONTENT,
+				content: fixture.content,
 				format: "html",
 				itemId: "standup-document",
 				location: { endBlock: 2, kind: "blocks", startBlock: 1, totalBlocks: 2 },
@@ -169,7 +193,7 @@ export async function runWorkspaceAgent(input: WorkspaceAgentInput): Promise<Wor
 	});
 
 	const toolCalls: WorkspaceAgentToolCall[] = [];
-	const priorReadEditRefs = new Set<string>();
+	const priorReadEditRefsByPath = new Map<string, Set<string>>();
 	for (const step of result.steps) {
 		for (const part of step.content) {
 			if (part.type !== "tool-call") continue;
@@ -178,7 +202,9 @@ export async function runWorkspaceAgent(input: WorkspaceAgentInput): Promise<Wor
 			toolCalls.push({
 				name: part.toolName,
 				input: part.input,
-				priorReadEditRefs: [...priorReadEditRefs],
+				priorReadEditRefsByPath: Object.fromEntries(
+					[...priorReadEditRefsByPath].map(([path, refs]) => [path, [...refs]]),
+				),
 				valid: parsed ? parsed.success : false,
 				issues: parsed
 					? parsed.success
@@ -191,7 +217,7 @@ export async function runWorkspaceAgent(input: WorkspaceAgentInput): Promise<Wor
 		}
 		for (const toolResult of step.toolResults) {
 			if (toolResult.toolName === "workspace_read_items") {
-				collectReadEditRefs(toolResult.output, priorReadEditRefs);
+				collectReadEditRefs(toolResult.output, priorReadEditRefsByPath);
 			}
 		}
 	}
@@ -199,7 +225,7 @@ export async function runWorkspaceAgent(input: WorkspaceAgentInput): Promise<Wor
 	return { text: result.text, toolCalls };
 }
 
-function collectReadEditRefs(output: unknown, refs: Set<string>) {
+function collectReadEditRefs(output: unknown, refsByPath: Map<string, Set<string>>) {
 	const results = (output as { results?: unknown[] })?.results;
 	if (!Array.isArray(results)) {
 		return;
@@ -210,7 +236,19 @@ function collectReadEditRefs(output: unknown, refs: Set<string>) {
 			continue;
 		}
 
-		const { content, editRef } = result as { content?: unknown; editRef?: unknown };
+		const { content, editRef, path } = result as {
+			content?: unknown;
+			editRef?: unknown;
+			path?: unknown;
+		};
+		if (typeof path !== "string") {
+			continue;
+		}
+		let refs = refsByPath.get(path);
+		if (!refs) {
+			refs = new Set<string>();
+			refsByPath.set(path, refs);
+		}
 		if (typeof editRef === "string") {
 			refs.add(editRef);
 		}
diff --git a/eval/support/scorers.ts b/eval/support/scorers.ts
index 3b13216f5..312b9ffa4 100644
--- a/eval/support/scorers.ts
+++ b/eval/support/scorers.ts
@@ -76,10 +76,15 @@ export function scoreTargetedEditProvenance(output: WorkspaceAgentOutput): Score
 
 	for (const call of output.toolCalls) {
 		if (call.name !== "workspace_edit_item") continue;
-		const input = call.input as { edits?: Array<{ editRef?: string; op?: string }> };
+		const input = call.input as {
+			edits?: Array<{ editRef?: string; op?: string }>;
+			path?: string;
+		};
 		if (!Array.isArray(input.edits)) continue;
 
-		const priorReadEditRefs = new Set(call.priorReadEditRefs);
+		const priorReadEditRefs = new Set(
+			typeof input.path === "string" ? call.priorReadEditRefsByPath[input.path] : [],
+		);
 		for (const edit of input.edits) {
 			if (edit.op === "overwrite") {
 				usedOverwrite = true;
diff --git a/eval/workspace-tools.eval.ts b/eval/workspace-tools.eval.ts
index 3020018f1..875f50fbd 100644
--- a/eval/workspace-tools.eval.ts
+++ b/eval/workspace-tools.eval.ts
@@ -12,20 +12,35 @@ import {
 } from "./support/scorers";
 
 const STANDUP_LIST_REF = "b_standupList1.r_bullet0001";
+const STANDUP_PATH = "/Notes/Standup.md";
 
 describe("workspace eval scorers", () => {
 	it.each([
-		{ expected: false, priorReadEditRefs: [] },
-		{ expected: true, priorReadEditRefs: [STANDUP_LIST_REF] },
-	])("requires an editRef from a completed earlier read", ({ expected, priorReadEditRefs }) => {
+		{ editPath: STANDUP_PATH, expected: false, readPath: STANDUP_PATH, refs: [] },
+		{
+			editPath: STANDUP_PATH,
+			expected: true,
+			readPath: STANDUP_PATH,
+			refs: [STANDUP_LIST_REF],
+		},
+		{
+			editPath: "/Notes/Other.md",
+			expected: false,
+			readPath: STANDUP_PATH,
+			refs: [STANDUP_LIST_REF],
+		},
+	])("requires an editRef read from the edited path", ({ editPath, expected, readPath, refs }) => {
 		const output: WorkspaceAgentOutput = {
 			text: "",
 			toolCalls: [
 				{
-					input: { edits: [{ editRef: STANDUP_LIST_REF, op: "insert_after" }] },
+					input: {
+						edits: [{ editRef: STANDUP_LIST_REF, op: "insert_after" }],
+						path: editPath,
+					},
 					issues: [],
 					name: "workspace_edit_item",
-					priorReadEditRefs,
+					priorReadEditRefsByPath: { [readPath]: refs },
 					valid: true,
 				},
 			],

From 9c720bfbe15735d0e1728b623fbd5c860ed398ec Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:29:27 -0400
Subject: [PATCH 26/32] fix(evals): guard inherited path names

---
 eval/support/scorers.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/eval/support/scorers.ts b/eval/support/scorers.ts
index 312b9ffa4..a38b0a643 100644
--- a/eval/support/scorers.ts
+++ b/eval/support/scorers.ts
@@ -83,7 +83,9 @@ export function scoreTargetedEditProvenance(output: WorkspaceAgentOutput): Score
 		if (!Array.isArray(input.edits)) continue;
 
 		const priorReadEditRefs = new Set(
-			typeof input.path === "string" ? call.priorReadEditRefsByPath[input.path] : [],
+			typeof input.path === "string" && Object.hasOwn(call.priorReadEditRefsByPath, input.path)
+				? call.priorReadEditRefsByPath[input.path]
+				: [],
 		);
 		for (const edit of input.edits) {
 			if (edit.op === "overwrite") {

From f20098e37d439a01889240e4f20ba79513783c84 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:33:35 -0400
Subject: [PATCH 27/32] refactor(widgets): reuse document math markup

---
 .../ai/skills/widget-authoring/SKILL.md       |  2 +-
 .../workspace-widget-sandbox-document.test.ts |  1 -
 .../workspace-widget-sandbox-document.ts      | 44 ++++++++++++++-----
 3 files changed, 34 insertions(+), 13 deletions(-)

diff --git a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
index 0d9bcd63b..ee3a12cf6 100644
--- a/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
+++ b/src/features/workspaces/ai/skills/widget-authoring/SKILL.md
@@ -29,7 +29,7 @@ Read these bundled references only when they apply:
 - For a new widget or a ground-up rebuild, read `references/starter.md` before writing source.
 - For any `<canvas>` drawing, read `references/canvas.md` before writing source.
 
-Use the document tool's HTML math markup. After adding math dynamically, call `renderWidgetMath(element)`. KaTeX is the only bundled library; create other diagrams and charts with inline SVG or canvas.
+Use the document tool's HTML math markup. The runtime renders matching math elements when they are added or changed. KaTeX is the only bundled library; create other diagrams and charts with inline SVG or canvas.
 
 ## Edit
 
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
index 4d25256f1..fd5dcb318 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
@@ -24,7 +24,6 @@ describe("buildWidgetSandboxDocument", () => {
 		expect(loadsKatex("<p>$$E = mc^2$$</p>")).toBe(true);
 		expect(loadsKatex("<p>\\(x\\)</p>")).toBe(true);
 		expect(loadsKatex("<script>renderMathInElement(el)</script>")).toBe(true);
-		expect(loadsKatex("<script>button.onclick=()=>renderWidgetMath(output)</script>")).toBe(true);
 	});
 
 	it("skips KaTeX for a widget with no math, including prices", () => {
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
index a012cf0b6..1d72050da 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
@@ -99,7 +99,7 @@ const WIDGET_KATEX_SCRIPT_PATHS = [
 const WIDGET_KATEX_FONT_PATH = `${WIDGET_KATEX_BASE_PATH}/fonts/`;
 
 /** Any supported math notation: chat LaTeX delimiters, document markup, or the API. */
-const WIDGET_MATH_PATTERN = /\$\$|\\\(|\\\[|data-latex|katex|renderMathInElement|renderWidgetMath/;
+const WIDGET_MATH_PATTERN = /\$\$|\\\(|\\\[|data-latex|katex|renderMathInElement/;
 
 /**
  * Restrictive CSP for the frame. Widgets are self-contained HTML: only inline
@@ -222,23 +222,45 @@ body{padding:clamp(10px,2.5%,16px);}
   window.addEventListener("DOMContentLoaded",function(){
     if(typeof renderMathInElement==="function"){
       var mathOptions={throwOnError:false,errorColor:"var(--muted-foreground)"};
-      window.renderWidgetMath=function(target){
-        var root=target||document.body;
-        renderMathInElement(root,Object.assign({
+      function renderLatexNode(node){
+        if(node.dataset.widgetMathRendered)return;
+        node.dataset.widgetMathRendered="1";
+        katex.render(node.getAttribute("data-latex"),node,Object.assign(
+          {displayMode:node.getAttribute("data-type")==="block-math"},mathOptions));
+      }
+      function renderLatexIn(root){
+        if(root.matches&&root.matches("[data-latex]"))renderLatexNode(root);
+        if(root.querySelectorAll)root.querySelectorAll("[data-latex]").forEach(renderLatexNode);
+      }
+      try{
+        renderMathInElement(document.body,Object.assign({
           delimiters:[
             {left:"$$",right:"$$",display:true},
             {left:"\\\\[",right:"\\\\]",display:true},
             {left:"\\\\(",right:"\\\\)",display:false}
           ]
         },mathOptions));
-        root.querySelectorAll("[data-latex]").forEach(function(node){
-          if(node.dataset.widgetMathRendered)return;
-          node.dataset.widgetMathRendered="1";
-          katex.render(node.getAttribute("data-latex"),node,Object.assign(
-            {displayMode:node.getAttribute("data-type")==="block-math"},mathOptions));
+        renderLatexIn(document.body);
+      }catch(_){}
+      new MutationObserver(function(records){
+        records.forEach(function(record){
+          if(record.type==="attributes"){
+            if(record.target.matches&&record.target.matches("[data-latex]")){
+              delete record.target.dataset.widgetMathRendered;
+              try{renderLatexNode(record.target);}catch(_){}
+            }
+            return;
+          }
+          record.addedNodes.forEach(function(node){
+            if(node.nodeType===1)try{renderLatexIn(node);}catch(_){}
+          });
         });
-      };
-      try{ window.renderWidgetMath(); }catch(_){}
+      }).observe(document.body,{
+        attributeFilter:["data-latex","data-type"],
+        attributes:true,
+        childList:true,
+        subtree:true
+      });
     }
     var lastHeight=0;
     var measureScheduled=false;

From 71d0ee54ed870b2dc36d246ee8d823e5582b1a30 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:58:01 -0400
Subject: [PATCH 28/32] refactor(widgets): simplify runtime contracts

---
 scripts/copy-widget-libs.mjs                  |   1 -
 .../ai-chat/ai-chat-tool-receipts.ts          |  13 +-
 .../widget/WorkspaceWidgetSandbox.test.tsx    | 206 ++++++------------
 .../widget/WorkspaceWidgetSandbox.tsx         |  44 ++--
 .../workspace-widget-sandbox-document.test.ts |  16 +-
 .../workspace-widget-sandbox-document.ts      |  24 +-
 .../documents/document-ai-edits.test.ts       |  18 +-
 .../workspaces/documents/document-ai-edits.ts |  52 ++---
 .../operations/workspace-tool-schemas.ts      |   2 +-
 9 files changed, 122 insertions(+), 254 deletions(-)

diff --git a/scripts/copy-widget-libs.mjs b/scripts/copy-widget-libs.mjs
index d4afecc76..14a494406 100644
--- a/scripts/copy-widget-libs.mjs
+++ b/scripts/copy-widget-libs.mjs
@@ -33,7 +33,6 @@ for (const entry of [
 	"katex.min.css",
 	"katex.min.js",
 	"fonts",
-	"contrib/auto-render.min.js",
 	// Chemistry (\ce) and units (\pu), matching what chat and documents import.
 	"contrib/mhchem.min.js",
 ]) {
diff --git a/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts b/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts
index f2ff3dbd1..f929f2ee3 100644
--- a/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts
+++ b/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts
@@ -1,8 +1,3 @@
-import {
-	getWorkspaceItemRegistryEntry,
-	workspaceItemTypeSchema,
-} from "#/features/workspaces/workspace-item-registry";
-
 export type AiChatToolReceiptStatus = "completed" | "failed" | "interrupted" | "running";
 type AiChatFinishedToolReceiptStatus = Exclude<AiChatToolReceiptStatus, "interrupted" | "running">;
 
@@ -167,12 +162,8 @@ export function getFinishedToolReceipt(input: {
 			return summarizeWorkspaceBatch(input.output, {
 				failureVerb: "create",
 				successVerb: "Created",
-				typeFromItem: (item) => {
-					const type = workspaceItemTypeSchema.safeParse(getString(asRecord(item).type));
-					return type.success
-						? getWorkspaceItemRegistryEntry(type.data).label.toLowerCase()
-						: "item";
-				},
+				typeFromItem: (item) =>
+					getString(asRecord(item).type) === "folder" ? "folder" : "document",
 			});
 		case "workspace_delete_items":
 			return summarizeWorkspaceBatch(input.output, {
diff --git a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx
index 59f984c1d..40e3b13c2 100644
--- a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx
+++ b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.test.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 
-import { act } from "react";
+import { act, type ReactNode } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -12,10 +12,7 @@ import {
 
 const themeState = vi.hoisted(() => ({ resolvedTheme: "light" as "light" | "dark" }));
 
-vi.mock("#/components/theme-provider", () => ({
-	useTheme: () => themeState,
-}));
-
+vi.mock("#/components/theme-provider", () => ({ useTheme: () => themeState }));
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 
 describe("WorkspaceWidgetSandbox", () => {
@@ -25,8 +22,7 @@ describe("WorkspaceWidgetSandbox", () => {
 	beforeEach(() => {
 		themeState.resolvedTheme = "light";
 		document.documentElement.style.setProperty("--background", "white");
-		container = document.createElement("div");
-		document.body.appendChild(container);
+		container = document.body.appendChild(document.createElement("div"));
 		root = createRoot(container);
 		vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
 			callback(0);
@@ -42,175 +38,103 @@ describe("WorkspaceWidgetSandbox", () => {
 		vi.unstubAllGlobals();
 	});
 
-	it("updates the live frame theme without rebuilding authored HTML", async () => {
-		await act(async () =>
-			root.render(<WorkspaceWidgetSandbox html="<p>one</p>" label="Counter" />),
-		);
-
-		const iframe = container.querySelector("iframe");
-		expect(iframe).not.toBeNull();
-		expect(iframe?.title).toBe("Counter widget");
-		if (!iframe?.contentWindow) throw new Error("Expected the sandbox iframe window");
-
+	it("preserves a live widget across theme changes and rejects stale messages", async () => {
+		await render(root, <WorkspaceWidgetSandbox html="<p>one</p>" label="Counter" />);
+		const iframe = getIframe(container);
+		const frame = iframe.parentElement;
 		const initialDocument = iframe.getAttribute("srcdoc");
-		expect(initialDocument).toContain("<p>one</p>");
-		expect(initialDocument).toContain("var SESSION=1");
-
 		const postMessage = vi.spyOn(iframe.contentWindow, "postMessage");
-		await act(async () => {
-			window.dispatchEvent(
-				new MessageEvent("message", {
-					data: {
-						source: WIDGET_SANDBOX_FRAME_SOURCE,
-						kind: "ready",
-						sessionId: 1,
-					},
-					source: iframe.contentWindow,
-				}),
-			);
-		});
+
+		await sendFrameMessage(iframe, { kind: "ready", sessionId: 1 });
+		await sendFrameMessage(iframe, { height: 900, kind: "height", sessionId: 1 });
+		expect(frame?.style.height).toBe("720px");
 
 		themeState.resolvedTheme = "dark";
 		document.documentElement.style.setProperty("--background", "black");
-		await act(async () =>
-			root.render(<WorkspaceWidgetSandbox html="<p>one</p>" label="Counter" />),
-		);
+		await render(root, <WorkspaceWidgetSandbox html="<p>one</p>" label="Counter" />);
 
 		expect(container.querySelector("iframe")).toBe(iframe);
+		expect(iframe.title).toBe("Counter widget");
 		expect(iframe.getAttribute("srcdoc")).toBe(initialDocument);
 		expect(postMessage).toHaveBeenLastCalledWith(
 			{
-				source: WIDGET_SANDBOX_HOST_SOURCE,
 				kind: "theme",
 				sessionId: 1,
+				source: WIDGET_SANDBOX_HOST_SOURCE,
 				theme: "dark",
 				tokens: expect.objectContaining({ "--background": "black" }),
 			},
 			"*",
 		);
 
-		await act(async () =>
-			root.render(<WorkspaceWidgetSandbox html="<p>two</p>" label="Counter" />),
-		);
-		expect(iframe.getAttribute("srcdoc")).not.toBe(initialDocument);
-		expect(iframe.getAttribute("srcdoc")).toContain("<p>two</p>");
+		await render(root, <WorkspaceWidgetSandbox html="<p>two</p>" />);
+		expect(frame?.style.height).toBe("120px");
 		expect(iframe.getAttribute("srcdoc")).toContain("var SESSION=2");
+		await sendFrameMessage(iframe, { height: 500, kind: "height", sessionId: 1 });
+		expect(frame?.style.height).toBe("120px");
 	});
 
-	it("resets height for new HTML and ignores messages from the old frame", async () => {
-		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>tall</p>" />));
-
-		const iframe = container.querySelector("iframe");
-		if (!iframe?.contentWindow) throw new Error("Expected the sandbox iframe window");
+	it("lets a load error size itself instead of reloading broken source", async () => {
+		await render(root, <WorkspaceWidgetSandbox html="<p>broken</p>" />);
+		const iframe = getIframe(container);
 		const frame = iframe.parentElement;
 
-		await act(async () => {
-			window.dispatchEvent(
-				new MessageEvent("message", {
-					data: {
-						source: WIDGET_SANDBOX_FRAME_SOURCE,
-						kind: "height",
-						height: 900,
-						sessionId: 1,
-					},
-					source: iframe.contentWindow,
-				}),
-			);
-		});
-		expect(frame?.style.height).toBe("720px");
-
-		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>short</p>" />));
-		expect(frame?.style.height).toBe("120px");
-
-		await act(async () => {
-			window.dispatchEvent(
-				new MessageEvent("message", {
-					data: {
-						source: WIDGET_SANDBOX_FRAME_SOURCE,
-						kind: "height",
-						height: 500,
-						sessionId: 1,
-					},
-					source: iframe.contentWindow,
-				}),
-			);
-		});
-		expect(frame?.style.height).toBe("120px");
-	});
-
-	it("lets the error view size itself instead of keeping the widget height", async () => {
-		await act(async () => root.render(<WorkspaceWidgetSandbox html="<p>broken</p>" />));
-
-		const iframe = container.querySelector("iframe");
-		expect(iframe?.contentWindow).not.toBeNull();
-		const frame = iframe?.parentElement;
-
-		await act(async () => {
-			window.dispatchEvent(
-				new MessageEvent("message", {
-					data: {
-						source: WIDGET_SANDBOX_FRAME_SOURCE,
-						kind: "error",
-						message: "Unexpected token",
-						sessionId: 1,
-					},
-					source: iframe?.contentWindow,
-				}),
-			);
+		await sendFrameMessage(iframe, {
+			kind: "error",
+			message: "Unexpected token",
+			sessionId: 1,
 		});
 
 		expect(frame?.style.height).toBe("");
-		expect(frame?.querySelector('[role="alert"]')).not.toBeNull();
 		expect(frame?.querySelector("iframe")).toBeNull();
-
-		const retry = [...(frame?.querySelectorAll("button") ?? [])].find(
-			(button) => button.textContent === "Try again",
-		);
-		await act(async () => retry?.click());
-
-		expect(frame?.querySelector('[role="alert"]')).toBeNull();
-		expect(frame?.querySelector("iframe")).not.toBeNull();
-		expect(frame?.style.height).toBe("120px");
+		expect(frame?.querySelector("button")).toBeNull();
 	});
 
 	it("keeps a ready widget mounted after a runtime error", async () => {
-		await act(async () => root.render(<WorkspaceWidgetSandbox html="<button>Run</button>" />));
-
-		const iframe = container.querySelector("iframe");
-		if (!iframe?.contentWindow) throw new Error("Expected the sandbox iframe window");
+		await render(root, <WorkspaceWidgetSandbox html="<button>Run</button>" />);
+		const iframe = getIframe(container);
 		const frame = iframe.parentElement;
 
-		await act(async () => {
-			window.dispatchEvent(
-				new MessageEvent("message", {
-					data: {
-						source: WIDGET_SANDBOX_FRAME_SOURCE,
-						kind: "ready",
-						sessionId: 1,
-					},
-					source: iframe.contentWindow,
-				}),
-			);
-			window.dispatchEvent(
-				new MessageEvent("message", {
-					data: {
-						source: WIDGET_SANDBOX_FRAME_SOURCE,
-						kind: "error",
-						message: "Click failed",
-						sessionId: 1,
-					},
-					source: iframe.contentWindow,
-				}),
-			);
-		});
+		await sendFrameMessage(iframe, { kind: "ready", sessionId: 1 });
+		await sendFrameMessage(iframe, { kind: "error", message: "Click failed", sessionId: 1 });
 
 		expect(frame?.querySelector("iframe")).toBe(iframe);
-		expect(frame?.querySelector('[role="alert"]')).not.toBeNull();
-		const dismiss = [...(frame?.querySelectorAll("button") ?? [])].find(
-			(button) => button.textContent === "Dismiss",
-		);
-		await act(async () => dismiss?.click());
+		await clickButton(frame, "Dismiss");
 		expect(frame?.querySelector('[role="alert"]')).toBeNull();
 		expect(frame?.querySelector("iframe")).toBe(iframe);
 	});
 });
+
+async function render(root: Root, element: ReactNode) {
+	await act(async () => root.render(element));
+}
+
+function getIframe(container: HTMLElement) {
+	const iframe = container.querySelector("iframe");
+	if (!iframe?.contentWindow) throw new Error("Expected the sandbox iframe window");
+	return iframe as HTMLIFrameElement & { contentWindow: Window };
+}
+
+async function sendFrameMessage(
+	iframe: HTMLIFrameElement,
+	message:
+		| { kind: "ready"; sessionId: number }
+		| { height: number; kind: "height"; sessionId: number }
+		| { kind: "error"; message: string; sessionId: number },
+) {
+	await act(async () => {
+		window.dispatchEvent(
+			new MessageEvent("message", {
+				data: { ...message, source: WIDGET_SANDBOX_FRAME_SOURCE },
+				source: iframe.contentWindow,
+			}),
+		);
+	});
+}
+
+async function clickButton(container: HTMLElement | null, label: string) {
+	const button = [...(container?.querySelectorAll("button") ?? [])].find(
+		(candidate) => candidate.textContent === label,
+	);
+	await act(async () => button?.click());
+}
diff --git a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
index 524923afc..cc6efd094 100644
--- a/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
+++ b/src/features/workspaces/components/widget/WorkspaceWidgetSandbox.tsx
@@ -127,11 +127,6 @@ export function WorkspaceWidgetSandbox({
 		return () => window.removeEventListener("message", onMessage);
 	}, []);
 
-	const retryWidget = () => {
-		readySessionIdRef.current = null;
-		setError(null);
-		setHeight(WIDGET_SANDBOX_MIN_HEIGHT);
-	};
 	const showFrame = !error || error.preserveFrame;
 
 	return (
@@ -162,26 +157,25 @@ export function WorkspaceWidgetSandbox({
 					<div className="max-h-32 w-full max-w-lg overflow-auto whitespace-pre-wrap rounded-md bg-muted px-4 py-3 font-mono text-muted-foreground text-xs leading-relaxed">
 						{error.message}
 					</div>
-					<div className="flex items-center gap-2">
-						<Button
-							type="button"
-							size="sm"
-							variant="outline"
-							onClick={error.preserveFrame ? () => setError(null) : retryWidget}
-						>
-							{error.preserveFrame ? "Dismiss" : "Try again"}
-						</Button>
-						{onAskAiToFix ? (
-							<Button
-								type="button"
-								size="sm"
-								variant="secondary"
-								onClick={() => onAskAiToFix(error.message)}
-							>
-								Ask AI to fix
-							</Button>
-						) : null}
-					</div>
+					{error.preserveFrame || onAskAiToFix ? (
+						<div className="flex items-center gap-2">
+							{error.preserveFrame ? (
+								<Button type="button" size="sm" variant="outline" onClick={() => setError(null)}>
+									Dismiss
+								</Button>
+							) : null}
+							{onAskAiToFix ? (
+								<Button
+									type="button"
+									size="sm"
+									variant="secondary"
+									onClick={() => onAskAiToFix(error.message)}
+								>
+									Ask AI to fix
+								</Button>
+							) : null}
+						</div>
+					) : null}
 				</div>
 			) : null}
 		</div>
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
index fd5dcb318..65c6c0224 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.test.ts
@@ -16,19 +16,11 @@ function loadsKatex(html: string) {
 }
 
 describe("buildWidgetSandboxDocument", () => {
-	// The only real decision in this module: KaTeX is ~290KB plus fonts, so it
-	// loads only for widgets that contain math. Over-matching costs a cached
-	// fetch; under-matching leaves math unrendered.
-	it("loads KaTeX for every math notation a widget may use", () => {
+	it("loads KaTeX only for document-style math markup", () => {
 		expect(loadsKatex('<span data-type="inline-math" data-latex="x^2"></span>')).toBe(true);
-		expect(loadsKatex("<p>$$E = mc^2$$</p>")).toBe(true);
-		expect(loadsKatex("<p>\\(x\\)</p>")).toBe(true);
-		expect(loadsKatex("<script>renderMathInElement(el)</script>")).toBe(true);
-	});
-
-	it("skips KaTeX for a widget with no math, including prices", () => {
+		expect(loadsKatex("<script>node.dataset.latex = 'x^2'</script>")).toBe(true);
+		expect(loadsKatex("<p>$$E = mc^2$$</p>")).toBe(false);
 		expect(loadsKatex("<p>Plans cost $30 or $75.</p><button>Buy</button>")).toBe(false);
-		expect(loadsKatex("<canvas id='c'></canvas>")).toBe(false);
 	});
 
 	it("limits external access to the bundled KaTeX assets", () => {
@@ -46,7 +38,7 @@ describe("buildWidgetSandboxDocument", () => {
 			"style-src 'unsafe-inline' https://app.test/widget-libs/katex/katex.min.css",
 		);
 		expect(document).toContain(
-			"script-src 'unsafe-inline' https://app.test/widget-libs/katex/katex.min.js https://app.test/widget-libs/katex/contrib/mhchem.min.js https://app.test/widget-libs/katex/contrib/auto-render.min.js",
+			"script-src 'unsafe-inline' https://app.test/widget-libs/katex/katex.min.js https://app.test/widget-libs/katex/contrib/mhchem.min.js",
 		);
 		expect(document).toContain("font-src data: https://app.test/widget-libs/katex/fonts/");
 		expect(document).toContain("connect-src 'none'");
diff --git a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
index 1d72050da..6c500e982 100644
--- a/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
+++ b/src/features/workspaces/components/widget/workspace-widget-sandbox-document.ts
@@ -94,12 +94,10 @@ const WIDGET_KATEX_STYLESHEET_PATH = `${WIDGET_KATEX_BASE_PATH}/katex.min.css`;
 const WIDGET_KATEX_SCRIPT_PATHS = [
 	`${WIDGET_KATEX_BASE_PATH}/katex.min.js`,
 	`${WIDGET_KATEX_BASE_PATH}/contrib/mhchem.min.js`,
-	`${WIDGET_KATEX_BASE_PATH}/contrib/auto-render.min.js`,
 ] as const;
 const WIDGET_KATEX_FONT_PATH = `${WIDGET_KATEX_BASE_PATH}/fonts/`;
 
-/** Any supported math notation: chat LaTeX delimiters, document markup, or the API. */
-const WIDGET_MATH_PATTERN = /\$\$|\\\(|\\\[|data-latex|katex|renderMathInElement/;
+const WIDGET_MATH_PATTERN = /data-latex|dataset\.latex/;
 
 /**
  * Restrictive CSP for the frame. Widgets are self-contained HTML: only inline
@@ -156,15 +154,8 @@ export function buildWidgetSandboxDocument({
 ${WIDGET_KATEX_SCRIPT_PATHS.map((path) => `<script src="${origin}${path}"></script>`).join("\n")}`
 		: "";
 
-	// Widgets are HTML, so math is authored the same way documents author it —
-	// `data-latex` markup — and the unambiguous LaTeX delimiters are accepted too
-	// for when a model reaches for chat habits. Single `$…$` is deliberately NOT
-	// a delimiter: it cannot be told apart from prices, so "$30 an hour … $75 an
-	// hour" would render the text between them as math. Dropping it is safer than
-	// defending it with a currency heuristic, and `$$…$$` still covers real math.
-	// Bad expressions render muted in place rather than throwing, so one
-	// malformed formula never takes the whole widget down.
-	//
+	// Widgets and documents use the same data-latex markup. The iframe still has
+	// to render it locally because its opaque origin cannot reuse the parent DOM.
 	// The base stylesheet deliberately sets no height. The frame reports what its
 	// content measures and the host sizes the block to match, so a widget takes
 	// the room it needs rather than a number picked here. Layout beyond that
@@ -220,7 +211,7 @@ body{padding:clamp(10px,2.5%,16px);}
     report("Unhandled promise rejection: "+((reason&&reason.stack)||reason));
   });
   window.addEventListener("DOMContentLoaded",function(){
-    if(typeof renderMathInElement==="function"){
+    if(typeof katex!=="undefined"&&typeof katex.render==="function"){
       var mathOptions={throwOnError:false,errorColor:"var(--muted-foreground)"};
       function renderLatexNode(node){
         if(node.dataset.widgetMathRendered)return;
@@ -233,13 +224,6 @@ body{padding:clamp(10px,2.5%,16px);}
         if(root.querySelectorAll)root.querySelectorAll("[data-latex]").forEach(renderLatexNode);
       }
       try{
-        renderMathInElement(document.body,Object.assign({
-          delimiters:[
-            {left:"$$",right:"$$",display:true},
-            {left:"\\\\[",right:"\\\\]",display:true},
-            {left:"\\\\(",right:"\\\\)",display:false}
-          ]
-        },mathOptions));
         renderLatexIn(document.body);
       }catch(_){}
       new MutationObserver(function(records){
diff --git a/src/features/workspaces/documents/document-ai-edits.test.ts b/src/features/workspaces/documents/document-ai-edits.test.ts
index 1f5b8b68a..b41d28342 100644
--- a/src/features/workspaces/documents/document-ai-edits.test.ts
+++ b/src/features/workspaces/documents/document-ai-edits.test.ts
@@ -98,22 +98,14 @@ describe("document AI edits", () => {
 		);
 	});
 
-	it("refuses an ambiguous widget source replacement", async () => {
-		const document = createDocument(
-			'<div data-type="widget">&lt;button&gt;Run&lt;/button&gt;&lt;button&gt;Run&lt;/button&gt;</div>',
-		);
-		const editRef = await getEditRef(document, "div");
+	it("rejects an ambiguous text replacement", async () => {
+		const document = createDocument("<p>Repeat. Repeat.</p>");
+		const editRef = await getEditRef(document, "p");
 		const result = await applyDocumentAiEdits(document, [
-			{ editRef, find: "Run", op: "replace_text", replace: "Stop" },
+			{ editRef, find: "Repeat", op: "replace_text", replace: "Stop" },
 		]);
 
-		expect(result).toMatchObject({
-			applied: 0,
-			failed: 1,
-			failures: [{ code: "edit_not_unique", index: 0 }],
-			status: "failed",
-		});
-		expect(getWidgetSource(result.document)).toContain("Run</button><button>Run");
+		expect(result.failures).toMatchObject([{ code: "edit_not_unique", index: 0 }]);
 	});
 
 	it("replaces the exact widget HTML returned by a block read", async () => {
diff --git a/src/features/workspaces/documents/document-ai-edits.ts b/src/features/workspaces/documents/document-ai-edits.ts
index aa3c249fb..ad9aebb01 100644
--- a/src/features/workspaces/documents/document-ai-edits.ts
+++ b/src/features/workspaces/documents/document-ai-edits.ts
@@ -238,32 +238,26 @@ function applyDocumentAiEdit(
 	const children = getDocumentChildren(document);
 	if (edit.op === "delete") {
 		children.splice(targetIndex, 1);
-	} else if (edit.op === "replace_text") {
-		const target = document.child(targetIndex);
-		const replaced = replaceUniqueText(
-			serializeTiptapNodeToEditableAiHtml(target),
-			edit.find,
-			edit.replace,
-		);
-		if (!replaced.ok) {
-			return { code: replaced.code, detail: replaced.detail, status: "failed" };
+	} else {
+		let operation: "insert_after" | "insert_before" | "replace";
+		let html: string;
+		if (edit.op === "replace_text") {
+			const replaced = replaceUniqueText(
+				serializeTiptapNodeToEditableAiHtml(document.child(targetIndex)),
+				edit.find,
+				edit.replace,
+			);
+			if (!replaced.ok) {
+				return { code: replaced.code, detail: replaced.detail, status: "failed" };
+			}
+			operation = "replace";
+			html = replaced.text;
+		} else {
+			operation = edit.op;
+			html = edit.html;
 		}
 
-		const parsed = parseEditHtml(replaced.text);
-		if (!parsed.children) {
-			return { code: "invalid_html", detail: parsed.detail, status: "failed" };
-		}
-		const targetBlockId = readTiptapNodeBlockId(target);
-		const firstNode = parsed.children[0];
-		children.splice(
-			targetIndex,
-			1,
-			...(targetBlockId && firstNode
-				? [withTiptapNodeAiRef(firstNode, targetBlockId), ...parsed.children.slice(1)]
-				: parsed.children),
-		);
-	} else {
-		const parsed = parseEditHtml(edit.html);
+		const parsed = parseEditHtml(html);
 		if (!parsed.children) {
 			return { code: "invalid_html", detail: parsed.detail, status: "failed" };
 		}
@@ -272,11 +266,11 @@ function applyDocumentAiEdit(
 		// A replacement inherits the block ID of the block it stands in for, so a
 		// model holding its editRef can keep editing it.
 		const inserted =
-			edit.op === "replace" && targetBlockId && firstNode
+			operation === "replace" && targetBlockId && firstNode
 				? [withTiptapNodeAiRef(firstNode, targetBlockId), ...parsed.children.slice(1)]
 				: parsed.children;
 
-		switch (edit.op) {
+		switch (operation) {
 			case "insert_after":
 				children.splice(targetIndex + 1, 0, ...inserted);
 				break;
@@ -295,8 +289,6 @@ function applyDocumentAiEdit(
 		: { document: next, status: "applied" };
 }
 
-const DATA_EDIT_REF_ATTRIBUTE = /\s+data-edit-ref="[^"]*"/g;
-
 /**
  * Replaces a single unique occurrence, or explains why it could not.
  *
@@ -311,8 +303,8 @@ function replaceUniqueText(
 ):
 	| { ok: true; text: string }
 	| { ok: false; code: "edit_not_found" | "edit_not_unique"; detail: string } {
-	const haystack = source.replaceAll("\r\n", "\n").replace(DATA_EDIT_REF_ATTRIBUTE, "");
-	const needle = find.replaceAll("\r\n", "\n").replace(DATA_EDIT_REF_ATTRIBUTE, "");
+	const haystack = source.replaceAll("\r\n", "\n");
+	const needle = find.replaceAll("\r\n", "\n");
 	const matches = haystack.split(needle).length - 1;
 
 	if (matches === 0) {
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index 0b8c2056f..4d9247c92 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -39,7 +39,7 @@ export {
  * both HTML, so they share one rule and the model tracks "Markdown or HTML?"
  * rather than three per-surface dialects — chat keeps the `$…$` Markdown form.
  */
-export const workspaceHtmlMathInstruction =
+const workspaceHtmlMathInstruction =
 	'This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML.';
 
 /**

From 1d8b93a7d9a91d872427fde285c4de3cc2f2a71b Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:58:09 -0400
Subject: [PATCH 29/32] test(workspaces): trim feature-specific coverage

---
 eval/datasets/workspace-tools.cases.ts        | 120 ------------------
 .../workspace-composer-actions.test.ts        |  47 -------
 2 files changed, 167 deletions(-)
 delete mode 100644 src/features/workspaces/composer/workspace-composer-actions.test.ts

diff --git a/eval/datasets/workspace-tools.cases.ts b/eval/datasets/workspace-tools.cases.ts
index 29f85bdd0..8375fea14 100644
--- a/eval/datasets/workspace-tools.cases.ts
+++ b/eval/datasets/workspace-tools.cases.ts
@@ -16,37 +16,6 @@ export interface WorkspaceToolCase {
 	contentChecks?: ContentCheck[];
 }
 
-// Math is authored differently per surface and the failure is silent: `$x^2$` in
-// document HTML is schema-valid and renders as literal dollar signs forever, so
-// only a content check catches it. These patterns encode the shipped contract.
-const DOCUMENT_MATH_MARKUP = {
-	label: "a math block with data-latex",
-	pattern:
-		/<[^>]*(?:data-type=["'](?:inline|block)-math["'][^>]*data-latex=["'][^"']+["']|data-latex=["'][^"']+["'][^>]*data-type=["'](?:inline|block)-math["'])[^>]*>/,
-};
-const DOLLAR_DELIMITED_MATH = { label: "$...$ math delimiters", pattern: /\$[^$\n]+\$/ };
-const BRACKET_DELIMITED_MATH = { label: "\\(...\\) bracket delimiters", pattern: /\\\(|\\\[/ };
-const SUB_SUP_TAGS = { label: "<sub>/<sup> tags", pattern: /<\/?(sub|sup)>/ };
-const ESCAPED_DOLLAR = { label: "backslash-escaped \\$", pattern: /\\\$/ };
-const MHCHEM_CE = { label: "\\ce{...} chemistry", pattern: /\\\\?ce\{/ };
-const DOCUMENT_WIDGET_MARKUP = {
-	label: "a document widget block",
-	pattern: /data-type=["']widget["']/,
-};
-const DOCUMENT_WIDGET_SOURCE = {
-	label: "encoded widget source",
-	pattern: /data-type=["']widget["'][^>]*>[\s\S]*&lt;[a-z]/i,
-};
-const FULL_HTML_DOCUMENT = {
-	label: "a full HTML document",
-	pattern: /(?:<|&lt;)\s*(?:!doctype\b|html\b|head\b|body\b)/i,
-};
-
-const PLAIN_PRICES = ["30", "60", "90"].map((price) => ({
-	label: `$${price}`,
-	pattern: new RegExp(`\\$${price}\\b`),
-}));
-
 export const workspaceToolCases: WorkspaceToolCase[] = [
 	{
 		name: "create a document at an explicit path",
@@ -57,21 +26,6 @@ export const workspaceToolCases: WorkspaceToolCase[] = [
 		expectedTools: ["workspace_create_items"],
 		forbiddenTools: ["workspace_delete_items"],
 	},
-	{
-		name: "interactive requests create a document with a widget block",
-		input: {
-			prompt:
-				"Create /Physics/Wave Explorer.md with an interactive widget that lets me adjust wave frequency and see the wave update.",
-		},
-		expectedTools: ["workspace_create_items"],
-		contentChecks: [
-			{
-				source: { tool: "workspace_create_items" },
-				mustMatch: [DOCUMENT_WIDGET_MARKUP, DOCUMENT_WIDGET_SOURCE],
-				mustNotMatch: [FULL_HTML_DOCUMENT],
-			},
-		],
-	},
 	{
 		name: "search before answering a content question",
 		input: {
@@ -124,78 +78,4 @@ export const workspaceToolCases: WorkspaceToolCase[] = [
 		qualityRubric:
 			"The answer correctly explains that a folder contains items while a document holds content, in roughly one sentence.",
 	},
-
-	// ---- Math authoring, per surface -------------------------------------------
-	// The shipped contract: documents use data-latex markup and never dollar
-	// delimiters; chat replies use dollar delimiters and never brackets; literal
-	// currency is escaped in Markdown but plain in document HTML.
-	{
-		name: "document math uses data-latex markup, never dollar delimiters",
-		input: {
-			prompt:
-				"Create a document at /Notes/Quadratic.md that explains the quadratic formula and shows the formula itself, plus the discriminant b^2 - 4ac.",
-		},
-		expectedTools: ["workspace_create_items"],
-		contentChecks: [
-			{
-				source: { tool: "workspace_create_items" },
-				mustMatch: [DOCUMENT_MATH_MARKUP],
-				mustNotMatch: [DOLLAR_DELIMITED_MATH, BRACKET_DELIMITED_MATH, SUB_SUP_TAGS],
-			},
-		],
-	},
-	{
-		name: "document chemistry uses \\ce inside math markup",
-		input: {
-			prompt:
-				"Create a document at /Notes/Combustion.md showing the balanced equation for methane combustion and the standard gravity constant with units.",
-		},
-		expectedTools: ["workspace_create_items"],
-		contentChecks: [
-			{
-				source: { tool: "workspace_create_items" },
-				mustMatch: [DOCUMENT_MATH_MARKUP, MHCHEM_CE],
-				mustNotMatch: [DOLLAR_DELIMITED_MATH, SUB_SUP_TAGS],
-			},
-		],
-	},
-	{
-		name: "document currency stays plain, not markdown-escaped",
-		input: {
-			prompt:
-				"Create a document at /Notes/Pricing.md listing three tiers costing $30, $60 and $90 per month.",
-		},
-		expectedTools: ["workspace_create_items"],
-		contentChecks: [
-			{
-				source: { tool: "workspace_create_items" },
-				mustMatch: PLAIN_PRICES,
-				mustNotMatch: [ESCAPED_DOLLAR],
-			},
-		],
-	},
-	{
-		name: "chat math uses dollar delimiters, never brackets",
-		input: {
-			prompt:
-				"Explain the quadratic formula in a couple of sentences and show the formula. Answer in chat; do not create anything.",
-		},
-		forbiddenTools: ["workspace_create_items", "workspace_edit_item"],
-		contentChecks: [
-			{
-				source: "text",
-				mustMatch: [DOLLAR_DELIMITED_MATH],
-				mustNotMatch: [BRACKET_DELIMITED_MATH],
-			},
-		],
-	},
-	{
-		name: "chat escapes literal currency",
-		input: {
-			prompt:
-				"A jacket costs $80 and is 25% off. What is the sale price? Answer in chat; do not create anything.",
-		},
-		forbiddenTools: ["workspace_create_items"],
-		contentChecks: [{ source: "text", mustMatch: [ESCAPED_DOLLAR] }],
-	},
 ];
diff --git a/src/features/workspaces/composer/workspace-composer-actions.test.ts b/src/features/workspaces/composer/workspace-composer-actions.test.ts
deleted file mode 100644
index bdb0a1f22..000000000
--- a/src/features/workspaces/composer/workspace-composer-actions.test.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-import { getDefaultWorkspaceThreadId } from "#/features/workspaces/ai/ai-thread-identity";
-import { stageComposerPrompt } from "#/features/workspaces/composer/workspace-composer-actions";
-import { useWorkspaceAiComposerDraftStore } from "#/features/workspaces/state/workspace-ai-composer-draft-store";
-import {
-	getWorkspaceUiSession,
-	useWorkspaceUiStore,
-} from "#/features/workspaces/state/workspace-ui-store";
-
-const workspaceId = "workspace-1";
-const threadId = getDefaultWorkspaceThreadId(workspaceId);
-
-describe("stageComposerPrompt", () => {
-	beforeEach(() => {
-		vi.stubGlobal("localStorage", {
-			getItem: vi.fn(() => null),
-			removeItem: vi.fn(),
-			setItem: vi.fn(),
-		});
-		useWorkspaceAiComposerDraftStore.setState({
-			focusRequestByThreadId: {},
-			textByThreadId: { [threadId]: "Existing draft" },
-		});
-		useWorkspaceUiStore.setState({ sessionsByWorkspaceId: {} });
-	});
-
-	afterEach(() => {
-		vi.unstubAllGlobals();
-	});
-
-	it("stages the prompt and reveals the mobile composer", () => {
-		vi.stubGlobal("window", {
-			matchMedia: () => ({ matches: false }),
-		});
-
-		stageComposerPrompt(workspaceId, "Build a widget");
-
-		expect(
-			getWorkspaceUiSession(useWorkspaceUiStore.getState().getSession(workspaceId)).chatSurfaceMode,
-		).toBe("fullscreen");
-		expect(useWorkspaceAiComposerDraftStore.getState().textByThreadId[threadId]).toBe(
-			"Existing draft\n\nBuild a widget",
-		);
-		expect(useWorkspaceAiComposerDraftStore.getState().focusRequestByThreadId[threadId]).toBe(1);
-	});
-});

From 487217f6778604353055f4467cb20cb357763673 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 14:13:49 -0400
Subject: [PATCH 30/32] refactor(widgets): simplify add flow

---
 .../widget/WorkspaceAddWidgetDialog.tsx       | 116 ++++++++----------
 .../operations/workspace-tool-definitions.ts  |   2 +-
 2 files changed, 50 insertions(+), 68 deletions(-)

diff --git a/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx b/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
index 34a8ea42f..203187018 100644
--- a/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
+++ b/src/features/workspaces/components/widget/WorkspaceAddWidgetDialog.tsx
@@ -33,78 +33,60 @@ export function WorkspaceAddWidgetDialog({
 	open: boolean;
 	workspaceId: string;
 	onOpenChange: (open: boolean) => void;
-}) {
-	return (
-		<Dialog open={open} onOpenChange={onOpenChange}>
-			{open ? (
-				<WorkspaceAddWidgetDialogContent
-					documentPath={documentPath}
-					workspaceId={workspaceId}
-					onOpenChange={onOpenChange}
-				/>
-			) : null}
-		</Dialog>
-	);
-}
-
-function WorkspaceAddWidgetDialogContent({
-	documentPath,
-	workspaceId,
-	onOpenChange,
-}: {
-	documentPath: string;
-	workspaceId: string;
-	onOpenChange: (open: boolean) => void;
 }) {
 	const descriptionId = useId();
 
 	return (
-		<DialogContent>
-			<form
-				className="grid gap-6"
-				action={(formData) => {
-					const raw = formData.get("description");
-					const description = (typeof raw === "string" ? raw : "").trim();
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			{open ? (
+				<DialogContent>
+					<form
+						className="grid gap-6"
+						action={(formData) => {
+							const raw = formData.get("description");
+							const description = (typeof raw === "string" ? raw : "").trim();
 
-					if (!description) {
-						return;
-					}
+							if (!description) {
+								return;
+							}
 
-					stageComposerPrompt(
-						workspaceId,
-						`Add an interactive widget to ${documentPath}: ${description}`,
-					);
-					onOpenChange(false);
-				}}
-			>
-				<DialogHeader>
-					<DialogTitle>Add a widget</DialogTitle>
-					<DialogDescription>
-						A widget is an interactive tool that lives in this document, such as a simulation,
-						calculator, diagram, or visualization. Describe what you want, and the AI will build it
-						for you.
-					</DialogDescription>
-				</DialogHeader>
-				<FieldGroup>
-					<Field>
-						<FieldLabel htmlFor={descriptionId}>What should it do?</FieldLabel>
-						<Textarea
-							id={descriptionId}
-							name="description"
-							rows={4}
-							required
-							autoFocus
-							placeholder="e.g. An interactive unit circle that shows sine and cosine as I drag the angle"
-						/>
-					</Field>
-				</FieldGroup>
-				<DialogFooter>
-					<Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
-						Cancel
-					</Button>
-					<Button type="submit">Add with AI</Button>
-				</DialogFooter>
-			</form>
-		</DialogContent>
+							stageComposerPrompt(
+								workspaceId,
+								`Add an interactive widget to ${documentPath}: ${description}`,
+							);
+							onOpenChange(false);
+						}}
+					>
+						<DialogHeader>
+							<DialogTitle>Add a widget</DialogTitle>
+							<DialogDescription>
+								A widget is an interactive tool that lives in this document, such as a simulation,
+								calculator, diagram, or visualization. Describe what you want, and the AI will build
+								it for you.
+							</DialogDescription>
+						</DialogHeader>
+						<FieldGroup>
+							<Field>
+								<FieldLabel htmlFor={descriptionId}>What should it do?</FieldLabel>
+								<Textarea
+									id={descriptionId}
+									name="description"
+									rows={4}
+									required
+									autoFocus
+									placeholder="e.g. An interactive unit circle that shows sine and cosine as I drag the angle"
+								/>
+							</Field>
+						</FieldGroup>
+						<DialogFooter>
+							<Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+								Cancel
+							</Button>
+							<Button type="submit">Add with AI</Button>
+						</DialogFooter>
+					</form>
+				</DialogContent>
+			) : null}
+		</Dialog>
 	);
 }
diff --git a/src/features/workspaces/operations/workspace-tool-definitions.ts b/src/features/workspaces/operations/workspace-tool-definitions.ts
index bfdbf3e4f..307b8048f 100644
--- a/src/features/workspaces/operations/workspace-tool-definitions.ts
+++ b/src/features/workspaces/operations/workspace-tool-definitions.ts
@@ -214,7 +214,7 @@ export const workspaceToolDefinitions = [
 	defineWorkspaceTool({
 		name: "workspace_create_items",
 		access: "write",
-		description: `Create one or more folders or documents at exact absolute paths. If a path already exists, creation fails instead of renaming. A document is also how interactive work ships: give it a widget block, on its own or alongside prose. ${workspaceDocumentHtmlInstruction}`,
+		description: `Create one or more folders or documents at exact absolute paths. If a path already exists, creation fails instead of renaming. ${workspaceDocumentHtmlInstruction}`,
 		inputSchema: workspaceCreateItemsInputSchema,
 		inputExamples: workspaceCreateItemsInputExamples,
 		outputSchema: workspaceCreateItemsOutputSchema,

From 307c1cd083cdc0c79611d9399b1c7a7487bda4f1 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 14:13:59 -0400
Subject: [PATCH 31/32] test(evals): remove unused content scoring

---
 eval/datasets/workspace-tools.cases.ts |  3 --
 eval/support/harness.ts                |  6 +--
 eval/support/scorers.ts                | 68 --------------------------
 eval/workspace-tools.eval.ts           | 10 ----
 4 files changed, 2 insertions(+), 85 deletions(-)

diff --git a/eval/datasets/workspace-tools.cases.ts b/eval/datasets/workspace-tools.cases.ts
index 8375fea14..2f4edeee9 100644
--- a/eval/datasets/workspace-tools.cases.ts
+++ b/eval/datasets/workspace-tools.cases.ts
@@ -1,5 +1,4 @@
 import type { WorkspaceAgentInput } from "../support/harness";
-import type { ContentCheck } from "../support/scorers";
 
 export interface WorkspaceToolCase {
 	name: string;
@@ -12,8 +11,6 @@ export interface WorkspaceToolCase {
 	qualityRubric?: string;
 	/** When true, the turn must produce a targeted edit whose editRef traces to the read fixture. */
 	requiresTargetedEditFromRead?: boolean;
-	/** Grade what the model wrote — the answer text, or a tool's arguments. */
-	contentChecks?: ContentCheck[];
 }
 
 export const workspaceToolCases: WorkspaceToolCase[] = [
diff --git a/eval/support/harness.ts b/eval/support/harness.ts
index bb95c2dfc..3b31ad02a 100644
--- a/eval/support/harness.ts
+++ b/eval/support/harness.ts
@@ -49,8 +49,6 @@ export interface WorkspaceAgentInput {
 	modelId?: string;
 	/** Whether the turn may mutate; drives the real runtime scope block. */
 	canMutate?: boolean;
-	timeZone?: string;
-	workspaceName?: string;
 }
 
 const STANDUP_PATH = "/Notes/Standup.md";
@@ -178,8 +176,8 @@ export async function runWorkspaceAgent(input: WorkspaceAgentInput): Promise<Wor
 	// harness, not the product.
 	const workspacePrompt = getAIThreadSystemPromptForWorkspace(
 		getAIThreadSoulPrompt(),
-		{ canMutate, workspaceName: input.workspaceName ?? "Study" },
-		{ timeZone: input.timeZone ?? "America/New_York" },
+		{ canMutate, workspaceName: "Study" },
+		{ timeZone: "America/New_York" },
 	);
 
 	const result = await generateText({
diff --git a/eval/support/scorers.ts b/eval/support/scorers.ts
index a38b0a643..8a045a8d8 100644
--- a/eval/support/scorers.ts
+++ b/eval/support/scorers.ts
@@ -110,74 +110,6 @@ export function scoreTargetedEditProvenance(output: WorkspaceAgentOutput): Score
 	};
 }
 
-/**
- * What the model actually *wrote* — the final answer, or the arguments it passed
- * to a tool. Tool choice and schema validity say nothing about authoring dialect:
- * `$x^2$` inside document HTML is schema-valid and renders as literal dollar
- * signs forever, so only a content check can catch it.
- */
-export interface ContentCheck {
-	/** `"text"` grades the final answer; `{ tool }` grades that tool's inputs. */
-	source: "text" | { tool: string };
-	mustMatch?: Array<{ label: string; pattern: RegExp }>;
-	mustNotMatch?: Array<{ label: string; pattern: RegExp }>;
-}
-
-/**
- * Every string the model wrote inside a tool argument, unescaped. Matching
- * against `JSON.stringify(input)` instead would compare patterns like
- * `data-type="inline-math"` against the escaped `data-type=\"inline-math\"` and
- * silently never match — a false failure that looks exactly like a real one.
- */
-function collectStrings(value: unknown, out: string[] = []): string[] {
-	if (typeof value === "string") {
-		out.push(value);
-	} else if (Array.isArray(value)) {
-		for (const item of value) collectStrings(item, out);
-	} else if (value && typeof value === "object") {
-		for (const item of Object.values(value)) collectStrings(item, out);
-	}
-	return out;
-}
-
-export function scoreContent(output: WorkspaceAgentOutput, check: ContentCheck): ScoreResult {
-	const source = check.source;
-	const strings: string[] = [];
-	if (typeof source !== "string") {
-		for (const call of output.toolCalls) {
-			if (call.name === source.tool) collectStrings(call.input, strings);
-		}
-	}
-	const subject = typeof source === "string" ? output.text : strings.join("\n");
-
-	if (!subject.trim()) {
-		const label = typeof check.source === "string" ? "final answer" : `${check.source.tool} input`;
-		return { score: 0, pass: false, message: `no ${label} to grade` };
-	}
-
-	const missing = (check.mustMatch ?? []).filter((rule) => !rule.pattern.test(subject));
-	const present = (check.mustNotMatch ?? []).filter((rule) => rule.pattern.test(subject));
-	const total = (check.mustMatch?.length ?? 0) + (check.mustNotMatch?.length ?? 0);
-	const failures = missing.length + present.length;
-	const reasons = [
-		...missing.map((rule) => `missing ${rule.label}`),
-		...present.map((rule) => `must not contain ${rule.label}`),
-	];
-
-	// Include what was actually written on failure — a dialect miss is only
-	// actionable if you can see the markup the model chose instead.
-	const excerpt = subject.length > 600 ? `${subject.slice(0, 600)}…` : subject;
-
-	return {
-		score: total === 0 ? 1 : 1 - failures / total,
-		pass: failures === 0,
-		message:
-			failures === 0
-				? "content matched every rule"
-				: `${reasons.join("; ")}\n--- wrote: ${excerpt}`,
-	};
-}
-
 const QUALITY_VERDICT_SCHEMA = z.object({
 	pass: z.boolean(),
 	score: z.number().min(0).max(1),
diff --git a/eval/workspace-tools.eval.ts b/eval/workspace-tools.eval.ts
index 875f50fbd..c0b05593c 100644
--- a/eval/workspace-tools.eval.ts
+++ b/eval/workspace-tools.eval.ts
@@ -4,7 +4,6 @@ import { workspaceToolCases } from "./datasets/workspace-tools.cases";
 import { runWorkspaceAgent, type WorkspaceAgentOutput } from "./support/harness";
 import {
 	scoreAnswerQuality,
-	scoreContent,
 	scoreExpectedTools,
 	scoreNoForbiddenTools,
 	scoreTargetedEditProvenance,
@@ -79,15 +78,6 @@ describe.skipIf(!process.env.AI_GATEWAY_API_KEY)("workspace tools", () => {
 			expect(provenance.pass, `edit provenance — ${provenance.message}`).toBe(true);
 		}
 
-		// 2c. Deterministic — what the model actually wrote. Tool choice and schema
-		//     validity cannot see authoring dialect: `$x^2$` in document HTML is
-		//     schema-valid and renders as literal dollar signs forever.
-		for (const check of testCase.contentChecks ?? []) {
-			const target = typeof check.source === "string" ? "answer" : check.source.tool;
-			const content = scoreContent(output, check);
-			expect(content.pass, `content (${target}) — ${content.message}`).toBe(true);
-		}
-
 		// 3. Model-graded — grade the prose answer against a rubric when set.
 		if (testCase.qualityRubric) {
 			const quality = await scoreAnswerQuality({

From 6292f7f69c5eaef057a361104b8228c8926a66cf Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 4 Aug 2026 14:14:07 -0400
Subject: [PATCH 32/32] chore(deps): remove redundant jsdom declaration

---
 package.json   |  1 -
 pnpm-lock.yaml | 78 ++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 57 insertions(+), 22 deletions(-)

diff --git a/package.json b/package.json
index d1d7cd645..9fbd0554d 100644
--- a/package.json
+++ b/package.json
@@ -173,7 +173,6 @@
 		"@voidzero-dev/vite-plus-core": "^0.2.7",
 		"atmn": "^1.1.16",
 		"babel-plugin-react-compiler": "^1.0.0",
-		"jsdom": "^28.1.0",
 		"knip": "^6.31.0",
 		"react-doctor": "0.6.0",
 		"tailwindcss": "^4.3.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a774b72c4..67bd2a7ba 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -350,7 +350,7 @@ importers:
         version: 1.50.0(@voidzero-dev/vite-plus-core@0.2.2(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(typescript@6.0.3)(yaml@2.9.0))(wrangler@4.118.0(@cloudflare/workers-types@5.20260801.1))
       '@cloudflare/vitest-pool-workers':
         specifier: ^0.18.8
-        version: 0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10)
+        version: 0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.2)(@vitest/browser-preview@4.1.10)(@voidzero-dev/vite-plus-core@0.2.2(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(typescript@6.0.3)(yaml@2.9.0))(jsdom@28.1.0(@noble/hashes@2.2.0))(msw@2.14.6(@types/node@26.1.2)(typescript@6.0.3)))
       '@cloudflare/workers-types':
         specifier: ^5.20260801.1
         version: 5.20260801.1
@@ -414,9 +414,6 @@ importers:
       babel-plugin-react-compiler:
         specifier: ^1.0.0
         version: 1.0.0
-      jsdom:
-        specifier: ^28.1.0
-        version: 28.1.0(@noble/hashes@2.2.0)
       knip:
         specifier: ^6.31.0
         version: 6.31.0
@@ -9667,7 +9664,8 @@ packages:
 
 snapshots:
 
-  '@acemir/cssom@0.9.31': {}
+  '@acemir/cssom@0.9.31':
+    optional: true
 
   '@ag-ui/core@0.0.52':
     dependencies:
@@ -9778,6 +9776,7 @@ snapshots:
       '@csstools/css-color-parser': 4.1.10(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)
       '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
       '@csstools/css-tokenizer': 4.0.0
+    optional: true
 
   '@asamuzakjp/dom-selector@6.8.1':
     dependencies:
@@ -9786,10 +9785,13 @@ snapshots:
       css-tree: 3.2.1
       is-potential-custom-element-name: 1.0.1
       lru-cache: 11.5.2
+    optional: true
 
-  '@asamuzakjp/generational-cache@1.0.1': {}
+  '@asamuzakjp/generational-cache@1.0.1':
+    optional: true
 
-  '@asamuzakjp/nwsapi@2.3.9': {}
+  '@asamuzakjp/nwsapi@2.3.9':
+    optional: true
 
   '@babel/code-frame@7.27.1':
     dependencies:
@@ -10186,6 +10188,7 @@ snapshots:
   '@bramus/specificity@2.4.2':
     dependencies:
       css-tree: 3.2.1
+    optional: true
 
   '@cfworker/json-schema@4.1.1': {}
 
@@ -10274,7 +10277,7 @@ snapshots:
       - bufferutil
       - utf-8-validate
 
-  '@cloudflare/vitest-pool-workers@0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10)':
+  '@cloudflare/vitest-pool-workers@0.18.8(@cloudflare/workers-types@5.20260801.1)(@vitest/runner@4.1.10)(@vitest/snapshot@4.1.10)(vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.2)(@vitest/browser-preview@4.1.10)(@voidzero-dev/vite-plus-core@0.2.2(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(typescript@6.0.3)(yaml@2.9.0))(jsdom@28.1.0(@noble/hashes@2.2.0))(msw@2.14.6(@types/node@26.1.2)(typescript@6.0.3)))':
     dependencies:
       '@vitest/runner': 4.1.10
       '@vitest/snapshot': 4.1.10
@@ -10471,12 +10474,14 @@ snapshots:
     dependencies:
       '@jridgewell/trace-mapping': 0.3.9
 
-  '@csstools/color-helpers@6.1.0': {}
+  '@csstools/color-helpers@6.1.0':
+    optional: true
 
   '@csstools/css-calc@3.3.0(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)':
     dependencies:
       '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
       '@csstools/css-tokenizer': 4.0.0
+    optional: true
 
   '@csstools/css-color-parser@4.1.10(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)':
     dependencies:
@@ -10484,16 +10489,20 @@ snapshots:
       '@csstools/css-calc': 3.3.0(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)
       '@csstools/css-parser-algorithms': 4.0.0(@csstools/css-tokenizer@4.0.0)
       '@csstools/css-tokenizer': 4.0.0
+    optional: true
 
   '@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0)':
     dependencies:
       '@csstools/css-tokenizer': 4.0.0
+    optional: true
 
   '@csstools/css-syntax-patches-for-csstree@1.1.7(css-tree@3.2.1)':
     optionalDependencies:
       css-tree: 3.2.1
+    optional: true
 
-  '@csstools/css-tokenizer@4.0.0': {}
+  '@csstools/css-tokenizer@4.0.0':
+    optional: true
 
   '@date-fns/tz@1.5.0':
     optional: true
@@ -11004,6 +11013,7 @@ snapshots:
   '@exodus/bytes@1.15.1(@noble/hashes@2.2.0)':
     optionalDependencies:
       '@noble/hashes': 2.2.0
+    optional: true
 
   '@floating-ui/core@1.8.0':
     dependencies:
@@ -13699,7 +13709,8 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  agent-base@7.1.4: {}
+  agent-base@7.1.4:
+    optional: true
 
   agent-install@0.0.5:
     dependencies:
@@ -13968,6 +13979,7 @@ snapshots:
   bidi-js@1.0.3:
     dependencies:
       require-from-string: 2.0.2
+    optional: true
 
   bl@4.1.0:
     dependencies:
@@ -14330,6 +14342,7 @@ snapshots:
     dependencies:
       mdn-data: 2.27.1
       source-map-js: 1.2.1
+    optional: true
 
   css-what@8.0.0: {}
 
@@ -14343,6 +14356,7 @@ snapshots:
       '@csstools/css-syntax-patches-for-csstree': 1.1.7(css-tree@3.2.1)
       css-tree: 3.2.1
       lru-cache: 11.5.2
+    optional: true
 
   csstype@3.2.3: {}
 
@@ -14536,6 +14550,7 @@ snapshots:
       whatwg-url: 16.0.1(@noble/hashes@2.2.0)
     transitivePeerDependencies:
       - '@noble/hashes'
+    optional: true
 
   date-fns@4.3.0:
     optional: true
@@ -14554,7 +14569,8 @@ snapshots:
     dependencies:
       ms: 2.1.3
 
-  decimal.js@10.6.0: {}
+  decimal.js@10.6.0:
+    optional: true
 
   decode-named-character-reference@1.3.0:
     dependencies:
@@ -15446,6 +15462,7 @@ snapshots:
       '@exodus/bytes': 1.15.1(@noble/hashes@2.2.0)
     transitivePeerDependencies:
       - '@noble/hashes'
+    optional: true
 
   html-escaper@3.0.3: {}
 
@@ -15474,6 +15491,7 @@ snapshots:
       debug: 4.4.3
     transitivePeerDependencies:
       - supports-color
+    optional: true
 
   https-proxy-agent@5.0.1:
     dependencies:
@@ -15488,6 +15506,7 @@ snapshots:
       debug: 4.4.3
     transitivePeerDependencies:
       - supports-color
+    optional: true
 
   human-signals@2.1.0: {}
 
@@ -15727,7 +15746,8 @@ snapshots:
 
   is-plain-obj@4.1.0: {}
 
-  is-potential-custom-element-name@1.0.1: {}
+  is-potential-custom-element-name@1.0.1:
+    optional: true
 
   is-promise@4.0.0: {}
 
@@ -15836,6 +15856,7 @@ snapshots:
     transitivePeerDependencies:
       - '@noble/hashes'
       - supports-color
+    optional: true
 
   jsesc@3.1.0: {}
 
@@ -16082,7 +16103,8 @@ snapshots:
     dependencies:
       js-tokens: 4.0.0
 
-  lru-cache@11.5.2: {}
+  lru-cache@11.5.2:
+    optional: true
 
   lru-cache@5.1.1:
     dependencies:
@@ -16305,7 +16327,8 @@ snapshots:
     dependencies:
       '@types/mdast': 4.0.4
 
-  mdn-data@2.27.1: {}
+  mdn-data@2.27.1:
+    optional: true
 
   media-typer@1.1.1: {}
 
@@ -17101,6 +17124,7 @@ snapshots:
   parse5@8.0.1:
     dependencies:
       entities: 8.0.0
+    optional: true
 
   parseurl@1.3.3: {}
 
@@ -17777,6 +17801,7 @@ snapshots:
   saxes@6.0.0:
     dependencies:
       xmlchars: 2.2.0
+    optional: true
 
   scheduler@0.27.0: {}
 
@@ -18197,7 +18222,8 @@ snapshots:
       react: 19.2.8
       use-sync-external-store: 1.6.0(react@19.2.8)
 
-  symbol-tree@3.2.4: {}
+  symbol-tree@3.2.4:
+    optional: true
 
   system-architecture@0.1.0: {}
 
@@ -18247,11 +18273,13 @@ snapshots:
 
   tinyrainbow@3.1.1: {}
 
-  tldts-core@7.4.10: {}
+  tldts-core@7.4.10:
+    optional: true
 
   tldts@7.4.10:
     dependencies:
       tldts-core: 7.4.10
+    optional: true
 
   to-buffer@1.2.2:
     dependencies:
@@ -18278,10 +18306,12 @@ snapshots:
   tough-cookie@6.0.2:
     dependencies:
       tldts: 7.4.10
+    optional: true
 
   tr46@6.0.0:
     dependencies:
       punycode: 2.3.1
+    optional: true
 
   trim-lines@3.0.1: {}
 
@@ -18599,6 +18629,7 @@ snapshots:
   w3c-xmlserializer@5.0.0:
     dependencies:
       xml-name-validator: 5.0.0
+    optional: true
 
   walk-up-path@4.0.0: {}
 
@@ -18606,11 +18637,13 @@ snapshots:
 
   web-vitals@5.3.0: {}
 
-  webidl-conversions@8.0.1: {}
+  webidl-conversions@8.0.1:
+    optional: true
 
   webpack-virtual-modules@0.6.2: {}
 
-  whatwg-mimetype@5.0.0: {}
+  whatwg-mimetype@5.0.0:
+    optional: true
 
   whatwg-url@16.0.1(@noble/hashes@2.2.0):
     dependencies:
@@ -18619,6 +18652,7 @@ snapshots:
       webidl-conversions: 8.0.1
     transitivePeerDependencies:
       - '@noble/hashes'
+    optional: true
 
   when-exit@2.1.5: {}
 
@@ -18747,7 +18781,8 @@ snapshots:
       is-wsl: 3.1.1
       powershell-utils: 0.1.0
 
-  xml-name-validator@5.0.0: {}
+  xml-name-validator@5.0.0:
+    optional: true
 
   xml-naming@0.3.0: {}
 
@@ -18758,7 +18793,8 @@ snapshots:
       '@oozcitak/util': 10.0.0
       js-yaml: 4.3.1
 
-  xmlchars@2.2.0: {}
+  xmlchars@2.2.0:
+    optional: true
 
   xtend@4.0.2:
     optional: true