pmx-canvas 0.9.3 → 0.11.0

package/src/server/operations/ops/ax-timeline.ts

@@ -341,7 +341,7 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
     // `consumer` is a loop-safety scope, not a source label — never defaulted.
     formatResult: axJsonResult,
   },
-  handler: async (input) => {
+  handler: async (input, ctx) => {
     const consumer = typeof input.consumer === 'string' ? input.consumer : undefined;
     // A claim is proof this consumer polls steering — its presence (session or
     // external writer) becomes a legitimate composer steer target.
@@ -363,7 +363,7 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
       // Long-poll: hosts that cannot be woken from outside (Copilot, Codex —
       // their model runs only while the host gives it a turn) park here and
       // wake the moment steering lands, instead of burning the turn polling.
-      await waitForAxCondition({ ready: () => readPending().length > 0, timeoutMs });
+      await waitForAxCondition({ ready: () => readPending().length > 0, timeoutMs, signal: ctx.signal });
       pending = readPending();
     }
     // The MCP tool aggregated pendingActivity; one wire body now serves it over

package/src/server/operations/ops/batch.ts

@@ -44,6 +44,7 @@ export interface BatchEnvelope {
   refs: Record<string, unknown>;
   failedIndex?: number;
   error?: string;
+  cancelled?: boolean;
 }
 
 const SUPPORTED_BATCH_OPS = new Set([
@@ -220,7 +221,7 @@ function shapeBatchEntry(op: string, result: unknown, creationReceipt = false):
   return body;
 }
 
-async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
+async function runBatch(operations: BatchEntry[], ctx: OperationContext): Promise<BatchEnvelope> {
   const refs: Record<string, unknown> = {};
   const results: Array<Record<string, unknown>> = [];
 
@@ -231,6 +232,15 @@ async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
       return { ok: false, failedIndex: index, error: `Operation ${index} has invalid args.`, results, refs };
     }
     try {
+      ctx.signal?.throwIfAborted();
+      if (ctx.onProgress) {
+        const boardGeneration = canvasState.boardGeneration;
+        await ctx.onProgress({ progress: index, total: operations.length, message: operation.op });
+        if (canvasState.boardGeneration !== boardGeneration) {
+          throw new Error('The board changed while the batch was running.');
+        }
+      }
+      ctx.signal?.throwIfAborted();
       if (!SUPPORTED_BATCH_OPS.has(operation.op)) {
         return {
           ok: false,
@@ -259,35 +269,43 @@ async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
       // ghost-cursor exemption for batch operations). No `fromWorkbench`: the
       // browser never issues batches, so inner writes are agent writes and the
       // scope fence applies to each of them.
-      const pending = executeOperation(dispatch.name, dispatch.args, { suppressAutoGhost: true });
+      const pending = executeOperation(dispatch.name, dispatch.args, {
+        suppressAutoGhost: true,
+        signal: ctx.signal,
+        onProgress: ctx.onProgress
+          ? (progress) => ctx.onProgress!({ progress: index, total: operations.length, message: progress.message })
+          : undefined,
+      });
       // The first write may synchronously open a board from Home. Capture after
       // dispatch, then refuse to continue a partially completed batch elsewhere.
       const boardGeneration = canvasState.boardGeneration;
       const raw = await pending;
-      if (canvasState.boardGeneration !== boardGeneration) {
-        throw new Error('The board changed while the batch was running.');
-      }
+      const boardChanged = canvasState.boardGeneration !== boardGeneration;
       const result = shapeBatchEntry(
         operation.op,
         raw,
-        ['node.add', 'group.create', 'edge.add'].includes(operation.op) &&
-          (args.requestId !== undefined || args.destinationBoardId !== undefined),
+        boardChanged ||
+          (['node.add', 'group.create', 'edge.add'].includes(operation.op) &&
+            (args.requestId !== undefined || args.destinationBoardId !== undefined)),
       );
       results.push(result);
       if (typeof operation.assign === 'string' && operation.assign.trim().length > 0) {
         refs[operation.assign] = result;
       }
+      if (boardChanged) throw new Error('The board changed while the batch was running.');
     } catch (error) {
       return {
         ok: false,
         failedIndex: index,
         error: error instanceof Error ? error.message : String(error),
+        ...(ctx.signal?.aborted ? { cancelled: true } : {}),
         results,
         refs,
       };
     }
   }
 
+  await ctx.onProgress?.({ progress: operations.length, total: operations.length, message: 'Batch complete' });
   return { ok: true, results, refs };
 }
 
@@ -356,6 +374,7 @@ function compactBatchResult(result: BatchEnvelope): Record<string, unknown> {
     ok: result.ok,
     ...(result.failedIndex !== undefined ? { failedIndex: result.failedIndex } : {}),
     ...(result.error ? { error: result.error } : {}),
+    ...(result.cancelled ? { cancelled: true } : {}),
     results: result.results.map((entry) => compactBatchValue(entry)),
     refs: Object.fromEntries(Object.entries(result.refs).map(([key, value]) => [key, compactBatchValue(value)])),
   };
@@ -406,7 +425,7 @@ const batchOperation = defineOperation<z.infer<typeof batchSchema>, BatchEnvelop
     // Suppress every per-entry SSE frame (auto layout emit + each handler's
     // ctx.emit). After the loop completes, emit ONE final canvas-layout-update.
     const revision = canvasState.getContentRevision().revision;
-    const envelope = await runWithSuppressedEmits(() => runBatch(operations));
+    const envelope = await runWithSuppressedEmits(() => runBatch(operations, ctx));
     if (
       revision !== canvasState.getContentRevision().revision ||
       operations.some(

package/src/server/operations/ops/boards.ts

@@ -12,11 +12,10 @@
  *
  * This module must never import server.ts or index.ts.
  */
-import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { normalizeBoardFolder } from '../../../shared/boards.js';
 import { relationVocabularySchema } from '../../../shared/relations.js';
-import { canvasState, type CanvasLayout } from '../../canvas-state.js';
+import { boardCatalogEpoch, canvasState, type CanvasLayout } from '../../canvas-state.js';
 import { openCanvasBoard } from '../../canvas-operations.js';
 import { summarizeNodeForAgentContext } from '../../../shared/agent-context.js';
 import { BRIEF_SUMMARY_LENGTH } from '../../context-brief.js';
@@ -25,7 +24,6 @@ import { defineOperation, OperationError, type Operation, type OperationContext
 
 /** The most cards a Home thumbnail draws (the largest first); the rest are noise at that size. */
 const PREVIEW_CARDS = 24;
-export const boardCatalogEpoch = randomUUID();
 let catalogRevision = 0;
 let reloadRevision = 0;
 

package/src/server/operations/ops/nodes.ts

@@ -633,6 +633,7 @@ async function createWebpageNode(body: Record<string, unknown>, ctx: OperationCo
 
   const extraData = isRecord(body.data) ? body.data : undefined;
   const geometry = resolveCreateGeometry(body);
+  ctx.signal?.throwIfAborted();
   const { id, node, sizeAdjustment } = addCanvasNode({
     type: 'webpage',
     ...(typeof body.title === 'string' ? { title: body.title } : {}),
@@ -648,7 +649,21 @@ async function createWebpageNode(body: Record<string, unknown>, ctx: OperationCo
   // registry emits the final layout update after the handler returns.
   ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
   const boardGeneration = canvasState.boardGeneration;
-  const refreshed = await refreshCanvasWebpageNode(id);
+  let refreshed: Awaited<ReturnType<typeof refreshCanvasWebpageNode>>;
+  try {
+    refreshed = await refreshCanvasWebpageNode(id, { signal: ctx.signal });
+  } catch (error) {
+    if (!ctx.signal?.aborted) throw error;
+    // Creation already committed. Return its receipt without writing an error
+    // status; batches retain this node and stop before their next entry.
+    return {
+      node,
+      extras: {
+        fetch: { ok: false, cancelled: true, error: 'Webpage fetch cancelled.' },
+        ...(sizeAdjustment ? { sizeAdjustment } : {}),
+      },
+    };
+  }
   if (canvasState.boardGeneration !== boardGeneration) {
     throw new OperationError('The board changed while the webpage was loading.', 409);
   }
@@ -1186,7 +1201,7 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
           throw new OperationError(error instanceof Error ? error.message : 'Invalid webpage URL.');
         }
       }
-      const result = await refreshCanvasWebpageNode(id, { ...(url ? { url } : {}) });
+      const result = await refreshCanvasWebpageNode(id, { ...(url ? { url } : {}), signal: ctx.signal });
       return result as unknown as Record<string, unknown>;
     }
 
@@ -1442,7 +1457,7 @@ const nodeRefreshOperation = defineOperation<z.infer<typeof nodeRefreshSchema>,
     }
     // Legacy wire: the layout update fires after every completed refresh
     // attempt, success or failure (the node may have partial refresh state).
-    const result = await refreshCanvasWebpageNode(nodeId, { ...(url ? { url } : {}) });
+    const result = await refreshCanvasWebpageNode(nodeId, { ...(url ? { url } : {}), signal: ctx.signal });
     ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
     return result as unknown as Record<string, unknown>;
   },

package/src/server/operations/ops/viewport.ts

@@ -13,7 +13,7 @@
  * This module must never import server.ts or index.ts.
  */
 import { z } from 'zod';
-import { tourSchema, rectSchema, cameraSchema, tourStopSchema } from '../../../shared/tour.js';
+import { tourSchema, rectSchema, cameraSchema, tourStopSchema, tourPresenterSchema } from '../../../shared/tour.js';
 import { canvasState } from '../../canvas-state.js';
 import {
   arrangeCanvasNodes,
@@ -339,6 +339,7 @@ const tourGetOperation = defineOperation({
 const tourGoShape = {
   stop: z.number().int().nonnegative().optional().describe('Zero-based stop index to go to'),
   step: z.enum(['next', 'previous']).optional().describe('Step relative to the current stop (clamped at the ends)'),
+  presenter: tourPresenterSchema.optional().describe('Document intent order and expected board activation'),
   present: z
     .boolean()
     .optional()
@@ -360,23 +361,24 @@ const tourGoOperation = defineOperation({
     if ((input.stop === undefined) === (input.step === undefined)) {
       throw new OperationError('Give exactly one of stop (index) or step ("next" | "previous").');
     }
-    const result = goToTourStop(input.stop ?? (input.step as 'next' | 'previous'));
-    ctx.emit('canvas-tour-step', { ...result, present: input.present !== false });
+    const result = goToTourStop(input.stop ?? (input.step as 'next' | 'previous'), input.presenter);
+    if (!('superseded' in result)) ctx.emit('canvas-tour-step', { ...result, present: input.present !== false });
     return { ok: true, ...result };
   },
 });
 
+const tourExitShape = { presenter: tourGoShape.presenter };
 const tourExitOperation = defineOperation({
   name: 'tour.exit',
   mutates: false,
-  input: z.object({}),
-  inputShape: {},
+  input: z.object(tourExitShape),
+  inputShape: tourExitShape,
   http: { method: 'POST', path: '/api/canvas/tour/exit' },
   mcp: { toolName: 'canvas_tour_exit', description: 'Leave presentation in every viewer.' },
-  handler: (_input, ctx) => {
-    exitTour();
-    ctx.emit('canvas-tour-exit', {});
-    return { ok: true };
+  handler: (input, ctx) => {
+    const result = exitTour(input.presenter);
+    if (!('superseded' in result)) ctx.emit('canvas-tour-exit', { ...result });
+    return { ok: true, ...result };
   },
 });
 

package/src/server/operations/registry.ts

@@ -20,7 +20,7 @@ import type { MemoryGraph } from '../../shared/memory-graph.js';
 import { openBoardForWrite } from '../canvas-operations.js';
 import { boardsPayload } from './ops/boards.js';
 import type { PmxAxIntent, PmxAxIntentKind } from '../../shared/ax-intent.js';
-import { OperationError, type Operation, type OperationContext } from './types.js';
+import { OperationError, type Operation, type OperationContext, type OperationExecutionOptions } from './types.js';
 
 const operations = new Map<string, Operation>();
 
@@ -75,8 +75,6 @@ export async function runWithSuppressedEmits<T>(fn: () => Promise<T>): Promise<T
   return suppressedEmits.run(true, fn);
 }
 
-const operationContext: OperationContext = { emit: emitOperationEvent };
-
 const INTENT_KINDS_BY_OPERATION: Record<string, readonly PmxAxIntentKind[]> = {
   'node.add': ['create'],
   'jsonrender.add': ['create'],
@@ -204,7 +202,7 @@ function autoGhostInput(name: string, rawInput: unknown, kind: string): Record<s
   }
 }
 
-export interface ExecuteOperationMeta {
+export interface ExecuteOperationMeta extends OperationExecutionOptions {
   /**
    * Skip the synthesized auto-ghost: set by the workbench's own HTTP calls
    * (a human dragging a node is not agent activity) and by canvas.batch for
@@ -395,6 +393,8 @@ export async function executeOperation(
   rawInput: unknown,
   meta: ExecuteOperationMeta = {},
 ): Promise<unknown> {
+  // Check before attribution, board auto-open, ghosts, or any handler writes.
+  meta.signal?.throwIfAborted();
   // Attribution follows this call chain across awaits and nested operations.
   const inputAgentId = asRecord(rawInput).agentId;
   return withCurrentActor(
@@ -479,6 +479,22 @@ function needsOpenBoard(op: Operation): boolean {
 }
 
 async function executeOperationInner(name: string, rawInput: unknown, meta: ExecuteOperationMeta): Promise<unknown> {
+  meta.signal?.throwIfAborted();
+  const operationContext: OperationContext = {
+    emit: emitOperationEvent,
+    signal: meta.signal,
+    // Progress is observational. A disconnected observer must not erase the
+    // receipt of a completed write or strand a batch's final layout emit.
+    onProgress: meta.onProgress
+      ? async (progress) => {
+          try {
+            await meta.onProgress!(progress);
+          } catch (error) {
+            if (!meta.signal?.aborted) console.error(`[operation] progress callback failed for ${name}:`, error);
+          }
+        }
+      : undefined,
+  };
   const op = getOperation(name);
   const storedCreation =
     ['node.add', 'group.create', 'edge.add'].includes(name) &&
@@ -543,6 +559,7 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
   }
   if (storedCreation) {
     const revision = canvasState.getContentRevision().revision;
+    meta.signal?.throwIfAborted();
     const result = await op.execute(rawInput, operationContext);
     const destination = asRecord(rawInput).destinationBoardId ?? canvasState.activeBoardId;
     if (destination === canvasState.activeBoardId || revision !== canvasState.getContentRevision().revision)
@@ -566,6 +583,7 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
       intentId,
       allowedKinds!,
       async () => {
+        meta.signal?.throwIfAborted();
         const result = await op.execute(input, operationContext);
         if (op.mutates) {
           emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
@@ -606,6 +624,7 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
     if (ghost) {
       const ghostId = ghost.id;
       try {
+        meta.signal?.throwIfAborted();
         const result = await op.execute(rawInput, operationContext);
         if (op.mutates) emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
         intentRegistry.clear(ghostId, { settledNodeId: settledNodeId(result, ghost) ?? undefined });
@@ -621,6 +640,7 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
   const beforeBoard = canvasState.activeBoardId;
   const beforeRevision =
     name === 'board.create-from' || name === 'board.delete' ? canvasState.getContentRevision().revision : null;
+  meta.signal?.throwIfAborted();
   const result = await op.execute(rawInput, operationContext);
   // Library writes can invalidate relations on the open board without being
   // layout mutations themselves. Publish those clocks once, after the write.

package/src/server/operations/types.ts

@@ -29,7 +29,19 @@ export class OperationError extends Error {
   }
 }
 
-export interface OperationContext {
+export interface OperationProgress {
+  progress: number;
+  total?: number;
+  message?: string;
+}
+
+/** Cooperative cancellation: completed writes are never rolled back. */
+export interface OperationExecutionOptions {
+  signal?: AbortSignal;
+  onProgress?: (progress: OperationProgress) => void | Promise<void>;
+}
+
+export interface OperationContext extends OperationExecutionOptions {
   /** Emit a workbench SSE event (e.g. extra `canvas-layout-update` frames, focus, viewport). */
   emit(event: string, payload?: Record<string, unknown>): void;
 }
@@ -67,7 +79,9 @@ export interface OperationMcpToolHost {
    * Used by formatters that need a follow-up read (undo/redo history flags,
    * restore summary).
    */
-  invoker(): { invoke(name: string, input: Record<string, unknown>): Promise<unknown> };
+  invoker(): {
+    invoke(name: string, input: Record<string, unknown>, options?: OperationExecutionOptions): Promise<unknown>;
+  };
 }
 
 export interface OperationMcpTool {

package/src/server/server.ts

@@ -47,8 +47,8 @@ import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'nod
 import * as marked from 'marked';
 import { renderWikiMarkdown, resolveWikiLinks, wikiReferences } from './wiki-links.js';
 import { wikiLinksFromData } from '../shared/memory-graph.js';
-import { type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
-import { boardCatalogEpoch, boardsPayload } from './operations/ops/boards.js';
+import { type CanvasNodeState, IMAGE_MIME_MAP, boardCatalogEpoch, canvasState } from './canvas-state.js';
+import { boardsPayload } from './operations/ops/boards.js';
 import {
   buildAxBridge,
   buildAxStateBridge,
@@ -72,7 +72,7 @@ import { buildAgentContextPreamble } from '../shared/agent-context.js';
 import { buildCanvasAxSurfaceSnapshot } from './ax-context.js';
 import { resolveNodeAxCapabilities } from './ax-interaction.js';
 import { normalizeCanvasTheme, type CanvasTheme } from './canvas-db.js';
-import { canvasThemeScheme, isCanvasTheme } from '../shared/themes.js';
+import { isCanvasTheme } from '../shared/themes.js';
 import { canOpenNodeAsSurface } from '../shared/surface.js';
 import { validateLocalImageFile } from './image-source.js';
 import {
@@ -930,6 +930,15 @@ let workbenchEventSeq = 0;
 const workbenchEventRing: Array<{ seq: number; event: string; payload: PrimaryWorkbenchEventPayload }> = [];
 const workbenchPollWaiters = new Set<() => void>();
 let remoteEdgesSignature = '';
+const workbenchEventListeners = new Set<(event: string) => void>();
+
+/** In-process invalidation observers share the same events as daemon SSE clients. */
+export function onWorkbenchEvent(listener: (event: string) => void): () => void {
+  workbenchEventListeners.add(listener);
+  return () => {
+    workbenchEventListeners.delete(listener);
+  };
+}
 
 function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPayload): void {
   let remoteEdgesChanged = false;
@@ -975,6 +984,7 @@ function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPa
       syncCanvasBrowserOpenedFromSubscribers();
     }
   }
+  for (const listener of workbenchEventListeners) listener(event);
   if (remoteEdgesChanged) emitPrimaryWorkbenchEvent('boards-changed', boardsPayload());
 }
 
@@ -1494,44 +1504,6 @@ function handleIframeProbe(): Response {
   );
 }
 
-// ── Ext-app recovery diagnostics (0.3.2 report Finding N) ──────
-//
-// The WebKit black-tile recovery trail is otherwise trapped inside host panels
-// without devtools (the Copilot WKWebView). Clients mirror their bounded
-// recovery log here; agents/testers read it back over HTTP. In-memory only,
-// diagnostics-grade: no persistence, no snapshots.
-const EXT_APP_RECOVERY_LOG_MAX = 500;
-const EXT_APP_RECOVERY_FIELD_MAX = 300;
-const extAppRecoveryEntries: Array<Record<string, unknown>> = [];
-
-/**
- * Clamp a reported entry to the known trail shape ({ t, nodeId, event,
- * visibility }) with bounded string lengths. The count trim below caps the
- * number of entries; this caps bytes per entry, so the in-memory log stays
- * diagnostics-sized no matter what a client posts.
- */
-function clampExtAppRecoveryEntry(entry: Record<string, unknown>): Record<string, unknown> {
-  const clamped: Record<string, unknown> = {};
-  if (typeof entry.t === 'number' && Number.isFinite(entry.t)) clamped.t = entry.t;
-  for (const key of ['nodeId', 'event', 'visibility'] as const) {
-    const value = entry[key];
-    if (typeof value === 'string') clamped[key] = value.slice(0, EXT_APP_RECOVERY_FIELD_MAX);
-  }
-  return clamped;
-}
-
-function handleExtAppRecoveryReport(entries: unknown): Response {
-  if (!Array.isArray(entries)) return responseJson({ ok: false, error: 'entries must be an array' }, 400);
-  for (const entry of entries.slice(0, 100)) {
-    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
-    extAppRecoveryEntries.push(clampExtAppRecoveryEntry(entry as Record<string, unknown>));
-  }
-  if (extAppRecoveryEntries.length > EXT_APP_RECOVERY_LOG_MAX) {
-    extAppRecoveryEntries.splice(0, extAppRecoveryEntries.length - EXT_APP_RECOVERY_LOG_MAX);
-  }
-  return responseJson({ ok: true, total: extAppRecoveryEntries.length });
-}
-
 // ── Node surfaces ("Open as site") ─────────────────────────────
 //
 // One stable, node-addressable URL — /api/canvas/surface/:nodeId — that serves
@@ -1831,14 +1803,7 @@ async function handleJsonRenderView(url: URL): Promise<Response> {
   );
 
   const themeValue = url.searchParams.get('theme');
-  // The viewer bundle themes dark/light/high-contrast directly; other named
-  // canvas themes (midnight, sepia, …) collapse to their dark/light scheme.
-  const theme =
-    themeValue === 'dark' || themeValue === 'light' || themeValue === 'high-contrast'
-      ? themeValue
-      : isCanvasTheme(themeValue)
-        ? canvasThemeScheme(themeValue)
-        : undefined;
+  const theme = themeValue === 'dark' || themeValue === 'light' || isCanvasTheme(themeValue) ? themeValue : 'harbor';
   const title = (node.data.title as string) || node.id;
   // Devtools panel is double-gated: the operator must opt in via the env flag
   // AND the request must carry ?devtools=1. Off by default in all normal runs.
@@ -2264,6 +2229,9 @@ function buildWorkbenchConnectSnapshot(
       timestamp: new Date().toISOString(),
     },
   });
+  // Establish ownership in this ordered stream before layouts and live tour
+  // commands. The separate catalog HTTP response may arrive after either.
+  events.push({ event: 'boards-changed', payload: boardsPayload() });
   if (primaryWorkbenchPath) {
     events.push({
       event: 'workbench-open',
@@ -3561,16 +3529,6 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleJsonRenderView(url);
           }
 
-          if (url.pathname === '/api/canvas/debug/ext-app-recovery' && req.method === 'POST') {
-            const body = await readJson(req);
-            if (body === null) return malformedJsonResponse();
-            return handleExtAppRecoveryReport(body.entries);
-          }
-
-          if (url.pathname === '/api/canvas/debug/ext-app-recovery' && req.method === 'GET') {
-            return responseJson({ ok: true, entries: extAppRecoveryEntries });
-          }
-
           if (url.pathname === '/api/canvas/frame-documents' && req.method === 'POST') {
             return handleCreateFrameDocument(req);
           }

package/src/server/tour-control.ts

@@ -8,19 +8,38 @@
  *
  * This module must never import server.ts or index.ts.
  */
-import { derivedTour, resolveStop, tourStopSchema, type Camera, type Tour, type TourStop } from '../shared/tour.js';
-import { canvasState } from './canvas-state.js';
+import {
+  derivedTour,
+  resolveStop,
+  tourPresenterSchema,
+  tourStopSchema,
+  type Camera,
+  type Tour,
+  type TourPresenter,
+  type TourStop,
+} from '../shared/tour.js';
+import { boardCatalogEpoch, canvasState } from './canvas-state.js';
 import { getClientViewportSize } from './canvas-operations.js';
 import { OperationError } from './operations/types.js';
 
 export type TourStep = number | 'next' | 'previous';
 
-export interface TourStepResult {
+export interface TourDelivery {
+  catalogEpoch: string;
+  boardGeneration: number;
+  sequence: number;
+}
+
+export interface TourStepResult extends TourDelivery {
   index: number;
   total: number;
   stop: TourStop;
 }
 
+export interface TourSuperseded {
+  superseded: true;
+}
+
 export interface TourState {
   tour: Tour;
   derived: boolean;
@@ -28,6 +47,35 @@ export interface TourState {
 }
 
 let cursor: { boardGeneration: number; tour: string; index: number } | null = null;
+// One order for both HTTP acknowledgements and event delivery in this server run.
+let sequence = 0;
+let presenterGeneration = -1;
+const presenterIntents = new Map<string, number>();
+
+function claimPresenter(presenter: TourPresenter | undefined): boolean {
+  if (presenter === undefined) return true;
+  const { clientId, intent, catalogEpoch, boardGeneration } = tourPresenterSchema.parse(presenter);
+  if (catalogEpoch !== boardCatalogEpoch || boardGeneration !== canvasState.boardGeneration) return false;
+  if (presenterGeneration !== boardGeneration) {
+    presenterIntents.clear();
+    presenterGeneration = boardGeneration;
+  }
+  const previous = presenterIntents.get(clientId);
+  if (previous !== undefined && intent <= previous) return false;
+  // Never evict an identity: that would make its delayed requests valid again.
+  if (previous === undefined && presenterIntents.size >= 4096)
+    throw new OperationError(
+      'Too many presentation documents on this board activation. Reopen the board to continue.',
+      409,
+    );
+  // Even a later invalid stop supersedes older commands. Claim before resolving it.
+  presenterIntents.set(clientId, intent);
+  return true;
+}
+
+function nextDelivery(): TourDelivery {
+  return { catalogEpoch: boardCatalogEpoch, boardGeneration: canvasState.boardGeneration, sequence: ++sequence };
+}
 
 export function currentTour(): TourState {
   const saved = canvasState.getTour();
@@ -44,7 +92,10 @@ function tourPosition(tour: Tour): number | null {
 }
 
 /** Move the shared cursor. `next`/`previous` clamp at the ends; an explicit index must exist. */
-export function goToTourStop(step: TourStep): TourStepResult {
+export function goToTourStop(step: TourStep): TourStepResult;
+export function goToTourStop(step: TourStep, presenter: TourPresenter | undefined): TourStepResult | TourSuperseded;
+export function goToTourStop(step: TourStep, presenter?: TourPresenter): TourStepResult | TourSuperseded {
+  if (!claimPresenter(presenter)) return { superseded: true };
   const { tour, position: at } = currentTour();
   const { stops } = tour;
   if (stops.length === 0) {
@@ -56,11 +107,20 @@ export function goToTourStop(step: TourStep): TourStepResult {
   else if (Number.isInteger(step) && step >= 0 && step < stops.length) index = step;
   else throw new OperationError(`Tour stop ${step} does not exist (stops 0–${stops.length - 1}).`, 400);
   cursor = { boardGeneration: canvasState.boardGeneration, tour: JSON.stringify(tour), index };
-  return { index, total: stops.length, stop: stops[index] as TourStop };
+  return {
+    ...nextDelivery(),
+    index,
+    total: stops.length,
+    stop: stops[index] as TourStop,
+  };
 }
 
-export function exitTour(): void {
+export function exitTour(): TourDelivery;
+export function exitTour(presenter: TourPresenter | undefined): TourDelivery | TourSuperseded;
+export function exitTour(presenter?: TourPresenter): TourDelivery | TourSuperseded {
+  if (!claimPresenter(presenter)) return { superseded: true };
   cursor = null;
+  return nextDelivery();
 }
 
 /**

package/src/server/webpage-node.ts

@@ -386,34 +386,37 @@ export function checkWebpageHop(originScope: AddressScope, hopScope: AddressScop
 
 export async function fetchWebpageSnapshot(
   inputUrl: string,
-  options: { resolveHost?: ResolveHost; timeoutMs?: number } = {},
+  options: { resolveHost?: ResolveHost; timeoutMs?: number; signal?: AbortSignal } = {},
 ): Promise<WebpageSnapshot> {
+  options.signal?.throwIfAborted();
   const url = normalizeWebpageUrl(inputUrl);
   const controller = new AbortController();
+  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
   const timeoutMs = options.timeoutMs ?? FETCH_TIMEOUT_MS;
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
   const resolveHost = options.resolveHost ?? ((host) => lookup(host, { all: true }));
 
   try {
     // Redirects are followed by hand so every hop's host is checked before it is fetched.
-    let resolved = await abortable(resolveHop(new URL(url), resolveHost), controller.signal);
+    let resolved = await abortable(resolveHop(new URL(url), resolveHost), signal);
     const originScope = resolved.scope;
     let hopUrl = url;
     let response: Response;
     for (let hop = 0; ; hop++) {
       checkWebpageHop(originScope, resolved.scope, hopUrl);
-      response = await requestHop(new URL(hopUrl), resolved, controller.signal);
+      response = await requestHop(new URL(hopUrl), resolved, signal);
       const location = response.headers.get('location');
       if (response.status < 300 || response.status >= 400 || !location) break;
       await response.body?.cancel();
       if (hop === MAX_REDIRECTS) throw new WebpageFetchError(`Too many redirects while fetching ${url}.`);
       hopUrl = normalizeWebpageUrl(new URL(location, hopUrl).toString());
-      resolved = await abortable(resolveHop(new URL(hopUrl), resolveHost), controller.signal);
+      resolved = await abortable(resolveHop(new URL(hopUrl), resolveHost), signal);
     }
 
     const contentType = response.headers.get('content-type');
     const responseUrl = hopUrl;
     const body = await readBoundedBody(response);
+    signal.throwIfAborted();
 
     if (!response.ok) {
       throw new WebpageFetchError(`Request failed with ${response.status} ${response.statusText}`.trim(), {
@@ -450,6 +453,8 @@ export async function fetchWebpageSnapshot(
       frameBlockedReason,
     };
   } catch (error) {
+    // Caller cancellation is not a fetch failure or our internal timeout.
+    options.signal?.throwIfAborted();
     if (error instanceof WebpageFetchError) throw error;
     if (error instanceof Error && error.name === 'AbortError') {
       throw new WebpageFetchError(`Timed out after ${timeoutMs}ms while fetching ${url}.`);