pmx-canvas 0.1.23 → 0.1.24

package/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -0,0 +1,111 @@
+# GitHub Copilot App Adapter
+
+Use this reference when PMX Canvas is running inside the GitHub Copilot app as a project canvas
+extension. The adapter is intentionally thin: PMX Canvas remains the state owner, and the extension
+maps Copilot SDK features onto PMX AX primitives.
+
+## Adapter Identity
+
+- Extension path: `.github/extensions/pmx-canvas/extension.mjs`
+- Extension ID: `project:pmx-canvas`
+- Canvas ID: `pmx-canvas`
+- Display name: `PMX Canvas`
+
+Open it with:
+
+```json
+{
+  "extensionId": "project:pmx-canvas",
+  "canvasId": "pmx-canvas",
+  "instanceId": "pmx-canvas"
+}
+```
+
+Use a different `instanceId` for parallel panels. Reusing an `instanceId` focuses/reloads the same
+panel.
+
+## What the Adapter Does
+
+- Opens the live PMX workbench directly in a native Copilot canvas panel.
+- Uses PMX-served same-origin frame documents for iframe-backed nodes (`html` and hosted MCP apps).
+  The Copilot app webview can leave nested `srcdoc` and `blob:` iframes blank, so PMX should route
+  generated frame HTML through `/api/canvas/frame-documents/...` instead.
+- Connects to a matching local PMX server for the current workspace, or starts one when needed.
+- Reads `/api/canvas/ax/context` and injects pinned/focused context from
+  `onUserPromptSubmitted`.
+- Exposes adapter actions for status, AX context refresh, AX focus, and explicit session steering.
+- Keeps all persistent PMX state in `.pmx-canvas/canvas.db`; the extension does not own canvas
+  state.
+
+## Open Input
+
+All fields are optional:
+
+```json
+{
+  "serverUrl": "http://127.0.0.1:4313",
+  "port": 4313,
+  "autoStart": true,
+  "allowWorkspaceMismatch": false,
+  "workspaceRoot": "/path/to/repo"
+}
+```
+
+Default discovery order:
+
+1. `serverUrl` input.
+2. `PMX_CANVAS_URL`.
+3. `PMX_CANVAS_PORT` / `PMX_WEB_CANVAS_PORT` / `4313` on loopback.
+4. Managed server startup for the current workspace when `autoStart` is not `false`.
+
+The adapter rejects an unrelated running PMX server unless `serverUrl` is explicit or
+`allowWorkspaceMismatch` is true.
+
+## Actions
+
+| Action | Purpose |
+|---|---|
+| `status` | Return PMX server health and persisted AX state. |
+| `get_ax_context` | Return current pinned + focused AX context. |
+| `focus_nodes` | Set AX focus with `source: "copilot"`. |
+| `send_instruction` | Send an explicit prompt into the active Copilot session. |
+
+Example focus action:
+
+```json
+{
+  "nodeIds": ["node-123"]
+}
+```
+
+Use `nodeIds: []` to clear adapter-set AX focus after a live test.
+
+## Live-Test Checklist
+
+After changing the adapter:
+
+1. Reload extensions.
+2. Inspect `pmx-canvas` and confirm status is `running`.
+3. Call `list_canvas_capabilities` for `extensionId: "project:pmx-canvas"` and
+   `canvasId: "pmx-canvas"`.
+4. Open the canvas with a stable `instanceId`.
+5. Invoke `status`.
+6. Invoke `get_ax_context`.
+7. If at least one node exists, invoke `focus_nodes` for one node ID and confirm
+   `get_ax_context.focus.nodeIds` includes it.
+8. Clear the focus with `focus_nodes` and `nodeIds: []`.
+9. Add or reuse one `html` node and one hosted MCP app node and confirm both render visibly in the
+   native PMX panel, not only in an external browser.
+10. Inspect the extension log tail and confirm there are no runtime errors.
+
+## Agent Behavior
+
+When this adapter is loaded, the next user prompt may include hidden AX context generated from PMX
+pins and focus. Treat pinned nodes and focused nodes as human-selected working context, not as a
+global instruction to ignore the rest of the repository.
+
+For non-Copilot agents, use the same core primitives directly:
+
+- HTTP: `/api/canvas/ax`, `/api/canvas/ax/context`, `/api/canvas/ax/focus`
+- MCP: `canvas://ax`, `canvas://ax-context`, `canvas_get_ax`, `canvas_set_ax_focus`
+- CLI: `pmx-canvas ax status|context|focus`

