pmx-canvas 0.4.4 → 0.4.6

package/src/server/canvas-db.ts

@@ -178,7 +178,8 @@ const SCHEMA_SQL = `
     node_ids TEXT NOT NULL DEFAULT '[]',
     data TEXT,
     created_at TEXT NOT NULL,
-    source TEXT
+    source TEXT,
+    agent_id TEXT
   );
   CREATE INDEX IF NOT EXISTS idx_ax_events_seq ON ax_events (seq);
 
@@ -202,7 +203,9 @@ const SCHEMA_SQL = `
     message TEXT NOT NULL,
     delivered INTEGER NOT NULL DEFAULT 0,
     created_at TEXT NOT NULL,
-    source TEXT
+    source TEXT,
+    agent_id TEXT,
+    target TEXT
   );
   CREATE INDEX IF NOT EXISTS idx_ax_steering_seq ON ax_steering (seq);
 
@@ -213,6 +216,22 @@ const SCHEMA_SQL = `
   );
 `;
 
+/** Idempotently add a column to an existing table (no prior-migrations system in this repo). */
+function ensureColumn(db: Database, table: string, column: string, ddl: string): void {
+  interface ColumnInfoRow {
+    name: string;
+  }
+  const columns = db.query<ColumnInfoRow, []>(`PRAGMA table_info(${table})`).all();
+  if (columns.some((c) => c.name === column)) return;
+  try {
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${ddl}`);
+  } catch (error) {
+    // Two processes can race the check-then-ALTER on the first post-upgrade
+    // open; the loser's duplicate-column error means the column exists — done.
+    if (!/duplicate column/i.test(error instanceof Error ? error.message : String(error))) throw error;
+  }
+}
+
 function normalizePositiveInteger(value: number | undefined): number | undefined {
   if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return undefined;
   return Math.floor(value);
@@ -258,6 +277,11 @@ export function openCanvasDb(dbPath: string): Database {
   db.exec('PRAGMA busy_timeout=5000');
   db.exec(SCHEMA_SQL);
 
+  // Additive columns for pre-existing DBs (fresh installs already get them via SCHEMA_SQL above).
+  ensureColumn(db, 'ax_events', 'agent_id', 'agent_id TEXT');
+  ensureColumn(db, 'ax_steering', 'agent_id', 'agent_id TEXT');
+  ensureColumn(db, 'ax_steering', 'target', 'target TEXT');
+
   // Set schema version if not present
   const row = db.query<{ value: string }, [string]>('SELECT value FROM meta WHERE key = ?').get('schema_version');
   if (!row) {
@@ -858,7 +882,7 @@ function readLastSeq(db: Database, table: 'ax_events' | 'ax_evidence' | 'ax_stee
 
 export function appendAxEventToDB(db: Database, ev: Omit<PmxAxEvent, 'seq'>): PmxAxEvent {
   db.run(
-    'INSERT INTO ax_events (id, kind, summary, detail, node_ids, data, created_at, source) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+    'INSERT INTO ax_events (id, kind, summary, detail, node_ids, data, created_at, source, agent_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
     [
       ev.id,
       ev.kind,
@@ -868,6 +892,7 @@ export function appendAxEventToDB(db: Database, ev: Omit<PmxAxEvent, 'seq'>): Pm
       ev.data ? JSON.stringify(ev.data) : null,
       ev.createdAt,
       ev.source,
+      ev.agentId,
     ],
   );
   const seq = readLastSeq(db, 'ax_events');
@@ -896,20 +921,20 @@ export function appendAxEvidenceToDB(db: Database, ev: Omit<PmxAxEvidence, 'seq'
 }
 
 export function appendAxSteeringToDB(db: Database, s: Omit<PmxAxSteeringMessage, 'seq'>): PmxAxSteeringMessage {
-  db.run('INSERT INTO ax_steering (id, message, delivered, created_at, source) VALUES (?, ?, ?, ?, ?)', [
-    s.id,
-    s.message,
-    s.delivered ? 1 : 0,
-    s.createdAt,
-    s.source,
-  ]);
+  db.run(
+    'INSERT INTO ax_steering (id, message, delivered, created_at, source, agent_id, target) VALUES (?, ?, ?, ?, ?, ?, ?)',
+    [s.id, s.message, s.delivered ? 1 : 0, s.createdAt, s.source, s.agentId, s.target],
+  );
   const seq = readLastSeq(db, 'ax_steering');
   trimAxTable(db, 'ax_steering');
   return { ...s, seq };
 }
 
 export function markAxSteeringDeliveredInDB(db: Database, id: string): boolean {
-  const r = db.run('UPDATE ax_steering SET delivered = 1 WHERE id = ?', [id]);
+  // Compare-and-set: true ONLY on the undelivered→delivered transition. Two
+  // adapters racing the same steer see exactly one true — the loser (and any
+  // re-mark) gets false and must not treat the message as its own delivery.
+  const r = db.run('UPDATE ax_steering SET delivered = 1 WHERE id = ? AND delivered = 0', [id]);
   return r.changes > 0;
 }
 
@@ -924,6 +949,7 @@ export function loadAxEventsFromDB(db: Database, q: AxTimelineQuery = {}): PmxAx
     data: string | null;
     created_at: string;
     source: string | null;
+    agent_id: string | null;
   }
   const rows = db
     .query<Row, [number]>('SELECT * FROM ax_events ORDER BY seq DESC LIMIT ?')
@@ -935,6 +961,7 @@ export function loadAxEventsFromDB(db: Database, q: AxTimelineQuery = {}): PmxAx
         createdAt: r.created_at,
         nodeIds: safeParseJson(r.node_ids),
         data: safeParseJson(r.data),
+        agentId: r.agent_id,
       }),
     )
     .filter((e): e is PmxAxEvent => e !== null);
@@ -968,58 +995,62 @@ export function loadAxEvidenceFromDB(db: Database, q: AxTimelineQuery = {}): Pmx
     .filter((e): e is PmxAxEvidence => e !== null);
 }
 
+interface AxSteeringRow {
+  seq: number;
+  id: string;
+  message: string;
+  delivered: number;
+  created_at: string;
+  source: string | null;
+  agent_id: string | null;
+  target: string | null;
+}
+
+function mapAxSteeringRow(r: AxSteeringRow): PmxAxSteeringMessage | null {
+  return normalizeAxSteeringMessage({
+    ...r,
+    createdAt: r.created_at,
+    delivered: r.delivered === 1,
+    agentId: r.agent_id,
+  });
+}
+
 export function loadAxSteeringFromDB(
   db: Database,
   q: AxTimelineQuery & { onlyPending?: boolean } = {},
 ): PmxAxSteeringMessage[] {
-  interface Row {
-    seq: number;
-    id: string;
-    message: string;
-    delivered: number;
-    created_at: string;
-    source: string | null;
-  }
   const sql = q.onlyPending
     ? 'SELECT * FROM ax_steering WHERE delivered = 0 ORDER BY seq DESC LIMIT ?'
     : 'SELECT * FROM ax_steering ORDER BY seq DESC LIMIT ?';
-  const rows = db.query<Row, [number]>(sql).all(clampTimelineLimit(q.limit));
-  return rows
-    .map((r) => normalizeAxSteeringMessage({ ...r, createdAt: r.created_at, delivered: r.delivered === 1 }))
-    .filter((s): s is PmxAxSteeringMessage => s !== null);
+  const rows = db.query<AxSteeringRow, [number]>(sql).all(clampTimelineLimit(q.limit));
+  return rows.map(mapAxSteeringRow).filter((s): s is PmxAxSteeringMessage => s !== null);
 }
 
 export function loadPendingAxSteeringFromDB(
   db: Database,
   options: { consumer?: string; limit?: number } = {},
 ): PmxAxSteeringMessage[] {
-  interface Row {
-    seq: number;
-    id: string;
-    message: string;
-    delivered: number;
-    created_at: string;
-    source: string | null;
-  }
-  // FIFO (oldest undelivered first); exclude the consumer's own steering in SQL
-  // so the LIMIT is applied AFTER loop-prevention, not before.
+  // FIFO (oldest undelivered first); exclude the consumer's own steering (loop
+  // prevention) and any steering addressed to a DIFFERENT consumer (target scoping)
+  // in SQL so the LIMIT is applied AFTER both filters, not before.
   const limit = clampTimelineLimit(options.limit);
   const rows = options.consumer
     ? db
-        .query<Row, [string, number]>(
-          'SELECT * FROM ax_steering WHERE delivered = 0 AND (source IS NULL OR source != ?) ORDER BY seq ASC LIMIT ?',
+        .query<AxSteeringRow, [string, string, string, number]>(
+          'SELECT * FROM ax_steering WHERE delivered = 0 AND (source IS NULL OR source != ?) AND (agent_id IS NULL OR agent_id != ?) AND (target IS NULL OR target = ?) ORDER BY seq ASC LIMIT ?',
         )
-        .all(options.consumer, limit)
-    : db.query<Row, [number]>('SELECT * FROM ax_steering WHERE delivered = 0 ORDER BY seq ASC LIMIT ?').all(limit);
-  return rows
-    .map((r) => normalizeAxSteeringMessage({ ...r, createdAt: r.created_at, delivered: r.delivered === 1 }))
-    .filter((s): s is PmxAxSteeringMessage => s !== null);
+        .all(options.consumer, options.consumer, options.consumer, limit)
+    : db
+        .query<AxSteeringRow, [number]>('SELECT * FROM ax_steering WHERE delivered = 0 ORDER BY seq ASC LIMIT ?')
+        .all(limit);
+  return rows.map(mapAxSteeringRow).filter((s): s is PmxAxSteeringMessage => s !== null);
 }
 
 /**
  * NEWEST undelivered steering first (report #57) for the compact AX context lead
  * block — so a fresh steer is visible even behind a long backlog. Loop-safe: excludes
- * the consumer's own steering in SQL so the LIMIT applies after loop-prevention.
+ * the consumer's own steering and steering targeted at a different consumer in SQL
+ * so the LIMIT applies after both filters.
  * Distinct from loadPendingAxSteeringFromDB (FIFO oldest-first) which the claim/ack
  * delivery queue uses for ordered processing.
  */
@@ -1027,35 +1058,27 @@ export function loadNewestPendingAxSteeringFromDB(
   db: Database,
   options: { consumer?: string; limit?: number } = {},
 ): PmxAxSteeringMessage[] {
-  interface Row {
-    seq: number;
-    id: string;
-    message: string;
-    delivered: number;
-    created_at: string;
-    source: string | null;
-  }
   const limit = clampTimelineLimit(options.limit);
   const rows = options.consumer
     ? db
-        .query<Row, [string, number]>(
-          'SELECT * FROM ax_steering WHERE delivered = 0 AND (source IS NULL OR source != ?) ORDER BY seq DESC LIMIT ?',
+        .query<AxSteeringRow, [string, string, string, number]>(
+          'SELECT * FROM ax_steering WHERE delivered = 0 AND (source IS NULL OR source != ?) AND (agent_id IS NULL OR agent_id != ?) AND (target IS NULL OR target = ?) ORDER BY seq DESC LIMIT ?',
         )
-        .all(options.consumer, limit)
-    : db.query<Row, [number]>('SELECT * FROM ax_steering WHERE delivered = 0 ORDER BY seq DESC LIMIT ?').all(limit);
-  return rows
-    .map((r) => normalizeAxSteeringMessage({ ...r, createdAt: r.created_at, delivered: r.delivered === 1 }))
-    .filter((s): s is PmxAxSteeringMessage => s !== null);
+        .all(options.consumer, options.consumer, options.consumer, limit)
+    : db
+        .query<AxSteeringRow, [number]>('SELECT * FROM ax_steering WHERE delivered = 0 ORDER BY seq DESC LIMIT ?')
+        .all(limit);
+  return rows.map(mapAxSteeringRow).filter((s): s is PmxAxSteeringMessage => s !== null);
 }
 
-/** Total undelivered steering for a consumer (loop-safe — excludes the consumer's own). */
+/** Total undelivered steering for a consumer (loop-safe — excludes the consumer's own; target-scoped). */
 export function countPendingAxSteeringFromDB(db: Database, consumer?: string): number {
   const n = consumer
     ? db
-        .query<{ n: number }, [string]>(
-          'SELECT COUNT(*) AS n FROM ax_steering WHERE delivered = 0 AND (source IS NULL OR source != ?)',
+        .query<{ n: number }, [string, string, string]>(
+          'SELECT COUNT(*) AS n FROM ax_steering WHERE delivered = 0 AND (source IS NULL OR source != ?) AND (agent_id IS NULL OR agent_id != ?) AND (target IS NULL OR target = ?)',
         )
-        .get(consumer)?.n
+        .get(consumer, consumer, consumer)?.n
     : db.query<{ n: number }, []>('SELECT COUNT(*) AS n FROM ax_steering WHERE delivered = 0').get()?.n;
   return Number(n ?? 0);
 }

package/src/server/canvas-operations.ts

@@ -17,6 +17,7 @@ import {
   type ExternalMcpTransportConfig,
 } from './mcp-app-runtime.js';
 import { mutationHistory } from './mutation-history.js';
+import { clampCreateNodeSize } from './canvas-validation.js';
 import { computeGroupBounds, findOpenCanvasPosition } from './placement.js';
 import { searchNodes } from './spatial-analysis.js';
 import { getCanvasNodeTitle } from './canvas-serialization.js';
@@ -114,6 +115,10 @@ export const MCP_APP_NODE_DEFAULT_SIZE = { width: 960, height: 600 };
 export const IMAGE_NODE_DEFAULT_SIZE = { width: 480, height: 360 };
 export const LEDGER_NODE_DEFAULT_SIZE = { width: 420, height: 280 };
 
+// Per-type minimum creation sizes + clamp live in canvas-validation.ts
+// (NODE_MIN_CREATE_SIZES / clampCreateNodeSize) — shared with the validate
+// surface's sizeWarnings.
+
 interface CanvasCreateGroupInput {
   title?: string;
   childIds?: string[];
@@ -360,11 +365,20 @@ export function buildJsonRenderNodeUpdate(
   if (node.type !== 'json-render') throw new Error(`Node "${node.id}" is not a json-render node.`);
   const spec = normalizeAndValidateJsonRenderSpec(input.spec);
   const title = input.title?.trim() || inferJsonRenderNodeTitle(spec);
+  // Bump specVersion so the viewer URL changes: the iframe src is keyed on
+  // nodeId + ?v=specVersion, and the viewer only reads the spec at document
+  // load. Without the bump the src is byte-identical after a content update,
+  // the iframe never reloads, and the node renders stale forever (the live
+  // workboard's refresh depends on this).
+  const prevVersion = typeof node.data.specVersion === 'number' ? node.data.specVersion : 0;
   return {
     spec,
     data: {
       ...node.data,
-      ...createJsonRenderNodeData(node.id, title, spec, { viewerType: 'json-render' }),
+      ...createJsonRenderNodeData(node.id, title, spec, {
+        viewerType: 'json-render',
+        specVersion: prevVersion + 1,
+      }),
     },
   };
 }
@@ -906,8 +920,12 @@ export function addCanvasNode(input: CanvasAddNodeInput): {
     throw new Error(`Use the dedicated ${input.type} node APIs for structured viewer nodes.`);
   }
 
-  const width = input.width ?? input.defaultWidth ?? 720;
-  const height = input.height ?? input.defaultHeight ?? 600;
+  const { width, height } = clampCreateNodeSize(
+    input.type,
+    input.width ?? input.defaultWidth ?? 720,
+    input.height ?? input.defaultHeight ?? 600,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -1540,8 +1558,12 @@ export function createCanvasJsonRenderNode(input: JsonRenderNodeInput): {
   node: CanvasNodeState;
 } {
   const spec = normalizeAndValidateJsonRenderSpec(input.spec);
-  const width = input.width ?? JSON_RENDER_NODE_SIZE.width;
-  const height = input.height ?? JSON_RENDER_NODE_SIZE.height;
+  const { width, height } = clampCreateNodeSize(
+    'json-render',
+    input.width ?? JSON_RENDER_NODE_SIZE.width,
+    input.height ?? JSON_RENDER_NODE_SIZE.height,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -1580,8 +1602,12 @@ export function createCanvasStreamingJsonRenderNode(input: {
   strictSize?: boolean;
 }): { id: string; url: string; spec: JsonRenderSpec; node: CanvasNodeState } {
   const spec = emptyStreamingSpec();
-  const width = input.width ?? JSON_RENDER_NODE_SIZE.width;
-  const height = input.height ?? JSON_RENDER_NODE_SIZE.height;
+  const { width, height } = clampCreateNodeSize(
+    'json-render',
+    input.width ?? JSON_RENDER_NODE_SIZE.width,
+    input.height ?? JSON_RENDER_NODE_SIZE.height,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -1652,8 +1678,12 @@ export function createCanvasGraphNode(input: GraphNodeInput): {
 } {
   const title = input.title?.trim() || 'Graph';
   const spec = buildGraphSpec(input);
-  const width = input.width ?? GRAPH_NODE_SIZE.width;
-  const height = input.heightPx ?? GRAPH_NODE_SIZE.height;
+  const { width, height } = clampCreateNodeSize(
+    'graph',
+    input.width ?? GRAPH_NODE_SIZE.width,
+    input.heightPx ?? GRAPH_NODE_SIZE.height,
+    input.strictSize,
+  );
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }

package/src/server/canvas-provenance.ts

@@ -14,6 +14,8 @@ export type CanvasNodeType =
   | 'ledger'
   | 'trace'
   | 'file'
+  | 'diff'
+  | 'mermaid'
   | 'image'
   | 'html'
   | 'group';

package/src/server/canvas-schema.ts

@@ -209,6 +209,39 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       'Path-backed file nodes automatically persist `data.provenance` with a file URI and file-watch refresh strategy.',
     ],
   },
+  {
+    type: 'diff',
+    kind: 'node',
+    description: 'Unified diff viewer with per-file sections and colored add/remove lines.',
+    endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_node (action:"add")',
+    fields: [
+      { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
+      { name: 'content', type: 'string', required: false, description: 'Unified diff text (git or raw hunks).' },
+    ],
+    example: {
+      type: 'diff',
+      title: 'Fix null check',
+      content: '--- a/src/app.ts\n+++ b/src/app.ts\n@@ -1,3 +1,3 @@\n-const a = b.c;\n+const a = b?.c;\n context',
+    },
+  },
+  {
+    type: 'mermaid',
+    kind: 'node',
+    description:
+      'Text-to-diagram node rendered client-side with Mermaid (flowcharts, sequence, state, class diagrams, …).',
+    endpoint: '/api/canvas/node',
+    mcpTool: 'canvas_node (action:"add")',
+    fields: [
+      { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
+      { name: 'content', type: 'string', required: false, description: 'Mermaid diagram source text.' },
+    ],
+    example: {
+      type: 'mermaid',
+      title: 'Request flow',
+      content: 'graph TD; A[Client] --> B[Server]; B --> C[(DB)];',
+    },
+  },
   {
     type: 'image',
     kind: 'node',

package/src/server/canvas-state.ts

@@ -175,6 +175,8 @@ export interface CanvasNodeState {
     | 'ledger'
     | 'trace'
     | 'file'
+    | 'diff'
+    | 'mermaid'
     | 'image'
     | 'html'
     | 'group';
@@ -368,6 +370,28 @@ class CanvasStateManager {
     };
   }
 
+  // ── Work-item change listener (single slot, for live workboard refresh) ──
+  private _workItemsChangedListener: (() => void) | null = null;
+
+  /**
+   * Register THE work-item change listener (single slot, last-write-wins).
+   * Fired after addWorkItem/updateWorkItem completes (including the node
+   * status mirror), so live views like the workboard can rebuild from the
+   * fresh work-item list.
+   */
+  setWorkItemsChangedListener(listener: (() => void) | null): void {
+    this._workItemsChangedListener = listener;
+  }
+
+  private notifyWorkItemsChanged(): void {
+    if (!this._workItemsChangedListener) return;
+    try {
+      this._workItemsChangedListener();
+    } catch (error) {
+      logCanvasStateWarning('work-items-changed listener failed', error);
+    }
+  }
+
   private notifyChange(type: CanvasChangeType): void {
     // Iterate a snapshot: a listener (e.g. a blocking-wait via onChange) may dispose
     // itself synchronously here, and splicing the live array mid-iteration would skip
@@ -1716,18 +1740,63 @@ class CanvasStateManager {
   }
 
   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 {
-    return this.ax.addWorkItem(input, options);
+    const item = this.ax.addWorkItem(input, options);
+    this.mirrorAxWorkStatusToNodes(item.nodeIds, [], item.status);
+    this.notifyWorkItemsChanged();
+    return item;
   }
 
   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 {
-    return this.ax.updateWorkItem(id, patch, options);
+    const previousNodeIds = this.ax.getWorkItems().find((w) => w.id === id)?.nodeIds ?? [];
+    const item = this.ax.updateWorkItem(id, patch, options);
+    if (!item) return null;
+    this.mirrorAxWorkStatusToNodes(item.nodeIds, previousNodeIds, item.status);
+    this.notifyWorkItemsChanged();
+    return item;
+  }
+
+  /**
+   * Mirror a work item's status onto every linked canvas node's `data.axWorkStatus`,
+   * through the standard node-update path (persistence + undo/redo, same as any other
+   * node data change). Nodes unlinked by an updateWorkItem nodeIds change have the
+   * mirrored status cleared.
+   */
+  private mirrorAxWorkStatusToNodes(nodeIds: string[], previousNodeIds: string[], status: PmxAxWorkItemStatus): void {
+    for (const nodeId of nodeIds) {
+      const node = this.nodes.get(nodeId);
+      if (!node) continue;
+      // No-op guard: a title-/agentId-only work-item patch must not push
+      // history entries and SSE churn for chips that aren't changing.
+      if (node.data.axWorkStatus === status) continue;
+      this.updateNode(nodeId, { data: { ...node.data, axWorkStatus: status } });
+    }
+    for (const nodeId of previousNodeIds) {
+      if (nodeIds.includes(nodeId)) continue;
+      const node = this.nodes.get(nodeId);
+      if (!node || node.data.axWorkStatus === undefined) continue;
+      const data = { ...node.data };
+      delete data.axWorkStatus;
+      this.updateNode(nodeId, { data });
+    }
   }
 
   // ── Approval gates (canvas-bound) ─────────────────────────────────
@@ -1873,7 +1942,7 @@ class CanvasStateManager {
       nodeIds?: string[];
       data?: Record<string, unknown> | null;
     },
-    options: { source?: PmxAxSource } = {},
+    options: { source?: PmxAxSource; agentId?: string | null } = {},
   ): PmxAxEvent {
     return this.ax.recordAxEvent(input, options);
   }
@@ -1892,7 +1961,10 @@ class CanvasStateManager {
     return this.ax.addEvidence(input, options);
   }
 
-  recordSteeringMessage(message: string, options: { source?: PmxAxSource } = {}): PmxAxSteeringMessage {
+  recordSteeringMessage(
+    message: string,
+    options: { source?: PmxAxSource; agentId?: string | null; target?: string | null } = {},
+  ): PmxAxSteeringMessage {
     return this.ax.recordSteeringMessage(message, options);
   }
 

package/src/server/canvas-validation.ts

@@ -1,6 +1,47 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import { getCanvasNodeTitle } from './canvas-serialization.js';
 
+/**
+ * Per-type minimum node size (0.4.5 report follow-up): agents frequently
+ * create nodes with explicit frames far too small for their content — clipped
+ * markdown, charts squeezed behind inner scrollbars. Explicit sizes below the
+ * floor are clamped UP at creation (canvas-operations.ts creators);
+ * `strictSize: true` is the escape hatch for a genuinely small fixed frame.
+ * Floors sit below every type default and above the point of unreadability.
+ * Creation-only: later updates are untouched (the browser's drag-resize
+ * enforces its own 200×100 floor client-side), but `validate` reports any
+ * node below its floor as an advisory sizeWarning. Absent types (trace,
+ * group, prompt/response) are intentionally unclamped — trace is small by
+ * design, groups size to their children.
+ */
+export const NODE_MIN_CREATE_SIZES: Partial<Record<CanvasNodeState['type'], { 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 },
+};
+
+export function clampCreateNodeSize(
+  type: CanvasNodeState['type'],
+  width: number,
+  height: number,
+  strictSize?: boolean,
+): { width: number; height: number } {
+  if (strictSize === true) return { width, height };
+  const min = NODE_MIN_CREATE_SIZES[type];
+  if (!min) return { width, height };
+  return { width: Math.max(width, min.width), height: Math.max(height, min.height) };
+}
+
 export interface CanvasValidationPair {
   aId: string;
   aTitle: string | null;
@@ -15,12 +56,24 @@ export interface CanvasContainmentIssue {
   childTitle: string | null;
 }
 
+export interface CanvasSizeWarning {
+  id: string;
+  title: string | null;
+  type: CanvasNodeState['type'];
+  width: number;
+  height: number;
+  minWidth: number;
+  minHeight: number;
+}
+
 export interface CanvasValidationResult {
   ok: boolean;
   collisions: CanvasValidationPair[];
   containments: CanvasContainmentIssue[];
   containmentViolations: CanvasContainmentIssue[];
   missingEdgeEndpoints: Array<{ edgeId: string; from: string; to: string }>;
+  /** Nodes below their type's readable minimum (advisory — does not fail `ok`). */
+  sizeWarnings: CanvasSizeWarning[];
   summary: {
     nodes: number;
     edges: number;
@@ -28,6 +81,7 @@ export interface CanvasValidationResult {
     containments: number;
     containmentViolations: number;
     missingEdgeEndpoints: number;
+    sizeWarnings: number;
   };
 }
 
@@ -109,12 +163,36 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
     .filter((edge) => !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
     .map((edge) => ({ edgeId: edge.id, from: edge.from, to: edge.to }));
 
+  // Advisory: nodes below their type's readable floor (clipped/unreadable
+  // content — 0.4.5 report follow-up). Creation clamps these, but resized or
+  // strictSize-created nodes can still be undersized; surface them so an
+  // agent's validate pass sees the problem. Collapsed/docked nodes render as
+  // bars, and strictSize is the deliberate opt-out — all skipped.
+  const sizeWarnings: CanvasSizeWarning[] = layout.nodes
+    .filter((node) => !node.collapsed && node.dockPosition == null && node.data?.strictSize !== true)
+    .flatMap((node) => {
+      const min = NODE_MIN_CREATE_SIZES[node.type];
+      if (!min || (node.size.width >= min.width && node.size.height >= min.height)) return [];
+      return [
+        {
+          id: node.id,
+          title: getCanvasNodeTitle(node),
+          type: node.type,
+          width: node.size.width,
+          height: node.size.height,
+          minWidth: min.width,
+          minHeight: min.height,
+        },
+      ];
+    });
+
   return {
     ok: collisions.length === 0 && containmentViolations.length === 0 && missingEdgeEndpoints.length === 0,
     collisions,
     containments,
     containmentViolations,
     missingEdgeEndpoints,
+    sizeWarnings,
     summary: {
       nodes: layout.nodes.length,
       edges: layout.edges.length,
@@ -122,6 +200,7 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
       containments: containments.length,
       containmentViolations: containmentViolations.length,
       missingEdgeEndpoints: missingEdgeEndpoints.length,
+      sizeWarnings: sizeWarnings.length,
     },
   };
 }

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;
   /**