pmx-canvas 0.6.1 → 0.6.3

package/dist/types/client/canvas/auto-fit.d.ts

@@ -17,3 +17,6 @@ export declare function shouldContentFitIframeNode(node: CanvasNodeState): boole
  * capped at the iframe ceiling.
  */
 export declare function computeContentGrowHeight(node: CanvasNodeState, contentHeight: number): number | null;
+/** Keep an automatically growing card clear without moving its neighbors or
+ * changing its column. Groups and screen-pinned cards retain authored placement. */
+export declare function contentFitPosition(node: CanvasNodeState, height: number, allNodes: CanvasNodeState[]): CanvasNodeState['position'];

package/dist/types/client/canvas/use-pan-zoom.d.ts

@@ -10,7 +10,8 @@ interface PanZoomOptions {
  * Hook that wires up pan/zoom interactions on a container element.
  * - Wheel + Ctrl/Cmd: zoom centered on pointer
  * - Wheel without modifier: pan
- * - Pointer drag on background: pan
+ * - Right or middle pointer drag: pan from anywhere
+ * - Pointer drag on background in pan mode: pan
  * - Pinch (touch): zoom
  */
 export declare function usePanZoom({ viewport, onViewportChange, onViewportCommit, disabled }: PanZoomOptions): import("preact/src").RefObject<HTMLDivElement>;

package/dist/types/client/nodes/use-iframe-content-height.d.ts

@@ -7,9 +7,9 @@ import type { CanvasNodeState } from '../types';
  * because growth is monotonic with a dead-band — cannot oscillate. This is the
  * fix for iframe nodes whose body scrollHeight the parent can't measure.
  *
- * The latest node is read through a ref so the effect stays mounted across the
- * grow (its deps are only id + token). Putting node.size in the deps would re-run
- * the effect on each grow and its cleanup would cancel the pending persist.
+ * Debounce before changing geometry, retaining the latest measurement during a
+ * human grab. Read current geometry at application time; persist only this node.
+ * Relocations are undoable, height-only adjustments do not fill the undo stack.
  */
 export declare function useIframeContentHeight(node: CanvasNodeState, iframeRef: {
     current: HTMLIFrameElement | null;

package/dist/types/client/state/human-store.d.ts

@@ -6,6 +6,7 @@ export declare const otherHumans: import("@preact/signals-core").ReadonlySignal<
 /** Nodes a human took over mid-edit → that human's name, shown as the yield pill for a moment. */
 export declare const yieldedNodes: import("@preact/signals-core").Signal<Map<string, string>>;
 export declare function applyHumanSnapshot(snapshot: Partial<HumanPresenceSnapshot> | null | undefined): void;
+export declare const grabbingNodeId: import("@preact/signals-core").Signal<string | null>;
 /** Report the pointer in world coordinates (throttled); null when it leaves the canvas. */
 export declare function reportHumanCursor(cursor: {
     x: number;

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

@@ -449,6 +449,26 @@ export declare const allComponentDefinitions: {
             readonly showLabels: true;
         };
     };
+    Card: {
+        slots: string[];
+        description: string;
+        props: z.ZodObject<{
+            title: z.ZodNullable<z.ZodString>;
+            description: z.ZodNullable<z.ZodString>;
+            maxWidth: z.ZodNullable<z.ZodEnum<{
+                sm: "sm";
+                md: "md";
+                lg: "lg";
+                full: "full";
+            }>>;
+            centered: z.ZodNullable<z.ZodBoolean>;
+            className: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        example: {
+            title: string;
+            description: string;
+        };
+    };
     Badge: {
         props: z.ZodObject<{
             text: z.ZodString;
@@ -491,26 +511,6 @@ export declare const allComponentDefinitions: {
         };
         events: string[];
     };
-    Card: {
-        props: z.ZodObject<{
-            title: z.ZodNullable<z.ZodString>;
-            description: z.ZodNullable<z.ZodString>;
-            maxWidth: z.ZodNullable<z.ZodEnum<{
-                sm: "sm";
-                md: "md";
-                lg: "lg";
-                full: "full";
-            }>>;
-            centered: z.ZodNullable<z.ZodBoolean>;
-            className: z.ZodNullable<z.ZodString>;
-        }, z.core.$strip>;
-        slots: string[];
-        description: string;
-        example: {
-            title: string;
-            description: string;
-        };
-    };
     Stack: {
         props: z.ZodObject<{
             direction: z.ZodNullable<z.ZodEnum<{

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

@@ -1,11 +1,31 @@
 export declare const schema: import("@json-render/core").Schema<{
     spec: import("@json-render/core").SchemaType<"object", {
         root: import("@json-render/core").SchemaType<"string", unknown>;
+        state: {
+            optional: true;
+            kind: "record";
+            inner?: import("@json-render/core").SchemaType<"any", unknown> | undefined;
+        };
         elements: import("@json-render/core").SchemaType<"record", import("@json-render/core").SchemaType<"object", {
             type: import("@json-render/core").SchemaType<"ref", string>;
             props: import("@json-render/core").SchemaType<"propsOf", string>;
             children: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>>;
             visible: import("@json-render/core").SchemaType<"any", unknown>;
+            repeat: {
+                optional: true;
+                kind: "any";
+                inner?: unknown;
+            };
+            watch: {
+                optional: true;
+                kind: "record";
+                inner?: import("@json-render/core").SchemaType<"any", unknown> | undefined;
+            };
+            slots: {
+                optional: true;
+                kind: "record";
+                inner?: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>> | undefined;
+            };
             on: import("@json-render/core").SchemaType<"any", unknown>;
         }>>;
     }>;
@@ -25,11 +45,31 @@ export declare const schema: import("@json-render/core").Schema<{
 export declare const elementTreeSchema: import("@json-render/core").Schema<{
     spec: import("@json-render/core").SchemaType<"object", {
         root: import("@json-render/core").SchemaType<"string", unknown>;
+        state: {
+            optional: true;
+            kind: "record";
+            inner?: import("@json-render/core").SchemaType<"any", unknown> | undefined;
+        };
         elements: import("@json-render/core").SchemaType<"record", import("@json-render/core").SchemaType<"object", {
             type: import("@json-render/core").SchemaType<"ref", string>;
             props: import("@json-render/core").SchemaType<"propsOf", string>;
             children: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>>;
             visible: import("@json-render/core").SchemaType<"any", unknown>;
+            repeat: {
+                optional: true;
+                kind: "any";
+                inner?: unknown;
+            };
+            watch: {
+                optional: true;
+                kind: "record";
+                inner?: import("@json-render/core").SchemaType<"any", unknown> | undefined;
+            };
+            slots: {
+                optional: true;
+                kind: "record";
+                inner?: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>> | undefined;
+            };
             on: import("@json-render/core").SchemaType<"any", unknown>;
         }>>;
     }>;

package/dist/types/mcp/skills.d.ts

@@ -0,0 +1,13 @@
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** SEP-2640 methods are protocol requests, not model-facing canvas tools. */
+export declare function registerSkillExtension(server: McpServer, catalog?: {
+    skills: import("../server/bundled-skills.js").SkillEntry[];
+    files: Map<string, {
+        uri: string;
+        mimeType: string;
+    } & ({
+        text: string;
+    } | {
+        blob: string;
+    })>;
+}): void;

package/dist/types/server/bundled-skills.d.ts

@@ -16,11 +16,17 @@
  *   - `canvas://skills`          → JSON index
  *   - `canvas://skills/<name>`   → full markdown content
  */
+import { z } from 'zod';
+declare const skillFrontmatterSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+}, z.core.$loose>;
 export interface BundledSkill {
     name: string;
     description: string;
     uri: string;
     filePath: string;
+    frontmatter: z.infer<typeof skillFrontmatterSchema>;
 }
 /**
  * Resolve the packaged `skills/` directory. Walks parents from this module
@@ -32,9 +38,31 @@ export interface BundledSkill {
 export declare function findBundledSkillsRoot(): string | null;
 /**
  * Enumerate every `<name>/SKILL.md` under the bundled skills root and return
- * a compact index. Hidden directories (dotfolders) and files that don't parse
- * are skipped silently rather than throwing — missing metadata should never
- * break the MCP server's resource listing.
+ * a compact index. Invalid packaged skills fail explicitly rather than being
+ * silently omitted from the Skills extension's integrity manifest.
  */
-export declare function listBundledSkills(): BundledSkill[];
+export declare function listBundledSkills(root?: string | null): BundledSkill[];
 export declare function readBundledSkill(name: string): string | null;
+export interface SkillEntry {
+    uri: string;
+    frontmatter: BundledSkill['frontmatter'];
+    resources: Array<{
+        uri: string;
+        digest: string;
+        size: number;
+    }>;
+}
+type SkillContent = {
+    uri: string;
+    mimeType: string;
+} & ({
+    text: string;
+} | {
+    blob: string;
+});
+/** Capture immutable package bytes once per MCP process, never read caller-supplied paths. */
+export declare function createBundledSkillCatalog(root?: string | null): {
+    skills: SkillEntry[];
+    files: Map<string, SkillContent>;
+};
+export {};

package/docs/http-api.md

@@ -88,7 +88,11 @@ curl -X PATCH http://localhost:4313/api/canvas/node/node-abc123 \
 ```
 
 The title follows the new filename unless the node was renamed away from the
-old one (or the patch sets `title` explicitly).
+old one (or the patch sets `title` explicitly). Relative `path` values (including
+`data.path` in batch updates) resolve against the configured canvas workspace,
+not the daemon's working directory; the stored path is absolute. A missing or
+unreadable target fails the update without changing the node or its existing watcher
+(`400` for a direct PATCH; a failed-operation result in a batch).
 
 ```bash
 # Raw bytes for a binary file node (PDF viewer, downloads)

package/docs/mcp.md

@@ -1,7 +1,7 @@
 # MCP reference
 
 PMX Canvas ships an MCP stdio server with **22 tools** + **14 core resources**,
-plus per-skill resources at `canvas://skills/<name>`. The server emits
+plus per-skill resources at `canvas://skills/<name>` and `skill://<name>/SKILL.md`. The server emits
 `notifications/resources/updated` when canvas state changes — humans pin
 nodes in the browser, agents are notified immediately.
 
@@ -202,6 +202,40 @@ Individual bundled skills are also readable at `canvas://skills/<name>`.
 | `canvas://code-graph` | Auto-detected file dependency graph (JS/TS, Python, Go, Rust) |
 | `canvas://skills` | Index of bundled agent skills + per-skill content at `canvas://skills/<name>` |
 
+### Skills extension (SEP-2640)
+
+PMX advertises `capabilities.extensions["io.modelcontextprotocol/skills"] = {}`
+alongside the base `resources` capability. This adds protocol methods, not canvas tools:
+
+| Method | Parameters | Result |
+|--------|------------|--------|
+| `skills/list` | None or `{}` | `{ resultType: "complete", skills: [...] }` |
+| `skills/get` | `{ uri: "skill://pmx-canvas/SKILL.md" }` | `{ resultType: "complete", skill: {...} }` |
+| `resources/read` | `{ uri: "skill://pmx-canvas/references/installing-pmx-canvas.md" }` | Standard resource content |
+
+Each skill entry contains its `SKILL.md` URI, full parsed YAML `frontmatter`, and a complete
+`resources` manifest of `{ uri, digest, size }` for every file. Digests are raw-byte SHA-256
+(`sha256:<hex>`); sizes are bytes. UTF-8 files are returned as text, binary files as base64 blobs.
+Resolve relative references against the skill directory. Files are loaded by the host on demand;
+discovery does not load all instructions into model context or start a canvas daemon.
+
+The packaged catalog fits in one page, so no `nextCursor` is returned and supplied cursors are
+rejected with `-32602`. Unknown skill/file URIs also return `-32602`. Optional
+`resources/directory/read` is not advertised or implemented; manifests already enumerate files.
+PMX currently negotiates the SDK's supported base protocol (up to `2025-11-25`), so the
+`2026-07-28` list-caching fields are not emitted.
+
+The server snapshots packaged files at MCP startup. Restart the MCP process after an upgrade to
+get new instructions and manifests. Invalid frontmatter, symbolic links, non-regular files, and
+skills exceeding 512 files or 16 MiB fail catalog creation. Reads only address captured package
+files, never arbitrary workspace paths. Scripts are served as data and are never executed by these methods.
+
+Hosts must implement the extension's origin tagging, integrity verification, activation, and
+approval rules. Reading a resource does not itself activate a skill or authorize local execution.
+Automatic skill loading depends on host support; ordinary resource reads and filesystem installs
+remain available. Use `pmx-canvas skills sync` for installed local mirrors. See the
+[final specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2640-skills-extension.md).
+
 ## Node interactions (capability-gated)
 
 Eligible nodes emit one normalized, validated interaction envelope

package/docs/node-types.md

@@ -328,7 +328,7 @@ Groups are spatial containers that visually contain other nodes. They render
 as dashed-border frames with a title bar and optional accent color.
 
 - Select 2+ nodes and click "Group" in the selection bar
-- Ungroup from the frame's ⋯ menu, the right-click menu, or Shift+G — the frame dissolves and
+- Ungroup from the frame's ⋯ menu, the double-click menu, or Shift+G — the frame dissolves and
   its children stay as independent nodes (one undo step); `canvas_group { action: "ungroup" }`
   does exactly the same
 - Collapsing a group hides children and shows a summary

package/docs/product-context-vision-2026-09.md

@@ -10,9 +10,11 @@
 
 **Work visually with your agents, build understanding as you go, and bring the right knowledge into whatever comes next.**
 
-pmx-canvas is for **planning, discovery, analysis, and coordination with agents**. This is its intended purpose, not merely an initial audience experiment. Boards are the working surface; personal knowledge and deliberately shared workspace knowledge provide continuity across them through one underlying knowledge model.
+**The board is the human's extended memory and the agent's working memory.** It is a place for the human to do knowledge work, not just prepare context for an agent: research, analysis, dashboards, discovery, planning, coordination, and starting or orchestrating coding and other work. These are examples of its broad purpose, not a closed list. People can use the board to think and work directly, with agents contributing on the same surface.
 
-- **Shape the work together.** Arrange, connect, pin, and annotate to express relationships and relevance that shape what agents read and help steer what they do next. Agents bring questions, proposals, and results back onto the same surface. Spatial layout provides context; not every move or camera gesture expresses intent.
+As the work develops, sources, notes, questions, charts, plans, decisions, and outputs accumulate and connect on the board. They contribute to a memory graph and maintained wiki that support both human recall and agent context across tasks. Relevant prior knowledge can then return to a board as material for further work. The board, graph, and wiki are connected views and uses of this knowledge—not three competing sources of truth or three separate filing chores.
+
+- **Do and shape the work together.** Read, write, compare evidence, monitor a dashboard, develop a plan, and direct execution on the board. Arrange, connect, pin, and annotate to support human understanding as well as shape agent context. Agents bring questions, proposals, and results back onto the same surface. Spatial layout provides context; not every move or camera gesture expresses intent.
 - **Make memory useful in the next task.** Resume without re-explaining everything. Bring relevant prior learning and authorized cross-team decisions, dependencies, and conflicts into the work—not merely into a growing collection of notes.
 - **Keep context honest as work changes.** Show sources and revisions, surface known changes and conflicts, and make uncertainty and review needs visible. Help people judge what still applies; do not treat a newer timestamp as truth or silently replace confirmed knowledge.
 
@@ -50,12 +52,12 @@ The loop is bidirectional: work produces personal understanding; selected outcom
 8. **Treat hosted as more than a login screen.** Revocation, derived-content permissions, backups/restores, uploads, quotas, sandbox isolation, and operational recovery are new responsibilities. Node-level compare-and-set can be a starting conflict policy, but requires visible conflict/retry behavior; it does not settle collaborative text editing.
 9. **Use measurements as evidence, not promises.** The earlier audit describes a particular tree and machine. Current context construction already has text previews and bounded pending steering. The claimed 10,000-token saving depends on what schemas hosts actually load; on-demand help alone does not remove advertised schemas. Measure current payloads before fixing budgets. Net-negative lines are not a user-value release gate.
 
-The north star is planning, discovery, analysis, and coordination visually with agents, with useful understanding carried into the next task. Validate which spatial signals and memory workflows best serve that purpose—not whether these activities are merely an initial audience experiment. Pins, camera attention, and the time scrubber remain ideas to validate, not proven sources of value.
+The north star is doing knowledge work on a shared visual surface that extends human memory and supplies agent working memory, with understanding carried into the next task. Validate human usefulness as well as agent behavior: can a person inspect evidence, understand relationships, resume research, monitor a dashboard, or develop and direct a plan? Pins, camera attention, and the time scrubber are mechanisms to validate against that purpose, not the purpose itself.
 
 ## The user experience
 
 1. **Describe your work.** “I lead developer experience, work with these teams, and own these outcomes.” The assistant proposes a small personal home: responsibilities, initiatives, goals, people, and open questions. No mandatory taxonomy or blank-wiki setup project.
-2. **Work on named boards.** A discovery board, quarterly plan, and workshop deck remain separate and recoverable. Each board is automatically listed as a source in the owner's context, within its existing permissions.
+2. **Work on named boards.** Research, compare evidence, use dashboards, create outputs, and start, plan, or orchestrate coding and other work. Boards remain separate and recoverable. Each board is automatically listed as a source in the owner's context, within its existing permissions; the human can return to it without needing an agent to reconstruct the work.
 3. **Remember without manual filing.** After the user delegates maintenance of specified private sources, the assistant updates existing personal working pages during the task. Source links, a quiet change history, and undo replace a compulsory wiki-edit review queue. Unknowns stay unknown; generated interpretations stay labeled.
 4. **Confirm what matters.** “Keep this as my decision” confirms an exact revision with its evidence and owner. New agent changes remain working revisions, not silently renewed confirmation. Pinning still means attention, not publication.
 5. **Resume with relevant memory.** A new board retrieves labeled personal working knowledge alongside confirmed personal context and authorized workspace knowledge. For shared organizational facts, shared canon has authority; for personal preferences, the person's context applies. Conflicting or newer evidence is shown rather than overwritten.
@@ -63,11 +65,20 @@ The north star is planning, discovery, analysis, and coordination visually with
 
 Example: a PM explores options on a discovery board, accepts a decision into personal context, then publishes an appropriately sourced workspace decision. A team lead opens a planning board and receives that decision plus related shared dependencies—not the PM's private stakeholder notes or abandoned brainstorming.
 
+### Work becomes memory, and memory supports more work
+
+1. **Work on the board:** humans and agents add and use source material, relationships, live views, plans, and results.
+2. **Connect the memory:** retain source and revision links so a person or agent can follow how an observation relates to evidence, a decision, or an outcome. Not every dashboard refresh or scratch note needs a permanent wiki page.
+3. **Maintain understanding:** under the private-maintenance delegation, synthesize useful learning into existing working wiki pages. Preserve uncertainty and rejected alternatives; confirmation and wider sharing remain separate actions.
+4. **Bring it back into work:** humans browse and revisit the graph, wiki, and boards; agents receive relevant, permission-scoped working context. New work adds evidence and can revise the understanding again.
+
+The graph holds meaningful connections and provenance; the wiki presents maintained understanding; the board keeps active work spatial and usable. A board can contribute immediately as evidence and working memory without declaring all of its contents authoritative. This loop is the proposed direction, not a claim that automatic graph/wiki maintenance already ships.
+
 ## One model, distinct scopes
 
 | Surface | Responsibility | What it must not imply |
 |---|---|---|
-| Board | Spatial working material, artifacts, asks, evidence | Everything visible is accepted knowledge |
+| Board | Human work surface and extended memory; agent working memory through spatial material, artifacts, asks, and evidence | The human only curates for agents, or everything visible is accepted knowledge |
 | Personal wiki | Durable context owned by one person across boards | Workspace membership grants access |
 | Workspace context | Deliberately shared goals, decisions, ownership, dependencies | A union of everyone's private context |
 | Agent brief | Budgeted, task-specific view over authorized material | A new source of truth or permission grant |

package/docs/product-vision-2026-09.md

@@ -7,9 +7,11 @@
 
 ## The one-line vision
 
-**The board is the agent's working memory, and the human's attention is the compiler.** Explicit steering directs agents; annotations, pins, connections, and grouping inform relevance, while spatial layout and human camera attention can contribute weaker cues. The server compiles one budgeted brief for every agent turn. Everything the agent has to say to the human is a card on the board, never a row in a side table. The board owns its own store and its own history, and reaches remote agents through its own authenticated network mode. One journal records every write by either side, so time on the board can be scrubbed like a video. In the long run the board is hosted, and a team and its agents share it as one working memory.
+**The board is the human's extended memory and the agent's working memory—a shared surface for doing work and building understanding.** The human uses it to research, analyze, monitor dashboards, explore ideas, and start, plan, and orchestrate coding or other work. People and agents bring sources, questions, relationships, plans, and results onto the board. This work contributes to a connected memory graph and maintained wiki; relevant knowledge returns to the board to support the next task. The human is a worker and thinker here, not merely a curator of agent context.
 
-**Purpose clarification, 2026-09-06:** pmx-canvas is a visual workspace for **planning, discovery, analysis, and coordination with agents**. This is its intended purpose, not merely an initial audience experiment. Its promise is to let people shape the work spatially, carry useful understanding into the next task, and see known changes and uncertainty in the context they use. The [companion vision](product-context-vision-2026-09.md#position) develops these promises; personal and shared knowledge support the working surface rather than replace it. Attention does not grant approval or sharing permission.
+Human attention helps select the agent's context; it does not define the whole product. Explicit steering directs agents; annotations, pins, connections, and grouping inform relevance, while spatial layout and human camera attention can contribute weaker cues. The server compiles one budgeted brief for every agent turn. Everything the agent has to say to the human is a card on the board, never a row in a side table. The board owns its own store and its own history, and reaches remote agents through its own authenticated network mode. One journal records every write by either side, so time on the board can be scrubbed like a video. In the long run the board is hosted, and a team and its agents share the working surface and deliberately shared knowledge.
+
+**Purpose clarification:** pmx-canvas supports **knowledge work broadly**, including research, analysis, dashboards, planning, discovery, coordination, and orchestrating coding or other work. These are examples, not a closed list or a coding-only boundary. Its promise is to help humans and agents do the work, carry useful understanding into the next task, and see known changes and uncertainty in the context they use. The [companion vision](product-context-vision-2026-09.md#position) develops this loop from board to memory graph and wiki and back. Contributing to memory does not automatically make every item a confirmed fact or shared organizational knowledge; attention does not grant approval or sharing permission.
 
 ## What the real boards show
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pmx-canvas",
-  "version": "0.6.1",
-  "description": "Spatial canvas workbench for coding agents \u2014 infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
+  "version": "0.6.3",
+  "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",
   "module": "./src/server/index.ts",
@@ -43,9 +43,9 @@
     "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
-    "test": "if [ -d tests/unit ]; then PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit; else echo 'tests/ is not shipped in the npm package \u2014 clone the repo to run the suite'; fi",
+    "test": "if [ -d tests/unit ]; then PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit; else echo 'tests/ is not shipped in the npm package — clone the repo to run the suite'; fi",
     "test:unit": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
-    "test:client": "if [ -d tests/client ]; then bun test --preload ./tests/client/setup.ts tests/client; else echo 'tests/ is not shipped in the npm package \u2014 clone the repo to run the suite'; fi",
+    "test:client": "if [ -d tests/client ]; then bun test --preload ./tests/client/setup.ts tests/client; else echo 'tests/ is not shipped in the npm package — clone the repo to run the suite'; fi",
     "test:coverage": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage && bun scripts/check-coverage.ts",
     "test:web-canvas": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun run build && PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bash scripts/run-playwright.sh",
     "test:e2e": "bun run test:web-canvas",
@@ -59,11 +59,11 @@
   },
   "dependencies": {
     "@joplin/turndown-plugin-gfm": "^1.0.64",
-    "@json-render/core": "0.19.0",
-    "@json-render/directives": "0.19.0",
-    "@json-render/mcp": "0.19.0",
-    "@json-render/react": "0.19.0",
-    "@json-render/shadcn": "0.19.0",
+    "@json-render/core": "0.21.0",
+    "@json-render/directives": "0.21.0",
+    "@json-render/mcp": "0.21.0",
+    "@json-render/react": "0.21.0",
+    "@json-render/shadcn": "0.21.0",
     "@modelcontextprotocol/ext-apps": "^1.3.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@preact/signals": "^2.0.0",
@@ -79,8 +79,8 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.2",
     "@happy-dom/global-registrator": "^20.10.6",
-    "@json-render/devtools": "0.19.0",
-    "@json-render/devtools-react": "0.19.0",
+    "@json-render/devtools": "0.21.0",
+    "@json-render/devtools-react": "0.21.0",
     "@playwright/test": "^1.58.2",
     "@tailwindcss/cli": "^4.1.18",
     "@testing-library/preact": "^3.2.4",

package/skills/json-render-mcp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: json-render-mcp
-description: MCP Apps integration for json-render. Use when building MCP servers that render interactive UIs in Claude, ChatGPT, Cursor, or VS Code, or when integrating json-render with the Model Context Protocol.
+description: Builds interactive json-render panels with PMX Canvas native tools or standalone MCP Apps. Use for stateful forms, repeated content, and AX actions in PMX Canvas, or MCP-hosted UIs in Claude, ChatGPT, Cursor, and VS Code.
 ---
 
 # @json-render/mcp
@@ -12,7 +12,123 @@ In `pmx-canvas`, prefer the native `canvas_render { action: "add-json-render" }`
 directly in canvas node state and render them through the local `pmx-canvas` viewer route without
 needing a separate sidecar server.
 
-## Quick Start
+## PMX Canvas workflow (json-render 0.21)
+
+1. Read `canvas://schema` (or use `canvas_render { action: "describe-schema" }`) for
+   the installed component catalog. PMX includes shadcn components and its own charts;
+   do not assume every component or action from an upstream example is registered.
+2. Build a complete `{ root, elements, state }` spec. Validate with
+   `canvas_render { action: "validate", type: "json-render", spec }`.
+3. Create it with `canvas_render { action: "add-json-render", title, spec }`.
+   For incremental generation, use `action: "stream-json-render"`, reuse the returned
+   `nodeId` for subsequent patches, and set `done: true` on the final call.
+4. Inspect the panel and exercise its inputs. Schema acceptance does not prove that
+   an action reached the server or that a form edit was persisted.
+
+### State, forms, and repeated content
+
+- Put initial values in spec-level `state`, alongside `root` and `elements`. PMX seeds
+  its viewer from this object; do not put `initialState` on a component.
+- Use JSON Pointer paths: `value: { "$bindState": "/form/title" }` for `Input`,
+  `Textarea`, or `Select`; `checked: { "$bindState": "/form/urgent" }` for `Checkbox`
+  or `Switch`. Supply the catalog's required `label` and `name` props. `$state` reads
+  a value only; `$bindState` also writes edits. `props.statePath` is not input binding.
+- `repeat`, `watch`, `visible`, `on`, and `slots` are element fields, not props.
+  `repeat: { "statePath": "/projects", "key": "id" }` repeats the container's children.
+  Within those children, a nested container can use
+  `repeat: { "statePath": { "$item": "tasks" }, "key": "id" }` to iterate the current
+  project's tasks. Do not use `"/tasks"` (a root path) for that nested array.
+  `$item` and `$index` refer to the innermost repeat; use
+  `checked: { "$bindItem": "done" }` to edit that task's `done` field.
+- Card body content uses `children: ["bodyId"]`. Named regions use
+  `slots: { "header": ["headingId"], "footer": ["actionsId"] }`. Every referenced ID
+  must exist in `elements`; do not put body content in `slots.default`. A header slot
+  replaces the Card's title and description props; without it, those props work as before.
+- Watchers skip mount: `watch: { "/form/title": { "action": "setState", "params":
+  { "statePath": "/dirty", "value": true } } }` runs after the value changes, not to
+  initialize `/dirty`. Seed initial and derived defaults explicitly. Avoid watchers
+  that write back to their own watched paths and create loops.
+
+### Actions and persistence boundaries
+
+- Bind buttons with `on.press`, for example an action named `ax.work.create` or
+  `ax.steer`, with its AX payload in `params`. PMX forwards only registered handlers;
+  invented action names cannot execute arbitrary tools, shell commands, or requests.
+  The server still validates the payload and the node's AX capabilities.
+- AX handlers are **fire-and-forget** postMessages. Their `onSuccess` callbacks mean
+  local dispatch completed, **not server acknowledgment**. Do not clear a draft or
+  show “Saved” on that basis. Confirm via reflected AX state under reserved `/ax`
+  (where applicable), or query the server's AX state/timeline. Do not use `/ax` for drafts.
+- Built-in `validateForm` writes `{ valid, errors }` to `/formValidation` (or
+  `params.statePath`) and returns without running `onSuccess`. Do not chain submission
+  through that callback, or assume a following action in an array is validation-gated.
+  Use an explicit validation step and state-based gating; server-side validation is
+  still required for any submitted data.
+- Form edits, `setState`, and `$bindItem` mutate **viewer-local state**, not the stored
+  spec. Iframe reloads, including spec/stream updates, reset it from the latest spec's
+  initial state. Finish streaming before collecting input; persist important changes
+  through an explicit supported server interaction. Stored canvas nodes survive
+  reloads, but unsent local drafts do not.
+
+### Example: editable task draft
+
+Pass this object to `canvas_render`. Editing either field sets a local dirty flag;
+the button requests a real AX work item without pretending the request was saved.
+
+```json
+{
+  "action": "add-json-render",
+  "title": "Task draft",
+  "spec": {
+    "root": "card",
+    "state": { "form": { "title": "Review release notes", "detail": "Check the upgrade caveats." }, "dirty": false },
+    "elements": {
+      "card": {
+        "type": "Card",
+        "props": { "title": "Task draft" },
+        "children": ["fields"],
+        "slots": { "footer": ["request"] }
+      },
+      "fields": {
+        "type": "Stack",
+        "props": { "direction": "vertical", "gap": "md" },
+        "children": ["title", "detail"],
+        "watch": {
+          "/form/title": { "action": "setState", "params": { "statePath": "/dirty", "value": true } },
+          "/form/detail": { "action": "setState", "params": { "statePath": "/dirty", "value": true } }
+        }
+      },
+      "title": {
+        "type": "Input",
+        "props": { "label": "Title", "name": "title", "value": { "$bindState": "/form/title" } }
+      },
+      "detail": {
+        "type": "Textarea",
+        "props": { "label": "Details", "name": "detail", "value": { "$bindState": "/form/detail" } }
+      },
+      "request": {
+        "type": "Button",
+        "props": { "label": "Request task", "variant": "primary" },
+        "on": {
+          "press": {
+            "action": "ax.work.create",
+            "params": { "title": { "$state": "/form/title" }, "detail": { "$state": "/form/detail" } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The draft remains visible after dispatch. Verify that the work item appears in AX
+state before reporting success. Repeated clicks can create duplicate work items.
+
+## Standalone MCP App quick start
+
+Use this path only when building a separate MCP Apps server rather than a native
+PMX panel. PMX's `canvas_render` path needs none of the server, bundler, or client
+configuration below.
 
 ### Server (Node.js)