pmx-canvas 0.1.19 → 0.1.21

package/skills/pmx-canvas/references/html-primitives.md

@@ -0,0 +1,132 @@
+# HTML Primitive Authoring
+
+Use this guide when creating reusable sandboxed HTML communication primitives through
+`canvas_add_html_primitive` or `pmx-canvas html primitive add`.
+
+## What They Are
+
+HTML primitives are generated `html` nodes. PMX Canvas stores the generated HTML in the normal
+sandboxed iframe node, plus metadata describing the primitive kind and source data.
+
+- Use them when markdown becomes too dense but a full React web artifact would be too heavy.
+- Prefer them for communication artifacts: choices, plans, reviews, maps, explainers, reports,
+  lightweight editors, and handoff boards.
+- Keep using `canvas_add_html_node` for bespoke one-off HTML and JS.
+- Keep using `canvas_build_web_artifact` for multi-component apps, routing, React state, or shadcn UI.
+
+The design language is inspired by high-density HTML communication patterns: strong hierarchy,
+metric cards, sticky context panels, annotated snippets, inline SVG figures, and copy/export actions.
+Do not copy upstream demo HTML verbatim; use the PMX primitive catalog and data shapes instead.
+
+## Current Catalog
+
+| Kind | Best use |
+|------|----------|
+| `choice-grid` | Side-by-side options with pros, cons, tradeoffs, and evidence |
+| `plan-timeline` | Sequenced implementation plans with risks, flow, and checkpoints |
+| `review-sheet` | PR or code review findings with severity, file, line, and diff context |
+| `pr-writeup` | Reviewer-ready PR narrative with motivation, file tour, tests, and rollout |
+| `system-map` | Architecture/module maps with entry points and relationships |
+| `code-walkthrough` | Guided source-path explanations with ordered steps and snippets |
+| `design-sheet` | Visual directions, palettes, tokens, type samples, and rationale |
+| `component-gallery` | Component variants, states, sizes, and accessibility notes |
+| `interaction-prototype` | Throwaway interaction or motion studies with live controls |
+| `flowchart` | Process, journey, pipeline, and failure-path diagrams |
+| `deck` | Compact arrow-key narrative decks with speaker notes |
+| `presentation` | Fullscreen-ready PowerPoint-like slide decks for briefings and pitches |
+| `illustration-set` | Inline SVG figure sheets with captions and SVG copy/export |
+| `explainer` | Feature or algorithm explainers with TLDR, steps, FAQ, and glossary |
+| `status-report` | Skimmable project health with metrics, shipped/slipped lists, and next actions |
+| `incident-report` | Incident summaries with impact, timeline, root cause, logs, and action items |
+| `triage-board` | Human-reorderable Now/Next/Later/Cut boards with markdown export |
+| `config-editor` | Feature flag or config editors with dependency warnings and diff export |
+| `prompt-tuner` | Prompt/template editors with variable previews and copy export |
+
+## Request Shape
+
+Use the running server as the source of truth before constructing data payloads:
+
+```bash
+pmx-canvas html primitive schema --summary
+pmx-canvas html primitive schema --kind explainer
+```
+
+MCP shape:
+
+```json
+{
+  "kind": "explainer",
+  "title": "HTML Primitives",
+  "data": {
+    "summary": "Reusable generated HTML nodes for rich agent-to-human communication.",
+    "steps": [
+      { "title": "Pick a primitive", "detail": "Match the work product to the catalog kind." }
+    ]
+  },
+  "x": 120,
+  "y": 80,
+  "width": 980,
+  "height": 760
+}
+```
+
+CLI shape:
+
+```bash
+pmx-canvas html primitive add \
+  --kind choice-grid \
+  --title "Implementation Options" \
+  --data-json '{"items":[{"title":"Small patch","summary":"Least disruption","tradeoff":"Limited future flexibility","pros":["Fast"],"cons":["May need follow-up"]}]}'
+```
+
+Important details:
+
+- `kind` is required.
+- `title`, `data`, `x`, `y`, `width`, `height`, and `strictSize` are optional.
+- The persisted node type is `html`, not a separate durable `html-primitive` node type.
+- `html-primitive` is accepted by schema validation and convenience creation paths as a virtual type.
+- Batch `node.add` does not create HTML primitives; use the dedicated primitive tool first or batch the generated `html` node.
+
+## Payload Rules
+
+- Keep titles short and scannable; put detail in structured fields.
+- Prefer arrays of small records over one large prose blob.
+- Include file paths, line numbers, test commands, and exact statuses when the primitive is review or engineering focused.
+- Use `summary`, `why`, `risks`, `next`, `tests`, and `reviewFocus` fields when the chosen primitive supports them.
+- For `presentation`, use `slides: [{ title, kicker?, body?, bullets?, metrics?, note? }]`; keep one idea per slide, use `metrics` for big numbers, and put speaker notes in `note`.
+- Only choose `presentation` when the user explicitly asks for a PowerPoint-like deck, pitch, briefing, workshop walkthrough, or fullscreen story. Otherwise create a normal `html` node or a non-presentation primitive.
+- Presentation data supports `theme: "canvas" | "midnight" | "paper" | "aurora"` or a custom color object with `bg`, `panel`, `surface`, `border`, `text`, `textSecondary`, `textMuted`, `accent`, and `colorScheme`.
+- For visual primitives, provide colors as hex/rgb/hsl values only; unsafe color strings are discarded.
+- For editor primitives, seed realistic initial columns, flags, controls, variables, or template text so the human can interact immediately.
+
+## Human Feedback Loop
+
+Interactive/editor primitives are useful when the human should modify state and return it to the
+agent.
+
+- `triage-board` lets the human reorder and rebucket items, then copy markdown.
+- `config-editor` lets the human toggle flags and copy a diff-like export.
+- `prompt-tuner` lets the human edit prompts, preview sample substitutions, and copy the current prompt state.
+- `interaction-prototype` exposes live controls and copyable config for implementation tuning.
+- Tell the human which copy/export button to use, then ask them to paste the result back if you need to act on edits.
+
+## Sandbox And Persistence
+
+- Primitive output runs inside the existing HTML iframe sandbox with scripts allowed but no same-origin access.
+- Generated HTML receives PMX Canvas theme CSS variables so it adapts to the current canvas theme, and sandboxed iframes receive live theme updates when the canvas theme changes.
+- Generated and raw HTML nodes store an agent-readable summary sidecar (`agentSummary`, `contentSummary`, and embedded references) for search, pinned context, and spatial context.
+- Only presentation-marked HTML nodes have a browser `Present` button. Use it for `presentation` nodes so the human can review the deck fullscreen, navigate slides with arrow keys/Space/Page Up/Page Down, and exit with `Esc` or `Exit presentation`.
+- Presentation primitives also persist `presentation`, `slideCount`, `slideTitles`, and optional `speakerNotes` metadata so agents can understand the deck without parsing the iframe HTML.
+- Primitive data is persisted in canvas state; do not include secrets, credentials, private tokens, or unnecessary personal data.
+- Treat primitives as communication surfaces, not authoritative application state. If the result must be machine-roundtrippable, keep the original data in the node metadata or another structured node as well.
+
+## Picking The Right Primitive
+
+- Pick `choice-grid` when a decision has competing options.
+- Pick `plan-timeline` when sequence, dependency, and risk matter.
+- Pick `review-sheet` or `pr-writeup` for code review and pull-request communication.
+- Pick `system-map`, `code-walkthrough`, or `flowchart` for architecture and source explanations.
+- Pick `design-sheet`, `component-gallery`, `interaction-prototype`, or `illustration-set` for visual/product work.
+- Pick `presentation` when the human asks for a PowerPoint-like deck, pitch, briefing, workshop walkthrough, or fullscreen story.
+- Pick `explainer`, `deck`, `status-report`, or `incident-report` for narrative reporting.
+- Pick `triage-board`, `config-editor`, or `prompt-tuner` when the human needs to edit or return structured feedback.

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.',
@@ -1073,6 +1160,15 @@ cmd('node add', 'Add a node to the canvas', [
   } else if (type === 'html') {
     const html = getStringFlag(flags, 'html') ?? getStringFlag(flags, 'content');
     if (html !== undefined) body.html = html;
+    const summary = getStringFlag(flags, 'summary');
+    const agentSummary = getStringFlag(flags, 'agent-summary', 'agentSummary');
+    const description = getStringFlag(flags, 'description');
+    if (summary !== undefined) body.summary = summary;
+    if (agentSummary !== undefined) body.agentSummary = agentSummary;
+    if (description !== undefined) body.description = description;
+    if (optionalBooleanFlag(flags, 'presentation', 'Use --presentation true or --presentation false') === true) body.presentation = true;
+    if (typeof flags['slide-title'] === 'string') body.slideTitles = [flags['slide-title']];
+    if (typeof flags['embedded-node-id'] === 'string') body.embeddedNodeIds = [flags['embedded-node-id']];
   } else if (flags.content) {
     body.content = flags.content;
   }
@@ -1136,6 +1232,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 +1294,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;
@@ -1898,19 +2017,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) {
@@ -2302,9 +2433,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)');
@@ -2319,6 +2458,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');
@@ -2328,6 +2471,7 @@ 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:');
@@ -2415,6 +2559,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
@@ -2488,6 +2634,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
@@ -2534,6 +2682,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/cli/index.ts

@@ -32,7 +32,7 @@ if (args.includes('--version') || args.includes('-v')) {
 const AGENT_COMMANDS = new Set([
   'node', 'edge', 'json-render', 'search', 'layout', 'status', 'arrange', 'focus',
   'fit', 'screenshot', 'pin', 'undo', 'redo', 'history', 'snapshot', 'diff', 'group', 'webview', 'open',
-  'clear', 'code-graph', 'spatial', 'watch', 'web-artifact', 'external-app', 'graph', 'batch', 'validate', 'serve',
+  'clear', 'code-graph', 'spatial', 'watch', 'web-artifact', 'external-app', 'graph', 'html', 'batch', 'validate', 'serve',
 ]);
 
 const firstArg = args[0] ?? '';

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;
@@ -234,9 +237,9 @@ function Toolbar({
             type="button"
             onClick={() => {
               const next = canvasTheme.value === 'dark' ? 'light' : 'dark';
-              canvasTheme.value = next;
               document.documentElement.setAttribute('data-theme', next);
               invalidateTokenCache();
+              canvasTheme.value = next;
             }}
             aria-label={`Switch to ${canvasTheme.value === 'dark' ? 'light' : 'dark'} theme`}
           >
@@ -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>
   );
 }