pmx-canvas 0.4.6 → 0.4.8

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/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,
@@ -631,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,
@@ -641,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 } : {}),

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';
@@ -228,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);
@@ -244,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';
@@ -52,6 +53,7 @@ import {
   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';
@@ -62,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,
@@ -626,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 {
@@ -1265,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);
@@ -1353,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') {
@@ -1363,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 ─────────────────────────
@@ -1402,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);
@@ -2285,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)}`;
@@ -3201,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);
           }

package/src/server/web-artifacts.ts

@@ -27,6 +27,19 @@ const LEGACY_SKILL_WEB_ARTIFACT_SCRIPTS_DIR = join(
 );
 const DEFAULT_TIMEOUT_MS = 10 * 60_000;
 const DEFAULT_PACKAGE_MANAGER = 'pnpm@10.33.0';
+const NODE_VERSION_PROBE_TIMEOUT_MS = 15_000;
+/**
+ * Minimum Node.js (`major.minor`) each pnpm major declares in its published
+ * `engines.node` — pnpm 10.x is `>=18.12`, pnpm 11.x is `>=22.13`. The pnpm that
+ * runs a build is not a local dependency (the scripts take it from PATH, `bun x`,
+ * or a global install), so its engines field cannot be read from disk; this table
+ * carries the same constraint keyed by the pinned major. An unlisted major
+ * imposes no preflight floor rather than an invented one.
+ */
+const PNPM_MAJOR_MIN_NODE: Record<string, string> = {
+  '10': '18.12',
+  '11': '22.13',
+};
 const DEFAULT_WEB_ARTIFACT_NODE_SIZE = { width: 960, height: 720 };
 const FALLBACK_PATH_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin'];
 const WEB_ARTIFACT_CONTEXT_MAX_LENGTH = 1200;
@@ -470,6 +483,101 @@ function summarizeArtifactLog(text: string): WebArtifactLogSummary | undefined {
   };
 }
 
+export type NodeVersionCheck = { ok: true } | { ok: false; message: string };
+
+function parseMajorMinor(value: string): { major: number; minor: number } | null {
+  const match = /^v?(\d+)\.(\d+)/.exec(value.trim());
+  if (!match) return null;
+  return { major: Number(match[1]), minor: Number(match[2]) };
+}
+
+/**
+ * Pure preflight comparison used before any package-manager invocation.
+ * `detected` is raw `node --version` output ("v20.11.1"), or null when no node
+ * executable answered; `required` is a `major.minor` floor; `packageManager` is
+ * the pin that imposes it (e.g. "pnpm@11.1.2"). Returns an actionable message
+ * instead of throwing so every caller surfaces it on its own error channel.
+ */
+export function checkWebArtifactNodeVersion(
+  detected: string | null,
+  required: string,
+  packageManager: string,
+): NodeVersionCheck {
+  const requiredParts = parseMajorMinor(required);
+  if (!requiredParts) return { ok: true };
+
+  const detectedLabel = detected === null ? null : detected.trim();
+  const detectedParts = detectedLabel === null ? null : parseMajorMinor(detectedLabel);
+  if (
+    detectedParts &&
+    (detectedParts.major > requiredParts.major ||
+      (detectedParts.major === requiredParts.major && detectedParts.minor >= requiredParts.minor))
+  ) {
+    return { ok: true };
+  }
+
+  const found =
+    detectedLabel && detectedParts
+      ? `the build environment has Node.js ${detectedLabel}`
+      : 'no usable `node` executable was found on the build PATH';
+  return {
+    ok: false,
+    message:
+      `Web-artifact build preflight failed: ${packageManager} requires Node.js >= ${required}, but ${found}. ` +
+      `Run PMX Canvas under Node.js ${required} or newer, then retry the build.`,
+  };
+}
+
+/** `node --version` as the build subprocesses see it, or null when node is unavailable. */
+async function detectSubprocessNodeVersion(cwd: string): Promise<string | null> {
+  try {
+    const { stdout } = await runProcess('node', ['--version'], { cwd, timeoutMs: NODE_VERSION_PROBE_TIMEOUT_MS });
+    return stdout.trim() || null;
+  } catch {
+    // A missing or non-runnable node IS the preflight failure — reported below
+    // with the required version, not rethrown as a spawn error here.
+    return null;
+  }
+}
+
+/**
+ * The `packageManager` pin that governs this build: a reused artifact project
+ * carries its own pin, a fresh one gets the bundled default that init-artifact.sh
+ * and ensurePackageManagerBoundary write.
+ */
+function resolvePinnedPackageManager(projectPath: string): string {
+  const packageJsonPath = join(projectPath, 'package.json');
+  if (!existsSync(packageJsonPath)) return DEFAULT_PACKAGE_MANAGER;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      const pinned = (parsed as Record<string, unknown>).packageManager;
+      if (typeof pinned === 'string' && pinned.includes('@')) return pinned;
+    }
+  } catch {
+    // A corrupt project package.json is the init script's problem; the preflight
+    // falls back to the pin PMX Canvas would write anyway.
+  }
+  return DEFAULT_PACKAGE_MANAGER;
+}
+
+/**
+ * Fail fast when the Node.js available to the build subprocesses is older than
+ * the pinned package manager supports. Without this, pnpm's engine error lands
+ * deep inside the init/bundle script output and reads as an unrelated build
+ * failure (reported: pnpm 11 needs Node 22.13+, the build ran on Node 20).
+ */
+async function preflightBuildRuntime(cwd: string, projectPath: string): Promise<void> {
+  const packageManager = resolvePinnedPackageManager(projectPath);
+  const [name, version] = packageManager.split('@');
+  if (name !== 'pnpm') return;
+  const required = PNPM_MAJOR_MIN_NODE[version.split('.')[0]];
+  if (!required) return;
+
+  const check = checkWebArtifactNodeVersion(await detectSubprocessNodeVersion(cwd), required, packageManager);
+  if (!check.ok) throw new Error(check.message);
+}
+
 export async function executeWebArtifactBuild(input: WebArtifactBuildInput): Promise<WebArtifactBuildOutput> {
   const workspaceRoot = currentWorkspaceRoot();
   const artifactsDir = ensureArtifactsDir(workspaceRoot);
@@ -490,6 +598,7 @@ export async function executeWebArtifactBuild(input: WebArtifactBuildInput): Pro
   const parentDir = dirname(projectPath);
   mkdirSync(parentDir, { recursive: true });
   ensurePackageManagerBoundary(parentDir);
+  await preflightBuildRuntime(parentDir, projectPath);
 
   let stdout = '';
   let stderr = '';

package/src/shared/ax-flow.ts

@@ -0,0 +1,102 @@
+/**
+ * The node-data contract for a materialized AX flow.
+ *
+ * `ax.flow.materialize` stamps every step node with `data.axStep` and the anchor
+ * (first) step with `data.axFlow`. Three consumers read those stamps and none of
+ * them owns the shape, so it lives here:
+ *   - the server loop (`ax-flow-loop.ts`) advances the flow from work-item changes
+ *   - the browser renders native Start/Done/Blocked + Run loop/Stop controls
+ *   - snapshots/restore carry the stamps as ordinary node data
+ *
+ * Node data is `Record<string, unknown>` on both sides, so the readers below are
+ * the ONLY way to narrow it: they validate rather than cast, because a stamp can
+ * also arrive from a restored snapshot or a hand-edited node.
+ */
+
+/** Hard ceiling on loop passes, whatever a node's stamped `maxRuns` claims. */
+export const AX_FLOW_LOOP_HARD_CAP = 20;
+
+/** One step of a flow, as recorded on the anchor node. */
+export interface AxFlowStepRef {
+  /** 1-based position in the flow. */
+  index: number;
+  nodeId: string;
+  workItemId: string;
+  title: string;
+}
+
+export interface AxFlowLoopState {
+  /** The loop only advances while this is true; Stop persists `false`. */
+  running: boolean;
+  /** Completed passes. `run >= maxRuns` ends the loop. */
+  run: number;
+  maxRuns: number;
+}
+
+/** `data.axStep` — stamped on EVERY step node, including the anchor. */
+export interface AxFlowStepStamp {
+  flowId: string;
+  index: number;
+  total: number;
+  workItemId: string;
+}
+
+/** `data.axFlow` — stamped on the anchor (first) step node only. */
+export interface AxFlowStamp {
+  flowId: string;
+  title: string;
+  steps: AxFlowStepRef[];
+  loop: AxFlowLoopState;
+}
+
+/** Clamp a stamped `maxRuns` into [1, AX_FLOW_LOOP_HARD_CAP]. */
+export function clampAxFlowMaxRuns(value: unknown): number {
+  const n = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : 1;
+  return Math.max(1, Math.min(AX_FLOW_LOOP_HARD_CAP, n));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/** Read `data.axStep`, or null when the node carries no valid step stamp. */
+export function readAxStep(data: Record<string, unknown>): AxFlowStepStamp | null {
+  const step = data.axStep;
+  if (!isRecord(step)) return null;
+  if (!nonEmptyString(step.flowId) || !nonEmptyString(step.workItemId)) return null;
+  if (typeof step.index !== 'number' || typeof step.total !== 'number') return null;
+  return { flowId: step.flowId, index: step.index, total: step.total, workItemId: step.workItemId };
+}
+
+/** Read `data.axFlow`, or null when the node is not a flow anchor. */
+export function readAxFlow(data: Record<string, unknown>): AxFlowStamp | null {
+  const flow = data.axFlow;
+  if (!isRecord(flow) || !nonEmptyString(flow.flowId) || !Array.isArray(flow.steps)) return null;
+  const steps: AxFlowStepRef[] = [];
+  for (const raw of flow.steps) {
+    if (!isRecord(raw) || !nonEmptyString(raw.nodeId) || !nonEmptyString(raw.workItemId)) return null;
+    if (typeof raw.index !== 'number') return null;
+    steps.push({
+      index: raw.index,
+      nodeId: raw.nodeId,
+      workItemId: raw.workItemId,
+      title: typeof raw.title === 'string' ? raw.title : '',
+    });
+  }
+  if (steps.length === 0) return null;
+  const loop = isRecord(flow.loop) ? flow.loop : {};
+  return {
+    flowId: flow.flowId,
+    title: typeof flow.title === 'string' ? flow.title : 'Flow',
+    steps,
+    loop: {
+      running: loop.running === true,
+      run: typeof loop.run === 'number' && Number.isFinite(loop.run) ? Math.max(0, Math.floor(loop.run)) : 0,
+      maxRuns: clampAxFlowMaxRuns(loop.maxRuns),
+    },
+  };
+}

package/src/shared/node-sizes.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-type minimum node size — the readability floor.
+ *
+ * Agents frequently create nodes with explicit frames far too small for their
+ * content (clipped markdown, charts squeezed behind inner scrollbars), so the
+ * server clamps undersized explicit sizes UP at creation and `validate` reports
+ * anything below the floor.
+ *
+ * This lives in `shared/` because BOTH sides must honor it. The 0.4.6 report's
+ * Finding AA: the server clamped a 200x100 markdown node up to 360x180, and
+ * then the browser's DOM auto-fit measured the (short) content and persisted
+ * 360x132 — undoing the guarantee on the most common path, a connected
+ * workbench. A floor only one side knows about is not a floor.
+ *
+ * `strictSize: true` is the escape hatch for a deliberately small fixed frame,
+ * and it exempts a node from both the creation clamp and the auto-fit floor.
+ * Types absent from the table are intentionally unclamped — `trace` is small by
+ * design, `group` sizes to its children.
+ */
+export const NODE_MIN_SIZES: Record<string, { width: number; height: number }> = {
+  markdown: { width: 360, height: 180 },
+  context: { width: 360, height: 180 },
+  file: { width: 360, height: 200 },
+  diff: { width: 420, height: 240 },
+  mermaid: { width: 360, height: 240 },
+  status: { width: 280, height: 120 },
+  ledger: { width: 320, height: 200 },
+  image: { width: 240, height: 180 },
+  html: { width: 420, height: 280 },
+  webpage: { width: 420, height: 280 },
+  'json-render': { width: 420, height: 280 },
+  graph: { width: 420, height: 280 },
+  'mcp-app': { width: 480, height: 320 },
+};
+
+/** The readability floor for a node type, or undefined when it has none. */
+export function nodeMinSize(type: string): { width: number; height: number } | undefined {
+  return NODE_MIN_SIZES[type];
+}
+
+/** Creation-time clamp: an explicit size below the floor is raised to it. */
+export function clampCreateNodeSize(
+  type: string,
+  width: number,
+  height: number,
+  strictSize?: boolean,
+): { width: number; height: number } {
+  if (strictSize === true) return { width, height };
+  const min = nodeMinSize(type);
+  if (!min) return { width, height };
+  return { width: Math.max(width, min.width), height: Math.max(height, min.height) };
+}

package/dist/types/server/chart-template.d.ts

@@ -1,29 +0,0 @@
-/**
- * Chart HTML template generator — produces self-contained ext-app HTML
- * documents that render interactive Chart.js charts inside the canvas
- * ExtAppFrame iframe.
- *
- * The generated HTML:
- * 1. Renders immediately from inline data (no bridge needed)
- * 2. Connects to host AppBridge via the embedded ext-app App SDK runtime
- * 3. Accepts updated data via toolInput for re-rendering
- */
-export interface ChartDataset {
-    label: string;
-    values: number[];
-    color?: string;
-}
-export interface ChartConfig {
-    title: string;
-    chartType: 'bar' | 'line' | 'pie' | 'scatter' | 'doughnut' | 'radar';
-    labels: string[];
-    datasets: ChartDataset[];
-    xAxisLabel?: string;
-    yAxisLabel?: string;
-    stacked?: boolean;
-}
-/**
- * Generate a self-contained HTML document that renders a Chart.js chart
- * and optionally connects to the host via the ext-app App SDK.
- */
-export declare function generateChartHtml(config: ChartConfig): string;