pmx-canvas 0.1.28 → 0.1.30

package/CHANGELOG.md

@@ -3,6 +3,197 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.30] - 2026-06-07
+
+### Added
+
+- **PMX-AX node interactions (plan-004 Phase 1).** A host-agnostic, capability-gated
+  interaction layer over the existing AX primitives. Eligible nodes emit one
+  normalized `PmxAxInteraction` envelope (`{ type, sourceNodeId, payload, ... }`)
+  that is validated against a per-node-type capability registry (with optional
+  per-node `data.axCapabilities` opt-in/narrowing, clamped to a server ceiling)
+  and mapped onto the matching AX operation — work item, evidence, approval,
+  review, focus, steering, or event. New `POST /api/canvas/ax/interaction`
+  endpoint plus full SDK (`PmxCanvas.submitAxInteraction`), CanvasAccess, MCP
+  (`canvas_ax_interaction`), and CLI (`pmx-canvas ax interaction`) coverage.
+  Interactions are sandbox/transport-agnostic (the same envelope will back native
+  nodes, json-render actions, the HTML bridge, MCP apps, and host adapters in
+  later phases); `html`/`html-primitive`, `mcp-app`, and internal `prompt`/`response`
+  nodes are disabled by default. Accepted and rejected interactions emit SSE
+  (`ax-interaction`) plus the underlying AX state event. PMX core still imports no
+  host SDK (guarded by `ax-parity.test.ts`).
+
+- **PMX-AX sandboxed HTML bridge (plan-004 Phase 3).** Opted-in `html` /
+  `html-primitive` nodes can emit AX interactions from inside the sandbox via
+  `window.PMX_AX.emit(type, payload)`. The server injects the bridge into the
+  surface document only when the node's AX capabilities are enabled; the bridge
+  posts a nonce-tagged message to the parent canvas, which validates the nonce +
+  node id and submits through the capability-gated endpoint (the server
+  re-validates, so the bridge is convenience, not a trust boundary). The iframe
+  sandbox stays `allow-scripts` only. (json-render action→AX mapping remains a
+  documented follow-up — the viewer needs a parent channel, same shape as this
+  bridge.)
+
+- **PMX-AX delivery semantics (plan-004 Phase 4).** Steering messages can be
+  claimed and acknowledged by adapterless consumers. New
+  `GET /api/canvas/ax/delivery/pending?consumer=` (loop-safe — excludes steering
+  the consumer itself originated) and `POST /api/canvas/ax/delivery/:id/mark`,
+  plus SDK/CanvasAccess (`getPendingSteering`, `markSteeringDelivered`), MCP tools
+  (`canvas_claim_ax_delivery`, `canvas_mark_ax_delivery`), MCP resources
+  (`canvas://ax-pending-steering`, `canvas://ax-delivery`), an MCP prompt
+  template (`pmx-current-context`) so MCP-aware clients can inject PMX context
+  without a host adapter, and CLI (`pmx-canvas ax delivery list|mark`).
+
+- **PMX-AX elicitation + mode-request primitives (plan-004 Phase 5).** Two new
+  canvas-bound, snapshotted AX primitives: `elicitation` (request structured
+  human input → respond) and `mode-request` (request a plan/execute/autonomous
+  transition → resolve). Full HTTP / SDK / CanvasAccess / MCP
+  (`canvas_request_elicitation`, `canvas_respond_elicitation`,
+  `canvas_request_mode`, `canvas_resolve_mode`) / CLI coverage, and both are
+  executable via the interaction envelope (`ax.elicitation.request`,
+  `ax.mode.request`). Command registry and tool/prompt policy primitives are
+  intentionally deferred pending the plan's open product questions (which
+  commands are first-class; how much prompt/system-message mutation PMX should
+  allow by default); the capability registry already reserves `mcp-app` (disabled
+  by default), so the MCP-app interaction bridge (Phase 6) is gated and
+  forward-compatible until that trust boundary is designed.
+
+- **PMX-AX follow-ups — command registry, tool/prompt policy, json-render +
+  MCP-app bridges.** The four documented deferrals now ship. (1) A **command
+  registry** (`pmx.plan`, `pmx.execute`, `pmx.promote-context`, `pmx.summarize`,
+  `pmx.review`) with a registry-gated `invokeCommand` (records an `agent-event`
+  of kind `command`); unknown names are rejected (`400`). Executable via the
+  envelope (`ax.command.invoke`) and exposed over HTTP
+  (`GET|POST /api/canvas/ax/command`), SDK, CanvasAccess, MCP
+  (`canvas_invoke_command`), and CLI (`pmx-canvas ax command list|invoke`).
+  (2) A canvas-bound, snapshotted **tool/prompt policy** singleton
+  (`tools.allowed|excluded|approvalRequired`, `prompt.systemAppend|mode`) read
+  into `canvas://ax-context`; set via `GET|POST /api/canvas/ax/policy`,
+  `canvas_set_ax_policy`, and `pmx-canvas ax policy get|set` (patches merge and
+  are normalized server-side). (3) The **json-render viewer → AX channel**: a
+  spec action named after an AX type (e.g. `on.press → { action:
+  "ax.work.create" }`) is forwarded by the viewer bundle to the parent canvas,
+  which validates (iframe source + per-viewer nonce + node id) and submits
+  through the capability-gated endpoint (`sourceSurface: 'json-render'`). The
+  bridge nonce/node-id globals are injected into the viewer HTML only when the
+  embedding node requests them. (4) The **MCP-app interaction bridge (Phase 6)**:
+  opted-in ext-app `mcp-app` nodes get `window.PMX_AX.emit(...)` injected into
+  the app HTML (same nonce-tagged shape as the HTML bridge,
+  `sourceSurface: 'mcp-app'`), disabled by default and node-scoped. All emit
+  surfaces remain convenience-only — the server re-validates every interaction
+  against the node's effective capabilities, so it stays the single trust
+  boundary.
+
+- **PMX-AX native node controls (plan-004 Phase 2).** Inline AX controls on
+  native nodes that submit interactions through the browser: status nodes get a
+  "Track as work" button (→ `ax.work.create`), file nodes a "mark as evidence"
+  control (→ `ax.evidence.add`), and context nodes a "Set focus" button
+  (→ `ax.focus.set`). A client helper (`submitAxInteractionFromClient`) posts to
+  the interaction endpoint and surfaces the outcome as a transient toast.
+  (json-render action → AX mapping is deferred to the bridge-transport work: the
+  json-render viewer consumes actions internally and needs a viewer→parent
+  channel, the same shape as the HTML and MCP-app bridges.)
+
+- **Open as site — standalone node surfaces.** Every renderable surface node can
+  now be opened full-page in its own browser tab via an ↗ "Open as site" button
+  (node title bar and expanded overlay), covering `html` / `html-primitive`,
+  bundled `web-artifact`, `json-render` / `graph`, `webpage`, and hosted ext-app
+  `mcp-app` nodes. A new stable route, `GET /api/canvas/surface/:nodeId`, serves
+  (or redirects to) the surface, and the in-canvas `html` iframe now loads that
+  **same URL** — one render path, no separate "preview" document, and the URL
+  reflects current node state and survives a refresh. Node payloads expose the
+  URL as `surfaceUrl` (`canvas_get_node` / `canvas_get_layout`) so agents can
+  point a human at "the artifact" without disturbing the canvas. Served HTML
+  keeps its opaque-origin posture (`Content-Security-Policy: sandbox`), so author
+  code opened top-level cannot reach the canvas origin. The html surface theme is
+  served from a new same-origin stylesheet (`/canvas/surface-theme.css`) and
+  live-switches via the existing theme bridge. ext-app surfaces render their UI
+  but, opened standalone, cannot run interactive tool-calls (no host bridge in a
+  bare tab); `webpage` / URL-backed `mcp-app` nodes redirect to their site.
+
+### Fixed
+
+- **json-render specs preserve `on` event bindings through validation.** The
+  json-render element schema dropped the `on` field during validation, so
+  spec-authored action bindings (`on.press`, `on.change`, …) were silently
+  stripped before reaching the viewer and never fired. `on` is now retained,
+  which both makes general json-render interactivity work and is what lets the
+  json-render → AX channel above dispatch its `ax.*` actions. `on` is optional —
+  normalization defaults it to an empty bindings object, so specs whose elements
+  have no event bindings still validate.
+
+- **Canvas iframes are promoted to their own compositing layer**
+  (`transform: translateZ(0)` on `.html-node-frame` / `.mcp-app-frame`) to
+  mitigate an intermittent blank-iframe glitch — an HTML/app node iframe in
+  the zoom/pan-transformed canvas (near the chrome's heavy backdrop-filter
+  blur and behind group frames) could occasionally paint blank until a
+  resize/zoom forced a repaint. Investigation ruled out a content/load issue
+  (the frame document served valid HTML) and a DOM-reorder/reload on grouping
+  (reproduced grouping single and multiple HTML nodes with the iframe keeping
+  its src and content); the remaining cause is a browser compositor paint
+  invalidation, which the dedicated GPU layer addresses.
+
+### Changed
+
+- **Group frames are roomier.** Auto-fit group frames now leave more margin
+  around their children (`GROUP_PAD` 40 → 56) so the group header and its
+  node-count badge stay visible instead of sitting under the top-left child.
+- **Skill guidance: open the canvas first, always.** The bundled
+  `pmx-canvas` skill now tells agents to open/focus the workbench themselves
+  before mutating nodes on **every** host (Codex in-app Browser, Copilot
+  panel, or any plain browser) rather than assuming the host opened it — some
+  hosts don't. Added layout guidance too: space nodes generously (more when
+  edges connect them and inside groups, so the edge flow is visible) and size
+  group frames larger than their children.
+
+### Fixed
+
+- **Group operations no longer auto-pack or repack children.** Grouping
+  existing nodes (`canvas_group_nodes` / `/api/canvas/group/add`) without
+  an explicit `childLayout` now preserves their positions (matching
+  `canvas_create_group` and the batch `group.add`), and moving or resizing
+  a grouped child re-fits the group frame **without** repacking siblings or
+  discarding the child's requested coordinates. Compaction is opt-in via an
+  explicit layout. (0.1.29 report Bug #32.)
+- **HTTP/CLI node-create responses now include the `nodeId` alias.** The
+  0.1.29 `id`/`nodeId` alias only reached the MCP responses; the
+  `/api/canvas/node` (and graph/json-render) responses used by the CLI now
+  expose both keys too. (0.1.29 report Bug #31.)
+- **`canvas_batch` now supports `node.remove`.** The operation is
+  implemented (and listed in the tool description) instead of being
+  rejected as unsupported. (0.1.29 report Bug #33.)
+
+## [0.1.29] - 2026-06-06
+
+### Changed
+
+- **Bullet graph nodes accept the conventional `actual` measure key** in
+  addition to `value`, so `data: [{ label, actual, target }]` renders
+  without an explicit `valueKey` instead of failing the data-key check.
+- **Node-create MCP responses expose both `id` and a `nodeId` alias.**
+  All node-create tools (including SpecStream) now return both keys,
+  matching the existing external-app / web-artifact responses, so agents
+  using either key (or a cached schema) work.
+- **Friendlier AX CLI errors for bare subcommands.** Running `pmx-canvas
+  ax event` (or `evidence`/`host`/`work`/`approval`/`review`) without the
+  action now suggests the full command (e.g. `ax event add`) or lists the
+  available actions instead of a generic unknown-command error.
+
+### Fixed
+
+- **`pmx-canvas --mcp` no longer crashes with `EADDRINUSE`** when a daemon
+  already holds the target port for a *different* workspace. The MCP/SDK
+  auto-start now falls back to a free port (a same-workspace daemon is
+  still attached to as before) and prints a stderr note explaining how to
+  share one canvas (`PMX_CANVAS_URL` / `PMX_CANVAS_PORT` or run the daemon
+  from this workspace). An explicit SDK `start()` port is still honored
+  exactly unless `allowPortFallback` is passed.
+- **Ledger nodes render body `content` as a log** — one line per entry,
+  no stray "Content" field label, and a literal `\n` (as the shell
+  passes through `--content "a\nb"`) is treated as a line break instead
+  of being shown verbatim. Structured key/value fields still render as
+  rows, now with a gap so the label never runs into the value.
+
 ## [0.1.28] - 2026-06-06
 
 ### Changed
@@ -1384,6 +1575,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.30]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.30
+[0.1.29]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.29
 [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

package/Readme.md

@@ -37,7 +37,9 @@ neighborhoods) and uses your layout to ground its next action.
 
 Files, web pages, screenshots, structured panels, charts, hand-drawn
 diagrams, embedded MCP Apps, and bundled web artifacts all live on the same
-surface. The reach of the canvas is the union of its
+surface. Any rich surface — an HTML node or a web artifact — can be **opened as
+a site**, full-page in its own browser tab with one click; the canvas and the
+tab render the same document. The reach of the canvas is the union of its
 [built-in node types](docs/node-types.md) and **whatever your agent's harness
 already has access to** — MCP servers, CLIs, file reads, web fetch, anything
 on its toolbelt.
@@ -65,14 +67,22 @@ canvas into a shared workspace between you and the agent:
 - **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.
+- **Node interactions** — eligible nodes emit one capability-gated, validated
+  interaction envelope from native controls, the sandboxed HTML / MCP-app
+  bridges (`window.PMX_AX.emit`), or json-render spec actions. The server is the
+  single trust boundary and clamps sandboxed surfaces to their own node.
+- **Elicitations, mode requests, commands & policy** — request structured human
+  input, propose a plan/execute/autonomous mode transition, invoke registry
+  commands (`pmx.plan`, `pmx.review`, …), and read a tool/prompt policy.
 - **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.
+Canvas-bound state (focus, work items, approvals, review annotations,
+elicitations, mode requests, policy) 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
 
@@ -85,8 +95,8 @@ the DB so SQLite WAL data is checkpointed into the file.
 
 ### 06 / Any agent
 
-Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (56 tools,
-12 resources, change notifications), the [CLI](docs/cli.md), the
+Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (65 tools,
+14 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.
@@ -235,7 +245,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)** — 56 tools, 12 resources, change
+- **[MCP reference](docs/mcp.md)** — 65 tools, 14 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

package/dist/canvas/global.css

@@ -1473,6 +1473,19 @@ html.is-node-resizing .ext-app-preview-catcher {
   border-radius: 0 0 calc(var(--radius) - 1px) calc(var(--radius) - 1px);
 }
 
+/* Promote canvas iframes to their own GPU compositing layer. An iframe embedded
+   in the zoom/pan-transformed canvas — especially near the heavy backdrop-filter
+   blur used across the chrome and behind group frames — can intermittently paint
+   blank until a resize/zoom forces a repaint (reported for grouped HTML nodes;
+   the same class of compositor glitch as the earlier Excalidraw flicker). A no-op
+   3D transform forces a stable layer so the iframe keeps painting through
+   surrounding layout/stacking changes. */
+.mcp-app-frame,
+.html-node-frame {
+  transform: translateZ(0);
+  backface-visibility: hidden;
+}
+
 /* ── Prompt nodes ──────────────────────────────────────────── */
 .canvas-node:has(.prompt-node-inner) {
   border-color: var(--c-accent-30);