pmx-canvas 0.2.5 → 0.2.6

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

@@ -3,6 +3,7 @@ import { AppBridge } from '@modelcontextprotocol/ext-apps/app-bridge';
 import type { CanvasNodeState } from '../types';
 type ExtAppBridgeNotifications = Pick<AppBridge, 'sendToolInput' | 'sendToolResult'>;
 type DisplayMode = 'inline' | 'fullscreen' | 'pip';
+type ExtAppFrameStatus = 'loading' | 'ready' | 'done';
 interface ExtAppHostDimensionsTarget {
     clientWidth?: number;
     clientHeight?: number;
@@ -18,6 +19,8 @@ interface ExtAppHostDimensionsTarget {
  * everywhere we can test (Chrome / Codex / Playwright).
  */
 export declare function isWebKitOnlyHost(userAgent: string): boolean;
+export declare function nextWebkitRepaintSlot(): number;
+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): {
     nextMode: DisplayMode;

package/package.json

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

@@ -58,6 +58,15 @@ Both surfaces report `workspace`. It must match the intended workspace root.
 - Target that port and re-check `/health`.
 - `PMX_CANVAS_PORT` is the agent CLI target; the server's startup port is controlled by `--port`
   or `PMX_WEB_CANVAS_PORT`.
+- **MCP transport caveat (wrong-workspace split).** An MCP server (`pmx-canvas --mcp`) holds its own
+  in-memory canvas and, if its preferred port is already taken by a *different* workspace's daemon,
+  binds the next free port adopting **its own launch `cwd`** as the workspace — so its writes land on
+  a daemon the browser panel never renders (it self-reports this fallback on stderr). Before trusting
+  MCP-written state, confirm the MCP server's workspace matches the panel's (`/health` on both ports)
+  and that no stray higher-numbered listener exists. The durable fix is to launch the MCP server with
+  `cwd=<project>` or `PMX_CANVAS_PORT=<panel-port>`. The CLI's query/mutation commands are a thin HTTP
+  client and never start a server of their own (only `serve` / `--mcp` spawn a process), so prefer
+  those CLI commands for watcher/automation loops until the launch config is pinned.
 
 ## Choose the Smallest Useful Node Type
 
@@ -197,11 +206,15 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   openable.
 - A hosted ext-app (Excalidraw) node that is already on the board when a **WebKit** host panel
   loads (e.g. the GitHub Copilot app's embedded WKWebView) can render as a black tile — a host
-  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 auto-remounts the iframe once on load under WebKit to force a
-  repaint; if a tile is still black, expand-then-close it (forces a remount) or open the workbench
-  in a normal browser. Do not diagnose a healthy app session as a broken node.
+  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.
 - 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

@@ -386,7 +386,16 @@ Agents tend to pack boards too tightly. Give nodes room to breathe — readabili
 
 ### Colors (Semantic)
 
-Use color consistently to convey meaning:
+A `color` parameter is honored only for **group** nodes (frame accent) and **graph** nodes
+(series/accent color). It is **not** a parameter for `markdown` / `status` / `context` nodes — a
+top-level `color` on those is silently ignored over both HTTP and the CLI (report Finding H). Their
+meaning comes from the node **type** and value instead: a `status` node colors its indicator from its
+**phase** (`idle`/`running`/`planning`/`thinking`/`drafting`/`tooling`/`review`/`waiting-approval`/
+`waiting` — e.g. `review` → green, `running` → accent; an unrecognized phase renders gray), and a
+`trace` node from its `status` field (`success` → green, `failed` → red, `running` → accent). To
+color an arbitrary region, group the nodes and set the group's `color`.
+
+When you do set a color (group/graph), use this palette consistently to convey meaning:
 - **Green** (`#22c55e`) — success, done, healthy
 - **Yellow** (`#eab308`) — in progress, warning, attention needed
 - **Red** (`#ef4444`) — error, blocked, failing
@@ -523,7 +532,7 @@ retrying the generic add.
 - `content`: markdown text for most types. For `file`, pass the **file path** (e.g. `"src/auth/login.ts"`) —
   the server auto-loads + watches it. For `image`, pass a file path, URL, or data URI.
 - `path`: compatibility alias for image paths only; prefer `content` for new image calls
-- `x`, `y`: position (prefer omitting for auto-layout); `width`, `height`: dimensions (sensible defaults); `color`: semantic color; `metadata`: arbitrary JSON
+- `x`, `y`: position (prefer omitting for auto-layout); `width`, `height`: dimensions (sensible defaults); `metadata`: arbitrary JSON. (`color` applies to **group**/**graph** nodes only — it is ignored on basic node types; see Colors (Semantic).)
 - Returns: `{ id: "<node-id>" }` — capture this ID for edges and groups
 
 **`canvas_node { action: "update", id, … }`** — Update an existing node in place (preferred over

package/src/client/nodes/ExtAppFrame.tsx

@@ -23,6 +23,7 @@ type McpUiTheme = 'light' | 'dark';
 
 type ExtAppBridgeNotifications = Pick<AppBridge, 'sendToolInput' | 'sendToolResult'>;
 type DisplayMode = 'inline' | 'fullscreen' | 'pip';
+type ExtAppFrameStatus = 'loading' | 'ready' | 'done';
 
 interface ExtAppHostDimensionsTarget {
   clientWidth?: number;
@@ -58,6 +59,28 @@ 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;
+}
+
+export function shouldScheduleWebKitRepaint(status: ExtAppFrameStatus, hasReplayToolResult: boolean): boolean {
+  return hasReplayToolResult ? status === 'done' : status === 'ready' || status === 'done';
+}
+
 export function getExtAppBridgeInitKey(node: CanvasNodeState, retryKey: number): string {
   const html = typeof node.data.html === 'string' ? node.data.html : '';
   const serverName = typeof node.data.serverName === 'string' ? node.data.serverName : '';
@@ -208,7 +231,8 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const bridgeReadyRef = useRef(false);
   const themeUnsubRef = useRef<(() => void) | null>(null);
   const webkitRepaintDoneRef = useRef(false);
-  const [status, setStatus] = useState<'loading' | 'ready' | 'done'>('loading');
+  const webkitRepaintTimerRef = useRef<number | null>(null);
+  const [status, setStatus] = useState<ExtAppFrameStatus>('loading');
   const [error, setError] = useState<string | null>(null);
   const [retryKey, setRetryKey] = useState(0);
 
@@ -231,6 +255,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const maxHeight = node.size.height;
   const nodeId = node.id;
   const frameKey = getExtAppBridgeInitKey(node, retryKey);
+  const hasReplayToolResult = toolResult != null;
   const iframeSandbox = resolveExtAppSandbox(null);
   // Phase 6 — opt-in ext-app AX bridge. When the node sets data.axCapabilities.enabled,
   // inject window.PMX_AX into the app HTML and accept emits below (server re-validates).
@@ -277,26 +302,42 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     return () => window.removeEventListener('message', onAxMessage);
   }, [axEnabled, axToken, nodeId]);
 
-  // Finding F (0.2.4): in a WebKit host panel (e.g. the GitHub Copilot app's
-  // WKWebView), the doubly-nested ext-app iframe (workbench iframe → mcp-app.html
-  // iframe) can lose the initial-paint race during board hydration and come up as a
-  // black tile for nodes already present at panel-load — clean in Blink (Chrome /
-  // Codex / our Playwright e2e) and clean for nodes created live after hydration.
-  // The deterministic recovery is an iframe remount (exactly what expand+close, and
-  // the error-retry button, already do). Replicate that recovery ONCE, on mount, in
-  // WebKit-only — gated on the engine so it is a strict no-op in Blink and cannot
-  // regress the engine we test against. Inline board instance only (the one that
-  // loads black); the expanded overlay already remounts on open.
+  // 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).
+  // Strict no-op in Blink/Gecko; the e2e engine is unaffected. Inline instance only.
   useEffect(() => {
     if (expanded || webkitRepaintDoneRef.current) return;
+    if (!shouldScheduleWebKitRepaint(status, hasReplayToolResult)) return;
     if (typeof navigator === 'undefined' || typeof window === 'undefined') return;
     if (!isWebKitOnlyHost(navigator.userAgent)) return;
     webkitRepaintDoneRef.current = true;
-    // Let the initial hydration burst settle, then force one remount so the nested
-    // iframe repaints (mirrors the post-hydration expand+close recovery).
-    const timer = window.setTimeout(() => setRetryKey((k) => k + 1), 250);
-    return () => window.clearTimeout(timer);
+    // 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);
     // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [status, hasReplayToolResult]);
+
+  useEffect(() => () => {
+    if (webkitRepaintTimerRef.current !== null) window.clearTimeout(webkitRepaintTimerRef.current);
   }, []);
 
   const toMcpTheme = (theme: string): McpUiTheme => (theme === 'light' ? 'light' : 'dark');
@@ -829,6 +870,10 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
           {...iframeDocument.attributes}
           sandbox={iframeSandbox}
           allow={buildAllowAttribute(resourceMeta?.permissions)}
+          // NB: do NOT add the `.mcp-app-frame` GPU-layer class (translateZ(0)) here —
+          // it creates a stacking context that breaks the AX emit→ack round-trip in the
+          // expanded ext-app overlay (#55 e2e); the post-boot WebKit repaint remount
+          // below recovers a single present-at-load ext-app without it (Finding F).
           style={{
             flex: 1,
             width: '100%',