pmx-canvas 0.6.4 → 0.6.5

package/dist/types/cli/agent.d.ts

@@ -21,6 +21,7 @@ import './commands/history.js';
 import './commands/ax.js';
 import './commands/pump.js';
 import './commands/webview.js';
+import './commands/record.js';
 import './commands/apps.js';
 import './commands/copilot.js';
 import './commands/skills.js';

package/dist/types/cli/commands/record.d.ts

@@ -0,0 +1,12 @@
+export declare function parseRecordOptions(flags: Record<string, string | boolean>): {
+    theme: "dark" | "light" | "high-contrast" | "midnight" | "sepia" | "arctic" | "ember" | "forest" | "volt" | undefined;
+    present: boolean;
+    tourFile: string | undefined;
+    chromePath: string | undefined;
+    width: number;
+    height: number;
+    fps: number;
+    mode: "realtime" | "deterministic";
+    output: string;
+    duration?: number | undefined;
+};

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

@@ -0,0 +1,13 @@
+import { type Camera } from '../../shared/tour.js';
+import { canvasArea } from './canvas-area';
+declare global {
+    interface Window {
+        pmxCapture?: {
+            ready: () => boolean;
+            area: typeof canvasArea;
+            camera: () => Camera;
+            frame: (camera: Camera) => Promise<Camera>;
+        };
+    }
+}
+export declare function Presentation(): import("preact/jsx-runtime").JSX.Element | null;

package/dist/types/client/canvas/use-node-drag.d.ts

@@ -5,11 +5,12 @@ interface NodeDragOptions {
     viewport: Signal<ViewportState>;
     onMove: (id: string, x: number, y: number) => void;
     onDragEnd: () => void;
+    onClick?: () => void;
 }
 /**
  * Hook for dragging canvas nodes by their title bar.
  * Converts screen-space pointer delta to canvas-space position delta
  * (accounting for current viewport scale).
  */
-export declare function useNodeDrag({ nodeId, viewport, onMove, onDragEnd }: NodeDragOptions): (e: PointerEvent, currentX: number, currentY: number) => void;
+export declare function useNodeDrag({ nodeId, viewport, onMove, onDragEnd, onClick }: NodeDragOptions): (e: PointerEvent, currentX: number, currentY: number) => void;
 export {};

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

@@ -1,6 +1,29 @@
+import type { RefObject } from 'preact';
 import type { CanvasNodeState } from '../types';
 export declare function isSameOriginFrameDocumentUrl(url: string, origin?: string): boolean;
+type ViewerFrameSource = {
+    src?: string;
+    srcdoc?: string;
+};
+/**
+ * Keep the last painted viewer in front while its replacement navigates. Viewer
+ * specs are immutable documents, so updates normally change `?v=` and reload the
+ * iframe; putting the new document in a hidden sibling avoids exposing Chromium's
+ * white navigation paint. Two animation frames after load gives the new document
+ * a composited paint before the old one is removed.
+ */
+export declare function RefreshingViewerFrame({ source, iframeRef, onLoad, title, className, sandbox, allow, tabIndex, }: {
+    source: ViewerFrameSource;
+    iframeRef: RefObject<HTMLIFrameElement>;
+    onLoad: () => void;
+    title: string;
+    className?: string;
+    sandbox?: string;
+    allow?: string;
+    tabIndex?: number;
+}): import("preact").JSX.Element;
 export declare function McpAppNode({ node, expanded }: {
     node: CanvasNodeState;
     expanded?: boolean;
-}): import("preact/jsx-runtime").JSX.Element;
+}): import("preact").JSX.Element;
+export {};

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

@@ -0,0 +1,3 @@
+export declare const presenting: import("@preact/signals-core").Signal<boolean>;
+export declare const recordingCamera: import("@preact/signals-core").Signal<boolean>;
+export declare function ownsCamera(): boolean;

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

@@ -54,7 +54,7 @@ export type AnnotationTool = 'pen' | 'eraser' | 'text' | null;
 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<"html" | "markdown" | "mcp-app" | "webpage" | "json-render" | "graph" | "prompt" | "response" | "status" | "context" | "ledger" | "trace" | "file" | "diff" | "mermaid" | "image" | "group">;
