pmx-canvas 0.1.16 → 0.1.18

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

@@ -0,0 +1,4 @@
+import type { CanvasAnnotation } from '../types';
+export declare function AnnotationLayer({ annotations }: {
+    annotations: CanvasAnnotation[];
+}): import("preact/src").JSX.Element | null;

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

@@ -1,8 +1,11 @@
 import type { CanvasNodeState } from '../types';
+type AnnotationTool = 'pen' | 'eraser' | null;
 interface CanvasViewportProps {
     onNodeContextMenu?: (e: MouseEvent, nodeId: string) => void;
     onCanvasContextMenu?: (e: MouseEvent, canvasX: number, canvasY: number) => void;
+    annotationMode?: boolean;
+    annotationTool?: AnnotationTool;
 }
 export declare function getRenderableWorldNodes(allNodes: Iterable<CanvasNodeState>, focusedNodeId: string | null): CanvasNodeState[];
-export declare function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu }: CanvasViewportProps): import("preact/src").JSX.Element;
+export declare function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu, annotationMode, annotationTool }: CanvasViewportProps): import("preact/src").JSX.Element;
 export {};

package/dist/types/client/canvas/use-pan-zoom.d.ts

@@ -4,6 +4,7 @@ interface PanZoomOptions {
     viewport: Signal<ViewportState>;
     onViewportChange: (v: ViewportState) => void;
     onViewportCommit: (v: ViewportState) => void;
+    disabled?: boolean;
 }
 /**
  * Hook that wires up pan/zoom interactions on a container element.
@@ -12,5 +13,5 @@ interface PanZoomOptions {
  * - Pointer drag on background: pan
  * - Pinch (touch): zoom
  */
-export declare function usePanZoom({ viewport, onViewportChange, onViewportCommit }: PanZoomOptions): import("preact/src").RefObject<HTMLDivElement>;
+export declare function usePanZoom({ viewport, onViewportChange, onViewportCommit, disabled }: PanZoomOptions): import("preact/src").RefObject<HTMLDivElement>;
 export {};

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

@@ -19,6 +19,10 @@ export declare function IconMinimap(p: IconProps): JSX.Element;
 export declare function IconSun(p: IconProps): JSX.Element;
 /** Crescent moon */
 export declare function IconMoon(p: IconProps): JSX.Element;
