pmx-canvas 0.1.26 → 0.1.28

package/.github/extensions/pmx-canvas/extension.mjs

@@ -388,6 +388,16 @@ async function startPanelServer(instanceId, ctx, pmx) {
                     return;
                 }
                 await copilotSession?.send({ prompt: body.prompt });
+                // Explicit user instruction from the panel → mirror onto the AX
+                // timeline as a steering message (fire-and-forget).
+                if (entry.pmx?.baseUrl) {
+                    void fetchJson(entry.pmx.baseUrl, "/api/canvas/ax/steer", {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({ message: body.prompt, source: "copilot" }),
+                        timeoutMs: 2_000,
+                    }).catch(() => {});
+                }
                 jsonResponse(res, 200, { ok: true });
                 return;
             }
@@ -434,6 +444,39 @@ async function setAxFocus(baseUrl, workspaceRoot, input = {}, nodeIds = []) {
     });
 }
 
+// POST a host-agnostic AX record to the canvas with the copilot source label.
+// Resolves the server first so the action returns an actionable error when the
+// canvas is unavailable, then maps the neutral primitive over plain HTTP.
+async function postAxRecord(ctx, path, payload) {
+    const resolved = await resolvePmxServer(ctx, { autoStart: false });
+    if (!resolved.ok || !resolved.baseUrl) {
+        return { ok: false, error: resolved.error ?? "PMX Canvas server is unavailable." };
+    }
+    try {
+        return await fetchJson(resolved.baseUrl, path, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ ...payload, source: "copilot" }),
+            timeoutMs: 2_000,
+        });
+    } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+
+// Fire-and-forget mirror of a copilot-originated action onto the AX timeline.
+// Never throws — adapter UX must not depend on the canvas being reachable.
+function recordCopilotSteering(ctx, message) {
+    void postAxRecord(ctx, "/api/canvas/ax/steer", { message }).catch(() => {});
+}
+
+async function getAxTimeline(ctx, limit) {
+    const resolved = await resolvePmxServer(ctx, { autoStart: false });
+    if (!resolved.ok || !resolved.baseUrl) return { ok: false, error: resolved.error };
+    const query = typeof limit === "number" && limit > 0 ? `?limit=${limit}` : "";
+    return await fetchJson(resolved.baseUrl, `/api/canvas/ax/timeline${query}`, { timeoutMs: 2_000 });
+}
+
 function hasUsefulAxContext(context) {
     return Boolean(context?.pinned?.count > 0 || context?.focus?.nodeIds?.length > 0);
 }
@@ -513,9 +556,157 @@ const pmxCanvas = createCanvas({
                 const prompt = typeof ctx.input?.prompt === "string" ? ctx.input.prompt.trim() : "";
                 if (!prompt) throw new CanvasError("prompt_required", "prompt is required");
                 await copilotSession?.send({ prompt });
+                // Mirror the explicit user instruction onto the AX timeline as a
+                // steering message (fire-and-forget). This is an explicit action
+                // flow, never a sync from the prompt hook.
+                recordCopilotSteering(ctx, prompt);
                 return { ok: true };
             },
         },
