pmx-canvas 0.1.20 → 0.1.22

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

@@ -1,5 +1,16 @@
 import type { CanvasNodeState } from '../types';
-export declare function HtmlNode({ node, expanded }: {
+export declare function createHtmlNodeSrcDocForTest(userHtml: string, options: {
+    theme: string;
+    themeCss: string;
+    themeToken?: string;
+    presentation?: boolean;
+    presentationExitToken?: string;
+}): string;
+export declare function shouldShowPresentationControls(node: CanvasNodeState): boolean;
+export declare function HtmlNode({ node, expanded, presentation, presentationExitToken, autoFocus, }: {
     node: CanvasNodeState;
     expanded?: boolean;
+    presentation?: boolean;
+    presentationExitToken?: string;
+    autoFocus?: boolean;
 }): import("preact/src").JSX.Element;

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

@@ -52,7 +52,7 @@ export interface CanvasAnnotation {
 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. */
-export declare const EXPANDABLE_TYPES: Set<"markdown" | "mcp-app" | "webpage" | "json-render" | "graph" | "prompt" | "response" | "status" | "context" | "ledger" | "trace" | "file" | "image" | "html" | "group">;
+export declare const EXPANDABLE_TYPES: Set<"html" | "markdown" | "mcp-app" | "webpage" | "json-render" | "graph" | "prompt" | "response" | "status" | "context" | "ledger" | "trace" | "file" | "image" | "group">;
 export declare const EXCALIDRAW_SERVER_NAME = "Excalidraw";
 export declare const EXCALIDRAW_CREATE_VIEW_TOOL = "create_view";
 export declare function isExcalidrawNode(node: CanvasNodeState): boolean;

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

@@ -35,6 +35,7 @@ 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 serializeCanvasNodeCompact(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasNodeWithBlobSummaries(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasLayout(layout: CanvasLayout): SerializedCanvasLayout;
 export declare function serializeCanvasLayoutForAgent(layout: CanvasLayout): SerializedCanvasLayout;

package/dist/types/server/html-node-summary.d.ts

@@ -0,0 +1,2 @@
+export declare function summarizeHtmlText(html: string): string | null;
+export declare function normalizeHtmlNodeSemanticData<T extends Record<string, unknown>>(data: T): T;

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

@@ -1,4 +1,4 @@
-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 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", "presentation", "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;
@@ -28,7 +28,15 @@ export interface HtmlPrimitiveBuildResult {
     };
     data: Record<string, unknown>;
 }
+export interface HtmlPrimitiveSemanticMetadata {
+    presentation?: true;
+    slideCount?: number;
+    slideTitles?: string[];
+    speakerNotes?: string[];
+    presentationTheme?: string | Record<string, string>;
+}
 export declare function isHtmlPrimitiveKind(value: string): value is HtmlPrimitiveKind;
 export declare function getHtmlPrimitiveDescriptor(kind: HtmlPrimitiveKind): HtmlPrimitiveDescriptor;
 export declare function listHtmlPrimitiveDescriptors(): HtmlPrimitiveDescriptor[];
+export declare function getHtmlPrimitiveSemanticMetadata(data: Record<string, unknown>): HtmlPrimitiveSemanticMetadata;
 export declare function buildHtmlPrimitive(input: HtmlPrimitiveInput): HtmlPrimitiveBuildResult;

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

@@ -244,6 +244,13 @@ export declare class PmxCanvas extends EventEmitter {
     addHtmlNode(input: {
         html: string;
         title?: string;
+        summary?: string;
+        agentSummary?: string;
+        description?: string;
+        presentation?: boolean;
+        slideTitles?: string[];
+        embeddedNodeIds?: string[];
+        embeddedUrls?: string[];
         x?: number;
         y?: number;
         width?: number;
@@ -292,7 +299,7 @@ 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 { buildHtmlPrimitive, getHtmlPrimitiveSemanticMetadata, 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';

package/docs/http-api.md

@@ -40,7 +40,7 @@ curl -X POST http://localhost:4313/api/canvas/node \
 # Add an html node (sandboxed iframe)
 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>"}'
+  -d '{"type":"html","title":"Chart","summary":"Cost projection chart for the Q2 plan.","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 \

package/docs/mcp.md

@@ -37,6 +37,10 @@ The canvas auto-starts on first tool call.
 | `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) |
 | `canvas_build_web_artifact` | Build a bundled HTML artifact and open it on the canvas |
+
+`canvas_add_html_node` accepts optional `summary`, `agentSummary`, `embeddedNodeIds`, and
+`embeddedUrls`. PMX also derives a bounded text summary from visible HTML, so rich HTML nodes stay
+searchable and readable in pinned/spatial context.
 | `canvas_update_node` | Update content, position, size, collapsed state |
 | `canvas_remove_node` | Remove a node and its edges |
 | `canvas_get_layout` | Get full canvas state |

package/docs/node-types.md

@@ -143,7 +143,7 @@ component catalog before building a spec.
 
 ## HTML nodes
 
-`html` nodes render a self-contained HTML/JS document in a sandboxed iframe.
+`html` nodes render a normal self-contained HTML/JS document in a sandboxed iframe.
 They sit between `json-render` (no custom JS) and `web-artifact` (full bundled
 React app) — perfect for Chart.js, D3, custom widgets, and any HTML you can
 write or paste.
@@ -152,7 +152,8 @@ The sandbox runs with `allow-scripts` only — no same-origin access, no
 top-level navigation, no form submission. Inline `<script>` and CDN
 `<script src>` both work. The canvas auto-injects its theme tokens
 (`--c-*` and `--color-*` aliases) into the iframe `<head>` so artifacts can
-match the active theme.
+match the active theme. Theme updates are posted into sandboxed HTML iframes,
+so theme-aware HTML can follow dark/light switches without reopening the node.
 
 ```ts
 canvas_add_html_node({
@@ -164,6 +165,17 @@ canvas_add_html_node({
 A fragment without `<html>`/`<head>` is wrapped in a full document
 automatically. Default size is 720×640.
 
+Presentation mode is opt-in. Raw HTML nodes do not show the browser `Present`
+button unless callers set `presentation: true`; prefer the `presentation`
+primitive when the user explicitly asks for a PowerPoint-like deck, pitch,
+briefing, workshop walkthrough, or fullscreen story.
+
+HTML nodes also store an agent-readable semantic sidecar. Callers can pass
+`summary`, `agentSummary`, `embeddedNodeIds`, or `embeddedUrls`; when no summary
+is provided, PMX derives `data.contentSummary` from visible HTML text and stores
+`data.agentSummary` for search, pinned context, and spatial context. Scripts and
+styles are ignored during extraction.
+
 ### HTML primitives
 
 `html-primitive` is a virtual schema type that creates a normal sandboxed
@@ -171,8 +183,8 @@ automatically. Default size is 720×640.
 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.
+presentation, explainer, status report, incident report, triage board, config
+editor, or prompt tuner.
 
 ```ts
 canvas_add_html_primitive({
@@ -189,7 +201,17 @@ canvas_add_html_primitive({
 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.
+the generated `data.html` payload. Generated primitives also get an
+agent-readable summary sidecar.
+
+Only presentation-marked HTML nodes expose a `Present` button in the browser.
+Use the `presentation` primitive for PowerPoint-like decks; it persists
+`presentation`, `slideCount`, `slideTitles`, optional `speakerNotes`, and
+optional `presentationTheme` metadata while the iframe handles
+Arrow/Space/Page Up/Page Down slide navigation. Presentation data supports
+`theme: "canvas" | "midnight" | "paper" | "aurora"` or a custom color object with
+`bg`, `panel`, `surface`, `border`, `text`, `textSecondary`, `textMuted`,
+`accent`, and `colorScheme`.
 
 ## Web artifacts
 

package/docs/sdk.md

@@ -29,6 +29,7 @@ canvas.createGroup({ title: 'Build Pipeline', childIds: [n1, n2] });
 // Self-contained HTML in a sandboxed iframe
 canvas.addHtmlNode({
   title: 'Cost projection',
+  summary: 'Cost projection chart for the Q2 plan.',
   html: '<canvas id="c"></canvas><script src="https://cdn.jsdelivr.net/npm/chart.js"></script><script>/* ... */</script>',
 });
 

package/package.json

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

@@ -50,6 +50,7 @@ tree:
 2. Decide which canvas node type best matches each output:
    - Long-form / narrative results → `markdown`
    - Structured records, tables, dashboards → `json-render` or `graph`
+   - Rich reusable communication artifacts → `html-primitive`
    - Interactive tool surfaces with their own UI → `mcp-app` (open with
      `canvas_open_mcp_app`)
    - Local source files → `file` (live-watched)
@@ -653,18 +654,23 @@ server's `ui://` resource as an iframe node on the canvas
 
 ### HTML Nodes (Sandboxed iframe)
 
-**`canvas_add_html_node`** — Add a self-contained HTML document rendered in a sandboxed iframe
+**`canvas_add_html_node`** — Add a normal self-contained HTML document rendered in a sandboxed iframe
 - Required: `html` (full document or fragment; inline `<script>` and CDN `<script src="...">` are allowed)
-- Optional: `title`, `x`, `y`, `width` (default 720), `height` (default 640), `strictSize`
+- Optional: `title`, `summary`, `agentSummary`, `presentation`, `slideTitles`, `embeddedNodeIds`, `embeddedUrls`, `x`, `y`, `width` (default 720), `height` (default 640), `strictSize`
 - Iframe sandbox is `allow-scripts` only — no same-origin access, no top-navigation, no forms
-- 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
+- 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`) and updated live when the canvas theme changes
 - 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)
+- Normal HTML is the default. Only pass `presentation: true` when the user explicitly asks for a deck/fullscreen presentation; otherwise do not mark raw HTML as presentable.
+- Only presentation-marked HTML nodes expose a browser `Present` button. Use it when the HTML is a deck, briefing, or fullscreen review surface; the PMX shell owns the fullscreen overlay and exits via `Esc` or `Exit presentation`.
+- PMX stores a semantic sidecar (`agentSummary`, `contentSummary`, embedded references) so HTML nodes remain understandable in search, pinned context, and spatial context
 
 **`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
+- When the human asks for a PowerPoint-like output, pitch deck, briefing, or presentation, use `kind: "presentation"` unless a bespoke raw HTML deck is required. Include `slides` with short titles, one idea per slide, optional `metrics`, `note` fields for speaker notes, and optional `theme: "canvas" | "midnight" | "paper" | "aurora"` or a custom theme object.
 - Read `htmlPrimitives` from `canvas_describe_schema` for the data shape and examples before constructing a payload
+- For payload patterns, export loops, and the primitive catalog, read `references/html-primitives.md` before creating dense or editable artifacts
 
 ### Choosing the Right Visual Tier
 
@@ -673,7 +679,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 |
+| Generated HTML primitive | `canvas_add_html_primitive` | None | Reusable communication artifacts such as choices, plans, reviews, maps, reports, presentations/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/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

@@ -164,7 +164,7 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
   // Boolean-only flags (never take a value argument)
   const BOOL_FLAGS = new Set([
     'help', 'h', 'ids', 'stdin', 'yes', 'list', 'clear', 'set', 'animated', 'dry-run', 'all',
-    'no-open-in-canvas', 'lock-arrange', 'unlock-arrange', 'json', 'compact', 'summary',
+    'no-open-in-canvas', 'lock-arrange', 'unlock-arrange', 'json', 'compact',
     'verbose', 'include-logs', 'no-pan', 'schema', 'example', 'examples', 'strict-size', 'scroll-overflow',
   ]);
   for (let i = 0; i < args.length; i++) {
@@ -1160,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;
   }
@@ -1714,6 +1723,16 @@ cmd('external-app add', 'Create a hosted external app node', [
     : result);
 });
 
+cmd('diagram add', 'Create an Excalidraw diagram node', [
+  'pmx-canvas diagram add --title "Architecture"',
+  'pmx-canvas diagram add --title "Architecture" --elements \'[{"type":"rectangle","id":"r1","x":0,"y":0,"width":120,"height":80}]\'',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('diagram add');
+  const externalAppAdd = COMMANDS['external-app add'];
+  await externalAppAdd.run([...args, '--kind', 'excalidraw']);
+});
+
 // ── pin ──────────────────────────────────────────────────────
 cmd('pin', 'Manage context pins', [
   'pmx-canvas pin node1 node2 node3',
@@ -2422,11 +2441,19 @@ function showCommandHelp(name: string): void {
   if (name === 'node add') {
     console.log('\nSchema help:');
     console.log('  pmx-canvas node add --help --type webpage');
+    console.log('  pmx-canvas node add --help --type html');
     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.');
+    console.log('\nHTML sidecar flags:');
+    console.log('  --summary <text>           Explicit human/agent-readable summary');
+    console.log('  --agent-summary <text>     Semantic summary for search, pinned context, and spatial context');
+    console.log('  --description <text>       Optional longer semantic description');
+    console.log('  --presentation true        Mark raw HTML as an explicit presentation deck');
+    console.log('  --slide-title <text>       Add a presentation slide title sidecar');
+    console.log('  --embedded-node-id <id>    Link represented/embedded canvas node ID');
   }
   if (name === 'html primitive add' || name === 'html primitive schema') {
     console.log('\nPrimitive flags:');
@@ -2525,6 +2552,10 @@ function showCommandHelp(name: string): void {
     console.log('  --initial-file <path>      Alias for --elements-file');
     console.log('  --timeout-ms <number>      Optional downstream MCP timeout for cold starts');
   }
+  if (name === 'diagram add') {
+    console.log('\nAlias:');
+    console.log('  Equivalent to: pmx-canvas external-app add --kind excalidraw ...');
+  }
   console.log('');
 }
 
@@ -2552,6 +2583,7 @@ Node commands:
   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
+  pmx-canvas diagram add               Add an Excalidraw diagram node
 
 Edge commands:
   pmx-canvas edge add [options]       Add an edge between nodes
@@ -2627,6 +2659,7 @@ Examples:
   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 diagram add --title "Architecture"
   pmx-canvas node add --help --type webpage
   pmx-canvas node schema --type json-render
   pmx-canvas node schema --type json-render --component Table --summary

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', 'diagram', 'graph', 'html', 'batch', 'validate', 'serve',
 ]);
 
 const firstArg = args[0] ?? '';
@@ -506,6 +506,7 @@ Agent CLI (works against running server):
   watch [--json] [--events ...]       Watch low-token semantic canvas changes
   focus <node-id>                     Pan to node
   external-app add                    Add hosted external apps like Excalidraw
+  diagram add                         Add an Excalidraw diagram node
   pin <ids...> | --list | --clear     Manage context pins
   undo / redo / history               Time travel
   snapshot save|list|restore|diff|delete
@@ -550,6 +551,7 @@ Examples:
   pmx-canvas node schema --type json-render                   Show running-server schema info
   pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx
   pmx-canvas external-app add --kind excalidraw --title "Diagram"
+  pmx-canvas diagram add --title "Diagram"
   pmx-canvas validate spec --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value
   pmx-canvas open                                             Open the workbench in a browser
   pmx-canvas webview status                                   Show WebView automation status

package/src/client/App.tsx

@@ -237,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`}
           >

package/src/client/canvas/CommandPalette.tsx

@@ -145,9 +145,9 @@ export function CommandPalette({
         badge: 'THEME',
         action: () => {
           const next = canvasTheme.value === 'dark' ? 'light' : 'dark';
-          canvasTheme.value = next;
           document.documentElement.setAttribute('data-theme', next);
           invalidateTokenCache();
+          canvasTheme.value = next;
           onClose();
         },
       },