pmx-canvas 0.1.13 → 0.1.15

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;
@@ -40,6 +41,12 @@ interface CanvasAddNodeInput {
     title?: string;
     content?: string;
     data?: Record<string, unknown>;
+    toolName?: string;
+    category?: string;
+    status?: string;
+    duration?: string;
+    resultSummary?: string;
+    error?: string;
     x?: number;
     y?: number;
     width?: number;
@@ -106,6 +113,8 @@ export declare function validateCanvasNodePatch(patch: {
         height: number;
     };
 }): string | null;
+export declare function mergeTraceNodeDataFields(base: Record<string, unknown>, input: Record<string, unknown>): Record<string, unknown>;
+export declare function hasTraceNodeDataFields(input: Record<string, unknown>): boolean;
 export declare function scheduleCodeGraphRecompute(onComplete?: () => void): void;
 export declare function addCanvasNode(input: CanvasAddNodeInput): {
     id: string;
@@ -142,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;
@@ -150,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/diagram-presets.d.ts

@@ -9,11 +9,13 @@ export declare const DEFAULT_EXCALIDRAW_ELEMENTS: ReadonlyArray<Record<string, u
 export declare const EXCALIDRAW_MCP_TRANSPORT: ExternalMcpTransportConfig;
 export interface DiagramPresetOpenInput {
     elements: unknown;
+    nodeId?: string;
     title?: string;
     x?: number;
     y?: number;
     width?: number;
     height?: number;
+    timeoutMs?: number;
 }
 export interface ExcalidrawOpenMcpAppInput {
     transport: ExternalMcpTransportConfig;
@@ -22,11 +24,13 @@ export interface ExcalidrawOpenMcpAppInput {
     toolArguments: {
         elements: string;
     };
+    nodeId?: string;
     title?: string;
     x?: number;
     y?: number;
     width?: number;
     height?: number;
+    timeoutMs?: number;
 }
 export declare function inferExcalidrawCameraUpdate(elements: Array<Record<string, unknown>>): Record<string, unknown> | null;
 export declare function normalizeExcalidrawElements(elements: unknown): string;

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';
@@ -23,6 +23,12 @@ export declare class PmxCanvas extends EventEmitter {
         type: CanvasNodeState['type'];
         title?: string;
         content?: string;
+        toolName?: string;
+        category?: string;
+        status?: string;
+        duration?: string;
+        resultSummary?: string;
+        error?: string;
         x?: number;
         y?: number;
         width?: number;
@@ -137,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;
@@ -145,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;
@@ -198,12 +205,14 @@ export declare class PmxCanvas extends EventEmitter {
         transport: ExternalMcpTransportConfig;
         toolName: string;
         toolArguments?: Record<string, unknown>;
+        nodeId?: string;
         serverName?: string;
         title?: string;
         x?: number;
         y?: number;
         width?: number;
         height?: number;
+        timeoutMs?: number;
     }): Promise<{
         ok: true;
         id?: string;
@@ -225,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;
@@ -245,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/mcp-app-runtime.d.ts

@@ -18,6 +18,7 @@ export interface OpenMcpAppInput {
     toolName: string;
     toolArguments?: Record<string, unknown>;
     serverName?: string;
+    timeoutMs?: number;
 }
 export interface OpenMcpAppResult {
     sessionId: string;

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.13",
+  "version": "0.1.15",
   "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