package/src/cli/agent.ts

@@ -1767,6 +1767,40 @@ cmd('pin', 'Manage context pins', [
   output(result);
 });
 
+// ── AX ────────────────────────────────────────────────────────
+cmd('ax status', 'Read host-agnostic PMX AX state', [
+  'pmx-canvas ax status',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax status');
+
+  output(await api('GET', '/api/canvas/ax'));
+});
+
+cmd('ax context', 'Read agent-ready PMX AX context', [
+  'pmx-canvas ax context',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax context');
+
+  output(await api('GET', '/api/canvas/ax/context'));
+});
+
+cmd('ax focus', 'Set or clear PMX AX focus without moving the viewport', [
+  'pmx-canvas ax focus node1 node2',
+  'pmx-canvas ax focus --clear',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax focus');
+
+  const nodeIds = flags.clear ? [] : positional;
+  if (!flags.clear && nodeIds.length === 0) {
+    die('Missing node ID', 'pmx-canvas ax focus <node-id> [more-node-ids]');
+  }
+
+  output(await api('POST', '/api/canvas/ax/focus', { nodeIds, source: 'cli' }));
+});
+
 // ── undo ─────────────────────────────────────────────────────
 cmd('undo', 'Undo the last canvas mutation', [
   'pmx-canvas undo',

package/src/cli/index.ts

@@ -31,7 +31,7 @@ if (args.includes('--version') || args.includes('-v')) {
 // If first arg is a known subcommand (not a --flag), route to the agent CLI.
 const AGENT_COMMANDS = new Set([
   'node', 'edge', 'json-render', 'search', 'layout', 'status', 'arrange', 'focus',
-  'fit', 'screenshot', 'pin', 'undo', 'redo', 'history', 'snapshot', 'diff', 'group', 'webview', 'open',
+  'fit', 'screenshot', 'pin', 'ax', 'undo', 'redo', 'history', 'snapshot', 'diff', 'group', 'webview', 'open',
   'clear', 'code-graph', 'spatial', 'watch', 'web-artifact', 'external-app', 'diagram', 'graph', 'html', 'batch', 'validate', 'serve',
 ]);
 
@@ -505,6 +505,7 @@ Agent CLI (works against running server):
   validate spec                       Validate json-render/graph payloads without creating nodes
   watch [--json] [--events ...]       Watch low-token semantic canvas changes
   focus <node-id>                     Pan to node
+  ax status|context|focus             Inspect AX state and focus
   external-app add                    Add hosted external apps like Excalidraw
   diagram add                         Add an Excalidraw diagram node
   pin <ids...> | --list | --clear     Manage context pins

package/src/client/App.tsx

@@ -38,6 +38,7 @@ import {
   walkGraph,
 } from './state/canvas-store';
 import { connectSSE } from './state/sse-bridge';
+import { saveCanvasTheme } from './state/intent-bridge';
 import {
   IconArrange,
   IconClearTrace,
@@ -240,6 +241,7 @@ function Toolbar({
               document.documentElement.setAttribute('data-theme', next);
               invalidateTokenCache();
               canvasTheme.value = next;
+              void saveCanvasTheme(next);
             }}
             aria-label={`Switch to ${canvasTheme.value === 'dark' ? 'light' : 'dark'} theme`}
           >

package/src/client/canvas/CanvasNode.tsx

@@ -56,6 +56,11 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
   // ── Drag (with snap alignment) ──────────────────────
   const handleMove = useCallback((id: string, x: number, y: number) => {
     const snap = snapToGuides(x, y, node.size.width, node.size.height);
+    const current = nodes.value.get(id);
+    if (current?.position.x === snap.x && current.position.y === snap.y) {
+      activeGuides.value = snap.guides.length > 0 ? snap.guides : null;
+      return;
+    }
     updateNode(id, { position: { x: snap.x, y: snap.y } });
     activeGuides.value = snap.guides.length > 0 ? snap.guides : null;
   }, [node.size.width, node.size.height]);
@@ -75,6 +80,8 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
 
   // ── Resize ────────────────────────────────────────────
   const handleResize = useCallback((id: string, width: number, height: number) => {
+    const current = nodes.value.get(id);
+    if (current?.size.width === width && current.size.height === height) return;
     updateNode(id, { size: { width, height } });
   }, []);
 

package/src/client/canvas/CommandPalette.tsx

@@ -8,7 +8,7 @@ import {
   nodes,
   searchHighlightIds,
 } from '../state/canvas-store';
-import { createNodeFromClient } from '../state/intent-bridge';
+import { createNodeFromClient, saveCanvasTheme } from '../state/intent-bridge';
 import { TYPE_LABELS, type CanvasNodeState } from '../types';
 import { invalidateTokenCache } from '../theme/tokens';
 
@@ -148,6 +148,7 @@ export function CommandPalette({
           document.documentElement.setAttribute('data-theme', next);
           invalidateTokenCache();
           canvasTheme.value = next;
+          void saveCanvasTheme(next);
           onClose();
         },
       },

package/src/client/canvas/use-node-drag.ts

@@ -22,27 +22,49 @@ export function useNodeDrag({ nodeId, viewport, onMove, onDragEnd }: NodeDragOpt
   const handlePointerDown = useCallback(
     (e: PointerEvent, currentX: number, currentY: number) => {
       e.stopPropagation();
+      e.preventDefault();
       isDragging.current = true;
+      document.documentElement.classList.add('is-node-dragging');
+      window.getSelection()?.removeAllRanges();
       startPointer.current = { x: e.clientX, y: e.clientY };
       startPosition.current = { x: currentX, y: currentY };
+      let pendingPointer: { x: number; y: number } | null = null;
+      let frameId: number | null = null;
 
-      const onPointerMove = (ev: PointerEvent) => {
-        if (!isDragging.current) return;
+      const flushMove = () => {
+        frameId = null;
+        if (!isDragging.current || !pendingPointer) return;
+        const pointer = pendingPointer;
+        pendingPointer = null;
         const scale = viewport.value.scale;
-        const dx = (ev.clientX - startPointer.current.x) / scale;
-        const dy = (ev.clientY - startPointer.current.y) / scale;
+        const dx = (pointer.x - startPointer.current.x) / scale;
+        const dy = (pointer.y - startPointer.current.y) / scale;
         onMove(nodeId, startPosition.current.x + dx, startPosition.current.y + dy);
       };
 
-      const onPointerUp = () => {
+      const onPointerMove = (ev: PointerEvent) => {
+        if (!isDragging.current) return;
+        pendingPointer = { x: ev.clientX, y: ev.clientY };
+        if (frameId !== null) return;
+        frameId = window.requestAnimationFrame(flushMove);
+      };
+
+      const finishDrag = () => {
+        if (frameId !== null) {
+          window.cancelAnimationFrame(frameId);
+          flushMove();
+        }
         isDragging.current = false;
+        document.documentElement.classList.remove('is-node-dragging');
         document.removeEventListener('pointermove', onPointerMove);
-        document.removeEventListener('pointerup', onPointerUp);
+        document.removeEventListener('pointerup', finishDrag);
+        document.removeEventListener('pointercancel', finishDrag);
         onDragEnd();
       };
 
       document.addEventListener('pointermove', onPointerMove);
-      document.addEventListener('pointerup', onPointerUp);
+      document.addEventListener('pointerup', finishDrag);
+      document.addEventListener('pointercancel', finishDrag);
     },
     [nodeId, viewport, onMove, onDragEnd],
   );

package/src/client/canvas/use-node-resize.ts

@@ -29,12 +29,18 @@ export function useNodeResize({ nodeId, viewport, onResize, onResizeEnd }: NodeR
       isResizing.current = true;
       startPointer.current = { x: e.clientX, y: e.clientY };
       startSize.current = { w: currentWidth, h: currentHeight };
+      document.documentElement.classList.add('is-node-resizing');
+      let pendingPointer: { x: number; y: number } | null = null;
+      let frameId: number | null = null;
 
-      const onPointerMove = (ev: PointerEvent) => {
-        if (!isResizing.current) return;
+      const flushResize = () => {
+        frameId = null;
+        if (!isResizing.current || !pendingPointer) return;
+        const pointer = pendingPointer;
+        pendingPointer = null;
         const scale = viewport.value.scale;
-        const dw = (ev.clientX - startPointer.current.x) / scale;
-        const dh = (ev.clientY - startPointer.current.y) / scale;
+        const dw = (pointer.x - startPointer.current.x) / scale;
+        const dh = (pointer.y - startPointer.current.y) / scale;
         onResize(
           nodeId,
           Math.max(MIN_WIDTH, startSize.current.w + dw),
@@ -42,15 +48,29 @@ export function useNodeResize({ nodeId, viewport, onResize, onResizeEnd }: NodeR
         );
       };
 
-      const onPointerUp = () => {
+      const onPointerMove = (ev: PointerEvent) => {
+        if (!isResizing.current) return;
+        pendingPointer = { x: ev.clientX, y: ev.clientY };
+        if (frameId !== null) return;
+        frameId = window.requestAnimationFrame(flushResize);
+      };
+
+      const finishResize = () => {
+        if (frameId !== null) {
+          window.cancelAnimationFrame(frameId);
+          flushResize();
+        }
         isResizing.current = false;
+        document.documentElement.classList.remove('is-node-resizing');
         document.removeEventListener('pointermove', onPointerMove);
-        document.removeEventListener('pointerup', onPointerUp);
+        document.removeEventListener('pointerup', finishResize);
+        document.removeEventListener('pointercancel', finishResize);
         onResizeEnd();
       };
 
       document.addEventListener('pointermove', onPointerMove);
-      document.addEventListener('pointerup', onPointerUp);
+      document.addEventListener('pointerup', finishResize);
+      document.addEventListener('pointercancel', finishResize);
     },
     [nodeId, viewport, onResize, onResizeEnd],
   );

package/src/client/nodes/ExtAppFrame.tsx

@@ -10,6 +10,7 @@ import {
   expandedNodeId,
 } from '../state/canvas-store';
 import type { CanvasNodeState } from '../types';
+import { useIframeDocument } from './iframe-document-url';
 
 type McpUiTheme = 'light' | 'dark';
 
@@ -43,7 +44,7 @@ export function getExtAppBridgeInitKey(node: CanvasNodeState, retryKey: number):
   const serverName = typeof node.data.serverName === 'string' ? node.data.serverName : '';
   const appSessionId = typeof node.data.appSessionId === 'string' ? node.data.appSessionId : '';
   const sessionStatus = typeof node.data.sessionStatus === 'string' ? node.data.sessionStatus : '';
-  return `${node.id}:${retryKey}:${node.size.height}:${serverName}:${appSessionId}:${sessionStatus}:${html}`;
+  return `${node.id}:${retryKey}:${serverName}:${appSessionId}:${sessionStatus}:${html}`;
 }
 
 export function resolveExtAppDisplayModeRequest(
@@ -111,6 +112,10 @@ export function shouldApplyExtAppSizeChange(height: unknown, isExpanded: boolean
   return typeof height === 'number' && Number.isFinite(height) && height > 0 && !isExpanded;
 }
 
+export function resolveExtAppInlineFrameHeight(appHeight: number, hostHeight: number): number {
+  return Math.max(positiveDimension(appHeight, 1), positiveDimension(hostHeight, 1));
+}
+
 export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState; expanded?: boolean }) {
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const bridgeRef = useRef<AppBridge | null>(null);
@@ -145,6 +150,8 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const maxHeight = node.size.height;
   const nodeId = node.id;
   const frameKey = getExtAppBridgeInitKey(node, retryKey);
+  const iframeSandbox = resolveExtAppSandbox(null);
+  const iframeDocument = useIframeDocument(html ?? '', iframeSandbox);
   const toMcpTheme = (theme: string): McpUiTheme => (theme === 'light' ? 'light' : 'dark');
   const isExpanded = expanded || expandedNodeId.value === nodeId;
 
@@ -202,7 +209,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
 
   // Initialize as soon as HTML is mounted; some apps send initialize before iframe load fires.
   useEffect(() => {
-    if (!html) return;
+    if (!html || !iframeDocument.ready) return;
     const iframe = iframeRef.current;
     if (!iframe) return;
     let disposed = false;
@@ -272,7 +279,11 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
       // Register handlers BEFORE connect
       bridge.onsizechange = async ({ height }) => {
         if (shouldApplyExtAppSizeChange(height, expandedNodeId.value === nodeId)) {
-          iframe.style.height = `${height}px`;
+          const hostDimensions = resolveExtAppContainerDimensions(iframe.parentElement ?? iframe, {
+            width: node.size.width,
+            height: maxHeight,
+          });
+          iframe.style.height = `${resolveExtAppInlineFrameHeight(height, hostDimensions.height)}px`;
         }
         return {};
       };
@@ -387,7 +398,11 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
       fallbackTimer = setTimeout(() => {
         if (disposed || bridgeReadyRef.current) return;
         const bootstrapToolResult = latestToolResultRef.current;
-        void sendExtAppBootstrapState(bridge, latestToolInputRef.current, bootstrapToolResult)
+        const hostContext = buildHostContext(isExpanded ? 'fullscreen' : 'inline');
+        bridgeReadyRef.current = true;
+        bridge.setHostContext?.(hostContext);
+        void Promise.resolve(bridge.sendHostContextChange(hostContext))
+          .then(() => sendExtAppBootstrapState(bridge, latestToolInputRef.current, bootstrapToolResult))
           .then(() => {
             toolResultSentRef.current = Boolean(bootstrapToolResult);
             if (bootstrapToolResult) {
@@ -424,6 +439,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
           ...buildHostContext(),
           theme: toMcpTheme(newTheme),
         });
+        void bridge.sendHostContextChange?.(buildHostContext());
       });
 
       void flushToolResult(bridge);
@@ -456,7 +472,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         transportRef.current = null;
       }
     };
-  }, [frameKey]);
+  }, [frameKey, iframeDocument.key]);
 
   // Forward tool result when it arrives after bridge is ready
   useEffect(() => {
@@ -472,6 +488,9 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   // click that triggered the expansion.
   useEffect(() => {
     const bridge = bridgeRef.current;
+    if (iframeRef.current) {
+      iframeRef.current.style.height = '100%';
+    }
     if (!bridge || !bridgeReadyRef.current) return;
     bridge.setHostContext?.({
       theme: toMcpTheme(canvasTheme.value),
@@ -484,6 +503,17 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
       locale: navigator.language,
       timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
     });
+    void bridge.sendHostContextChange?.({
+      theme: toMcpTheme(canvasTheme.value),
+      platform: 'web',
+      containerDimensions: resolveExtAppContainerDimensions(iframeRef.current, {
+        width: node.size.width,
+        height: maxHeight,
+      }),
+      displayMode: isExpanded ? 'fullscreen' : 'inline',
+      locale: navigator.language,
+      timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    });
   }, [isExpanded, maxHeight]);
 
   // Loading state — HTML not yet fetched
@@ -518,7 +548,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   }
 
   return (
-    <div style={{ height: '100%', minHeight: 0, display: 'flex', flexDirection: 'column' }}>
+    <div style={{ flex: 1, width: '100%', height: '100%', minWidth: 0, minHeight: 0, display: 'flex', flexDirection: 'column' }}>
       {sessionStatus && sessionStatus !== 'ready' && (
         <div
           style={{
@@ -598,10 +628,18 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         <iframe
           key={frameKey}
           ref={iframeRef}
-          srcdoc={html}
-          sandbox={resolveExtAppSandbox(null)}
+          {...iframeDocument.attributes}
+          sandbox={iframeSandbox}
           allow={buildAllowAttribute(resourceMeta?.permissions)}
-          style={{ flex: 1, width: '100%', height: '100%', minHeight: 0, border: 'none', background: 'var(--c-panel)' }}
+          style={{
+            flex: 1,
+            width: '100%',
+            height: '100%',
+            minHeight: 0,
+            border: 'none',
+            background: 'var(--c-panel)',
+            pointerEvents: isExpanded ? 'auto' : 'none',
+          }}
           title={`Ext App: ${toolName}`}
         />
         {!isExpanded && (
@@ -615,7 +653,10 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
             title="Click to open"
             style={{
               position: 'absolute',
-              inset: 0,
+              top: 0,
+              right: '56px',
+              bottom: '56px',
+              left: 0,
               background: 'transparent',
               border: 'none',
               padding: 0,

package/src/client/nodes/HtmlNode.tsx

@@ -2,6 +2,7 @@ import { useEffect, useMemo, useRef } from 'preact/hooks';
 import { canvasTheme } from '../state/canvas-store';
 import { getCanvasTokens } from '../theme/tokens';
 import type { CanvasNodeState } from '../types';
+import { useIframeDocument } from './iframe-document-url';
 
 /**
  * Strip characters that could break out of a CSS custom-property value context
@@ -197,6 +198,8 @@ export function HtmlNode({
       ? node.data.content
       : '';
   const srcDoc = useMemo(() => (html ? buildSrcDoc(html, { presentation, presentationExitToken, themeToken, themeCss, theme }) : ''), [html, presentation, presentationExitToken, themeToken]);
+  const iframeSandbox = 'allow-scripts';
+  const iframeDocument = useIframeDocument(srcDoc, iframeSandbox);
 
   useEffect(() => {
     iframeRef.current?.contentWindow?.postMessage({
@@ -245,8 +248,8 @@ export function HtmlNode({
       ref={iframeRef}
       class={presentation ? 'html-node-frame html-node-frame-presentation' : 'html-node-frame'}
       title={typeof node.data.title === 'string' ? node.data.title : 'HTML node'}
-      sandbox="allow-scripts"
-      srcdoc={srcDoc}
+      sandbox={iframeSandbox}
+      {...iframeDocument.attributes}
       tabIndex={autoFocus ? 0 : undefined}
       onLoad={handleFrameLoad}
       style={{

package/src/client/nodes/iframe-document-url.ts

@@ -0,0 +1,58 @@
+import { useEffect, useMemo, useState } from 'preact/hooks';
+
+interface FrameDocumentCreateResponse {
+  ok: boolean;
+  url?: string;
+  error?: string;
+}
+
+function isFrameDocumentCreateResponse(value: unknown): value is FrameDocumentCreateResponse {
+  return Boolean(value)
+    && typeof value === 'object'
+    && value !== null
+    && !Array.isArray(value)
+    && 'ok' in value
+    && typeof (value as { ok: unknown }).ok === 'boolean';
+}
+
+export async function createIframeDocumentUrl(html: string, sandbox: string): Promise<string> {
+  const response = await fetch('/api/canvas/frame-documents', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ html, sandbox }),
+  });
+  const json = await response.json() as unknown;
+  if (!response.ok || !isFrameDocumentCreateResponse(json) || !json.ok || typeof json.url !== 'string') {
+    const message = isFrameDocumentCreateResponse(json) && json.error
+      ? json.error
+      : `Frame document request failed with HTTP ${response.status}`;
+    throw new Error(message);
+  }
+  return json.url;
+}
+
+export function useIframeDocument(html: string, sandbox: string): { attributes: { src?: string }; ready: boolean; key: string } {
+  const [src, setSrc] = useState<string | null>(null);
+
+  useEffect(() => {
+    setSrc(null);
+    if (!html) return;
+    let cancelled = false;
+    void createIframeDocumentUrl(html, sandbox)
+      .then((url) => {
+        if (!cancelled) setSrc(url);
+      })
+      .catch((error) => {
+        console.error('[iframe-document] failed to create frame document:', error);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [html, sandbox]);
+
+  return useMemo(() => ({
+    attributes: src ? { src } : {},
+    ready: Boolean(src),
+    key: src ?? '',
+  }), [src]);
+}

package/src/client/state/intent-bridge.ts

@@ -104,6 +104,14 @@ export async function fetchCanvasState(): Promise<Record<string, unknown>> {
   return requestJson('fetchCanvasState', '/api/canvas/state?includeBlobs=true', {});
 }
 
+export async function saveCanvasTheme(theme: string): Promise<{ ok: boolean; theme?: string }> {
+  return requestJson('saveCanvasTheme', '/api/canvas/theme', { ok: false }, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ theme }),
+  });
+}
+
 /** Fetch available slash commands for prompt completion. */
 export async function fetchSlashCommands(): Promise<Array<{ name: string; description: string }>> {
   return [];

package/src/client/state/sse-bridge.ts

@@ -290,10 +290,10 @@ function ensureLedgerNode(summary: Record<string, unknown>): void {
 
 function applyCanvasTheme(theme: string): void {
   const valid = theme === 'dark' || theme === 'light' || theme === 'high-contrast';
-  if (!valid || canvasTheme.value === theme) return;
+  if (!valid) return;
   document.documentElement.setAttribute('data-theme', theme);
   invalidateTokenCache();
-  canvasTheme.value = theme;
+  if (canvasTheme.value !== theme) canvasTheme.value = theme;
 }
 
 function isCanvasNodeType(value: unknown): value is CanvasNodeState['type'] {

package/src/client/theme/global.css

@@ -1107,10 +1107,13 @@ body,
   position: absolute;
   bottom: 0;
   right: 0;
-  width: 16px;
-  height: 16px;
+  width: 32px;
+  height: 32px;
+  background: rgba(0, 0, 0, 0.001);
   cursor: nwse-resize;
-  z-index: 2;
+  z-index: 30;
+  pointer-events: auto;
+  touch-action: none;
 }
 
 .canvas-node .node-resize-handle::after {
@@ -1130,6 +1133,36 @@ body,
   opacity: 1;
 }
 
+html.is-node-resizing,
+html.is-node-resizing * {
+  cursor: nwse-resize !important;
+}
+
+html.is-node-resizing .canvas-node {
+  transition: box-shadow 0.15s ease !important;
+}
+
+html.is-node-dragging .attention-field-layer {
+  visibility: hidden;
+}
+
+html.is-node-dragging,
+html.is-node-dragging * {
+  cursor: grabbing !important;
+  user-select: none !important;
+  -webkit-user-select: none !important;
+}
+
+html.is-node-dragging iframe,
+html.is-node-dragging .ext-app-preview-catcher {
+  pointer-events: none !important;
+}
+
+html.is-node-resizing iframe,
+html.is-node-resizing .ext-app-preview-catcher {
+  pointer-events: none !important;
+}
+
 /* Pinned node indicator */
 .canvas-node.pinned {
   border-style: dashed;