pmx-canvas 0.10.0 → 0.12.0

package/src/client/state/presentation.ts

@@ -1,14 +1,23 @@
 import { signal } from '@preact/signals';
-import { interpolateCamera, resolveStop, type TourStop } from '../../shared/tour.js';
+import {
+  interpolateCamera,
+  resolveStop,
+  tourStopSchema,
+  type TourPresenter,
+  type TourStop,
+} from '../../shared/tour.js';
 import { canvasArea } from '../canvas/canvas-area';
 import type { ViewportState } from '../types';
-import { animateCameraPath, nodes, viewport } from './canvas-store';
+import { boardGeneration, catalogEpoch } from './boards-store';
+import { animateCameraPath, cancelViewportAnimation, nodes, viewport } from './canvas-store';
 import { requestBestEffort, requestJson } from './intent-bridge';
 
 export const presenting = signal(false);
 export const recordingCamera = signal(false);
 /** Why the current stop cannot be shown (missing target, no stops, server unreachable). */
 export const presentationError = signal('');
+/** Read-only mirror of the server's shared cursor, never advanced optimistically. */
+export const presentationCursor = signal<{ index: number; total: number } | null>(null);
 
 export function ownsCamera(): boolean {
   return presenting.value || recordingCamera.value;
@@ -24,7 +33,21 @@ function prefersReducedMotion(): boolean {
  */
 export function playStop(stop: TourStop, onDone?: (end: ViewportState) => void): void {
   const area = canvasArea();
-  const target = resolveStop(stop, [...nodes.value.values()], area.width, area.height);
+  let target: ViewportState;
+  if (presenting.value && !recordingCamera.value && !('viewport' in stop.target)) {
+    const padding = stop.padding ?? 40;
+    const controls = document.querySelector('.presentation-controls')?.getBoundingClientRect();
+    const top = Math.max(padding, controls ? controls.bottom - area.top + 12 : 0);
+    target = resolveStop(
+      { ...stop, padding: 0 },
+      [...nodes.value.values()],
+      area.width - 2 * padding,
+      area.height - top - padding,
+    );
+    target = { ...target, x: target.x + padding, y: target.y + top };
+  } else {
+    target = resolveStop(stop, [...nodes.value.values()], area.width, area.height);
+  }
   const from = { ...viewport.value };
   const duration = prefersReducedMotion() ? 0 : (stop.duration ?? 1) * 1000;
   animateCameraPath(
@@ -35,6 +58,7 @@ export function playStop(stop: TourStop, onDone?: (end: ViewportState) => void):
 }
 
 let stepSeq = 0;
+let presentationRun = 0;
 
 /**
  * Show a tour stop, entering presentation if needed. Entering hides the
@@ -58,41 +82,137 @@ export function presentStop(stop: TourStop): void {
   else play();
 }
 
-/**
- * Move the server's shared tour cursor. The `canvas-tour-step` echo does the
- * animating, here and in every other presenting viewer, so a human's keys and
- * an agent's `tour.go` always agree on where the tour is.
- */
-export async function stepTour(to: { stop: number } | { step: 'next' | 'previous' }): Promise<void> {
-  const result = await requestJson<{ ok: boolean; error?: string }>(
+let requestSeq = 0;
+const presenterId = crypto.randomUUID();
+let lastDelivery: { catalogEpoch: string; sequence: number; applied: boolean } | null = null;
+
+function nextPresenter(): TourPresenter | null {
+  if (catalogEpoch === null || boardGeneration === null) {
+    presentationError.value = 'The board is still connecting. Try presenting again when it is ready.';
+    return null;
+  }
+  return { clientId: presenterId, intent: ++requestSeq, catalogEpoch, boardGeneration };
+}
+
+function isCurrentPresenter(presenter: TourPresenter): boolean {
+  return (
+    presenter.intent === requestSeq &&
+    presenter.catalogEpoch === catalogEpoch &&
+    presenter.boardGeneration === boardGeneration
+  );
+}
+
+function acceptDelivery(data: Record<string, unknown>, apply: boolean): boolean {
+  if (
+    typeof data.catalogEpoch !== 'string' ||
+    data.catalogEpoch !== catalogEpoch ||
+    data.boardGeneration !== boardGeneration ||
+    typeof data.sequence !== 'number' ||
+    (lastDelivery?.catalogEpoch === catalogEpoch &&
+      (data.sequence < lastDelivery.sequence ||
+        (data.sequence === lastDelivery.sequence && (!apply || lastDelivery.applied))))
+  )
+    return false;
+  lastDelivery = { catalogEpoch: data.catalogEpoch, sequence: data.sequence, applied: apply };
+  return true;
+}
+
+/** Apply either delivery of the server's shared cursor, without replaying its echo. */
+export function applyTourStep(data: Record<string, unknown>): void {
+  if (recordingCamera.value) return;
+  const stop = tourStopSchema.safeParse(data.stop);
+  const display = presenting.value || data.present === true;
+  // Observe hidden steps too. The same operation's HTTP acknowledgement may
+  // authorize local presentation later, but an older acknowledgement must not.
+  if (!stop.success || !acceptDelivery(data, display) || !display) return;
+  if (typeof data.index === 'number' && typeof data.total === 'number') {
+    presentationCursor.value = { index: data.index, total: data.total };
+  }
+  presentStop(stop.data);
+}
+
+export function applyTourExit(data: Record<string, unknown>): void {
+  if (!recordingCamera.value && acceptDelivery(data, true)) hidePresentation();
+}
+
+/** Move the shared cursor. A successful response also works while events are delayed or disconnected. */
+export async function stepTour(
+  to: { stop: number } | { step: 'next' | 'previous' },
+  presenter = nextPresenter(),
+): Promise<void> {
+  if (!presenter) return;
+  const run = presentationRun;
+  const previous = lastDelivery;
+  const result = await requestJson<
+    | {
+        ok: true;
+        catalogEpoch: string;
+        boardGeneration: number;
+        sequence: number;
+        index: number;
+        total: number;
+        stop: TourStop;
+      }
+    | { ok: true; superseded: true }
+    | { ok: false; error?: string }
+  >(
     'step tour',
     '/api/canvas/tour/go',
     { ok: false, error: 'Could not reach the canvas server.' },
     {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ ...to, present: false }),
+      body: JSON.stringify({ ...to, present: false, presenter }),
     },
   );
-  if (!result.ok) presentationError.value = result.error ?? 'Could not change the tour stop.';
+  // Only a local cancellation invalidates this intent. Remote steps/exits are
+  // ordered by the server stamp, even if an older exit hid the pending restart.
+  if (run !== presentationRun || !isCurrentPresenter(presenter)) return;
+  if (result.ok) {
+    if ('superseded' in result) {
+      if (previous === lastDelivery)
+        presentationError.value = 'The presentation request was superseded. Exit and present again.';
+    } else applyTourStep({ ...result, present: true });
+  } else if (previous === lastDelivery) presentationError.value = result.error ?? 'Could not change the tour stop.';
 }
 
 /** Present from the first stop, or resume where the tour already is (`?present=1`). */
 export async function startPresentation(resume = false): Promise<void> {
+  const run = ++presentationRun;
   presenting.value = true;
   presentationError.value = '';
+  presentationCursor.value = null;
+  // Reserve the gesture before the read: an older resume cannot overtake Next.
+  const presenter = nextPresenter();
+  if (!presenter) return;
   const at = resume
     ? (await requestJson<{ position?: number | null }>('read tour', '/api/canvas/tour', {})).position
     : null;
-  await stepTour({ stop: typeof at === 'number' ? at : 0 });
+  if (run !== presentationRun || !isCurrentPresenter(presenter)) return;
+  await stepTour({ stop: typeof at === 'number' ? at : 0 }, presenter);
 }
 
-export function endPresentation(): void {
+function hidePresentation(): void {
+  stepSeq++;
+  cancelViewportAnimation();
   presenting.value = false;
   presentationError.value = '';
+  presentationCursor.value = null;
+}
+
+/** Local cancellation also fences pending requests from this presentation. */
+export function dismissPresentation(): void {
+  presentationRun++;
+  hidePresentation();
+}
+
+export function endPresentation(): void {
+  dismissPresentation();
+  const presenter = nextPresenter();
+  if (!presenter) return;
   void requestBestEffort('exit tour', '/api/canvas/tour/exit', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: '{}',
+    body: JSON.stringify({ presenter }),
   });
 }

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

@@ -1,9 +1,123 @@
 import { computed, effect, signal } from '@preact/signals';
 import { relationKind, relationPreset, relationSourceEnd } from '../../shared/relations.js';
+import { memoryKey } from '../../shared/memory-graph.js';
 import { activeBoard, activeBoardId } from './boards-store';
-import { activeNodeId, edges, nodes, selectedNodeIds } from './canvas-store';
+import {
+  activeNodeId,
+  edges,
+  nodes,
+  selectedNodeIds,
+  focusNode,
+  collapseExpandedNode,
+  canvasInteractionEpoch,
+} from './canvas-store';
+import { cardQualification } from './knowledge-store';
+import type { CanvasEdge } from '../types';
 
 export const relationFilter = signal<{ boardId: string; kind: string } | null>(null);
+const inspection = signal<{ boardId: string; nodeId: string; mode: 'lineage' | 'connections'; epoch: number } | null>(
+  null,
+);
+
+export function showRelationsOnCanvas(nodeId: string, mode: 'lineage' | 'connections'): void {
+  const boardId = activeBoardId.value;
+  if (!boardId) return;
+  collapseExpandedNode();
+  selectedNodeIds.value = new Set();
+  relationFilter.value = null;
+  focusNode(nodeId, { recordHistory: false, persistStacking: false });
+  activeNodeId.value = nodeId;
+  inspection.value = { boardId, nodeId, mode, epoch: canvasInteractionEpoch.value };
+}
+
+effect(() => {
+  const value = inspection.value;
+  if (
+    value &&
+    (value.boardId !== activeBoardId.value ||
+      value.nodeId !== activeNodeId.value ||
+      value.epoch !== canvasInteractionEpoch.value ||
+      relationFilter.value)
+  )
+    inspection.value = null;
+});
+
+/** Only qualified dependency/lineage sources warn; citations and illustrated loops never do. */
+export function relationWarning(edge: CanvasEdge): string[] {
+  const boardId = activeBoardId.value;
+  const kind = relationKind(edge);
+  if (!boardId || !['depends-on', 'derived-from'].includes(kind)) return [];
+  const from = { boardId, cardId: edge.from };
+  const to = { boardId: edge.toBoardId ?? boardId, cardId: edge.to };
+  const source = relationSourceEnd(edge) === 'from' ? from : to;
+  const dependent = relationSourceEnd(edge) === 'from' ? to : from;
+  if (dependent.boardId !== boardId) return [];
+  return (
+    cardQualification(dependent.cardId)?.sourceWarnings?.[
+      JSON.stringify([boardId, edge.id, kind, memoryKey(source)])
+    ] ?? []
+  );
+}
+
+export const dependencyAnalysis = computed(() => {
+  const links = [...edges.value.values()].filter((edge) => !edge.toBoardId && relationKind(edge) === 'depends-on');
+  const forward = new Map<string, Set<string>>();
+  const reverse = new Map<string, Set<string>>();
+  for (const edge of links) {
+    if (!forward.has(edge.from)) forward.set(edge.from, new Set());
+    if (!forward.has(edge.to)) forward.set(edge.to, new Set());
+    if (!reverse.has(edge.from)) reverse.set(edge.from, new Set());
+    if (!reverse.has(edge.to)) reverse.set(edge.to, new Set());
+    forward.get(edge.from)!.add(edge.to);
+    reverse.get(edge.to)!.add(edge.from);
+  }
+  // Iterative strongly connected components: one count per cyclic dependency cluster.
+  const visited = new Set<string>();
+  const order: string[] = [];
+  for (const root of forward.keys()) {
+    const stack: Array<[string, boolean]> = [[root, false]];
+    while (stack.length) {
+      const [id, done] = stack.pop()!;
+      if (done) {
+        order.push(id);
+        continue;
+      }
+      if (visited.has(id)) continue;
+      visited.add(id);
+      stack.push([id, true]);
+      for (const next of forward.get(id) ?? []) if (!visited.has(next)) stack.push([next, false]);
+    }
+  }
+  const assigned = new Set<string>();
+  const cyclic = new Map<string, number>();
+  let cycles = 0;
+  for (const root of order.reverse()) {
+    if (assigned.has(root)) continue;
+    const component = new Set<string>([root]);
+    assigned.add(root);
+    for (const id of component)
+      for (const next of reverse.get(id) ?? []) {
+        if (assigned.has(next)) continue;
+        assigned.add(next);
+        component.add(next);
+      }
+    if (component.size > 1 || forward.get(root)?.has(root)) {
+      cycles++;
+      for (const id of component) cyclic.set(id, cycles);
+    }
+  }
+  const cycleEdges = new Set(
+    links
+      .filter((edge) => cyclic.has(edge.from) && cyclic.get(edge.from) === cyclic.get(edge.to))
+      .map((edge) => edge.id),
+  );
+  const roots = new Set(selectedNodeIds.value);
+  if (activeNodeId.value) roots.add(activeNodeId.value);
+  const affected = new Set(roots);
+  for (const id of affected) for (const next of reverse.get(id) ?? []) affected.add(next);
+  for (const id of roots) affected.delete(id);
+  return { cycles, cycleEdges, affected, focused: roots.size > 0, hasDependencies: links.length > 0 };
+});
 
 effect(() => {
   const filter = relationFilter.value;
@@ -40,6 +154,18 @@ export const relationHighlight = computed(() => {
     cards.add(edge.from);
     cards.add(edge.to);
   };
+  const view = inspection.value;
+  if (view && view.boardId === activeBoardId.value && view.nodeId === focus && !kind) {
+    if (view.mode === 'connections') {
+      for (const edge of list) if (edge.from === focus || edge.to === focus) add(edge);
+    } else {
+      for (const id of cards)
+        for (const edge of list)
+          if (['derived-from', 'depends-on'].includes(relationKind(edge)) && (edge.from === id || edge.to === id))
+            add(edge);
+    }
+    return { cards, links };
+  }
   if (!kind) for (const edge of list) if (focusedCards.has(edge.from) && focusedCards.has(edge.to)) add(edge);
   if (kind) {
     for (const edge of list) if (relationKind(edge) === kind) add(edge);

package/src/client/state/sse-bridge.ts

@@ -2,7 +2,7 @@ import { findOpenCanvasPosition } from '../utils/placement.js';
 import { refreshKnowledge } from './knowledge-store';
 import { applyWorkspaceSettings } from './workspace-settings';
 import { cameraSchema, tourStopSchema } from '../../shared/tour.js';
-import { ownsCamera, playStop, presentationError, presenting, presentStop, recordingCamera } from './presentation';
+import { applyTourExit, applyTourStep, ownsCamera, playStop, presenting, recordingCamera } from './presentation';
 import { isHostedWorkbench, workbenchFetch } from './workbench-transport';
 import { normalizeExtAppToolResult } from '../utils/ext-app-tool-result.js';
 import type { CanvasAnnotation, CanvasEdge, CanvasNodeState, NodeActor } from '../types';
@@ -176,7 +176,7 @@ function ensureMarkdownNode(path: string, title: string): void {
     const node = makeNode(id, 'markdown', { path, title, content: '', rendered: '' });
     node.position = placement;
     addNode(node);
-    focusNode(id);
+    focusNode(id, { persistStacking: false });
   }
 }
 
@@ -199,7 +199,7 @@ function ensureMcpAppNode(data: Record<string, unknown>): void {
     updateNodeData(id, data);
   } else {
     addNode(makeNode(id, 'mcp-app', data));
-    focusNode(id);
+    focusNode(id, { persistStacking: false });
   }
 }
 
@@ -260,7 +260,7 @@ function ensureExtAppNode(data: Record<string, unknown>): void {
     ),
   );
   addNode(node);
-  focusNode(id, { recordHistory: false });
+  focusNode(id, { recordHistory: false, persistStacking: false });
 }
 
 function findExtAppNodeId(toolCallId: string): string | null {
@@ -849,7 +849,7 @@ function handleCanvasPromptCreated(data: Record<string, unknown>): void {
         ),
       ),
     );
-    focusNode(nodeId);
+    focusNode(nodeId, { persistStacking: false });
   }
 
   // Add flow edge from parent → prompt if parent exists
@@ -888,7 +888,7 @@ function handleCanvasResponseStart(data: Record<string, unknown>): void {
       threadStatus: 'streaming',
       _activeResponseId: responseNodeId,
     });
