pmx-canvas 0.1.19 → 0.1.20

package/dist/types/client/canvas/CanvasViewport.d.ts

@@ -1,5 +1,5 @@
 import type { CanvasNodeState } from '../types';
-type AnnotationTool = 'pen' | 'eraser' | null;
+type AnnotationTool = 'pen' | 'eraser' | 'text' | null;
 interface CanvasViewportProps {
     onNodeContextMenu?: (e: MouseEvent, nodeId: string) => void;
     onCanvasContextMenu?: (e: MouseEvent, canvasX: number, canvasY: number) => void;

package/dist/types/client/icons.d.ts

@@ -23,6 +23,8 @@ export declare function IconMoon(p: IconProps): JSX.Element;
 export declare function IconPen(p: IconProps): JSX.Element;
 /** Eraser — remove canvas annotations */
 export declare function IconEraser(p: IconProps): JSX.Element;
+/** Text cursor — canvas text annotation mode */
+export declare function IconTextAnnotation(p: IconProps): JSX.Element;
 /** Camera — snapshots */
 export declare function IconSnapshot(p: IconProps): JSX.Element;
 /** Bullseye — trace toggle */

package/dist/types/client/state/canvas-store.d.ts

@@ -45,9 +45,11 @@ export declare function removeEdgesForNode(nodeId: string): void;
 export declare function addAnnotation(annotation: CanvasAnnotation): void;
 export declare function removeAnnotation(id: string): void;
 export declare function createAnnotationFromClient(input: {
+    type?: CanvasAnnotation['type'];
     points: CanvasAnnotation['points'];
     color: string;
     width: number;
+    text?: string;
     label?: string;
 }): Promise<{
     ok: boolean;

package/dist/types/client/types.d.ts

@@ -35,7 +35,7 @@ export interface CanvasAnnotationPoint {
 }
 export interface CanvasAnnotation {
     id: string;
-    type: 'freehand';
+    type: 'freehand' | 'text';
     points: CanvasAnnotationPoint[];
     bounds: {
         x: number;
@@ -45,6 +45,7 @@ export interface CanvasAnnotation {
     };
     color: string;
     width: number;
+    text?: string;
     label?: string;
     createdAt: string;
 }

package/dist/types/json-render/charts/components.d.ts

@@ -6,7 +6,7 @@
  * chat example. Each component receives BaseComponentProps<T> and renders
  * a responsive chart inside a styled container.
  */
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import type { BaseComponentProps } from '@json-render/react';
 export declare const CHART_COLORS: string[];
 export type AggregateMode = 'sum' | 'count' | 'avg';
@@ -56,6 +56,10 @@ export declare const axisTickMargin = 8;
 export declare const legendMargin: {
     top: number;
 };
+export declare function useChartFrameHeight(explicitHeight: number | null | undefined, fallbackHeight?: number): {
+    frameRef: import("react").RefObject<HTMLDivElement | null>;
+    height: number;
+};
 /** Shared wrapper for cartesian charts (Line + Bar). */
 export declare function CartesianChart({ props, children, className, }: {
     props: CartesianChartProps;

package/dist/types/json-render/renderer/index.d.ts

@@ -12,5 +12,6 @@ declare global {
             state?: Record<string, unknown>;
         };
         __PMX_CANVAS_JSON_RENDER_THEME__?: string;
+        __PMX_CANVAS_JSON_RENDER_DISPLAY__?: string;
     }
 }

package/dist/types/json-render/server.d.ts

@@ -58,4 +58,5 @@ export declare function buildJsonRenderViewerHtml(options: {
     title: string;
     spec: JsonRenderSpec;
     theme?: 'dark' | 'light' | 'high-contrast';
+    display?: 'expanded';
 }): Promise<string>;

package/dist/types/mcp/canvas-access.d.ts

@@ -8,6 +8,8 @@ type AddDiagramInput = Parameters<PmxCanvas['addDiagram']>[0];
 type AddJsonRenderNodeInput = Parameters<PmxCanvas['addJsonRenderNode']>[0];
 type AddJsonRenderNodeResult = ReturnType<PmxCanvas['addJsonRenderNode']>;
 type AddHtmlNodeInput = Parameters<PmxCanvas['addHtmlNode']>[0];
+type AddHtmlPrimitiveInput = Parameters<PmxCanvas['addHtmlPrimitive']>[0];
+type AddHtmlPrimitiveResult = ReturnType<PmxCanvas['addHtmlPrimitive']>;
 type AddGraphNodeInput = Parameters<PmxCanvas['addGraphNode']>[0];
 type AddGraphNodeResult = ReturnType<PmxCanvas['addGraphNode']>;
 type UpdateNodePatch = Parameters<PmxCanvas['updateNode']>[1];
@@ -50,6 +52,7 @@ export interface CanvasAccess {
     addDiagram(input: AddDiagramInput): Promise<OpenMcpAppResult>;
     addJsonRenderNode(input: AddJsonRenderNodeInput): Promise<AddJsonRenderNodeResult>;
     addHtmlNode(input: AddHtmlNodeInput): Promise<string>;
+    addHtmlPrimitive(input: AddHtmlPrimitiveInput): Promise<AddHtmlPrimitiveResult>;
     addGraphNode(input: AddGraphNodeInput): Promise<AddGraphNodeResult>;
     buildWebArtifact(input: WebArtifactInput): Promise<WebArtifactResult>;
     updateNode(id: string, patch: UpdateNodePatch): Promise<void>;

package/dist/types/server/canvas-operations.d.ts

@@ -56,6 +56,10 @@ interface CanvasAddNodeInput {
     fileMode?: 'path' | 'inline' | 'auto';
     strictSize?: boolean;
 }
+export declare const MARKDOWN_NODE_DEFAULT_SIZE: {
+    width: number;
+    height: number;
+};
 interface CanvasCreateGroupInput {
     title?: string;
     childIds?: string[];

package/dist/types/server/canvas-schema.d.ts

@@ -1,5 +1,6 @@
 import { type JsonRenderComponentDescriptor } from '../json-render/catalog.js';
 import { type GraphNodeInput, type JsonRenderSpec } from '../json-render/server.js';
+import { type HtmlPrimitiveDescriptor } from './html-primitives.js';
 export interface CanvasCreateField {
     name: string;
     type: string;
@@ -19,8 +20,17 @@ export interface CanvasCreateTypeSchema {
 }
 export interface StructuredValidationResult {
     ok: true;
-    type: 'json-render' | 'graph';
-    normalizedSpec: JsonRenderSpec;
+    type: 'json-render' | 'graph' | 'html-primitive';
+    normalizedSpec?: JsonRenderSpec;
+    normalizedPrimitive?: {
+        kind: string;
+        title: string;
+        htmlBytes: number;
+        defaultSize: {
+            width: number;
+            height: number;
+        };
+    };
     summary: Record<string, unknown>;
 }
 declare const CANONICAL_GRAPH_TYPES: readonly ["line", "bar", "pie", "area", "scatter", "radar", "stacked-bar", "composed"];
@@ -37,6 +47,7 @@ export declare function describeCanvasSchema(): {
     graph: {
         graphTypes: CanvasGraphType[];
     };
+    htmlPrimitives: HtmlPrimitiveDescriptor[];
     mcp: {
         tools: string[];
         resources: string[];
@@ -44,8 +55,13 @@ export declare function describeCanvasSchema(): {
     };
 };
 export declare function validateStructuredCanvasPayload(input: {
-    type: 'json-render' | 'graph';
+    type: 'json-render' | 'graph' | 'html-primitive';
     spec?: unknown;
     graph?: GraphNodeInput;
+    primitive?: {
+        kind: string;
+        title?: string;
+        data?: Record<string, unknown>;
+    };
 }): StructuredValidationResult;
 export {};

package/dist/types/server/canvas-serialization.d.ts

@@ -18,6 +18,7 @@ export interface CanvasAnnotationSummary {
     color: string;
     width: number;
     pointCount: number;
+    text: string | null;
     label: string | null;
     createdAt: string;
 }

package/dist/types/server/canvas-state.d.ts

@@ -90,7 +90,7 @@ export interface CanvasAnnotationPoint {
 }
 export interface CanvasAnnotation {
     id: string;
-    type: 'freehand';
+    type: 'freehand' | 'text';
     points: CanvasAnnotationPoint[];
     bounds: {
         x: number;
@@ -100,6 +100,7 @@ export interface CanvasAnnotation {
     };
     color: string;
     width: number;
+    text?: string;
     label?: string;
     createdAt: string;
 }
@@ -134,6 +135,9 @@ interface GroupNodesOptions {
     layout?: 'grid' | 'column' | 'flow';
     keepGroupFrame?: boolean;
 }
+interface ApplyUpdatesOptions {
+    skipGroupChildTranslation?: boolean;
+}
 declare class CanvasStateManager {
     private nodes;
     private edges;
@@ -231,7 +235,7 @@ declare class CanvasStateManager {
     private removeEdgesForNode;
     getLayout(): CanvasLayout;
     getLayoutForPersistence(): CanvasLayout;
-    applyUpdates(updates: CanvasNodeUpdate[]): {
+    applyUpdates(updates: CanvasNodeUpdate[], options?: ApplyUpdatesOptions): {
         applied: number;
         skipped: number;
     };

package/dist/types/server/html-primitives.d.ts

@@ -0,0 +1,34 @@
+export declare const HTML_PRIMITIVE_KINDS: readonly ["choice-grid", "plan-timeline", "review-sheet", "pr-writeup", "system-map", "code-walkthrough", "design-sheet", "component-gallery", "interaction-prototype", "flowchart", "deck", "illustration-set", "explainer", "status-report", "incident-report", "triage-board", "config-editor", "prompt-tuner"];
+export type HtmlPrimitiveKind = typeof HTML_PRIMITIVE_KINDS[number];
+export interface HtmlPrimitiveDescriptor {
+    kind: HtmlPrimitiveKind;
+    title: string;
+    description: string;
+    useWhen: string;
+    defaultSize: {
+        width: number;
+        height: number;
+    };
+    dataShape: string;
+    example: Record<string, unknown>;
+}
+export interface HtmlPrimitiveInput {
+    kind: HtmlPrimitiveKind;
+    title?: string;
+    data?: Record<string, unknown>;
+}
+export interface HtmlPrimitiveBuildResult {
+    kind: HtmlPrimitiveKind;
+    title: string;
+    html: string;
+    summary: string;
+    defaultSize: {
+        width: number;
+        height: number;
+    };
+    data: Record<string, unknown>;
+}
+export declare function isHtmlPrimitiveKind(value: string): value is HtmlPrimitiveKind;
+export declare function getHtmlPrimitiveDescriptor(kind: HtmlPrimitiveKind): HtmlPrimitiveDescriptor;
+export declare function listHtmlPrimitiveDescriptors(): HtmlPrimitiveDescriptor[];
+export declare function buildHtmlPrimitive(input: HtmlPrimitiveInput): HtmlPrimitiveBuildResult;

package/dist/types/server/index.d.ts

@@ -3,6 +3,7 @@ import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from
 import { searchNodes } from './spatial-analysis.js';
 import { diffLayouts } from './mutation-history.js';
 import { fitCanvasView, gcCanvasSnapshots, listCanvasSnapshots } from './canvas-operations.js';
+import type { HtmlPrimitiveKind } from './html-primitives.js';
 import { type WebArtifactBuildInput, type WebArtifactCanvasBuildResult } from './web-artifacts.js';
 import { type ExternalMcpTransportConfig } from './mcp-app-runtime.js';
 import { type DiagramPresetOpenInput } from './diagram-presets.js';
@@ -181,6 +182,7 @@ export declare class PmxCanvas extends EventEmitter {
         graph: {
             graphTypes: ("line" | "bar" | "pie" | "area" | "scatter" | "radar" | "composed" | "stacked-bar")[];
         };
+        htmlPrimitives: import("./html-primitives.js").HtmlPrimitiveDescriptor[];
         mcp: {
             tools: string[];
             resources: string[];
@@ -248,6 +250,21 @@ export declare class PmxCanvas extends EventEmitter {
         height?: number;
         strictSize?: boolean;
     }): string;
+    addHtmlPrimitive(input: {
+        kind: HtmlPrimitiveKind;
+        title?: string;
+        data?: Record<string, unknown>;
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+        strictSize?: boolean;
+    }): {
+        id: string;
+        kind: HtmlPrimitiveKind;
+        title: string;
+        htmlBytes: number;
+    };
     addGraphNode(input: GraphNodeInput): {
         id: string;
         url: string;
@@ -275,10 +292,12 @@ export type { SpatialCluster, SpatialContext, SpatialNeighbor, NodeSpatialInfo }
 export { mutationHistory, diffLayouts, formatDiff } from './mutation-history.js';
 export { recomputeCodeGraph, buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 export { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
+export { buildHtmlPrimitive, isHtmlPrimitiveKind, listHtmlPrimitiveDescriptors } from './html-primitives.js';
 export { buildWebArtifactOnCanvas, executeWebArtifactBuild, openWebArtifactInCanvas, resolveWebArtifactScriptPath, resolveWorkspacePath, } from './web-artifacts.js';
 export { buildGraphSpec, buildJsonRenderViewerHtml, createJsonRenderNodeData, GRAPH_NODE_SIZE, JSON_RENDER_NODE_SIZE, normalizeAndValidateJsonRenderSpec, } from '../json-render/server.js';
 export type { CodeGraphSummary, CodeGraphEdge } from './code-graph.js';
 export type { MutationEntry, MutationSummary, SnapshotDiffResult } from './mutation-history.js';
 export type { WebArtifactBuildInput, WebArtifactBuildOutput, WebArtifactCanvasBuildResult, WebArtifactCanvasOpenResult, } from './web-artifacts.js';
 export type { GraphNodeInput, JsonRenderNodeInput, JsonRenderSpec } from '../json-render/server.js';
+export type { HtmlPrimitiveKind, HtmlPrimitiveDescriptor, HtmlPrimitiveInput, HtmlPrimitiveBuildResult } from './html-primitives.js';
 export { traceManager } from './trace-manager.js';

package/docs/cli.md

@@ -8,7 +8,7 @@ The CLI is the shell-native way to run and control PMX Canvas. It targets
 
 ```bash
 pmx-canvas                            # Start canvas, open browser
-pmx-canvas --demo                     # Start with the project-tour demo board
+pmx-canvas --demo                     # Start with the saved dashboard demo board
 pmx-canvas --port=8080                # Custom port
 pmx-canvas --no-open                  # Headless (for agents/CI)
 pmx-canvas --theme=light              # dark | light | high-contrast
@@ -35,6 +35,8 @@ 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 node add --type graph --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y
 pmx-canvas graph add --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y   # Alias
+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 --json                                        # Schema for one type
 
 pmx-canvas external-app add --kind excalidraw --title "Diagram"
@@ -66,6 +68,7 @@ content.
 pmx-canvas node schema --type json-render --component Table --summary
 pmx-canvas validate                                                      # Layout validation
 pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary
+pmx-canvas validate spec --type html-primitive --kind choice-grid --data-json '{"items":[{"title":"A"}]}' --summary
 ```
 
 The schema commands surface the running server's data, which is strictly

package/docs/http-api.md

@@ -22,6 +22,11 @@ curl http://localhost:4313/api/canvas/schema
 curl -X POST http://localhost:4313/api/canvas/schema/validate \
   -H "Content-Type: application/json" \
   -d '{"type":"json-render","spec":{"root":"card","elements":{"card":{"type":"Card","props":{"title":"Preview"},"children":[]}}}}'
+
+# Validate an HTML primitive without creating a node
+curl -X POST http://localhost:4313/api/canvas/schema/validate \
+  -H "Content-Type: application/json" \
+  -d '{"type":"html-primitive","kind":"choice-grid","data":{"items":[{"title":"A"}]}}'
 ```
 
 ## Nodes
@@ -36,6 +41,11 @@ curl -X POST http://localhost:4313/api/canvas/node \
 curl -X POST http://localhost:4313/api/canvas/node \
   -H "Content-Type: application/json" \
   -d '{"type":"html","title":"Chart","html":"<canvas id=\"c\"></canvas><script src=\"https://cdn.jsdelivr.net/npm/chart.js\"></script><script>/* ... */</script>"}'
+
+# Add a generated HTML primitive as a sandboxed html node
+curl -X POST http://localhost:4313/api/canvas/node \
+  -H "Content-Type: application/json" \
+  -d '{"type":"html-primitive","kind":"choice-grid","title":"Options","data":{"items":[{"title":"Small patch","summary":"Least disruption."}]}}'
 ```
 
 ## Edges

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **41 tools** + **8 core resources**,
+PMX Canvas ships an MCP stdio server with **42 tools** + **8 core resources**,
 plus per-skill resources at `canvas://skills/<name>`. The server emits
 `notifications/resources/updated` when canvas state changes — humans pin
 nodes in the browser, agents are notified immediately.
@@ -28,10 +28,11 @@ The canvas auto-starts on first tool call.
 |------|-------------|
 | `canvas_add_node` | Add a node (markdown, status, context, file, webpage, html, etc.) |
 | `canvas_add_html_node` | Create an `html` node from a self-contained HTML/JS document (sandboxed iframe) |
+| `canvas_add_html_primitive` | Create a reusable generated HTML communication primitive as a sandboxed `html` node |
 | `canvas_add_diagram` | Hand-drawn diagram via the hosted Excalidraw MCP App (preset alias for `canvas_open_mcp_app`) |
 | `canvas_open_mcp_app` | Open any [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) server's `ui://` resource as an iframe node |
-| `canvas_describe_schema` | Describe the running server's create schemas, examples, and json-render catalog |
-| `canvas_validate_spec` | Validate a json-render spec or graph payload without creating a node |
+| `canvas_describe_schema` | Describe the running server's create schemas, examples, json-render catalog, and HTML primitive catalog |
+| `canvas_validate_spec` | Validate a json-render spec, graph payload, or HTML primitive payload without creating a node |
 | `canvas_refresh_webpage_node` | Re-fetch and update a webpage node from its stored URL |
 | `canvas_add_json_render_node` | Create a native json-render node from a validated spec |
 | `canvas_add_graph_node` | Create a native graph node (line, bar, pie, area, scatter, radar, stacked-bar, composed) |
@@ -118,6 +119,7 @@ in doubt:
 
 - `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`
 - `mcp-app` → `canvas_open_mcp_app`
@@ -128,7 +130,7 @@ in doubt:
 ## CLI/MCP alignment
 
 CLI and MCP are kept aligned for the main canvas operations: node and edge
-creation, graph/json-render/html nodes, web artifacts, external apps, groups,
+creation, graph/json-render/html/html-primitive nodes, web artifacts, external apps, groups,
 batch builds, layout validation, snapshots, search, focus, pins, undo/redo,
 semantic watch streams, WebView automation, and daemon/server control where
 it applies. A few agent-native capabilities — resource subscriptions and

package/docs/node-types.md

@@ -164,6 +164,33 @@ canvas_add_html_node({
 A fragment without `<html>`/`<head>` is wrapped in a full document
 automatically. Default size is 720×640.
 
+### HTML primitives
+
+`html-primitive` is a virtual schema type that creates a normal sandboxed
+`html` node from a reusable communication template. Use it when a long markdown
+answer would be easier to review as an option grid, implementation timeline,
+review sheet, PR writeup, code walkthrough, system map, design sheet,
+component gallery, interaction prototype, flowchart, SVG illustration set,
+explainer, status report, incident report, triage board, config editor, or
+prompt tuner.
+
+```ts
+canvas_add_html_primitive({
+  kind: 'choice-grid',
+  title: 'Implementation options',
+  data: {
+    items: [
+      { title: 'Small patch', summary: 'Least disruption.', pros: ['Fast'], cons: ['Less flexible'] },
+    ],
+  },
+});
+```
+
+HTTP callers may post either `{ "type": "html-primitive", "kind": "choice-grid", "data": ... }`
+or `{ "type": "html", "primitive": "choice-grid", "data": ... }`. The stored
+node remains `type: "html"` with `data.htmlPrimitive`, `data.primitiveData`, and
+the generated `data.html` payload.
+
 ## Web artifacts
 
 A **web artifact** is a single-file, fully bundled HTML app (React + Tailwind
@@ -222,9 +249,9 @@ Agents don't have to guess node shapes. The running server exposes its create
 schemas, json-render component catalog, and node-type examples:
 
 - `canvas_describe_schema` / `GET /api/canvas/schema` — list all node-create
-  schemas, required fields, json-render components, and sample payloads
+  schemas, required fields, json-render components, HTML primitives, and sample payloads
 - `canvas_validate_spec` / `POST /api/canvas/schema/validate` — validate a
-  json-render spec or graph payload **without** creating a node
+  json-render spec, graph payload, or HTML primitive payload **without** creating a node
 - `canvas_validate` / `GET /api/canvas/validate` — validate the current
   layout for collisions, containment, and missing edge endpoints
 - `canvas://schema` — the same data as an MCP resource
@@ -236,6 +263,7 @@ MCP node creation uses dedicated tools for structured node families. Read
 `mcp.nodeTypeRouting` from `canvas_describe_schema` when in doubt:
 `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`,
 `mcp-app` → `canvas_open_mcp_app`,

package/docs/sdk.md

@@ -32,6 +32,17 @@ canvas.addHtmlNode({
   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: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.19",
+  "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",

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 |