pmx-canvas 0.1.20 → 0.1.21

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/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.21",
   "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

@@ -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;
   }

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

@@ -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();
         },
       },

package/src/client/canvas/ExpandedNodeOverlay.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useState } from 'preact/hooks';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
 import { ContextNode } from '../nodes/ContextNode';
 import { FileNode } from '../nodes/FileNode';
 import { LedgerNode } from '../nodes/LedgerNode';
@@ -7,7 +7,7 @@ import { McpAppNode } from '../nodes/McpAppNode';
 import { StatusNode } from '../nodes/StatusNode';
 import { ImageNode } from '../nodes/ImageNode';
 import { WebpageNode } from '../nodes/WebpageNode';
-import { HtmlNode } from '../nodes/HtmlNode';
+import { HtmlNode, shouldShowPresentationControls } from '../nodes/HtmlNode';
 import { PromptNode } from '../nodes/PromptNode';
 import { ResponseNode } from '../nodes/ResponseNode';
 import { TraceNode } from '../nodes/TraceNode';
@@ -81,15 +81,62 @@ function wordCount(text: string): number {
   return text.split(/\s+/).filter(Boolean).length;
 }
 
+function isPresentationExitMessage(value: unknown, token: string): boolean {
+  return value !== null &&
+    typeof value === 'object' &&
+    (value as { source?: unknown }).source === 'pmx-canvas-html-node' &&
+    (value as { type?: unknown }).type === 'presentation-exit' &&
+    (value as { token?: unknown }).token === token;
+}
+
+function isPresentationNavigationKey(key: string): boolean {
+  return key === 'ArrowRight' || key === 'PageDown' || key === ' ' || key === 'ArrowLeft' || key === 'PageUp' || key === 'Home' || key === 'End';
+}
+
 export function ExpandedNodeOverlay() {
   const nodeId = expandedNodeId.value;
   const node = nodeId ? nodes.value.get(nodeId) : undefined;
   const [copied, setCopied] = useState(false);
+  const [presenting, setPresenting] = useState(false);
+  const [presentationExitToken, setPresentationExitToken] = useState('');
+  const presentationOverlayRef = useRef<HTMLDivElement>(null);
 
   const handleClose = useCallback(() => {
+    setPresenting(false);
     collapseExpandedNode();
   }, []);
 
+  const handlePresent = useCallback(() => {
+    setPresentationExitToken(`presentation-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
+    setPresenting(true);
+  }, []);
+
+  const postPresentationMessage = useCallback((message: Record<string, unknown>) => {
+    const frame = document.querySelector<HTMLIFrameElement>('.html-presentation-overlay iframe.html-node-frame-presentation');
+    frame?.contentWindow?.postMessage({
+      source: 'pmx-canvas-html-node',
+      token: presentationExitToken,
+      ...message,
+    }, '*');
+  }, [presentationExitToken]);
+
+  const handleExitPresentation = useCallback(() => {
+    setPresenting(false);
+  }, []);
+
+  const handlePresentationKeyDown = useCallback((event: KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      event.stopPropagation();
+      setPresenting(false);
+      return;
+    }
+    if (!isPresentationNavigationKey(event.key)) return;
+    event.preventDefault();
+    event.stopPropagation();
+    postPresentationMessage({ type: 'presentation-key', key: event.key });
+  }, [postPresentationMessage]);
+
   const handleBackdropPointerDown = useCallback((e: PointerEvent) => {
     if ((e.target as HTMLElement).classList.contains('expanded-overlay-backdrop')) {
       collapseExpandedNode();
@@ -111,6 +158,29 @@ export function ExpandedNodeOverlay() {
     toggleContextPin(nodeId);
   }, [nodeId]);
 
+  useEffect(() => {
+    setPresenting(false);
+  }, [nodeId]);
+
+  useLayoutEffect(() => {
+    if (!presenting) return;
+    const focusPresentationOverlay = () => {
+      presentationOverlayRef.current?.focus();
+    };
+    const focusTimers = [0, 50, 150].map((delay) => window.setTimeout(focusPresentationOverlay, delay));
+    const handleMessage = (event: MessageEvent) => {
+      if (!isPresentationExitMessage(event.data, presentationExitToken)) return;
+      setPresenting(false);
+    };
+    document.addEventListener('keydown', handlePresentationKeyDown, true);
+    window.addEventListener('message', handleMessage);
+    return () => {
+      focusTimers.forEach((timer) => window.clearTimeout(timer));
+      document.removeEventListener('keydown', handlePresentationKeyDown, true);
+      window.removeEventListener('message', handleMessage);
+    };
+  }, [handlePresentationKeyDown, presentationExitToken, presenting]);
+
   if (!node) return null;
 
   const title =
@@ -123,6 +193,7 @@ export function ExpandedNodeOverlay() {
   const hasText = textContent.length > 0;
   const pendingClose = pendingExpandedNodeCloseId.value === nodeId;
   const isEmbeddedViewer = node.type === 'mcp-app' || node.type === 'webpage' || node.type === 'json-render' || node.type === 'graph';
+  const canPresent = shouldShowPresentationControls(node);
 
   return (
     <div
@@ -218,6 +289,17 @@ export function ExpandedNodeOverlay() {
               </button>
             )}
 
+            {canPresent && (
+              <button
+                type="button"
+                class="expanded-action-btn expanded-action-primary"
+                onClick={handlePresent}
+                title="Present this HTML node fullscreen"
+              >
+                Present
+              </button>
+            )}
+
             {/* Word count */}
             {words > 0 && (
               <span class="expanded-meta">
@@ -270,6 +352,27 @@ export function ExpandedNodeOverlay() {
             </div>
           ) : renderContent(node, true)}
         </div>
+        {canPresent && presenting && (
+          <div ref={presentationOverlayRef} class="html-presentation-overlay" role="dialog" aria-modal="true" aria-label={`Present ${title}`} tabIndex={-1} onKeyDownCapture={handlePresentationKeyDown}>
+            <div class="html-presentation-toolbar">
+              <div>
+                <div class="html-presentation-kicker">HTML presentation</div>
+                <div class="html-presentation-title">{title}</div>
+              </div>
+              <button
+                type="button"
+                class="html-presentation-exit"
+                onClick={handleExitPresentation}
+                title="Exit presentation (Esc)"
+              >
+                Exit presentation
+              </button>
+            </div>
+            <div class="html-presentation-stage">
+              <HtmlNode node={node} expanded presentation presentationExitToken={presentationExitToken} />
+            </div>
+          </div>
+        )}
       </div>
     </div>
   );

package/src/client/canvas/auto-fit.ts

@@ -11,8 +11,12 @@ function hasExplicitStructuredFrame(node: CanvasNodeState): boolean {
   return node.type === 'graph' || node.type === 'json-render';
 }
 
+function isPresentationHtmlNode(node: CanvasNodeState): boolean {
+  return node.type === 'html' && node.data.presentation === true;
+}
+
 export function shouldAutoFitNode(node: CanvasNodeState): boolean {
-  return !node.collapsed && !node.dockPosition && node.data.strictSize !== true && node.type !== 'group' && !isExtAppNode(node) && !hasExplicitStructuredFrame(node);
+  return !node.collapsed && !node.dockPosition && node.data.strictSize !== true && node.type !== 'group' && !isExtAppNode(node) && !hasExplicitStructuredFrame(node) && !isPresentationHtmlNode(node);
 }
 
 export function computeAutoFitHeight(node: CanvasNodeState, contentHeight: number): number | null {