+        {
+            name: "add_work_item",
+            description: "Add a canvas-bound PMX AX work item (visible task/plan/status) from Copilot.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string" },
+                    status: { type: "string", enum: ["todo", "in-progress", "blocked", "done", "cancelled"] },
+                    detail: { type: "string" },
+                    nodeIds: { type: "array", items: { type: "string" } },
+                },
+                required: ["title"],
+                additionalProperties: false,
+            },
+            handler: async (ctx) => await postAxRecord(ctx, "/api/canvas/ax/work", {
+                title: ctx.input?.title,
+                ...(ctx.input?.status ? { status: ctx.input.status } : {}),
+                ...(ctx.input?.detail ? { detail: ctx.input.detail } : {}),
+                ...(Array.isArray(ctx.input?.nodeIds) ? { nodeIds: ctx.input.nodeIds } : {}),
+            }),
+        },
+        {
+            name: "request_approval",
+            description: "Request human approval before a high-impact action via a PMX AX approval gate.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string" },
+                    detail: { type: "string" },
+                    action: { type: "string" },
+                    nodeIds: { type: "array", items: { type: "string" } },
+                },
+                required: ["title"],
+                additionalProperties: false,
+            },
+            handler: async (ctx) => await postAxRecord(ctx, "/api/canvas/ax/approval", {
+                title: ctx.input?.title,
+                ...(ctx.input?.detail ? { detail: ctx.input.detail } : {}),
+                ...(ctx.input?.action ? { action: ctx.input.action } : {}),
+                ...(Array.isArray(ctx.input?.nodeIds) ? { nodeIds: ctx.input.nodeIds } : {}),
+            }),
+        },
+        {
+            name: "resolve_approval",
+            description: "Resolve a pending PMX AX approval gate (approved or rejected).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    decision: { type: "string", enum: ["approved", "rejected"] },
+                    resolution: { type: "string" },
+                },
+                required: ["id", "decision"],
+                additionalProperties: false,
+            },
+            handler: async (ctx) => await postAxRecord(
+                ctx,
+                `/api/canvas/ax/approval/${encodeURIComponent(String(ctx.input?.id ?? ""))}/resolve`,
+                {
+                    decision: ctx.input?.decision,
+                    ...(ctx.input?.resolution ? { resolution: ctx.input.resolution } : {}),
+                },
+            ),
+        },
+        {
+            name: "add_review_annotation",
+            description: "Add a canvas-bound PMX AX review annotation (comment/finding) anchored to a node, file, or region.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    body: { type: "string" },
+                    kind: { type: "string", enum: ["comment", "finding"] },
+                    severity: { type: "string", enum: ["info", "warning", "error"] },
+                    anchorType: { type: "string", enum: ["node", "file", "region"] },
+                    nodeId: { type: "string" },
+                    file: { type: "string" },
+                },
+                required: ["body"],
+                additionalProperties: false,
+            },
+            handler: async (ctx) => await postAxRecord(ctx, "/api/canvas/ax/review", {
+                body: ctx.input?.body,
+                ...(ctx.input?.kind ? { kind: ctx.input.kind } : {}),
+                ...(ctx.input?.severity ? { severity: ctx.input.severity } : {}),
+                ...(ctx.input?.anchorType ? { anchorType: ctx.input.anchorType } : {}),
+                ...(ctx.input?.nodeId ? { nodeId: ctx.input.nodeId } : {}),
+                ...(ctx.input?.file ? { file: ctx.input.file } : {}),
+            }),
+        },
+        {
+            name: "get_timeline",
+            description: "Read the bounded PMX AX timeline (events, evidence, steering) for diagnostics and continuity.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    limit: { type: "integer", minimum: 1, maximum: 200 },
+                },
+                additionalProperties: false,
+            },
+            handler: async (ctx) => await getAxTimeline(ctx, ctx.input?.limit),
+        },
+        {
+            name: "report_capability",
+            description: "Report this Copilot host/session capability to the canvas for AX diagnostics.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    canvas: { type: "boolean" },
+                    hooks: { type: "boolean" },
+                    tools: { type: "boolean" },
+                    sessionMessaging: { type: "boolean" },
+                    permissions: { type: "boolean" },
+                    files: { type: "boolean" },
+                    uiPrompts: { type: "boolean" },
+                },
+                additionalProperties: false,
+            },
+            handler: async (ctx) => {
+                const resolved = await resolvePmxServer(ctx, { autoStart: false });
+                if (!resolved.ok || !resolved.baseUrl) {
+                    return { ok: false, error: resolved.error ?? "PMX Canvas server is unavailable." };
+                }
+                try {
+                    return await fetchJson(resolved.baseUrl, "/api/canvas/ax/host-capability", {
+                        method: "PUT",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({
+                            host: "copilot",
+                            canvas: ctx.input?.canvas === true,
+                            hooks: ctx.input?.hooks === true,
+                            tools: ctx.input?.tools === true,
+                            sessionMessaging: ctx.input?.sessionMessaging === true,
+                            permissions: ctx.input?.permissions === true,
+                            files: ctx.input?.files === true,
+                            uiPrompts: ctx.input?.uiPrompts === true,
+                            source: "copilot",
+                        }),
+                        timeoutMs: 2_000,
+                    });
+                } catch (error) {
+                    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+                }
+            },
+        },
     ],
     open: async (ctx) => {
         let pmx;

package/CHANGELOG.md

@@ -3,6 +3,114 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.28] - 2026-06-06
+
+### Changed
+
+- **BREAKING (SDK): `PmxCanvas.addNode()` now returns the created node**
+  (a `CanvasNodeState` with `id`, geometry, and data) instead of a bare
+  id string. Use `const { id } = canvas.addNode(...)` or keep the whole
+  node. The MCP / HTTP / CLI surfaces and the internal `CanvasAccess`
+  contract are unchanged (still id-based).
+
+### Fixed
+
+- Tufte graph nodes (DotPlot/Bullet/Slopegraph) no longer flicker: the
+  chart-height ResizeObserver no longer feeds the document's own scroll
+  overflow back into its height.
+- Expanded Tufte graph views now fill the modal instead of staying
+  tile-sized with whitespace.
+- Graph node iframes no longer show a doubled scrollbar; a chart that
+  fits shows none, a dense chart shows exactly one.
+- Excalidraw / ext-app nodes paint on first mount instead of rendering
+  black until a manual expand/collapse (a post-layout host-context
+  nudge is delivered once the iframe has settled).
+- `image` and `ledger` nodes get roomier default sizes (480×360 /
+  420×280) instead of a cramped 360-wide frame.
+- `pmx-canvas web-artifact build` streams a stderr heartbeat during the
+  long install+bundle so agents don't see it as hung.
+- json-render rejects an unknown `$`-directive (e.g. `$path`) with a
+  clear error pointing at `$state`, instead of rendering
+  `"[object Object]"`.
+- Web-artifact script-path overrides are contained to the workspace with
+  a symlink-aware (realpath) check, fixing a false rejection on macOS.
+- **Security:** the `/api/canvas/image/<id>` route now refuses to serve
+  files outside the workspace root (returns 403), closing a path-
+  traversal read (e.g. an image node pointed at `../../etc/passwd`).
+
+## [0.1.27] - 2026-06-06
+
+Big release: the full host-agnostic agent-experience (AX) primitive
+contract and a json-render 0.19 upgrade with Tufte charts, directives,
+and live SpecStream rendering. The MCP canvas now exposes 56 tools (was
+45) and four AX resources. Plus the native GitHub Copilot and Codex
+canvas adapters are featured in the README.
+
+### Added
+
+- **Full AX primitive contract (plan-004 Phases 2-5).** Eleven new MCP
+  tools, each with complete parity across CanvasStateManager, SQLite
+  persistence, the Bun SDK, HTTP, the MCP server, the RemoteCanvasAccess
+  proxy, and the CLI, organized into three lifecycle partitions:
+  - **Canvas-bound** (participate in snapshots + restore, cleared by
+    `canvas_clear`, read via `canvas_get_ax` / `canvas://ax-work`):
+    `canvas_add_work_item`, `canvas_update_work_item`,
+    `canvas_request_approval`, `canvas_resolve_approval` (state machine
+    `pending → approved/rejected`, double-resolve rejected),
+    `canvas_add_review_annotation`.
+  - **Timeline** (persist in dedicated DB tables bounded by 500-row
+    retention, NOT restored by snapshots, NOT cleared by
+    `canvas_clear`, read via `canvas_get_ax_timeline` /
+    `canvas://ax-timeline`): `canvas_add_evidence`,
+    `canvas_record_ax_event`, `canvas_send_steering`.
+  - **Host/session** (survives `canvas_clear`):
+    `canvas_report_host_capability`.
+  New resources: `canvas://ax-work` and `canvas://ax-timeline` (joining
+  `canvas://ax` and `canvas://ax-context`). CLI gains `pmx-canvas ax`
+  subcommands.
+- **`canvas_stream_json_render_node` (SpecStream).** Progressively build
+  a json-render node by streaming JSON-Patch operations; the server
+  accumulates the spec (it is the source of truth) and the live node
+  re-renders as patches arrive. Omit `nodeId` to create, pass it back to
+  append, set `done:true` to finish.
+- **Tufte chart types.** json-render graph nodes gain `Sparkline`,
+  `DotPlot`, `BulletChart`, and `Slopegraph`, wired through the full
+  definitions → catalog → component-registry pipeline alongside the
+  existing chart types.
+- **json-render 0.19.0 upgrade + directives + devtools.** All
+  `@json-render/*` packages move to 0.19.0. Specs can use the standard
+  stateless directives (`$format`, `$math`, `$concat`, `$count`,
+  `$truncate`, `$pluralize`, `$join`) for server-side derivations; an
+  opt-in devtools panel (double-gated behind an env flag + `?devtools=1`)
+  is available for debugging.
+- **Native GitHub Copilot and Codex canvas adapters featured in the
+  README**, with the `.github/extensions/pmx-canvas` Copilot extension
+  and the Codex/Copilot app-adapter skill references.
+
+### Fixed
+
+- **SpecStream rejects prototype-pollution patch paths.** Streamed
+  JSON-Patch paths whose JSON-Pointer contains a `__proto__`,
+  `constructor`, or `prototype` segment are now skipped (and counted)
+  rather than applied, closing a server-side prototype-pollution vector
+  in the new streaming path.
+- **`canvas_add_review_annotation` no longer reports false success for
+  invalid node anchors.** A node-anchored review annotation whose
+  `nodeId` is missing or not on the canvas was silently dropped by
+  normalization yet returned as a populated success object. It now
+  rejects up front (`ok:false` / HTTP 400 / MCP error) across every
+  layer, so agents can't lose review findings to a typo'd node id.
+
+### Internal
+
+- Regression coverage added for: SpecStream patch application (happy
+  path, malformed-item skipping, and the prototype-pollution guard with
+  an explicit `Object.prototype` cleanliness assertion), the Tufte
+  Sparkline/Slopegraph spec builders, and node-anchor validation for
+  review annotations (missing / unknown / file / valid). Docs updated:
+  `docs/mcp.md` adds the `canvas_fit_view` row, and
+  `skills/pmx-canvas/SKILL.md` lists the four `canvas://ax*` resources.
+
 ## [0.1.26] - 2026-06-03
 
 Small follow-up to 0.1.25. `canvas_add_node` can now create populated
