pmx-canvas 0.9.3 → 0.10.0

package/docs/plans/plan-019-post-0.9-roadmap.md

@@ -1,9 +1,9 @@
 # Plan 019: After 0.9.0
 
-**Status (2026-10-24):** 0.9.0–0.9.2 are released. The maintainer authorized review,
-testing and release of the patch-only 0.9.3 cleanup after the prerequisite fixes reached
-`origin/main` at `bed57fe9a4b79bd54f8b5ee51cefd65fec3dbe1a`. The SDK tour return shape
-stays unchanged. MCP hardening and SDK tour result parity move to 0.10 on SDK v1.
+**Status (2026-10-24):** 0.9.3 is released to npm and GitHub, with fresh registry smoke
+passing. Step 2, MCP hardening and SDK tour result parity on SDK v1, is implemented
+and pushed with the Settings tooltip fix, operation help and schema-size reduction.
+The maintainer authorized review, testing and release of 0.10.0; release gates are in progress.
 Later version numbers are proposals, not publication approval; every release must pass
 the [release gates](../RELEASE.md).
 **Sources:** [product vision](../product-vision-2026-09.md) (moves and the 2026-10-19 sequence),
@@ -23,7 +23,7 @@ measured; the maintainer carries that risk rather than reinstating an earlier ga
 | Step | Proposed version | Scope | Vision | Size |
 |---|---|---|---|---|
 | 1 | 0.9.3 | Cleanup: tour debt, large-board costs, bounded due evaluator, MCP reconnect, lint | 12, 1 | S–M |
-| 2 | 0.10 | MCP hardening: contracts, annotations, cancellation, resource subscriptions | 6a, 1 | M |
+| 2 | 0.10 | MCP hardening, operation help and bounded discovery-schema reduction | 6a, 1 | M |
 | 3 | 0.11 | One frame host, portal-layer mount, Wave-0 design pass | 5, 9 | M–L |
 | 4 | 0.12 | Wave 5: agent output as nodes, make/inline board, group drill-in, relations sketch parity | 3, 0 | L |
 | 5 | later | Trust (M half), journal, concurrent boards, binary | 7, 4, 8 | L–XL |
