pmx-canvas 0.1.22 → 0.1.24

package/CHANGELOG.md

@@ -3,6 +3,144 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.24] - 2026-06-03
+
+Host-adapter and agent-experience (AX) release. Adds host-agnostic AX
+focus/context primitives across every layer, ships GitHub Copilot and
+Codex canvas adapters, moves embedded HTML/MCP-app iframes onto a
+same-origin frame-document transport (still strictly sandboxed via a
+CSP `sandbox` response header), and fixes a batch of iframe-backed
+node drag/resize/fullscreen interaction glitches.
+
+### Added
+
+- **PMX AX focus + context primitives.** A new host-agnostic
+  "agent experience" focus field lets any surface mark which nodes
+  an agent is attending to without moving the viewport. Implemented
+  end to end with full parity:
+  - State: `CanvasStateManager.getAxFocus()` / `setAxFocus()` /
+    `getAxState()`, recorded as a `setAxFocus` mutation-history op
+    (undo/redo) and persisted in a new SQLite `ax_state` table.
+  - SDK: `PmxCanvas.getAxState()`, `getAxContext()`, `setAxFocus()`.
+  - HTTP: `GET`/`PATCH /api/canvas/ax`, `GET /api/canvas/ax/context`,
+    `POST /api/canvas/ax/focus`.
+  - MCP: `canvas_get_ax`, `canvas_set_ax_focus` (45 tools total),
+    plus `canvas://ax` and `canvas://ax-context` resources that emit
+    `notifications/resources/updated` on change.
+  - CLI: `pmx-canvas ax focus <node-id...>` / `--clear`.
+  Focus state carries a `source` tag (`agent`/`api`/`browser`/`cli`/
+  `codex`/`copilot`/`mcp`/`sdk`/`system`) and node IDs are validated
+  against the live layout.
+- **GitHub Copilot canvas adapter.** A new
+  `.github/extensions/pmx-canvas/extension.mjs` (591 lines) plus
+  `skills/pmx-canvas/references/github-copilot-app-adapter.md`
+  document and implement driving the canvas from GitHub Copilot.
+- **Codex canvas adapter coverage.**
+  `skills/pmx-canvas/references/codex-app-adapter.md` documents the
+  Codex host integration, with browser regression coverage.
+- **Same-origin frame-document transport for embedded apps.**
+  Embedded HTML and MCP-app iframes now load their document from
+  `POST /api/canvas/frame-documents` → `GET /api/canvas/frame-
+  documents/<id>` instead of an inline `srcdoc`. The served document
+  carries `Content-Security-Policy: sandbox <tokens>`,
+  `Referrer-Policy: no-referrer`, and `X-Content-Type-Options:
+  nosniff`. The sandbox-token allowlist deliberately excludes
+  `allow-same-origin` and top-navigation tokens, so frame content
+  stays in an opaque origin and cannot reach the canvas host. The
+  document store is in-memory, capped at 128 entries (LRU eviction)
+  and 5 MB per document.
+
+### Changed
+
+- **Iframe-backed node drag is flicker-free.** Node drag now
+  rAF-throttles pointer moves, clears the browser text selection,
+  and toggles an `is-node-dragging` document class to suppress
+  selection and attention-field repaint artifacts. Inline app
+  iframes are kept pointer-inert near the resize handle so resize
+  starts reliably.
+- **Docs tool/resource references updated.** `docs/mcp.md` and the
+  README now read 45 tools + 9 core resources; the `AGENTS.md` and
+  `CLAUDE.md` MCP tool enumerations were corrected to the full
+  45-tool list (they had drifted to 42 and 39 respectively and were
+  missing `canvas_fit_view` and the new AX tools).
+
+### Internal
+
+- Regression coverage for: AX focus set/clear/persistence through
+  state, HTTP, MCP, SDK, and CLI; AX focus round-tripping through
+  SQLite; arrange-lock interactions; iframe-backed node
+  drag/resize/fullscreen behavior (large browser e2e additions); and
+  the Copilot/Codex adapter surfaces.
+
+## [0.1.23] - 2026-05-12
+
+Persistence overhaul. Canvas state, snapshots, context pins, and the
+large-payload blob store all move from filesystem JSON files into a
+single SQLite database at `.pmx-canvas/canvas.db` (WAL mode). The
+old `state.json`, `snapshots/`, and per-blob files are auto-imported
+on first boot and renamed to `.bak`. Adds dock-aware validation and
+arrange behavior, accepts the documented `?type=` query string on
+node creation, and grows the schema-metadata kebab-case aliases to
+include both singular and plural variants.
+
+### Added
+
+- **SQLite persistence (`src/server/canvas-db.ts`, 710 lines).**
+  Canvas state, snapshots, context pins, and the blob sidecar
+  store now live in `.pmx-canvas/canvas.db` (Bun SQLite in WAL
+  mode). Shape preserved across the migration: nodes, edges,
+  annotations, viewport, context pins, history, snapshots, and
+  blob payloads with checksum validation.
+  - Override DB path: `PMX_CANVAS_DB_PATH` env var.
+  - Backward-compatible legacy path: `PMX_CANVAS_STATE_FILE` (if
+    you set a `.db` path there, it's used as the DB; if not, it's
+    treated as a legacy JSON path for migration).
+  - `stopCanvasServer()` now calls `canvasState.close()` which
+    checkpoints WAL data into the DB file — stop the server (or
+    flush/close the SDK) before committing `canvas.db`.
+  - SQLite WAL/SHM files (`*.db-wal`, `*.db-shm`) are gitignored;
+    `canvas.db` itself is git-committable.
+- **Legacy migration on first boot.** Existing
+  `.pmx-canvas/state.json`, root `.pmx-canvas.json`,
+  `.pmx-canvas/snapshots/`, `.pmx-canvas-snapshots/`, and blob
+  files are imported into the SQLite database and renamed to
+  `.bak` on first start. The migration is idempotent and only
+  runs when the DB is empty.
+- **HTTP node create accepts `?type=` query string.** `POST
+  /api/canvas/node?type=html-primitive` with the body's `data`
+  fields is accepted as an alternative to passing `type` in the
+  body — handy for `curl` and shell-based agents. The body form
+  still wins when both are present.
+
+### Changed
+
+- **Docked nodes are excluded from layout collision validation.**
+  `validateCanvasLayout` no longer flags `dockPosition !== null`
+  nodes as overlap or containment violations. Docked HUD-style
+  nodes intentionally sit on top of canvas content; the validator
+  now models that.
+- **Docked nodes are treated as arrange-locked.** `arrange()`
+  now skips translating nodes with `dockPosition !== null` along
+  with pinned and explicitly arrange-locked nodes. Dock geometry
+  is anchored to the HUD layer, not the world grid.
+- **Schema kebab-case aliases include plural forms.** `--embedded-
+  node-ids`, `--embedded-urls`, and `--slide-titles` are now
+  documented aliases for the array-shaped HTML sidecar fields,
+  alongside the existing singular `--embedded-node-id`,
+  `--embedded-url`, and `--slide-title`.
+- **Bun engine bumped to `>=1.3.14`.** `package.json#engines.bun`
+  raised from `>=1.3.12` to `>=1.3.14` to pick up the
+  `bun:sqlite` improvements the new persistence layer depends on.
+
+### Internal
+
+- Regression coverage for: `validateCanvasLayout` ignoring docked
+  nodes as collision candidates, html primitive node creation
+  accepting the documented query-string `?type=` form, and the
+  existing canvas-state and operations suites continuing to pass
+  against the SQLite-backed persistence (including snapshot
+  save/restore, blob round-trip, and undo/redo history).
+
 ## [0.1.22] - 2026-05-12
 
 CLI ergonomics and response-size polish on top of 0.1.21. Adds a