+export declare const EXPANDABLE_TYPES: Set<"file" | "group" | "html" | "markdown" | "mcp-app" | "webpage" | "json-render" | "graph" | "prompt" | "response" | "status" | "context" | "ledger" | "trace" | "diff" | "mermaid" | "image">;
 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/json-render/catalog.d.ts

@@ -474,10 +474,10 @@ export declare const allComponentDefinitions: {
             text: z.ZodString;
             variant: z.ZodNullable<z.ZodEnum<{
                 error: "error";
+                success: "success";
+                default: "default";
                 info: "info";
                 warning: "warning";
-                default: "default";
-                success: "success";
                 secondary: "secondary";
                 destructive: "destructive";
                 outline: "outline";

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

@@ -65,6 +65,8 @@ export declare const GRAPH_NODE_SIZE: {
 export type GraphChartType = 'LineChart' | 'BarChart' | 'PieChart' | 'AreaChart' | 'ScatterChart' | 'RadarChart' | 'StackedBarChart' | 'ComposedChart' | 'Sparkline' | 'DotPlot' | 'BulletChart' | 'Slopegraph';
 export declare function inferJsonRenderNodeTitle(spec: JsonRenderSpec, fallback?: string): string;
 export declare function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpec;
+/** shadcn 0.21 ignores these props unless the renderer supplies a two-way binding. */
+export declare function jsonRenderFormWarnings(spec: JsonRenderSpec): string[];
 export declare function normalizeGraphType(value: string): GraphChartType;
 export declare function buildGraphSpec(input: GraphNodeInput): JsonRenderSpec;
 export declare function buildGraphConfig(input: GraphNodeInput): Record<string, unknown>;

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

@@ -5,12 +5,14 @@
  * WAL-mode persistence. Replaces the previous JSON file-based approach.
  */
 import { Database } from 'bun:sqlite';
+import { type Tour } from '../shared/tour.js';
 import { type CanvasThemeName } from '../shared/themes.js';
 import type { CanvasAnnotation, CanvasEdge, CanvasNodeState, CanvasSnapshot, CanvasSnapshotListOptions, ViewportState } from './canvas-state.js';
 import { type PmxAxState, type PmxAxEvent, type PmxAxEvidence, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
 export type CanvasTheme = CanvasThemeName;
 export declare function normalizeCanvasTheme(value: unknown, fallback?: CanvasTheme): CanvasTheme;
 export interface PersistedCanvasState {
+    tour?: Tour;
     version: number;
     theme?: CanvasTheme;
     viewport: ViewportState;

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

@@ -73,6 +73,21 @@ export declare const LEDGER_NODE_DEFAULT_SIZE: {
     width: number;
     height: number;
 };
+export interface CanvasSizeAdjustment {
+    requested: {
+        width: number | null;
+        height: number | null;
+    };
+    applied: {
+        width: number;
+        height: number;
+    };
+    reason: 'defaulted' | 'clamped-to-minimum' | 'defaulted-and-clamped-to-minimum' | 'fit-to-children';
+}
+export declare function describeCreateSize(requestedWidth: number | undefined, requestedHeight: number | undefined, resolvedWidth: number, resolvedHeight: number, applied: {
+    width: number;
+    height: number;
+}): CanvasSizeAdjustment | undefined;
 interface CanvasCreateGroupInput {
     title?: string;
     childIds?: string[];
@@ -146,6 +161,7 @@ export declare function addCanvasNode(input: CanvasAddNodeInput): {
     id: string;
     node: CanvasNodeState;
     needsCodeGraphRecompute: boolean;
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 export declare function resolveCanvasNode(nodeRef: CanvasNodeLookupInput): {
     ok: true;
@@ -213,11 +229,13 @@ export declare function removeCanvasEdge(id: string): {
 export declare function createCanvasGroup(input: CanvasCreateGroupInput): {
     id: string;
     node: CanvasNodeState;
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 export declare function groupCanvasNodes(groupId: string, childIds: string[], options?: {
     childLayout?: CanvasArrangeMode;
 }): {
     ok: boolean;
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 export declare function ungroupCanvasNodes(groupId: string): {
     ok: boolean;
@@ -230,6 +248,8 @@ export declare function createCanvasJsonRenderNode(input: JsonRenderNodeInput):
     url: string;
     spec: JsonRenderSpec;
     node: CanvasNodeState;
+    warnings: string[];
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 /**
  * Create an empty streaming json-render node. Unlike createCanvasJsonRenderNode
@@ -248,6 +268,7 @@ export declare function createCanvasStreamingJsonRenderNode(input: {
     url: string;
     spec: JsonRenderSpec;
     node: CanvasNodeState;
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 /**
  * Apply a batch of SpecStream patches to an existing json-render node, bumping
@@ -269,6 +290,7 @@ export declare function createCanvasGraphNode(input: GraphNodeInput): {
     url: string;
     spec: JsonRenderSpec;
     node: CanvasNodeState;
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 export declare function setClientViewportSize(width: unknown, height: unknown): void;
 export declare function getClientViewportSize(): {

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

@@ -22,6 +22,7 @@ export interface StructuredValidationResult {
     ok: true;
     type: 'json-render' | 'graph' | 'html-primitive';
     normalizedSpec?: JsonRenderSpec;
+    warnings?: string[];
     normalizedPrimitive?: {
         kind: string;
         title: string;

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

@@ -11,6 +11,7 @@
  * `.pmx-canvas-snapshots/`, loose blob files) are no longer imported as of 0.4.0 —
  * the one-shot boot migration into SQLite was retired.
  */
+import { type Tour } from '../shared/tour.js';
 import { type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
 import { type PmxAxActivityKind, type PmxAxElicitation, type PmxAxModeRequest, type PmxAxMode, type PmxAxCommandDescriptor, type PmxAxPolicy, type PmxAxFocusState, type PmxAxSource, type PmxAxState, type PmxAxWorkItem, type PmxAxWorkItemStatus, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxReviewKind, type PmxAxReviewSeverity, type PmxAxReviewStatus, type PmxAxReviewAnchorType, type PmxAxReviewRegion, type PmxAxEvent, type PmxAxEventKind, type PmxAxEvidence, type PmxAxEvidenceKind, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
 export declare const PMX_CANVAS_DIR = ".pmx-canvas";
@@ -102,6 +103,7 @@ export interface CanvasAnnotation {
     createdAt: string;
 }
 export interface CanvasLayout {
+    tour?: Tour;
     viewport: ViewportState;
     theme: CanvasTheme;
     nodes: CanvasNodeState[];
@@ -140,6 +142,7 @@ declare class CanvasStateManager {
     private edges;
     private annotations;
     private _viewport;
+    private _tour;
     private _theme;
     private _contextPinnedNodeIds;
     private _workspaceRoot;
@@ -236,6 +239,7 @@ declare class CanvasStateManager {
         nodes: CanvasNodeState[];
         edges: CanvasEdge[];
         annotations: CanvasAnnotation[];
+        tour?: Tour;
     } | null;
     /** Delete a snapshot. */
     renameSnapshot(id: string, name: string): boolean;
@@ -261,6 +265,8 @@ declare class CanvasStateManager {
     private removeEdgesForNode;
     getLayout(): CanvasLayout;
     getLayoutForPersistence(): CanvasLayout;
+    getTour(): Tour | undefined;
+    setTour(tour: Tour | null): void;
     applyUpdates(updates: CanvasNodeUpdate[], options?: ApplyUpdatesOptions): {
         applied: number;
         skipped: number;

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

@@ -26,6 +26,8 @@ export interface CanvasValidationResult {
     collisions: CanvasValidationPair[];
     containments: CanvasContainmentIssue[];
     containmentViolations: CanvasContainmentIssue[];
+    /** Group frames overlapping nodes that are not members (advisory). */
+    groupFrameOverlaps: CanvasValidationPair[];
     missingEdgeEndpoints: Array<{
         edgeId: string;
         from: string;
@@ -39,6 +41,7 @@ export interface CanvasValidationResult {
         collisions: number;
         containments: number;
         containmentViolations: number;
+        groupFrameOverlaps: number;
         missingEdgeEndpoints: number;
         sizeWarnings: number;
     };

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

@@ -60,7 +60,7 @@ export declare function buildContentHeightReporter(frameToken: string): string;
  * of the main SPA bundle). Escaping is mandatory: the source is arbitrary node
  * data and must not be parsed as markup.
  */
-export declare function buildMermaidSurfaceHtml(source: string, inlineEntry?: string | null): string;
+export declare function buildMermaidSurfaceHtml(source: string, inlineEntry?: string | null, fit?: 'contain' | 'none', frameToken?: string): string;
 export interface HtmlSurfaceOptions {
     theme: SurfaceTheme;
     /**

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

@@ -1,4 +1,6 @@
 import { EventEmitter } from 'node:events';
+import { type Tour } from '../shared/tour.js';
+export type { Tour, TourStop } from '../shared/tour.js';
 import type { AgentPhase, AgentPresence, AgentPresenceSnapshot } from '../shared/agent-presence.js';
 import { canvasState } from './canvas-state.js';
 import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
@@ -140,6 +142,8 @@ export declare class PmxCanvas extends EventEmitter {
     ungroupNodes(groupId: string, options?: {
         intentId?: string;
     }): boolean;
+    getTour(): Tour;
+    setTour(tour: Tour | null): void;
     clear(): void;
     arrange(layout?: 'grid' | 'column' | 'flow'): void;
     focusNode(id: string, options?: {

package/dist/types/server/operations/ops/app.d.ts

@@ -1,3 +1,4 @@
+import { type CanvasSizeAdjustment } from '../../canvas-operations.js';
 import { type ExternalMcpTransportConfig } from '../../mcp-app-runtime.js';
 import { type Operation, type OperationContext } from '../types.js';
 export interface OpenMcpAppCoreInput {
@@ -20,6 +21,7 @@ export interface OpenMcpAppCoreResult {
     toolCallId: string;
     sessionId: string;
     resourceUri: string;
+    sizeAdjustment?: CanvasSizeAdjustment;
 }
 /**
  * Open an external MCP app: connect + call + read resource (openExternalMcpApp),

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

@@ -1,3 +1,4 @@
+import { type CanvasSizeAdjustment } from '../../canvas-operations.js';
 import { type Operation } from '../types.js';
 /** Legacy server.ts parseGraphPayloadData: a graph dataset must be an array of records. */
 export declare function parseGraphPayloadData(value: unknown): Array<Record<string, unknown>> | null;
@@ -21,6 +22,7 @@ export interface StreamJsonRenderResult {
     specVersion: number;
     elementCount: number;
     streamStatus: 'open' | 'closed';
+    sizeAdjustment?: CanvasSizeAdjustment;
 }
 /**
  * Create-or-append core for streaming json-render nodes (the SDK's

package/dist/types/server/operations/ops/nodes.d.ts

@@ -1,4 +1,5 @@
 import { type CanvasLayout, type CanvasNodeState } from '../../canvas-state.js';
+import { type CanvasSizeAdjustment } from '../../canvas-operations.js';
 import { type Operation } from '../types.js';
 export declare const NODE_TYPES: readonly ["markdown", "status", "context", "ledger", "trace", "file", "diff", "mermaid", "image", "mcp-app", "webpage", "html", "group"];
 /** Per-type default node frame size (formerly copy-pasted ladders). */
@@ -30,7 +31,7 @@ export declare function agentSafeFullLayoutPayload(layout: CanvasLayout): Record
  * agents using either key (or a cached schema) work — matching the
  * external-app / web-artifact responses that already return both.
  */
-export declare function createdNodePayloadFromNode(node: CanvasNodeState, options?: Record<string, unknown>): Record<string, unknown>;
+export declare function createdNodePayloadFromNode(node: CanvasNodeState, options?: Record<string, unknown>, extras?: Record<string, unknown>): Record<string, unknown>;
 /**
  * Create a basic (non-webpage / non-group / non-primitive) node. Union of the
  * legacy handleCanvasAddNode generic branch; the SDK passes fileMode 'path',
@@ -41,6 +42,7 @@ export declare function createBasicCanvasNode(body: Record<string, unknown>, opt
 }): {
     node: CanvasNodeState;
     needsCodeGraphRecompute: boolean;
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 /**
  * Build a node patch with the full HTTP superset semantics (webpage

package/dist/types/server/web-artifacts.d.ts

@@ -1,3 +1,4 @@
+import { type CanvasSizeAdjustment } from './canvas-operations.js';
 export interface WebArtifactBuildInput {
     title: string;
     appTsx: string;
@@ -41,11 +42,13 @@ export interface WebArtifactSourceContext {
 export interface WebArtifactCanvasOpenResult {
     nodeId: string;
     url: string;
+    sizeAdjustment: CanvasSizeAdjustment;
 }
 export interface WebArtifactCanvasBuildResult extends WebArtifactBuildOutput {
     openedInCanvas: boolean;
     nodeId?: string;
     url?: string;
+    sizeAdjustment?: CanvasSizeAdjustment;
     startedAt: string;
     completedAt: string;
     durationMs: number;

package/dist/types/shared/tour.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+export declare const cameraSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    scale: z.ZodNumber;
+}, z.core.$strip>;
+export declare const tourStopSchema: z.ZodObject<{
+    target: z.ZodUnion<readonly [z.ZodObject<{
+        nodeId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        viewport: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            scale: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strict>]>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    easing: z.ZodOptional<z.ZodEnum<{
+        linear: "linear";
+        "ease-in-out": "ease-in-out";
+        "ease-out": "ease-out";
+    }>>;
+    padding: z.ZodOptional<z.ZodNumber>;
+    pullback: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const tourSchema: z.ZodObject<{
+    stops: z.ZodArray<z.ZodObject<{
+        target: z.ZodUnion<readonly [z.ZodObject<{
+            nodeId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            viewport: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                scale: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strict>]>;
+        duration: z.ZodOptional<z.ZodNumber>;
+        easing: z.ZodOptional<z.ZodEnum<{
+            linear: "linear";
+            "ease-in-out": "ease-in-out";
+            "ease-out": "ease-out";
+        }>>;
+        padding: z.ZodOptional<z.ZodNumber>;
+        pullback: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Tour = z.infer<typeof tourSchema>;
+export type TourStop = z.infer<typeof tourStopSchema>;
+export type Camera = z.infer<typeof cameraSchema>;
+export interface TourNode {
+    id: string;
+    type: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+}
+export declare function derivedTour(nodes: TourNode[]): Tour;
+export declare function resolveStop(stop: TourStop, nodes: TourNode[], width: number, height: number): Camera;
+/** Interpolate world-space centres and log zoom; translations remain screen-space. */
+export declare function interpolateCamera(from: Camera, to: Camera, progress: number, width: number, height: number, easing?: TourStop['easing'], pullback?: number): Camera;
+/** Each segment includes its endpoint; zero-duration stops take one frame. */
+export declare function segmentFrameCount(duration: number, fps: number): number;
+export declare function tourFrames(tour: Tour, initial: Camera, nodes: TourNode[], width: number, height: number, fps: number): Generator<{
+    x: number;
+    y: number;
+    scale: number;
+}, void, unknown>;

package/docs/cli.md

@@ -13,6 +13,91 @@ pmx-canvas node list --port 4750                      # target a non-default dae
 pmx-canvas --server-url http://127.0.0.1:4750 status  # same, by URL
 ```
 
+## Tour and presentation
+
+This is the small tour slice of the [vision's “board is the presentation”](product-vision-2026-09.md#12-tours-the-board-is-the-presentation-m):
+the existing cards remain the content, rather than being rebuilt as a separate deck.
+The same stops and camera interpolation drive interactive presentation and optional capture.
+A visual stop editor and carrying tours into static exports/share links are not implemented here.
+
+Click **Present** in the top bar, or open `/workbench?present=1` for a chrome-free
+embedded/capture view. Right/Down/Space advances, Left/Up goes back, Esc exits.
+The camera is local to the viewer; board content continues updating over SSE.
+Stops do not auto-advance. Missing targets show an error and can be skipped.
+
+Save this as `tour.json` (replace the IDs with IDs from `pmx-canvas node list`):
+
+```json
+{
+  "stops": [
+    { "target": { "nodeId": "overview-group" }, "duration": 1.5, "padding": 60 },
+    { "target": { "nodeId": "detail-note" }, "duration": 2, "easing": "ease-in-out", "pullback": 0.7 },
+    { "target": { "viewport": { "x": 80, "y": 100, "scale": 0.5 } }, "duration": 1 }
+  ]
+}
+```
+
+```bash
+pmx-canvas tour set --file tour.json
+pmx-canvas tour get
+```
+
+A stop targets either a node ID (including a group ID) or an explicit viewport.
+Viewport translation is screen-space: `screen = world * scale + offset`.
+`duration` is transition time in seconds (default 1, zero jumps); `padding` is
+screen pixels around a target (default 40). Easing is `linear`, `ease-in-out`
+(default), or `ease-out`. Zoom interpolates logarithmically about the moving
+world-space centre. `pullback` (0–4, default 0) subtracts a sinusoidal log-zoom
+offset mid-move without changing endpoints. Tours allow at most 1000 stops.
+
+Tours persist with the board and snapshots, participate in undo, and clear with
+the board. A file containing `null` resets the tour: when none is saved, groups
+are sorted by y, then x, then ID. A saved empty `stops` array deliberately has no
+stops. SDK: `canvas.setTour(tourOrNull)` / `canvas.getTour()`.
+
+### Optional capture of the same tour
+
+`record` is an optional local utility, not a second presentation model. It reads
+the saved/derived tour, or the identical tour JSON supplied with `--tour-file`.
+Start the server first. Capture launches its own Bun.WebView Chrome session;
+it does not replace a server automation session or move other viewers' cameras.
+
+```bash
+# Capture the saved/derived board tour
+pmx-canvas record --mode deterministic --present --fps 30 --resolution 1920x1080 --output tour.mp4
+
+# Try the same tour model from a file without changing the saved tour
+pmx-canvas record --mode deterministic --tour-file tour.json --present --output frames
+
+# Alternatively, sample the live presentation while agents update the board
+pmx-canvas record --duration 10 --present --theme light --output activity.mp4
+
+# Keep recording until SIGINT (Ctrl+C) or SIGTERM, then encode
+pmx-canvas record --stop-on-signal --output live.mp4
+```
+
+Options: `--mode realtime|deterministic` (default realtime), `--resolution WIDTHxHEIGHT`
+(default 1280x720), `--fps` (1–120, default 30), `--theme`, `--present`,
+`--duration SECONDS` or `--stop-on-signal` for realtime, `--tour-file FILE`
+for deterministic mode, `--chrome-path PATH`, and required `--output PATH`.
+Global `--port` / `--server-url` work here too. Existing output paths are refused.
+
+An `.mp4` output uses ffmpeg/H.264; any other path is a PNG sequence directory.
+Frames and `recording.json` are retained at `<output>.frames` even after video
+encoding. If ffmpeg is missing, the command clearly reports the PNG fallback
+and returns that directory. Encoding failures retain frames and exit nonzero.
+
+Deterministic mode resolves target geometry once and writes
+`max(1, ceil(duration × fps))` frames per stop, including each endpoint. It sets
+the camera, waits for two animation frames, checks the applied camera, then
+captures. Duplicate a target to hold it. This makes **camera timing** deterministic,
+not animated iframe content, fonts loaded later, network assets, or concurrent
+board edits. Realtime mode samples the live board; slow captures repeat frames
+to preserve wall-clock speed, with the repeated-frame count in `recording.json`.
+Capture has no audio. Chrome and a Bun runtime with WebView support are required.
+Recording is a local CLI/file operation, not a remote HTTP/MCP file-writing API;
+HTTP/MCP manage tours and retain their existing screenshot/automation surfaces.
+
 ## pump — reactive steering for CLI agents
 
 `pmx-canvas pump` turns any CLI agent (Codex, Amp, a script) into a steerable
@@ -99,6 +184,10 @@ pmx-canvas node update <node-id> --width 840 --height 620
 pmx-canvas node update <node-id> --title "Renamed" --full
 ```
 
+Mermaid `node add` and `node update` accept `--fit contain|none`, stored as
+`data.fit`. Contain is the default and shrinks only overflowing diagrams;
+none keeps 100% with scrolling. [Sizing and readability](node-types.md#mermaid-nodes).
+
 `--from-search` / `--to-search` must each resolve to exactly one node — broad
 queries fail rather than guess. Use the full visible title.