pmx-canvas 0.9.2 → 0.10.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/lifecycle.ts

@@ -3,8 +3,7 @@ import { canvasState } from '../../canvas-state.js';
 import { categorySchema, folderPropertiesSchema, lifecycleSchema } from '../../knowledge-lifecycle.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { readTargetBoard } from './boards.js';
-import { lifecycleQualifications, lifecycleSnapshot } from '../../lifecycle-status.js';
-import { memoryKey } from '../../../shared/memory-graph.js';
+import { lifecycleQualification, lifecycleSnapshot } from '../../lifecycle-status.js';
 import { folderAncestors } from '../../../shared/boards.js';
 import { relationPresetSchema } from '../../../shared/relations.js';
 
@@ -155,9 +154,7 @@ export const lifecycleOperations: Operation[] = [
         contentRevision: node.contentRevision ?? 0,
         ...canvasState.knowledge.resolveCard(folder, node),
         ...canvasState.knowledge.reviews(read.boardId, input.id),
-        qualification: lifecycleQualifications(Date.now(), [{ boardId: read.boardId, cardId: input.id }])[
-          memoryKey({ boardId: read.boardId, cardId: input.id })
-        ],
+        qualification: lifecycleQualification({ boardId: read.boardId, cardId: input.id }),
       };
     },
   }),
@@ -216,8 +213,7 @@ export const lifecycleOperations: Operation[] = [
       if (!canvasState.getNode(input.id) || !canvasState.activeBoardId)
         throw new OperationError('Card not found.', 404);
       const observations =
-        lifecycleQualifications()[memoryKey({ boardId: canvasState.activeBoardId, cardId: input.id })]?.observations ??
-        {};
+        lifecycleQualification({ boardId: canvasState.activeBoardId, cardId: input.id })?.observations ?? {};
       const validates =
         input.applied && input.evidence.trim() && ['retain', 'revise', 'externalize'].includes(input.outcome);
       if (validates) {

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

@@ -55,8 +55,7 @@ import {
 import { WEBPAGE_NODE_DEFAULT_SIZE, normalizeWebpageUrl } from '../../webpage-node.js';
 import { defineOperation, OperationError, type Operation, type OperationContext } from '../types.js';
 import { readTargetBoard } from './boards.js';
-import { lifecycleQualifications } from '../../lifecycle-status.js';
-import { memoryKey } from '../../../shared/memory-graph.js';
+import { lifecycleQualification } from '../../lifecycle-status.js';
 
 // ── Node types ────────────────────────────────────────────────
 // Single definition site for the basic node-type list: drives the HTTP type
@@ -634,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 } : {}),
@@ -649,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);
   }
@@ -1005,9 +1019,7 @@ const nodeGetOperation = defineOperation<z.infer<typeof nodeGetSchema>, Serializ
     const full = includeBlobs === true || includeBlobs === 'true';
     const qualify = (node: CanvasNodeState, boardId: string | null) => ({
       ...(full ? serializeCanvasNode(node) : serializeCanvasNodeWithBlobSummaries(node)),
-      qualification: boardId
-        ? lifecycleQualifications(Date.now(), [{ boardId, cardId: id }])[memoryKey({ boardId, cardId: id })]
-        : undefined,
+      qualification: boardId ? lifecycleQualification({ boardId, cardId: id }) : undefined,
     });
     if (typeof board === 'string' && board.trim()) {
       const target = readTargetBoard(board, full);
@@ -1189,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>;
     }
 
@@ -1445,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, derivedTour, rectSchema, cameraSchema, tourStopSchema } from '../../../shared/tour.js';
+import { tourSchema, rectSchema, cameraSchema, tourStopSchema } from '../../../shared/tour.js';
 import { canvasState } from '../../canvas-state.js';
 import {
   arrangeCanvasNodes,
@@ -23,7 +23,7 @@ import {
   setClientViewportSize,
 } from '../../canvas-operations.js';
 import { validateCanvasLayout } from '../../canvas-validation.js';
-import { exitTour, goToTourStop, moveCamera, tourPosition } from '../../tour-control.js';
+import { currentTour, exitTour, goToTourStop, moveCamera } from '../../tour-control.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { closeNodeAppSession, isRecord } from './nodes.js';
 
@@ -329,11 +329,7 @@ const tourGetOperation = defineOperation({
     toolName: 'canvas_get_tour',
     description: 'Read the board tour, deriving groups in reading order when absent.',
   },
-  handler: () => ({
-    tour: canvasState.getTour() ?? derivedTour(canvasState.getLayout().nodes),
-    derived: !canvasState.getTour(),
-    position: tourPosition(),
-  }),
+  handler: () => currentTour(),
 });
 
 // ── tour.go / tour.exit / camera.move ────────────────────────

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

@@ -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());
 }
 
