pmx-canvas 0.4.5 → 0.4.7

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
@@ -1296,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');
@@ -1698,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();
   }
@@ -1727,6 +1761,7 @@ class CanvasStateManager {
   ): PmxAxWorkItem {
     const item = this.ax.addWorkItem(input, options);
     this.mirrorAxWorkStatusToNodes(item.nodeIds, [], item.status);
+    this.notifyWorkItemsChanged();
     return item;
   }
 
@@ -1745,6 +1780,7 @@ class CanvasStateManager {
     const item = this.ax.updateWorkItem(id, patch, options);
     if (!item) return null;
     this.mirrorAxWorkStatusToNodes(item.nodeIds, previousNodeIds, item.status);
+    this.notifyWorkItemsChanged();
     return item;
   }
 

package/src/server/canvas-validation.ts

@@ -1,5 +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';
+
+export { NODE_MIN_SIZES, clampCreateNodeSize, nodeMinSize } from '../shared/node-sizes.js';
 
 export interface CanvasValidationPair {
   aId: string;
@@ -15,12 +21,38 @@ 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 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: {
     nodes: number;
     edges: number;
@@ -28,6 +60,8 @@ export interface CanvasValidationResult {
     containments: number;
     containmentViolations: number;
     missingEdgeEndpoints: number;
+    hiddenEdgeEndpoints: number;
+    sizeWarnings: number;
   };
 }
 
@@ -109,12 +143,64 @@ 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
+  // 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 = nodeMinSize(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 {
+    // `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,
       edges: layout.edges.length,
@@ -122,6 +208,8 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
       containments: containments.length,
       containmentViolations: containmentViolations.length,
       missingEdgeEndpoints: missingEdgeEndpoints.length,
+      hiddenEdgeEndpoints: hiddenEdgeEndpoints.length,
+      sizeWarnings: sizeWarnings.length,
     },
   };
 }