pmx-canvas 0.4.6 → 0.4.8

package/src/server/canvas-db.ts

@@ -273,7 +273,13 @@ export function openCanvasDb(dbPath: string): Database {
 
   const db = new Database(dbPath);
   db.exec('PRAGMA journal_mode=WAL');
-  db.exec('PRAGMA synchronous=NORMAL');
+  // FULL, not NORMAL: under WAL, NORMAL lets a host/OS-level crash lose the most
+  // recent commits (a clean process exit loses nothing either way). The reporter of
+  // issue #22 declined FULL specifically because a save rewrote the whole board, so
+  // an fsync per commit scaled with board size. Saves are incremental now — a
+  // typical save is a row or two — so that objection is gone and the durability is
+  // worth the fsync.
+  db.exec('PRAGMA synchronous=FULL');
   db.exec('PRAGMA busy_timeout=5000');
   db.exec(SCHEMA_SQL);
 
@@ -295,38 +301,117 @@ export function checkpointCanvasDb(db: Database): void {
   db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
 }
 
+/**
+ * Delete blob rows nothing references any more. Blobs are content-addressed and
+ * written with INSERT OR IGNORE, so editing a node's html supersedes its old blob
+ * and leaves it orphaned — without this, `canvas.db` (which is git-committable)
+ * would grow without bound once externalization applies to ordinary html nodes.
+ *
+ * References are collected by scanning the raw persisted JSON for sha256 fields
+ * rather than parsing every node. That deliberately OVER-approximates: a stray
+ * 64-hex string keeps a blob alive that could have been dropped, which wastes a
+ * little space. The opposite error would delete live content, so the scan is
+ * biased to the safe side on purpose. Snapshot rows are scanned too — a snapshot
+ * restore must still find its blobs.
+ */
+export function gcBlobsInDB(db: Database): number {
+  const referenced = new Set<string>();
+  const collect = (sql: string): void => {
+    for (const row of db.query<{ data: string }, []>(sql).all()) {
+      if (!row.data) continue;
+      for (const match of row.data.matchAll(/"sha256"\s*:\s*"([0-9a-f]{64})"/g)) referenced.add(match[1]);
+    }
+  };
+  collect('SELECT data FROM nodes');
+  collect('SELECT data FROM snapshot_nodes');
+
+  const all = db.query<{ sha256: string }, []>('SELECT sha256 FROM blobs').all();
+  const orphans = all.filter((row) => !referenced.has(row.sha256));
+  if (orphans.length === 0) return 0;
+  const remove = db.prepare('DELETE FROM blobs WHERE sha256 = ?');
+  const transaction = db.transaction(() => {
+    for (const row of orphans) remove.run(row.sha256);
+  });
+  transaction();
+  return orphans.length;
+}
+
 export function finalizeCanvasDbForClose(db: Database): void {
   checkpointCanvasDb(db);
-  db.exec('PRAGMA journal_mode=DELETE');
+  // The WAL→DELETE switch takes an exclusive lock, so it succeeds only when no
+  // other connection has the DB open — and that makes it the GC gate. GC deletes
+  // blob rows a second live process may still depend on: its in-memory nodes
+  // hold content-addressed refs, not content, so a GC'd blob is unrecoverable
+  // once that process re-saves (review of #22, reproduced). Locked ⇒ someone
+  // else is on this canvas: leave WAL in place and keep every blob.
+  try {
+    db.exec('PRAGMA journal_mode=DELETE');
+  } catch {
+    return;
+  }
+  gcBlobsInDB(db);
 }
 
 // ── State Persistence ───────────────────────────────────────────
 
+/**
+ * Drop rows whose id is no longer in the live state. Reads only the id column
+ * (index-only scan) so it stays cheap on large boards.
+ */
+function deleteMissingRows(
+  db: Database,
+  table: 'nodes' | 'edges' | 'annotations' | 'context_pins',
+  idColumn: 'id' | 'node_id',
+  keep: Set<string>,
+): void {
+  const rows = db.query<{ id: string }, []>(`SELECT ${idColumn} AS id FROM ${table}`).all();
+  if (rows.length === 0) return;
+  const remove = db.prepare(`DELETE FROM ${table} WHERE ${idColumn} = ?`);
+  for (const row of rows) {
+    if (!keep.has(row.id)) remove.run(row.id);
+  }
+}
+
 export function saveStateToDB(db: Database, state: PersistedCanvasState): void {
   const transaction = db.transaction(() => {
-    // Clear current state tables
-    db.run('DELETE FROM nodes');
-    db.run('DELETE FROM edges');
-    db.run('DELETE FROM annotations');
-    db.run('DELETE FROM context_pins');
-    db.run('DELETE FROM ax_state');
-
-    // Save viewport and UI preferences
-    db.run('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', ['theme', normalizeCanvasTheme(state.theme)]);
-    db.run('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', ['viewport_x', String(state.viewport.x)]);
-    db.run('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', ['viewport_y', String(state.viewport.y)]);
-    db.run('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', ['viewport_scale', String(state.viewport.scale)]);
-
+    // Rows are upserted only when a column actually differs, and rows that are
+    // gone are deleted by id. This used to be DELETE-all + INSERT-all, which
+    // rewrote every row on every debounced save: dragging one node rewrote the
+    // whole board, multi-MB html payloads included, so the write cost scaled
+    // with board size instead of change size (issue #22). The
+    // `WHERE ... IS NOT excluded....` guard makes an unchanged row a true
+    // no-op — SQLite performs no update, so no page is written. The comparison
+    // is against the DB itself rather than an in-memory cache, so nothing can
+    // go stale and silently skip a write that was actually needed.
+    const upsertMeta = db.prepare(
+      `INSERT INTO meta (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value
+       WHERE value IS NOT excluded.value`,
+    );
+    upsertMeta.run('theme', normalizeCanvasTheme(state.theme));
+    upsertMeta.run('viewport_x', String(state.viewport.x));
+    upsertMeta.run('viewport_y', String(state.viewport.y));
+    upsertMeta.run('viewport_scale', String(state.viewport.scale));
     // Mark DB as populated (for migration detection)
-    db.run('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', ['state_populated', '1']);
+    upsertMeta.run('state_populated', '1');
 
     // Save nodes
-    const insertNode = db.prepare(
+    const upsertNode = db.prepare(
       `INSERT INTO nodes (id, type, pos_x, pos_y, width, height, z_index, collapsed, pinned, dock_position, data)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         type = excluded.type, pos_x = excluded.pos_x, pos_y = excluded.pos_y,
+         width = excluded.width, height = excluded.height, z_index = excluded.z_index,
+         collapsed = excluded.collapsed, pinned = excluded.pinned,
+         dock_position = excluded.dock_position, data = excluded.data
+       WHERE type IS NOT excluded.type OR pos_x IS NOT excluded.pos_x
+          OR pos_y IS NOT excluded.pos_y OR width IS NOT excluded.width
+          OR height IS NOT excluded.height OR z_index IS NOT excluded.z_index
+          OR collapsed IS NOT excluded.collapsed OR pinned IS NOT excluded.pinned
+          OR dock_position IS NOT excluded.dock_position OR data IS NOT excluded.data`,
     );
     for (const node of state.nodes) {
-      insertNode.run(
+      upsertNode.run(
         node.id,
         node.type,
         node.position.x,
@@ -340,14 +425,21 @@ export function saveStateToDB(db: Database, state: PersistedCanvasState): void {
         JSON.stringify(node.data),
       );
     }
+    deleteMissingRows(db, 'nodes', 'id', new Set(state.nodes.map((node) => node.id)));
 
     // Save edges
-    const insertEdge = db.prepare(
+    const upsertEdge = db.prepare(
       `INSERT INTO edges (id, from_node, to_node, type, label, style, animated)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         from_node = excluded.from_node, to_node = excluded.to_node, type = excluded.type,
+         label = excluded.label, style = excluded.style, animated = excluded.animated
+       WHERE from_node IS NOT excluded.from_node OR to_node IS NOT excluded.to_node
+          OR type IS NOT excluded.type OR label IS NOT excluded.label
+          OR style IS NOT excluded.style OR animated IS NOT excluded.animated`,
     );
     for (const edge of state.edges) {
-      insertEdge.run(
+      upsertEdge.run(
         edge.id,
         edge.from,
         edge.to,
@@ -357,14 +449,24 @@ export function saveStateToDB(db: Database, state: PersistedCanvasState): void {
         edge.animated ? 1 : 0,
       );
     }
+    deleteMissingRows(db, 'edges', 'id', new Set(state.edges.map((edge) => edge.id)));
 
     // Save annotations
-    const insertAnnotation = db.prepare(
+    const annotations = state.annotations ?? [];
+    const upsertAnnotation = db.prepare(
       `INSERT INTO annotations (id, type, points, bounds, color, width, text, label, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         type = excluded.type, points = excluded.points, bounds = excluded.bounds,
+         color = excluded.color, width = excluded.width, text = excluded.text,
+         label = excluded.label, created_at = excluded.created_at
+       WHERE type IS NOT excluded.type OR points IS NOT excluded.points
+          OR bounds IS NOT excluded.bounds OR color IS NOT excluded.color
+          OR width IS NOT excluded.width OR text IS NOT excluded.text
+          OR label IS NOT excluded.label OR created_at IS NOT excluded.created_at`,
     );
-    for (const annotation of state.annotations ?? []) {
-      insertAnnotation.run(
+    for (const annotation of annotations) {
+      upsertAnnotation.run(
         annotation.id,
         annotation.type,
         JSON.stringify(annotation.points),
@@ -376,17 +478,21 @@ export function saveStateToDB(db: Database, state: PersistedCanvasState): void {
         annotation.createdAt,
       );
     }
+    deleteMissingRows(db, 'annotations', 'id', new Set(annotations.map((annotation) => annotation.id)));
 
-    // Save context pins
-    const insertPin = db.prepare('INSERT INTO context_pins (node_id) VALUES (?)');
+    // Save context pins (node_id is the whole row — nothing to update)
+    const insertPin = db.prepare('INSERT OR IGNORE INTO context_pins (node_id) VALUES (?)');
     for (const pinId of state.contextPins) {
       insertPin.run(pinId);
     }
+    deleteMissingRows(db, 'context_pins', 'node_id', new Set(state.contextPins));
 
-    db.run('INSERT INTO ax_state (key, value) VALUES (?, ?)', [
-      'state',
-      JSON.stringify(state.ax ?? createEmptyAxState()),
-    ]);
+    db.run(
+      `INSERT INTO ax_state (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value
+       WHERE value IS NOT excluded.value`,
+      ['state', JSON.stringify(state.ax ?? createEmptyAxState())],
+    );
   });
 
   transaction();

package/src/server/canvas-operations.ts

@@ -8,6 +8,7 @@ import {
   type CanvasNodeUpdate,
   type CanvasSnapshot,
 } from './canvas-state.js';
+import { applyFileContentToNodeData, readFileNodeContent } from './file-content.js';
 import { rewatchAllFileNodes, unwatchAll, unwatchFileForNode, watchFileForNode } from './file-watcher.js';
 import {
   closeMcpAppSession,
@@ -568,6 +569,11 @@ function prepareExtAppNodesForSessionSync(forceRehydrate: boolean): string[] {
 
       const transportConfig = normalizeTransportConfig(node.data.transportConfig);
       if (!transportConfig) {
+        // Only a node that HAD a session has one to fail restoring. A static
+        // ext-app node (no session, no transport — e.g. the demo board's
+        // showcase tile) would otherwise be stamped with a persisted error
+        // banner on every start after the first, for a session it never had.
+        if (!sessionId) continue;
         setExtAppRuntimeState(node.id, {
           appSessionId: null,
           sessionStatus: 'error',
@@ -748,19 +754,8 @@ function buildFileNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
     title: input.title ?? fileName,
   };
 
-  try {
-    if (existsSync(resolved)) {
-      const fileContent = readFileSync(resolved, 'utf-8');
-      const stat = statSync(resolved);
-      data.fileContent = fileContent;
-      data.lineCount = fileContent.split('\n').length;
-      data.updatedAt = new Date(stat.mtimeMs).toISOString();
-    }
-  } catch {
-    // Missing or unreadable files still render as path-backed file nodes.
-  }
-
-  return data;
+  // Missing or unreadable files still render as path-backed file nodes.
+  return applyFileContentToNodeData(data, readFileNodeContent(resolved));
 }
 
 function buildImageNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
@@ -833,7 +828,7 @@ function normalizeTraceNodeData(input: CanvasAddNodeInput): Record<string, unkno
   return data;
 }
 
-function buildNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
+function buildNodeDataForType(input: CanvasAddNodeInput): Record<string, unknown> {
   if (input.type === 'file') return buildFileNodeData(input);
   if (input.type === 'image') return buildImageNodeData(input);
   if (input.type === 'webpage') return buildWebpageNodeData(input);
@@ -842,10 +837,21 @@ function buildNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
     ...(input.data ?? {}),
     ...(input.title ? { title: input.title } : {}),
     ...(input.content ? { content: input.content } : {}),
-    ...(input.strictSize ? { strictSize: true } : {}),
   };
 }
 
+function buildNodeData(input: CanvasAddNodeInput): Record<string, unknown> {
+  const data = buildNodeDataForType(input);
+  // `strictSize` is type-agnostic — it exempts a node from BOTH the creation
+  // size clamp and the browser's auto-fit. It used to be applied inside each
+  // per-type builder, and the file / image / webpage builders return a fresh
+  // object without it, so those three silently dropped the flag: the clamp
+  // honored it (it reads `input.strictSize` directly) but nothing persisted
+  // `data.strictSize`, so auto-fit resized the node in the browser anyway.
+  // Applying it once here makes it uniform for every type.
+  return input.strictSize ? { ...data, strictSize: true } : data;
+}
+
 export function mergeTraceNodeDataFields(
   base: Record<string, unknown>,
   input: Record<string, unknown>,
@@ -1709,9 +1715,30 @@ export function createCanvasGraphNode(input: GraphNodeInput): {
   return { id, url: String(node.data.url), spec, node };
 }
 
+/**
+ * The connected workbench's actual window size, reported by the client (0.4.6
+ * orb feedback #2). `fit` used to compute against a hardcoded 1440x900, so an
+ * agent calling fit without dimensions produced a scale sized for a window the
+ * human did not have — the board overflowed and clipped on both sides. The
+ * client reports its size on connect and on resize; explicit width/height in a
+ * fit call still win. In-memory only (a live client fact, never persisted);
+ * with several clients connected, the most recent reporter wins.
+ */
+let lastClientViewportSize: { width: number; height: number } | null = null;
+
+export function setClientViewportSize(width: unknown, height: unknown): void {
+  if (typeof width !== 'number' || typeof height !== 'number') return;
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return;
+  lastClientViewportSize = { width, height };
+}
+
+export function getClientViewportSize(): { width: number; height: number } | null {
+  return lastClientViewportSize ? { ...lastClientViewportSize } : null;
+}
+
 export function fitCanvasView(options: CanvasFitViewOptions = {}): CanvasFitViewResult {
-  const width = positiveNumber(options.width, 1440);
-  const height = positiveNumber(options.height, 900);
+  const width = positiveNumber(options.width, lastClientViewportSize?.width ?? 1440);
+  const height = positiveNumber(options.height, lastClientViewportSize?.height ?? 900);
   const padding = positiveNumber(options.padding, 60);
   const maxScale = positiveNumber(options.maxScale, 1);
   const nodeIdFilter = options.nodeIds && options.nodeIds.length > 0 ? new Set(options.nodeIds) : null;

package/src/server/canvas-state.ts

@@ -1320,16 +1320,15 @@ class CanvasStateManager {
   }
 
   addNode(node: CanvasNodeState): void {
-    // Context nodes default to a right-docked, collapsed pill when created without
-    // an explicit dock position. CREATE-time default only — once placed, updates
-    // (including undock → dockPosition null) are respected (see normalizeNode).
-    // Skip during suppressed replay (undo/redo re-add) so a deliberately-undocked
-    // context node is restored verbatim instead of being snapped back to the dock.
-    const seeded =
-      node.type === 'context' && node.dockPosition == null && this._suppressRecordingDepth === 0
-        ? { ...node, dockPosition: 'right' as const, collapsed: true }
-        : node;
-    const cloned = structuredClone(this.normalizeNode(seeded));
+    // Docking is EXPLICIT (0.4.6). Context nodes used to auto-dock to a collapsed
+    // right-hand pill when created without a dock position, which meant an agent
+    // creating a context node — even at explicit coordinates — got a node that
+    // existed in the API and passed validation but never rendered on the canvas,
+    // and any edge to it terminated in empty space (0.4.6 orb feedback #1). The
+    // seeded HUD widgets (status-main / context-main) pass `dockPosition` on
+    // create, so the docked pills are unaffected; anything else reaches the
+    // canvas where the caller put it. Dock deliberately via node.update.
+    const cloned = structuredClone(this.normalizeNode(node));
     this.nodes.set(node.id, cloned);
     this.scheduleSave();
     this.notifyChange('nodes');
@@ -1722,6 +1721,17 @@ class CanvasStateManager {
     return this.ax.getAxState();
   }
 
+  /**
+   * Replace the canvas-bound AX partition from a persisted blob, normalized against
+   * the current node set — the same operation snapshot restore performs internally
+   * (`applyPersistedState`), exposed for the demo seed. Both restore nodes whose
+   * `data.axStep.workItemId` only resolves if the work items come back with their
+   * original ids, so this preserves them verbatim rather than re-creating them.
+   */
+  applyPersistedAxState(ax: unknown): void {
+    this.ax.applyPersistedAx(ax);
+  }
+
   getAxFocus(): PmxAxFocusState {
     return this.ax.getAxFocus();
   }

package/src/server/canvas-validation.ts

@@ -1,46 +1,11 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import { getCanvasNodeTitle } from './canvas-serialization.js';
+// The readability floor is SHARED with the client: the server clamps it at
+// creation and `validate` reports violations, but the browser's auto-fit must
+// honor the same floor or it silently undoes the clamp (0.4.6 Finding AA).
+import { nodeMinSize } from '../shared/node-sizes.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 { NODE_MIN_SIZES, clampCreateNodeSize, nodeMinSize } from '../shared/node-sizes.js';
 
 export interface CanvasValidationPair {
   aId: string;
@@ -66,12 +31,26 @@ export interface CanvasSizeWarning {
   minHeight: number;
 }
 
+export interface CanvasHiddenEdgeEndpoint {
+  edgeId: string;
+  nodeId: string;
+  nodeTitle: string | null;
+  dockPosition: 'left' | 'right';
+}
+
 export interface CanvasValidationResult {
   ok: boolean;
   collisions: CanvasValidationPair[];
   containments: CanvasContainmentIssue[];
   containmentViolations: CanvasContainmentIssue[];
   missingEdgeEndpoints: Array<{ edgeId: string; from: string; to: string }>;
+  /**
+   * Edges whose endpoint node is DOCKED — it renders in the HUD column, not on
+   * the canvas, so the edge visually terminates in empty space even though both
+   * endpoint IDs resolve (0.4.6 orb feedback #1). Advisory: reported for
+   * diagnosis, but does NOT fail `ok` (see the note at the return site).
+   */
+  hiddenEdgeEndpoints: CanvasHiddenEdgeEndpoint[];
   /** Nodes below their type's readable minimum (advisory — does not fail `ok`). */
   sizeWarnings: CanvasSizeWarning[];
   summary: {
@@ -81,6 +60,7 @@ export interface CanvasValidationResult {
     containments: number;
     containmentViolations: number;
     missingEdgeEndpoints: number;
+    hiddenEdgeEndpoints: number;
     sizeWarnings: number;
   };
 }
@@ -163,6 +143,28 @@ 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 }));
 
+  // An edge to a DOCKED node cannot be drawn: docked nodes live in the HUD
+  // column, and the world-space edge layer skips them, so the edge trails off
+  // into empty canvas. Structural validation used to miss this entirely because
+  // both endpoint IDs resolve (0.4.6 orb feedback #1).
+  const dockedById = new Map(
+    layout.nodes.filter((node) => node.dockPosition != null).map((node) => [node.id, node] as const),
+  );
+  const hiddenEdgeEndpoints: CanvasHiddenEdgeEndpoint[] = layout.edges.flatMap((edge) =>
+    [edge.from, edge.to].flatMap((nodeId) => {
+      const docked = dockedById.get(nodeId);
+      if (!docked || docked.dockPosition == null) return [];
+      return [
+        {
+          edgeId: edge.id,
+          nodeId,
+          nodeTitle: getCanvasNodeTitle(docked),
+          dockPosition: docked.dockPosition,
+        },
+      ];
+    }),
+  );
+
   // 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
@@ -171,7 +173,7 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
   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];
+      const min = nodeMinSize(node.type);
       if (!min || (node.size.width >= min.width && node.size.height >= min.height)) return [];
       return [
         {
@@ -187,11 +189,17 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
     });
 
   return {
+    // `hiddenEdgeEndpoints` is ADVISORY (like sizeWarnings): a docked endpoint
+    // is a rendering observation, not a structural defect, and folding it into
+    // `ok` would flip previously-healthy boards to ok:false with no user change
+    // — `ok` is a documented response field of a frozen surface, so that is a
+    // contract break, not a patch. It is still reported for diagnosis.
     ok: collisions.length === 0 && containmentViolations.length === 0 && missingEdgeEndpoints.length === 0,
     collisions,
     containments,
     containmentViolations,
     missingEdgeEndpoints,
+    hiddenEdgeEndpoints,
     sizeWarnings,
     summary: {
       nodes: layout.nodes.length,
@@ -200,6 +208,7 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
       containments: containments.length,
       containmentViolations: containmentViolations.length,
       missingEdgeEndpoints: missingEdgeEndpoints.length,
+      hiddenEdgeEndpoints: hiddenEdgeEndpoints.length,
       sizeWarnings: sizeWarnings.length,
     },
   };