pmx-canvas 0.1.28 → 0.1.30

package/src/server/server.ts

@@ -48,6 +48,7 @@ import type {
   ListToolsResult,
 } from '@modelcontextprotocol/sdk/types.js';
 import { type CanvasAnnotation, type CanvasEdge, type CanvasLayout, type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
+import { buildHtmlSurfaceDocument, HTML_SURFACE_SANDBOX, normalizeSurfaceTheme } from './html-surface.js';
 import { findCanvasExtAppNodeId as findCanvasExtAppNodeIdShared } from './ext-app-lookup.js';
 import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
 import { getMcpAppHostSnapshot } from './mcp-app-host.js';
@@ -77,8 +78,10 @@ import {
 import { buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
 import { buildCanvasAxContext } from './ax-context.js';
+import { applyAxInteraction, resolveNodeAxCapabilities } from './ax-interaction.js';
 import { isAxEventKind, isAxEvidenceKind } from './ax-state.js';
 import type {
+  PmxAxPolicy,
   PmxAxReviewAnchorType,
   PmxAxReviewKind,
   PmxAxReviewRegion,
@@ -1376,6 +1379,108 @@ function handleFrameDocument(pathname: string): Response {
   });
 }
 
+// ── Node surfaces ("Open as site") ─────────────────────────────
+//
+// One stable, node-addressable URL — /api/canvas/surface/:nodeId — that serves
+// (or redirects to) the exact same rendered surface a node shows in the canvas.
+// The in-canvas html iframe points at this URL too, so there is one render path.
+//
+// Served document types (html / ext-app) carry the same opaque-origin posture as
+// frame documents: `Content-Security-Policy: sandbox <tokens>` (no
+// allow-same-origin) means author scripts cannot reach the PMX origin even when
+// the page is opened top-level in a browser tab. Other types redirect to the
+// route that already renders them standalone.
+
+function surfaceHtmlResponse(html: string, sandbox: string): Response {
+  return new Response(html, {
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store',
+      'Content-Security-Policy': `sandbox ${sandbox}`,
+      'Referrer-Policy': 'no-referrer',
+      'X-Content-Type-Options': 'nosniff',
+    },
+  });
+}
+
+function surfaceRedirect(target: string): Response {
+  return new Response(null, { status: 302, headers: { Location: target, 'Cache-Control': 'no-store' } });
+}
+
+// Permit only absolute http(s) URLs and root-relative same-origin paths. Blocks
+// `javascript:`/`data:` and protocol-relative `//host` open-redirects.
+function isSafeSurfaceRedirect(target: string): boolean {
+  if (/^https?:\/\//i.test(target)) return true;
+  if (/^\/(?!\/)/.test(target)) return true;
+  return false;
+}
+
+function handleNodeSurface(pathname: string, url: URL): Response {
+  const nodeId = decodeURIComponent(pathname.slice('/api/canvas/surface/'.length));
+  if (!nodeId) return responseText('Missing node id', 400);
+  const node = canvasState.getNode(nodeId);
+  if (!node) return responseText('Node not found', 404);
+
+  const theme = normalizeSurfaceTheme(url.searchParams.get('theme'));
+
+  if (node.type === 'html') {
+    const html = typeof node.data.html === 'string'
+      ? node.data.html
+      : typeof node.data.content === 'string'
+        ? node.data.content
+        : '';
+    if (!html) return responseText('HTML node has no content', 404);
+    const present = url.searchParams.get('present') === '1';
+    const axCaps = resolveNodeAxCapabilities(node);
+    const doc = buildHtmlSurfaceDocument(html, {
+      theme,
+      themeToken: url.searchParams.get('themeToken') ?? undefined,
+      presentation: present,
+      presentationExitToken: url.searchParams.get('presentToken') ?? undefined,
+      axBridge: axCaps.enabled && axCaps.allowed.length > 0,
+      axToken: url.searchParams.get('axToken') ?? undefined,
+      nodeId: node.id,
+    });
+    return surfaceHtmlResponse(doc, HTML_SURFACE_SANDBOX);
+  }
+
+  if (node.type === 'json-render' || node.type === 'graph') {
+    const params = new URLSearchParams({ nodeId, theme });
+    const display = url.searchParams.get('display');
+    if (display === 'expanded') params.set('display', 'expanded');
+    return surfaceRedirect(`/api/canvas/json-render/view?${params.toString()}`);
+  }
+
+  if (node.type === 'mcp-app') {
+    // Bundled web artifact — same standalone page the canvas iframe already loads.
+    if (node.data.viewerType === 'web-artifact' && typeof node.data.path === 'string' && node.data.path) {
+      return surfaceRedirect(`/artifact?path=${encodeURIComponent(node.data.path)}`);
+    }
+    // Hosted ext-app — serve the same prepared HTML the in-canvas frame receives.
+    // The app's host bridge has no peer in a standalone tab, so interactive
+    // tool-calls won't function there; the UI still renders. Served TOP-LEVEL with
+    // a tighter sandbox than the in-canvas iframe (no allow-popups-to-escape-sandbox)
+    // since this is untrusted third-party HTML opened as its own page.
+    if (node.data.mode === 'ext-app' && typeof node.data.html === 'string' && node.data.html) {
+      return surfaceHtmlResponse(node.data.html, HTML_SURFACE_SANDBOX);
+    }
+    // URL-backed viewer — hand off to its own origin.
+    if (typeof node.data.url === 'string' && isSafeSurfaceRedirect(node.data.url)) {
+      return surfaceRedirect(node.data.url);
+    }
+    return responseText('MCP app node has no openable surface', 404);
+  }
+
+  if (node.type === 'webpage') {
+    if (typeof node.data.url === 'string' && isSafeSurfaceRedirect(node.data.url)) {
+      return surfaceRedirect(node.data.url);
+    }
+    return responseText('Webpage node has no url', 404);
+  }
+
+  return responseText('Node type cannot be opened as a site', 404);
+}
+
 async function handleCanvasUpdate(req: Request): Promise<Response> {
   const body = await readJson(req);
   const updates = Array.isArray(body.updates) ? body.updates : [];
@@ -1542,6 +1647,9 @@ function buildNodeResponse(node: CanvasNodeState): Record<string, unknown> {
     ok: true,
     node: serialized,
     ...serialized,
+    // `nodeId` aliases `id` so HTTP/CLI node-create responses match the MCP
+    // createdNodePayload — agents using either key (or a cached schema) work.
+    nodeId: node.id,
   };
 }
 
@@ -2423,12 +2531,14 @@ async function handleJsonRenderView(url: URL): Promise<Response> {
   const devtoolsEnabled =
     process.env.PMX_CANVAS_JSON_RENDER_DEVTOOLS === '1' &&
     url.searchParams.get('devtools') === '1';
+  const axToken = url.searchParams.get('axToken');
   const html = await buildJsonRenderViewerHtml({
     title,
     spec,
     ...(theme ? { theme } : {}),
     ...(url.searchParams.get('display') === 'expanded' ? { display: 'expanded' as const } : {}),
     ...(devtoolsEnabled ? { devtools: true } : {}),
+    ...(axToken ? { nodeId, axToken } : {}),
   });
   return new Response(html, {
     headers: {
@@ -3713,6 +3823,136 @@ function handleGetAxContext(): Response {
   return responseJson(buildCanvasAxContext());
 }
 
+async function handleAxInteraction(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const { result, events } = applyAxInteraction(canvasState, body, normalizeAxSource(body.source, 'api'));
+  for (const e of events) {
+    broadcastWorkbenchEvent(e.event, {
+      ...e.payload,
+      sessionId: primaryWorkbenchSessionId,
+      timestamp: new Date().toISOString(),
+    });
+  }
+  return responseJson(result, result.ok ? 200 : result.status);
+}
+
+function handleAxDeliveryPending(url: URL): Response {
+  const consumer = url.searchParams.get('consumer') ?? undefined;
+  const limitRaw = Number(url.searchParams.get('limit') ?? '');
+  const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? limitRaw : undefined;
+  const pending = canvasState.getPendingSteering({
+    ...(consumer ? { consumer } : {}),
+    ...(limit ? { limit } : {}),
+  });
+  return responseJson({ ok: true, pending });
+}
+
+function handleAxDeliveryMark(id: string): Response {
+  const delivered = canvasState.markSteeringDelivered(id);
+  if (delivered) {
+    broadcastWorkbenchEvent('ax-event-created', {
+      steeringDelivered: id,
+      sessionId: primaryWorkbenchSessionId,
+      timestamp: new Date().toISOString(),
+    });
+  }
+  return responseJson({ ok: true, delivered });
+}
+
+function handleAxElicitationList(): Response {
+  return responseJson({ ok: true, elicitations: canvasState.getElicitations() });
+}
+
+async function handleAxElicitationRequest(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  if (typeof body.prompt !== 'string' || !body.prompt.trim()) {
+    return responseJson({ ok: false, error: 'elicitation requires a prompt.' }, 400);
+  }
+  const elicitation = canvasState.requestElicitation(
+    {
+      prompt: body.prompt,
+      ...(Array.isArray(body.fields) ? { fields: body.fields.filter((f: unknown): f is string => typeof f === 'string') } : {}),
+      ...(Array.isArray(body.nodeIds) ? { nodeIds: normalizeAxNodeIds(body.nodeIds) } : {}),
+    },
+    { source: normalizeAxSource(body.source, 'api') },
+  );
+  broadcastWorkbenchEvent('ax-state-changed', { elicitation, sessionId: primaryWorkbenchSessionId, timestamp: new Date().toISOString() });
+  return responseJson({ ok: true, elicitation });
+}
+
+async function handleAxElicitationRespond(req: Request, id: string): Promise<Response> {
+  const body = await readJson(req);
+  const response = isRecord(body.response) ? body.response : {};
+  const elicitation = canvasState.respondElicitation(id, response, { source: normalizeAxSource(body.source, 'api') });
+  if (!elicitation) return responseJson({ ok: false, error: 'elicitation not found or already answered.' }, 404);
+  broadcastWorkbenchEvent('ax-state-changed', { elicitation, sessionId: primaryWorkbenchSessionId, timestamp: new Date().toISOString() });
+  return responseJson({ ok: true, elicitation });
+}
+
+function handleAxModeList(): Response {
+  return responseJson({ ok: true, modeRequests: canvasState.getModeRequests() });
+}
+
+async function handleAxModeRequest(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  if (body.mode !== 'plan' && body.mode !== 'execute' && body.mode !== 'autonomous') {
+    return responseJson({ ok: false, error: 'mode request requires mode plan|execute|autonomous.' }, 400);
+  }
+  const modeRequest = canvasState.requestMode(
+    {
+      mode: body.mode,
+      ...(typeof body.reason === 'string' ? { reason: body.reason } : {}),
+      ...(Array.isArray(body.nodeIds) ? { nodeIds: normalizeAxNodeIds(body.nodeIds) } : {}),
+    },
+    { source: normalizeAxSource(body.source, 'api') },
+  );
+  broadcastWorkbenchEvent('ax-state-changed', { modeRequest, sessionId: primaryWorkbenchSessionId, timestamp: new Date().toISOString() });
+  return responseJson({ ok: true, modeRequest });
+}
+
+async function handleAxModeResolve(req: Request, id: string): Promise<Response> {
+  const body = await readJson(req);
+  if (body.decision !== 'approved' && body.decision !== 'rejected') {
+    return responseJson({ ok: false, error: 'resolve requires decision approved or rejected.' }, 400);
+  }
+  const modeRequest = canvasState.resolveModeRequest(id, body.decision, {
+    ...(typeof body.resolution === 'string' ? { resolution: body.resolution } : {}),
+    source: normalizeAxSource(body.source, 'api'),
+  });
+  if (!modeRequest) return responseJson({ ok: false, error: 'mode request not found or already resolved.' }, 404);
+  broadcastWorkbenchEvent('ax-state-changed', { modeRequest, sessionId: primaryWorkbenchSessionId, timestamp: new Date().toISOString() });
+  return responseJson({ ok: true, modeRequest });
+}
+
+function handleAxCommandList(): Response {
+  return responseJson({ ok: true, commands: canvasState.getCommandRegistry() });
+}
+
+async function handleAxCommandInvoke(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  if (typeof body.name !== 'string') {
+    return responseJson({ ok: false, error: 'command requires a name.' }, 400);
+  }
+  const event = canvasState.invokeCommand(body.name, isRecord(body.args) ? body.args : null, { source: normalizeAxSource(body.source, 'api') });
+  if (!event) return responseJson({ ok: false, error: `Unknown command "${body.name}".` }, 400);
+  broadcastWorkbenchEvent('ax-event-created', { event, sessionId: primaryWorkbenchSessionId, timestamp: new Date().toISOString() });
+  return responseJson({ ok: true, event });
+}
+
+function handleAxPolicyGet(): Response {
+  return responseJson({ ok: true, policy: canvasState.getPolicy() });
+}
+
+async function handleAxPolicySet(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const patch: { tools?: Partial<PmxAxPolicy['tools']>; prompt?: Partial<PmxAxPolicy['prompt']> } = {};
+  if (isRecord(body.tools)) patch.tools = body.tools as Partial<PmxAxPolicy['tools']>;
+  if (isRecord(body.prompt)) patch.prompt = body.prompt as Partial<PmxAxPolicy['prompt']>;
+  const policy = canvasState.setPolicy(patch, { source: normalizeAxSource(body.source, 'api') });
+  broadcastWorkbenchEvent('ax-state-changed', { policy, sessionId: primaryWorkbenchSessionId, timestamp: new Date().toISOString() });
+  return responseJson({ ok: true, policy });
+}
+
 async function handleAxFocusUpdate(req: Request): Promise<Response> {
   const body = await readJson(req);
   const nodeIds = normalizeAxNodeIds(body.nodeIds);
@@ -4760,6 +5000,10 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleFrameDocument(url.pathname);
           }
 
+          if (url.pathname.startsWith('/api/canvas/surface/') && req.method === 'GET') {
+            return handleNodeSurface(url.pathname, url);
+          }
+
           if (url.pathname === '/' || url.pathname === '/workbench' || url.pathname === '/artifact') {
             return new Response(canvasSpaHtml(), {
               headers: {
@@ -5074,6 +5318,67 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleAxHostCapabilityReport(req);
           }
 
+          if (url.pathname === '/api/canvas/ax/interaction' && req.method === 'POST') {
+            return handleAxInteraction(req);
+          }
+
+          if (url.pathname === '/api/canvas/ax/delivery/pending' && req.method === 'GET') {
+            return handleAxDeliveryPending(url);
+          }
+
+          if (url.pathname.startsWith('/api/canvas/ax/delivery/') && url.pathname.endsWith('/mark') && req.method === 'POST') {
+            const deliveryId = decodeURIComponent(
+              url.pathname.slice('/api/canvas/ax/delivery/'.length, -'/mark'.length),
+            );
+            return handleAxDeliveryMark(deliveryId);
+          }
+
+          if (url.pathname === '/api/canvas/ax/elicitation' && req.method === 'GET') {
+            return handleAxElicitationList();
+          }
+
+          if (url.pathname === '/api/canvas/ax/elicitation' && req.method === 'POST') {
+            return handleAxElicitationRequest(req);
+          }
+
+          if (url.pathname.startsWith('/api/canvas/ax/elicitation/') && url.pathname.endsWith('/respond') && req.method === 'POST') {
+            const elicitationId = decodeURIComponent(
+              url.pathname.slice('/api/canvas/ax/elicitation/'.length, -'/respond'.length),
+            );
+            return handleAxElicitationRespond(req, elicitationId);
+          }
+
+          if (url.pathname === '/api/canvas/ax/mode' && req.method === 'GET') {
+            return handleAxModeList();
+          }
+
+          if (url.pathname === '/api/canvas/ax/mode' && req.method === 'POST') {
+            return handleAxModeRequest(req);
+          }
+
+          if (url.pathname.startsWith('/api/canvas/ax/mode/') && url.pathname.endsWith('/resolve') && req.method === 'POST') {
+            const modeId = decodeURIComponent(
+              url.pathname.slice('/api/canvas/ax/mode/'.length, -'/resolve'.length),
+            );
+            return handleAxModeResolve(req, modeId);
+          }
+
+          if (url.pathname === '/api/canvas/ax/command' && req.method === 'GET') {
+            return handleAxCommandList();
+          }
+
+          if (url.pathname === '/api/canvas/ax/command' && req.method === 'POST') {
+            return handleAxCommandInvoke(req);
+          }
+
+          if (url.pathname === '/api/canvas/ax/policy' && req.method === 'GET') {
+            return handleAxPolicyGet();
+          }
+
+          if (url.pathname === '/api/canvas/ax/policy' && req.method === 'POST') {
+            return handleAxPolicySet(req);
+          }
+
           // Spatial context API
           if (url.pathname === '/api/canvas/spatial-context' && req.method === 'GET') {
             const layout = canvasState.getLayout();

package/src/shared/surface.ts

@@ -0,0 +1,38 @@
+/**
+ * Cross-cutting helpers for node "surfaces" — the standalone documents served at
+ * /api/canvas/surface/:nodeId. Shared by the server route, the server-side node
+ * serialization, and the client so the openability rule lives in exactly one
+ * place. The authoritative dispatch (serve vs redirect) lives in the server's
+ * handleNodeSurface; this predicate mirrors which node types it can open.
+ */
+
+/**
+ * Whether a node has an "Open as site" surface. Coarse by design (presence of the
+ * minimal field) — the route itself decides what to actually serve.
+ */
+export function canOpenNodeAsSurface(type: string, data: Record<string, unknown>): boolean {
+  switch (type) {
+    case 'html':
+      return (typeof data.html === 'string' && data.html.length > 0)
+        || (typeof data.content === 'string' && data.content.length > 0);
+    case 'json-render':
+    case 'graph':
+      return true;
+    case 'mcp-app':
+      return (data.viewerType === 'web-artifact' && typeof data.path === 'string' && data.path.length > 0)
+        || (data.mode === 'ext-app' && typeof data.html === 'string' && data.html.length > 0)
+        || (typeof data.url === 'string' && data.url.length > 0);
+    case 'webpage':
+      return typeof data.url === 'string' && data.url.length > 0;
+    default:
+      return false;
+  }
+}
+
+/**
+ * CSP sandbox tokens for a hosted ext-app surface, used both as the in-canvas
+ * iframe `sandbox` attribute and as the `Content-Security-Policy: sandbox` value
+ * when the surface route serves an ext-app standalone. All tokens are in the
+ * server's safe-sandbox allowlist; notably NOT allow-same-origin.
+ */
+export const DEFAULT_EXT_APP_SANDBOX = 'allow-scripts allow-popups allow-popups-to-escape-sandbox';