@@ -1276,6 +1384,8 @@ otherwise have to discover by trial and error.
 - Regression coverage for snapshot flat-`id` aliases on both MCP and
   HTTP surfaces, plus async / top-level-`await` WebView script bodies.
 
+[0.1.28]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.28
+[0.1.27]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.27
 [0.1.26]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.26
 [0.1.25]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.25
 [0.1.24]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.24

package/Readme.md

@@ -3,9 +3,10 @@
 **A moldable canvas for agent-assisted thinking.** An infinite 2D surface
 where files, plans, status, charts, fetched web pages, annotations, and
 hand-drawn diagrams live side by side. Every node carries its own renderer; agents
-(and you) build new views in the middle of a session, not as a separate
-tooling project. Pin what matters and the agent reads your spatial
-curation as structured context.
+(and you) build new views in the middle of a session — even streaming a
+structured panel into place as they generate it — not as a separate tooling
+project. Pin what matters and the agent reads your spatial curation as
+structured context.
 
 <p align="center">
   <img src="docs/screenshots/welcome-dark.png" alt="Empty canvas — dark theme" width="49%" />
@@ -50,15 +51,28 @@ agents as compact spatial context: target, bounds, and nearby canvas content.
 
 ### 04 / Control your context
 
-Pinning is an explicit, low-noise control over what the agent sees next. No
-prompt engineering, no copy-paste — pin a node in the browser and the MCP
-server fires a `notifications/resources/updated` event the agent's harness
-picks up immediately.
-
-AX context adds a host-agnostic focus layer on top of pins. Core PMX exposes
-`/api/canvas/ax/context`, `canvas://ax-context`, SDK methods, and
-`pmx-canvas ax context|focus`; adapters can map that same primitive to their
-native hook systems without making PMX Canvas GitHub-specific.
+Steer the agent and see its work, without prompt engineering or copy-paste.
+Pin a node in the browser and the MCP server fires a
+`notifications/resources/updated` event the agent's harness picks up
+immediately — an explicit, low-noise control over what the agent sees next.
+
+On top of pins, a host-agnostic **AX (agent-experience) layer** turns the
+canvas into a shared workspace between you and the agent:
+
+- **Focus** — promote nodes into the agent's active context without moving the viewport.
+- **Work items & approval gates** — track visible tasks tied to nodes, and gate
+  high-impact actions behind a human `pending → approved/rejected` decision.
+- **Steering messages & agent-event timeline** — send instructions to the
+  active session, and read a normalized, bounded timeline of prompts, tool
+  runs, evidence (logs/diffs/screenshots/test-output), and failures.
+- **Host capability** — adapters report what the host can do, for diagnostics.
+
+Canvas-bound state (focus, work items, approvals, review annotations) rides
+canvas snapshots and restore; the timeline persists for continuity but is
+retention-bounded and never restored by a snapshot. Every primitive is reachable
+from MCP, the HTTP API, the SDK, and `pmx-canvas ax …`. The core never depends
+on any host SDK, so adapters (e.g. the GitHub Copilot app) map onto the same
+neutral surfaces without making PMX Canvas vendor-specific.
 
 ### 05 / Save
 
