pmx-canvas 0.4.5 → 0.4.7

package/src/server/html-surface.ts

@@ -211,6 +211,17 @@ function escapeSurfaceHtml(value: string): string {
   return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
+/**
+ * Author-HTML fragment for a `mermaid` node surface: the HTML-escaped diagram
+ * source in a hidden `<pre>` the entry script reads back via textContent, plus
+ * the separately-built renderer bundle (dist/canvas/mermaid-entry.js — kept out
+ * of the main SPA bundle). Escaping is mandatory: the source is arbitrary node
+ * data and must not be parsed as markup.
+ */
+export function buildMermaidSurfaceHtml(source: string): string {
+  return `<pre class="mermaid-source" style="display:none">${escapeSurfaceHtml(source)}</pre><script src="/canvas/mermaid-entry.js"></script>`;
+}
+
 export interface HtmlSurfaceOptions {
   theme: SurfaceTheme;
   /**

package/src/server/index.ts

@@ -542,15 +542,22 @@ export class PmxCanvas extends EventEmitter {
       nodeIds?: string[];
       data?: Record<string, unknown> | null;
     },
-    options?: { source?: PmxAxSource },
+    options?: { source?: PmxAxSource; agentId?: string | null },
   ): PmxAxEvent {
-    const event = canvasState.recordAxEvent(input, { source: options?.source ?? 'sdk' });
+    const event = canvasState.recordAxEvent(input, { source: options?.source ?? 'sdk', agentId: options?.agentId });
     emitPrimaryWorkbenchEvent('ax-event-created', { event });
     return event;
   }
 
-  sendSteering(message: string, options?: { source?: PmxAxSource }): PmxAxSteeringMessage {
-    const steering = canvasState.recordSteeringMessage(message, { source: options?.source ?? 'sdk' });
+  sendSteering(
+    message: string,
+    options?: { source?: PmxAxSource; agentId?: string | null; target?: string | null },
+  ): PmxAxSteeringMessage {
+    const steering = canvasState.recordSteeringMessage(message, {
+      source: options?.source ?? 'sdk',
+      agentId: options?.agentId,
+      target: options?.target,
+    });
     emitPrimaryWorkbenchEvent('ax-event-created', { steering });
     return steering;
   }
@@ -604,7 +611,13 @@ export class PmxCanvas extends EventEmitter {
   }
 
   addWorkItem(
-    input: { title: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    input: {
+      title: string;
+      status?: PmxAxWorkItemStatus;
+      detail?: string | null;
+      nodeIds?: string[];
+      agentId?: string | null;
+    },
     options?: { source?: PmxAxSource },
   ): PmxAxWorkItem {
     const workItem = canvasState.addWorkItem(input, { source: options?.source ?? 'sdk' });
@@ -614,7 +627,13 @@ export class PmxCanvas extends EventEmitter {
 
   updateWorkItem(
     id: string,
-    patch: { title?: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    patch: {
+      title?: string;
+      status?: PmxAxWorkItemStatus;
+      detail?: string | null;
+      nodeIds?: string[];
+      agentId?: string | null;
+    },
     options?: { source?: PmxAxSource },
   ): PmxAxWorkItem | null {
     const workItem = canvasState.updateWorkItem(id, patch, { source: options?.source ?? 'sdk' });

package/src/server/operations/composites.ts

@@ -156,14 +156,15 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_render',
     description:
-      'Spec-driven content: discover the schema, validate a payload, or create a json-render / graph node. Action "describe-schema" returns the json-render component catalog + create schemas; "validate" checks a spec or graph payload without creating a node; "add-json-render" creates a json-render node from a complete spec; "stream-json-render" progressively builds one from SpecStream patches (omit nodeId to create, pass it back to append, done=true to finish); "add-graph" creates a chart node (line, bar, pie, area, scatter, radar, stacked-bar, composed, sparkline, dot-plot, bullet, slopegraph).',
-    actionSummary: 'describe-schema | validate | add-json-render | stream-json-render | add-graph',
+      'Spec-driven content: discover the schema, validate a payload, or create a json-render / graph node. Action "describe-schema" returns the json-render component catalog + create schemas; "validate" checks a spec or graph payload without creating a node; "add-json-render" creates a json-render node from a complete spec; "stream-json-render" progressively builds one from SpecStream patches (omit nodeId to create, pass it back to append, done=true to finish); "add-graph" creates a chart node (line, bar, pie, area, scatter, radar, stacked-bar, composed, sparkline, dot-plot, bullet, slopegraph); "workboard" materializes a live AX work-item board (a json-render node with a column per status) that auto-refreshes whenever work items change — idempotent, rebuilding the existing board in place.',
+    actionSummary: 'describe-schema | validate | add-json-render | stream-json-render | add-graph | workboard',
     actions: {
       'describe-schema': 'schema.describe',
       validate: 'spec.validate',
       'add-json-render': 'jsonrender.add',
       'stream-json-render': 'jsonrender.stream',
       'add-graph': 'graph.add',
+      workboard: 'render.workboard',
     },
   },
   {

package/src/server/operations/ops/ax-work.ts

@@ -45,6 +45,11 @@
  * This module must never import server.ts or index.ts.
  */
 import { z } from 'zod';
+// Side-effect import: wires the work-item change listener (live workboard refresh
+// + materialized-flow loop advance). Work items are this module's domain, and the
+// ops registry loads it on every entry path (HTTP, MCP, SDK), so the flow loop is
+// armed wherever work items can change.
+import '../../ax-flow-loop.js';
 import { canvasState } from '../../canvas-state.js';
 import type {
   PmxAxMode,

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

@@ -375,6 +375,14 @@ const batchOperation = defineOperation<z.infer<typeof batchSchema>, BatchEnvelop
     // ctx.emit). After the loop completes, emit ONE final canvas-layout-update.
     const envelope = await runWithSuppressedEmits(() => runBatch(operations));
     ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    // The suppression window also swallows the pins op's context-pins-changed
+    // frame, leaving the client's pin state (menus, indicators) stale until
+    // reload (0.4.5 report Finding X). If the batch touched pins, follow the
+    // layout frame with ONE final pins frame carrying the end state.
+    if (operations.some((entry) => entry.op.startsWith('pin.'))) {
+      const nodeIds = Array.from(canvasState.contextPinnedNodeIds);
+      ctx.emit('context-pins-changed', { count: nodeIds.length, nodeIds });
+    }
     return envelope;
   },
 });