-    focusNode(promptNodeId);
+    focusNode(promptNodeId, { persistStacking: false });
     return;
   }
 
@@ -921,7 +921,7 @@ function handleCanvasResponseStart(data: Record<string, unknown>): void {
     });
   }
 
-  focusNode(responseNodeId);
+  focusNode(responseNodeId, { persistStacking: false });
 }
 
 function handleCanvasResponseDelta(data: Record<string, unknown>): void {
@@ -1078,10 +1078,10 @@ function handleCanvasFocusNode(data: Record<string, unknown>): void {
   const nodeId = data.nodeId as string;
   if (nodeId && nodes.value.has(nodeId)) {
     if (data.noPan === true) {
-      bringToFront(nodeId);
+      bringToFront(nodeId, false);
       return;
     }
-    focusNode(nodeId);
+    focusNode(nodeId, { persistStacking: false });
   }
 }
 
@@ -1093,6 +1093,12 @@ function handleCanvasViewportUpdate(data: Record<string, unknown>): void {
   const x = typeof viewport.x === 'number' ? viewport.x : 0;
   const y = typeof viewport.y === 'number' ? viewport.y : 0;
   const scale = typeof viewport.scale === 'number' ? viewport.scale : 1;
+  // The catalog may still be holding the initial layout. Its older camera
+  // must not overwrite this later event when the board identity arrives.
+  const pendingLayout = pendingBoardLayout?.layout as Record<string, unknown> | undefined;
+  if (pendingLayout) {
+    pendingBoardLayout = { ...pendingBoardLayout, layout: { ...pendingLayout, viewport: { x, y, scale } } };
+  }
   cancelViewportAnimation();
   replaceViewport({ x, y, scale });
 }
@@ -1100,18 +1106,11 @@ function handleCanvasViewportUpdate(data: Record<string, unknown>): void {
 // Tour steps and camera moves animate locally; a deterministic capture owns
 // its camera outright and ignores both.
 function handleCanvasTourStep(data: Record<string, unknown>): void {
-  if (recordingCamera.value) return;
-  // A human stepping in one tab moves tabs already presenting; only a
-  // `present` step (the agent's default) starts presenting elsewhere.
-  if (!presenting.value && data.present !== true) return;
-  const stop = tourStopSchema.safeParse(data.stop);
-  if (stop.success) presentStop(stop.data);
+  applyTourStep(data);
 }
 
-function handleCanvasTourExit(): void {
-  if (recordingCamera.value) return;
-  presenting.value = false;
-  presentationError.value = '';
+function handleCanvasTourExit(data: Record<string, unknown>): void {
+  applyTourExit(data);
 }
 
 function handleCanvasCameraMove(data: Record<string, unknown>): void {