pmx-canvas 0.4.7 → 0.5.0

package/src/client/state/canvas-store.ts

@@ -9,7 +9,8 @@ import {
   type ViewportState,
 } from '../types';
 import { computeAutoArrange } from '../../shared/auto-arrange';
-import { pushCanvasUpdate, updateViewportFromClient } from './intent-bridge';
+import { canvasAreaCenter } from '../canvas/canvas-area';
+import { pushCanvasUpdate, requestBestEffort, requestOk, updateViewportFromClient } from './intent-bridge';
 
 function logCanvasStoreError(action: string, error: unknown): void {
   console.error(`[canvas-store] ${action} failed`, error);
@@ -21,12 +22,21 @@ export const nodes = signal<Map<string, CanvasNodeState>>(new Map());
 export const edges = signal<Map<string, CanvasEdge>>(new Map());
 export const annotations = signal<Map<string, CanvasAnnotation>>(new Map());
 export const activeNodeId = signal<string | null>(null);
+/** Click-selected edge — Delete removes it, Escape/background click clears it. */
+export const selectedEdgeId = signal<string | null>(null);
 export const connectionStatus = signal<ConnectionStatus>('connecting');
 // Bumped on every processed `connected` frame (SSE reconnects and poll snapshot
 // resets alike). Consumers holding server-minted URLs revalidate on change —
 // a server restart invalidates in-memory resources like frame documents
 // (Finding S) while the browser keeps the stale URLs alive.
 export const workbenchConnectionEpoch = signal<number>(0);
+/**
+ * Degraded-connection detail (rail-chrome-v2 phase 7, design item 14):
+ * the reconnect attempt and the delay before the next try while the stream is
+ * down. Both reset to 0 when a transport is back.
+ */
+export const reconnectAttempt = signal<number>(0);
+export const reconnectDelay = signal<number>(0);
 export const sessionId = signal<string>('');
 export const traceEnabled = signal<boolean>(false);
 export const canvasTheme = signal<string>('dark');
@@ -56,6 +66,10 @@ export const draggingEdge = signal<{
   fromY: number;
   cursorX: number;
   cursorY: number;
+  /** Node under the cursor that would receive the edge on release (item 15). */
+  targetId?: string | null;
+  /** L was pressed during the drag: ask for a label on release. */
+  withLabel?: boolean;
 } | null>(null);
 
 // ── Spatial search highlight (command palette live results) ──
@@ -67,6 +81,18 @@ export const selectedNodeIds = signal<Set<string>>(new Set());
 // ── Context pins (persistent context for agent queries) ──────
 export const contextPinnedNodeIds = signal<Set<string>>(new Set());
 
+// ── Chrome tool state (rail) ─────────────────────────────────
+// 'select': background drag lassos, clicks select. 'pan': dragging anywhere
+// pans — the world layer goes pointer-inert so nodes cannot swallow the drag.
+/** `connect` (rail-chrome-v2 item 15): drag from anywhere on a node to draw an edge. */
+export type CanvasTool = 'select' | 'pan' | 'connect';
+export const canvasTool = signal<CanvasTool>('select');
+/** Held-Space temporary pan — same semantics as the pan tool while held. */
+export const spacePanHeld = signal<boolean>(false);
+export function isPanModeActive(): boolean {
+  return canvasTool.value === 'pan' || spacePanHeld.value;
+}
+
 export function getNeighborNodeIds(nodeId: string | null, edgeMap: Map<string, CanvasEdge>): Set<string> {
   if (!nodeId) return new Set();
 
@@ -111,10 +137,228 @@ export function selectNodes(ids: string[]): void {
 }
 
 export function clearSelection(): void {
+  // Edge selection rides along: a background click (or any other selection
+  // reset) deselects the edge exactly like it deselects nodes.
+  selectedEdgeId.value = null;
   if (selectedNodeIds.value.size === 0) return;
   selectedNodeIds.value = new Set();
 }
 
+// ── Groups v2 (rail-chrome-v2 phase 7, item 20) ──────────────────────
+
+/**
+ * Membership feedback while a node is being dragged: the group it would join
+ * on release (`add`), or the parent it would leave (`remove`). Membership
+ * changes ONLY on release while this is set — never silently by geometry.
+ * Esc during the drag clears it and keeps it cleared for that drag.
+ */
+export const dragDropTarget = signal<{ nodeId: string; groupId: string; mode: 'add' | 'remove' } | null>(null);
+let dropSuppressedForDrag = false;
+
+export function suppressDropForDrag(): void {
+  dropSuppressedForDrag = true;
+  dragDropTarget.value = null;
+}
+
+export function endDropTracking(): void {
+  dropSuppressedForDrag = false;
+  dragDropTarget.value = null;
+}
+
+function rectOf(node: CanvasNodeState): { x: number; y: number; w: number; h: number } {
+  return { x: node.position.x, y: node.position.y, w: node.size.width, h: node.size.height };
+}
+
+function contains(outer: CanvasNodeState, x: number, y: number): boolean {
+  const r = rectOf(outer);
+  return x >= r.x && x <= r.x + r.w && y >= r.y && y <= r.y + r.h;
+}
+
+function fullyOutside(inner: CanvasNodeState, outer: CanvasNodeState): boolean {
+  const a = rectOf(inner);
+  const b = rectOf(outer);
+  return a.x + a.w < b.x || a.x > b.x + b.w || a.y + a.h < b.y || a.y > b.y + b.h;
+}
+
+/**
+ * Called on every drag move of `nodeId`: updates the drop target and grows a
+ * fit-mode parent frame live so a child dragged against it never clips
+ * (the server re-fits on persist; shrinking happens there).
+ */
+export function trackDragMembership(nodeId: string): void {
+  const node = nodes.value.get(nodeId);
+  if (!node || node.type === 'group') return;
+  const parentId = typeof node.data.parentGroup === 'string' ? node.data.parentGroup : null;
+  const parent = parentId ? nodes.value.get(parentId) : undefined;
+  const cx = node.position.x + node.size.width / 2;
+  const cy = node.position.y + node.size.height / 2;
+  let candidate: CanvasNodeState | null = null;
+  for (const other of nodes.value.values()) {
+    if (other.type !== 'group' || other.id === parentId || other.collapsed) continue;
+    if (contains(other, cx, cy)) candidate = other;
+  }
+  if (!dropSuppressedForDrag) {
+    const next = candidate
+      ? { nodeId, groupId: candidate.id, mode: 'add' as const }
+      : parent && fullyOutside(node, parent)
+        ? { nodeId, groupId: parent.id, mode: 'remove' as const }
+        : null;
+    const current = dragDropTarget.value;
+    if ((current?.groupId ?? null) !== (next?.groupId ?? null) || current?.mode !== next?.mode) {
+      dragDropTarget.value = next;
+    }
+  }
+  if (parent && parent.data.frameMode !== 'manual' && !fullyOutside(node, parent)) {
+    const pad = 22;
+    const left = Math.min(parent.position.x, node.position.x - pad);
+    const top = Math.min(parent.position.y, node.position.y - pad - 32);
+    const right = Math.max(parent.position.x + parent.size.width, node.position.x + node.size.width + pad);
+    const bottom = Math.max(parent.position.y + parent.size.height, node.position.y + node.size.height + pad);
+    if (
+      left !== parent.position.x ||
+      top !== parent.position.y ||
+      right !== parent.position.x + parent.size.width ||
+      bottom !== parent.position.y + parent.size.height
+    ) {
+      updateNodeWithOptions(
+        parent.id,
+        { position: { x: left, y: top }, size: { width: right - left, height: bottom - top } },
+        { skipGroupChildTranslation: true },
+      );
+    }
+  }
+}
+
+/** Children of collapsed groups are hidden; edges to them point at the chip. */
+export const hiddenByCollapsedGroup = computed(() => {
+  const hidden = new Map<string, string>();
+  for (const node of nodes.value.values()) {
+    if (node.type !== 'group' || !node.collapsed) continue;
+    const children = Array.isArray(node.data.children) ? node.data.children : [];
+    for (const childId of children) {
+      if (typeof childId === 'string') hidden.set(childId, node.id);
+    }
+  }
+  return hidden;
+});
+
+/** The node that stands in for `id` on the canvas: itself, or its collapsed group's chip. */
+export function visibleNodeFor(id: string): CanvasNodeState | undefined {
+  const chipId = hiddenByCollapsedGroup.value.get(id);
+  return nodes.value.get(chipId ?? id);
+}
+
+/** Collapsed groups render as a chip; children keep their positions for restore. */
+export function groupsOfSelection(): string[] {
+  const ids = new Set<string>();
+  for (const id of selectedNodeIds.value) {
+    const node = nodes.value.get(id);
+    if (!node) continue;
+    if (node.type === 'group') ids.add(node.id);
+    else if (typeof node.data.parentGroup === 'string') ids.add(node.data.parentGroup);
+  }
+  return [...ids];
+}
+
+// ── Selection bar geometry actions (rail-chrome-v2 phase 7, item 13) ──
+// Each works on the current selection in world space and persists through the
+// same path a drag does (store update + persistLayout → /api/canvas/update).
+
+export function alignSelection(edge: 'left' | 'top'): void {
+  const selected = getSelectedNodes();
+  if (selected.length < 2) return;
+  const target = Math.min(...selected.map((n) => (edge === 'left' ? n.position.x : n.position.y)));
+  // Sharing an edge collapses nodes that used to sit side by side ONTO each
+  // other. Aligning must never destroy the layout: when the shared edge makes
+  // any pair overlap, flow the selection along the other axis in its current
+  // order instead — align-left of a row reads as "stack into a left-aligned
+  // column", which is what the gesture means.
+  const GAP = 24;
+  const positions = new Map<string, { x: number; y: number }>();
+  for (const node of selected) {
+    positions.set(node.id, edge === 'left' ? { x: target, y: node.position.y } : { x: node.position.x, y: target });
+  }
+  const overlaps = (
+    a: { x: number; y: number; w: number; h: number },
+    b: { x: number; y: number; w: number; h: number },
+  ) => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+  const framed = selected.map((node) => {
+    const at = positions.get(node.id)!;
+    return { node, x: at.x, y: at.y, w: node.size.width, h: node.size.height };
+  });
+  const collides = framed.some((a, i) => framed.some((b, j) => j > i && overlaps(a, b)));
+  if (collides) {
+    const ordered = [...selected].sort((a, b) =>
+      edge === 'left' ? a.position.y - b.position.y : a.position.x - b.position.x,
+    );
+    let cursor =
+      edge === 'left' ? Math.min(...selected.map((n) => n.position.y)) : Math.min(...selected.map((n) => n.position.x));
+    for (const node of ordered) {
+      positions.set(node.id, edge === 'left' ? { x: target, y: cursor } : { x: cursor, y: target });
+      cursor += (edge === 'left' ? node.size.height : node.size.width) + GAP;
+    }
+  }
+  batch(() => {
+    for (const node of selected) {
+      updateNode(node.id, { position: positions.get(node.id)! });
+    }
+  });
+  persistLayout();
+}
+
+/** Even horizontal gaps between the selected nodes, first and last staying put. */
+export function distributeSelection(): void {
+  const selected = getSelectedNodes().sort((a, b) => a.position.x - b.position.x);
+  if (selected.length < 3) return;
+  const first = selected[0]!;
+  const last = selected[selected.length - 1]!;
+  const span = last.position.x - (first.position.x + first.size.width);
+  const inner = selected.slice(1, -1);
+  const innerWidth = inner.reduce((sum, n) => sum + n.size.width, 0);
+  const gap = (span - innerWidth) / (inner.length + 1);
+  batch(() => {
+    if (gap < 8) {
+      // The selection doesn't fit between first and last (a column, or an
+      // already-tight row): keeping the ends pinned would SQUEEZE the middle
+      // into overlap. Flow everything after the first into a row instead.
+      let cursor = first.position.x + first.size.width + 24;
+      for (const node of selected.slice(1)) {
+        updateNode(node.id, { position: { x: cursor, y: node.position.y } });
+        cursor += node.size.width + 24;
+      }
+      return;
+    }
+    let cursor = first.position.x + first.size.width + gap;
+    for (const node of inner) {
+      updateNode(node.id, { position: { x: cursor, y: node.position.y } });
+      cursor += node.size.width + gap;
+    }
+  });
+  persistLayout();
+}
+
+/** Grid the selection in reading order from its own top-left corner. */
+export function arrangeSelection(gap = 24): void {
+  const selected = getSelectedNodes().sort((a, b) => a.position.y - b.position.y || a.position.x - b.position.x);
+  if (selected.length < 2) return;
+  const originX = Math.min(...selected.map((n) => n.position.x));
+  const originY = Math.min(...selected.map((n) => n.position.y));
+  const cols = Math.ceil(Math.sqrt(selected.length));
+  const colWidth = Math.max(...selected.map((n) => n.size.width));
+  const rowHeight = Math.max(...selected.map((n) => n.size.height));
+  batch(() => {
+    selected.forEach((node, index) => {
+      updateNode(node.id, {
+        position: {
+          x: originX + (index % cols) * (colWidth + gap),
+          y: originY + Math.floor(index / cols) * (rowHeight + gap),
+        },
+      });
+    });
+  });
+  persistLayout();
+}
+
 export function getSelectedNodes(): CanvasNodeState[] {
   const sel = selectedNodeIds.value;
   if (sel.size === 0) return [];
@@ -155,21 +399,13 @@ export function replaceContextPinsFromServer(ids: string[]): void {
   contextPinnedNodeIds.value = new Set(ids);
 }
 
-export function getContextPinnedNodes(): CanvasNodeState[] {
-  const pins = contextPinnedNodeIds.value;
-  if (pins.size === 0) return [];
-  return Array.from(pins)
-    .map((id) => nodes.value.get(id))
-    .filter((n): n is CanvasNodeState => n !== undefined);
-}
-
 function syncContextPinsToServer(ids: Set<string>): void {
-  fetch('/api/canvas/context-pins', {
+  // Through the bridge so the write carries the workbench marker — a bare
+  // fetch makes the human's pin look like an anonymous `api` agent.
+  void requestBestEffort('syncContextPinsToServer', '/api/canvas/context-pins', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ nodeIds: Array.from(ids) }),
-  }).catch((error) => {
-    logCanvasStoreError('syncContextPinsToServer', error);
   });
 }
 
@@ -301,30 +537,19 @@ export async function createAnnotationFromClient(input: {
   text?: string;
   label?: string;
 }): Promise<{ ok: boolean }> {
-  try {
-    const res = await fetch('/api/canvas/annotation', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(input),
-    });
-    return { ok: res.ok };
-  } catch (error) {
-    logCanvasStoreError('createAnnotationFromClient', error);
-    return { ok: false };
-  }
+  return requestOk('createAnnotationFromClient', '/api/canvas/annotation', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(input),
+  });
 }
 
 export async function removeAnnotationFromClient(id: string): Promise<{ ok: boolean }> {
-  try {
-    const res = await fetch(`/api/canvas/annotation/${encodeURIComponent(id)}`, {
-      method: 'DELETE',
-    });
-    if (res.ok) removeAnnotation(id);
-    return { ok: res.ok };
-  } catch (error) {
-    logCanvasStoreError('removeAnnotationFromClient', error);
-    return { ok: false };
-  }
+  const result = await requestOk('removeAnnotationFromClient', `/api/canvas/annotation/${encodeURIComponent(id)}`, {
+    method: 'DELETE',
+  });
+  if (result.ok) removeAnnotation(id);
+  return result;
 }
 
 export function resizeNode(id: string, size: { width: number; height: number }): void {
@@ -336,7 +561,15 @@ export function resizeNode(id: string, size: { width: number; height: number }):
 export function bringToFront(id: string): void {
   const existing = nodes.value.get(id);
   if (!existing) return;
-  updateNode(id, { zIndex: maxZ++ });
+  batch(() => {
+    updateNode(id, { zIndex: maxZ++ });
+    // A group is a frame: it must never stack above its own children.
+    if (existing.type === 'group' && Array.isArray(existing.data.children)) {
+      for (const childId of existing.data.children) {
+        if (typeof childId === 'string' && nodes.value.has(childId)) updateNode(childId, { zIndex: maxZ++ });
+      }
+    }
+  });
   activeNodeId.value = id;
 }
 
@@ -344,48 +577,8 @@ export function toggleCollapsed(id: string): void {
   const existing = nodes.value.get(id);
   if (!existing) return;
   updateNode(id, { collapsed: !existing.collapsed });
-}
-
-// Collapse every docked context node. Used to enforce mutual exclusion between
-// the Context side panel and the Updates side panel (they share the same
-// right-edge anchor and would otherwise visually collide).
-export function collapseDockedContextNodes(): void {
-  for (const node of nodes.value.values()) {
-    if (node.type === 'context' && node.dockPosition === 'right' && !node.collapsed) {
-      updateNode(node.id, { collapsed: true });
-    }
-  }
-}
-
-// True iff at least one docked context node is currently expanded. Used by the
-// Updates pill to hide itself while the Context panel is open.
-export const hasOpenDockedContextPanel = computed(() => {
-  for (const node of nodes.value.values()) {
-    if (node.type === 'context' && node.dockPosition === 'right' && !node.collapsed) {
-      return true;
-    }
-  }
-  return false;
-});
-
-export function dockNode(id: string, position: 'left' | 'right'): void {
-  const existing = nodes.value.get(id);
-  if (!existing) return;
-  updateNode(id, { dockPosition: position });
-  persistLayout();
-}
-
-export function undockNode(id: string): void {
-  const existing = nodes.value.get(id);
-  if (!existing) return;
-  // Place at center of current viewport in world-space
-  const v = viewport.value;
-  const cx = (window.innerWidth / 2 - v.x) / v.scale;
-  const cy = (window.innerHeight / 2 - v.y) / v.scale;
-  updateNode(id, {
-    dockPosition: null,
-    position: { x: cx - existing.size.width / 2, y: cy - existing.size.height / 2 },
-  });
+  // Collapse is board state (a collapsed group hides its children for every
+  // viewer and survives reload), not a per-tab preference.
   persistLayout();
 }
 
@@ -480,8 +673,7 @@ export function zoomByFactor(factor: number, duration = 150): void {
   const scale = Math.min(4, Math.max(0.1, v.scale * factor));
   if (scale === v.scale) return;
   const ratio = scale / v.scale;
-  const cx = window.innerWidth / 2;
-  const cy = window.innerHeight / 2;
+  const { x: cx, y: cy } = canvasAreaCenter();
   animateViewport({ x: cx - ratio * (cx - v.x), y: cy - ratio * (cy - v.y), scale }, duration);
 }
 
@@ -536,7 +728,6 @@ export function persistLayout(options: { recordHistory?: boolean } = {}): void {
       position: n.position,
       size: n.size,
       collapsed: n.collapsed,
-      dockPosition: n.dockPosition,
     }));
     const layout = {
       viewport: viewport.value,
@@ -547,7 +738,6 @@ export function persistLayout(options: { recordHistory?: boolean } = {}): void {
         size: n.size,
         collapsed: n.collapsed,
         pinned: n.pinned,
-        dockPosition: n.dockPosition,
       })),
       edges: Array.from(edges.value.values()).map((e) => ({
         id: e.id,
@@ -579,7 +769,6 @@ export function restoreLayout(): Map<string, Partial<CanvasNodeState>> | null {
         size?: CanvasNodeState['size'];
         collapsed?: boolean;
         pinned?: boolean;
-        dockPosition?: CanvasNodeState['dockPosition'];
       }>;
     };
     const savedNodes = Array.isArray(layout.nodes) ? layout.nodes : [];
@@ -593,7 +782,6 @@ export function restoreLayout(): Map<string, Partial<CanvasNodeState>> | null {
         ...(node.size ? { size: node.size } : {}),
         ...(node.collapsed !== undefined ? { collapsed: node.collapsed } : {}),
         ...(node.pinned !== undefined ? { pinned: node.pinned } : {}),
-        ...(node.dockPosition !== undefined ? { dockPosition: node.dockPosition } : {}),
       });
     }
 
