pmx-canvas 0.3.1 → 0.3.2

package/dist/types/cli/agent.d.ts

@@ -10,4 +10,12 @@
  * - Idempotent operations where possible
  * - --yes for destructive actions, --dry-run for preview
  */
-export declare function runAgentCli(args: string[]): Promise<void>;
+/**
+ * Extract the global `--port <n>` / `--server-url <url>` flags (any position,
+ * `=` or space-separated value) and set the invocation's target override.
+ * Returns the remaining args for command dispatch. Invalid values are a loud
+ * `die` — never a silent fallback to the default port. `--server-url` wins
+ * over `--port` when both are given.
+ */
+export declare function extractGlobalTargetFlags(args: string[]): string[];
+export declare function runAgentCli(rawArgs: string[]): Promise<void>;

package/dist/types/client/nodes/ExtAppFrame.d.ts

@@ -19,7 +19,15 @@ interface ExtAppHostDimensionsTarget {
  * everywhere we can test (Chrome / Codex / Playwright).
  */
 export declare function isWebKitOnlyHost(userAgent: string): boolean;
-export declare function nextWebkitRepaintSlot(): number;
+export declare const WEBKIT_REMOUNT_SETTLE_MS = 1000;
+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>;
+}
+export declare function extAppRecoveryLog(nodeId: string, event: string): void;
+export declare function enqueueWebkitRemount(task: WebkitRemountTask): void;
 export declare function shouldScheduleWebKitRepaint(status: ExtAppFrameStatus, hasReplayToolResult: boolean): boolean;
 export declare function getExtAppBridgeInitKey(node: CanvasNodeState, retryKey: number): string;
 export declare function resolveExtAppDisplayModeRequest(requestedMode: DisplayMode, isExpanded: boolean): {

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

@@ -81,6 +81,14 @@ export declare function setPrimaryWorkbenchAutoOpenEnabled(enabled: boolean): vo
 export declare function isPrimaryWorkbenchAutoOpenEnabled(): boolean;
 export declare function hasWorkbenchSubscribers(): boolean;
 export declare function setPrimaryWorkbenchCanvasPromptHandler(handler: PrimaryWorkbenchCanvasPromptHandler | null): void;
+/**
+ * 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 declare function isCanvasBundlePath(distPath: string, bundleDir: string): boolean;
 export declare function buildMacBrowserOpenScript(appName: string, url: string): string;
 export declare function openUrlInExternalBrowser(url: string): boolean;
 /**

package/docs/cli.md

@@ -2,7 +2,16 @@
 
 The CLI is the shell-native way to run and control PMX Canvas. It targets
 `http://localhost:4313` by default — override with `PMX_CANVAS_URL` or
-`PMX_CANVAS_PORT` when the server runs elsewhere.
+`PMX_CANVAS_PORT` when the server runs elsewhere, or per invocation with the
+global `--port <n>` / `--server-url <url>` flags (any position; `--server-url`
+wins over `--port`, and both win over the environment variables). An invalid
+value for either flag is a hard error — the CLI never falls back silently to
+the default port.
+
+```bash
+pmx-canvas node list --port 4750                      # target a non-default daemon
+pmx-canvas --server-url http://127.0.0.1:4750 status  # same, by URL
+```
 
 ## Server lifecycle
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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/skills/pmx-canvas/SKILL.md

@@ -24,7 +24,8 @@ Humans curate agent context by pinning nodes; agents read that curation through
    `workspace` must equal the intended absolute workspace root. A healthy listener on port 4313
    may belong to another project.
 3. **Read before write.** Search with `canvas_query { action: "search", query }` before creating
-   nodes. Read the full layout only when necessary.
+   nodes. Read the full layout only when necessary. The MCP parameter is `query` — passing the
+   HTTP API's `q` is silently ignored and returns zero results.
 4. **Snapshot before destructive changes.** Use `canvas_snapshot` (deprecated standalone; folds into
    the `canvas_snapshot` composite's `save` action in v0.4) before clear, restore, or a major
    reorganization.
@@ -33,7 +34,8 @@ Humans curate agent context by pinning nodes; agents read that curation through
    or edit, then pass the returned `intent.id` as `intentId` on the mutation so the ghost settles
    into the result. Use it as much as possible to make your next move and your work visible: the
    human watches intent form and can veto mid-thought. Skip it only for trivial in-place tweaks or
-   high-frequency batch churn.
+   high-frequency batch churn. The default TTL (~8s) expires between agent turns: signal with
+   `ttlMs: 30000` and settle by passing `intentId` on the mutation in the same or next call.
 6. **Mutate through current composites.** Prefer the 15 composite MCP tools below.
 7. **Arrange and validate.** After batch changes, use `canvas_view { action: "arrange" }` when
    appropriate and always finish with `canvas_query { action: "validate" }`.
@@ -215,13 +217,14 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   loads (e.g. the GitHub Copilot app's embedded WKWebView) can render as a black tile — a host
   compositor paint race on the nested iframe, **not** a broken node (the session is healthy and
   `sessionStatus` is `ready`; it renders fine in Chrome, the Codex browser, and for nodes created
-  live after the panel hydrates). The canvas forces a one-time post-boot repaint remount under
-  WebKit, which reliably repaints a **single** present-at-load
-  ext-app — but a board with **several** ext-apps present at WebKit panel-load can still black out
-  (the simultaneous cold-hydration burst overwhelms the WebKit compositor). Recovery is
-  deterministic: **expand-then-close** any black tile (forces a fresh mount in the fullscreen
-  overlay, which always paints), or open the workbench in a normal browser (Chrome). Do not
-  diagnose a healthy app session as a broken node; the durable fix is upstream in the host panel.
+  live after the panel hydrates). Under WebKit the canvas auto-recovers: after boot, each
+  present-at-load ext-app is remounted through a **serialized, boot-aware queue** (one app at a
+  time, each waiting for the previous app's handshake + scene replay), with a watchdog retry for
+  iframes that never boot — so multi-app boards converge to painted tiles within a few seconds of
+  panel load. In rare cases a tile can still end up black (compositing success is not observable
+  from page JS, so retries are bounded); recovery is deterministic: **expand-then-close** the
+  black tile (forces a fresh mount in the fullscreen overlay, which always paints), or open the
+  workbench in a normal browser (Chrome). Do not diagnose a healthy app session as a broken node.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and
   reflow on a live window resize in a normal browser. Some single-tab host browsers (e.g. the
   Codex in-app browser) don't deliver live-resize events, so a resized standalone chart can look

package/skills/pmx-canvas/references/full-reference.md

@@ -510,6 +510,13 @@ surfaces): `canvas_batch`, `canvas_pin_nodes`, `canvas_screenshot`, `canvas_ax_i
 `canvas_diff` — deprecated pending a `canvas_snapshot` composite in v0.4; the name collides with
 the current save-snapshot tool, so the composite cannot land additively).
 
+`canvas_batch` supports exactly these ops: `node.add`, `node.update`, `node.remove`, `graph.add`,
+`edge.add`, `edge.remove`, `group.create`, `group.add`, `group.remove`, `pin.set`/`pin.add`/
+`pin.remove`, `snapshot.save`, and `arrange`. Anything else fails with "Unsupported canvas_batch
+operation" — batch is non-atomic, so earlier ops stay applied and the response carries
+`failedIndex`. `canvas_screenshot` requires an active automation WebView: call
+`canvas_webview { action: "start" }` first.
+
 > **Removed in v0.3.0 → use the composite instead**: `canvas_open_mcp_app` / `canvas_add_diagram` /
 > `canvas_build_web_artifact` → **`canvas_app`**; `canvas_webview_start` / `canvas_webview_status` /
 > `canvas_webview_stop` / `canvas_resize` / `canvas_evaluate` → **`canvas_webview`**;

package/src/cli/agent.ts

@@ -89,13 +89,77 @@ interface CanvasSchemaResponse {
   };
 }
 
+// Per-invocation target override from the global --server-url / --port flags.
+// Before these existed, `--port 4750` on any agent command was SILENTLY ignored
+// and the command hit the default 4313 daemon — which once pointed a test
+// automation WebView at a live production board.
+let cliTargetOverride: string | null = null;
+
 function getBaseUrl(): string {
+  if (cliTargetOverride) return cliTargetOverride;
   const envUrl = process.env.PMX_CANVAS_URL;
   if (envUrl) return envUrl.replace(/\/$/, '');
   const port = process.env.PMX_CANVAS_PORT || DEFAULT_PORT;
   return `http://localhost:${port}`;
 }
 
+/**
+ * Extract the global `--port <n>` / `--server-url <url>` flags (any position,
+ * `=` or space-separated value) and set the invocation's target override.
+ * Returns the remaining args for command dispatch. Invalid values are a loud
+ * `die` — never a silent fallback to the default port. `--server-url` wins
+ * over `--port` when both are given.
+ */
+export function extractGlobalTargetFlags(args: string[]): string[] {
+  cliTargetOverride = null;
+  let portOverride: number | null = null;
+  let urlOverride: string | null = null;
+  const rest: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    let name: 'port' | 'server-url' | null = null;
+    let value: string | undefined;
+    if (arg === '--port' || arg === '--server-url') {
+      name = arg.slice(2) as 'port' | 'server-url';
+      value = args[i + 1];
+      i += 1;
+    } else if (arg.startsWith('--port=')) {
+      name = 'port';
+      value = arg.slice('--port='.length);
+    } else if (arg.startsWith('--server-url=')) {
+      name = 'server-url';
+      value = arg.slice('--server-url='.length);
+    } else {
+      rest.push(arg);
+      continue;
+    }
+
+    if (name === 'port') {
+      const port = Number(value);
+      if (!value || !Number.isInteger(port) || port <= 0 || port > 65535) {
+        die(
+          `--port requires a port number, got ${value === undefined ? 'no value' : JSON.stringify(value)}.`,
+          'Example: --port 4313. Without the flag, PMX_CANVAS_PORT / PMX_CANVAS_URL pick the target.',
+        );
+      }
+      portOverride = port;
+    } else {
+      if (!value || !/^https?:\/\//.test(value)) {
+        die(
+          `--server-url requires an http(s) URL, got ${value === undefined ? 'no value' : JSON.stringify(value)}.`,
+          'Example: --server-url http://localhost:4313. Without the flag, PMX_CANVAS_URL picks the target.',
+        );
+      }
+      urlOverride = value.replace(/\/$/, '');
+    }
+  }
+
+  if (urlOverride) cliTargetOverride = urlOverride;
+  else if (portOverride) cliTargetOverride = `http://localhost:${portOverride}`;
+  return rest;
+}
+
 function die(message: string, hint?: string): never {
   const out: Record<string, string> = { error: message };
   if (hint) out.hint = hint;
@@ -3535,6 +3599,8 @@ Analysis:
 
 Global flags:
   --help, -h                          Show help for any command
+  --port <n>                          Target daemon port for this invocation (overrides PMX_CANVAS_PORT)
+  --server-url <url>                  Target server URL for this invocation (overrides PMX_CANVAS_URL; wins over --port)
 
 Environment:
   PMX_CANVAS_URL    Server URL (default: http://localhost:4313)
@@ -3592,7 +3658,8 @@ async function readStdin(): Promise<string> {
 
 // ── Router ───────────────────────────────────────────────────
 
-export async function runAgentCli(args: string[]): Promise<void> {
+export async function runAgentCli(rawArgs: string[]): Promise<void> {
+  const args = extractGlobalTargetFlags(rawArgs);
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     showTopLevelHelp();
     return;

package/src/cli/index.ts

@@ -120,6 +120,25 @@ function stripOption(argv: string[], name: string): string[] {
   return stripped;
 }
 
+// Global target flags (--port / --server-url) may precede the subcommand, e.g.
+// `pmx-canvas --port 4750 node list`. Skip them (and their values) when picking
+// the subcommand to dispatch, so the agent CLI — which strips these flags via
+// extractGlobalTargetFlags and validates them loudly — is reached instead of the
+// server-startup fallback. Only these two flags are skipped; other leading flags
+// (--mcp, --demo, …) still route exactly as before.
+function commandAfterGlobalTargetFlags(argv: string[]): string {
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--port' || arg === '--server-url') {
+      if (index + 1 < argv.length && !argv[index + 1].startsWith('-')) index++;
+      continue;
+    }
+    if (arg.startsWith('--port=') || arg.startsWith('--server-url=')) continue;
+    return arg;
+  }
+  return '';
+}
+
 function runMcpServerProcess(): Promise<void> {
   return new Promise((resolvePromise, rejectPromise) => {
     const child = spawn(process.execPath, ['run', mcpServerEntry], {
@@ -181,7 +200,8 @@ if (firstArg === 'serve') {
   args.shift();
 }
 
-if (AGENT_COMMANDS.has(firstArg) && firstArg !== 'serve') {
+const routedCommand = commandAfterGlobalTargetFlags(args);
+if (AGENT_COMMANDS.has(routedCommand) && routedCommand !== 'serve') {
   await runAgentCli(args);
 } else if (args.includes('--mcp')) {
   // MCP server mode: stdio transport, auto-starts canvas on first tool call

package/src/client/nodes/ExtAppFrame.tsx

@@ -59,24 +59,50 @@ 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 });
+}
+
+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 {
@@ -231,7 +257,14 @@ 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);
+  const bootWaitersRef = useRef<Array<() => void>>([]);
+  const remountQueuedRef = useRef(false);
+  const unmountedRef = useRef(false);
   const [status, setStatus] = useState<ExtAppFrameStatus>('loading');
   const [error, setError] = useState<string | null>(null);
   const [retryKey, setRetryKey] = useState(0);
@@ -308,23 +341,55 @@ 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;
+        }
+        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 +397,33 @@ 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]);
 
+  // Never-booted watchdog (0.3.1): 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. If the CURRENT frame
+  // has not completed the genuine initialize handshake within the watchdog window,
+  // retry it through the same 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 || 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 +494,9 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     lastSentToolResultRef.current = undefined;
     toolResultSendingRef.current = null;
     bridgeReadyRef.current = false;
+    // New frame = new boot attempt: the genuine-initialized signal belongs to the
+    // CURRENT iframe. The queue's awaitBoot waits on this frame's handshake.
+    appInitializedRef.current = false;
 
     const clearFallbackTimer = (): void => {
       if (!fallbackTimer) return;
@@ -611,12 +693,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/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), {