pmx-canvas 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -5,6 +5,128 @@ All notable changes to `pmx-canvas` are documented here. This project follows
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-06-22
+
+### Added
+
+- **Ghost Cursor of Intent — a pre-commit presence layer.** An agent can announce the
+  spatial move it is *about* to make, so the canvas paints a faint, dashed "ghost"
+  placeholder *before* the real mutation lands — modeled on a multiplayer cursor
+  (ephemeral presence, never canvas state). An intent describes one of five moves
+  (`create` / `move` / `connect` / `remove` / `edit`) at a spatial anchor, with an
+  optional `label`, `reason` (why the agent wants it), `confidence` (0–1, drives ghost
+  opacity), and `seq` (staged-batch ordering). The human watching the browser can
+  **veto** a forming ghost (✕ on the ghost or Esc while hovered) before it happens — a
+  veto dissolves the ghost, queues a steering message back to the agent, and *poisons
+  that intent id* so the linked mutation is rejected. When the agent runs the real
+  mutation **linked** to the intent (by passing the returned `intent.id` as
+  `intentId`), the ghost **settles** into the real node automatically. Ghosts are never
+  persisted, never snapshotted, never in `canvas_get_layout`; they auto-expire (~8 s
+  default, 60 s max) and are count-capped (12 live, oldest evicted).
+  - **New MCP tool `canvas_intent`** (composite-only): `signal` (register/replace an
+    intent → `{ ok, intent }`), `update` (patch a live intent + reset its TTL), `clear`
+    (dissolve a ghost; `vetoed:true` for a human veto, `settledNodeId` to morph it into a
+    real node). The public MCP surface grows from 83 to 84 tools (15 composites).
+  - **New optional `intentId`** on the mutation tools/ops (`canvas_node`, `canvas_edge`,
+    `canvas_group`, `canvas_render`) and the matching SDK methods — passing it links the
+    mutation to a live ghost so it settles on success and is rejected if vetoed/expired.
+    Omitting it (every prior caller) is byte-identical to before.
+  - **New HTTP routes** `POST /api/canvas/ax/intent`, `PATCH`/`DELETE
+    /api/canvas/ax/intent/:id`; **new SSE frames** `ax-intent` / `ax-intent-clear`
+    (replayed to reconnecting browsers); **new SDK methods** `signalIntent` /
+    `updateIntent` / `clearIntent`. Purely additive — no existing behavior changes.
+
+### Fixed
+
+- **Daemon status reports its workspace identity.** `pmx-canvas serve status` now returns the
+  canonical `workspace` from the live `/health` response, so agents can safely verify that a
+  responsive listener belongs to the intended project before mutating its board.
+- **Status nodes can be removed (report #64).** Status nodes now show the standard ×
+  remove control in their title bar (and a "Close" context-menu item) like every other
+  node type, with the same undo/history behavior — they were previously the only node
+  type with no removal control, so temporary/test status nodes accumulated with no way
+  to dismiss them from the node UI.
+- **Right-click "Pin" now pins to the agent context set (report #63).** The node
+  context menu offered the niche arrange-lock as the obvious "Pin"/"Unpin" item while
+  the primary human→agent context pin was buried under "Add to context", so clicking
+  "Pin" appeared to do nothing. The menu now lists **"Pin as context" / "Unpin from
+  context"** first (matching the SelectionBar wording; drives the context count +
+  indicator), and the arrange-lock item is renamed **"Lock position (no auto-arrange)"**
+  and now persists like other layout mutations.
+- **Hosted MCP-app nodes no longer offer a broken "Open as site" (report #61).** A
+  hosted ext-app (e.g. Excalidraw) is a live MCP-app shell that only renders with the
+  in-canvas AppBridge host; opening it as a standalone browser tab produced
+  `MCP error -32601: Method not found`. Such apps are no longer openable as a PMX site
+  (the control is hidden and the surface route returns a clean 404) — open them
+  externally through their own app, or view them in the canvas. Bundled web-artifacts
+  and url-backed viewers still open as a site.
+- **Expanded MCP-app nodes no longer clip text (report #62).** The expand/collapse
+  host-context update measured the iframe synchronously, before the expanded overlay had
+  laid out, so an app like Excalidraw reflowed bound text against the stale inline size
+  and clipped the start of labels. The measurement + host-context send now wait for
+  layout (double rAF, mirroring the post-ready nudge) so the app gets the real expanded
+  dimensions.
+- **Graph / json-render "Open as site" fills the browser viewport (report #65).** The
+  standalone viewer reused the in-canvas card height, so a graph opened as a site sat in
+  a shallow band at the top of a large window. The "Open as site" surface now serves the
+  viewer in a `display=site` mode that fills the viewport (flex `100dvh`, chart height
+  measured from the full window, resize-responsive) — distinct from the in-canvas
+  content-fit grow and the expanded-overlay fill, neither of which changes.
+
+### Docs
+
+- **Bundled skill audit fixes (skill-audit 2026-06-22).** `skills/pmx-canvas/SKILL.md`:
+  added a mandatory **workspace-identity preflight** (read `/health`, match
+  `workspace`, treat `responsive:true`+`pidRunning:false` as a stale listener,
+  isolate with an explicit `--port`) so an agent never mutates another project's canvas
+  via a leftover port-4313 daemon; a short **Quick Operating Path** front-door; corrected
+  the **MCP composite map to the current 15** (added `canvas_app` + `canvas_webview`,
+  `canvas_query validate`, `canvas_node`-creates-html/primitive) and reclassified the
+  folded standalones as deprecated→composite (removed in v0.3); and a **Known limitations
+  & host differences** section reflecting the #61–#65 fixes plus the remaining Codex
+  sandboxed-iframe automation limit. The eval suite grew from 7 to 15 cases (workspace
+  mismatch, current composites, board extension, verified pinning, status cleanup, AX
+  control surface, AX delivery, final cleanup/validate). The top-level skill is now a
+  224-line operational guide; the complete long-form manual lives in
+  `references/full-reference.md`.
+
+## [0.2.1] - 2026-06-17
+
+### Fixed
+
+- **Compact AX context surfaces the NEWEST steering first (report #57).** The
+  `delivery.pendingSteering` lead block on `GET /api/canvas/ax/context` /
+  `canvas://ax-context` returned the OLDEST 10 undelivered steers, so on a long-lived
+  board a fresh steer was buried behind old unacked ones and never appeared in the
+  compact block. It now returns the **newest** undelivered steering first (capped at
+  10), so a fresh steer is always visible. The FIFO claim/ack delivery queue
+  (`/api/canvas/ax/delivery/pending`, `canvas_ax_delivery { action: "claim" }`) is
+  unchanged — still oldest-first for ordered processing.
+
+### Added
+
+- **AX context delivery backlog counts (report #57).** `delivery` now includes
+  `totalPending` (undelivered steering for the consumer, loop-safe) and `omittedPending`
+  (`= totalPending − pendingSteering.length`), so an agent can tell the compact block
+  omitted a backlog and drain the full FIFO queue when `omittedPending > 0`. Additive,
+  non-breaking.
+- **Blessed AX HTML Control Surface recipe (report #60).** New
+  `skills/pmx-canvas/references/ax-html-control-surface.md` (linked from `SKILL.md`): a
+  copy-paste-safe template (awaited `emit` + live ack display + `pmx-ax-update`
+  reflection) plus the three footguns that make a hand-rolled AX node look inert — the
+  sandboxed opaque-origin iframe throws on `localStorage`/`sessionStorage`/cookies,
+  `emit` must be awaited, and `ax.steer` is recorded (queued), not delivered.
+
+### Docs
+
+- **Canvas-origin steering does not wake the active agent by itself (report #59).** The
+  host-adapter contract, `SKILL.md`, and the GitHub Copilot adapter reference now state
+  plainly that a browser-origin `ax.steer` (and its `ok:true` emit ack) is *queued*, not
+  pushed into the live session; the wake is host-adapter-owned (drain
+  `canvas_ax_delivery { action: "claim" }` → native send → `mark`), and a steering button
+  must be labeled "queued for the agent's next turn." Adapters should read steering from
+  the compact `delivery.pendingSteering` block, not `timeline.pendingSteering`.
+
 ## [0.2.0] - 2026-06-16
 
 ### Breaking
@@ -2234,6 +2356,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.2.2]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.2
+[0.2.1]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.1
 [0.2.0]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.0
 [0.1.36]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.36
 [0.1.35]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.35

package/Readme.md

@@ -105,7 +105,7 @@ the DB so SQLite WAL data is checkpointed into the file.
 
 ### 06 / Any agent
 
-Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (83 tools,
+Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (84 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
@@ -255,7 +255,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)** — 83 tools, 14 resources, change
+- **[MCP reference](docs/mcp.md)** — 84 tools, 14 resources, change
   notifications, node-type routing
 - **[HTTP API](docs/http-api.md)** — REST endpoints, SSE, batch operations
 - **[AX host-adapter contract](docs/ax-host-adapter-contract.md)** — how native

package/dist/canvas/global.css

@@ -3484,3 +3484,263 @@ button.welcome-hint:hover {
 .image-node-zoom-reset:hover {
   background: var(--c-surface-hover);
 }
+
+/* ── Ghost Cursor of Intent ─────────────────────────────────────
+   Pre-commit presence: faint placeholders for the move the agent is about to
+   make. Lives inside the canvas world transform (positions are world coords).
+   The layer sits above nodes so remove/edit overlays read on top of their
+   target, but is pointer-transparent except the info card + veto control. */
+.intent-layer {
+  display: contents;
+}
+
+.intent-ghost {
+  position: absolute;
+  pointer-events: none;
+  z-index: 100000;
+  transition:
+    left 480ms ease,
+    top 480ms ease,
+    width 480ms ease,
+    height 480ms ease,
+    opacity 180ms ease;
+}
+
+/* create / move destination — a dashed ghost node */
+.intent-ghost-box {
+  border: 1.5px dashed var(--c-accent);
+  border-radius: 10px;
+  background: var(--c-accent-10);
+  box-shadow: 0 0 0 1px var(--c-accent-10), 0 6px 22px var(--c-accent-10);
+  animation: intent-breathe 2.1s ease-in-out infinite;
+  overflow: visible;
+}
+
+.intent-ghost-titlebar {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 10px;
+  color: var(--c-accent);
+}
+
+.intent-ghost-icon {
+  display: inline-flex;
+  align-items: center;
+  color: var(--c-accent);
+}
+
+.intent-ghost-badge {
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  color: var(--c-accent);
+  opacity: 0.85;
+}
+
+@keyframes intent-breathe {
+  0%, 100% { box-shadow: 0 0 0 1px var(--c-accent-10), 0 6px 22px var(--c-accent-10); }
+  50%      { box-shadow: 0 0 0 1px var(--c-accent-25), 0 8px 30px var(--c-accent-25); }
+}
+
+/* remove — a red crosshatch tombstone over the target */
+.intent-ghost-remove {
+  border: 1.5px dashed var(--c-danger);
+  border-radius: 10px;
+  background-color: color-mix(in srgb, var(--c-danger) 8%, transparent);
+  background-image: repeating-linear-gradient(
+    45deg,
+    color-mix(in srgb, var(--c-danger) 22%, transparent) 0,
+    color-mix(in srgb, var(--c-danger) 22%, transparent) 2px,
+    transparent 2px,
+    transparent 9px
+  );
+}
+
+/* edit — a shimmer bar over the target */
+.intent-ghost-edit {
+  border: 1.5px dashed var(--c-accent);
+  border-radius: 10px;
+  background: var(--c-accent-10);
+  overflow: visible;
+}
+
+.intent-edit-bar {
+  position: absolute;
+  top: 0;
+  left: 0;
+  height: 3px;
+  width: 100%;
+  background: linear-gradient(90deg, transparent, var(--c-accent), transparent);
+  animation: response-stream-pulse 1.5s ease-in-out infinite;
+}
+
+/* connect — info card anchored at the bezier midpoint */
+.intent-ghost-connect {
+  display: flex;
+  justify-content: center;
+}
+
+/* the info treatment: label + confidence chip, reason, seq, veto */
+.intent-info {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  margin-top: 6px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  pointer-events: auto;
+  max-width: 280px;
+}
+
+.intent-ghost-connect .intent-info {
+  position: static;
+  margin-top: 0;
+  align-items: center;
+}
+
+.intent-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  align-self: flex-start;
+  padding: 3px 6px 3px 8px;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--c-panel-glass) 96%, transparent);
+  backdrop-filter: blur(10px);
+  border: 1px solid var(--c-accent-25);
+  box-shadow: 0 4px 14px var(--c-shadow);
+  color: var(--c-text);
+  font-size: 12px;
+  line-height: 1.2;
+}
+
+.intent-seq {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 16px;
+  height: 16px;
+  padding: 0 4px;
+  border-radius: 999px;
+  background: var(--c-accent);
+  color: var(--c-bg);
+  font-size: 10px;
+  font-weight: 700;
+}
+
+.intent-chip-icon {
+  display: inline-flex;
+  align-items: center;
+  color: var(--c-accent);
+}
+
+.intent-chip-label {
+  font-weight: 600;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 180px;
+}
+
+.intent-confidence {
+  font-size: 10px;
+  font-variant-numeric: tabular-nums;
+  color: var(--c-muted);
+}
+
+.intent-veto {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  margin-left: 2px;
+  padding: 0;
+  border: none;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--c-muted);
+  font-size: 11px;
+  cursor: pointer;
+  transition: background 120ms ease, color 120ms ease;
+}
+
+.intent-veto:hover {
+  background: color-mix(in srgb, var(--c-danger) 18%, transparent);
+  color: var(--c-danger);
+}
+
+.intent-reason {
+  align-self: flex-start;
+  padding: 3px 8px;
+  border-radius: 7px;
+  background: color-mix(in srgb, var(--c-panel-glass) 92%, transparent);
+  border: 1px solid var(--c-line);
+  color: var(--c-muted);
+  font-size: 11px;
+  line-height: 1.35;
+}
+
+/* connect bezier + move trail (SVG) */
+.intent-line-layer path {
+  fill: none;
+}
+
+.intent-line-layer {
+  z-index: 99999;
+}
+
+.intent-edge {
+  stroke-width: 2;
+  stroke-dasharray: 6 5;
+  animation: intent-dash 0.9s linear infinite;
+}
+
+.intent-edge.type-flow { stroke: var(--c-accent); }
+.intent-edge.type-depends-on { stroke: var(--c-warn); }
+.intent-edge.type-relation { stroke: var(--c-muted); }
+.intent-edge.type-references { stroke: var(--c-dim); }
+
+.intent-trail {
+  stroke: var(--c-accent);
+  stroke-width: 2;
+  stroke-dasharray: 5 5;
+  animation: intent-dash 0.9s linear infinite;
+}
+
+.intent-arrow-head {
+  fill: var(--c-accent);
+}
+
+@keyframes intent-dash {
+  to { stroke-dashoffset: -22; }
+}
+
+/* settle — the ghost becomes real, then clears */
+.intent-ghost.is-settling {
+  animation: intent-settle 480ms ease forwards;
+}
+
+@keyframes intent-settle {
+  0%   { transform: scale(1); }
+  45%  { transform: scale(1.04); border-style: solid; opacity: 1; }
+  100% { transform: scale(1); opacity: 0; }
+}
+
+/* dissolve — abandoned / vetoed / expired */
+.intent-ghost.is-dissolving {
+  animation: intent-dissolve 320ms ease forwards;
+}
+
+@keyframes intent-dissolve {
+  to { transform: scale(0.96); opacity: 0; filter: blur(2px); }
+}
+
+/* keep ghosts calm while a node is being dragged */
+html.is-node-dragging .intent-ghost,
+html.is-node-dragging .intent-line-layer {
+  opacity: 0.5;
+}