pmx-canvas 0.4.8 → 0.5.0

package/src/server/canvas-state.ts

@@ -25,6 +25,7 @@ import {
   loadSnapshotFromDB,
   listSnapshotsFromDB,
   deleteSnapshotFromDB,
+  renameSnapshotInDB,
   writeBlobToDB,
   readBlobFromDB,
   isDbPopulated,
@@ -185,7 +186,6 @@ export interface CanvasNodeState {
   zIndex: number;
   collapsed: boolean;
   pinned: boolean;
-  dockPosition: 'left' | 'right' | null;
   data: Record<string, unknown>;
 }
 
@@ -235,7 +235,6 @@ export interface CanvasNodeUpdate {
   position?: { x: number; y: number };
   size?: { width: number; height: number };
   collapsed?: boolean;
-  dockPosition?: 'left' | 'right' | null;
 }
 
 export type CanvasChangeType = 'pins' | 'nodes' | 'ax' | 'ax-timeline';
@@ -246,6 +245,7 @@ export interface MutationRecordInfo {
     | 'updateNode'
     | 'removeNode'
     | 'addEdge'
+    | 'updateEdge'
     | 'removeEdge'
     | 'addAnnotation'
     | 'removeAnnotation'
@@ -267,7 +267,7 @@ export interface MutationRecordInfo {
     | 'arrange'
     | 'batch'
     | 'groupNodes'
-    | 'ungroupNodes'
+    | 'releaseGroupChildren'
     | 'viewport';
   description: string;
   forward: () => void;
@@ -288,20 +288,17 @@ function formatBatchUpdateDescription(updates: CanvasNodeUpdate[]): string {
   let moved = 0;
   let resized = 0;
   let collapsed = 0;
-  let docked = 0;
 
   for (const update of updates) {
     if (update.position) moved++;
     if (update.size) resized++;
     if (update.collapsed !== undefined) collapsed++;
-    if (update.dockPosition !== undefined) docked++;
   }
 
   const parts: string[] = [];
   if (moved > 0) parts.push(`${moved} moved`);
   if (resized > 0) parts.push(`${resized} resized`);
   if (collapsed > 0) parts.push(`${collapsed} collapsed`);
-  if (docked > 0) parts.push(`${docked} docked`);
 
   const prefix = `Updated ${updates.length} node${updates.length === 1 ? '' : 's'}`;
   return parts.length > 0 ? `${prefix} (${parts.join(', ')})` : prefix;
@@ -506,10 +503,6 @@ class CanvasStateManager {
   }
 
   private normalizeNode(node: CanvasNodeState): CanvasNodeState {
-    // Context nodes default to a right-docked, collapsed pill (see DockedNode.tsx),
-    // but that default is applied at CREATE time only — it must not be re-forced on
-    // every write, or the node could never be undocked. Undocking (dockPosition →
-    // null) is a deliberate user action and is respected here.
     return {
       ...node,
       data: normalizeCanvasNodeData(node.type, node.data),
@@ -874,16 +867,6 @@ class CanvasStateManager {
     return false;
   }
 
-  /**
-   * Whether this workspace's canvas DB already holds saved state. Used to gate
-   * brand-new-workspace seeding (e.g. the default docked status/context widgets)
-   * so we never add nodes to a canvas that already has content. Reflects the
-   * pre-run persisted flag until the next save.
-   */
-  hasPersistedState(): boolean {
-    return this._db ? isDbPopulated(this._db) : false;
-  }
-
   /** Debounced save — coalesces rapid mutations into a single write. */
   private scheduleSave(): void {
     if (!this._db) return;
@@ -1272,6 +1255,16 @@ class CanvasStateManager {
   }
 
   /** Delete a snapshot. */
+  renameSnapshot(id: string, name: string): boolean {
+    if (!this._db) return false;
+    try {
+      return renameSnapshotInDB(this._db, id, name);
+    } catch (error) {
+      logCanvasStateWarning('rename snapshot failed', error, { id, name });
+      return false;
+    }
+  }
+
   deleteSnapshot(id: string): boolean {
     // Try SQLite first
     if (this._db) {
@@ -1320,14 +1313,6 @@ class CanvasStateManager {
   }
 
   addNode(node: CanvasNodeState): void {
-    // 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();
@@ -1385,29 +1370,35 @@ class CanvasStateManager {
     const connectedEdges = existing ? this.getEdgesForNode(id).map((e) => structuredClone(e)) : [];
     const cloned = existing ? structuredClone(existing) : null;
     const oldAxState = this.getAxState();
+    const wasPinned = this._contextPinnedNodeIds.has(id);
+    // The enclosing group's membership before this removal — restored verbatim on undo.
+    let enclosingBefore: { id: string; children: string[] } | null = null;
+    // A removed group DISSOLVES: its children are released — into the enclosing
+    // group when nested, else to the board. This is the one implementation of
+    // ungroup, so the human's Ungroup and the agent's `group.remove` cannot differ.
+    let released: string[] = [];
 
-    // Prune from parent group's children list
     if (existing) {
       const parentGroupId = existing.data.parentGroup as string | undefined;
-      if (parentGroupId) {
-        const parent = this.nodes.get(parentGroupId);
-        if (parent && parent.type === 'group') {
-          const children = (parent.data.children as string[]) ?? [];
-          const pruned = children.filter((cid) => cid !== id);
-          this.nodes.set(parentGroupId, { ...parent, data: { ...parent.data, children: pruned } });
-        }
-      }
-      // If removing a group, clear parentGroup on all its children
+      const parent = parentGroupId ? this.nodes.get(parentGroupId) : undefined;
+      const enclosing = parent && parent.type === 'group' ? parent : null;
+      if (enclosing)
+        enclosingBefore = { id: enclosing.id, children: ((enclosing.data.children as string[]) ?? []).slice() };
       if (existing.type === 'group') {
-        const childIds = (existing.data.children as string[]) ?? [];
-        for (const cid of childIds) {
-          const child = this.nodes.get(cid);
-          if (!child) continue;
+        released = ((existing.data.children as string[]) ?? []).filter((cid) => this.nodes.has(cid));
+        for (const cid of released) {
+          const child = this.nodes.get(cid)!;
           const d = { ...child.data };
-          delete d.parentGroup;
+          if (enclosing) d.parentGroup = enclosing.id;
+          else delete d.parentGroup;
           this.nodes.set(cid, { ...child, data: d });
         }
       }
+      if (enclosing && enclosingBefore) {
+        // The removed node leaves the enclosing group; a dissolved group's children take its place.
+        const children = enclosingBefore.children.flatMap((cid) => (cid === id ? released : [cid]));
+        this.nodes.set(enclosing.id, { ...enclosing, data: { ...enclosing.data, children } });
+      }
     }
 
     this.nodes.delete(id);
@@ -1450,15 +1441,36 @@ class CanvasStateManager {
       );
     }
     if (cloned) {
+      const title = (cloned.data.title as string) ?? id;
       this.recordMutation({
         operationType: 'removeNode',
-        description: `Removed ${cloned.type} node "${(cloned.data.title as string) ?? id}"`,
+        description:
+          cloned.type === 'group'
+            ? `Dissolved group "${title}" — ${released.length} node${released.length === 1 ? '' : 's'} released`
+            : `Removed ${cloned.type} node "${title}"`,
         forward: this.suppressed(() => this.removeNode(id)),
         inverse: this.suppressed(() => {
           this.addNode(structuredClone(cloned));
+          // A restored group takes its children back; the enclosing group's membership is restored verbatim.
+          for (const cid of released) {
+            const child = this.nodes.get(cid);
+            if (child) this.nodes.set(cid, { ...child, data: { ...child.data, parentGroup: id } });
+          }
+          if (enclosingBefore) {
+            const enclosing = this.nodes.get(enclosingBefore.id);
+            if (enclosing) {
+              this.nodes.set(enclosing.id, {
+                ...enclosing,
+                data: { ...enclosing.data, children: enclosingBefore.children },
+              });
+            }
+          }
           for (const edge of connectedEdges) this.addEdge(structuredClone(edge));
+          if (wasPinned) this._contextPinnedNodeIds.add(id);
           this.ax.applyPersistedAx(oldAxState);
           this.scheduleSave();
+          this.notifyChange('nodes');
+          this.notifyChange('pins');
           this.notifyChange('ax');
         }),
       });
@@ -1497,6 +1509,46 @@ class CanvasStateManager {
     return true;
   }
 
+  updateEdge(id: string, patch: Partial<Pick<CanvasEdge, 'type' | 'label' | 'style' | 'animated'>>): CanvasEdge | null {
+    const existing = this.edges.get(id);
+    if (!existing) return null;
+    // Retyping onto an existing from/to/type triple would create the duplicate
+    // addEdge refuses.
+    if (patch.type && patch.type !== existing.type) {
+      for (const other of this.edges.values()) {
+        if (other.id !== id && other.from === existing.from && other.to === existing.to && other.type === patch.type) {
+          return null;
+        }
+      }
+    }
+    const before = structuredClone(existing);
+    const updated: CanvasEdge = { ...existing, ...patch };
+    // An explicit undefined in the patch clears the field (label/style/animated
+    // are optional on the wire shape — never store undefined values).
+    for (const key of ['label', 'style', 'animated'] as const) {
+      if (key in patch && patch[key] === undefined) delete updated[key];
+    }
+    const after = structuredClone(updated);
+    this.edges.set(id, updated);
+    this.scheduleSave();
+    this.notifyChange('nodes');
+    this.recordMutation({
+      operationType: 'updateEdge',
+      description: `Updated ${updated.type} edge ${updated.from} → ${updated.to}`,
+      forward: this.suppressed(() => {
+        this.edges.set(id, structuredClone(after));
+        this.scheduleSave();
+        this.notifyChange('nodes');
+      }),
+      inverse: this.suppressed(() => {
+        this.edges.set(id, structuredClone(before));
+        this.scheduleSave();
+        this.notifyChange('nodes');
+      }),
+    });
+    return structuredClone(updated);
+  }
+
   removeEdge(id: string): boolean {
     const existing = this.edges.get(id);
     const cloned = existing ? structuredClone(existing) : null;
@@ -1612,9 +1664,6 @@ class CanvasStateManager {
       if (update.collapsed !== undefined && update.collapsed !== existing.collapsed) {
         nextPatch.collapsed = update.collapsed;
       }
-      if (update.dockPosition !== undefined && update.dockPosition !== existing.dockPosition) {
-        nextPatch.dockPosition = update.dockPosition;
-      }
       if (Object.keys(nextPatch).length === 0) {
         skipped++;
         continue;
@@ -1815,7 +1864,7 @@ class CanvasStateManager {
   }
 
   requestApproval(
-    input: { title: string; detail?: string | null; action?: string | null; nodeIds?: string[] },
+    input: { title: string; detail?: string | null; action?: string | null; nodeIds?: string[]; ttlMs?: number },
     options: { source?: PmxAxSource } = {},
   ): PmxAxApprovalGate {
     return this.ax.requestApproval(input, options);
@@ -1823,12 +1872,17 @@ class CanvasStateManager {
 
   resolveApproval(
     id: string,
-    decision: 'approved' | 'rejected',
+    decision: 'approved' | 'rejected' | 'held',
     options: { resolution?: string; source?: PmxAxSource } = {},
   ): PmxAxApprovalGate | null {
     return this.ax.resolveApproval(id, decision, options);
   }
 
+  /** Reopen a resolved (typically auto-held) gate with a fresh TTL. */
+  reopenApproval(id: string, options: { ttlMs?: number; source?: PmxAxSource } = {}): PmxAxApprovalGate | null {
+    return this.ax.reopenApproval(id, options);
+  }
+
   // ── Review annotations (canvas-bound) ─────────────────────────────
   getReviewAnnotations(): PmxAxReviewAnnotation[] {
     return this.ax.getReviewAnnotations();
@@ -1933,7 +1987,11 @@ class CanvasStateManager {
 
   /** Merge a declarative tool/prompt policy patch (canvas-bound, snapshotted). */
   setPolicy(
-    patch: { tools?: Partial<PmxAxPolicy['tools']>; prompt?: Partial<PmxAxPolicy['prompt']> },
+    patch: {
+      tools?: Partial<PmxAxPolicy['tools']>;
+      prompt?: Partial<PmxAxPolicy['prompt']>;
+      scope?: { nodeIds: string[]; padding?: number } | null;
+    },
     options: { source?: PmxAxSource } = {},
   ): PmxAxPolicy {
     return this.ax.setPolicy(patch, options);
@@ -1978,8 +2036,8 @@ class CanvasStateManager {
     return this.ax.recordSteeringMessage(message, options);
   }
 
-  markSteeringDelivered(id: string): boolean {
-    return this.ax.markSteeringDelivered(id);
+  markSteeringDelivered(id: string, consumer?: string | null): boolean {
+    return this.ax.markSteeringDelivered(id, consumer);
   }
 
   ingestActivity(
@@ -2140,19 +2198,34 @@ class CanvasStateManager {
     return true;
   }
 
-  /** Remove all children from a group, clearing their parentGroup. */
+  /**
+   * Ungroup = dissolve: the children become independent nodes (members of the
+   * enclosing group when nested) and the frame is removed, in one undo step.
+   * Delegates to `removeNode` so the human's Ungroup and the agent's
+   * `group.remove` are the same operation. False when `groupId` is not a group.
+   */
   ungroupNodes(groupId: string): boolean {
     const group = this.nodes.get(groupId);
     if (!group || group.type !== 'group') return false;
+    this.removeNode(groupId);
+    return true;
+  }
+
+  /**
+   * Internal membership step: release every child but keep the frame (the
+   * first half of "set this group's children to …"). Not an ungroup — a
+   * human or agent ungroup dissolves the frame (`ungroupNodes`).
+   */
+  releaseGroupChildren(groupId: string): boolean {
+    const group = this.nodes.get(groupId);
+    if (!group || group.type !== 'group') return false;
 
     const childIds = (group.data.children as string[]) ?? [];
     if (childIds.length === 0) return false;
 
     const snapshot = childIds.slice();
 
-    // Clear children from group
     this.nodes.set(groupId, { ...group, data: { ...group.data, children: [] } });
-    // Clear parentGroup from each child
     for (const id of childIds) {
       const child = this.nodes.get(id);
       if (!child) continue;
@@ -2164,9 +2237,9 @@ class CanvasStateManager {
     this.scheduleSave();
     this.notifyChange('nodes');
     this.recordMutation({
-      operationType: 'ungroupNodes',
-      description: `Ungrouped ${childIds.length} nodes from "${(group.data.title as string) ?? groupId}"`,
-      forward: this.suppressed(() => this.ungroupNodes(groupId)),
+      operationType: 'releaseGroupChildren',
+      description: `Released ${childIds.length} nodes from "${(group.data.title as string) ?? groupId}"`,
+      forward: this.suppressed(() => this.releaseGroupChildren(groupId)),
       inverse: this.suppressed(() => this.groupNodes(groupId, snapshot)),
     });
     return true;

package/src/server/canvas-validation.ts

@@ -31,26 +31,12 @@ 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: {
@@ -60,7 +46,6 @@ export interface CanvasValidationResult {
     containments: number;
     containmentViolations: number;
     missingEdgeEndpoints: number;
-    hiddenEdgeEndpoints: number;
     sizeWarnings: number;
   };
 }
@@ -74,10 +59,6 @@ function overlaps(a: CanvasNodeState, b: CanvasNodeState): boolean {
   );
 }
 
-function participatesInCanvasCollisionValidation(node: CanvasNodeState): boolean {
-  return node.dockPosition === null;
-}
-
 function fullyContains(group: CanvasNodeState, child: CanvasNodeState): boolean {
   return (
     child.position.x >= group.position.x &&
@@ -119,10 +100,8 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
 
   for (let i = 0; i < layout.nodes.length; i++) {
     const a = layout.nodes[i]!;
-    if (!participatesInCanvasCollisionValidation(a)) continue;
     for (let j = i + 1; j < layout.nodes.length; j++) {
       const b = layout.nodes[j]!;
-      if (!participatesInCanvasCollisionValidation(b)) continue;
       if (!overlaps(a, b)) continue;
 
       if (isGroupChildPair(a, b)) {
@@ -143,35 +122,13 @@ 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.
+  // agent's validate pass sees the problem. Collapsed nodes render as bars,
+  // and strictSize is the deliberate opt-out — both skipped.
   const sizeWarnings: CanvasSizeWarning[] = layout.nodes
-    .filter((node) => !node.collapsed && node.dockPosition == null && node.data?.strictSize !== true)
+    .filter((node) => !node.collapsed && node.data?.strictSize !== true)
     .flatMap((node) => {
       const min = nodeMinSize(node.type);
       if (!min || (node.size.width >= min.width && node.size.height >= min.height)) return [];
@@ -189,17 +146,11 @@ 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,
@@ -208,7 +159,6 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
       containments: containments.length,
       containmentViolations: containmentViolations.length,
       missingEdgeEndpoints: missingEdgeEndpoints.length,
-      hiddenEdgeEndpoints: hiddenEdgeEndpoints.length,
       sizeWarnings: sizeWarnings.length,
     },
   };