pmx-canvas 0.1.23 → 0.1.24

package/src/server/canvas-state.ts

@@ -30,7 +30,9 @@ import {
   checkpointCanvasDb,
   finalizeCanvasDbForClose,
   type PersistedCanvasState,
+  type CanvasTheme,
 } from './canvas-db.js';
+import { normalizeCanvasTheme } from './canvas-db.js';
 import {
   type CanvasPlacementRect,
   computeGroupBounds,
@@ -39,6 +41,13 @@ import {
   GROUP_TITLEBAR_HEIGHT,
   resolveGroupCollision,
 } from './placement.js';
+import {
+  createEmptyAxState,
+  normalizeAxState,
+  type PmxAxFocusState,
+  type PmxAxSource,
+  type PmxAxState,
+} from './ax-state.js';
 
 function logCanvasStateWarning(action: string, error: unknown, details?: Record<string, unknown>): void {
   console.warn(`[canvas-state] ${action}`, { error, ...(details ?? {}) });
@@ -186,6 +195,7 @@ export interface CanvasAnnotation {
 
 export interface CanvasLayout {
   viewport: ViewportState;
+  theme: CanvasTheme;
   nodes: CanvasNodeState[];
   edges: CanvasEdge[];
   annotations: CanvasAnnotation[];
@@ -199,10 +209,10 @@ export interface CanvasNodeUpdate {
   dockPosition?: 'left' | 'right' | null;
 }
 
-export type CanvasChangeType = 'pins' | 'nodes';
+export type CanvasChangeType = 'pins' | 'nodes' | 'ax';
 
 export interface MutationRecordInfo {
-  operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
+  operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
   description: string;
   forward: () => void;
   inverse: () => void;
@@ -260,7 +270,9 @@ class CanvasStateManager {
   private edges = new Map<string, CanvasEdge>();
   private annotations = new Map<string, CanvasAnnotation>();
   private _viewport: ViewportState = { x: 0, y: 0, scale: 1 };
+  private _theme: CanvasTheme = 'dark';
   private _contextPinnedNodeIds = new Set<string>();
+  private _axState: PmxAxState = createEmptyAxState();
   private _workspaceRoot = process.cwd();
 
   // ── Change listeners (for MCP resource notifications) ──────
@@ -310,6 +322,18 @@ class CanvasStateManager {
     }
   }
 
+  private currentNodeIdSet(): Set<string> {
+    return new Set(this.nodes.keys());
+  }
+
+  private normalizeAxForCurrentNodes(state: unknown): PmxAxState {
+    return normalizeAxState(state, this.currentNodeIdSet());
+  }
+
+  private applyAxState(state: PmxAxState): void {
+    this._axState = this.normalizeAxForCurrentNodes(state);
+  }
+
   private applyResolvedGroupBounds(
     group: CanvasNodeState,
     groupId: string,
@@ -788,11 +812,13 @@ class CanvasStateManager {
   private emptyPersistedState(): PersistedCanvasState {
     return {
       version: 1,
+      theme: this._theme,
       viewport: { x: 0, y: 0, scale: 1 },
       nodes: [],
       edges: [],
       annotations: [],
       contextPins: [],
+      ax: createEmptyAxState(),
     };
   }
 
@@ -863,11 +889,13 @@ class CanvasStateManager {
     try {
       const payload = this.externalizePersistedStateBlobs({
         version: 1,
+        theme: this._theme,
         viewport: this._viewport,
         nodes: Array.from(this.nodes.values()),
         edges: Array.from(this.edges.values()),
         annotations: Array.from(this.annotations.values()),
         contextPins: Array.from(this._contextPinnedNodeIds),
+        ax: this.getAxState(),
       });
       saveStateToDB(this._db, payload);
     } catch (error) {
@@ -909,12 +937,14 @@ class CanvasStateManager {
     this.edges.clear();
     this.annotations.clear();
     this._contextPinnedNodeIds.clear();
+    this._axState = createEmptyAxState();
 
     this._viewport = {
       x: state.viewport?.x ?? 0,
       y: state.viewport?.y ?? 0,
       scale: state.viewport?.scale ?? 1,
     };
+    this._theme = normalizeCanvasTheme(state.theme, this._theme);
 
     if (Array.isArray(state.nodes)) {
       for (const node of state.nodes) {
@@ -938,6 +968,7 @@ class CanvasStateManager {
         if (this.nodes.has(pinId)) this._contextPinnedNodeIds.add(pinId);
       }
     }
+    this._axState = this.normalizeAxForCurrentNodes(state.ax);
   }
 
   private readResolvedSnapshot(idOrName: string): {
@@ -1028,11 +1059,13 @@ class CanvasStateManager {
     try {
       const payload = this.externalizePersistedStateBlobs({
         version: 1,
+        theme: this._theme,
         viewport: this._viewport,
         nodes: Array.from(this.nodes.values()),
         edges: Array.from(this.edges.values()),
         annotations: Array.from(this.annotations.values()),
         contextPins: Array.from(this._contextPinnedNodeIds),
+        ax: this.getAxState(),
       });
       saveSnapshotToDB(this._db, snapshot, payload);
       snapshot.nodeCount = payload.nodes.length;
@@ -1117,19 +1150,23 @@ class CanvasStateManager {
 
     const previousState: PersistedCanvasState = this.externalizePersistedStateBlobs({
       version: 1,
+      theme: this._theme,
       viewport: structuredClone(this._viewport),
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(node)),
       edges: Array.from(this.edges.values(), (edge) => structuredClone(edge)),
       annotations: Array.from(this.annotations.values(), (annotation) => structuredClone(annotation)),
       contextPins: Array.from(this._contextPinnedNodeIds),
+      ax: this.getAxState(),
     });
     const nextState: PersistedCanvasState = {
       version: 1,
+      theme: normalizeCanvasTheme(resolved.state.theme, this._theme),
       viewport: structuredClone(resolved.state.viewport),
       nodes: Array.isArray(resolved.state.nodes) ? resolved.state.nodes.map((node) => structuredClone(node)) : [],
       edges: Array.isArray(resolved.state.edges) ? resolved.state.edges.map((edge) => structuredClone(edge)) : [],
       annotations: Array.isArray(resolved.state.annotations) ? resolved.state.annotations.map((annotation) => structuredClone(annotation)) : [],
       contextPins: Array.isArray(resolved.state.contextPins) ? [...resolved.state.contextPins] : [],
+      ax: resolved.state.ax ? structuredClone(resolved.state.ax) : createEmptyAxState(),
     };
 
     try {
@@ -1137,6 +1174,7 @@ class CanvasStateManager {
       this.scheduleSave();
       this.notifyChange('nodes');
       this.notifyChange('pins');
+      this.notifyChange('ax');
       this.recordMutation({
         operationType: 'restoreSnapshot',
         description: `Restored snapshot "${resolved.snapshot.name}"`,
@@ -1145,12 +1183,14 @@ class CanvasStateManager {
           this.scheduleSave();
           this.notifyChange('nodes');
           this.notifyChange('pins');
+          this.notifyChange('ax');
         }),
         inverse: this.suppressed(() => {
           this.applyPersistedState(previousState);
           this.scheduleSave();
           this.notifyChange('nodes');
           this.notifyChange('pins');
+          this.notifyChange('ax');
         }),
       });
       return true;
@@ -1287,6 +1327,7 @@ class CanvasStateManager {
     const existing = this.nodes.get(id);
     const connectedEdges = existing ? this.getEdgesForNode(id).map((e) => structuredClone(e)) : [];
     const cloned = existing ? structuredClone(existing) : null;
+    const oldAxState = this.getAxState();
 
     // Prune from parent group's children list
     if (existing) {
@@ -1315,9 +1356,11 @@ class CanvasStateManager {
     this.nodes.delete(id);
     this.removeEdgesForNode(id);
     this._contextPinnedNodeIds.delete(id);
+    this.applyAxState(this._axState);
     this.scheduleSave();
     this.notifyChange('nodes');
     this.notifyChange('pins');
+    this.notifyChange('ax');
     if (cloned) {
       this.recordMutation({
         operationType: 'removeNode',
@@ -1326,6 +1369,9 @@ class CanvasStateManager {
         inverse: this.suppressed(() => {
           this.addNode(structuredClone(cloned));
           for (const edge of connectedEdges) this.addEdge(structuredClone(edge));
+          this.applyAxState(oldAxState);
+          this.scheduleSave();
+          this.notifyChange('ax');
         }),
       });
     }
@@ -1435,6 +1481,7 @@ class CanvasStateManager {
   getLayout(): CanvasLayout {
     return {
       viewport: structuredClone(this._viewport),
+      theme: this._theme,
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(node)),
       edges: Array.from(this.edges.values(), (edge) => structuredClone(edge)),
       annotations: this.getAnnotations(),
@@ -1444,6 +1491,7 @@ class CanvasStateManager {
   getLayoutForPersistence(): CanvasLayout {
     return {
       viewport: structuredClone(this._viewport),
+      theme: this._theme,
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(this.externalizeNodeDataBlobs(node))),
       edges: Array.from(this.edges.values(), (edge) => structuredClone(edge)),
       annotations: this.getAnnotations(),
@@ -1563,12 +1611,70 @@ class CanvasStateManager {
     });
   }
 
+  get theme(): CanvasTheme {
+    return this._theme;
+  }
+
+  setTheme(theme: CanvasTheme): CanvasTheme {
+    const next = normalizeCanvasTheme(theme, this._theme);
+    if (next === this._theme) return this._theme;
+    this._theme = next;
+    this.scheduleSave();
+    this.notifyChange('nodes');
+    return this._theme;
+  }
+
   // ── Context pins ─────────────────────────────────────────────
 
   get contextPinnedNodeIds(): Set<string> {
     return new Set(this._contextPinnedNodeIds);
   }
 
+  getAxState(): PmxAxState {
+    return structuredClone(this.normalizeAxForCurrentNodes(this._axState));
+  }
+
+  getAxFocus(): PmxAxFocusState {
+    return this.getAxState().focus;
+  }
+
+  setAxFocus(nodeIds: string[], options: { source?: PmxAxSource; recordHistory?: boolean } = {}): PmxAxFocusState {
+    const oldAxState = this.getAxState();
+    const nextAxState: PmxAxState = {
+      ...oldAxState,
+      focus: {
+        nodeIds,
+        primaryNodeId: nodeIds[0] ?? null,
+        updatedAt: new Date().toISOString(),
+        source: options.source ?? 'api',
+      },
+    };
+    this.applyAxState(nextAxState);
+    const appliedAxState = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    if (options.recordHistory === false) return appliedAxState.focus;
+    this.recordMutation({
+      operationType: 'setAxFocus',
+      description: `Set AX focus (${appliedAxState.focus.nodeIds.length} nodes)`,
+      forward: this.suppressed(() => {
+        this.applyAxState(appliedAxState);
+        this.scheduleSave();
+        this.notifyChange('ax');
+      }),
+      inverse: this.suppressed(() => {
+        this.applyAxState(oldAxState);
+        this.scheduleSave();
+        this.notifyChange('ax');
+      }),
+    });
+    return appliedAxState.focus;
+  }
+
+  clearAxFocus(): PmxAxFocusState {
+    return this.setAxFocus([], { source: 'system' });
+  }
+
   setContextPins(nodeIds: string[]): void {
     const oldPins = Array.from(this._contextPinnedNodeIds);
     this._contextPinnedNodeIds.clear();
@@ -1694,15 +1800,18 @@ class CanvasStateManager {
     const oldEdges = Array.from(this.edges.values()).map((e) => structuredClone(e));
     const oldAnnotations = Array.from(this.annotations.values()).map((annotation) => structuredClone(annotation));
     const oldPins = Array.from(this._contextPinnedNodeIds);
+    const oldAxState = this.getAxState();
     const oldViewport = { ...this._viewport };
     this.nodes.clear();
     this.edges.clear();
     this.annotations.clear();
     this._contextPinnedNodeIds.clear();
+    this._axState = createEmptyAxState();
     this._viewport = { x: 0, y: 0, scale: 1 };
     this.scheduleSave();
     this.notifyChange('nodes');
     this.notifyChange('pins');
+    this.notifyChange('ax');
     this.recordMutation({
       operationType: 'clear',
       description: `Cleared canvas (was ${oldNodes.length} nodes, ${oldEdges.length} edges)`,
@@ -1712,7 +1821,9 @@ class CanvasStateManager {
         for (const e of oldEdges) this.addEdge(structuredClone(e));
         for (const annotation of oldAnnotations) this.addAnnotation(structuredClone(annotation));
         this.setContextPins(oldPins);
+        this.applyAxState(oldAxState);
         this.setViewport(oldViewport);
+        this.notifyChange('ax');
       }),
     });
   }

package/src/server/index.ts

@@ -1,6 +1,8 @@
 import { EventEmitter } from 'node:events';
 import { canvasState, IMAGE_MIME_MAP } from './canvas-state.js';
 import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from './canvas-state.js';
+import { buildCanvasAxContext } from './ax-context.js';
+import type { PmxAxContext, PmxAxFocusState, PmxAxSource, PmxAxState } from './ax-state.js';
 import { findCanvasExtAppNodeId } from './ext-app-lookup.js';
 import { onFileNodeChanged } from './file-watcher.js';
 import { findOpenCanvasPosition, computeGroupBounds } from './placement.js';
@@ -402,7 +404,9 @@ export class PmxCanvas extends EventEmitter {
         y: node.position.y - 100,
       });
     }
+    const focus = canvasState.setAxFocus([id], { source: 'sdk', recordHistory: false });
     emitPrimaryWorkbenchEvent('canvas-focus-node', { nodeId: id, noPan });
+    emitPrimaryWorkbenchEvent('ax-state-changed', { focus });
     if (!noPan) {
       emitPrimaryWorkbenchEvent('canvas-viewport-update', { viewport: canvasState.viewport });
     }
@@ -410,6 +414,20 @@ export class PmxCanvas extends EventEmitter {
     return { focused: id, panned: !noPan };
   }
 
+  getAxState(): PmxAxState {
+    return canvasState.getAxState();
+  }
+
+  getAxContext(): PmxAxContext {
+    return buildCanvasAxContext();
+  }
+
+  setAxFocus(nodeIds: string[], options?: { source?: PmxAxSource }): PmxAxFocusState {
+    const focus = canvasState.setAxFocus(nodeIds, { source: options?.source ?? 'sdk' });
+    emitPrimaryWorkbenchEvent('ax-state-changed', { focus });
+    return focus;
+  }
+
   fitView(options?: {
     width?: number;
     height?: number;

package/src/server/mutation-history.ts

@@ -28,6 +28,7 @@ export type MutationOp =
   | 'arrange'
   | 'restoreSnapshot'
   | 'setPins'
+  | 'setAxFocus'
   | 'batch'
   | 'viewport'
   | 'groupNodes'

package/src/server/server.ts

@@ -35,6 +35,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { basename, extname, join, relative, resolve } from 'node:path';
@@ -75,6 +76,9 @@ import {
 } from './canvas-serialization.js';
 import { buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
+import { buildCanvasAxContext } from './ax-context.js';
+import type { PmxAxSource } from './ax-state.js';
+import { normalizeCanvasTheme, type CanvasTheme } from './canvas-db.js';
 import { validateLocalImageFile } from './image-source.js';
 import {
   addCanvasNode,
@@ -145,9 +149,7 @@ let nextWorkbenchSubscriberId = 1;
 const workbenchSubscribers = new Map<number, ReadableStreamDefaultController<Uint8Array>>();
 const textEncoder = new TextEncoder();
 let primaryWorkbenchAutoOpenEnabled = true;
-const canvasThemeSetting = (['dark', 'light', 'high-contrast'].includes(process.env.PMX_CANVAS_THEME ?? '')
-  ? process.env.PMX_CANVAS_THEME!
-  : 'dark');
+const initialCanvasThemeSetting = normalizeCanvasTheme(process.env.PMX_CANVAS_THEME);
 let lastWorkbenchContextCardsEnvelope: Record<string, unknown> | null = null;
 
 function normalizeGraphViewerSpec(
@@ -1038,6 +1040,24 @@ function normalizeMarkdownExternalUrls(markdown: string): string {
 
 // ── Canvas SPA HTML ────────────────────────────────────────────
 
+const CANVAS_ASSET_VERSION = Date.now().toString(36);
+const MAX_FRAME_DOCUMENTS = 128;
+const MAX_FRAME_DOCUMENT_BYTES = 5 * 1024 * 1024;
+const DEFAULT_FRAME_DOCUMENT_SANDBOX = 'allow-scripts';
+const SAFE_FRAME_DOCUMENT_SANDBOX_TOKENS = new Set([
+  'allow-downloads',
+  'allow-forms',
+  'allow-modals',
+  'allow-orientation-lock',
+  'allow-pointer-lock',
+  'allow-popups',
+  'allow-popups-to-escape-sandbox',
+  'allow-presentation',
+  'allow-scripts',
+  'allow-storage-access-by-user-activation',
+]);
+const frameDocuments = new Map<string, { html: string; sandbox: string }>();
+
 function canvasSpaHtml(): string {
   return `<!doctype html>
 <html lang="en">
@@ -1106,7 +1126,7 @@ function canvasSpaHtml(): string {
       color: #eef4ff;
     }
   </style>
-  <link rel="stylesheet" href="/canvas/global.css" />
+  <link rel="stylesheet" href="/canvas/global.css?v=${CANVAS_ASSET_VERSION}" />
 </head>
 <body>
   <div id="canvasBootstrap">
@@ -1143,7 +1163,7 @@ function canvasSpaHtml(): string {
       }, 4000);
     })();
   </script>
-  <script type="module" src="/canvas/index.js"></script>
+  <script type="module" src="/canvas/index.js?v=${CANVAS_ASSET_VERSION}"></script>
 </body>
 </html>`;
 }
@@ -1229,6 +1249,61 @@ function serveCanvasFavicon(): Response {
 
 // ── Canvas REST handlers ──────────────────────────────────────
 
+function normalizeFrameDocumentSandbox(value: unknown): string | null {
+  if (value === undefined || value === null) return DEFAULT_FRAME_DOCUMENT_SANDBOX;
+  if (typeof value !== 'string') return null;
+  const tokens = value.trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return DEFAULT_FRAME_DOCUMENT_SANDBOX;
+  const uniqueTokens: string[] = [];
+  for (const token of tokens) {
+    if (!SAFE_FRAME_DOCUMENT_SANDBOX_TOKENS.has(token)) return null;
+    if (!uniqueTokens.includes(token)) uniqueTokens.push(token);
+  }
+  return uniqueTokens.join(' ');
+}
+
+function addFrameDocument(html: string, sandbox: string): string {
+  const id = randomUUID();
+  frameDocuments.set(id, { html, sandbox });
+  while (frameDocuments.size > MAX_FRAME_DOCUMENTS) {
+    const firstKey = frameDocuments.keys().next().value;
+    if (typeof firstKey !== 'string') break;
+    frameDocuments.delete(firstKey);
+  }
+  return `/api/canvas/frame-documents/${id}`;
+}
+
+async function handleCreateFrameDocument(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const html = body.html;
+  if (typeof html !== 'string' || !html) {
+    return responseJson({ ok: false, error: 'Frame document requires non-empty html.' }, 400);
+  }
+  if (new TextEncoder().encode(html).byteLength > MAX_FRAME_DOCUMENT_BYTES) {
+    return responseJson({ ok: false, error: 'Frame document is too large.' }, 413);
+  }
+  const sandbox = normalizeFrameDocumentSandbox(body.sandbox);
+  if (!sandbox) {
+    return responseJson({ ok: false, error: 'Frame document sandbox contains unsupported tokens.' }, 400);
+  }
+  return responseJson({ ok: true, url: addFrameDocument(html, sandbox) });
+}
+
+function handleFrameDocument(pathname: string): Response {
+  const id = decodeURIComponent(pathname.slice('/api/canvas/frame-documents/'.length));
+  const document = frameDocuments.get(id);
+  if (!document) return responseText('Frame document not found.', 404);
+  return new Response(document.html, {
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store',
+      'Content-Security-Policy': `sandbox ${document.sandbox}`,
+      'Referrer-Policy': 'no-referrer',
+      'X-Content-Type-Options': 'nosniff',
+    },
+  });
+}
+
 async function handleCanvasUpdate(req: Request): Promise<Response> {
   const body = await readJson(req);
   const updates = Array.isArray(body.updates) ? body.updates : [];
@@ -1817,10 +1892,16 @@ async function handleCanvasFocus(req: Request): Promise<Response> {
     const maxZ = canvasState.getLayout().nodes.reduce((max, layoutNode) => Math.max(max, layoutNode.zIndex), 0);
     canvasState.updateNode(nodeId, { zIndex: maxZ + 1 });
   }
+  const focus = canvasState.setAxFocus([nodeId], { source: 'api', recordHistory: false });
+  broadcastWorkbenchEvent('ax-state-changed', {
+    focus,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
   emitPrimaryWorkbenchEvent('canvas-focus-node', { nodeId, noPan });
   if (!noPan) emitPrimaryWorkbenchEvent('canvas-viewport-update', { viewport: canvasState.viewport });
   emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
-  return responseJson({ ok: true, focused: nodeId, panned: !noPan });
+  return responseJson({ ok: true, focused: nodeId, panned: !noPan, axFocus: focus });
 }
 
 async function handleCanvasFit(req: Request): Promise<Response> {
@@ -2105,6 +2186,18 @@ function handleCanvasValidate(): Response {
   return responseJson(validateCanvasLayout(canvasState.getLayout()));
 }
 
+async function handleCanvasThemeUpdate(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const theme = normalizeCanvasTheme(body.theme, canvasState.theme);
+  const next = canvasState.setTheme(theme);
+  broadcastWorkbenchEvent('theme-changed', {
+    theme: next,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, theme: next });
+}
+
 async function handleJsonRenderView(url: URL): Promise<Response> {
   const nodeId = url.searchParams.get('nodeId') ?? '';
   if (!nodeId) return responseText('Missing nodeId', 400);
@@ -2973,7 +3066,7 @@ function handleWorkbenchEvents(req: Request): Response {
           requestedSessionId: requestedSessionId || null,
           continuity,
           path: primaryWorkbenchPath,
-          theme: canvasThemeSetting,
+          theme: canvasState.theme,
           timestamp: new Date().toISOString(),
         }),
       );
@@ -3391,6 +3484,63 @@ function handleGetPinnedContext(): Response {
   return responseJson({ preamble, nodeIds: pinnedIds, count: pinnedIds.length, nodes });
 }
 
+function normalizeAxNodeIds(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((id): id is string => typeof id === 'string');
+}
+
+function normalizeAxSource(value: unknown, fallback: PmxAxSource): PmxAxSource {
+  return value === 'agent' ||
+    value === 'api' ||
+    value === 'browser' ||
+    value === 'cli' ||
+    value === 'codex' ||
+    value === 'copilot' ||
+    value === 'mcp' ||
+    value === 'sdk' ||
+    value === 'system'
+    ? value
+    : fallback;
+}
+
+function handleGetAxState(): Response {
+  return responseJson({ ok: true, state: canvasState.getAxState() });
+}
+
+function handleGetAxContext(): Response {
+  return responseJson(buildCanvasAxContext());
+}
+
+async function handleAxFocusUpdate(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const nodeIds = normalizeAxNodeIds(body.nodeIds);
+  const source = normalizeAxSource(body.source, 'api');
+  const focus = canvasState.setAxFocus(nodeIds, { source });
+  broadcastWorkbenchEvent('ax-state-changed', {
+    focus,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, focus });
+}
+
+async function handleAxStatePatch(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  if (!body.focus || typeof body.focus !== 'object' || Array.isArray(body.focus)) {
+    return responseJson({ ok: false, error: 'PATCH /api/canvas/ax currently requires a focus object.' }, 400);
+  }
+  const focusInput = body.focus as Record<string, unknown>;
+  const focus = canvasState.setAxFocus(normalizeAxNodeIds(focusInput.nodeIds), {
+    source: normalizeAxSource(focusInput.source, 'api'),
+  });
+  broadcastWorkbenchEvent('ax-state-changed', {
+    focus,
+    sessionId: primaryWorkbenchSessionId,
+    timestamp: new Date().toISOString(),
+  });
+  return responseJson({ ok: true, state: canvasState.getAxState() });
+}
+
 // ── Port resolution ───────────────────────────────────────────
 
 function buildPortCandidates(preferredPort: number): number[] {
@@ -4075,6 +4225,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
 
   // ── Canvas persistence: set workspace root and load saved state ──
   canvasState.setWorkspaceRoot(activeWorkspaceRoot);
+  canvasState.setTheme(initialCanvasThemeSetting as CanvasTheme);
   const loaded = canvasState.loadFromDisk({ clearExisting: true });
   setCanvasLayoutUpdateEmitter(() => {
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
@@ -4090,7 +4241,9 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
   rotatePrimaryWorkbenchSessionIfNeeded();
 
   const preferredPort = options.port ?? Number(process.env.PMX_WEB_CANVAS_PORT ?? DEFAULT_PORT);
-  const portCandidates = options.allowPortFallback === false
+  const portCandidates = options.port === 0
+    ? [0]
+    : options.allowPortFallback === false
     ? [preferredPort > 0 ? Math.floor(preferredPort) : DEFAULT_PORT]
     : buildPortCandidates(preferredPort);
 
@@ -4119,6 +4272,14 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleJsonRenderView(url);
           }
 
+          if (url.pathname === '/api/canvas/frame-documents' && req.method === 'POST') {
+            return handleCreateFrameDocument(req);
+          }
+
+          if (url.pathname.startsWith('/api/canvas/frame-documents/') && req.method === 'GET') {
+            return handleFrameDocument(url.pathname);
+          }
+
           if (url.pathname === '/' || url.pathname === '/workbench' || url.pathname === '/artifact') {
             return new Response(canvasSpaHtml(), {
               headers: {
@@ -4192,6 +4353,14 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return responseJson(buildCanvasSummary());
           }
 
+          if (url.pathname === '/api/canvas/theme' && req.method === 'GET') {
+            return responseJson({ ok: true, theme: canvasState.theme });
+          }
+
+          if (url.pathname === '/api/canvas/theme' && req.method === 'POST') {
+            return handleCanvasThemeUpdate(req);
+          }
+
           if (url.pathname === '/api/canvas/update' && req.method === 'POST') {
             return handleCanvasUpdate(req);
           }
@@ -4334,6 +4503,22 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleGetPinnedContext();
           }
 
+          if (url.pathname === '/api/canvas/ax' && req.method === 'GET') {
+            return handleGetAxState();
+          }
+
+          if (url.pathname === '/api/canvas/ax' && req.method === 'PATCH') {
+            return handleAxStatePatch(req);
+          }
+
+          if (url.pathname === '/api/canvas/ax/context' && req.method === 'GET') {
+            return handleGetAxContext();
+          }
+
+          if (url.pathname === '/api/canvas/ax/focus' && req.method === 'POST') {
+            return handleAxFocusUpdate(req);
+          }
+
           // Spatial context API
           if (url.pathname === '/api/canvas/spatial-context' && req.method === 'GET') {
             const layout = canvasState.getLayout();