pmx-canvas 0.1.14 → 0.1.16

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

@@ -287,9 +287,9 @@ export declare const allComponentDefinitions: {
         props: z.ZodObject<{
             text: z.ZodString;
             variant: z.ZodNullable<z.ZodEnum<{
+                default: "default";
                 error: "error";
                 success: "success";
-                default: "default";
                 secondary: "secondary";
                 destructive: "destructive";
                 outline: "outline";

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

@@ -7,6 +7,7 @@ type OpenMcpAppResult = Awaited<ReturnType<PmxCanvas['openMcpApp']>>;
 type AddDiagramInput = Parameters<PmxCanvas['addDiagram']>[0];
 type AddJsonRenderNodeInput = Parameters<PmxCanvas['addJsonRenderNode']>[0];
 type AddJsonRenderNodeResult = ReturnType<PmxCanvas['addJsonRenderNode']>;
+type AddHtmlNodeInput = Parameters<PmxCanvas['addHtmlNode']>[0];
 type AddGraphNodeInput = Parameters<PmxCanvas['addGraphNode']>[0];
 type AddGraphNodeResult = ReturnType<PmxCanvas['addGraphNode']>;
 type UpdateNodePatch = Parameters<PmxCanvas['updateNode']>[1];
@@ -23,8 +24,11 @@ type HistoryResult = ReturnType<PmxCanvas['getHistory']>;
 type SetContextPinsResult = ReturnType<PmxCanvas['setContextPins']>;
 type RunBatchInput = Parameters<PmxCanvas['runBatch']>[0];
 type RunBatchResult = Awaited<ReturnType<PmxCanvas['runBatch']>>;
+type SnapshotListOptions = Parameters<PmxCanvas['listSnapshots']>[0];
 type SnapshotList = ReturnType<PmxCanvas['listSnapshots']>;
 type DeleteSnapshotResult = ReturnType<PmxCanvas['deleteSnapshot']>;
+type GcSnapshotsOptions = Parameters<PmxCanvas['gcSnapshots']>[0];
+type GcSnapshotsResult = ReturnType<PmxCanvas['gcSnapshots']>;
 type DiffSnapshotResult = ReturnType<PmxCanvas['diffSnapshot']>;
 type CodeGraphResult = ReturnType<PmxCanvas['getCodeGraph']>;
 type ValidationResult = ReturnType<PmxCanvas['validate']>;
@@ -45,6 +49,7 @@ export interface CanvasAccess {
     openMcpApp(input: OpenMcpAppInput): Promise<OpenMcpAppResult>;
     addDiagram(input: AddDiagramInput): Promise<OpenMcpAppResult>;
     addJsonRenderNode(input: AddJsonRenderNodeInput): Promise<AddJsonRenderNodeResult>;
+    addHtmlNode(input: AddHtmlNodeInput): Promise<string>;
     addGraphNode(input: AddGraphNodeInput): Promise<AddGraphNodeResult>;
     buildWebArtifact(input: WebArtifactInput): Promise<WebArtifactResult>;
     updateNode(id: string, patch: UpdateNodePatch): Promise<void>;
@@ -67,12 +72,13 @@ export interface CanvasAccess {
     setContextPins(nodeIds: string[], mode?: 'set' | 'add' | 'remove'): Promise<SetContextPinsResult>;
     getPinnedNodeIds(): Promise<string[]>;
     runBatch(operations: RunBatchInput): Promise<RunBatchResult>;
-    listSnapshots(): Promise<SnapshotList>;
+    listSnapshots(options?: SnapshotListOptions): Promise<SnapshotList>;
     saveSnapshot(name: string): Promise<CanvasSnapshot | null>;
     restoreSnapshot(id: string): Promise<{
         ok: boolean;
     }>;
     deleteSnapshot(id: string): Promise<DeleteSnapshotResult>;
+    gcSnapshots(options?: GcSnapshotsOptions): Promise<GcSnapshotsResult>;
     diffSnapshot(idOrName: string): Promise<DiffSnapshotResult>;
     getCodeGraph(): Promise<CodeGraphResult>;
     validate(): Promise<ValidationResult>;

package/dist/types/server/agent-context.d.ts

@@ -2,6 +2,7 @@ import type { CanvasNodeState } from './canvas-state.js';
 export interface AgentContextNode {
     id: string;
     type: CanvasNodeState['type'];
+    kind: string;
     title: string | null;
     content: string | null;
     metadata?: Record<string, unknown>;

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

@@ -1,7 +1,8 @@
-import { type CanvasEdge, type CanvasNodeState, type CanvasNodeUpdate, type CanvasSnapshot } from './canvas-state.js';
+import { canvasState, type CanvasEdge, type CanvasNodeState, type CanvasNodeUpdate, type CanvasSnapshot } from './canvas-state.js';
 import { type GraphNodeInput, type JsonRenderNodeInput, type JsonRenderSpec } from '../json-render/server.js';
 export type CanvasArrangeMode = 'grid' | 'column' | 'flow';
 export type CanvasPinMode = 'set' | 'add' | 'remove';
+export declare function setCanvasLayoutUpdateEmitter(emitter: (() => void) | null): void;
 export interface CanvasFitViewOptions {
     width?: number;
     height?: number;
@@ -150,7 +151,7 @@ export declare function setCanvasContextPins(nodeIds: string[], mode?: CanvasPin
     count: number;
     nodeIds: string[];
 };
-export declare function listCanvasSnapshots(): CanvasSnapshot[];
+export declare function listCanvasSnapshots(options?: Parameters<typeof canvasState.listSnapshots>[0]): CanvasSnapshot[];
 export declare function saveCanvasSnapshot(name: string): CanvasSnapshot | null;
 export declare function restoreCanvasSnapshot(idOrName: string): Promise<{
     ok: boolean;
@@ -158,6 +159,7 @@ export declare function restoreCanvasSnapshot(idOrName: string): Promise<{
 export declare function deleteCanvasSnapshot(id: string): {
     ok: boolean;
 };
+export declare function gcCanvasSnapshots(options?: Parameters<typeof canvasState.gcSnapshots>[0]): ReturnType<typeof canvasState.gcSnapshots>;
 export declare function addCanvasEdge(input: {
     from?: string;
     to?: string;

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

@@ -1,4 +1,4 @@
-export type CanvasNodeType = 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'image' | 'group';
+export type CanvasNodeType = 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'image' | 'html' | 'group';
 export type CanvasNodeProvenanceSourceKind = 'workspace-file' | 'webpage-url' | 'mcp-tool' | 'artifact-file' | 'image-url';
 export type CanvasNodeRefreshStrategy = 'file-watch' | 'file-read-write' | 'image-reload' | 'webpage-refresh' | 'mcp-app-rehydrate' | 'artifact-reopen';
 export interface CanvasNodeProvenance {

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

@@ -11,10 +11,13 @@ export interface SerializedCanvasNode extends CanvasNodeState {
 export interface SerializedCanvasLayout extends Omit<CanvasLayout, 'nodes'> {
     nodes: SerializedCanvasNode[];
 }
+export declare function getCanvasNodeKind(node: CanvasNodeState, data: Record<string, unknown>): string;
 export declare function getCanvasNodeTitle(node: CanvasNodeState): string | null;
 export declare function getCanvasNodeContent(node: CanvasNodeState): string | null;
 export declare function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode;
+export declare function serializeCanvasNodeWithBlobSummaries(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasLayout(layout: CanvasLayout): SerializedCanvasLayout;
+export declare function serializeCanvasLayoutWithBlobSummaries(layout: CanvasLayout): SerializedCanvasLayout;
 export interface CanvasSummary {
     totalNodes: number;
     totalEdges: number;

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

@@ -9,6 +9,21 @@
  * workspace root on every mutation (debounced). Auto-loads on `loadFromDisk()`.
  */
 export declare const PMX_CANVAS_DIR = ".pmx-canvas";
+export interface PersistedBlobRef {
+    __pmxCanvasBlob: 'v1';
+    path: string;
+    sha256: string;
+    encoding: 'json+gzip';
+    bytes: number;
+    jsonBytes: number;
+}
+interface PersistedCanvasState {
+    version: number;
+    viewport: ViewportState;
+    nodes: CanvasNodeState[];
+    edges: CanvasEdge[];
+    contextPins: string[];
+}
 interface LoadFromDiskOptions {
     clearExisting?: boolean;
 }
@@ -20,9 +35,24 @@ export interface CanvasSnapshot {
     nodeCount: number;
     edgeCount: number;
 }
+export interface CanvasSnapshotListOptions {
+    limit?: number;
+    query?: string;
+    all?: boolean;
+}
+export interface CanvasSnapshotGcOptions {
+    keep?: number;
+    dryRun?: boolean;
+}
+export interface CanvasSnapshotGcResult {
+    ok: boolean;
+    kept: number;
+    deleted: CanvasSnapshot[];
+    dryRun: boolean;
+}
 export interface CanvasNodeState {
     id: string;
-    type: 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'image' | 'group';
+    type: 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'image' | 'html' | 'group';
     position: {
         x: number;
         y: number;
@@ -92,7 +122,7 @@ declare class CanvasStateManager {
     onChange(cb: (type: CanvasChangeType) => void): void;
     private notifyChange;
     private _mutationRecorder;
-    private _suppressRecording;
+    private _suppressRecordingDepth;
     /** Register a mutation recorder. Used by mutation-history to capture undo/redo closures. */
     onMutation(cb: (info: MutationRecordInfo) => void): void;
     /** Run a function with mutation recording suppressed (for undo/redo replay and computed edges). */
@@ -111,6 +141,16 @@ declare class CanvasStateManager {
     private _saveTimer;
     /** Set the workspace root to enable auto-persistence. */
     setWorkspaceRoot(workspaceRoot: string): void;
+    private get blobsDir();
+    private relativeBlobPath;
+    private resolveBlobPath;
+    private writeBlobValue;
+    private readBlobValue;
+    private externalizeNodeDataBlobs;
+    private resolveNodeDataBlobs;
+    isBlobReference(value: unknown): value is PersistedBlobRef;
+    resolveBlobReference(value: unknown): unknown;
+    private externalizePersistedStateBlobs;
     /**
      * One-time migration: rename files from the pre-consolidation layout
      * (`.pmx-canvas.json` + `.pmx-canvas-snapshots/`) into `.pmx-canvas/`.
@@ -129,10 +169,15 @@ declare class CanvasStateManager {
     private get snapshotsDir();
     private applyPersistedState;
     private readResolvedSnapshot;
+    getSnapshotDataForPersistence(idOrName: string): {
+        snapshot: CanvasSnapshot;
+        state: PersistedCanvasState;
+    } | null;
     /** Save current canvas state as a named snapshot. */
     saveSnapshot(name: string): CanvasSnapshot | null;
-    /** List all saved snapshots. */
-    listSnapshots(): CanvasSnapshot[];
+    /** List saved snapshots, newest first. */
+    listSnapshots(options?: CanvasSnapshotListOptions): CanvasSnapshot[];
+    gcSnapshots(options?: CanvasSnapshotGcOptions): CanvasSnapshotGcResult;
     /** Restore canvas state from a snapshot. */
     restoreSnapshot(idOrName: string): boolean;
     /** Read a snapshot's data without restoring it (for diff). Resolves by ID or name. */
@@ -150,12 +195,14 @@ declare class CanvasStateManager {
     updateNode(id: string, patch: Partial<CanvasNodeState>): void;
     removeNode(id: string): void;
     getNode(id: string): CanvasNodeState | undefined;
+    getNodeForPersistence(id: string): CanvasNodeState | undefined;
     addEdge(edge: CanvasEdge): boolean;
     removeEdge(id: string): boolean;
     getEdges(): CanvasEdge[];
     getEdgesForNode(nodeId: string): CanvasEdge[];
     private removeEdgesForNode;
     getLayout(): CanvasLayout;
+    getLayoutForPersistence(): CanvasLayout;
     applyUpdates(updates: CanvasNodeUpdate[]): {
         applied: number;
         skipped: number;

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

@@ -0,0 +1,5 @@
+export declare function seedDemoCanvas(): {
+    nodes: number;
+    edges: number;
+    groups: number;
+};

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

@@ -2,7 +2,7 @@ import { EventEmitter } from 'node:events';
 import type { CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
 import { searchNodes } from './spatial-analysis.js';
 import { diffLayouts } from './mutation-history.js';
-import { fitCanvasView } from './canvas-operations.js';
+import { fitCanvasView, gcCanvasSnapshots, listCanvasSnapshots } from './canvas-operations.js';
 import { type WebArtifactBuildInput, type WebArtifactCanvasBuildResult } from './web-artifacts.js';
 import { type ExternalMcpTransportConfig } from './mcp-app-runtime.js';
 import { type DiagramPresetOpenInput } from './diagram-presets.js';
@@ -143,7 +143,7 @@ export declare class PmxCanvas extends EventEmitter {
         count: number;
         nodeIds: string[];
     };
-    listSnapshots(): import("./canvas-state.js").CanvasSnapshot[];
+    listSnapshots(options?: Parameters<typeof listCanvasSnapshots>[0]): import("./canvas-state.js").CanvasSnapshot[];
     saveSnapshot(name: string): import("./canvas-state.js").CanvasSnapshot | null;
     restoreSnapshot(id: string): Promise<{
         ok: boolean;
@@ -151,6 +151,7 @@ export declare class PmxCanvas extends EventEmitter {
     deleteSnapshot(id: string): {
         ok: boolean;
     };
+    gcSnapshots(options?: Parameters<typeof gcCanvasSnapshots>[0]): ReturnType<typeof gcCanvasSnapshots>;
     diffSnapshot(idOrName: string): {
         ok: boolean;
         text?: string;
@@ -233,6 +234,15 @@ export declare class PmxCanvas extends EventEmitter {
         url: string;
         spec: JsonRenderSpec;
     };
+    addHtmlNode(input: {
+        html: string;
+        title?: string;
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+        strictSize?: boolean;
+    }): string;
     addGraphNode(input: GraphNodeInput): {
         id: string;
         url: string;
@@ -253,7 +263,7 @@ export type { CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from '.
 export type { CanvasAutomationWebViewOptions, CanvasAutomationWebViewStatus, PrimaryWorkbenchCanvasPromptRequest, PrimaryWorkbenchIntent, } from './server.js';
 export { emitPrimaryWorkbenchEvent, consumePrimaryWorkbenchIntents, setPrimaryWorkbenchAutoOpenEnabled, setPrimaryWorkbenchCanvasPromptHandler, startCanvasServer, stopCanvasServer, getCanvasServerPort, openUrlInExternalBrowser, getCanvasAutomationWebViewStatus, startCanvasAutomationWebView, stopCanvasAutomationWebView, evaluateCanvasAutomationWebView, resizeCanvasAutomationWebView, screenshotCanvasAutomationWebView, } from './server.js';
 export { canvasState } from './canvas-state.js';
-export type { CanvasSnapshot } from './canvas-state.js';
+export type { CanvasSnapshot, CanvasSnapshotGcResult, CanvasSnapshotListOptions } from './canvas-state.js';
 export { findOpenCanvasPosition } from './placement.js';
 export { searchNodes, buildSpatialContext, detectClusters, findNeighborhoods } from './spatial-analysis.js';
 export type { SpatialCluster, SpatialContext, SpatialNeighbor, NodeSpatialInfo } from './spatial-analysis.js';

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

@@ -17,6 +17,7 @@ export interface WebArtifactBuildOutput {
     fileSize: number;
     projectPath: string;
     metadata: Record<string, unknown>;
+    sourceContext: WebArtifactSourceContext;
     logs?: {
         stdout?: WebArtifactLogSummary;
         stderr?: WebArtifactLogSummary;
@@ -30,6 +31,13 @@ export interface WebArtifactLogSummary {
     truncated: boolean;
     suppressedNoiseCount: number;
 }
+export interface WebArtifactSourceContext {
+    content: string;
+    sourceFiles: string[];
+    sourceFileCount: number;
+    sourcePreview: string;
+    deps?: string[];
+}
 export interface WebArtifactCanvasOpenResult {
     nodeId: string;
     url: string;
@@ -38,7 +46,10 @@ export interface WebArtifactCanvasBuildResult extends WebArtifactBuildOutput {
     openedInCanvas: boolean;
     nodeId?: string;
     url?: string;
+    startedAt: string;
     completedAt: string;
+    durationMs: number;
+    timeoutMs: number;
 }
 export declare function resolveWorkspacePath(pathLike: string, cwd?: string): string;
 export declare function resolveWebArtifactScriptPath(kind: 'init' | 'bundle'): string;
@@ -46,6 +57,13 @@ export declare function executeWebArtifactBuild(input: WebArtifactBuildInput): P
 export declare function openWebArtifactInCanvas(input: {
     title: string;
     filePath: string;
+    fileSize?: number;
+    projectPath?: string;
+    content?: string;
+    sourceFiles?: string[];
+    sourceFileCount?: number;
+    sourcePreview?: string;
+    deps?: string[];
 }): WebArtifactCanvasOpenResult;
 export declare function buildWebArtifactOnCanvas(input: WebArtifactBuildInput & {
     openInCanvas?: boolean;

package/dist/types/shared/canvas-node-kind.d.ts

@@ -0,0 +1,5 @@
+export interface CanvasNodeKindInput {
+    type: string;
+    data: Record<string, unknown>;
+}
+export declare function getCanvasNodeKind(node: CanvasNodeKindInput): string;

package/package.json

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

@@ -225,6 +225,7 @@ The CLI targets `http://localhost:4313` by default. Override with `PMX_CANVAS_UR
 | `mcp-app` | Hosted app/embed frame | Tool-backed MCP apps or external app content; not generic CLI-created notes |
 | `json-render` | Native structured UI panel | Dashboards, forms, tables, interactive layouts from json-render specs |
 | `graph` | Native chart panel | Line, bar, pie, area, scatter, radar, stacked-bar, and composed charts rendered inside the canvas |
+| `html` | Sandboxed HTML+JS document | Self-contained HTML with optional inline `<script>` and CDN imports rendered in a sandbox-restricted iframe; canvas theme tokens are auto-injected |
 | `group` | Spatial container/frame | Visually group related nodes together |
 | `prompt` | Prompt thread root | Canvas-native prompt entry points for agent conversations. **Internal type — surfaces in `canvas://layout` for thread rendering but is not created via the public `canvas_add_node` API. Don't try to add one directly.** |
 | `response` | Prompt reply / streamed answer | Agent responses linked to prompt threads. **Same internal-only restriction as `prompt`.** |
@@ -269,6 +270,7 @@ MCP node-type routing:
 | Basic nodes (`markdown`, `status`, `context`, `ledger`, `trace`, `file`, `image`, `webpage`) | `canvas_add_node` |
 | `json-render` | `canvas_add_json_render_node` |
 | `graph` | `canvas_add_graph_node` |
+| `html` | `canvas_add_html_node` |
 | `web-artifact` | `canvas_build_web_artifact` |
 | `external-app` / tool-backed `mcp-app` | `canvas_open_mcp_app` |
 | `group` | `canvas_create_group` |
@@ -431,6 +433,27 @@ ID extraction for mixed tool responses:
 **`canvas_ungroup`** — Release children from a group
 - `groupId` (required): group to dissolve
 
+### Group Layout Guidance
+
+Use groups as spacious semantic regions, not as tight containers.
+
+- Size the child nodes first, especially `graph`, `json-render`, `mcp-app`, image, and webpage
+  nodes whose rendered content may need more height than their visible title suggests.
+- Give every group generous interior padding. Reserve extra top padding for the group header, then
+  keep children clear of the frame edges so headers, glow, resize handles, and node chrome do not
+  visually collide.
+- If creating a group manually, compute its frame from the final child bounds plus padding. If the
+  group exists first, expand it before adding large children rather than shrinking children to fit.
+- Use groups to label major regions of a board. Avoid wrapping every small relationship; too many
+  tight groups make the canvas harder to read than no groups.
+- Keep edges local to a group where possible. Long cross-board edges can look like they come from
+  nowhere; use a nearby bridge/context node or split the relationship into shorter labeled edges.
+- After grouping, verify the result in `canvas_get_layout` or the browser: child nodes should be
+  fully inside the group with padding, visible nodes should not overlap, and group headers should
+  not cover content.
+- If a group makes important content less visible, enlarge the group, split it into clearer
+  regions, or remove the group. Visibility is more important than preserving a frame.
+
 ### Grouped Comparison Boards
 
 Use groups as named comparison areas, not just visual boxes.
@@ -613,6 +636,26 @@ server's `ui://` resource as an iframe node on the canvas
 - Prefer the dedicated `web-artifacts-builder` skill when you need the full React + shadcn workflow
 - Use the `playwright-cli` skill when you need to validate the built artifact in a live browser
 
+### HTML Nodes (Sandboxed iframe)
+
+**`canvas_add_html_node`** — Add a 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`
+- 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
+- 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)
+
+### Choosing the Right Visual Tier
+
+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` |
+| 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 |
+
 ### Native Structured UI
 
 Use native `json-render` and `graph` nodes when the output should stay fully inside PMX Canvas:

package/skills/pmx-canvas-testing/SKILL.md

@@ -72,6 +72,23 @@ Prefer extending the existing suites before inventing a one-off script.
 - If a change spans server and client, add at least one server-side assertion and one browser or
   API-level proof
 
+## Layout And Embedded Content Checks
+
+- For seeded or generated boards, add API-level geometry assertions: expected node/edge counts,
+  group counts, valid edge endpoints, no visible node overlaps, and group children contained with
+  header/padding space.
+- For grouped layouts, test non-group node overlap separately from group containment. Group frames
+  are allowed to contain children; children should not overlap each other or collide with headers.
+- For edge-heavy layouts, assert endpoints exist and long cross-board edges are intentional. If a
+  user says an edge “comes from nowhere,” add a regression check for missing endpoints or excessive
+  edge distance in that board.
+- For `graph`, `json-render`, `mcp-app`, webpage, and image nodes, API geometry is not enough.
+  Verify the rendered browser frame when changing sizing: iframe/body `scrollHeight` and
+  `scrollWidth` should fit the available frame unless scrolling is the intended behavior.
+- When checking embedded frame fit manually, start from a clean seeded state, rebuild stale bundles,
+  and inspect the actual iframe document in a browser. Server dimensions can look correct while the
+  embedded content is still clipped.
+
 ## Failure Handling
 
 - Never wave away a failure without checking whether your change caused it

package/src/cli/agent.ts

@@ -154,7 +154,7 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
   const flags: Record<string, string | true> = {};
   // Boolean-only flags (never take a value argument)
   const BOOL_FLAGS = new Set([
-    'help', 'h', 'ids', 'stdin', 'yes', 'list', 'clear', 'set', 'animated', 'dry-run',
+    'help', 'h', 'ids', 'stdin', 'yes', 'list', 'clear', 'set', 'animated', 'dry-run', 'all',
     'no-open-in-canvas', 'lock-arrange', 'unlock-arrange', 'json', 'compact', 'summary',
     'verbose', 'include-logs', 'no-pan', 'schema', 'example', 'examples', 'strict-size', 'scroll-overflow',
   ]);
@@ -1081,7 +1081,7 @@ cmd('node add', 'Add a node to the canvas', [
   applyStrictSizeFlags(body, flags);
   if (type === 'trace') {
     for (const field of TRACE_NODE_FIELDS) {
-      const value = getStringFlag(flags, field);
+      const value = getStringFlag(flags, field, field.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`));
       if (value !== undefined) body[field] = value;
     }
   }
@@ -1315,6 +1315,11 @@ cmd('node update', 'Update a node by ID', [
 
   applyStrictSizeFlags(body, flags);
 
+  for (const field of TRACE_NODE_FIELDS) {
+    const value = getStringFlag(flags, field, field.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`));
+    if (value !== undefined) body[field] = value;
+  }
+
   if (x !== undefined || y !== undefined || width !== undefined || frameHeight !== undefined || arrangeLocked !== undefined) {
     const existing = await api('GET', `/api/canvas/node/${encodeURIComponent(id)}`) as {
       position: { x: number; y: number };
@@ -1346,7 +1351,7 @@ cmd('node update', 'Update a node by ID', [
   if (Object.keys(body).length === 0) {
     die(
       'No updates specified',
-      'Use --title, --content, --x, --y, --width, --height, --strict-size, --pinned, --lock-arrange, --unlock-arrange, or --stdin',
+      'Use --title, --content, --x, --y, --width, --height, --strict-size, --pinned, trace fields, --lock-arrange, --unlock-arrange, or --stdin',
     );
   }
 
@@ -1684,13 +1689,41 @@ cmd('snapshot save', 'Save a named snapshot of the current canvas', [
 });
 
 // ── snapshot list ────────────────────────────────────────────
-cmd('snapshot list', 'List all saved snapshots', [
+cmd('snapshot list', 'List saved snapshots', [
   'pmx-canvas snapshot list',
+  'pmx-canvas snapshot list --limit 50 --query baseline',
+  'pmx-canvas snapshot list --all',
 ], async (args) => {
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('snapshot list');
 
-  const result = await api('GET', '/api/canvas/snapshots');
+  const params = new URLSearchParams();
+  const limit = optionalNumberFlag(flags, 'limit', 'Use a positive integer, e.g. --limit 50');
+  const query = getStringFlag(flags, 'query', 'q');
+  if (limit !== undefined) params.set('limit', String(limit));
+  if (query) params.set('q', query);
+  if (flags.all) params.set('all', 'true');
+  const result = await api('GET', `/api/canvas/snapshots${params.size > 0 ? `?${params.toString()}` : ''}`);
+  output(result);
+});
+
+// ── snapshot gc ──────────────────────────────────────────────
+cmd('snapshot gc', 'Delete old snapshots, keeping the newest N', [
+  'pmx-canvas snapshot gc --keep 20 --dry-run',
+  'pmx-canvas snapshot gc --keep 50 --yes',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('snapshot gc');
+
+  const keep = optionalNumberFlag(flags, 'keep', 'Use a positive integer, e.g. --keep 20');
+  const dryRun = flags['dry-run'] === true;
+  if (!dryRun && !flags.yes) {
+    die('Destructive operation requires --yes flag', 'Preview with: pmx-canvas snapshot gc --keep 20 --dry-run');
+  }
+  const result = await api('POST', '/api/canvas/snapshots/gc', {
+    ...(keep !== undefined ? { keep } : {}),
+    dryRun,
+  });
   output(result);
 });
 
@@ -2285,12 +2318,25 @@ function showCommandHelp(name: string): void {
     console.log('\nOutput control:');
     console.log('  --summary                 Return only validation summary metadata');
   }
+  if (name === 'snapshot list') {
+    console.log('\nOptions:');
+    console.log('  --limit <number>          Maximum snapshots to return (default 20)');
+    console.log('  --query <text>            Case-insensitive ID/name filter');
+    console.log('  --all                     Return all snapshots');
+  }
+  if (name === 'snapshot gc') {
+    console.log('\nOptions:');
+    console.log('  --keep <number>           Number of newest snapshots to keep (default 20)');
+    console.log('  --dry-run                 Preview deletions without removing files');
+    console.log('  --yes                     Confirm deletion');
+  }
   if (name === 'web-artifact build') {
     console.log('\nDependencies:');
     console.log('  --deps <list>              Add npm dependencies before bundling, e.g. --deps recharts,zod');
     console.log('\nOutput control:');
     console.log('  --include-logs            Include raw build stdout/stderr in the response');
     console.log('  --verbose                 Alias for --include-logs');
+    console.log('  --timeout-ms <number>     Optional init/install/build timeout in milliseconds');
   }
   if (name === 'focus') {
     console.log('\nViewport:');
@@ -2389,6 +2435,7 @@ History:
 Snapshots:
   pmx-canvas snapshot save --name X   Save a named snapshot
   pmx-canvas snapshot list            List snapshots
+  pmx-canvas snapshot gc --keep 20    Delete old snapshots
   pmx-canvas snapshot restore <id>    Restore from snapshot
   pmx-canvas snapshot diff <id>       Compare current canvas to snapshot
   pmx-canvas snapshot delete <id>     Delete a snapshot

package/src/cli/index.ts

@@ -5,6 +5,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runAgentCli } from './agent.js';
 import { createCanvas } from '../server/index.js';
+import { seedDemoCanvas } from '../server/demo.js';
 
 const args = process.argv.slice(2);
 
@@ -594,29 +595,7 @@ Examples:
     process.exit(1);
   }
 
-  if (demo && canvas.getLayout().nodes.length === 0) {
-    const n1 = canvas.addNode({
-      type: 'markdown',
-      title: 'Welcome to PMX Canvas',
-      content: '# PMX Canvas Workbench\n\nA spatial canvas for coding agents.\n\n## Features\n- Infinite 2D canvas with pan/zoom\n- Multiple node types\n- Edges between nodes\n- Real-time SSE updates\n- HTTP API for agent control',
-    });
-
-    const n2 = canvas.addNode({
-      type: 'markdown',
-      title: 'Getting Started',
-      content: `# Quick Start\n\n\`\`\`bash\n# Add a node via CLI\npmx-canvas node add --type markdown --title "Hello" --content "# World"\n\n# List nodes\npmx-canvas node list\n\n# Get canvas state\npmx-canvas layout\n\`\`\``,
-    });
-
-    const n3 = canvas.addNode({
-      type: 'status',
-      title: 'Agent Status',
-      content: 'Ready',
-    });
-
-    canvas.addEdge({ from: n1, to: n2, type: 'flow', label: 'next' });
-    canvas.addEdge({ from: n2, to: n3, type: 'flow' });
-    canvas.arrange('grid');
-  }
+  if (demo && canvas.getLayout().nodes.length === 0) seedDemoCanvas();
 
   console.log(`\n  PMX Canvas running at http://localhost:${canvas.port}`);
   console.log(`  Health: http://localhost:${canvas.port}/health\n`);

package/src/client/canvas/AttentionHistory.tsx

@@ -5,6 +5,7 @@ import {
   closeAttentionHistory,
   openAttentionHistory,
 } from '../state/attention-store';
+import { collapseDockedContextNodes, hasOpenDockedContextPanel } from '../state/canvas-store';
 
 function formatTimestamp(timestamp: number): string {
   return new Date(timestamp).toLocaleTimeString([], {
@@ -13,19 +14,31 @@ function formatTimestamp(timestamp: number): string {
   });
 }
 
+function handleOpenUpdates(): void {
+  // Mutual exclusion with the Context panel — only one side panel open at a
+  // time (they share the same right-edge anchor).
+  collapseDockedContextNodes();
+  openAttentionHistory();
+}
+
 export function AttentionHistory() {
   const entries = attentionHistory.value;
   if (entries.length === 0) return null;
 
   const isOpen = attentionHistoryOpen.value;
   const unread = attentionHistoryUnread.value;
+  // Hide the collapsed Updates pill while the Context side panel is open —
+  // the panel sits at the same right-edge and would visually cover the pill.
+  // Mutual exclusion guarantees both can't be expanded simultaneously, so the
+  // pill only needs to hide while context is expanded.
+  if (!isOpen && hasOpenDockedContextPanel.value) return null;
 
   if (!isOpen) {
     return (
       <button
         type="button"
         class="attention-history-tab"
-        onClick={openAttentionHistory}
+        onClick={handleOpenUpdates}
         aria-label={unread > 0 ? `Recent updates — ${unread} new` : 'Recent updates'}
         title={unread > 0 ? `${unread} new updates since last viewed` : 'Recent updates'}
       >

package/src/client/canvas/CanvasNode.tsx

@@ -164,7 +164,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
           window.clearTimeout(autoFitPersistTimer.current);
         }
         autoFitPersistTimer.current = window.setTimeout(() => {
-          persistLayout();
+          persistLayout({ recordHistory: false });
           autoFitPersistTimer.current = null;
         }, 0);
       }