@@ -71,27 +85,47 @@ the DB so SQLite WAL data is checkpointed into the file.
 
 ### 06 / Any agent
 
-Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (45 tools,
-9 resources, change notifications), the [CLI](docs/cli.md), the
+Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (56 tools,
+12 resources, change notifications), the [CLI](docs/cli.md), the
 [HTTP API](docs/http-api.md), or the [Bun SDK](docs/sdk.md). Works with
 Claude Code, GitHub Copilot CLI, Codex, Cursor, Windsurf, or any agent
 that can spawn an MCP stdio server, call a CLI, or hit an HTTP endpoint.
 
-The repo also ships a GitHub Copilot app adapter at
-`.github/extensions/pmx-canvas/`. It opens the live PMX workbench in a native
-Copilot canvas panel, injects AX pinned/focused context on prompt submission,
-and exposes adapter actions for status, AX focus, context refresh, and explicit
-session steering.
+### 07 / Native app adapters
 
-In the Codex app, PMX Canvas is MCP-first plus the Codex in-app Browser: agents
-read `canvas://ax-context` / `canvas_get_ax`, humans use the live `/workbench`
-view, and Codex-originated focus can be labeled with `source: "codex"` through
-`canvas_set_ax_focus`. The CLI remains a fallback for scripts and manual
-debugging, not the native Codex adapter path.
+PMX Canvas doesn't just run in a browser tab — it embeds **natively inside the
+agent apps you already use**, as a thin adapter layer over the same neutral AX
+surfaces (the core never imports a host SDK).
+
+<p align="center">
+  <img src="docs/screenshots/github-copilot-app.png" alt="PMX Canvas as a native canvas panel in the GitHub Copilot app" width="100%" />
+</p>
+<p align="center"><sub>PMX Canvas as a native canvas panel in the GitHub Copilot app.</sub></p>
+
+<p align="center">
+  <img src="docs/screenshots/codex-app.png" alt="PMX Canvas workbench in the Codex in-app Browser" width="100%" />
+</p>
+<p align="center"><sub>The live PMX workbench in the Codex in-app Browser.</sub></p>
+
+- **GitHub Copilot app** — a committed project canvas extension
+  (`.github/extensions/pmx-canvas/`) opens the live PMX workbench in a native
+  Copilot panel, injects pinned/focused AX context on prompt submission, and
+  exposes actions for focus, session steering, work items, approval gates,
+  review annotations, the AX timeline, and host-capability reporting. Install it
+  into any repo with `pmx-canvas copilot install-extension` (`--dry-run` to
+  preview).
+- **Codex app** — native through the Codex in-app Browser (opened to
+  `/workbench`) plus the PMX MCP server: agents read `canvas://ax-context` /
+  `canvas_get_ax` and label Codex-originated focus with `source: "codex"`. No
+  extension API needed — Codex's two native surfaces (MCP + in-app Browser) are
+  exactly what the canvas requires.
+
+The contract is host-agnostic, so a new host plugs in the same way: map its
+hooks, canvas, and session APIs onto PMX's AX primitives — no core changes.
 
 ## Prerequisites
 