+/** Pen stroke — canvas annotation mode */
+export declare function IconPen(p: IconProps): JSX.Element;
+/** Eraser — remove canvas annotations */
+export declare function IconEraser(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

@@ -1,7 +1,8 @@
-import { type CanvasEdge, type CanvasLayout, type CanvasNodeState, type ConnectionStatus, type ViewportState } from '../types';
+import { type CanvasAnnotation, type CanvasEdge, type CanvasLayout, type CanvasNodeState, type ConnectionStatus, type ViewportState } from '../types';
 export declare const viewport: import("@preact/signals-core").Signal<ViewportState>;
 export declare const nodes: import("@preact/signals-core").Signal<Map<string, CanvasNodeState>>;
 export declare const edges: import("@preact/signals-core").Signal<Map<string, CanvasEdge>>;
+export declare const annotations: import("@preact/signals-core").Signal<Map<string, CanvasAnnotation>>;
 export declare const activeNodeId: import("@preact/signals-core").Signal<string | null>;
 export declare const connectionStatus: import("@preact/signals-core").Signal<ConnectionStatus>;
 export declare const sessionId: import("@preact/signals-core").Signal<string>;
@@ -41,6 +42,19 @@ export declare function removeNode(id: string): void;
 export declare function addEdge(edge: CanvasEdge): void;
 export declare function removeEdge(id: string): void;
 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: {
+    points: CanvasAnnotation['points'];
+    color: string;
+    width: number;
+    label?: string;
+}): Promise<{
+    ok: boolean;
+}>;
+export declare function removeAnnotationFromClient(id: string): Promise<{
+    ok: boolean;
+}>;
 export declare function resizeNode(id: string, size: {
     width: number;
     height: number;
@@ -56,6 +70,7 @@ export declare function replaceViewport(next: ViewportState): void;
 export declare function commitViewport(next: ViewportState): void;
 export declare function applyServerCanvasLayout(layout: Pick<CanvasLayout, 'nodes' | 'edges'> & {
     viewport?: ViewportState;
+    annotations?: CanvasAnnotation[];
 }, options?: {
     applyViewport?: boolean;
 }): void;

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

@@ -29,6 +29,25 @@ export interface CanvasEdge {
     style?: 'solid' | 'dashed' | 'dotted';
     animated?: boolean;
 }
+export interface CanvasAnnotationPoint {
+    x: number;
+    y: number;
+}
+export interface CanvasAnnotation {
+    id: string;
+    type: 'freehand';
+    points: CanvasAnnotationPoint[];
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    color: string;
+    width: number;
+    label?: string;
+    createdAt: string;
+}
 export type ConnectionStatus = 'connecting' | 'connected' | 'disconnected';
 export declare const TYPE_LABELS: Record<CanvasNodeState['type'], string>;
 /** Node types that support the full-viewport expand/focus overlay. */
@@ -40,4 +59,5 @@ export interface CanvasLayout {
     viewport: ViewportState;
     nodes: CanvasNodeState[];
     edges: CanvasEdge[];
+    annotations?: CanvasAnnotation[];
 }

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

@@ -54,6 +54,7 @@ export interface CanvasAccess {
     buildWebArtifact(input: WebArtifactInput): Promise<WebArtifactResult>;
     updateNode(id: string, patch: UpdateNodePatch): Promise<void>;
     removeNode(id: string): Promise<void>;
+    removeAnnotation(id: string): Promise<boolean>;
     addEdge(input: AddEdgeInput): Promise<string>;
     removeEdge(id: string): Promise<void>;
     createGroup(input: CreateGroupInput): Promise<string>;

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

@@ -1,4 +1,4 @@
-import type { CanvasLayout, CanvasNodeState, ViewportState } from './canvas-state.js';
+import type { CanvasAnnotation, CanvasLayout, CanvasNodeState, ViewportState } from './canvas-state.js';
 import { type CanvasNodeProvenance } from './canvas-provenance.js';
 export interface SerializedCanvasNode extends CanvasNodeState {
     kind: string;
@@ -11,16 +11,40 @@ export interface SerializedCanvasNode extends CanvasNodeState {
 export interface SerializedCanvasLayout extends Omit<CanvasLayout, 'nodes'> {
     nodes: SerializedCanvasNode[];
 }
+export interface CanvasAnnotationSummary {
+    id: string;
+    type: CanvasAnnotation['type'];
+    bounds: CanvasAnnotation['bounds'];
+    color: string;
+    width: number;
+    pointCount: number;
+    label: string | null;
+    createdAt: string;
+}
+export interface CanvasAnnotationContextSummary {
+    id: string;
+    label: string | null;
+    bounds: CanvasAnnotation['bounds'];
+    targetNodeIds: string[];
+    targetNodeTitles: string[];
+    target: string;
+}
 export declare function getCanvasNodeKind(node: CanvasNodeState, data: Record<string, unknown>): string;
 export declare function getCanvasNodeTitle(node: CanvasNodeState): string | null;
 export declare function getCanvasNodeContent(node: CanvasNodeState): string | null;
 export declare function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode;
+export declare function serializeCanvasNodeForAgent(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasNodeWithBlobSummaries(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasLayout(layout: CanvasLayout): SerializedCanvasLayout;
+export declare function serializeCanvasLayoutForAgent(layout: CanvasLayout): SerializedCanvasLayout;
 export declare function serializeCanvasLayoutWithBlobSummaries(layout: CanvasLayout): SerializedCanvasLayout;
+export declare function summarizeCanvasAnnotation(annotation: CanvasAnnotation): CanvasAnnotationSummary;
+export declare function summarizeCanvasAnnotationForContext(annotation: CanvasAnnotation, nodes: CanvasNodeState[]): CanvasAnnotationContextSummary;
 export interface CanvasSummary {
     totalNodes: number;
     totalEdges: number;
+    totalAnnotations: number;
+    annotations: CanvasAnnotationContextSummary[];
     nodesByType: Record<string, number>;
     pinnedCount: number;
     pinnedTitles: string[];

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

@@ -22,6 +22,7 @@ interface PersistedCanvasState {
     viewport: ViewportState;
     nodes: CanvasNodeState[];
     edges: CanvasEdge[];
+    annotations?: CanvasAnnotation[];
     contextPins: string[];
 }
 interface LoadFromDiskOptions {
@@ -81,10 +82,30 @@ export interface CanvasEdge {
     style?: 'solid' | 'dashed' | 'dotted';
     animated?: boolean;
 }
+export interface CanvasAnnotationPoint {
+    x: number;
+    y: number;
+}
+export interface CanvasAnnotation {
+    id: string;
+    type: 'freehand';
+    points: CanvasAnnotationPoint[];
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    color: string;
+    width: number;
+    label?: string;
+    createdAt: string;
+}
 export interface CanvasLayout {
     viewport: ViewportState;
     nodes: CanvasNodeState[];
     edges: CanvasEdge[];
+    annotations: CanvasAnnotation[];
 }
 export interface CanvasNodeUpdate {
     id: string;
@@ -101,7 +122,7 @@ export interface CanvasNodeUpdate {
 }
 export type CanvasChangeType = 'pins' | 'nodes';
 export interface MutationRecordInfo {
-    operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'clear' | 'restoreSnapshot' | 'setPins' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
+    operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
     description: string;
     forward: () => void;
     inverse: () => void;
@@ -114,6 +135,7 @@ interface GroupNodesOptions {
 declare class CanvasStateManager {
     private nodes;
     private edges;
+    private annotations;
     private _viewport;
     private _contextPinnedNodeIds;
     private _workspaceRoot;
@@ -185,6 +207,7 @@ declare class CanvasStateManager {
         name: string;
         nodes: CanvasNodeState[];
         edges: CanvasEdge[];
+        annotations: CanvasAnnotation[];
     } | null;
     /** Delete a snapshot. */
     deleteSnapshot(id: string): boolean;
@@ -200,6 +223,9 @@ declare class CanvasStateManager {
     removeEdge(id: string): boolean;
     getEdges(): CanvasEdge[];
     getEdgesForNode(nodeId: string): CanvasEdge[];
+    addAnnotation(annotation: CanvasAnnotation): void;
+    removeAnnotation(id: string): boolean;
+    getAnnotations(): CanvasAnnotation[];
     private removeEdgesForNode;
     getLayout(): CanvasLayout;
     getLayoutForPersistence(): CanvasLayout;

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

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import type { CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
+import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
 import { searchNodes } from './spatial-analysis.js';
 import { diffLayouts } from './mutation-history.js';
 import { fitCanvasView, gcCanvasSnapshots, listCanvasSnapshots } from './canvas-operations.js';
@@ -69,6 +69,11 @@ export declare class PmxCanvas extends EventEmitter {
         style?: CanvasEdge['style'];
         animated?: boolean;
     }): string;
+    addAnnotation(input: Omit<CanvasAnnotation, 'id' | 'createdAt'> & {
+        id?: string;
+        createdAt?: string;
+    }): string;
+    removeAnnotation(id: string): boolean;
     removeEdge(id: string): void;
     /**
      * Create a group node and optionally add child nodes to it.
@@ -263,7 +268,7 @@ export type { CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from '.
 export type { CanvasAutomationWebViewOptions, CanvasAutomationWebViewStatus, PrimaryWorkbenchCanvasPromptRequest, PrimaryWorkbenchIntent, } from './server.js';
 export { emitPrimaryWorkbenchEvent, consumePrimaryWorkbenchIntents, setPrimaryWorkbenchAutoOpenEnabled, setPrimaryWorkbenchCanvasPromptHandler, startCanvasServer, stopCanvasServer, getCanvasServerPort, openUrlInExternalBrowser, getCanvasAutomationWebViewStatus, startCanvasAutomationWebView, stopCanvasAutomationWebView, evaluateCanvasAutomationWebView, resizeCanvasAutomationWebView, screenshotCanvasAutomationWebView, } from './server.js';
 export { canvasState } from './canvas-state.js';
-export type { CanvasSnapshot, CanvasSnapshotGcResult, CanvasSnapshotListOptions } from './canvas-state.js';
+export type { CanvasAnnotation, CanvasSnapshot, CanvasSnapshotGcResult, CanvasSnapshotListOptions } from './canvas-state.js';
 export { findOpenCanvasPosition } from './placement.js';
 export { searchNodes, buildSpatialContext, detectClusters, findNeighborhoods } from './spatial-analysis.js';
 export type { SpatialCluster, SpatialContext, SpatialNeighbor, NodeSpatialInfo } from './spatial-analysis.js';

package/dist/types/server/mutation-history.d.ts

@@ -12,7 +12,7 @@
  * - _replaying flag prevents undo/redo from recording new entries
  */
 import type { CanvasNodeState, CanvasEdge } from './canvas-state.js';
-export type MutationOp = 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'clear' | 'arrange' | 'restoreSnapshot' | 'setPins' | 'batch' | 'viewport' | 'groupNodes' | 'ungroupNodes';
+export type MutationOp = 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'arrange' | 'restoreSnapshot' | 'setPins' | 'batch' | 'viewport' | 'groupNodes' | 'ungroupNodes';
 export interface MutationEntry {
     id: string;
     timestamp: string;

package/dist/types/server/spatial-analysis.d.ts

@@ -9,7 +9,7 @@
  * actually real for agents. Instead of raw x/y coordinates, agents get
  * semantic clusters, ordered context, and implicit human intent.
  */
-import type { CanvasNodeState, CanvasEdge } from './canvas-state.js';
+import type { CanvasAnnotation, CanvasNodeState, CanvasEdge } from './canvas-state.js';
 export interface SpatialCluster {
     /** Auto-generated cluster ID */
     id: string;
@@ -45,6 +45,14 @@ export interface NodeSpatialInfo {
     /** Reading order index (top-left to bottom-right) */
     readingOrder: number;
 }
+export interface SpatialAnnotationContext {
+    id: string;
+    label: string | null;
+    bounds: CanvasAnnotation['bounds'];
+    targetNodeIds: string[];
+    targetNodeTitles: string[];
+    target: string;
+}
 export interface SpatialContext {
     /** Total nodes on canvas */
     totalNodes: number;
@@ -58,6 +66,7 @@ export interface SpatialContext {
         pinnedNodeTitle: string | null;
         neighbors: SpatialNeighbor[];
     }[];
+    annotations: SpatialAnnotationContext[];
 }
 /**
  * Detect proximity clusters using single-linkage clustering.
@@ -84,4 +93,4 @@ export declare function searchNodes(nodes: CanvasNodeState[], query: string): {
 /**
  * Build the complete spatial context for the canvas.
  */
-export declare function buildSpatialContext(nodes: CanvasNodeState[], _edges: CanvasEdge[], pinnedIds: Set<string>): SpatialContext;
+export declare function buildSpatialContext(nodes: CanvasNodeState[], _edges: CanvasEdge[], pinnedIds: Set<string>, annotations?: CanvasAnnotation[]): SpatialContext;

package/package.json

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

@@ -302,6 +302,10 @@ If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` a
 - `id` (required): node to remove
 - Clean up nodes that are no longer relevant
 
+**`canvas_remove_annotation`** — Remove a human-drawn annotation
+- `id` (required): annotation to remove
+- Use when context gives you the annotation ID; use WebView first if you need to identify a mark by shape or location.
+
 **`canvas_get_node`** — Get a single node's full data
 - `id` (required): node to retrieve
 
@@ -564,6 +568,11 @@ tools below operate on the live canvas state.
 Useful workbench selectors:
 - Nodes: `.canvas-node`, `.canvas-node.active`, `.canvas-node.context-pinned`, `.canvas-node.group-node`
 - Node internals: `.node-title`, `.node-titlebar`, `.node-body`, `.node-type-badge`, `.node-controls`
+- Annotations: `.annotation-layer path` renders human-drawn freehand ink. Use WebView
+  to inspect or screenshot annotation shapes; MCP/context resources only expose compact
+  annotation target summaries, not the raw visual shape. Humans can remove marks with
+  the eraser toolbar button; agents can remove a known annotation ID with
+  `canvas_remove_annotation`.
 - Canvas chrome: `.hud-layer`, `.canvas-toolbar`, `.connection-dot`, `.canvas-bootstrap-card`
 - Nodes do not expose stable `data-node-id` attributes. Use `canvas_get_layout`, `canvas_search`, or MCP resource data for exact node IDs.
 
@@ -610,6 +619,11 @@ canvas_webview_stop();
   geometric `graph` node would feel too rigid
 - Prefer labeled shapes (`"label": { "text": "..." }` on rectangle/ellipse/diamond) over
   separate text elements — fewer tokens and auto-centered
+- Do not use separate `text` elements with `containerId`/`boundElements` to place centered text
+  inside shapes. The hosted SVG preview does not auto-position those; PMX normalizes imported
+  canonical bound text back into shape labels for hosted app calls.
+- For detailed sizing, camera, and label-fit rules, read `references/excalidraw-diagram-authoring.md`
+  before creating dense diagrams.
 - Prefer the pastel fill palette in the Excalidraw `read_me` (light blue/green/orange/...) for
   a consistent look across diagrams
 
@@ -691,6 +705,11 @@ The `canvas://spatial-context` resource reveals how the human has organized info
   This implies sequence or priority.
 - **Pinned neighborhoods** — For each pinned node, nearby unpinned nodes are listed. These
   are the human's implicit context — things they consider related to what they pinned.
+- **Annotations** — Human-drawn markup is summarized by target/bounds only, e.g. an
+  annotation over a node or empty canvas region. Use WebView (`canvas_webview_start` +
+  `canvas_evaluate`/`canvas_screenshot`) when you need to see whether the mark is an
+  arrow, line, circle, or other drawn shape. Remove known annotations with
+  `canvas_remove_annotation`; otherwise use WebView to identify the mark first.
 - **Board density matters** — On a dense board, spatial context can still read like one large
   gallery unless groups and spacing separate the major regions clearly.
 

package/skills/pmx-canvas/references/excalidraw-diagram-authoring.md

@@ -0,0 +1,145 @@
+# Excalidraw Diagram Authoring
+
+Use this guide when creating diagrams through PMX Canvas with `canvas_add_diagram` or
+`pmx-canvas external-app add --kind excalidraw`.
+
+## Why Text Can Still Drift
+
+PMX normalizes canonical Excalidraw bound text (`containerId` / `boundElements`) into the hosted
+app's supported shape-level `label` format before calling Excalidraw. That fixes the payload
+format mismatch, but it does not fix poor diagram geometry.
+
+Text can still appear clipped or misplaced when:
+
+- A label is too long for its shape.
+- A diamond or ellipse is too small for the label's usable center area.
+- The `cameraUpdate` viewport is too tight or not 4:3.
+- Title, footer, or notes are placed near the camera edge.
+- The caller bypasses PMX and sends raw elements directly to Excalidraw MCP.
+
+## Text Format Rules
+
+For text inside a rectangle, ellipse, or diamond, use shape-level `label`:
+
+```json
+{
+  "type": "rectangle",
+  "id": "step-a",
+  "x": 100,
+  "y": 100,
+  "width": 260,
+  "height": 90,
+  "label": { "text": "Step A", "fontSize": 18 }
+}
+```
+
+Do not create separate centered text elements for shape labels:
+
+```json
+{
+  "type": "text",
+  "containerId": "step-a",
+  "text": "Step A"
+}
+```
+
+Standalone text is fine for titles, notes, captions, and free-floating annotations. For standalone
+text, `x` is the left edge; `textAlign` does not center it on a point.
+
+## Label Length Rules
+
+- Use 1-4 words inside shapes.
+- Put detailed explanations in nearby standalone text annotations.
+- Prefer `Bound Text` over `Pattern B: containerId+boundElements only`.
+- If a label needs more than 4 words, either widen the shape or split the idea into a label plus an annotation.
+
+## Shape Sizing Rules
+
+- Minimum labeled rectangle or ellipse: `180x80`.
+- For 3-5 word labels: `240x90` or larger.
+- For long labels: `320+` width or use an external annotation.
+- Diamonds need more room than rectangles because the usable center area is smaller.
+- Leave at least `30px` gap between shapes and labels/arrows.
+
+## Camera Rules
+
+Always start with a `cameraUpdate` as the first element.
+
+Use 4:3 camera sizes only:
+
+- `400x300`
+- `600x450`
+- `800x600`
+- `1200x900`
+- `1600x1200`
+
+Camera bounds must include the full diagram plus padding. Leave at least `80px` padding around all
+visible content.
+
+Example:
+
+```json
+{ "type": "cameraUpdate", "x": 20, "y": 0, "width": 1200, "height": 900 }
+```
+
+If a title, footer, or rightmost label is clipped, the camera is wrong even if the elements are valid.
+
+## Good Pattern
+
+```json
+[
+  { "type": "cameraUpdate", "x": 20, "y": 0, "width": 1200, "height": 900 },
+  {
+    "type": "rectangle",
+    "id": "a",
+    "x": 120,
+    "y": 160,
+    "width": 260,
+    "height": 90,
+    "backgroundColor": "#a5d8ff",
+    "fillStyle": "solid",
+    "label": { "text": "Short Label", "fontSize": 18 }
+  },
+  {
+    "type": "rectangle",
+    "id": "b",
+    "x": 520,
+    "y": 160,
+    "width": 280,
+    "height": 90,
+    "backgroundColor": "#b2f2bb",
+    "fillStyle": "solid",
+    "label": { "text": "Next Step", "fontSize": 18 }
+  },
+  {
+    "type": "arrow",
+    "id": "a-to-b",
+    "x": 390,
+    "y": 205,
+    "width": 110,
+    "height": 0,
+    "points": [[0, 0], [110, 0]],
+    "endArrowhead": "arrow",
+    "label": { "text": "then", "fontSize": 14 }
+  },
+  {
+    "type": "text",
+    "id": "note",
+    "x": 120,
+    "y": 290,
+    "text": "Longer explanation goes here, outside the shape.",
+    "fontSize": 16
+  }
+]
+```
+
+## Preflight Checklist
+
+- Shape text uses `label`, not separate `text` elements.
+- Shape labels are short enough to fit.
+- Long explanations are outside shapes.
+- The first element is a 4:3 `cameraUpdate`.
+- Camera has at least `80px` padding around all visible content.
+- Titles and footers are not near the camera edge.
+- Arrows have explicit `points` and enough space for labels.
+- Calls go through PMX (`canvas_add_diagram` or `external-app add --kind excalidraw`) unless you manually apply these rules to raw Excalidraw MCP input.

package/src/cli/agent.ts

@@ -1027,6 +1027,7 @@ cmd('node add', 'Add a node to the canvas', [
   'pmx-canvas node add --type status --title "Build" --content "passing"',
   '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 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',
@@ -1069,6 +1070,9 @@ cmd('node add', 'Add a node to the canvas', [
     body.url = webpageUrl;
   } else if (type === 'image' && imagePath && !flags.content) {
     body.content = imagePath;
+  } else if (type === 'html') {
+    const html = getStringFlag(flags, 'html') ?? getStringFlag(flags, 'content');
+    if (html !== undefined) body.html = html;
   } else if (flags.content) {
     body.content = flags.content;
   }
@@ -1090,6 +1094,8 @@ cmd('node add', 'Add a node to the canvas', [
   if (flags.stdin) {
     if (type === 'webpage') {
       body.url = await readStdin();
+    } else if (type === 'html') {
+      body.html = await readStdin();
     } else {
       body.content = await readStdin();
     }