pmx-canvas 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -3,6 +3,53 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.12] - 2026-05-02
+
+MCP/canvas state-sharing pass on top of 0.1.11. The MCP server now
+attaches to an already-running canvas daemon for the current workspace
+instead of spinning up a parallel in-process state, so HTTP-created
+nodes and browser pins show up immediately in MCP responses and emit
+the matching resource notifications. The SDK's port binding is also
+hardened so explicit `port:` requests no longer silently land on a
+fallback port.
+
+### Added
+
+- **`startCanvasServer({ allowPortFallback: false })` and SDK port
+  determinism.** The HTTP server option lets callers opt out of the
+  fallback-port walk. The Bun SDK's `PmxCanvas.start()` and
+  `PmxCanvas.startAutomationWebView()` now pass this flag, so when an
+  SDK consumer says `createCanvas({ port: 4313 })` they either bind to
+  4313 or fail loudly — preventing two SDK instances or an SDK + a
+  daemon from racing onto silently different ports.
+- **`CanvasAccess` abstraction with local + remote backends.** A new
+  `src/mcp/canvas-access.ts` module defines the interface the MCP
+  server uses to talk to canvas state. `LocalCanvasAccess` wraps an
+  in-process `PmxCanvas` (legacy behavior); `RemoteCanvasAccess` talks
+  to an existing daemon over HTTP and consumes its SSE stream. The
+  factory probes for an existing canvas server in the workspace before
+  starting a new one.
+
+### Changed
+
+- **MCP server defers to an existing canvas daemon as the state
+  authority.** When `pmx-canvas --mcp` boots in a workspace that
+  already has a canvas server running on the agreed port, the MCP
+  process now reads and writes through that daemon's HTTP API instead
+  of starting its own canvas. Nodes created via the daemon's HTTP API
+  (or by a human in the browser) are visible to MCP queries
+  immediately, and SSE events from the daemon are translated into
+  MCP `notifications/resources/updated` calls for `canvas://layout`,
+  `canvas://summary`, `canvas://spatial-context`, `canvas://history`,
+  `canvas://code-graph`, and `canvas://pinned-context`.
+
+### Internal
+
+- Regression coverage for: `canvas_add_node` strict-size persistence
+  through MCP, an MCP session using an existing daemon as the state
+  authority for HTTP-created nodes, and HTTP node creation broadcasting
+  a live `canvas-layout-update` SSE event.
+
 ## [0.1.11] - 2026-05-02
 
 Agent ergonomics + chart polish on top of 0.1.10. Adds a `--strict-size`
@@ -316,6 +363,7 @@ 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.12]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.12
 [0.1.11]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.11
 [0.1.10]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.10
 [0.1.9]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.9

package/dist/types/mcp/canvas-access.d.ts

