pmx-canvas 0.2.4 → 0.2.6

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

@@ -3,11 +3,24 @@ 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;
     getBoundingClientRect(): Pick<DOMRectReadOnly, 'width' | 'height'>;
 }
+/**
+ * Finding F (0.2.4): detect a WebKit-only host — Safari or a WKWebView (e.g. the
+ * GitHub Copilot app's embedded panel). Blink engines (Chrome / Chromium / Edge /
+ * the Codex browser, all of which carry a Chrome/Chromium/CriOS/Edg token) and
+ * Android WebView are excluded, as is Gecko (no `AppleWebKit`). Used to gate the
+ * one-time ext-app iframe repaint remount to the only engine that exhibits the
+ * present-at-load black-tile paint race, so the remount is a strict no-op
+ * 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.4",
+  "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
 
@@ -195,6 +204,17 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
 - Hosted MCP-app/ext-app nodes such as Excalidraw require the in-canvas host bridge and are not
   standalone **Open as site** targets. URL-backed viewers and bundled web artifacts remain
   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
+  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
@@ -764,7 +773,8 @@ tools below operate on the live canvas state.
 > "evaluate" | "resize" }` respectively. Field names are unchanged.
 
 **`canvas_webview_status`** — Inspect the current automation session
-- Returns `{ supported, active, backend, viewportWidth, viewportHeight, url, lastError }`
+- Returns `{ supported, active, headlessOnly, url, backend, width, height, dataStoreDir, startedAt, lastError }`
+  (the viewport size is `width` / `height`, not `viewportWidth` / `viewportHeight`)
 - Call before `start` to check whether a session is already alive
 
 **`canvas_webview_start`** — Start (or replace) the automation session

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;
@@ -45,6 +46,41 @@ async function postJson<T>(url: string, body: Record<string, unknown>): Promise<
   return json.result as T;
 }
 
+/**
+ * Finding F (0.2.4): detect a WebKit-only host — Safari or a WKWebView (e.g. the
+ * GitHub Copilot app's embedded panel). Blink engines (Chrome / Chromium / Edge /
+ * the Codex browser, all of which carry a Chrome/Chromium/CriOS/Edg token) and
+ * Android WebView are excluded, as is Gecko (no `AppleWebKit`). Used to gate the
+ * one-time ext-app iframe repaint remount to the only engine that exhibits the
+ * present-at-load black-tile paint race, so the remount is a strict no-op
+ * everywhere we can test (Chrome / Codex / Playwright).
+ */
+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 : '';
@@ -194,7 +230,9 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const toolResultSendingRef = useRef<Promise<void> | null>(null);
   const bridgeReadyRef = useRef(false);
   const themeUnsubRef = useRef<(() => void) | null>(null);
-  const [status, setStatus] = useState<'loading' | 'ready' | 'done'>('loading');
+  const webkitRepaintDoneRef = useRef(false);
+  const webkitRepaintTimerRef = useRef<number | null>(null);
+  const [status, setStatus] = useState<ExtAppFrameStatus>('loading');
   const [error, setError] = useState<string | null>(null);
   const [retryKey, setRetryKey] = useState(0);
 
@@ -217,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).
@@ -262,6 +301,45 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     window.addEventListener('message', onAxMessage);
     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).
+  // 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;
+    // 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');
   const isExpanded = expanded || expandedNodeId.value === nodeId;
 
@@ -792,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%',

package/src/server/intent-registry.ts

@@ -60,6 +60,7 @@ const intentUpdateSchema = z.looseObject({
   confidence: z.number().min(0).max(1).optional(),
   seq: z.number().int().min(0).max(9999).optional(),
   ttlMs: z.number().positive().max(MAX_INTENT_TTL_MS).optional(),
+  vetoed: z.boolean().optional(),
 });
 
 function parseOrThrow<T>(schema: z.ZodType<T>, raw: unknown, label: string): T {
@@ -165,6 +166,21 @@ export class IntentRegistry {
     if (!existing) throw new OperationError(`No live intent "${id}".`, 404);
     const patch = parseOrThrow(intentUpdateSchema, raw, 'intent update');
     const now = Date.now();
+
+    // A vetoed update is a veto, not a patch: poison the id and dissolve the ghost
+    // so a later linked settle (beginCommit) is rejected — for a live, non-committing
+    // intent the same authoritative outcome as clear({ vetoed:true }). (A committing
+    // intent is already gated above with a 409, so the commit wins the race.) Without
+    // this, vetoed-via-update only dissolved the ghost visually while the linked
+    // mutation still landed (#C, 0.2.4).
+    if (patch.vetoed === true) {
+      this.rememberVeto(id);
+      this.intents.delete(id);
+      this.emit('ax-intent-clear', { id, vetoed: true });
+      this.maybeStopSweeper();
+      return { ...existing, expiresAt: now };
+    }
+
     const ttl = typeof patch.ttlMs === 'number' ? patch.ttlMs : DEFAULT_INTENT_TTL_MS;
 
     const intent: PmxAxIntent = {

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

@@ -66,6 +66,7 @@ const intentUpdateShape = {
   confidence: z.number().optional().describe('0..1 → ghost opacity/solidity.'),
   seq: z.number().optional().describe('New ordering hint.'),
   ttlMs: z.number().optional().describe('Reset the TTL to this many ms from now.'),
+  vetoed: z.boolean().optional().describe('Veto the intent: dissolves the ghost AND poisons the id so a later linked settle is rejected (same as clear { vetoed:true }).'),
 };
 
 const intentUpdateSchema = z.looseObject(intentUpdateShape);