@@ -2483,16 +2493,19 @@ async function handleRender(req: Request): Promise<Response> {
   // The editor sends its draft through this same endpoint. Only changed/unsaved
   // text may resolve titles; persisted text must replay even unresolved bindings.
   const persisted = node?.type === 'markdown' && node.data.content === markdown;
-  const initializedRefs =
-    node?.type === 'markdown' && node.data.wikiLinks !== undefined && typeof node.data.content === 'string'
-      ? wikiReferences(node.data.content)
-      : [];
-  const refs = wikiReferences(markdown).filter(
-    (ref) => !initializedRefs.includes(ref) || previous.some((link) => link.ref === ref),
-  );
-  const needsResolution = !persisted && refs.some((ref) => !previous.some((link) => link.ref === ref && link.target));
-  const catalog = needsResolution ? canvasState.wikiCatalog() : [];
-  const links = persisted ? previous : refs.map((ref) => resolveWikiLinks(`[[${ref}]]`, previous, catalog)[0]);
+  let links = previous;
+  if (!persisted) {
+    const initializedRefs =
+      node?.type === 'markdown' && node.data.wikiLinks !== undefined && typeof node.data.content === 'string'
+        ? wikiReferences(node.data.content)
+        : [];
+    const refs = wikiReferences(markdown).filter(
+      (ref) => !initializedRefs.includes(ref) || previous.some((link) => link.ref === ref),
+    );
+    const needsResolution = refs.some((ref) => !previous.some((link) => link.ref === ref && link.target));
+    const catalog = needsResolution ? canvasState.wikiCatalog() : [];
+    links = refs.map((ref) => resolveWikiLinks(`[[${ref}]]`, previous, catalog)[0]);
+  }
   const targets = new Map<string, ReturnType<typeof canvasState.readBoard>>();
   const html = renderWikiMarkdown(normalizeMarkdownExternalUrls(markdown), links, (target) => {
     if (!targets.has(target.boardId)) targets.set(target.boardId, canvasState.readBoard(target.boardId, false));

package/src/server/tour-control.ts

@@ -21,14 +21,22 @@ export interface TourStepResult {
   stop: TourStop;
 }
 
+export interface TourState {
+  tour: Tour;
+  derived: boolean;
+  position: number | null;
+}
+
 let cursor: { boardGeneration: number; tour: string; index: number } | null = null;
 
-export function currentTour(): Tour {
-  return canvasState.getTour() ?? derivedTour(canvasState.getLayout().nodes);
+export function currentTour(): TourState {
+  const saved = canvasState.getTour();
+  const tour = saved ?? derivedTour(canvasState.nodeGeometry());
+  return { tour, derived: !saved, position: tourPosition(tour) };
 }
 
 /** The stop the tour is on for the active board, or null when not touring. */
-export function tourPosition(tour: Tour = currentTour()): number | null {
+function tourPosition(tour: Tour): number | null {
   if (cursor && (cursor.boardGeneration !== canvasState.boardGeneration || cursor.tour !== JSON.stringify(tour))) {
     cursor = null;
   }
@@ -37,9 +45,8 @@ export function tourPosition(tour: Tour = currentTour()): number | null {
 
 /** Move the shared cursor. `next`/`previous` clamp at the ends; an explicit index must exist. */
 export function goToTourStop(step: TourStep): TourStepResult {
-  const tour = currentTour();
+  const { tour, position: at } = currentTour();
   const { stops } = tour;
-  const at = tourPosition(tour);
   if (stops.length === 0) {
     throw new OperationError('This board has no tour stops. Save a tour or add groups.', 400);
   }
@@ -67,13 +74,15 @@ export function moveCamera(input: unknown): { stop: TourStop; viewport: Camera }
     throw new OperationError('Give exactly one of nodeId, rect {x,y,width,height} or viewport {x,y,scale}.', 400);
   }
   const stop = parsed.data;
-  if ('nodeId' in stop.target && !canvasState.getNode(stop.target.nodeId)) {
-    throw new OperationError(`Node "${stop.target.nodeId}" not found.`, 404);
+  const nodes = 'nodeId' in stop.target ? canvasState.nodeGeometry() : [];
+  const target = stop.target;
+  if ('nodeId' in target && !nodes.some((node) => node.id === target.nodeId)) {
+    throw new OperationError(`Node "${target.nodeId}" not found.`, 404);
   }
   const size = getClientViewportSize() ?? { width: 1440, height: 900 };
   let viewport: Camera;
   try {
-    viewport = resolveStop(stop, canvasState.getLayout().nodes, size.width, size.height);
+    viewport = resolveStop(stop, nodes, size.width, size.height);
   } catch (error) {
     throw new OperationError(error instanceof Error ? error.message : String(error), 400);
   }

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}.`);