package/src/server/operations/ops/json-render.ts

@@ -39,6 +39,7 @@ import {
 } from '../../canvas-operations.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from '../../canvas-schema.js';
 import { isHtmlPrimitiveKind } from '../../html-primitives.js';
+import { renderWorkboard } from '../../workboard.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import {
   buildNodeResponse,
@@ -311,6 +312,48 @@ const jsonRenderStreamOperation = defineOperation<z.infer<typeof jsonRenderStrea
   // Wire shape is `{ id, url, ok, applied, ... }` — handler output verbatim.
 });
 
+// ── render.workboard ──────────────────────────────────────────
+
+const workboardRenderShape = {
+  intentId: z
+    .string()
+    .optional()
+    .catch(undefined)
+    .describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
+  x: z.number().optional().catch(undefined).describe('Optional X position (only used when creating the board)'),
+  y: z.number().optional().catch(undefined).describe('Optional Y position (only used when creating the board)'),
+};
+
+const workboardRenderSchema = z.looseObject(workboardRenderShape);
+
+const workboardRenderOperation = defineOperation<
+  z.infer<typeof workboardRenderSchema>,
+  ReturnType<typeof renderWorkboard>
+>({
+  name: 'render.workboard',
+  mutates: true,
+  input: workboardRenderSchema,
+  inputShape: workboardRenderShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/workboard',
+  },
+  mcp: {
+    toolName: 'canvas_render_workboard',
+    description:
+      'Materialize a live work-item board: a json-render node with one column per status (todo → in-progress → blocked → done → cancelled) showing every AX work item as a card (title, agentId chip, detail). Idempotent: rebuilds the existing board node in place when one exists, otherwise creates it. The board auto-refreshes whenever work items change.',
+  },
+  handler: (input) => {
+    const body: Record<string, unknown> = input;
+    const x = pickFiniteNumber(body, 'x');
+    const y = pickFiniteNumber(body, 'y');
+    return renderWorkboard({
+      ...(x !== undefined ? { x } : {}),
+      ...(y !== undefined ? { y } : {}),
+    });
+  },
+});
+
 // ── graph.add ─────────────────────────────────────────────────
 
 const graphAddShape = {
@@ -829,6 +872,7 @@ const specValidateOperation = defineOperation<z.infer<typeof specValidateSchema>
 export const jsonRenderOperations: Operation[] = [
   jsonRenderAddOperation,
   jsonRenderStreamOperation,
+  workboardRenderOperation,
   graphAddOperation,
   schemaDescribeOperation,
   specValidateOperation,

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

@@ -28,7 +28,12 @@ import {
   LEDGER_NODE_DEFAULT_SIZE,
 } from '../../canvas-operations.js';
 import { normalizeNodeAxCapabilities } from '../../ax-interaction.js';
-import { buildHtmlPrimitive, getHtmlPrimitiveSemanticMetadata, isHtmlPrimitiveKind } from '../../html-primitives.js';
+import {
+  buildHtmlPrimitive,
+  getHtmlPrimitiveDescriptor,
+  getHtmlPrimitiveSemanticMetadata,
+  isHtmlPrimitiveKind,
+} from '../../html-primitives.js';
 import { closeMcpAppSession } from '../../mcp-app-runtime.js';
 import {
   getCanvasNodeTitle,
@@ -55,6 +60,8 @@ export const NODE_TYPES = [
   'ledger',
   'trace',
   'file',
+  'diff',
+  'mermaid',
   'image',
   'mcp-app',
   'webpage',
@@ -74,6 +81,10 @@ export function defaultNodeSize(type: string): { width: number; height: number }
       // a useful snippet — the generic default rendered as a content-less bar
       // (0.4.4 portal feedback).
       return { width: 520, height: 360 };
+    case 'diff':
+      return { width: 640, height: 420 };
+    case 'mermaid':
+      return { width: 640, height: 460 };
     case 'markdown':
       return MARKDOWN_NODE_DEFAULT_SIZE;
     case 'mcp-app':
@@ -625,6 +636,14 @@ function createHtmlPrimitiveNode(body: Record<string, unknown>): NodeAddResult {
     throw new OperationError(error instanceof Error ? error.message : String(error));
   }
   const geometry = resolveCreateGeometry(body);
+  // `html` is AX-opt-in, so an emitting primitive is inert without capabilities:
+  // apply the ones its descriptor declares. An explicit caller value wins (both are
+  // clamped to the `html` type ceiling by resolveNodeAxCapabilities). The declared
+  // set is copied — the descriptor is a module constant shared by every node.
+  const declared = getHtmlPrimitiveDescriptor(built.kind).axCapabilities;
+  const axCapabilities =
+    normalizeNodeAxCapabilities(body.axCapabilities) ??
+    (declared ? { enabled: declared.enabled, allowed: [...declared.allowed] } : undefined);
   const { node } = addCanvasNode({
     type: 'html',
     title: built.title,
@@ -635,6 +654,7 @@ function createHtmlPrimitiveNode(body: Record<string, unknown>): NodeAddResult {
       description: built.summary,
       agentSummary: typeof data.agentSummary === 'string' ? data.agentSummary : built.summary,
       ...(typeof data.summary === 'string' ? { summary: data.summary } : {}),
+      ...(axCapabilities ? { axCapabilities } : {}),
       ...getHtmlPrimitiveSemanticMetadata(built.data),
     },
     ...(body.strictSize === true ? { strictSize: true } : {}),
@@ -783,7 +803,7 @@ const nodeAddOperation = defineOperation<z.infer<typeof nodeAddSchema>, NodeAddR
   mcp: {
     toolName: 'canvas_add_node',
     description:
-      'Add a basic node to the canvas. Returns the created node with normalized title/content and rendered geometry. Supported here: markdown, status, context, ledger, trace, file, image, webpage, mcp-app, html, group. Dedicated routes: json-render -> canvas_render {action:"add-json-render"}, graph -> canvas_render {action:"add-graph"}, web-artifact -> canvas_app {action:"build-artifact"}, external apps -> canvas_app {action:"open-mcp-app"}, groups -> canvas_group {action:"create"}. Call canvas_render {action:"describe-schema"} for the full nodeTypeRouting table.',
+      'Add a basic node to the canvas. Returns the created node with normalized title/content and rendered geometry. Supported here: markdown, status, context, ledger, trace, file, diff, mermaid, image, webpage, mcp-app, html, group. Dedicated routes: json-render -> canvas_render {action:"add-json-render"}, graph -> canvas_render {action:"add-graph"}, web-artifact -> canvas_app {action:"build-artifact"}, external apps -> canvas_app {action:"open-mcp-app"}, groups -> canvas_group {action:"create"}. Call canvas_render {action:"describe-schema"} for the full nodeTypeRouting table.',
     extraShape: {
       type: z
         .enum([
@@ -793,6 +813,8 @@ const nodeAddOperation = defineOperation<z.infer<typeof nodeAddSchema>, NodeAddR
           'ledger',
           'trace',
           'file',
+          'diff',
+          'mermaid',
           'image',
           'webpage',
           'mcp-app',

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

@@ -14,7 +14,7 @@
  */
 import { z } from 'zod';
 import { canvasState } from '../../canvas-state.js';
-import { arrangeCanvasNodes, clearCanvas, fitCanvasView } from '../../canvas-operations.js';
+import { arrangeCanvasNodes, clearCanvas, fitCanvasView, setClientViewportSize } from '../../canvas-operations.js';
 import { validateCanvasLayout } from '../../canvas-validation.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { closeNodeAppSession, isRecord } from './nodes.js';
@@ -121,7 +121,14 @@ const focusOperation = defineOperation<z.infer<typeof focusSchema>, Record<strin
     if (!node) throw new OperationError(`Node "${nodeId}" not found.`, 404);
     const noPan = body.noPan === true;
     if (!noPan) {
-      canvasState.setViewport({ x: node.position.x - 100, y: node.position.y - 100 });
+      // The viewport is a SCREEN-space translate: screen = world * scale + v
+      // (CanvasViewport's matrix(scale,0,0,scale,x,y)), the same convention
+      // fitCanvasView and the client's focusNode use. So park the node's
+      // top-left at a fixed screen-space margin — 64/96 screen px, which
+      // clears the 44px floating toolbar at ANY zoom (0.4.5 report Finding Z:
+      // the old world-space margin shrank below the toolbar at low scales).
+      const scale = canvasState.viewport.scale || 1;
+      canvasState.setViewport({ x: 64 - node.position.x * scale, y: 96 - node.position.y * scale });
     } else {
       const maxZ = canvasState.getLayout().nodes.reduce((max, layoutNode) => Math.max(max, layoutNode.zIndex), 0);
       canvasState.updateNode(nodeId, { zIndex: maxZ + 1 });
@@ -221,6 +228,8 @@ const viewportSetShape = {
   y: z.unknown().optional().describe('Viewport y offset'),
   scale: z.unknown().optional().describe('Viewport zoom scale'),
   recordHistory: z.unknown().optional().describe('Pass false to skip the undo-history entry'),
+  clientWidth: z.unknown().optional().describe("The reporting client's window width in CSS pixels"),
+  clientHeight: z.unknown().optional().describe("The reporting client's window height in CSS pixels"),
 };
 
 const viewportSetSchema = z.looseObject(viewportSetShape);
@@ -237,6 +246,10 @@ const viewportSetOperation = defineOperation<z.infer<typeof viewportSetSchema>,
   // Legacy wire: emits canvas-viewport-update (never a layout update).
   handler: (input, ctx) => {
     const body: Record<string, unknown> = input;
+    // The browser piggybacks its real window size here so a later agent `fit`
+    // sizes to the human's actual window instead of a hardcoded 1440x900
+    // (0.4.6 orb feedback #2).
+    setClientViewportSize(body.clientWidth, body.clientHeight);
     const next = {
       x: typeof body.x === 'number' ? body.x : canvasState.viewport.x,
       y: typeof body.y === 'number' ? body.y : canvasState.viewport.y,

package/src/server/server.ts

@@ -22,6 +22,7 @@
  * - POST /api/canvas/json-render  -> create a native json-render node
  * - POST /api/canvas/graph        -> create a native graph node
  * - GET  /api/canvas/json-render/view?nodeId=... -> local json-render viewer
+ * - GET  /api/canvas/file-bytes?nodeId=... -> raw bytes for a file node
  * - POST /api/canvas/web-artifact -> build bundled HTML artifact + optional canvas node
  * - GET  /api/workbench/events   -> SSE event stream
  * - GET  /api/workbench/poll     -> proxy-safe polling transport (same events, JSON)
@@ -37,7 +38,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { existsSync, readFileSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { basename, extname, join, relative, resolve } from 'node:path';
 import * as marked from 'marked';
@@ -47,10 +48,12 @@ import {
   buildAxStateBridge,
   buildContentHeightReporter,
   buildHtmlSurfaceDocument,
+  buildMermaidSurfaceHtml,
   HTML_SURFACE_SANDBOX,
   normalizeSurfaceTheme,
 } from './html-surface.js';
 import { findCanvasExtAppNodeId as findCanvasExtAppNodeIdShared } from './ext-app-lookup.js';
+import { isPdfFilePath } from './file-content.js';
 import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
 import { getMcpAppHostSnapshot } from './mcp-app-host.js';
 import { closeMcpAppSession, closeAllMcpAppSessions } from './mcp-app-runtime.js';
@@ -61,6 +64,7 @@ import { buildCanvasAxSurfaceSnapshot } from './ax-context.js';
 import { resolveNodeAxCapabilities } from './ax-interaction.js';
 import { normalizeCanvasTheme, type CanvasTheme } from './canvas-db.js';
 import { canvasThemeScheme, isCanvasTheme } from '../shared/themes.js';
+import { canOpenNodeAsSurface } from '../shared/surface.js';
 import { validateLocalImageFile } from './image-source.js';
 import {
   cancelCodeGraphRecompute,
@@ -625,9 +629,28 @@ function resolveWorkspaceMarkdownPath(pathLike: string): string | null {
 function resolveWorkspaceArtifactPath(pathLike: string): string | null {
   if (!pathLike || typeof pathLike !== 'string') return null;
   const resolved = resolve(pathLike);
-  const workspaceRel = relative(activeWorkspaceRoot, resolved);
+  // Containment must be checked on REAL paths: a lexical resolve() only stops
+  // `..` and absolute escapes, so a symlink INSIDE the workspace pointing at
+  // /etc/passwd or ~/.ssh/id_rsa would pass. Both sides are realpath'd — the
+  // root itself is commonly a symlink (macOS /tmp → /private/tmp), and
+  // comparing a real candidate against a symlinked root would reject
+  // legitimate files.
+  let realResolved = resolved;
+  let realRoot = activeWorkspaceRoot;
+  try {
+    realResolved = realpathSync(resolved);
+  } catch {
+    // Not yet on disk (callers handle existence themselves) — fall back to the
+    // lexical path, whose parent chain is still checked below.
+  }
+  try {
+    realRoot = realpathSync(activeWorkspaceRoot);
+  } catch {
+    // Workspace root unreadable — keep the configured value.
+  }
+  const workspaceRel = relative(realRoot, realResolved);
   const insideWorkspace = !(workspaceRel.startsWith('..') || workspaceRel === '..');
-  return insideWorkspace ? resolved : null;
+  return insideWorkspace ? realResolved : null;
 }
 
 function escapeHtml(text: string): string {
@@ -1004,6 +1027,7 @@ function canvasSpaHtml(): string {
     // (see src/client/state/iframe-mode.ts).
     process.env.AMP_ORB ? '<script>window.__PMX_AMP_ORB = true;</script>' : ''
   }
+  <script>window.__PMX_BOOT_SERVER_VERSION = ${JSON.stringify(serverPackageVersion())};</script>
   <script type="module" src="/canvas/index.js?v=${CANVAS_ASSET_VERSION}"></script>
 </body>
 </html>`;
@@ -1263,6 +1287,14 @@ function isSafeSurfaceRedirect(target: string): boolean {
   return false;
 }
 
+// Why a node has no standalone surface, in one wording shared by the route's own
+// 404 and by open-external's refusal — the two must never disagree about a node.
+function surfaceRefusalMessage(type: string): string {
+  return type === 'mcp-app'
+    ? 'This MCP app renders in the canvas and cannot be opened as a standalone site.'
+    : 'Node type cannot be opened as a site';
+}
+
 function handleNodeSurface(pathname: string, url: URL): Response {
   const nodeId = decodeURIComponent(pathname.slice('/api/canvas/surface/'.length));
   if (!nodeId) return responseText('Missing node id', 400);
@@ -1271,6 +1303,28 @@ function handleNodeSurface(pathname: string, url: URL): Response {
 
   const theme = normalizeSurfaceTheme(url.searchParams.get('theme'));
 
+  if (node.type === 'mermaid') {
+    const source = typeof node.data.content === 'string' ? node.data.content : '';
+    if (!source.trim()) return responseText('Mermaid node has no content', 404);
+    const surfaceTitle = typeof node.data.title === 'string' && node.data.title.trim() ? node.data.title : node.id;
+    // Display-only surface: same theme/height plumbing as html nodes, but no AX
+    // bridge and no presentation mode — the document is our own wrapper around
+    // escaped diagram source, rendered by /canvas/mermaid-entry.js.
+    const doc = buildHtmlSurfaceDocument(buildMermaidSurfaceHtml(source), {
+      theme,
+      title: surfaceTitle,
+      themeToken: url.searchParams.get('themeToken') ?? undefined,
+      // Content-height reporter nonce (lets the node grow to fit the diagram).
+      ...(url.searchParams.get('frameToken')
+        ? { contentHeightToken: url.searchParams.get('frameToken') as string }
+        : {}),
+      // Inline the theme tokens so srcdoc-rendered surfaces (Amp orb portals)
+      // are styled without depending on the <link> subresource.
+      ...(surfaceThemeCssInline() ? { inlineThemeCss: surfaceThemeCssInline() as string } : {}),
+    });
+    return surfaceHtmlResponse(doc, HTML_SURFACE_SANDBOX);
+  }
+
   if (node.type === 'html') {
     const html =
       typeof node.data.html === 'string'
@@ -1329,7 +1383,7 @@ function handleNodeSurface(pathname: string, url: URL): Response {
     // `-32601` (report #61). It is intentionally NOT openable as a site — open such
     // apps externally through their own app, or view them in the canvas. (Kept in sync
     // with canOpenNodeAsSurface in src/shared/surface.ts, which hides the UI control.)
-    return responseText('This MCP app renders in the canvas and cannot be opened as a standalone site.', 404);
+    return responseText(surfaceRefusalMessage(node.type), 404);
   }
 
   if (node.type === 'webpage') {
@@ -1339,7 +1393,7 @@ function handleNodeSurface(pathname: string, url: URL): Response {
     return responseText('Webpage node has no url', 404);
   }
 
-  return responseText('Node type cannot be opened as a site', 404);
+  return responseText(surfaceRefusalMessage(node.type), 404);
 }
 
 // ── Serve image file for image nodes ─────────────────────────
@@ -1378,6 +1432,66 @@ async function handleCanvasImage(pathname: string): Promise<Response> {
   });
 }
 
+// ── Serve raw bytes for file nodes (PDF viewer, downloads) ───
+/**
+ * Ceiling for the raw byte route. The route streams via Bun.file, so this is a
+ * sanity bound (an embedded PDF viewer is the only consumer), not a memory
+ * guard — but it stops a stray multi-GB path from tying up a connection.
+ */
+const FILE_BYTES_MAX = 100 * 1024 * 1024;
+
+async function handleCanvasFileBytes(url: URL): Promise<Response> {
+  const nodeId = url.searchParams.get('nodeId') ?? '';
+  if (!nodeId) return responseText('Missing nodeId', 400);
+  const node = canvasState.getNode(nodeId);
+  if (node?.type !== 'file') {
+    return responseText('File node not found', 404);
+  }
+  const filePath = typeof node.data.path === 'string' ? node.data.path : '';
+  if (!filePath) {
+    return responseText('File node is not backed by a path', 404);
+  }
+  // Same containment guard as the image route: `path` comes from node data,
+  // which any unauthenticated local caller can set, so an unguarded read here
+  // would serve arbitrary host files.
+  const safePath = resolveWorkspaceArtifactPath(filePath);
+  if (!safePath) {
+    return responseText('File path is outside the workspace; the byte route only serves workspace files', 403);
+  }
+  if (!existsSync(safePath)) {
+    return responseText('File not found', 404);
+  }
+  let stats: ReturnType<typeof statSync>;
+  try {
+    stats = statSync(safePath);
+  } catch {
+    return responseText('File not found', 404);
+  }
+  // Regular files only: a directory would throw EISDIR into a 500, and a FIFO
+  // would block the read forever (the server has no request timeout).
+  if (!stats.isFile()) {
+    return responseText('File path is not a regular file', 400);
+  }
+  if (stats.size > FILE_BYTES_MAX) {
+    return responseText(`File is larger than the ${Math.floor(FILE_BYTES_MAX / 1_000_000)} MB byte-route limit`, 413);
+  }
+  // Content-Type is derived from the BYTES, never from node.data.mimeType:
+  // node data is freely writable by any local caller, and this response is
+  // framed same-origin — echoing a caller-chosen `text/html` here would run
+  // attacker markup on the canvas origin. PDFs are the only inline-rendered
+  // type; everything else is an opaque download. nosniff stops the browser
+  // from second-guessing us.
+  const contentType = isPdfFilePath(safePath) ? 'application/pdf' : 'application/octet-stream';
+  return new Response(Bun.file(safePath), {
+    headers: {
+      'Content-Type': contentType,
+      'Content-Disposition': contentType === 'application/pdf' ? 'inline' : 'attachment',
+      'X-Content-Type-Options': 'nosniff',
+      'Cache-Control': 'no-store',
+    },
+  });
+}
+
 async function handleJsonRenderView(url: URL): Promise<Response> {
   const nodeId = url.searchParams.get('nodeId') ?? '';
   if (!nodeId) return responseText('Missing nodeId', 400);
@@ -1449,6 +1563,23 @@ function responseJson(data: unknown, status = 200): Response {
   });
 }
 
+// Resolved from the sibling package.json so it stays accurate through bunx,
+// global npm installs, and repo-local runs — same mechanism as --version in
+// src/cli/index.ts and the MCP server. Memoized: /health is polled.
+let cachedPackageVersion: string | null = null;
+function serverPackageVersion(): string {
+  if (cachedPackageVersion !== null) return cachedPackageVersion;
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf-8')) as {
+      version?: string;
+    };
+    cachedPackageVersion = pkg.version ?? 'unknown';
+  } catch {
+    cachedPackageVersion = 'unknown';
+  }
+  return cachedPackageVersion;
+}
+
 // v0.4.0 (M4): every hand-written error response is a JSON envelope
 // ({ ok: false, error }, same status codes) matching the registry dispatcher —
 // consumers no longer need to branch on text/plain vs JSON error bodies.
@@ -1799,6 +1930,9 @@ function buildWorkbenchConnectSnapshot(
       continuity,
       path: primaryWorkbenchPath,
       theme: canvasState.theme,
+      // Lets a long-lived client detect that the server was upgraded under it
+      // (stale in-memory SPA — 0.4.5 report Finding W) and reload once.
+      version: serverPackageVersion(),
       timestamp: new Date().toISOString(),
     },
   });
@@ -2241,6 +2375,11 @@ async function handleOpenExternalSurface(req: Request): Promise<Response> {
   if (!nodeId) return responseJson({ ok: false, error: 'nodeId is required.' }, 400);
   const node = canvasState.getNode(nodeId);
   if (!node) return responseJson({ ok: false, error: `Node "${nodeId}" not found.` }, 404);
+  // Same rule the surface route and the "Open as site" control apply: refuse here
+  // rather than launching a browser at a URL that is guaranteed to 404 (report #61).
+  if (!canOpenNodeAsSurface(node.type, node.data)) {
+    return responseJson({ ok: false, opened: false, error: surfaceRefusalMessage(node.type) }, 400);
+  }
   const port = getCanvasServerPort();
   if (!port) return responseJson({ ok: false, opened: false, error: 'Server port unavailable.' }, 503);
   const defaultSurfacePath = `/api/canvas/surface/${encodeURIComponent(nodeId)}`;
@@ -3038,11 +3177,14 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             // when the pid file is stale (e.g. an adapter respawned the server
             // outside `serve --daemon` — 0.3.2 report Finding P). `persistence`
             // surfaces silent save failures (M4): the canvas keeps serving from
-            // memory, but ok:false means durability is degraded.
+            // memory, but ok:false means durability is degraded. `version` lets
+            // `pmx-canvas smoke` verify the RUNNING server, not just the CLI —
+            // version skew between the two is a known failure mode.
             return responseJson({
               ok: true,
               workspace: activeWorkspaceRoot,
               pid: process.pid,
+              version: serverPackageVersion(),
               persistence: canvasState.persistenceHealth,
             });
           }
@@ -3154,6 +3296,12 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return await handleCanvasImage(url.pathname);
           }
 
+          // HEAD answers like GET (see the standalone-surface note above): a PDF
+          // viewer probes this URL for type/length before fetching the bytes.
+          if (url.pathname === '/api/canvas/file-bytes' && (req.method === 'GET' || req.method === 'HEAD')) {
+            return await handleCanvasFileBytes(url);
+          }
+
           if (url.pathname === '/api/canvas/open-external' && req.method === 'POST') {
             return handleOpenExternalSurface(req);
           }