@@ -641,10 +829,11 @@ export function focusNode(id: string, options: { recordHistory?: boolean } = {})
   const v = viewport.value;
   const cx = node.position.x + node.size.width / 2;
   const cy = node.position.y + node.size.height / 2;
+  const centre = canvasAreaCenter();
   animateViewport(
     {
-      x: window.innerWidth / 2 - cx * v.scale,
-      y: window.innerHeight / 2 - cy * v.scale,
+      x: centre.x - cx * v.scale,
+      y: centre.y - cy * v.scale,
       scale: v.scale,
     },
     300,

package/src/client/state/human-store.ts

@@ -0,0 +1,175 @@
+import { computed, signal } from '@preact/signals';
+import {
+  HUMAN_CURSOR_THROTTLE_MS,
+  type HumanPresence,
+  type HumanPresenceSnapshot,
+} from '../../shared/human-presence.js';
+import { requestBestEffort, vetoGhostIntent } from './intent-bridge';
+import { intents, removeIntent } from './intent-store';
+
+/**
+ * Human collaborator presence (rail-chrome-v2 phase 8). This tab reports its
+ * cursor (throttled) and the node it is holding; the server fans every tab
+ * out over `human-presence` SSE frames. `otherHumans` is what the presence
+ * layer draws — never this tab's own cursor.
+ */
+
+function sessionScoped(key: string, make: () => string): string {
+  try {
+    const existing = window.sessionStorage.getItem(key);
+    if (existing) return existing;
+    const value = make();
+    window.sessionStorage.setItem(key, value);
+    return value;
+  } catch {
+    return make();
+  }
+}
+
+export const humanClientId = sessionScoped(
+  'pmx-canvas-human-client',
+  () => `tab-${Math.random().toString(36).slice(2, 8)}`,
+);
+
+function resolveName(): string {
+  try {
+    const fromQuery = new URLSearchParams(window.location.search).get('name')?.trim();
+    if (fromQuery) {
+      window.localStorage.setItem('pmx-canvas-human-name', fromQuery);
+      return fromQuery;
+    }
+    const stored = window.localStorage.getItem('pmx-canvas-human-name')?.trim();
+    if (stored) return stored;
+  } catch {
+    // storage unavailable: fall through to a generated name
+  }
+  return `guest-${humanClientId.slice(-4)}`;
+}
+
+export const humanName = signal<string>(resolveName());
+export const humans = signal<HumanPresence[]>([]);
+export const otherHumans = computed(() => humans.value.filter((human) => human.clientId !== humanClientId));
+
+/** Nodes a human took over mid-edit → that human's name, shown as the yield pill for a moment. */
+export const yieldedNodes = signal<Map<string, string>>(new Map());
+
+export function applyHumanSnapshot(snapshot: Partial<HumanPresenceSnapshot> | null | undefined): void {
+  if (!snapshot || !Array.isArray(snapshot.humans)) return;
+  humans.value = snapshot.humans;
+}
+
+let grabbing: string | null = null;
+let lastCursor: { x: number; y: number } | null = null;
+let lastSentAt = 0;
+let pending: ReturnType<typeof setTimeout> | null = null;
+
+function post(body: Record<string, unknown>): void {
+  void requestBestEffort('humanPresence', '/api/canvas/human-presence', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ clientId: humanClientId, name: humanName.value, ...body }),
+  });
+}
+
+function flushCursor(): void {
+  pending = null;
+  lastSentAt = Date.now();
+  post({ cursor: lastCursor, grabbingNodeId: grabbing });
+}
+
+/** Report the pointer in world coordinates (throttled); null when it leaves the canvas. */
+export function reportHumanCursor(cursor: { x: number; y: number } | null): void {
+  lastCursor = cursor;
+  const elapsed = Date.now() - lastSentAt;
+  if (elapsed >= HUMAN_CURSOR_THROTTLE_MS) {
+    if (pending) clearTimeout(pending);
+    flushCursor();
+  } else if (!pending) {
+    pending = setTimeout(flushCursor, HUMAN_CURSOR_THROTTLE_MS - elapsed);
+  }
+}
+
+/** Hold / release a node (drag, rename): the edit lock agents must respect. */
+export function reportHumanGrab(nodeId: string | null): void {
+  grabbing = nodeId;
+  post({ cursor: lastCursor, grabbingNodeId: nodeId });
+}
+
+export function markYielded(nodeId: string, name: string): void {
+  const next = new Map(yieldedNodes.value);
+  next.set(nodeId, name);
+  yieldedNodes.value = next;
+  setTimeout(() => {
+    const later = new Map(yieldedNodes.value);
+    if (later.get(nodeId) === name) {
+      later.delete(nodeId);
+      yieldedNodes.value = later;
+    }
+  }, 6000);
+}
+
+/**
+ * User wins (item 6): the human grabbed a node the agent is mid-edit on. Every
+ * explicit intent targeting it is vetoed through the normal veto path (the
+ * agent hears it as steering), a Yield entry lands in the timeline, and the
+ * node wears a "took over — agent yielded" pill for a moment.
+ */
+export function takeOverNode(nodeId: string, title: string): void {
+  const pendingOnNode = [...intents.value.values()].filter(
+    (intent) => intent.nodeId === nodeId && !intent.auto && intent.phase === 'forming',
+  );
+  if (pendingOnNode.length === 0) return;
+  const name = humanName.value;
+  markYielded(nodeId, name);
+  for (const intent of pendingOnNode) {
+    void vetoGhostIntent({
+      id: intent.id,
+      kind: intent.kind,
+      label: intent.label,
+      reason: `${name} took over “${title}” mid-edit — yield and requeue the change once it is released`,
+    }).then((ok) => {
+      if (ok) removeIntent(intent.id);
+    });
+  }
+  void requestBestEffort('yieldEvent', '/api/canvas/ax/event', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      kind: 'yield',
+      summary: `${name} grabbed “${title}” mid-edit — agent yielded, change requeued`,
+      nodeIds: [nodeId],
+      source: 'browser',
+    }),
+  });
+}
+
+let heartbeat: ReturnType<typeof setInterval> | null = null;
+
+/** Announce this tab and keep it alive; renews a held grab. Call once per connection. */
+export function startHumanPresence(): () => void {
+  post({ cursor: lastCursor, grabbingNodeId: grabbing });
+  heartbeat = setInterval(() => post({ grabbingNodeId: grabbing }), 3000);
+  const leave = () => {
+    try {
+      navigator.sendBeacon?.(
+        '/api/canvas/human-presence',
+        new Blob([JSON.stringify({ clientId: humanClientId, left: true })], { type: 'application/json' }),
+      );
+    } catch {
+      // best effort
+    }
+  };
+  window.addEventListener('pagehide', leave);
+  return () => {
+    if (heartbeat) clearInterval(heartbeat);
+    heartbeat = null;
+    window.removeEventListener('pagehide', leave);
+  };
+}
+
+export function resetHumanPresence(): void {
+  humans.value = [];
+  yieldedNodes.value = new Map();
+  grabbing = null;
+  lastCursor = null;
+}