pmx-canvas 0.11.0 → 0.12.1

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/references/installing-pmx-canvas.md

@@ -0,0 +1,301 @@
+# Installing PMX Canvas
+
+Use this reference when the `pmx-canvas` skill is installed but the `pmx-canvas` command is not available yet.
+
+## Prerequisites and version
+
+The examples pin **PMX Canvas 0.12.1**, which requires **Bun >=1.4.4** even when
+installed through npm: the CLI runs through Bun, not Node. Check `bun --version`
+first. If missing or older, follow the [Bun installation instructions](https://bun.sh/docs/installation)
+with the user's authorization. Ensure Bun is on the MCP host's PATH as well as the
+interactive shell's; use an absolute `bun`/`bunx` executable path if needed.
+
+Bun 1.4.4 fixes the Brotli decoder vulnerability CVE-2026-111497. Updating the
+PMX package does not update Bun; upgrade the runtime and restart existing PMX/MCP
+processes. Development and build tooling should use Node 24.22.1 or a newer patched
+release on a supported Node line.
+
+Install/configure only when requested. After an intentional runtime upgrade, sync the
+skill from that installed package and restart existing server/MCP processes as described
+in `SKILL.md`. Do not pair newer checkout guidance with an older runtime unknowingly.
+
+## Install from npm
+
+```bash
+npm install -g pmx-canvas@0.12.1
+pmx-canvas --version
+```
+
+Without a global install, use `bunx pmx-canvas@0.12.1` in place of `pmx-canvas` in
+the commands below. Do not use unpinned `bunx pmx-canvas` for a version-specific check.
+
+## Choose the workspace and target
+
+Select an existing absolute root and a dedicated free port. These shell examples use
+POSIX syntax; supply equivalent environment variables on other platforms.
+
+```bash
+export PMX_CANVAS_WORKSPACE_ROOT=/absolute/path/to/project
+export PMX_CANVAS_PORT=14313 # Example only: choose a free port for this workspace.
+unset PMX_CANVAS_URL # A stale URL overrides the environment's CLI port target.
+```
+
+Use **both root and port**. Root pinning alone does not align the CLI, MCP, and browser
+if a server falls back to another port. Without an explicit root, MCP may attach to a
+different workspace on the preferred port. `PMX_CANVAS_ALLOW_WORKSPACE_SPLIT=1` opts
+out of that heuristic but is not a substitute for checking the actual target.
+
+For server startup, precedence is `--port`, then `PMX_WEB_CANVAS_PORT`, then
+`PMX_CANVAS_PORT` (then `PORT` in Amp orbs), then the default 4313. For CLI queries and
+mutations, explicit `--server-url`/`--port` override environment targeting; otherwise
+`PMX_CANVAS_URL` wins over `PMX_CANVAS_PORT`. URL targeting does not set the bind port.
+
+## Start the server
+
+On an ordinary local machine:
+
+```bash
+pmx-canvas serve --daemon --no-open --port="$PMX_CANVAS_PORT" --wait-ms=20000
+```
+
+In a managed environment, use the host's supervised-service mechanism with foreground
+`pmx-canvas serve --no-open --port=<chosen-port>`, passing the selected environment.
+Do not daemonize inside a supervisor or rely on `nohup`, background shell jobs, or tmux
+to survive an orb restart. In an Amp orb, prefer declared services with
+`amp orb services ensure`; otherwise use `amp orb service start` with the foreground
+command. Use the host's authenticated portal/preview for remote viewing, not a raw
+loopback URL. Verify health below before opening the workbench or making writes.
+
+CLI query/mutation commands do not auto-start a server; `serve` or `--mcp` does.
+
+## From a local checkout (development)
+
+```bash
+git clone https://github.com/pskoett/pmx-canvas.git
+cd pmx-canvas
+bun install
+bun run build
+bun run src/cli/index.ts --version
+```
+
+This uses the checked-out source, not necessarily the published package. Follow
+that checkout's `package.json` Bun requirement and bundled skill. Set the same root/port
+environment above; substitute `bun run /absolute/path/to/pmx-canvas/src/cli/index.ts`
+for `pmx-canvas` in startup and verification commands. The target workspace can be
+different from the source checkout. Build the client before browser verification.
+
+## MCP Config
+
+For agents that support MCP, configure the pinned package as a stdio server. Replace
+the root and port with your selections; ensure the port is dedicated to this workspace.
+The empty URL overrides a stale inherited value (empty is treated as unset). If the host
+discards empty env values, remove `PMX_CANVAS_URL` from its launch environment instead.
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "bunx",
+      "args": ["pmx-canvas@0.12.1", "--mcp"],
+      "env": {
+        "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
+        "PMX_CANVAS_PORT": "14313",
+        "PMX_CANVAS_URL": ""
+      }
+    }
+  }
+}
+```
+
+If you are using a local checkout instead of the published package, point the command at the CLI entry:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "bun",
+      "args": ["run", "/absolute/path/to/pmx-canvas/src/cli/index.ts", "--mcp"],
+      "env": {
+        "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
+        "PMX_CANVAS_PORT": "14313",
+        "PMX_CANVAS_URL": ""
+      }
+    }
+  }
+}
+```
+
+Restart the host's MCP process after changing configuration. Inspect startup output for
+fallback ports; do not assume the configured port is the one the MCP server bound.
+
+## Amp: connect the agent separately from the portal
+
+PMX ships an opt-in directory plugin with board binding and receipt-based steering, or
+you can configure raw MCP for active polling. The portal is the human's browser UI;
+neither opening it nor configuring raw MCP installs the plugin. Choose one integration
+for the task rather than creating duplicate writers.
+
+### Amp plugin: bound threads
+
+When installation is requested, copy the complete installed package directory
+`node_modules/pmx-canvas/dist/amp-plugin/pmx-canvas` to the project's
+`.amp/plugins/pmx-canvas`. Inspect existing plugin files and preserve local changes;
+replacement needs owner approval. Reload Amp plugins and load the qualified
+`pmx-canvas:pmx-canvas` skill. Approve its workspace MCP command through the normal
+human trust flow, never by bypassing it. No global plugin installation is implied.
+
+Use `pmx_canvas_session { action: "open" }` to start/reconnect and verify the service,
+then `bind` with an existing explicit `boardId`. `status` reports the binding and
+shared active board; `unbind` removes only this thread's binding. Binding does not
+open a board, change sharing, or create an access-control boundary.
+
+Bound MCP tool calls route to that board with identity `amp:<thread-id>`, even when
+the human views another board or Home. Use `canvas_query` for context and full
+`canvas_node` reads for needed content. CLI calls and MCP resource reads are not
+intercepted. Do not navigate the shared workbench through bound calls, override the
+destination, or open the board to make a write work. A missing board or changed
+binding fails instead of silently targeting the visible board; a binding change
+during a turn requires a new turn.
+
+At turn start, return the supplied context token through
+`pmx_canvas_delivery { action: "receive", token }`. Reception records the delivered
+map, not full card reads, understanding or approval. For a steering token, receive it,
+read the relevant content, act, verify the result, and only then call
+`pmx_canvas_delivery { action: "acknowledge", token }`. Do not acknowledge failed or
+unverified work. Uncertain sends require human resolution, not blind retries or
+deleting the transport journal.
+
+Addressed steering can start an idle thread or queue into a busy turn only while
+the plugin executor is awake. It does not wake a sleeping orb or hold a keep-alive
+lease. A raw MCP polling test does not prove this native delivery path.
+
+**Context ranking** and **Jev advice** are separate opt-ins, both off by default.
+Their Amp commands require separate human confirmation for the current binding and
+disclose data sent to TypeSafe Jev and the invoking thread's inference billing.
+Ranking reorders optional summaries; advice suggests formats or review order without
+creating output or verifying work. One consent never enables the other. Rebinding
+does not carry either consent. Respect deterministic fallback and report it rather
+than retrying with another provider. See the
+[plugin contract](https://github.com/pskoett/pmx-canvas/blob/main/docs/amp-plugin.md)
+for request fields, retry identities and native acceptance limits.
+
+### Raw MCP: active polling
+
+Configure MCP inside the orb or runner where Amp executes, not only on the user's
+laptop. Merge this into that workspace's
+`.amp/settings.json`, preserving other settings (Amp does not use the generic `.mcp.json`):
+
+```json
+{
+  "amp.mcpServers": {
+    "canvas": {
+      "command": "bunx",
+      "args": ["pmx-canvas@0.12.1", "--mcp"],
+      "includeTools": ["canvas_*"],
+      "env": {
+        "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
+        "PMX_CANVAS_PORT": "14313",
+        "PMX_CANVAS_URL": "",
+        "PMX_CANVAS_AGENT_SOURCE": "amp"
+      }
+    }
+  }
+}
+```
+
+Replace root and port with the **existing portal service's actual workspace and local
+listening port**. A supervised service may use an assigned `PORT`, not 4313 or 14313;
+inspect its status/logs and `/health`. Do not put the public portal URL in the stdio
+command or copy another test run's absolute paths. Use an absolute executable path if
+the MCP process cannot find Bun. The `canvas_*` filter exposes the Canvas tool family.
+
+### Workspace trust is a human approval
+
+Run `amp mcp doctor` from this workspace to distinguish `awaiting approval` from a
+missing executable or connection failure. A new workspace MCP command requires the
+user to review and approve it. Give the user this command to run in that workspace's
+orb Terminal or runner terminal (replace `canvas` if the configured server name differs):
+
+```bash
+amp mcp approve canvas
+```
+
+The agent must not run this approval itself or move the command to global settings or
+`--mcp-config` to bypass workspace trust. Approval authorizes execution of this MCP
+command; it is not a new Canvas import consent or permission to mutate arbitrary boards.
+After approval, reload MCP connections (`reload_mcp` in Amp) and require `connected`.
+Discover `canvas` tools with `tool_search`; the full unfiltered 0.12.1 server has 25 tools,
+including `canvas_help`. If still absent, inspect the server status, command/PATH and target instead
+of reinstalling blindly. See [Amp MCP documentation](https://ampcode.com/docs/customize/mcp).
+
+### Verify native tools, then steering
+
+1. Check `/health` for the expected package version and canonical workspace. Through
+   Amp's discovered tools, read `canvas_board { action: "get" }` and
+   `canvas_query { action: "context" }`; verify the board matches the visible portal.
+   A CLI smoke check or SDK-spawned MCP client does not establish native Amp discovery.
+2. For a requested end-to-end check, use a disposable board. Pin a known card in the
+   portal and require a native context read to return that card as pinned. Use one
+   stable presence/steering identity (`amp` above, or a unique source per independent
+   agent); reuse any adapter-owned session instead of attaching a duplicate.
+3. Send a fresh browser message addressed to that identity. The running agent claims
+   it with `canvas_ax_delivery` using the same `consumer`, reads the relevant card,
+   signals intent, and performs the requested edit through native Canvas tools.
+4. Verify the visible result in the browser before marking the message delivered for
+   that consumer. A subsequent claim should omit it. Detach only test-owned sessions.
+
+This raw-MCP check proves an **active agent can poll and act**, not automatic wake-up
+of an idle Amp thread, background polling, or automatic agent launch for imports. An MCP connection
+does not install a steering pump. Only configure a pump/host integration when requested;
+its startup backlog rules are in the main skill. Tool discovery and resource reads also
+do not establish Amp support for native MCP Skills-extension discovery or activation.
+
+## Verify the actual target before writes
+
+For the local target selected above:
+
+```bash
+pmx-canvas --version
+curl --fail --silent --show-error "http://localhost:${PMX_CANVAS_PORT}/health"
+pmx-canvas serve status --port="$PMX_CANVAS_PORT"
+```
+
+Require healthy `ok`, the expected running `version`, and a **`workspace`** matching the
+intended canonical absolute root (resolve symlinks on both paths). Inspect persistence
+health too. `serve status` checks a local port, not an arbitrary `PMX_CANVAS_URL`.
+When deliberately targeting a URL or a fallback port, fetch `/health` there instead,
+then align CLI, MCP, and browser to it. Never print a credential-bearing URL.
+On mismatch, stop: leave the other server alone, choose a free port, and repeat.
+
+Only after confirming the target:
+
+```bash
+pmx-canvas layout
+pmx-canvas open
+```
+
+Inside an orb, open the registered portal rather than asking the user to open localhost.
+
+## Disposable smoke verification
+
+`smoke` creates/searches/removes a temporary node and can leave history/activity records.
+It reports the workspace but does **not** compare it with your intended root. Do not run
+it on a valuable board as an identity check. Use a new disposable workspace and its own
+free port, start it with the appropriate startup method above, and verify `/health` first:
+
+```bash
+export PMX_CANVAS_WORKSPACE_ROOT="$(mktemp -d)"
+export PMX_CANVAS_PORT=14314 # Choose another free port.
+unset PMX_CANVAS_URL
+# Start this workspace's server, then verify its actual health workspace/version.
+# Only after that verification succeeds:
+pmx-canvas smoke
+```
+
+Inspect the JSON report and exit status: health, MCP initialize, node lifecycle, and
+validation should pass; failures exit 1. Version skew is reported in details and is not
+necessarily a failing check. Smoke proves neither `tools/list` discovery nor browser
+rendering: verify those separately when testing the complete onboarding experience.
+Stop only the test server (service-manager stop, or `serve stop --port=<test-port>` for
+your local daemon) before removing its disposable directory. Never clear a user's board
+or stop an unrelated listener to make a smoke test pass.

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/references/tours-and-recording.md

@@ -0,0 +1,117 @@
+# Tours and recording
+
+Tours use the existing board cards as presentation content. Interactive presentation and
+deterministic capture share this one stop model; recording does not create a second deck.
+
+## Author a tour
+
+Persist a tour with `canvas_view { action: "set-tour", tour: { stops: [...] } }` and read it with
+`canvas_view { action: "get-tour" }`. A stop has exactly one target:
+
+```json
+{
+  "stops": [
+    { "target": { "nodeId": "overview-group" }, "duration": 1.5, "padding": 60 },
+    { "target": { "nodeId": "detail-note" }, "duration": 2, "easing": "ease-in-out", "pullback": 0.7 },
+    { "target": { "viewport": { "x": 80, "y": 100, "scale": 0.5 } }, "duration": 1 }
+  ]
+}
+```
+
+- `nodeId` may identify a card or group. Its persisted position and size determine the camera.
+- `rect` is a world-space box `{ x, y, width, height }` (top-left corner plus size).
+- An explicit viewport is `{ x, y, scale }`, with positive `scale`. Translation is screen-space:
+  `screen = world * scale + offset`.
+- `duration` is transition time in seconds (default 1; zero jumps). Valid values are 0–3600.
+- `padding` is screen pixels around a node or rect target (default 40).
+- `easing` is `linear`, `ease-in-out` (default), or `ease-out`.
+- `pullback` is 0–4 (default 0). It zooms out during the move without changing either endpoint.
+- A tour contains at most 1000 stops.
+
+Open `/workbench?present=1` for chrome-free viewing. Right, Down, or Space advances; Left or Up
+goes back; Escape or **Exit presentation** exits. Right-drag pans and interrupts an ongoing
+transition without editing cards. Stops do not auto-advance. A missing node target reports an
+error and may be skipped. Camera rendering and free pan are viewer-local, but human Back/Next
+and arrow keys advance the target board's shared cursor for its presenting viewers; Exit leaves
+presentation for those viewers. `present: false` does not isolate viewers of the same board.
+Deterministic capture uses its own viewer and ignores live navigation. Recording hides the exit control.
+
+Tours are board-scoped, persist with that board and its snapshots, participate in undo, and clear
+with the board. Setting `tour: null` resets to a derived tour: groups ordered by y, then x, then
+ID. A saved `{ "stops": [] }` intentionally has no stops; it does not enable group derivation.
+Preserve the tour of each board when working across boards and target the intended board before
+setting or reading it.
+
+## Drive a tour
+
+The server keeps board-local in-memory tour cursors, not one workspace-wide cursor.
+`canvas_view { action: "tour-go", stop: 0 }` starts presenting in workbenches showing the
+target board; `step: "next" | "previous"` moves relative to that board's cursor
+(a human's arrow keys move the same cursor) and clamps at the ends. Pass
+`present: false` to move only viewers already presenting. `canvas_view { action: "tour-exit" }`
+exits presentation on the target board. `get-tour` reports `position` (the current stop, or null).
+Bound background calls do not navigate the human's visible board. Cursors are not durable:
+tour edits or activation changes can invalidate them, so read `get-tour` rather than assuming
+a previous stop survives reopening a board.
+
+`canvas_view { action: "move", nodeId | rect | viewport, duration, easing, padding, pullback }`
+eases the camera without a tour. Outside a presentation the end camera becomes the board
+viewport. Tour steps and moves never enter undo history, never count as agent writes, and are
+allowed under a scope fence. Viewers with reduced motion jump instead of animating; a
+deterministic capture ignores both.
+
+If another viewer's camera must stay unchanged, do not send `tour-go`, `tour-exit` or `move`,
+or use the human shared navigation controls. Author stops and capture them in the separate
+recording viewer instead. Verify isolation with another viewer already presenting, not only
+an ordinary canvas tab.
+
+### Optional presenter ordering fence
+
+`tour-go` and `tour-exit` accept `presenter: { clientId, intent, catalogEpoch, boardGeneration }`.
+Use a distinct `clientId` per document, an increasing positive safe-integer `intent` per gesture,
+and the actual server activation's epoch and nonnegative safe-integer generation. Ordinary
+agent calls may omit this object. It orders requests; it is not authorization or viewer isolation.
+
+A stale activation, duplicate/older intent, or presenter-bearing call on a background board
+returns `{ ok: true, superseded: true }` with no navigation event or cursor change.
+Ordinary unfenced background calls still target their own board, not the visible one.
+Do not claim navigation from `ok: true` alone. Applied results
+and events carry `catalogEpoch`, `boardGeneration` and `sequence`; presenter-aware clients use
+these to reject stale acknowledgements and events. A structurally valid newer intent is claimed
+before resolving the stop, so even a missing newer stop supersedes older requests.
+
+This is latest-intent-wins, not FIFO: reversed relative Next requests can coalesce. Separate
+documents remain independent, and reload does not cancel an old document's pending request.
+An activation retains at most 4096 document IDs; a new ID beyond that returns 409 rather than
+evicting an ordering record. Switching boards resets the capacity but old activation stamps stay stale.
+The SDK accepts `goToTourStop(step, { presenter })` and `exitTour(presenter)`; fenced go can return
+`{ superseded: true }`, while exit returns void. Do not infer applied exit from that void return.
+
+## Capture prerequisites and behavior
+
+Start and verify the matching PMX daemon first: its `/health` workspace and version must match the
+installation and workspace used by the CLI/MCP host. Capture is a local CLI/file operation. It
+requires Bun with WebView support and Chrome (or `--chrome-path`); MP4 encoding additionally
+requires ffmpeg. Recording starts a separate Chrome session; it does not capture the native host's
+Browser pane. Use a new output path because existing output and frame paths are refused.
+
+Capture the saved or derived tour:
+
+```bash
+pmx-canvas record --mode deterministic --present --fps 30 --resolution 1920x1080 --output tour.mp4
+```
+
+Use `--tour-file tour.json` in deterministic mode to try the same model without changing the
+board. Resolution defaults to 1280x720 and FPS to 30 (valid 1–120). Deterministic mode resolves
+target geometry once and emits `max(1, ceil(duration * fps))` frames per stop, including each
+endpoint. Duplicate a stop to hold it. It makes camera timing deterministic, not iframe animation,
+late fonts/network assets, or concurrent board edits.
+
+Realtime mode instead needs one stopping rule: `--duration SECONDS` or `--stop-on-signal`. It
+samples the live board and repeats frames when capture is slow to preserve wall-clock duration.
+Capture has no audio and does not move other viewers' cameras or replace an existing automation
+session.
+
+An `.mp4` output uses ffmpeg/H.264. Frames and `recording.json` remain in `<output>.frames`; if
+ffmpeg is unavailable, the command reports and returns the PNG sequence directory. Any other
+output path is itself a PNG sequence directory. Encoding failures retain the frames and fail.