pmx-canvas 0.1.18 → 0.1.20

package/docs/sdk.md

@@ -0,0 +1,103 @@
+# JavaScript/TypeScript SDK (Bun runtime)
+
+The published SDK entrypoint is Bun-first. Node.js consumers should use the
+[CLI](cli.md), [MCP server](mcp.md), or [HTTP API](http-api.md) instead.
+
+```bash
+bun add pmx-canvas
+```
+
+## Quick example
+
+```ts
+import { createCanvas } from 'pmx-canvas';
+
+const canvas = createCanvas({ port: 4313 });
+await canvas.start({ open: true });
+
+// Add nodes
+const n1 = canvas.addNode({ type: 'markdown', title: 'Plan', content: '# Step 1\nDo the thing.' });
+const n2 = canvas.addNode({ type: 'status', title: 'Build', content: 'passing' });
+const n3 = canvas.addNode({ type: 'file', content: 'src/index.ts' });
+
+// Connect them
+canvas.addEdge({ from: n1, to: n2, type: 'flow' });
+
+// Group related nodes
+canvas.createGroup({ title: 'Build Pipeline', childIds: [n1, n2] });
+
+// Self-contained HTML in a sandboxed iframe
+canvas.addHtmlNode({
+  title: 'Cost projection',
+  html: '<canvas id="c"></canvas><script src="https://cdn.jsdelivr.net/npm/chart.js"></script><script>/* ... */</script>',
+});
+
+// Generated HTML communication primitive, stored as a sandboxed html node
+canvas.addHtmlPrimitive({
+  kind: 'choice-grid',
+  title: 'Implementation options',
+  data: {
+    items: [
+      { title: 'Small patch', summary: 'Least disruption.', pros: ['Fast'], cons: ['Less flexible'] },
+    ],
+  },
+});
+
+// Hand-drawn diagram via the Excalidraw MCP-app preset
+await canvas.addDiagram({
+  elements: [
+    { type: 'rectangle', id: 'r1', x: 80, y: 80, width: 160, height: 60,
+      roundness: { type: 3 }, backgroundColor: '#a5d8ff', fillStyle: 'solid',
+      label: { text: 'Agent' } },
+  ],
+  title: 'Quick sketch',
+});
+
+// Batch-build a graph and group around it
+await canvas.runBatch([
+  {
+    op: 'graph.add',
+    assign: 'graph',
+    args: {
+      title: 'Major wins',
+      graphType: 'bar',
+      data: [
+        { label: 'Docs', value: 5 },
+        { label: 'Tests', value: 8 },
+      ],
+      xKey: 'label',
+      yKey: 'value',
+    },
+  },
+  {
+    op: 'group.create',
+    args: {
+      title: 'Quarterly graphs',
+      childIds: ['$graph.id'],
+    },
+  },
+]);
+
+// Arrange and inspect
+canvas.arrange('grid');
+console.log(canvas.validate());
+console.log(canvas.getLayout());
+```
+
+## WebView automation
+
+```ts
+const webview = await canvas.startAutomationWebView({ backend: 'chrome', width: 1280, height: 800 });
+console.log(webview.active);
+console.log(await canvas.evaluateAutomationWebView('document.title'));
+await canvas.resizeAutomationWebView(1440, 900);
+const screenshot = await canvas.screenshotAutomationWebView({ format: 'png' });
+console.log(screenshot.byteLength);
+await canvas.stopAutomationWebView();
+```
+
+## See also
+
+- [Node types](node-types.md) — what each node type is for
+- [HTTP API](http-api.md) — the same operations from any language
+- [MCP reference](mcp.md) — the agent-facing surface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",
@@ -18,6 +18,7 @@
   "files": [
     "src/",
     "skills/",
+    "docs/",
     "dist/canvas/",
     "dist/json-render/",
     "dist/types/",

package/skills/pmx-canvas/SKILL.md

@@ -270,6 +270,7 @@ MCP node-type routing:
 | Basic nodes (`markdown`, `status`, `context`, `ledger`, `trace`, `file`, `image`, `webpage`) | `canvas_add_node` |
 | `json-render` | `canvas_add_json_render_node` |
 | `graph` | `canvas_add_graph_node` |
+| `html-primitive` | `canvas_add_html_primitive` |
 | `html` | `canvas_add_html_node` |
 | `web-artifact` | `canvas_build_web_artifact` |
 | `external-app` / tool-backed `mcp-app` | `canvas_open_mcp_app` |
@@ -659,6 +660,12 @@ server's `ui://` resource as an iframe node on the canvas
 - Canvas theme tokens are auto-injected as CSS custom properties (both `--c-*` and common `--color-*` aliases such as `--color-text-primary`, `--color-bg`, `--color-accent`) so authored HTML inherits the active theme
 - Use for moderate-complexity visualizations and interactive widgets that need real JS but do not warrant a full React build (Chart.js demos, D3 sketches, custom HTML report views)
 
+**`canvas_add_html_primitive`** — Generate a reusable HTML communication primitive as a sandboxed `html` node
+- Required: `kind`; run `canvas_describe_schema` and read `htmlPrimitives` for the current catalog
+- Optional: `title`, `data`, `x`, `y`, `width`, `height`, `strictSize`
+- Use when markdown would be too dense and a structured visual artifact is clearer: tradeoff grids, implementation plans, PR reviews, module maps, design sheets, explainers, reports, and lightweight human-editable boards/editors
+- Read `htmlPrimitives` from `canvas_describe_schema` for the data shape and examples before constructing a payload
+
 ### Choosing the Right Visual Tier
 
 When the output is more than markdown, pick the lightest tier that fits:
@@ -666,6 +673,7 @@ When the output is more than markdown, pick the lightest tier that fits:
 | Tier | Tool | Build cost | When to pick it |
 |------|------|------------|-----------------|
 | Declarative UI | `canvas_add_json_render_node` / `canvas_add_graph_node` | None | Schema-driven dashboards, forms, charts; agent-friendly to read back via `canvas_get_node` |
+| Generated HTML primitive | `canvas_add_html_primitive` | None | Reusable communication artifacts such as choices, plans, reviews, maps, reports, decks, and lightweight editors |
 | Sandboxed HTML+JS | `canvas_add_html_node` | None | Self-contained HTML with inline JS or CDN scripts; one-off visualizations or report views |
 | Hosted MCP app | `canvas_open_mcp_app` / `canvas_add_diagram` | None | Interactive editors backed by an external MCP server (e.g. Excalidraw) |
 | Bundled React app | `canvas_build_web_artifact` | Heavy (npm install + bundle) | Multi-component UIs needing React state, routing, shadcn/ui, or Tailwind class composition |

package/src/cli/agent.ts

@@ -73,6 +73,15 @@ interface CanvasSchemaResponse {
       'line' | 'bar' | 'pie' | 'area' | 'scatter' | 'radar' | 'stacked-bar' | 'composed'
     >;
   };
+  htmlPrimitives?: Array<{
+    kind: string;
+    title: string;
+    description: string;
+    useWhen: string;
+    defaultSize: { width: number; height: number };
+    dataShape: string;
+    example: Record<string, unknown>;
+  }>;
   mcp: {
     tools: string[];
     resources: string[];
@@ -480,6 +489,14 @@ function parseJsonValue(raw: string, label: string, hint: string): unknown {
   }
 }
 
+function parseJsonRecord(raw: string, label: string, hint: string): Record<string, unknown> {
+  const parsed = parseJsonValue(raw, label, hint);
+  if (!isRecord(parsed)) {
+    die(`${label} must be a JSON object.`, hint);
+  }
+  return parsed;
+}
+
 async function readTextInput(
   flags: Record<string, string | true>,
   options: {
@@ -615,6 +632,34 @@ async function buildJsonRenderRequestBody(
   return body;
 }
 
+async function buildHtmlPrimitiveRequestBody(
+  flags: Record<string, string | true>,
+): Promise<Record<string, unknown>> {
+  const hint = 'Use: pmx-canvas html primitive add --kind choice-grid --data-file ./primitive.json --title "Options"';
+  const kind = getStringFlag(flags, 'kind', 'primitive');
+  if (!kind) die('HTML primitives require --kind.', hint);
+  const body: Record<string, unknown> = { type: 'html', primitive: kind };
+  if (typeof flags.title === 'string') body.title = flags.title;
+  const rawData = await readOptionalTextInput(flags, {
+    fileFlags: ['data-file'],
+    valueFlags: ['data-json', 'data'],
+    allowStdin: true,
+    label: 'HTML primitive data',
+    hint,
+  });
+  if (rawData !== undefined) {
+    body.data = parseJsonRecord(rawData, 'HTML primitive data', hint);
+  }
+  applyCommonGeometryFlags(body, flags, {
+    x: 'Use a finite number, e.g. --x 500',
+    y: 'Use a finite number, e.g. --y 300',
+    width: 'Use a positive number, e.g. --width 980',
+    height: 'Use a positive number, e.g. --height 720',
+  });
+  applyStrictSizeFlags(body, flags);
+  return body;
+}
+
 async function buildGraphRequestBody(
   flags: Record<string, string | true>,
   options: { requireData?: boolean; allowStdin?: boolean } = {},
@@ -967,6 +1012,35 @@ function filterJsonRenderSchemaView(
   return flags.summary ? summarizeJsonRenderComponent(component) : component;
 }
 
+function summarizeHtmlPrimitive(primitive: NonNullable<CanvasSchemaResponse['htmlPrimitives']>[number]): Record<string, unknown> {
+  return {
+    kind: primitive.kind,
+    title: primitive.title,
+    description: primitive.description,
+    useWhen: primitive.useWhen,
+    defaultSize: primitive.defaultSize,
+    dataShape: primitive.dataShape,
+  };
+}
+
+function filterHtmlPrimitiveSchemaView(
+  schema: CanvasSchemaResponse,
+  flags: Record<string, string | true>,
+): Record<string, unknown> {
+  const primitives = schema.htmlPrimitives ?? [];
+  const kind = getStringFlag(flags, 'kind', 'primitive');
+  if (!kind) {
+    return {
+      primitives: flags.summary ? primitives.map((entry) => summarizeHtmlPrimitive(entry)) : primitives,
+    };
+  }
+  const primitive = primitives.find((entry) => entry.kind === kind);
+  if (!primitive) {
+    die(`Unknown HTML primitive: ${kind}`, 'Run: pmx-canvas html primitive schema --summary');
+  }
+  return flags.summary ? summarizeHtmlPrimitive(primitive) : primitive;
+}
+
 // ── Commands ─────────────────────────────────────────────────
 
 const COMMANDS: Record<string, { run: (args: string[]) => Promise<void>; help: string; examples: string[] }> = {};
@@ -1028,6 +1102,7 @@ cmd('node add', 'Add a node to the canvas', [
   'pmx-canvas node add --type file --content "src/index.ts"',
   'pmx-canvas node add --type webpage --url "https://example.com/docs"',
   'pmx-canvas node add --type html --title "Widget" --content "<main>Hello</main>"',
+  'pmx-canvas node add --type html --primitive choice-grid --data-file ./options.json --title "Options"',
   'pmx-canvas node add --type markdown --title "Note" --x 100 --y 200',
   'pmx-canvas node add --type json-render --title "Ops Dashboard" --spec-file ./dashboard.json',
   'pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value',
@@ -1055,6 +1130,18 @@ cmd('node add', 'Add a node to the canvas', [
     return;
   }
 
+  if (type === 'html-primitive') {
+    const result = await api('POST', '/api/canvas/node', await buildHtmlPrimitiveRequestBody(flags));
+    output(result);
+    return;
+  }
+
+  if (type === 'html' && getStringFlag(flags, 'primitive', 'kind')) {
+    const result = await api('POST', '/api/canvas/node', await buildHtmlPrimitiveRequestBody(flags));
+    output(result);
+    return;
+  }
+
   if (type === 'mcp-app') {
     die(
       'mcp-app nodes require tool-backed app metadata and cannot be created with generic node add.',
@@ -1136,6 +1223,28 @@ cmd('json-render', 'Show json-render schema and canonical examples', [
   output(filterJsonRenderSchemaView(schema.jsonRender, flags));
 });
 
+cmd('html primitive add', 'Create a reusable sandboxed HTML communication primitive', [
+  'pmx-canvas html primitive add --kind choice-grid --data-file ./options.json --title "Options"',
+  'pmx-canvas html primitive add --kind plan-timeline --data-json \'{"milestones":[{"title":"Ship","detail":"Implement and verify","status":"next"}]}\'',
+  'pmx-canvas html primitive add --kind triage-board --data-file ./tickets.json --strict-size',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('html primitive add');
+  const result = await api('POST', '/api/canvas/node', await buildHtmlPrimitiveRequestBody(flags));
+  output(result);
+});
+
+cmd('html primitive schema', 'Describe reusable HTML communication primitives', [
+  'pmx-canvas html primitive schema --summary',
+  'pmx-canvas html primitive schema --kind choice-grid',
+  'pmx-canvas html primitive schema --kind triage-board --summary',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('html primitive schema');
+  const schema = await loadCanvasSchema();
+  output(filterHtmlPrimitiveSchemaView(schema, flags));
+});
+
 cmd('graph add', 'Add a graph node to the canvas', [
   'pmx-canvas graph add --graph-type bar --data-file ./metrics.json --x-key label --y-key value',
   'pmx-canvas graph add --graphType composed --data \'[{"day":"Mon","visits":10,"conversion":0.4}]\' --xKey day --barKey visits --lineKey conversion',
@@ -1176,6 +1285,7 @@ cmd('node schema', 'Describe server-supported node create schemas and canonical
           rootShape: result.jsonRender.rootShape,
         },
         graph: result.graph,
+        htmlPrimitives: result.htmlPrimitives?.map((entry) => summarizeHtmlPrimitive(entry)) ?? [],
         mcp: result.mcp,
       });
       return;
@@ -1698,6 +1808,7 @@ cmd('snapshot save', 'Save a named snapshot of the current canvas', [
 cmd('snapshot list', 'List saved snapshots', [
   'pmx-canvas snapshot list',
   'pmx-canvas snapshot list --limit 50 --query baseline',
+  'pmx-canvas snapshot list --after 2026-05-01T00:00:00Z --before 2026-05-05T00:00:00Z',
   'pmx-canvas snapshot list --all',
 ], async (args) => {
   const { flags } = parseFlags(args);
@@ -1706,8 +1817,12 @@ cmd('snapshot list', 'List saved snapshots', [
   const params = new URLSearchParams();
   const limit = optionalNumberFlag(flags, 'limit', 'Use a positive integer, e.g. --limit 50');
   const query = getStringFlag(flags, 'query', 'q');
+  const before = getStringFlag(flags, 'before');
+  const after = getStringFlag(flags, 'after');
   if (limit !== undefined) params.set('limit', String(limit));
   if (query) params.set('q', query);
+  if (before) params.set('before', before);
+  if (after) params.set('after', after);
   if (flags.all) params.set('all', 'true');
   const result = await api('GET', `/api/canvas/snapshots${params.size > 0 ? `?${params.toString()}` : ''}`);
   output(result);
@@ -1893,19 +2008,31 @@ cmd('validate', 'Validate the current layout for collisions and missing edge end
 cmd('validate spec', 'Validate a json-render spec or graph payload without creating a node', [
   'pmx-canvas validate spec --type json-render --spec-file ./dashboard.json',
   'pmx-canvas validate spec --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value',
+  'pmx-canvas validate spec --type html-primitive --kind choice-grid --data-file ./options.json',
   'pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary',
 ], async (args) => {
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('validate spec');
 
   const type = getStringFlag(flags, 'type');
-  if (type !== 'json-render' && type !== 'graph') {
-    die('validate spec requires --type json-render or --type graph.');
+  if (type !== 'json-render' && type !== 'graph' && type !== 'html-primitive') {
+    die('validate spec requires --type json-render, --type graph, or --type html-primitive.');
   }
 
-  const body = type === 'json-render'
-    ? { type, spec: (await buildJsonRenderRequestBody({ ...flags, title: String(flags.title ?? 'Validation') })).spec }
-    : { type, ...(await buildGraphRequestBody(flags)) };
+  let body: Record<string, unknown>;
+  if (type === 'json-render') {
+    body = { type, spec: (await buildJsonRenderRequestBody({ ...flags, title: String(flags.title ?? 'Validation') })).spec };
+  } else if (type === 'html-primitive') {
+    const primitiveBody = await buildHtmlPrimitiveRequestBody(flags);
+    body = {
+      type,
+      kind: primitiveBody.primitive,
+      ...(typeof primitiveBody.title === 'string' ? { title: primitiveBody.title } : {}),
+      ...(isRecord(primitiveBody.data) ? { data: primitiveBody.data } : {}),
+    };
+  } else {
+    body = { type, ...(await buildGraphRequestBody(flags)) };
+  }
 
   const result = await api('POST', '/api/canvas/schema/validate', body) as Record<string, unknown>;
   if (flags.summary) {
@@ -2297,9 +2424,17 @@ function showCommandHelp(name: string): void {
     console.log('  pmx-canvas node add --help --type webpage');
     console.log('  pmx-canvas node add --help --type json-render --component Table');
     console.log('  pmx-canvas node add --help --type graph');
+    console.log('  pmx-canvas html primitive schema --summary');
     console.log('  pmx-canvas node add --help --type webpage --json');
     console.log('  Use --strict-size to keep explicit width/height fixed and scroll overflowing content.');
   }
+  if (name === 'html primitive add' || name === 'html primitive schema') {
+    console.log('\nPrimitive flags:');
+    console.log('  --kind <name>              Run `pmx-canvas html primitive schema --summary` for the full catalog');
+    console.log('  --data-file <path>         JSON object payload for the primitive');
+    console.log('  --data-json, --data <json> Inline JSON object payload');
+    console.log('  --stdin                    Read JSON object payload from stdin');
+  }
   if (name === 'json-render') {
     console.log('\nOptions:');
     console.log('  --schema                  Show json-render catalog schema (default)');
@@ -2314,6 +2449,10 @@ function showCommandHelp(name: string): void {
     console.log('  Use --node-height/--nodeHeight for canvas frame height; use --chart-height for chart content height. --height is kept as a frame-height alias for compatibility.');
     console.log('  Pass --show-legend false to hide legends in compact node layouts.');
   }
+  if (name === 'validate spec') {
+    console.log('\nHTML primitive flags:');
+    console.log('  --type html-primitive --kind <name> --data-file ./payload.json');
+  }
   if (name === 'node schema') {
     console.log('\nFilters:');
     console.log('  --summary                 Show compact schema summaries');
@@ -2323,13 +2462,26 @@ function showCommandHelp(name: string): void {
   if (name === 'validate spec') {
     console.log('\nOutput control:');
     console.log('  --summary                 Return only validation summary metadata');
+    console.log('  For --type html-primitive, pass --kind plus optional --data-file/--data-json.');
   }
   if (name === 'snapshot list') {
     console.log('\nOptions:');
     console.log('  --limit <number>          Maximum snapshots to return (default 20)');
     console.log('  --query <text>            Case-insensitive ID/name filter');
+    console.log('  --before <timestamp>      Only return snapshots created at or before this ISO timestamp');
+    console.log('  --after <timestamp>       Only return snapshots created at or after this ISO timestamp');
     console.log('  --all                     Return all snapshots');
   }
+  if (name === 'node update') {
+    console.log('\nTrace fields:');
+    console.log('  --tool-name, --toolName   Trace tool or operation label');
+    console.log('  --category <name>         Trace category, e.g. mcp, file, subagent, other');
+    console.log('  --status <status>         Trace status, e.g. running, success, failed');
+    console.log('  --duration <text>         Trace duration badge text');
+    console.log('  --result-summary, --resultSummary <text>');
+    console.log('                            Trace result summary');
+    console.log('  --error <text>            Trace error message');
+  }
   if (name === 'snapshot gc') {
     console.log('\nOptions:');
     console.log('  --keep <number>           Number of newest snapshots to keep (default 20)');
@@ -2398,6 +2550,8 @@ Node commands:
   pmx-canvas node remove <id>         Remove a node
   pmx-canvas json-render              Show json-render schema/examples
   pmx-canvas graph add [options]      Add a graph node
+  pmx-canvas html primitive add        Add an HTML communication primitive
+  pmx-canvas html primitive schema     List HTML primitive kinds and shapes
 
 Edge commands:
   pmx-canvas edge add [options]       Add an edge between nodes
@@ -2471,6 +2625,8 @@ Examples:
   pmx-canvas node add --type web-artifact --title "Dashboard" --app-file ./App.tsx
   pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value
   pmx-canvas graph add --graph-type bar --data-file ./metrics.json --x-key label --y-key value
+  pmx-canvas html primitive add --kind choice-grid --data-file ./options.json --title "Options"
+  pmx-canvas html primitive schema --summary
   pmx-canvas node add --help --type webpage
   pmx-canvas node schema --type json-render
   pmx-canvas node schema --type json-render --component Table --summary
@@ -2517,6 +2673,12 @@ export async function runAgentCli(args: string[]): Promise<void> {
     return;
   }
 
+  const threeWord = `${args[0]} ${args[1] ?? ''} ${args[2] ?? ''}`.trim();
+  if (COMMANDS[threeWord]) {
+    await COMMANDS[threeWord].run(args.slice(3));
+    return;
+  }
+
   // Try two-word command first (e.g., "node add"), then one-word (e.g., "search")
   const twoWord = `${args[0]} ${args[1] ?? ''}`.trim();
   if (COMMANDS[twoWord]) {

package/src/client/App.tsx

@@ -52,6 +52,7 @@ import {
   IconShortcuts,
   IconSnapshot,
   IconSun,
+  IconTextAnnotation,
   IconTrace,
   IconZoomIn,
   IconZoomOut,
@@ -73,7 +74,7 @@ function sendIntent(type: string, payload: Record<string, unknown> = {}): void {
   });
 }
 
-type AnnotationTool = 'pen' | 'eraser' | null;
+type AnnotationTool = 'pen' | 'eraser' | 'text' | null;
 
 function ToolbarHint({
   label,
@@ -115,6 +116,7 @@ function Toolbar({
   annotationTool,
   onToggleAnnotationMode,
   onToggleAnnotationEraser,
+  onToggleTextAnnotation,
 }: {
   minimapVisible: boolean;
   onToggleMinimap: () => void;
@@ -126,6 +128,7 @@ function Toolbar({
   annotationTool: AnnotationTool;
   onToggleAnnotationMode: () => void;
   onToggleAnnotationEraser: () => void;
+  onToggleTextAnnotation: () => void;
 }) {
   const status = connectionStatus.value;
   const hasSynced = hasInitialServerLayout.value;
@@ -316,6 +319,20 @@ function Toolbar({
             <IconEraser />
           </button>
         </ToolbarHint>
+        <ToolbarHint
+          label={annotationTool === 'text' ? 'Stop text annotations' : 'Text annotations'}
+          detail="Click anywhere to type an intent note"
+        >
+          <button
+            type="button"
+            onClick={onToggleTextAnnotation}
+            aria-label={annotationTool === 'text' ? 'Stop text annotations' : 'Text annotations'}
+            aria-pressed={annotationTool === 'text'}
+            style={{ color: annotationTool === 'text' ? 'var(--c-accent)' : undefined }}
+          >
+            <IconTextAnnotation />
+          </button>
+        </ToolbarHint>
 
         <div class="separator" />
 
@@ -392,6 +409,7 @@ export function App() {
   const handleCloseSnapshot = useCallback(() => setSnapshotOpen(false), []);
   const handleToggleAnnotationMode = useCallback(() => setAnnotationTool((tool) => tool === 'pen' ? null : 'pen'), []);
   const handleToggleAnnotationEraser = useCallback(() => setAnnotationTool((tool) => tool === 'eraser' ? null : 'eraser'), []);
+  const handleToggleTextAnnotation = useCallback(() => setAnnotationTool((tool) => tool === 'text' ? null : 'text'), []);
 
   const handleMinimapNavigate = useCallback((x: number, y: number) => {
     animateViewport({ x, y, scale: viewport.value.scale }, 200);
@@ -520,6 +538,7 @@ export function App() {
           annotationTool={annotationTool}
           onToggleAnnotationMode={handleToggleAnnotationMode}
           onToggleAnnotationEraser={handleToggleAnnotationEraser}
+          onToggleTextAnnotation={handleToggleTextAnnotation}
         />
         <div class="hud-right">
           {dockedRight.map((n) => (

package/src/client/canvas/AnnotationLayer.tsx

@@ -11,18 +11,39 @@ export function AnnotationLayer({ annotations }: { annotations: CanvasAnnotation
 
   return (
     <svg class="annotation-layer" aria-hidden="true">
-      {annotations.map((annotation) => (
-        <path
-          key={annotation.id}
-          d={pointsToPath(annotation.points)}
-          fill="none"
-          stroke={annotation.color === 'currentColor' ? 'var(--c-annotation)' : annotation.color}
-          stroke-width={annotation.width}
-          stroke-linecap="round"
-          stroke-linejoin="round"
-          opacity="0.9"
-        />
-      ))}
+      {annotations.map((annotation) => {
+        const color = annotation.color === 'currentColor' ? 'var(--c-annotation)' : annotation.color;
+        if (annotation.type === 'text') {
+          const point = annotation.points[0];
+          if (!point || !annotation.text) return null;
+          return (
+            <text
+              key={annotation.id}
+              x={point.x}
+              y={point.y}
+              fill={color}
+              font-size={annotation.width}
+              font-family="var(--font)"
+              font-weight="700"
+              opacity="0.95"
+            >
+              {annotation.text}
+            </text>
+          );
+        }
+        return (
+          <path
+            key={annotation.id}
+            d={pointsToPath(annotation.points)}
+            fill="none"
+            stroke={color}
+            stroke-width={annotation.width}
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            opacity="0.9"
+          />
+        );
+      })}
     </svg>
   );
 }