@@ -1045,6 +1183,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.24]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.24
+[0.1.23]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.23
 [0.1.22]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.22
 [0.1.21]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.21
 [0.1.20]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.20

package/Readme.md

@@ -55,22 +55,40 @@ 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.
+
 ### 05 / Save
 
-Spatial state auto-saves to `.pmx-canvas/state.json` (debounced ~500 ms) —
+Spatial state auto-saves to `.pmx-canvas/canvas.db` (debounced ~500 ms) —
 git-committable, shareable across machines, and survives both browser
 refresh and server restart. Named [snapshots](docs/mcp.md#tools), full
 undo/redo, and an auto-detected code graph (JS/TS, Python, Go, Rust) make
-the canvas durable rather than throwaway.
+the canvas durable rather than throwaway. Stop the server before committing
+the DB so SQLite WAL data is checkpointed into the file.
 
 ### 06 / Any agent
 
-Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (42 tools,
-8 resources, change notifications), the [CLI](docs/cli.md), the
+Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (45 tools,
+9 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.
+
+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.
+
 ## Prerequisites
 
 - [Bun](https://bun.sh) >= 1.3.12
@@ -125,6 +143,20 @@ Add to your agent's MCP config:
 
 The canvas auto-starts on first tool call.
 
+### Use inside the GitHub Copilot app
+
+This repository includes a project canvas extension:
+
+```text
+.github/extensions/pmx-canvas/extension.mjs
+```
+
+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.
+
 ### Install the agent skill (recommended)
 
 The fastest way to get a working canvas is to install the `pmx-canvas` agent
@@ -147,8 +179,8 @@ Common harness skill directories: `.claude/skills/` (Claude Code),
 `.github/skills/` or `.copilot/skills/` (Copilot CLI),
 `.agents/skills/` (cross-harness convention). Once the canvas is running,
 the agent can read `canvas://skills` and pull in companion skills
-(`web-artifacts-builder`, `json-render-*`, `pmx-canvas-testing`,
-`playwright-cli`, etc.) as the work demands.
+(`control-session-orchestrator`, `web-artifacts-builder`, `json-render-*`,
+`pmx-canvas-testing`, `playwright-cli`, etc.) as the work demands.
 
 ## Documentation
 
@@ -156,7 +188,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)** — 42 tools, 8 resources, change
+- **[MCP reference](docs/mcp.md)** — 45 tools, 9 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
@@ -168,7 +200,7 @@ the agent can read `canvas://skills` and pull in companion skills
   one machine. No built-in multi-user auth or presence — collaboration means
   human ↔ agent on the same machine, plus any other browser tab/agent
   pointed at the same `localhost:4313`. To share across machines, commit
-  `.pmx-canvas/state.json`.
+  `.pmx-canvas/canvas.db`.
 - **What leaves your machine.** The core canvas runs entirely on
   `localhost`. Network egress only happens for explicit, opt-in flows:
   `webpage` nodes fetch the URL you give them; `mcp-app` /

package/dist/canvas/global.css

@@ -1107,10 +1107,13 @@ body,
   position: absolute;
   bottom: 0;
   right: 0;
-  width: 16px;
-  height: 16px;
+  width: 32px;
+  height: 32px;
+  background: rgba(0, 0, 0, 0.001);
   cursor: nwse-resize;
-  z-index: 2;
+  z-index: 30;
+  pointer-events: auto;
+  touch-action: none;
 }
 
 .canvas-node .node-resize-handle::after {
@@ -1130,6 +1133,36 @@ body,
   opacity: 1;
 }
 
+html.is-node-resizing,
+html.is-node-resizing * {
+  cursor: nwse-resize !important;
+}
+
+html.is-node-resizing .canvas-node {
+  transition: box-shadow 0.15s ease !important;
+}
+
+html.is-node-dragging .attention-field-layer {
+  visibility: hidden;
+}
+
+html.is-node-dragging,
+html.is-node-dragging * {
+  cursor: grabbing !important;
+  user-select: none !important;
+  -webkit-user-select: none !important;
+}
+
+html.is-node-dragging iframe,
+html.is-node-dragging .ext-app-preview-catcher {
+  pointer-events: none !important;
+}
+
+html.is-node-resizing iframe,
+html.is-node-resizing .ext-app-preview-catcher {
+  pointer-events: none !important;
+}
+
 /* Pinned node indicator */
 .canvas-node.pinned {
   border-style: dashed;