@@ -0,0 +1,87 @@
+import { type CanvasLayout, type CanvasNodeState, type CanvasSnapshot, type PmxCanvas } from '../server/index.js';
+type AddNodeInput = Parameters<PmxCanvas['addNode']>[0];
+type AddWebpageNodeInput = Parameters<PmxCanvas['addWebpageNode']>[0];
+type RefreshWebpageNodeResult = Awaited<ReturnType<PmxCanvas['refreshWebpageNode']>>;
+type OpenMcpAppInput = Parameters<PmxCanvas['openMcpApp']>[0];
+type OpenMcpAppResult = Awaited<ReturnType<PmxCanvas['openMcpApp']>>;
+type AddDiagramInput = Parameters<PmxCanvas['addDiagram']>[0];
+type AddJsonRenderNodeInput = Parameters<PmxCanvas['addJsonRenderNode']>[0];
+type AddJsonRenderNodeResult = ReturnType<PmxCanvas['addJsonRenderNode']>;
+type AddGraphNodeInput = Parameters<PmxCanvas['addGraphNode']>[0];
+type AddGraphNodeResult = ReturnType<PmxCanvas['addGraphNode']>;
+type UpdateNodePatch = Parameters<PmxCanvas['updateNode']>[1];
+type AddEdgeInput = Parameters<PmxCanvas['addEdge']>[0];
+type CreateGroupInput = Parameters<PmxCanvas['createGroup']>[0];
+type GroupNodesOptions = Parameters<PmxCanvas['groupNodes']>[2];
+type ArrangeLayout = Parameters<PmxCanvas['arrange']>[0];
+type FocusNodeResult = ReturnType<PmxCanvas['focusNode']>;
+type FitViewOptions = Parameters<PmxCanvas['fitView']>[0];
+type FitViewResult = ReturnType<PmxCanvas['fitView']>;
+type SearchResult = ReturnType<PmxCanvas['search']>;
+type UndoRedoResult = Awaited<ReturnType<PmxCanvas['undo']>>;
+type HistoryResult = ReturnType<PmxCanvas['getHistory']>;
+type SetContextPinsResult = ReturnType<PmxCanvas['setContextPins']>;
+type RunBatchInput = Parameters<PmxCanvas['runBatch']>[0];
+type RunBatchResult = Awaited<ReturnType<PmxCanvas['runBatch']>>;
+type SnapshotList = ReturnType<PmxCanvas['listSnapshots']>;
+type DeleteSnapshotResult = ReturnType<PmxCanvas['deleteSnapshot']>;
+type DiffSnapshotResult = ReturnType<PmxCanvas['diffSnapshot']>;
+type CodeGraphResult = ReturnType<PmxCanvas['getCodeGraph']>;
+type ValidationResult = ReturnType<PmxCanvas['validate']>;
+type WebArtifactInput = Parameters<PmxCanvas['buildWebArtifact']>[0];
+type WebArtifactResult = Awaited<ReturnType<PmxCanvas['buildWebArtifact']>>;
+type AutomationWebViewOptions = Parameters<PmxCanvas['startAutomationWebView']>[0];
+type AutomationWebViewStatus = Awaited<ReturnType<PmxCanvas['startAutomationWebView']>>;
+type AutomationEvaluateResult = Awaited<ReturnType<PmxCanvas['evaluateAutomationWebView']>>;
+type AutomationScreenshotOptions = Parameters<PmxCanvas['screenshotAutomationWebView']>[0];
+export interface CanvasAccess {
+    readonly port: number;
+    readonly remoteBaseUrl: string | null;
+    getLayout(): Promise<CanvasLayout>;
+    getNode(id: string): Promise<CanvasNodeState | undefined>;
+    addNode(input: AddNodeInput): Promise<string>;
+    addWebpageNode(input: AddWebpageNodeInput): Promise<Awaited<ReturnType<PmxCanvas['addWebpageNode']>>>;
+    refreshWebpageNode(id: string, url?: string): Promise<RefreshWebpageNodeResult>;
+    openMcpApp(input: OpenMcpAppInput): Promise<OpenMcpAppResult>;
+    addDiagram(input: AddDiagramInput): Promise<OpenMcpAppResult>;
+    addJsonRenderNode(input: AddJsonRenderNodeInput): Promise<AddJsonRenderNodeResult>;
+    addGraphNode(input: AddGraphNodeInput): Promise<AddGraphNodeResult>;
+    buildWebArtifact(input: WebArtifactInput): Promise<WebArtifactResult>;
+    updateNode(id: string, patch: UpdateNodePatch): Promise<void>;
+    removeNode(id: string): Promise<void>;
+    addEdge(input: AddEdgeInput): Promise<string>;
+    removeEdge(id: string): Promise<void>;
+    createGroup(input: CreateGroupInput): Promise<string>;
+    groupNodes(groupId: string, childIds: string[], options?: GroupNodesOptions): Promise<boolean>;
+    ungroupNodes(groupId: string): Promise<boolean>;
+    arrange(layout?: ArrangeLayout): Promise<void>;
+    focusNode(id: string, options?: {
+        noPan?: boolean;
+    }): Promise<FocusNodeResult>;
+    fitView(options?: FitViewOptions): Promise<FitViewResult>;
+    clear(): Promise<void>;
+    search(query: string): Promise<SearchResult>;
+    undo(): Promise<UndoRedoResult>;
+    redo(): Promise<UndoRedoResult>;
+    getHistory(): Promise<HistoryResult>;
+    setContextPins(nodeIds: string[], mode?: 'set' | 'add' | 'remove'): Promise<SetContextPinsResult>;
+    getPinnedNodeIds(): Promise<string[]>;
+    runBatch(operations: RunBatchInput): Promise<RunBatchResult>;
+    listSnapshots(): Promise<SnapshotList>;
+    saveSnapshot(name: string): Promise<CanvasSnapshot | null>;
+    restoreSnapshot(id: string): Promise<{
+        ok: boolean;
+    }>;
+    deleteSnapshot(id: string): Promise<DeleteSnapshotResult>;
+    diffSnapshot(idOrName: string): Promise<DiffSnapshotResult>;
+    getCodeGraph(): Promise<CodeGraphResult>;
+    validate(): Promise<ValidationResult>;
+    getAutomationWebViewStatus(): Promise<AutomationWebViewStatus>;
+    startAutomationWebView(options?: AutomationWebViewOptions): Promise<AutomationWebViewStatus>;
+    stopAutomationWebView(): Promise<boolean>;
+    evaluateAutomationWebView(expression: string): Promise<AutomationEvaluateResult>;
+    resizeAutomationWebView(width: number, height: number): Promise<AutomationWebViewStatus>;
+    screenshotAutomationWebView(options?: AutomationScreenshotOptions): Promise<Uint8Array>;
+}
+export declare function createCanvasAccess(): Promise<CanvasAccess>;
+export {};

package/dist/types/server/server.d.ts

@@ -96,6 +96,7 @@ export interface CanvasServerOptions {
     port?: number;
     workspaceRoot?: string;
     autoOpenBrowser?: boolean;
+    allowPortFallback?: boolean;
 }
 export declare function startCanvasServer(options?: CanvasServerOptions): string | null;
 export declare function stopCanvasServer(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "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",