pmx-canvas 0.3.3 → 0.4.0

package/src/server/operations/ops/snapshots.ts

@@ -70,7 +70,7 @@ const snapshotListOperation = defineOperation<z.infer<typeof snapshotListSchema>
   mcp: {
     toolName: 'canvas_list_snapshots',
     description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). List saved canvas snapshots with IDs, names, timestamps, and node/edge counts. Defaults to the 20 newest snapshots; pass all=true to return every snapshot.',
+      'List saved canvas snapshots with IDs, names, timestamps, and node/edge counts. Defaults to the 20 newest snapshots; pass all=true to return every snapshot.',
     extraShape: {
       limit: z.number().optional().describe('Maximum snapshots to return (default: 20)'),
       query: z.string().optional().describe('Optional case-insensitive ID/name filter'),
@@ -117,7 +117,7 @@ const snapshotSaveOperation = defineOperation<z.infer<typeof snapshotSaveSchema>
   mcp: {
     toolName: 'canvas_snapshot',
     description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Save the current canvas state as a named snapshot. Snapshots persist to disk and can be restored later.',
+      'Save the current canvas state as a named snapshot. Snapshots persist to disk and can be restored later.',
     extraShape: {
       name: z.string().describe('Name for this snapshot (e.g., "before refactor", "investigation v2")'),
     },
@@ -155,7 +155,7 @@ const snapshotGcOperation = defineOperation<z.infer<typeof snapshotGcSchema>, Re
   mcp: {
     toolName: 'canvas_gc_snapshots',
     description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Delete old saved canvas snapshots, keeping the newest N snapshots. Use dryRun=true to preview deletions.',
+      'Delete old saved canvas snapshots, keeping the newest N snapshots. Use dryRun=true to preview deletions.',
     extraShape: {
       keep: z.number().optional().describe('Number of newest snapshots to keep (default: 20)'),
       dryRun: z.boolean().optional().describe('Preview deletions without removing snapshot files'),
@@ -206,7 +206,7 @@ const snapshotDiffOperation = defineOperation<z.infer<typeof snapshotDiffSchema>
   mcp: {
     toolName: 'canvas_diff',
     description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Compare the current canvas state against a saved snapshot. Shows added/removed/modified nodes and edges. Pass either a snapshot name or ID.',
+      'Compare the current canvas state against a saved snapshot. Shows added/removed/modified nodes and edges. Pass either a snapshot name or ID.',
     extraShape: {
       snapshot: z.string().describe('Snapshot name or ID to compare against'),
     },
@@ -291,7 +291,7 @@ const snapshotRestoreOperation = defineOperation<z.infer<typeof snapshotRestoreS
   mcp: {
     toolName: 'canvas_restore',
     description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Restore the canvas to a previously saved snapshot. Use canvas_snapshot to save first. Pass either the snapshot ID or name to restore.',
+      'Restore the canvas to a previously saved snapshot. Use canvas_snapshot to save first. Pass either the snapshot ID or name to restore.',
     extraShape: {
       id: z.string().describe('Snapshot ID or name to restore (from canvas_snapshot or snapshot list)'),
     },
@@ -346,8 +346,7 @@ const snapshotDeleteOperation = defineOperation<z.infer<typeof snapshotDeleteSch
   },
   mcp: {
     toolName: 'canvas_delete_snapshot',
-    description:
-      'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Delete a saved snapshot by ID.',
+    description: 'Delete a saved snapshot by ID.',
     extraShape: {
       id: z.string().describe('Snapshot ID to delete'),
     },

package/src/server/operations/registry.ts

@@ -39,7 +39,10 @@ export function setOperationEventEmitter(emitter: OperationEventEmitter | null):
   operationEventEmitter = emitter;
 }
 
-// Depth-counted emit suppression (mirrors canvasState._suppressRecordingDepth).
+// Depth-counted EMIT suppression (same pattern as, but deliberately distinct
+// state from, canvasState's recording suppression: batch suppresses SSE emits
+// while sub-ops still record history; undo/redo suppresses recording while
+// still emitting SSE — merging the two counters would break one or the other).
 // While > 0, emitOperationEvent is a no-op so a meta-op (canvas.batch) can run
 // many sub-ops without producing per-entry SSE frames, then emit ONE final
 // layout frame itself. Both the `mutates` auto-emit and `ctx.emit` route through

package/src/server/server.ts

@@ -24,6 +24,7 @@
  * - GET  /api/canvas/json-render/view?nodeId=... -> local json-render viewer
  * - POST /api/canvas/web-artifact -> build bundled HTML artifact + optional canvas node
  * - GET  /api/workbench/events   -> SSE event stream
+ * - GET  /api/workbench/poll     -> proxy-safe polling transport (same events, JSON)
  * - GET  /api/workbench/state    -> workbench state snapshot
  * - POST /api/workbench/intent   -> workbench intents
  * - GET  /api/workbench/webview  -> Bun.WebView automation status
@@ -61,6 +62,7 @@ import { resolveNodeAxCapabilities } from './ax-interaction.js';
 import { normalizeCanvasTheme, type CanvasTheme } from './canvas-db.js';
 import { validateLocalImageFile } from './image-source.js';
 import {
+  cancelCodeGraphRecompute,
   primeCanvasRuntimeBackends,
   setCanvasLayoutUpdateEmitter,
   syncCanvasRuntimeBackends,
@@ -709,7 +711,24 @@ function toSseFrame(event: string, payload: PrimaryWorkbenchEventPayload): Uint8
   return textEncoder.encode(`${lines.join('\n')}\n`);
 }
 
+// ── Workbench event ring (proxy-safe polling transport) ─────────
+// Buffering proxies (e.g. the Amp orb portal) hold a long-lived SSE response
+// open and never flush it to the browser, so an EventSource client behind one
+// receives nothing and the canvas never boots. Every broadcast event is also
+// recorded here with a monotonic seq; GET /api/workbench/poll replays them as
+// a normal, immediately-closed JSON response that any proxy delivers. Bounded:
+// a client whose `since` fell off the ring gets a fresh connect snapshot,
+// which fully rebuilds client state (same events an SSE connect sends).
+const WORKBENCH_EVENT_RING_MAX = 500;
+let workbenchEventSeq = 0;
+const workbenchEventRing: Array<{ seq: number; event: string; payload: PrimaryWorkbenchEventPayload }> = [];
+
 function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPayload): void {
+  workbenchEventSeq += 1;
+  workbenchEventRing.push({ seq: workbenchEventSeq, event, payload });
+  if (workbenchEventRing.length > WORKBENCH_EVENT_RING_MAX) {
+    workbenchEventRing.splice(0, workbenchEventRing.length - WORKBENCH_EVENT_RING_MAX);
+  }
   const frame = toSseFrame(event, payload);
   for (const [subscriberId, controller] of workbenchSubscribers.entries()) {
     try {
@@ -1371,14 +1390,19 @@ function responseJson(data: unknown, status = 200): Response {
   });
 }
 
+// v0.4.0 (M4): every hand-written error response is a JSON envelope
+// ({ ok: false, error }, same status codes) matching the registry dispatcher —
+// consumers no longer need to branch on text/plain vs JSON error bodies.
 function responseText(text: string, status = 400): Response {
-  return new Response(text, {
-    status,
-    headers: {
-      'Content-Type': 'text/plain; charset=utf-8',
-      'Cache-Control': 'no-store',
+  return Response.json(
+    { ok: false, error: text },
+    {
+      status,
+      headers: {
+        'Cache-Control': 'no-store',
+      },
     },
-  });
+  );
 }
 
 function handleArtifactView(url: URL): Response {
@@ -1691,15 +1715,134 @@ async function handleWorkbenchIntent(req: Request): Promise<Response> {
   return responseJson({ ok: true, intent });
 }
 
-function handleWorkbenchEvents(req: Request): Response {
-  const reqUrl = new URL(req.url);
-  const requestedSessionId = reqUrl.searchParams.get('session')?.trim() ?? '';
+/**
+ * The connect snapshot: the ordered event list that fully rebuilds a client's
+ * state. Single source for BOTH transports — the SSE stream enqueues these
+ * frames on connect, and /api/workbench/poll returns them as JSON when a
+ * poller has no usable `since` (fresh client, server restart, or ring
+ * eviction). Adding a new connect-time event here reaches both paths.
+ */
+function buildWorkbenchConnectSnapshot(
+  requestedSessionId: string,
+): Array<{ event: string; payload: Record<string, unknown> }> {
   const continuity =
     requestedSessionId.length === 0
       ? 'fresh'
       : requestedSessionId === primaryWorkbenchSessionId
         ? 'resumed'
         : 'rotated';
+  const events: Array<{ event: string; payload: Record<string, unknown> }> = [];
+  events.push({
+    event: 'connected',
+    payload: {
+      sessionId: primaryWorkbenchSessionId,
+      requestedSessionId: requestedSessionId || null,
+      continuity,
+      path: primaryWorkbenchPath,
+      theme: canvasState.theme,
+      timestamp: new Date().toISOString(),
+    },
+  });
+  if (primaryWorkbenchPath) {
+    events.push({
+      event: 'workbench-open',
+      payload: {
+        sessionId: primaryWorkbenchSessionId,
+        path: primaryWorkbenchPath,
+        title: basename(primaryWorkbenchPath),
+        source: 'snapshot',
+        updatedAt: new Date().toISOString(),
+      },
+    });
+  }
+  if (lastWorkbenchContextCardsEnvelope) {
+    events.push({
+      event: 'context-cards',
+      payload: {
+        ...lastWorkbenchContextCardsEnvelope,
+        sessionId: primaryWorkbenchSessionId,
+        timestamp: new Date().toISOString(),
+      },
+    });
+  }
+  events.push({
+    event: 'mcp-app-host-snapshot',
+    payload: {
+      reason: 'connect-snapshot',
+      ...getMcpAppHostSnapshot(),
+      timestamp: new Date().toISOString(),
+    },
+  });
+  events.push({
+    event: 'canvas-layout-update',
+    payload: {
+      layout: canvasState.getLayout(),
+      sessionId: primaryWorkbenchSessionId,
+      timestamp: new Date().toISOString(),
+    },
+  });
+  events.push({
+    event: 'context-pins-changed',
+    payload: {
+      count: canvasState.contextPinnedNodeIds.size,
+      nodeIds: Array.from(canvasState.contextPinnedNodeIds),
+      sessionId: primaryWorkbenchSessionId,
+      timestamp: new Date().toISOString(),
+    },
+  });
+  for (const intent of intentRegistry.list()) {
+    events.push({
+      event: 'ax-intent',
+      payload: {
+        intent,
+        reason: 'connect-snapshot',
+        sessionId: primaryWorkbenchSessionId,
+        timestamp: new Date().toISOString(),
+      },
+    });
+  }
+  return events;
+}
+
+/**
+ * Proxy-safe transport (Amp orb portals and any proxy that buffers streaming
+ * responses): returns the buffered events after `since` — or the full connect
+ * snapshot when `since` is absent, from a previous server run, or already
+ * evicted from the ring — as a normal JSON response that closes immediately.
+ * The client polls every couple of seconds; each response flushes through any
+ * proxy. `seq` is the cursor for the next poll.
+ */
+function handleWorkbenchPoll(url: URL): Response {
+  rotatePrimaryWorkbenchSessionIfNeeded();
+  const requestedSessionId = url.searchParams.get('session')?.trim() ?? '';
+  const sinceRaw = url.searchParams.get('since');
+  const since = sinceRaw === null ? Number.NaN : Number(sinceRaw);
+  const ringHeadSeq =
+    workbenchEventRing.length > 0 ? (workbenchEventRing[0] as { seq: number }).seq : workbenchEventSeq + 1;
+  const usableSince = Number.isInteger(since) && since >= 0 && since <= workbenchEventSeq && since + 1 >= ringHeadSeq;
+  if (!usableSince) {
+    return responseJson({
+      ok: true,
+      transport: 'poll',
+      snapshot: true,
+      seq: workbenchEventSeq,
+      sessionId: primaryWorkbenchSessionId,
+      events: buildWorkbenchConnectSnapshot(requestedSessionId),
+    });
+  }
+  return responseJson({
+    ok: true,
+    transport: 'poll',
+    snapshot: false,
+    seq: workbenchEventSeq,
+    sessionId: primaryWorkbenchSessionId,
+    events: workbenchEventRing.filter((entry) => entry.seq > since),
+  });
+}
+
+function handleWorkbenchEvents(req: Request): Response {
+  const reqUrl = new URL(req.url);
+  const requestedSessionId = reqUrl.searchParams.get('session')?.trim() ?? '';
   const subscriberId = nextWorkbenchSubscriberId++;
   let pingTimer: ReturnType<typeof setInterval> | null = null;
 
@@ -1707,68 +1850,8 @@ function handleWorkbenchEvents(req: Request): Response {
     start(controller) {
       workbenchSubscribers.set(subscriberId, controller);
       syncCanvasBrowserOpenedFromSubscribers();
-      controller.enqueue(
-        toSseFrame('connected', {
-          sessionId: primaryWorkbenchSessionId,
-          requestedSessionId: requestedSessionId || null,
-          continuity,
-          path: primaryWorkbenchPath,
-          theme: canvasState.theme,
-          timestamp: new Date().toISOString(),
-        }),
-      );
-      if (primaryWorkbenchPath) {
-        controller.enqueue(
-          toSseFrame('workbench-open', {
-            sessionId: primaryWorkbenchSessionId,
-            path: primaryWorkbenchPath,
-            title: basename(primaryWorkbenchPath),
-            source: 'snapshot',
-            updatedAt: new Date().toISOString(),
-          }),
-        );
-      }
-      if (lastWorkbenchContextCardsEnvelope) {
-        controller.enqueue(
-          toSseFrame('context-cards', {
-            ...lastWorkbenchContextCardsEnvelope,
-            sessionId: primaryWorkbenchSessionId,
-            timestamp: new Date().toISOString(),
-          }),
-        );
-      }
-      controller.enqueue(
-        toSseFrame('mcp-app-host-snapshot', {
-          reason: 'connect-snapshot',
-          ...getMcpAppHostSnapshot(),
-          timestamp: new Date().toISOString(),
-        }),
-      );
-      const layout = canvasState.getLayout();
-      controller.enqueue(
-        toSseFrame('canvas-layout-update', {
-          layout,
-          sessionId: primaryWorkbenchSessionId,
-          timestamp: new Date().toISOString(),
-        }),
-      );
-      controller.enqueue(
-        toSseFrame('context-pins-changed', {
-          count: canvasState.contextPinnedNodeIds.size,
-          nodeIds: Array.from(canvasState.contextPinnedNodeIds),
-          sessionId: primaryWorkbenchSessionId,
-          timestamp: new Date().toISOString(),
-        }),
-      );
-      for (const intent of intentRegistry.list()) {
-        controller.enqueue(
-          toSseFrame('ax-intent', {
-            intent,
-            reason: 'connect-snapshot',
-            sessionId: primaryWorkbenchSessionId,
-            timestamp: new Date().toISOString(),
-          }),
-        );
+      for (const { event, payload } of buildWorkbenchConnectSnapshot(requestedSessionId)) {
+        controller.enqueue(toSseFrame(event, payload));
       }
       pingTimer = setInterval(() => {
         try {
@@ -2854,7 +2937,10 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
 
   rotatePrimaryWorkbenchSessionIfNeeded();
 
-  const preferredPort = options.port ?? Number(process.env.PMX_WEB_CANVAS_PORT ?? DEFAULT_PORT);
+  // M11: PMX_WEB_CANVAS_PORT (server-specific) wins, then PMX_CANVAS_PORT — so
+  // setting only the client var no longer splits the client and server ports.
+  const preferredPort =
+    options.port ?? Number(process.env.PMX_WEB_CANVAS_PORT ?? process.env.PMX_CANVAS_PORT ?? DEFAULT_PORT);
   const portCandidates =
     options.port === 0
       ? [0]
@@ -2883,8 +2969,15 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
           if (url.pathname === '/health') {
             // `pid` lets `serve status` report the ACTUAL serving process even
             // when the pid file is stale (e.g. an adapter respawned the server
-            // outside `serve --daemon` — 0.3.2 report Finding P).
-            return responseJson({ ok: true, workspace: activeWorkspaceRoot, pid: process.pid });
+            // outside `serve --daemon` — 0.3.2 report Finding P). `persistence`
+            // surfaces silent save failures (M4): the canvas keeps serving from
+            // memory, but ok:false means durability is degraded.
+            return responseJson({
+              ok: true,
+              workspace: activeWorkspaceRoot,
+              pid: process.pid,
+              persistence: canvasState.persistenceHealth,
+            });
           }
 
           if (url.pathname === '/favicon.ico' || url.pathname === '/favicon.svg') {
@@ -2951,6 +3044,10 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleWorkbenchEvents(req);
           }
 
+          if (url.pathname === '/api/workbench/poll' && req.method === 'GET') {
+            return handleWorkbenchPoll(url);
+          }
+
           if (url.pathname === '/api/workbench/intent' && req.method === 'POST') {
             return handleWorkbenchIntent(req);
           }
@@ -3015,6 +3112,7 @@ export function stopCanvasServer(): void {
   intentRegistry.reset();
   canvasState.close();
   closeAllMcpAppSessions();
+  cancelCodeGraphRecompute();
   setCanvasLayoutUpdateEmitter(null);
   void closeCanvasAutomationWebViewInternal().catch((error) => {
     logWorkbenchWarning('stopCanvasServer closeCanvasAutomationWebViewInternal', error);

package/src/shared/ax-surface-protocol.ts

@@ -0,0 +1,22 @@
+/**
+ * Wire-protocol source tags for sandboxed-surface ↔ canvas postMessage traffic
+ * (plan-009 M2): one module owns the strings that used to be spread across the
+ * client node components, the server-side surface script generators, the
+ * ext-app script builders, and the json-render viewer. These are the trust
+ * boundary between opaque-origin iframes and the canvas — a typo'd tag fails
+ * SILENTLY (the listener just ignores the message), so single-siting them is a
+ * correctness measure, not cosmetics. The values are a persisted wire contract
+ * with already-generated surface documents: never change them.
+ */
+
+/** A sandboxed surface emitting an AX interaction to the parent canvas. */
+export const AX_SURFACE_EMIT_SOURCE = 'pmx-canvas-ax';
+
+/** The parent canvas acking an AX interaction back to the emitting surface (#55). */
+export const AX_SURFACE_ACK_SOURCE = 'pmx-canvas-ax-ack';
+
+/** Parent→surface pushes (theme updates, live AX state) into html/viewer iframes. */
+export const HTML_SURFACE_PUSH_SOURCE = 'pmx-canvas-html-node';
+
+/** Ext-app boot beacon: the iframe's scripts executed (WebKit watchdog liveness). */
+export const EXT_APP_BOOT_BEACON_SOURCE = 'pmx-canvas-ext-app-alive';

package/dist/types/client/canvas/ContextPinHud.d.ts

@@ -1 +0,0 @@
-export declare function ContextPinHud(): import("preact/src").JSX.Element | null;

package/src/client/canvas/ContextPinHud.tsx

@@ -1,17 +0,0 @@
-import { clearContextPins, contextPinnedNodeIds } from '../state/canvas-store';
-
-export function ContextPinHud() {
-  const count = contextPinnedNodeIds.value.size;
-  if (count === 0) return null;
-
-  return (
-    <div class="context-pin-hud">
-      <span class="context-pin-hud-label">
-        {'\u2726'} {count} in context
-      </span>
-      <button type="button" class="context-pin-hud-clear" onClick={clearContextPins} title="Clear all context pins">
-        ×
-      </button>
-    </div>
-  );
-}