-- [Bun](https://bun.sh) >= 1.3.12
+- [Bun](https://bun.sh) >= 1.3.14
 
 The published SDK entrypoint is Bun-first. Node.js consumers should use the
 CLI, MCP server, or HTTP API.
@@ -155,7 +189,20 @@ When loaded by the Copilot app, it opens the PMX workbench natively, starts a
 matching local PMX server when needed, and injects `AX` pinned/focused context
 as hidden per-turn context. The adapter is thin: PMX state still lives in
 `.pmx-canvas/canvas.db`, and the same HTTP, MCP, CLI, and SDK surfaces remain
-available to non-GitHub agents.
+available to non-GitHub agents. See
+[`github-copilot-app-adapter.md`](skills/pmx-canvas/references/github-copilot-app-adapter.md)
+for the full setup and live-test checklist.
+
+### Use inside the Codex app
+
+Codex needs no extension — its two native surfaces are exactly what the canvas
+requires. Add the PMX MCP server to the Codex workspace config (same snippet as
+[Connect your agent](#connect-your-agent-mcp)), then open the returned
+`/workbench` URL in the **Codex in-app Browser** so you can see mutations live.
+Agents read pinned/focused context from `canvas://ax-context` / `canvas_get_ax`
+and label Codex-originated focus with `source: "codex"`. See
+[`codex-app-adapter.md`](skills/pmx-canvas/references/codex-app-adapter.md) for
+the full workflow and live-test checklist.
 
 ### Install the agent skill (recommended)
 
@@ -188,7 +235,7 @@ the agent can read `canvas://skills` and pull in companion skills
   the three-tier visual matrix (json-render → html → web-artifact)
 - **[CLI reference](docs/cli.md)** — full command surface, daemon mode,
   watch streams, WebView automation
-- **[MCP reference](docs/mcp.md)** — 45 tools, 9 resources, change
+- **[MCP reference](docs/mcp.md)** — 56 tools, 12 resources, change
   notifications, node-type routing
 - **[HTTP API](docs/http-api.md)** — REST endpoints, SSE, batch operations
 - **[Bun SDK](docs/sdk.md)** — `createCanvas()` for TypeScript on Bun