@@ -125,6 +125,121 @@ lists the exact locations. These remain outside the narrow behavioral fixes:
 [Vision move 6a](../product-vision-2026-09.md#6a-make-the-tool-surface-cheap-s--staged-follow-up)
 and move 1's context delivery, on the current SDK v1.
 
+**Local implementation checkpoint (2026-10-24):**
+- All 24 tools advertise output schemas and explicit effect hints. Registry results use
+  `{ result: { operation, outcome, data } }`; handwritten interaction, activity and screenshot
+  tools retain their direct objects. Existing model-facing text/projections stay unchanged.
+  Schemas distinguish batch success, empty failure and retained partial outcomes.
+- Cancellation reaches AX waits and webpage I/O through local and HTTP invokers. Batches
+  retain completed receipts and stop before subsequent operations. Progress is opt-in through
+  MCP tokens and HTTP NDJSON. External runtime/build calls and local WebView captures remain
+  noninterruptible mid-call. Disconnects may lose the response, never undo completed writes.
+- Subscriptions belong to each connection, include exact parameterized URIs, and dispose
+  on unsubscribe/close. Local state and workbench events cover library-only changes as well
+  as active nodes; remote SSE reconnects invalidate subscribed resources. Notifications never
+  record reads or advance cursors. A library-only-change regression failed before integration
+  and passes with the shared event source.
+- SDK `getTour()` now returns `{ tour, derived, position }`; `.tour.stops` is documented as
+  the minor-version breaking change. No SDK/dependency upgrade or frame-host work.
+
+**Approved follow-up, 2026-10-24:** `canvas_help { op }` derives one operation's
+public arguments, required fields, routing selectors and guidance from the registry.
+Omitting `op` lists MCP registry names; internal/human-only and non-registry tools are
+excluded. Metadata reads neither boot a canvas nor record content delivery. The catalog
+now has 25 tools. Conditional handler validation still applies; no lazy host discovery
+or smaller input schemas are claimed.
+
+Equivalent success schemas shared by identity are grouped within each tool. Distinct
+payload contracts, error branches and batch partial receipts remain unchanged. Two
+real stdio measurements with `bun run scripts/measure-mcp-catalog.ts` were byte-identical:
+the previous 24-tool candidate's 144,680 UTF-8 JSON bytes become 137,381 for the same
+tools (7,299 fewer, 5.05%). Existing output schemas drop from 77,105 to 69,806 bytes.
+Adding help costs 1,156 catalog bytes including its separator: 138,537 bytes total,
+6,143 fewer than the previous candidate (4.25%). Input-schema byte counts are unchanged.
+This remains larger than published 0.9.3's 65,219 bytes. Bytes are not tokens, latency
+or measured agent effectiveness. `session.start` and composite-input redesign remain deferred.
+
+**Follow-up verification:** build, typecheck and `bun run test` pass (1,546 tests).
+Real SDK stdio checks enumerate help for every exposed registry operation, validate
+required fields, aliases and gate selectors, and create/remove a card using returned
+arguments. Schema controls reject mismatched operations, malformed receipts and extra
+envelope fields while accepting extensible payloads. Lint passes with 55 warnings and
+12 infos. The first combined run caught a second frozen tool list still expecting 24;
+that assertion now includes help. Test-fixture/typecheck failures were corrected, with
+first-failure logs retained.
+
+**Full candidate rerun requested by the maintainer:** `bun run test:coverage` passes
+1,546 tests (67.27% lines, 73.62% functions, above the 60%/64% floors);
+`bun run test:client` passes 332; `xvfb-run -a bash scripts/run-playwright.sh --headed`
+passes all 333 desktop and 600/1024/1920 reference cases. Headed `test:e2e-cli`,
+`release:smoke`, `pack:dry-run`, build, typecheck, lint and generated-catalog mirror
+checks pass. A fresh packed MCP consumer discovers 25 tools, reads help without
+creating state, and validates add/get results. Its allowed dependency versions
+(SDK 1.32.2, Zod 4.6.7 versus checkout 1.28.0/4.3.6) encode nullable primitive schemas
+as type arrays instead of `anyOf`. The initial byte-identity assertion failed;
+comparison passes when only that equivalent encoding is normalized. No dependency changed.
+
+The live portal serves the exact rebuilt bundle. Real stdio help-guided calls and
+headed browser checks pass human pin → notification → explicit read → rendered edit,
+unsubscribe, numeric progress tokens, cancelled approval waits, partial batch receipts
+and refresh persistence. Both minimap toggles leave no tooltip and preserve Settings
+focus. The first recording encoder fell behind; a later recording with the large suite
+finished and a smaller viewport succeeded and was inspected frame by frame.
+Native Amp/Copilot acceptance, Windows/macOS and remote/native reconnect remain unverified.
+
+**Initial hardening verification:** build and typecheck pass; `bun run test` passes 1,544 tests and
+`bun run test:client` passes 332. `xvfb-run -a bash scripts/run-playwright.sh --headed`
+passes 333 cases; three pin/viewport/polling controls also pass after the final local
+subscription event hook. `bun run release:smoke` passes on a disposable packed install,
+not a registry publication. Lint passes with the same 55 warnings and 12 infos; generated
+tool catalogs match. Real stdio tests cover local and daemon-attached progress/cancellation
+and resource isolation. Initial test typing/SDK error-envelope failures and the red
+library-notification regression were corrected; this is not a first-run-green claim.
+Native 0.10 host acceptance, Windows/macOS and remote/native reconnect remain unverified.
+Bounded simplify/harden review found no further blockers and made no additional changes.
+
+**Independent baseline evidence:** the
+[0.9.3 test thread](https://ampcode.com/threads/T-01a048cf-adb3-71bd-a7c6-472053b691d1)
+reports no new confirmed functional defect after reruns, including installed SDK direct-tour
+compatibility and native Amp pin/read/edit/ack acceptance. It does not establish 0.10 MCP
+structured-output, cancellation or subscription conformance. Its low-severity KaTeX advisory,
+unresolved first-run coverage timeout and remote/native reconnect gap remain separate from
+this candidate; no dependency or reconnect fix is claimed here.
+
+**Discovery cost:** `bun run scripts/measure-mcp-catalog.ts` measures UTF-8 bytes of the
+real SDK client's `tools/list` JSON in a disposable stdio workspace, without canvas reads.
+The 0.9.3 baseline is 65,219 bytes; the initial hardening candidate was 144,680 bytes, both 24 tools.
+Output schemas contributed 77,105 bytes before the follow-up above. This is an increase in discovery overhead, not a
+claim of cheaper prompts or a token estimate. Existing result text is unchanged; structured
+results duplicate that projection for machine consumers. Host-specific prompt costs are unmeasured.
+
+| Tool | 0.9.3 bytes | Initial hardening bytes |
+|---|---:|---:|
+| `canvas_pin_nodes` | 782 | 2227 |
+| `canvas_invoke_command` | 804 | 2312 |
+| `canvas_batch` | 1367 | 5184 |
+| `canvas_import` | 1152 | 4251 |
+| `canvas_snapshot` | 2238 | 6365 |
+| `canvas_board` | 5859 | 14803 |
+| `canvas_node` | 8184 | 13485 |
+| `canvas_render` | 6321 | 11165 |
+| `canvas_edge` | 2186 | 4423 |
+| `canvas_group` | 1953 | 4532 |
+| `canvas_history` | 494 | 2430 |
+| `canvas_view` | 4341 | 12821 |
+| `canvas_query` | 2476 | 7000 |
+| `canvas_app` | 4729 | 7496 |
+| `canvas_webview` | 1810 | 4834 |
+| `canvas_ax_state` | 4462 | 7652 |
+| `canvas_ax_work` | 2074 | 4527 |
+| `canvas_ax_gate` | 2417 | 8285 |
+| `canvas_ax_timeline` | 2637 | 6135 |
+| `canvas_ax_delivery` | 1366 | 3284 |
+| `canvas_intent` | 3127 | 5453 |
+| `canvas_ax_interaction` | 1460 | 1969 |
+| `canvas_ingest_activity` | 2341 | 2872 |
+| `canvas_screenshot` | 604 | 1140 |
+
 1. Remeasure `tools/list` size per tool before any schema change.
 2. `outputSchema` + `structuredContent` for stable results (IDs, revisions, mutation
    outcomes); compact model-facing content; UI-only payloads in `_meta` where supported.
@@ -137,7 +252,9 @@ and move 1's context delivery, on the current SDK v1.
 6. Align SDK tour reads with HTTP/MCP `{ tour, derived, position }`; document the breaking
    change from `.stops` to `.tour.stops` at this minor-version boundary.
 
-Candidates, not automatic scope: `canvas_help { op }`, `session.start`, per-action schemas.
+7. Approved follow-up: `canvas_help { op }` and bounded output-schema deduplication, as above.
+
+Candidates, not automatic scope: `session.start`, composite-input redesign.
 
 **Done when**
 - Representative read and mutation results validate against their advertised schemas.

package/docs/sdk.md

@@ -38,8 +38,11 @@ records retain their reviewed revision, and legacy unversioned evidence remains
 
 ## Board tours
 
-`canvas.getTour()` returns the tour directly. Read stops from `canvas.getTour().stops`.
-When no tour is saved, stops come from group reading order.
+`canvas.getTour()` returns `{ tour, derived, position }`, matching HTTP and MCP.
+Read stops from `canvas.getTour().tour.stops`. `derived` is true when stops come
+from group reading order rather than a saved tour. `position` is the current
+stop index, or null outside a tour.
+This is a breaking change in 0.10: replace `.getTour().stops` with `.getTour().tour.stops`.
 `canvas.setTour(tourOrNull)` saves the tour or resets it to derived group order.
 See the [tour contract](http-api.md#board-tours) for navigation and camera moves.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/plugins/pmx-canvas/com.github.copilot/extensions/pmx-canvas/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.9.3"
+  "version": "0.10.0"
 }

package/plugins/pmx-canvas/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pmx-canvas",
   "description": "PMX Canvas spatial workbench and MCP tools, with a native canvas panel in the GitHub Copilot app.",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "author": {
     "name": "pskoett",
     "url": "https://github.com/pskoett"

package/plugins/pmx-canvas/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.9.3"
+  "version": "0.10.0"
 }