pmx-canvas 0.3.1 → 0.3.3

package/src/client/nodes/ExtAppFrame.tsx

@@ -59,24 +59,77 @@ export function isWebKitOnlyHost(userAgent: string): boolean {
   return /AppleWebKit/.test(userAgent) && !/Chrome|Chromium|CriOS|Edg|Android/.test(userAgent);
 }
 
-// Finding F (0.2.5): SERIALIZED WebKit repaint slots. The black tile is a cold-
-// hydration BURST problem — a single ext-app repaints fine into an idle panel (like
-// a live-created node, or expand+close), but several compositing at once overwhelm
-// WebKit and all stay black. We give each mounting ext-app an increasing slot so its
-// one-time repaint remount fires into a progressively-quieter panel (one app at a
-// time), turning the burst back into a sequence of single repaints. The shared
-// counter resets after the burst so a later board load starts from slot 0.
-let webkitRepaintSlot = 0;
-let webkitRepaintSlotResetTimer: ReturnType<typeof setTimeout> | null = null;
-export function nextWebkitRepaintSlot(): number {
-  const slot = webkitRepaintSlot++;
-  if (typeof window !== 'undefined') {
-    if (webkitRepaintSlotResetTimer) clearTimeout(webkitRepaintSlotResetTimer);
-    webkitRepaintSlotResetTimer = setTimeout(() => {
-      webkitRepaintSlot = 0;
-    }, 3000);
-  }
-  return slot;
+// Finding F (0.2.5, reworked 0.3.1): BOOT-AWARE serialized WebKit remount queue.
+// The black tile is a cold-hydration BURST problem — a single ext-app repaints fine
+// into an idle panel (like a live-created node, or expand+close), but several
+// compositing at once overwhelm WebKit and all stay black. The 0.2.5 fixed-stagger
+// slots (450ms apart) were NOT boot-aware: each recovery remount reboots the app
+// (~1-2s for Excalidraw), so N staggered remounts overlapped into a fresh burst and
+// the per-node one-shot flag was spent — exactly the multi-app reload blackout the
+// 0.3.1 report shows. This queue runs remounts strictly one at a time: each entry
+// performs its remount, then waits for that app's GENUINE initialized handshake
+// (or a bounded timeout for an app that never boots) plus a settle delay before the
+// next entry fires — so every remount lands in an idle panel, which is the
+// empirically always-successful recovery (what expand+close does manually).
+// Settle covers the scene DRAW: the app's initialized handshake fires before the
+// replayed tool result arrives and the scene is painted, so the queue waits for the
+// settled signal (bootstrap chain incl. tool-result send complete) plus this pause.
+export const WEBKIT_REMOUNT_SETTLE_MS = 1000;
+const WEBKIT_BOOT_TIMEOUT_MS = 7000;
+
+export interface WebkitRemountTask {
+  /** Perform the remount. Return false if the node no longer needs it (skips the boot wait). */
+  remount: () => boolean;
+  /** Resolves when the remounted app genuinely boots AND finishes its bootstrap replay, or after a bounded timeout. */
+  awaitBoot: () => Promise<void>;
+}
+
+// Bounded recovery trail readable via `webview evaluate` / devtools
+// (window.__PMX_EXTAPP_LOG). The WebKit compositor dropout is otherwise
+// unobservable from page JS — this is the only diagnostic surface.
+export function extAppRecoveryLog(nodeId: string, event: string): void {
+  if (typeof window === 'undefined') return;
+  const host = window as unknown as { __PMX_EXTAPP_LOG?: Array<{ t: number; nodeId: string; event: string }> };
+  host.__PMX_EXTAPP_LOG ??= [];
+  if (host.__PMX_EXTAPP_LOG.length < 500) host.__PMX_EXTAPP_LOG.push({ t: Date.now(), nodeId, event });
+  queueExtAppRecoveryReport({ t: Date.now(), nodeId, event });
+}
+
+// Mirror the recovery trail to the daemon (batched, fire-and-forget) so a host
+// panel without devtools access — the Copilot WKWebView, exactly where the
+// black tiles happen — still yields an actionable trace: agents read it back
+// via GET /api/canvas/debug/ext-app-recovery (0.3.2 report Finding N).
+let extAppReportQueue: Array<{ t: number; nodeId: string; event: string; visibility?: string }> = [];
+let extAppReportTimer: ReturnType<typeof setTimeout> | null = null;
+function queueExtAppRecoveryReport(entry: { t: number; nodeId: string; event: string }): void {
+  extAppReportQueue.push({
+    ...entry,
+    ...(typeof document !== 'undefined' ? { visibility: document.visibilityState } : {}),
+  });
+  if (extAppReportTimer) return;
+  extAppReportTimer = setTimeout(() => {
+    extAppReportTimer = null;
+    const entries = extAppReportQueue.splice(0);
+    if (entries.length === 0) return;
+    void fetch('/api/canvas/debug/ext-app-recovery', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ entries }),
+    }).catch(() => {
+      // Diagnostics only — never let reporting failures affect recovery.
+    });
+  }, 1500);
+}
+
+let webkitRemountChain: Promise<void> = Promise.resolve();
+export function enqueueWebkitRemount(task: WebkitRemountTask): void {
+  webkitRemountChain = webkitRemountChain
+    .then(async () => {
+      if (!task.remount()) return;
+      await task.awaitBoot();
+      await new Promise((resolve) => setTimeout(resolve, WEBKIT_REMOUNT_SETTLE_MS));
+    })
+    .catch(() => {});
 }
 
 export function shouldScheduleWebKitRepaint(status: ExtAppFrameStatus, hasReplayToolResult: boolean): boolean {
@@ -178,6 +231,24 @@ export function buildExtAppAxBridgeScript(axToken: string, nodeId: string): stri
 </script>`;
 }
 
+/**
+ * Boot beacon injected into EVERY ext-app document (not gated on AX): posts one
+ * parent message the moment the iframe's scripts execute. This is the liveness
+ * signal the WebKit never-booted watchdog keys on — it distinguishes an app
+ * that is alive but boots via the 1200ms bootstrap fallback (e.g. a non-SDK
+ * widget that never sends ui/notifications/initialized) from a dead window
+ * whose scripts never ran. Without it, the watchdog treated every
+ * fallback-booted app as never-booted and remounted it up to the attempt cap —
+ * a reboot/flicker loop for exactly the apps the fallback exists to support
+ * (0.3.2 pre-release review). The token scopes the message to this component;
+ * the host also checks event.source against the live iframe.
+ */
+export function buildExtAppBootBeaconScript(frameToken: string, nodeId: string): string {
+  return `<script data-pmx-canvas-boot-beacon>
+window.parent.postMessage({ source: 'pmx-canvas-ext-app-alive', token: ${JSON.stringify(frameToken)}, nodeId: ${JSON.stringify(nodeId)} }, '*');
+</script>`;
+}
+
 export function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string {
   if (!axBridgeScript) return html;
   const headMatch = /<head\b[^>]*>/i.exec(html);
@@ -231,7 +302,21 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const bridgeReadyRef = useRef(false);
   const themeUnsubRef = useRef<(() => void) | null>(null);
   const webkitRepaintDoneRef = useRef(false);
-  const webkitRepaintTimerRef = useRef<number | null>(null);
+  const webkitRemountAttemptsRef = useRef(0);
+  // Genuine boot signal: set ONLY when the app completes the ui/initialize
+  // handshake (bridge.oninitialized) — NOT by the 1200ms bootstrap fallback,
+  // which flips status via notifications that resolve even into a dead iframe.
+  const appInitializedRef = useRef(false);
+  // Liveness signal from the injected boot beacon: the CURRENT frame's scripts
+  // executed. Proves "alive" for apps that boot via the fallback path without
+  // ever sending initialized; a dead window never beacons.
+  const appScriptsRanRef = useRef(false);
+  const bootWaitersRef = useRef<Array<() => void>>([]);
+  const remountQueuedRef = useRef(false);
+  // Recovery ran while the document was hidden (compositing suppressed) — re-arm
+  // one fresh remount round when the panel becomes visible (Finding N).
+  const bootedWhileHiddenRef = useRef(false);
+  const unmountedRef = useRef(false);
   const [status, setStatus] = useState<ExtAppFrameStatus>('loading');
   const [error, setError] = useState<string | null>(null);
   const [retryKey, setRetryKey] = useState(0);
@@ -265,7 +350,26 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const axEnabled = axCaps?.enabled === true && typeof html === 'string' && html.length > 0;
   const axToken = useMemo(() => `ax-${crypto.randomUUID()}`, []);
   const axBridgeScript = axEnabled ? buildExtAppAxBridgeScript(axToken, nodeId) : '';
-  const iframeDocument = useIframeDocument(injectExtAppAxBridgeScript(html ?? '', axBridgeScript), iframeSandbox);
+  // The boot beacon precedes the AX bridge so it runs first at parse time; it
+  // shares the per-component token (used purely to authenticate the message).
+  const bootBeaconScript =
+    typeof html === 'string' && html.length > 0 ? buildExtAppBootBeaconScript(axToken, nodeId) : '';
+  const iframeDocument = useIframeDocument(
+    injectExtAppAxBridgeScript(html ?? '', bootBeaconScript + axBridgeScript),
+    iframeSandbox,
+  );
+
+  useEffect(() => {
+    function onBootBeacon(event: MessageEvent) {
+      if (event.source !== iframeRef.current?.contentWindow) return;
+      const data = event.data as { source?: string; token?: string; nodeId?: string } | null;
+      if (!data || data.source !== 'pmx-canvas-ext-app-alive' || data.token !== axToken || data.nodeId !== nodeId)
+        return;
+      appScriptsRanRef.current = true;
+    }
+    window.addEventListener('message', onBootBeacon);
+    return () => window.removeEventListener('message', onBootBeacon);
+  }, [axToken, nodeId]);
 
   useEffect(() => {
     if (!axEnabled) return;
@@ -308,23 +412,61 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     return () => window.removeEventListener('message', onAxMessage);
   }, [axEnabled, axToken, nodeId]);
 
-  // Finding F (0.2.4/0.2.5): in a WebKit host panel (e.g. the GitHub Copilot app's
-  // WKWebView, and Bun's headless WebKit WebView) the doubly-nested ext-app iframe
-  // (workbench iframe → mcp-app.html iframe) can come up as a black tile for nodes
-  // present at panel-load. The mcp-app shell loads blank, then the app boots over the
-  // bridge and draws its content AFTER load; under a cold-hydration burst WebKit does
-  // not composite that late draw, so the layer stays black (clean in Blink, and clean
-  // for a node created live into an already-idle panel). A parent-side transform/src
-  // nudge does NOT repair a black layer — only a full remount (new iframe element +
-  // bridge re-init, what expand+close does) does, and only when it lands in an idle
-  // moment. So: once the app has booted — `ready` for empty apps, `done` for restored
-  // apps that must replay saved tool output — under WebKit only, force ONE remount,
-  // SERIALIZED per node (an increasing slot delay) so concurrent ext-apps
-  // don't re-form a single compositing burst (the 0.2.4 fixed-250ms-on-mount remount
-  // fired mid-burst before the app had even booted, and all siblings re-raced —
-  // insufficient). This reliably repaints a SINGLE present-at-load ext-app; a board
-  // with several ext-apps present at WebKit panel-load can still black out (a host
-  // compositor limit — expand+close or Chrome remains the fallback; see SKILL.md).
+  // Enqueue one serialized remount attempt for this node (Finding F recovery).
+  // Attempts are capped so a persistently-failing app degrades to the manual
+  // fallback (expand+close / Retry) instead of remount-looping forever.
+  const WEBKIT_MAX_REMOUNT_ATTEMPTS = 3;
+  const scheduleWebkitRemount = (reason: string): void => {
+    if (webkitRemountAttemptsRef.current >= WEBKIT_MAX_REMOUNT_ATTEMPTS) {
+      extAppRecoveryLog(nodeId, `remount-cap-hit (${reason})`);
+      return;
+    }
+    if (remountQueuedRef.current) return; // an attempt is already queued and has not run yet
+    webkitRemountAttemptsRef.current += 1;
+    remountQueuedRef.current = true;
+    extAppRecoveryLog(nodeId, `remount-queued #${webkitRemountAttemptsRef.current} (${reason})`);
+    enqueueWebkitRemount({
+      remount: () => {
+        remountQueuedRef.current = false;
+        if (unmountedRef.current || expandedNodeId.value === nodeId) {
+          extAppRecoveryLog(nodeId, 'remount-skipped');
+          return false;
+        }
+        // Stamp visibility at RUN time, not schedule time: the serialized queue
+        // can hold this slot for many seconds, and what decides whether the
+        // repaint can composite is the document's visibility when the remount
+        // actually executes (the Finding N re-arm keys on this flag). Covers
+        // every scheduling path (post-boot repaint, boot watchdog, re-arm).
+        bootedWhileHiddenRef.current = typeof document !== 'undefined' && document.visibilityState === 'hidden';
+        extAppRecoveryLog(nodeId, `remount-run #${webkitRemountAttemptsRef.current}`);
+        setRetryKey((k) => k + 1);
+        return true;
+      },
+      awaitBoot: () =>
+        new Promise<void>((resolve) => {
+          const timer = window.setTimeout(finish, WEBKIT_BOOT_TIMEOUT_MS);
+          function finish() {
+            window.clearTimeout(timer);
+            resolve();
+          }
+          bootWaitersRef.current.push(finish);
+        }),
+    });
+  };
+
+  // Finding F (0.2.4/0.2.5, reworked 0.3.1): in a WebKit host panel (e.g. the GitHub
+  // Copilot app's WKWebView, and Bun's headless WebKit WebView) the doubly-nested
+  // ext-app iframe (workbench iframe → mcp-app.html iframe) can come up as a black
+  // tile for nodes present at panel-load. The mcp-app shell loads blank, then the app
+  // boots over the bridge and draws its content AFTER load; under a cold-hydration
+  // burst WebKit does not composite that late draw, so the layer stays black (clean
+  // in Blink, and clean for a node created live into an already-idle panel). A
+  // parent-side transform/src nudge does NOT repair a black layer — only a full
+  // remount (new iframe element + bridge re-init, what expand+close does) does, and
+  // only when it lands in an idle moment. So: once the app has booted — `ready` for
+  // empty apps, `done` for restored apps that must replay saved tool output — under
+  // WebKit only, enqueue ONE recovery remount through the boot-aware queue above, so
+  // concurrent ext-apps remount strictly one at a time instead of re-bursting.
   // Strict no-op in Blink/Gecko; the e2e engine is unaffected. Inline instance only.
   useEffect(() => {
     if (expanded || webkitRepaintDoneRef.current) return;
@@ -332,19 +474,64 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     if (typeof navigator === 'undefined' || typeof window === 'undefined') return;
     if (!isWebKitOnlyHost(navigator.userAgent)) return;
     webkitRepaintDoneRef.current = true;
-    // Serialize: each ext-app repaints into a progressively-quieter panel so the
-    // cold-hydration burst becomes a sequence of single (always-successful) repaints.
-    // The timer is held in a ref and cleared only on UNMOUNT (separate effect), NOT in
-    // this effect's cleanup — otherwise a later status change (ready→done) would cancel
-    // the one-shot remount before it fires. The gate above runs once per node.
-    const delayMs = 250 + nextWebkitRepaintSlot() * 450;
-    webkitRepaintTimerRef.current = window.setTimeout(() => setRetryKey((k) => k + 1), delayMs);
+    scheduleWebkitRemount('post-boot-repaint');
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [status, hasReplayToolResult]);
 
+  // Finding N (0.3.2 report): the Copilot panel can load the canvas while the
+  // WKWebView document is HIDDEN (panel backgrounded/occluded). WebKit suppresses
+  // compositing for hidden documents, so the whole serialized recovery above can
+  // run to completion without ever producing a visible paint — and nothing
+  // retried once the panel was shown, which is why tiles stayed black until a
+  // manual expand+close (necessarily performed while visible). When the document
+  // becomes visible again, re-arm ONE fresh serialized remount round for frames
+  // whose recovery ran while hidden.
+  useEffect(() => {
+    if (expanded) return;
+    if (typeof document === 'undefined' || typeof navigator === 'undefined' || typeof window === 'undefined') return;
+    if (!isWebKitOnlyHost(navigator.userAgent)) return;
+    function onVisibilityChange() {
+      if (document.visibilityState !== 'visible') return;
+      if (!bootedWhileHiddenRef.current || unmountedRef.current) return;
+      bootedWhileHiddenRef.current = false;
+      // Fresh visibility = fresh recovery budget: the hidden-run attempts were
+      // spent without a chance of compositing.
+      webkitRemountAttemptsRef.current = 0;
+      extAppRecoveryLog(nodeId, 'visible-again-rearm');
+      scheduleWebkitRemount('visible-after-hidden-boot');
+    }
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    return () => document.removeEventListener('visibilitychange', onVisibilityChange);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [expanded, nodeId]);
+
+  // Never-booted watchdog (0.3.2): an iframe whose scripts never ran in the burst
+  // shows no error — the bootstrap fallback flips status via notifications that
+  // resolve into a dead window, so the tile just stays black. "Alive" is either
+  // boot signal from the CURRENT frame: the genuine initialize handshake, or the
+  // injected boot beacon (which covers apps that boot via the fallback without
+  // ever sending initialized — remounting those was a flicker loop, and checking
+  // bridgeReadyRef instead would be wrong: the fallback sets it blindly, dead
+  // window or not). Only a frame with NEITHER signal is retried through the
+  // serialized queue (bounded by the shared attempt cap).
+  const WEBKIT_BOOT_WATCHDOG_MS = 6000;
+  useEffect(() => {
+    if (expanded) return;
+    if (typeof navigator === 'undefined' || typeof window === 'undefined') return;
+    if (!isWebKitOnlyHost(navigator.userAgent)) return;
+    if (!iframeDocument.ready) return;
+    const timer = window.setTimeout(() => {
+      if (appInitializedRef.current || appScriptsRanRef.current || unmountedRef.current) return;
+      scheduleWebkitRemount('boot-watchdog');
+    }, WEBKIT_BOOT_WATCHDOG_MS);
+    return () => window.clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [frameKey, iframeDocument.ready, expanded]);
+
   useEffect(
     () => () => {
-      if (webkitRepaintTimerRef.current !== null) window.clearTimeout(webkitRepaintTimerRef.current);
+      unmountedRef.current = true;
+      for (const waiter of bootWaitersRef.current.splice(0)) waiter();
     },
     [],
   );
@@ -415,6 +602,11 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     lastSentToolResultRef.current = undefined;
     toolResultSendingRef.current = null;
     bridgeReadyRef.current = false;
+    // New frame = new boot attempt: both boot signals belong to the CURRENT
+    // iframe (the beacon listener also pins event.source to the live element).
+    // The queue's awaitBoot waits on this frame's handshake.
+    appInitializedRef.current = false;
+    appScriptsRanRef.current = false;
 
     const clearFallbackTimer = (): void => {
       if (!fallbackTimer) return;
@@ -611,12 +803,23 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         if (disposed) return;
         clearFallbackTimer();
         bridgeReadyRef.current = true;
+        appInitializedRef.current = true;
+        extAppRecoveryLog(nodeId, 'initialized');
         setStatus('ready');
         setError(null);
         void Promise.resolve(bridge.sendHostContextChange(buildHostContext(isExpanded ? 'fullscreen' : 'inline')))
           .then(() => sendExtAppBootstrapState(bridge, latestToolInputRef.current, undefined))
           .then(() => flushToolResult(bridge))
-          .then(() => nudgeHostContextAfterLayout())
+          .then(() => {
+            // Settled: handshake + bootstrap replay delivered — the app draws its
+            // scene right after this. Release the remount queue (which then adds
+            // its own settle pause covering the draw) only from this genuine path;
+            // the bootstrap fallback never releases it (a dead iframe must run the
+            // queue's bounded timeout instead of green-lighting the next remount).
+            extAppRecoveryLog(nodeId, 'settled');
+            for (const waiter of bootWaitersRef.current.splice(0)) waiter();
+            nudgeHostContextAfterLayout();
+          })
           .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             setError(`Bridge bootstrap failed: ${msg}`);

package/src/server/bundled-skills.ts

@@ -65,7 +65,11 @@ export function findBundledSkillsRoot(): string | null {
   return null;
 }
 
-function parseFrontmatterDescription(markdown: string): string {
+function parseFrontmatterDescription(rawMarkdown: string): string {
+  // Normalize CRLF first: a git checkout with autocrlf (the Windows default)
+  // puts a trailing \r on every line, which `(.*)$` cannot match (JS `.` and
+  // `$` both exclude \r), silently emptying every description.
+  const markdown = rawMarkdown.replace(/\r\n/g, '\n');
   // YAML frontmatter lives between two `---` fences at the very top.
   if (!markdown.startsWith('---')) return '';
   const end = markdown.indexOf('\n---', 3);

package/src/server/canvas-operations.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 import { recomputeCodeGraph } from './code-graph.js';
 import {
   canvasState,
@@ -727,7 +727,7 @@ function buildFileNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
   const rawPath =
     typeof input.data?.path === 'string' && input.data.path.length > 0 ? input.data.path : (input.content ?? '');
   const resolved = resolve(rawPath);
-  const fileName = resolved.split('/').pop() ?? rawPath;
+  const fileName = basename(resolved) || rawPath;
   const data: Record<string, unknown> = {
     ...(input.data ?? {}),
     path: resolved,
@@ -767,7 +767,7 @@ function buildImageNodeData(input: CanvasAddNodeInput): Record<string, unknown>
 
   if (!isDataUri && !isUrl && src) {
     const resolved = resolve(src);
-    const fileName = resolved.split('/').pop() ?? src;
+    const fileName = basename(resolved) || src;
     const { mimeType } = validateLocalImageFile(resolved);
     return {
       ...(input.data ?? {}),

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

@@ -51,6 +51,7 @@ const SUPPORTED_BATCH_OPS = new Set([
   'node.remove',
   'graph.add',
   'edge.add',
+  'edge.remove',
   'group.create',
   'group.add',
   'group.remove',
@@ -204,7 +205,7 @@ function shapeBatchEntry(op: string, result: unknown): Record<string, unknown> {
     return { ok: true, arranged: body.arranged, layout: body.layout };
   }
 
-  // edge.add / group.remove: wire shape already matches the legacy push verbatim.
+  // edge.add / edge.remove / group.remove: wire shape matches the push verbatim.
   return body;
 }
 
@@ -356,7 +357,7 @@ const batchOperation = defineOperation<z.infer<typeof batchSchema>, BatchEnvelop
   mcp: {
     toolName: 'canvas_batch',
     description:
-      'Run a non-atomic batch of canvas operations with optional assigned references. Use assign to name a result, then reference it later as "$name" for the created node id or "$name.id" for a specific result field. On failure, earlier successful operations remain applied and the response includes ok:false, failedIndex, error, results, and refs. Supports node.add, node.update, node.remove, graph.add, edge.add, group.create, group.add, group.remove, pin.set/add/remove, snapshot.save, and arrange.',
+      'Run a non-atomic batch of canvas operations with optional assigned references. Use assign to name a result, then reference it later as "$name" for the created node id or "$name.id" for a specific result field. On failure, earlier successful operations remain applied and the response includes ok:false, failedIndex, error, results, and refs. Supports node.add, node.update, node.remove, graph.add, edge.add, edge.remove, group.create, group.add, group.remove, pin.set/add/remove, snapshot.save, and arrange.',
     formatResult: (result, input) => {
       const envelope = result as BatchEnvelope;
       const payload = wantsFullBatch(input) ? envelope : compactBatchResult(envelope);

package/src/server/server.ts

@@ -1021,13 +1021,26 @@ function resolveCanvasBundleDir(): string {
   return fallback;
 }
 
+/**
+ * Containment check for bundle-asset serving. Separator-agnostic: on Windows,
+ * `resolve()` returns backslash paths, so comparing against a `${dir}/` template
+ * rejected every asset — /canvas/index.js 404'd and the SPA never booted (the
+ * 0.3.1 Windows report). Normalizing both sides keeps the check exact on POSIX
+ * and correct on win32, and testable with win32-shaped fixtures on any host.
+ */
+export function isCanvasBundlePath(distPath: string, bundleDir: string): boolean {
+  const normalize = (value: string) => value.replaceAll('\\', '/');
+  const dir = normalize(bundleDir).replace(/\/+$/, '');
+  return normalize(distPath).startsWith(`${dir}/`);
+}
+
 function serveCanvasStatic(pathname: string): Response | null {
   const fileName = pathname.slice('/canvas/'.length);
   if (!fileName || fileName.includes('..') || fileName.startsWith('/')) return null;
 
   const bundleDir = resolveCanvasBundleDir();
   const distPath = resolve(bundleDir, fileName);
-  if (!distPath.startsWith(`${bundleDir}/`)) return null;
+  if (!isCanvasBundlePath(distPath, bundleDir)) return null;
   if (existsSync(distPath)) {
     const ext = extname(fileName);
     return new Response(readFileSync(distPath), {
@@ -1107,6 +1120,44 @@ function handleFrameDocument(pathname: string): Response {
   });
 }
 
+// ── Ext-app recovery diagnostics (0.3.2 report Finding N) ──────
+//
+// The WebKit black-tile recovery trail is otherwise trapped inside host panels
+// without devtools (the Copilot WKWebView). Clients mirror their bounded
+// recovery log here; agents/testers read it back over HTTP. In-memory only,
+// diagnostics-grade: no persistence, no snapshots.
+const EXT_APP_RECOVERY_LOG_MAX = 500;
+const EXT_APP_RECOVERY_FIELD_MAX = 300;
+const extAppRecoveryEntries: Array<Record<string, unknown>> = [];
+
+/**
+ * Clamp a reported entry to the known trail shape ({ t, nodeId, event,
+ * visibility }) with bounded string lengths. The count trim below caps the
+ * number of entries; this caps bytes per entry, so the in-memory log stays
+ * diagnostics-sized no matter what a client posts.
+ */
+function clampExtAppRecoveryEntry(entry: Record<string, unknown>): Record<string, unknown> {
+  const clamped: Record<string, unknown> = {};
+  if (typeof entry.t === 'number' && Number.isFinite(entry.t)) clamped.t = entry.t;
+  for (const key of ['nodeId', 'event', 'visibility'] as const) {
+    const value = entry[key];
+    if (typeof value === 'string') clamped[key] = value.slice(0, EXT_APP_RECOVERY_FIELD_MAX);
+  }
+  return clamped;
+}
+
+function handleExtAppRecoveryReport(entries: unknown): Response {
+  if (!Array.isArray(entries)) return responseJson({ ok: false, error: 'entries must be an array' }, 400);
+  for (const entry of entries.slice(0, 100)) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    extAppRecoveryEntries.push(clampExtAppRecoveryEntry(entry as Record<string, unknown>));
+  }
+  if (extAppRecoveryEntries.length > EXT_APP_RECOVERY_LOG_MAX) {
+    extAppRecoveryEntries.splice(0, extAppRecoveryEntries.length - EXT_APP_RECOVERY_LOG_MAX);
+  }
+  return responseJson({ ok: true, total: extAppRecoveryEntries.length });
+}
+
 // ── Node surfaces ("Open as site") ─────────────────────────────
 //
 // One stable, node-addressable URL — /api/canvas/surface/:nodeId — that serves
@@ -2830,7 +2881,10 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
           const url = new URL(req.url);
 
           if (url.pathname === '/health') {
-            return responseJson({ ok: true, workspace: activeWorkspaceRoot });
+            // `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 });
           }
 
           if (url.pathname === '/favicon.ico' || url.pathname === '/favicon.svg') {
@@ -2841,10 +2895,25 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleArtifactView(url);
           }
 
-          if (url.pathname === '/api/canvas/json-render/view' && req.method === 'GET') {
+          // Standalone surfaces answer HEAD like GET (status + headers, no body):
+          // tooling probes these advertised URLs, and a HEAD 404 against a
+          // working GET reads as a broken surface (0.3.2 report Finding O).
+          // Bun.serve strips the body and keeps the true Content-Length on HEAD,
+          // so the GET handler's response is returned as-is.
+          if (url.pathname === '/api/canvas/json-render/view' && (req.method === 'GET' || req.method === 'HEAD')) {
             return handleJsonRenderView(url);
           }
 
+          if (url.pathname === '/api/canvas/debug/ext-app-recovery' && req.method === 'POST') {
+            const body = await readJson(req);
+            if (body === null) return malformedJsonResponse();
+            return handleExtAppRecoveryReport(body.entries);
+          }
+
+          if (url.pathname === '/api/canvas/debug/ext-app-recovery' && req.method === 'GET') {
+            return responseJson({ ok: true, entries: extAppRecoveryEntries });
+          }
+
           if (url.pathname === '/api/canvas/frame-documents' && req.method === 'POST') {
             return handleCreateFrameDocument(req);
           }
@@ -2853,7 +2922,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleFrameDocument(url.pathname);
           }
 
-          if (url.pathname.startsWith('/api/canvas/surface/') && req.method === 'GET') {
+          if (url.pathname.startsWith('/api/canvas/surface/') && (req.method === 'GET' || req.method === 'HEAD')) {
             return handleNodeSurface(url.pathname, url);
           }