@opencraw/studio 0.0.34 → 0.0.37

package/dist/index.esm.js

@@ -3,14 +3,14 @@ import { createServer } from 'node:http';
 import { promisify, stripVTControlCharacters } from 'node:util';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { z } from 'zod';
-import { BODY_KINDS, formatOfResponse, HttpClient, BrowserClient, NODE_ID_ATTRIBUTE, sessionStateOf, rowsOfCells, parseXml, marginRows, findDeckTables, findGridTables, analyzeTables, parseRegion, regionText, deckRegionText, isDeckDocument, readRecipeSource, parseInputRecipe, parseOutputRecipe, calloutLabel, bindRecipeSet, memorySink, createCrawler, traceLine, UnknownHookError, resolveMissingPolicy, isWorkbookDocument, RecipeBindingError, RecipeValidationError, countMatches, matchesOf, tryParseJson, isPdfDocument, BrowserProfiles } from '@opencraw/core';
-import { randomBytes, createHash } from 'node:crypto';
+import { BODY_KINDS, formatOfResponse, HttpClient, BrowserClient, NODE_ID_ATTRIBUTE, sessionStateOf, readRecipeSource, parseInputRecipe, parseOutputRecipe, calloutLabel, bindRecipeSet, memorySink, createCrawler, traceLine, UnknownHookError, rowsOfCells, parseXml, marginRows, findDeckTables, findGridTables, analyzeTables, parseRegion, regionText, deckRegionText, isDeckDocument, resolveMissingPolicy, isWorkbookDocument, RecipeBindingError, RecipeValidationError, countMatches, matchesOf, tryParseJson, isPdfDocument, BrowserProfiles } from '@opencraw/core';
+import { randomBytes, randomUUID, createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
+import { mkdir, writeFile, chmod, rm, readFile, rename, stat } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
 import { load } from 'cheerio';
-import { readFile, writeFile, rm, rename, mkdir, stat } from 'node:fs/promises';
 import { describeJson } from '@opencraw/probe';
-import { tmpdir } from 'node:os';
 import { existsSync, createReadStream } from 'node:fs';
 
 const sentencePartSchema = z.object({
@@ -41,6 +41,25 @@ const outlineViewSchema = z.object({
   steps: z.array(outlineNodeSchema)
 });
 
+/** What an outside controller (an agent, through the MCP server) can ask the open Studio page to do. Grows one `kind` at a time. */
+const uiRequestSchema = z.discriminatedUnion('kind', [/** Open a folder, a recipe file or a document, exactly as a Studio link does (`open-path`); `workspace` is the folder a document belongs to. */
+z.object({
+  kind: z.literal('open'),
+  path: z.string().min(1),
+  workspace: z.string().min(1).optional()
+}),
+/**
+ * Pick a value on the recipe's web page, as a click would: the page finds the element by `selector` (a CSS selector) or by its `text`,
+ * stages it the way a click does (the ways to reach it are shown to choose from) and, with `add`, adds it to the recipe.
+ */
+z.object({
+  kind: z.literal('pick'),
+  recipeId: z.string().min(1),
+  selector: z.string().min(1).optional(),
+  text: z.string().min(1).optional(),
+  add: z.boolean().optional()
+})]);
+
 /** A budget for a sample run; never authored into a recipe, only asked for by the caller. */
 const sampleBudgetSchema = z.object({
   maxRecords: z.number().int().positive().optional(),
@@ -373,7 +392,35 @@ const importDocumentCommandSchema = z.object({
   name: z.string().min(1),
   bytes: z.string()
 });
-const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, chooseFolderCommandSchema, openPathCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, detectUrlCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, gridViewCommandSchema, gridRowsCommandSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema]);
+/** Asks every open Studio page to do something (`ui-request`); the answer says how many pages were listening. How an agent opens a recipe for the person who is watching. */
+const askUiCommandSchema = z.object({
+  type: z.literal('ask-ui'),
+  request: uiRequestSchema
+});
+/** The page tells the server how a controller's request went, so the controller can find out (`ui-outcome`). */
+const uiReportCommandSchema = z.object({
+  type: z.literal('ui-report'),
+  requestId: z.string().min(1),
+  ok: z.boolean(),
+  message: z.string(),
+  /** What the page found or did, for the controller to read. */
+  detail: z.record(z.string(), z.unknown()).optional()
+});
+/** Asks how a controller's request went: still waiting for the page, or done. */
+const uiOutcomeCommandSchema = z.object({
+  type: z.literal('ui-outcome'),
+  requestId: z.string().min(1)
+});
+/** Asks what Studio is doing: its workspace, how many pages are open and the run in progress. */
+const studioStatusCommandSchema = z.object({
+  type: z.literal('studio-status')
+});
+/** Asks how a recipe's sample run is going: still running, finished (with its first records) or never run. */
+const runStatusCommandSchema = z.object({
+  type: z.literal('run-status'),
+  recipeId: z.string().min(1)
+});
+const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, chooseFolderCommandSchema, openPathCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, detectUrlCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, gridViewCommandSchema, gridRowsCommandSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema, askUiCommandSchema, uiReportCommandSchema, uiOutcomeCommandSchema, studioStatusCommandSchema, runStatusCommandSchema]);
 
 /**
  * What `take-snapshot` answers with: the rewritten document ready for the
@@ -531,7 +578,14 @@ const recordingStoppedEventSchema = z.object({
   type: z.literal('recording-stopped'),
   steps: z.array(recordedStepSchema)
 });
-const studioEventSchema = z.discriminatedUnion('type', [traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema]);
+/** A controller (an agent, through the MCP server) asked the open page to do something; every page does it. */
+const uiRequestEventSchema = z.object({
+  type: z.literal('ui-request'),
+  /** Names the request, so the page can report how it went (`ui-report`) and the controller can ask (`ui-outcome`). */
+  requestId: z.string().min(1),
+  request: uiRequestSchema
+});
+const studioEventSchema = z.discriminatedUnion('type', [traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, uiRequestEventSchema]);
 
 /** One problem found on a recipe file, with the JSON path it lives at. */
 const recipeIssueSchema = z.object({
@@ -913,6 +967,45 @@ const deckTablePreviewViewSchema = z.object({
   error: z.string().optional()
 });
 
+/** How many pages were listening when a controller asked them to do something: none means nobody has Studio open. */
+z.object({
+  pages: z.number(),
+  requestId: z.string()
+});
+/** How a controller's request went: `pending` until a page reported, then what it said. */
+z.object({
+  state: z.enum(['pending', 'done']),
+  ok: z.boolean().optional(),
+  message: z.string().optional(),
+  detail: z.record(z.string(), z.unknown()).optional()
+});
+/** What Studio is doing: its workspace, how many pages are open, and the recipe whose sample run is in progress. */
+z.object({
+  folder: z.string().optional(),
+  pages: z.number(),
+  running: z.string().optional()
+});
+const rejectionSchema = z.object({
+  field: z.string(),
+  reason: z.string(),
+  url: z.string()
+});
+/** How a recipe's sample run is going; `result` only once it finished: the counts, the first records and the first rejections (the rest are in Studio). */
+z.object({
+  recipeId: z.string(),
+  state: z.enum(['running', 'finished', 'never-run']),
+  result: z.object({
+    emitted: z.number(),
+    rejected: z.number(),
+    duplicates: z.number(),
+    durationMs: z.number(),
+    error: z.string().optional(),
+    stoppedBy: z.string().optional(),
+    records: z.array(sampleRunRecordSchema),
+    rejections: z.array(rejectionSchema)
+  }).optional()
+});
+
 /** The cookie set on the page's own document response, so its own asset and API requests carry the token too. */
 const TOKEN_COOKIE = 'opencraw_token';
 /** A random token, generated once at server startup and required on every request. */
@@ -1064,30 +1157,41 @@ async function chooseFolderWithDialog(platform = process.platform, run = runDial
   throw new Error(`there is no folder dialog on this machine${tried === '' ? '' : ` (${tried} is not installed)`}: type the folder instead`);
 }
 
-/** Asks the dialog, and clears `openDialog` once it has answered or failed, so the next request opens a new one. */
-async function askOnce(state, ask) {
-  try {
-    return await ask();
-  } finally {
-    state.openDialog = undefined;
-  }
+/** The announcement's file: one per process and port, so two Studios in one process do not share it. */
+function fileOf(instance, directory) {
+  return join(directory, `${String(instance.pid)}-${new URL(instance.url).port}.json`);
+}
+/** Where running Studios announce themselves, unless the caller says otherwise. */
+function defaultInstancesDirectory() {
+  return join(homedir(), '.opencraw', 'studio');
 }
 /**
- * Handles `choose-folder`: opens the folder dialog of the machine the server
- * runs on and answers the folder picked. Only answers: the UI follows with
- * `open-workspace`, the same as when the folder is typed. A dialog still
- * open is not opened a second time; the second request waits for the first.
+ * Writes the file that tells controllers this Studio is running. Failing to write it never stops Studio: it only means no agent can find it.
  *
- * @param state - The server state holding the dialog to use.
- * @returns The folder, or none when the dialog was closed.
+ * @param instance - What to announce.
+ * @param directory - Where announcements live.
+ * @returns Whether the file was written.
  */
-async function handleChooseFolder(state) {
-  if (state.chooseFolder === undefined) throw new Error('this server has no folder dialog: type the folder instead');
-  state.openDialog ??= askOnce(state, state.chooseFolder);
-  const folder = await state.openDialog;
-  return folder === undefined ? {} : {
-    folder
-  };
+async function announceInstance(instance, directory) {
+  try {
+    await mkdir(directory, {
+      recursive: true
+    });
+    const file = fileOf(instance, directory);
+    await writeFile(file, JSON.stringify(instance), {
+      mode: 0o600
+    });
+    await chmod(file, 0o600);
+    return true;
+  } catch {
+    return false;
+  }
+}
+/** Removes the announcement, when Studio stops. */
+async function withdrawInstance(instance, directory) {
+  await rm(fileOf(instance, directory), {
+    force: true
+  });
 }
 
 /** How much of the start of a response is looked at: enough for the engine to tell a PDF or an Office package from its bytes, and for JSON to start. */
@@ -1980,156 +2084,515 @@ async function savedRecipe(file) {
   }
 }
 
-/** A cell reads as an ISO date (`2026-06-01`), an ISO moment (`2026-06-01T09:30:00`) or a bare time of day (`09:30:00`) — the three shapes `workbook-document`'s `read-xlsx.client.ts` writes for a spreadsheet date. */
-const ISO_DATE_OR_TIME = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2})?$|^\d{2}:\d{2}:\d{2}$/;
 /**
- * Builds the grid canvas's view model (studio plan §3.4, issue #94's 5c) from
- * an already-read `WorkbookDocument` (`take-snapshot`'s cached body — no
- * second read of the file): every sheet's cells, typed, with hidden sheets
- * and rows marked, and merged ranges resolved to bounds so the grid draws
- * them as one cell. Table-specific diagnostics (the matched rows of the
- * current `table` extract's options) are not here — they depend on the
- * picks so far, so they come from `table-preview.use-case.ts`'s
- * `previewGridTable` instead, computed live as those options change.
+ * Finds and parses one input recipe of a workspace folder, and the output
+ * recipe it names.
  *
- * @param document - The read workbook (a spreadsheet or a CSV).
- * @returns The view.
+ * @param folder - The workspace folder.
+ * @param recipeId - The input recipe's id.
+ * @returns The parsed pair.
+ * @throws RecipeValidationError when either recipe does not parse.
+ * @throws Error when the input or its output is not in the folder.
  */
-function workbookDocumentView(document, options = {}) {
+async function loadRecipePair(folder, recipeId) {
+  const documents = await readRecipeSource(folder);
+  const inputDocument = documents.find(document => kindOf(document.content) === 'input' && idOf(document.content) === recipeId);
+  if (inputDocument === undefined) throw new Error(`no input recipe "${recipeId}" in this workspace`);
+  const input = parseInputRecipe(inputDocument.content, inputDocument.source);
+  const outputDocument = documents.find(document => kindOf(document.content) === 'output' && idOf(document.content) === input.output);
+  if (outputDocument === undefined) throw new Error(`no output recipe "${input.output}" in this workspace`);
   return {
-    sheets: document.sheets.map(sheet => sheetView(sheet, options.windowRows)),
-    ...(document.csv !== undefined && {
-      csv: document.csv
-    })
+    input,
+    output: parseOutputRecipe(outputDocument.content, outputDocument.source)
   };
 }
-function sheetView(sheet, windowRows) {
-  const windowed = windowRows !== undefined && sheet.rows.length > windowRows;
-  return {
-    name: sheet.name,
-    hidden: sheet.hidden === true,
-    hiddenRows: sheet.hiddenRows === undefined ? [] : [...sheet.hiddenRows],
-    // Not `Math.max(...lengths)`: a spread of a few hundred thousand rows overflows the call stack.
-    columnCount: sheet.rows.reduce((widest, row) => Math.max(widest, row.length), 0),
-    rows: (windowed ? sheet.rows.slice(0, windowRows) : sheet.rows).map(row => row.map(cell => cellView(cell))),
-    ...(windowed && {
-      rowCount: sheet.rows.length
-    }),
-    merges: (sheet.merges ?? []).flatMap(reference => {
-      const range = rangeOf(reference);
-      return range === undefined ? [] : [{
-        ref: reference,
-        ...range
-      }];
-    }),
-    ...(sheet.columnWidths !== undefined && {
-      columnWidths: {
-        ...sheet.columnWidths
-      }
-    }),
-    ...(sheet.rowHeights !== undefined && {
-      rowHeights: {
-        ...sheet.rowHeights
-      }
-    }),
-    ...(sheet.defaultColumnWidth !== undefined && {
-      defaultColumnWidth: sheet.defaultColumnWidth
-    }),
-    ...(sheet.defaultRowHeight !== undefined && {
-      defaultRowHeight: sheet.defaultRowHeight
-    })
-  };
+function kindOf(content) {
+  return content?.kind;
+}
+function idOf(content) {
+  return content?.id;
 }
+
 /**
- * A run of one sheet's rows, typed, for a grid that only holds the screens around where it is scrolled to (the rest of a big file is never
- * sent to the browser until it is needed).
+ * The hooks a sample run uses: the ones Studio was started with, except that
  *
- * @param document - The read workbook.
- * @param sheetIndex - Which sheet, 0-based.
- * @param from - The first row, 0-based.
- * @param count - How many rows at most.
- * @returns The rows (fewer at the end of the sheet, none past it).
+ * - a hook the person stubbed returns the stub's value and calls nothing, and
+ * - a hook that calls outside the process says so in the trace, once per call, because it may be slow
+ *   and it may cost money.
+ *
+ * @param hooks - The hooks Studio was started with.
+ * @param stubs - Values to answer with instead of calling a hook, by hook name. A name that is not a hook is ignored.
+ * @param announce - Where the trace lines go.
+ * @returns The hooks to run the sample with.
  */
-function workbookSheetRows(document, sheetIndex, from, count) {
-  const sheet = document.sheets[sheetIndex];
-  if (sheet === undefined) return [];
-  return sheet.rows.slice(from, from + count).map(row => row.map(cell => cellView(cell)));
-}
-function cellView(cell) {
-  return {
-    value: cell,
-    type: cellType(cell)
-  };
-}
-function cellType(cell) {
-  if (typeof cell === 'number') return 'number';
-  if (typeof cell === 'boolean') return 'boolean';
-  return ISO_DATE_OR_TIME.test(cell) ? 'date' : 'string';
-}
-/** `B10:B13` (or a single cell, `A1`) as 0-based inclusive bounds; `undefined` for anything else — mirrors `@opencraw/core`'s own (unexported) `rangeOf`/`cellOf` in `grid-table.algorithm.ts`: a small pure parse, kept here rather than reached for across the package boundary (a sibling slice's non-`index.ts` file is never imported, and this is `@opencraw/core`'s own private helper, not even on its barrel). */
-function rangeOf(reference) {
-  const [from, to = from] = reference.split(':', 2);
-  const start = cellOf(from);
-  const end = cellOf(to);
-  if (start === undefined || end === undefined) return undefined;
-  return {
-    top: Math.min(start.row, end.row),
-    left: Math.min(start.column, end.column),
-    bottom: Math.max(start.row, end.row),
-    right: Math.max(start.column, end.column)
-  };
-}
-function cellOf(reference) {
-  const match = /^\$?([A-Z]+)\$?(\d+)$/i.exec(reference.trim());
-  if (match === null) return undefined;
-  const letters = match[1].toUpperCase();
-  let column = 0;
-  for (const char of letters) column = column * 26 + (char.codePointAt(0) ?? 64) - 64;
-  return {
-    row: Number(match[2]) - 1,
-    column: column - 1
-  };
+function calloutHooks(hooks, stubs, announce) {
+  if (hooks === undefined) return undefined;
+  const prepared = {};
+  for (const [name, hook] of Object.entries(hooks)) {
+    if (stubs !== undefined && Object.hasOwn(stubs, name)) {
+      const stub = stubs[name];
+      prepared[name] = () => {
+        announce(`☎ hook "${name}" is stubbed: answering ${JSON.stringify(stub) ?? 'undefined'} without calling it`);
+        return stub;
+      };
+      continue;
+    }
+    const label = calloutLabel(hook);
+    prepared[name] = label === undefined ? hook : async (input, args, context) => {
+      announce(`☎ hook "${name}" calls ${label} (slow, and it may cost: stub it to skip the call)`);
+      return await hook(input, args, context);
+    };
+  }
+  return prepared;
 }
 
 /**
- * Builds the deck canvas's view model (studio plan §3.4, issue #94's 5d)
- * from an already-read `DeckDocument` (`take-snapshot`'s cached body — no
- * second read of the file): every slide's shapes (with their visual-row
- * grouping, for the text-box-grid pick), native tables (through
- * `workbook-view.mapper.ts`'s own sheet view — a deck table *is* a sheet),
- * charts and notes. Table-specific diagnostics for a `table` extract's own
- * options (the live preview) are not here — they come from
- * `table-preview.use-case.ts`'s `previewDeckTable` instead, computed live as
- * those options change, the same split `pdf-view.mapper.ts`/`workbook-view.mapper.ts`
- * already use.
+ * Runs one input recipe of a workspace folder as a sample: `debug: true` (so
+ * each `record:emit` carries its scope snapshot and mapping trace, and each
+ * `record:reject` its scope), an in-memory sink, and `budget` as the
+ * crawler's `sample` (`@opencraw/core`'s `CrawlOptions.sample`, #89). Every
+ * engine event becomes a trace line with the same `traceLine` formatter the
+ * cli's `--trace` uses; every emitted record reaches `callbacks.onRecord` as
+ * it happens, not only in the final result. Step events (`step:start`,
+ * `step:skip`, `step:retry`) are aggregated by path into `result.steps`, so
+ * `explain-why` (#92) can later say whether the step that bound a mapping's
+ * source id ran, was skipped, or retried — without a second run.
  *
- * @param document - The read deck.
- * @returns The view.
+ * @param folder - The workspace folder the recipe lives in.
+ * @param recipeId - The input recipe to run.
+ * @param budget - The sample budget; unset runs the recipe to completion (still capped by its own `limits`).
+ * @param callbacks - Where trace lines and records go as the run proceeds.
+ * @param browser - Browser launch settings for a web-mode recipe (an executable path override, headless…); the server-wide setting `studio-http.use-case.ts`'s `StudioServerOptions.browser` carries in, e.g. `OPENCRAW_CHROMIUM` in a sandbox with no full Playwright install.
+ * @param plugins - Hooks, access plugins and captcha solvers the person started Studio with (`--hooks`, issue #150); none when it was started without.
+ * @param stubs - Values a hook answers with instead of being called, by hook name, for this run only (issue #201): how a sample skips a slow or paid callout.
+ * @returns A handle: `stop` closes the crawler cleanly, `result` resolves when the run ends.
+ * @throws RecipeValidationError, RecipeBindingError, Error when the recipe or its output cannot be loaded or bound.
  */
-function deckDocumentView(document) {
-  return {
-    width: document.width,
-    height: document.height,
-    slides: document.slides.map(slide => slideView(slide, document.height))
-  };
-}
-function slideView(slide, slideHeight) {
-  return {
-    number: slide.number,
-    ...(slide.title !== undefined && {
-      title: slide.title
-    }),
-    hidden: slide.hidden,
-    shapes: slide.shapes.map(shape => shapeView(shape)),
-    shapeRows: shapeRowsOf(slide.shapes, slideHeight),
-    tables: workbookDocumentView({
-      sheets: slide.tables
-    }).sheets,
-    charts: slide.charts.map(chart => chartView(chart)),
-    notes: slide.notes
-  };
-}
-function shapeView(shape) {
+async function runSample(folder, recipeId, budget, callbacks, browser, plugins, stubs) {
+  const {
+    input,
+    output
+  } = await loadRecipePair(folder, recipeId);
+  const set = bindRecipeSet(output, [input]);
+  const sink = memorySink();
+  const records = [];
+  const rejectedRecords = [];
+  const steps = new Map();
+  const crawler = createCrawler({
+    sink,
+    debug: true,
+    sample: budget,
+    browser,
+    hooks: calloutHooks(plugins?.hooks, stubs, callbacks.onTraceLine),
+    accessPlugins: plugins?.accessPlugins,
+    captchaSolvers: plugins?.captchaSolvers,
+    onEvent: event => {
+      const line = traceLine(event);
+      if (line !== undefined) callbacks.onTraceLine(line);
+      trackStep(steps, event);
+      if (event.type === 'record:emit') {
+        const record = {
+          key: event.key,
+          data: event.data,
+          scope: event.scope,
+          mapping: event.mapping
+        };
+        records.push(record);
+        callbacks.onRecord(record);
+      } else if (event.type === 'record:reject') {
+        const rejected = {
+          field: event.field,
+          reason: event.reason,
+          url: event.url,
+          scope: event.scope
+        };
+        rejectedRecords.push(rejected);
+        callbacks.onRejected?.(rejected);
+      }
+    }
+  });
+  const result = runToResult(crawler, set, recipeId, records, rejectedRecords, steps, plugins);
+  return {
+    stop: () => crawler.close(),
+    result
+  };
+}
+/**
+ * Folds one `step:*` event into `steps`, by path: `skip` always wins over an
+ * earlier `ran`/`retried` outcome for the same path (a step skipped even
+ * once is worth flagging), `retry` wins over a plain `ran`, and a path seen
+ * only as `finish`/`start` (no skip, no retry) settles on `ran`. A `forEach`
+ * runs its body once per item, so the same path folds repeatedly; this is
+ * deliberately a summary across the whole sample, not a per-record trace.
+ */
+function trackStep(steps, event) {
+  if (event.type === 'step:start') {
+    if (!steps.has(event.path)) steps.set(event.path, {
+      path: event.path,
+      stepType: event.stepType,
+      stepId: event.stepId,
+      outcome: 'ran'
+    });
+    return;
+  }
+  if (event.type === 'step:retry') {
+    steps.set(event.path, {
+      path: event.path,
+      stepType: event.stepType,
+      stepId: event.stepId,
+      outcome: 'retried',
+      error: event.error
+    });
+    return;
+  }
+  if (event.type === 'step:skip') {
+    steps.set(event.path, {
+      path: event.path,
+      stepType: event.stepType,
+      stepId: event.stepId,
+      outcome: 'skipped',
+      error: event.error
+    });
+  }
+}
+/**
+ * Awaits the run and shapes its result. A throw from `crawler.run` (an unknown
+ * hook, a recipe that cannot start) becomes the run's `error` instead of a
+ * rejection: nothing awaits `result` but a `.then`, and an unhandled rejection
+ * would take the whole Studio server down (issue #148).
+ */
+async function runToResult(crawler, set, recipeId, records, rejectedRecords, steps, plugins) {
+  try {
+    const report = await crawler.run(set);
+    const recipe = report.recipes[0];
+    return {
+      recipeId: recipe.recipeId,
+      emitted: recipe.emitted,
+      rejected: recipe.rejected,
+      duplicates: recipe.duplicates,
+      durationMs: recipe.durationMs,
+      error: recipe.error,
+      stoppedBy: recipe.stoppedBy,
+      records,
+      rejectedRecords,
+      // eslint-disable-next-line unicorn/prefer-iterator-to-array -- `.toArray()` needs a `lib` newer than this repo's `es2022` (tsconfig.base.json)
+      steps: [...steps.values()]
+    };
+  } catch (error) {
+    return {
+      recipeId,
+      emitted: 0,
+      rejected: 0,
+      duplicates: 0,
+      durationMs: 0,
+      error: failureMessage(error, plugins),
+      records,
+      rejectedRecords,
+      // eslint-disable-next-line unicorn/prefer-iterator-to-array -- `.toArray()` needs a `lib` newer than this repo's `es2022` (tsconfig.base.json)
+      steps: [...steps.values()]
+    };
+  } finally {
+    await crawler.close();
+  }
+}
+/** What a run that could not start reports. A hook is the author's own code, which Studio only runs when it was started with `--hooks` (issue #150): say which case this is, instead of leaving "unknown hook" to read as a typo. */
+function failureMessage(error, plugins) {
+  if (error instanceof UnknownHookError) {
+    const message = stripVTControlCharacters(error.message);
+    if (plugins !== undefined) return `${message}. It is not one of the hooks in ${plugins.source}: ${Object.keys(plugins.hooks).join(', ') || 'none exported'}.`;
+    return `${message}. Studio was started without hooks: restart it with \`opencraw studio --hooks <file>\` (a module you trust; it runs as your code), or temporarily replace the hook step to preview the rest.`;
+  }
+  if (error instanceof Error) return stripVTControlCharacters(error.message);
+  return stripVTControlCharacters(String(error));
+}
+
+/** @returns A fresh, empty cache. */
+function createLastRunCache() {
+  return {
+    entries: new Map()
+  };
+}
+/** Records a finished sample run, replacing whatever this recipe's cache entry held before. */
+function recordLastRun(cache, recipeId, result) {
+  cache.entries.set(recipeId, {
+    recipeId,
+    result
+  });
+}
+/** @returns The recipe's last completed sample run, or `undefined` when none has finished yet. */
+function lastRunOf(cache, recipeId) {
+  return cache.entries.get(recipeId);
+}
+
+/** Where the studio's own recorder profile lives when `StudioServerOptions.recorderProfileDir` is not given: never a crawl's own `session.browserProfile` directory, never the person's default browser profile. */
+function defaultRecorderProfileDir() {
+  return join(tmpdir(), 'opencraw-studio', 'recorder-profile');
+}
+/** @returns Fresh state for a new server instance: no workspace open, no run, no recording, no sockets, an empty snapshot cache, no last runs, Playwright's own default browser, the default recorder profile directory. */
+function createStudioState() {
+  return {
+    sockets: new Set(),
+    uiOutcomes: new Map(),
+    snapshots: createSnapshotCache(),
+    lastRuns: createLastRunCache(),
+    recorderProfileDir: defaultRecorderProfileDir()
+  };
+}
+/**
+ * Sends one event to every connected client. A socket that errors while
+ * sending (gone away without a clean close yet reaching us) is dropped
+ * rather than left to fail every later broadcast too.
+ *
+ * @param state - The server state holding the connected sockets.
+ * @param event - The event to send.
+ */
+function broadcast(state, event) {
+  const text = JSON.stringify(event);
+  for (const socket of state.sockets) {
+    try {
+      socket.send(text);
+    } catch {
+      state.sockets.delete(socket);
+    }
+  }
+}
+
+/** How many outcomes are kept: a controller asks soon after it sent the request, so a few dozen is plenty. */
+const KEPT_OUTCOMES = 50;
+/**
+ * Handles `ask-ui`: tells every open page what a controller (an agent, through the MCP server) asked for, so
+ * the person watching sees it happen. Nothing is done server-side: the page does it the way a click would, and
+ * says how it went (`ui-report`).
+ *
+ * @param state - The server state holding the connected pages.
+ * @param command - What to ask the pages.
+ * @returns How many pages were listening (0 means nobody has Studio open) and the id to ask the outcome with.
+ */
+function handleAskUi(state, command) {
+  const requestId = randomUUID();
+  broadcast(state, {
+    type: 'ui-request',
+    requestId,
+    request: command.request
+  });
+  return {
+    pages: state.sockets.size,
+    requestId
+  };
+}
+/**
+ * Handles `ui-report`: a page says how a controller's request went. The first answer stays: every open page gets the
+ * request, and a page that has nothing to do with it (another recipe open) does not report.
+ *
+ * @param state - The server state.
+ * @param command - The request's id and the outcome.
+ * @returns Whether the report was kept.
+ */
+function handleUiReport(state, command) {
+  if (state.uiOutcomes.has(command.requestId)) return {
+    kept: false
+  };
+  state.uiOutcomes.set(command.requestId, {
+    state: 'done',
+    ok: command.ok,
+    message: command.message,
+    detail: command.detail
+  });
+  const [oldest] = state.uiOutcomes.keys();
+  if (oldest !== undefined && state.uiOutcomes.size > KEPT_OUTCOMES) state.uiOutcomes.delete(oldest);
+  return {
+    kept: true
+  };
+}
+/**
+ * Handles `ui-outcome`: how a controller's request went.
+ *
+ * @param state - The server state.
+ * @param command - The request's id.
+ * @returns `pending` until a page reported, then what it said.
+ */
+function handleUiOutcome(state, command) {
+  return state.uiOutcomes.get(command.requestId) ?? {
+    state: 'pending'
+  };
+}
+
+/** Asks the dialog, and clears `openDialog` once it has answered or failed, so the next request opens a new one. */
+async function askOnce(state, ask) {
+  try {
+    return await ask();
+  } finally {
+    state.openDialog = undefined;
+  }
+}
+/**
+ * Handles `choose-folder`: opens the folder dialog of the machine the server
+ * runs on and answers the folder picked. Only answers: the UI follows with
+ * `open-workspace`, the same as when the folder is typed. A dialog still
+ * open is not opened a second time; the second request waits for the first.
+ *
+ * @param state - The server state holding the dialog to use.
+ * @returns The folder, or none when the dialog was closed.
+ */
+async function handleChooseFolder(state) {
+  if (state.chooseFolder === undefined) throw new Error('this server has no folder dialog: type the folder instead');
+  state.openDialog ??= askOnce(state, state.chooseFolder);
+  const folder = await state.openDialog;
+  return folder === undefined ? {} : {
+    folder
+  };
+}
+
+/** A cell reads as an ISO date (`2026-06-01`), an ISO moment (`2026-06-01T09:30:00`) or a bare time of day (`09:30:00`) — the three shapes `workbook-document`'s `read-xlsx.client.ts` writes for a spreadsheet date. */
+const ISO_DATE_OR_TIME = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2})?$|^\d{2}:\d{2}:\d{2}$/;
+/**
+ * Builds the grid canvas's view model (studio plan §3.4, issue #94's 5c) from
+ * an already-read `WorkbookDocument` (`take-snapshot`'s cached body — no
+ * second read of the file): every sheet's cells, typed, with hidden sheets
+ * and rows marked, and merged ranges resolved to bounds so the grid draws
+ * them as one cell. Table-specific diagnostics (the matched rows of the
+ * current `table` extract's options) are not here — they depend on the
+ * picks so far, so they come from `table-preview.use-case.ts`'s
+ * `previewGridTable` instead, computed live as those options change.
+ *
+ * @param document - The read workbook (a spreadsheet or a CSV).
+ * @returns The view.
+ */
+function workbookDocumentView(document, options = {}) {
+  return {
+    sheets: document.sheets.map(sheet => sheetView(sheet, options.windowRows)),
+    ...(document.csv !== undefined && {
+      csv: document.csv
+    })
+  };
+}
+function sheetView(sheet, windowRows) {
+  const windowed = windowRows !== undefined && sheet.rows.length > windowRows;
+  return {
+    name: sheet.name,
+    hidden: sheet.hidden === true,
+    hiddenRows: sheet.hiddenRows === undefined ? [] : [...sheet.hiddenRows],
+    // Not `Math.max(...lengths)`: a spread of a few hundred thousand rows overflows the call stack.
+    columnCount: sheet.rows.reduce((widest, row) => Math.max(widest, row.length), 0),
+    rows: (windowed ? sheet.rows.slice(0, windowRows) : sheet.rows).map(row => row.map(cell => cellView(cell))),
+    ...(windowed && {
+      rowCount: sheet.rows.length
+    }),
+    merges: (sheet.merges ?? []).flatMap(reference => {
+      const range = rangeOf(reference);
+      return range === undefined ? [] : [{
+        ref: reference,
+        ...range
+      }];
+    }),
+    ...(sheet.columnWidths !== undefined && {
+      columnWidths: {
+        ...sheet.columnWidths
+      }
+    }),
+    ...(sheet.rowHeights !== undefined && {
+      rowHeights: {
+        ...sheet.rowHeights
+      }
+    }),
+    ...(sheet.defaultColumnWidth !== undefined && {
+      defaultColumnWidth: sheet.defaultColumnWidth
+    }),
+    ...(sheet.defaultRowHeight !== undefined && {
+      defaultRowHeight: sheet.defaultRowHeight
+    })
+  };
+}
+/**
+ * A run of one sheet's rows, typed, for a grid that only holds the screens around where it is scrolled to (the rest of a big file is never
+ * sent to the browser until it is needed).
+ *
+ * @param document - The read workbook.
+ * @param sheetIndex - Which sheet, 0-based.
+ * @param from - The first row, 0-based.
+ * @param count - How many rows at most.
+ * @returns The rows (fewer at the end of the sheet, none past it).
+ */
+function workbookSheetRows(document, sheetIndex, from, count) {
+  const sheet = document.sheets[sheetIndex];
+  if (sheet === undefined) return [];
+  return sheet.rows.slice(from, from + count).map(row => row.map(cell => cellView(cell)));
+}
+function cellView(cell) {
+  return {
+    value: cell,
+    type: cellType(cell)
+  };
+}
+function cellType(cell) {
+  if (typeof cell === 'number') return 'number';
+  if (typeof cell === 'boolean') return 'boolean';
+  return ISO_DATE_OR_TIME.test(cell) ? 'date' : 'string';
+}
+/** `B10:B13` (or a single cell, `A1`) as 0-based inclusive bounds; `undefined` for anything else — mirrors `@opencraw/core`'s own (unexported) `rangeOf`/`cellOf` in `grid-table.algorithm.ts`: a small pure parse, kept here rather than reached for across the package boundary (a sibling slice's non-`index.ts` file is never imported, and this is `@opencraw/core`'s own private helper, not even on its barrel). */
+function rangeOf(reference) {
+  const [from, to = from] = reference.split(':', 2);
+  const start = cellOf(from);
+  const end = cellOf(to);
+  if (start === undefined || end === undefined) return undefined;
+  return {
+    top: Math.min(start.row, end.row),
+    left: Math.min(start.column, end.column),
+    bottom: Math.max(start.row, end.row),
+    right: Math.max(start.column, end.column)
+  };
+}
+function cellOf(reference) {
+  const match = /^\$?([A-Z]+)\$?(\d+)$/i.exec(reference.trim());
+  if (match === null) return undefined;
+  const letters = match[1].toUpperCase();
+  let column = 0;
+  for (const char of letters) column = column * 26 + (char.codePointAt(0) ?? 64) - 64;
+  return {
+    row: Number(match[2]) - 1,
+    column: column - 1
+  };
+}
+
+/**
+ * Builds the deck canvas's view model (studio plan §3.4, issue #94's 5d)
+ * from an already-read `DeckDocument` (`take-snapshot`'s cached body — no
+ * second read of the file): every slide's shapes (with their visual-row
+ * grouping, for the text-box-grid pick), native tables (through
+ * `workbook-view.mapper.ts`'s own sheet view — a deck table *is* a sheet),
+ * charts and notes. Table-specific diagnostics for a `table` extract's own
+ * options (the live preview) are not here — they come from
+ * `table-preview.use-case.ts`'s `previewDeckTable` instead, computed live as
+ * those options change, the same split `pdf-view.mapper.ts`/`workbook-view.mapper.ts`
+ * already use.
+ *
+ * @param document - The read deck.
+ * @returns The view.
+ */
+function deckDocumentView(document) {
+  return {
+    width: document.width,
+    height: document.height,
+    slides: document.slides.map(slide => slideView(slide, document.height))
+  };
+}
+function slideView(slide, slideHeight) {
+  return {
+    number: slide.number,
+    ...(slide.title !== undefined && {
+      title: slide.title
+    }),
+    hidden: slide.hidden,
+    shapes: slide.shapes.map(shape => shapeView(shape)),
+    shapeRows: shapeRowsOf(slide.shapes, slideHeight),
+    tables: workbookDocumentView({
+      sheets: slide.tables
+    }).sheets,
+    charts: slide.charts.map(chart => chartView(chart)),
+    notes: slide.notes
+  };
+}
+function shapeView(shape) {
   return {
     x: shape.x,
     y: shape.y,
@@ -2405,499 +2868,259 @@ function pdfDocumentView(document) {
         ...(margins.has(row) && {
           running: true
         })
-      })),
-      rowCount: page.rows.length,
-      cellCount: page.rows.reduce((total, row) => total + row.cells.length, 0),
-      hasTextLayer: page.rows.length > 0
-    }))
-  };
-}
-
-/**
- * Runs a `table` extract's options against an already-read PDF (studio plan
- * §3.4, issue #94's 5b: the live preview) — a pure function of the document
- * and the options, so re-running it on every keystroke as the person edits
- * `selector`/`until`/`columns` costs nothing: no re-fetch, no re-parse
- * (`readPdf` already ran once, when `take-snapshot` captured the document).
- *
- * The workbook grid's live preview (issue #94's 5c) is `previewGridTable`,
- * below: the same idea (a pure re-run of the options against the cached
- * document), but its own result shape — a workbook table has no page, no
- * column bands, no wrapped-row regrouping, so folding it into
- * `TablePreviewMatch`/`TablePreviewResult` would leave most of those fields
- * meaningless for a grid pick; a `GridTablePreviewMatch`/`GridTablePreviewResult`
- * sibling reads honestly instead.
- *
- * @param document - The already-read PDF.
- * @param options - The `table` extract's options, not yet compiled to `RegExp`.
- * @returns Every match, each with the exact row indices to highlight — or `error` (and no matches) when a pattern is not a valid regular expression, expected while the person is still typing it.
- */
-function previewPdfTable(document, options) {
-  let query;
-  try {
-    query = {
-      header: compile(options.header, 'selector'),
-      until: options.until === undefined ? undefined : compile(options.until, 'until'),
-      columns: options.columns === undefined ? undefined : Object.fromEntries(Object.entries(options.columns).map(([key, pattern]) => [key, compile(pattern, `columns.${key}`)])),
-      align: options.align
-    };
-  } catch (error) {
-    return {
-      matches: [],
-      error: error instanceof Error ? error.message : String(error)
-    };
-  }
-  const analyses = analyzeTables(document, query);
-  return {
-    matches: analyses.map(analysis => ({
-      page: analysis.page,
-      headerRowIndex: analysis.headerRowIndex,
-      matchedRowIndices: rowIndicesOf(analysis),
-      bands: analysis.bands,
-      bandTolerance: analysis.bandTolerance,
-      table: analysis.table
-    }))
-  };
-}
-function rowIndicesOf(analysis) {
-  const indices = new Set([analysis.headerRowIndex, ...analysis.rowGroups.flat()]);
-  if (analysis.untilRowIndex !== undefined) indices.add(analysis.untilRowIndex);
-  return [...indices].sort((a, b) => a - b);
-}
-function compile(source, where) {
-  try {
-    return new RegExp(source, 'i');
-  } catch (error) {
-    throw new Error(`${where}: invalid pattern ${source} (${error.message})`, {
-      cause: error
-    });
-  }
-}
-/**
- * Runs a `table` extract's options against an already-read workbook (studio
- * plan §3.4, issue #94's 5c: the live preview) — a pure function of the
- * document and the options, exactly like `previewPdfTable` above: no
- * re-fetch, no re-parse (`csvWorkbook`/`readXlsxWorkbook` already ran once,
- * when `take-snapshot` captured the document).
- *
- * @param document - The already-read workbook.
- * @param options - The `table` extract's options, not yet compiled to `RegExp`.
- * @returns Every matched table — or `error` (and no matches) when a pattern is not a valid regular expression, expected while the person is still typing it.
- */
-function previewGridTable(document, options) {
-  let query;
-  try {
-    query = {
-      header: compile(options.header, 'selector'),
-      until: options.until === undefined ? undefined : compile(options.until, 'until'),
-      columns: options.columns === undefined ? undefined : Object.fromEntries(Object.entries(options.columns).map(([key, pattern]) => [key, compile(pattern, `columns.${key}`)])),
-      sheet: options.sheet === undefined ? undefined : compile(options.sheet, 'sheet'),
-      headerRows: options.headerRows,
-      fillDown: options.fillDown,
-      includeHidden: options.includeHidden
-    };
-  } catch (error) {
-    return {
-      matches: [],
-      error: error instanceof Error ? error.message : String(error)
-    };
-  }
-  const tables = findGridTables(document, query);
-  return {
-    matches: tables.map(table => ({
-      sheet: table.sheet,
-      title: table.title,
-      header: table.header,
-      rows: table.rows
-    }))
-  };
-}
-/**
- * Runs a `table` extract's options against an already-read deck (studio plan
- * §3.4, issue #94's 5d: the live preview) — a pure function of the document
- * and the options, exactly like `previewPdfTable`/`previewGridTable` above:
- * no re-fetch, no re-parse (`readPptxDeck` already ran once, when
- * `take-snapshot` captured the document).
- *
- * @param document - The already-read deck.
- * @param options - The `table` extract's options, not yet compiled to `RegExp`.
- * @returns Every matched table — or `error` (and no matches) when a pattern is not a valid regular expression, expected while the person is still typing it.
- */
-function previewDeckTable(document, options) {
-  let query;
-  try {
-    query = {
-      slide: options.slide === undefined ? undefined : compile(options.slide, 'slide'),
-      shapes: options.shapes,
-      align: options.align,
-      header: compile(options.header, 'selector'),
-      until: options.until === undefined ? undefined : compile(options.until, 'until'),
-      columns: options.columns === undefined ? undefined : Object.fromEntries(Object.entries(options.columns).map(([key, pattern]) => [key, compile(pattern, `columns.${key}`)])),
-      headerRows: options.headerRows,
-      fillDown: options.fillDown,
-      includeHidden: options.includeHidden
-    };
-  } catch (error) {
-    return {
-      matches: [],
-      error: error instanceof Error ? error.message : String(error)
-    };
-  }
-  const tables = findDeckTables(document, query);
-  return {
-    matches: tables.map(table => ({
-      slide: table.slide,
-      slideTitle: table.slideTitle,
-      title: table.title,
-      header: table.header,
-      rows: table.rows
-    }))
-  };
-}
-
-/**
- * Runs a `region` extract's selector against an already-read PDF or deck
- * (issues #121 and #122: the canvases' click-to-snap selection) — the
- * engine's own `regionText` / `deckRegionText`, so what the canvas
- * highlights and the text it shows are exactly what the step will read,
- * and a pure function of the document, so re-running it on every change
- * of the box costs nothing. A `slide=` on a PDF (or a `page=` on a deck)
- * is the same mismatch the step would fail with, reported as `error`.
- *
- * @param document - The read PDF or deck (`take-snapshot`'s cached body).
- * @param selector - The `region` selector, `page=1 x=72..252 y=640..664` or `slide=2 x=60..900 y=30..90`.
- * @returns The matches, or `error` when the selector does not parse or does not fit the document.
- */
-function previewRegion(document, selector) {
-  try {
-    const region = parseRegion(selector);
-    if (document.kind === 'pdf') {
-      if (region.on !== 'page') return {
-        matches: [],
-        error: 'region: "slide=" reads a deck; this document is a PDF (name a "page=")'
-      };
-      return {
-        matches: regionText(document, region).map(match => ({
-          page: match.page,
-          text: match.text,
-          cells: match.cells,
-          shapes: []
-        }))
-      };
-    }
-    if (region.on !== 'slide') return {
-      matches: [],
-      error: 'region: "page=" reads a PDF; this document is a deck (name a "slide=")'
-    };
-    return {
-      matches: deckRegionText(document, region).map(match => ({
-        page: match.slide,
-        text: match.text,
-        cells: [],
-        shapes: match.shapes
-      }))
-    };
-  } catch (error) {
-    return {
-      matches: [],
-      error: error instanceof Error ? error.message : String(error)
-    };
-  }
-}
-
-/**
- * Handles `deck-preview`: the deck canvas's live preview of a `table`
- * extract's options (`document-view`'s `table-preview.use-case.ts`'s
- * `previewDeckTable`, studio plan §3.4, issue #94's 5d), off the same cached
- * snapshot `take-snapshot`/`deck-view` already captured — a pure computation
- * over it, so this answers instantly on every option change, no re-fetch or
- * re-parse.
- *
- * @param state - The server state.
- * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
- * @returns The matched tables, or `error` when an option's pattern does not compile.
- * @throws Error when no workspace is open, or `command.path` has no cached snapshot yet.
- */
-function handleDeckPreview(state, command) {
-  const snapshot = cachedSnapshot(state.snapshots, command.recipeId, command.path);
-  if (snapshot === undefined) throw new Error(`no cached snapshot for "${command.recipeId}" at "${command.path}": call take-snapshot first`);
-  if (!isDeckDocument(snapshot.body)) throw new Error(`"${command.recipeId}" at "${command.path}" is not a deck snapshot: deck-preview only reads a read PowerPoint document`);
-  return previewDeckTable(snapshot.body, command.options);
-}
-
-/**
- * Handles `deck-view`: the deck canvas's slides, shapes, tables, charts and
- * notes (`document-view`'s `deck-view.mapper.ts`, studio plan §3.4, issue
- * #94's 5d), off the same cached snapshot `take-snapshot`/`document-tree`
- * already use.
- *
- * @param state - The server state.
- * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
- * @returns The document's view.
- * @throws Error when no workspace is open, `command.path` has no cached snapshot yet, or the snapshot's document is not a read deck.
- */
-function handleDeckView(state, command) {
-  const snapshot = cachedSnapshot(state.snapshots, command.recipeId, command.path);
-  if (snapshot === undefined) throw new Error(`no cached snapshot for "${command.recipeId}" at "${command.path}": call take-snapshot first`);
-  if (!isDeckDocument(snapshot.body)) throw new Error(`"${command.recipeId}" at "${command.path}" is not a deck snapshot: the deck canvas only reads a read PowerPoint document`);
-  return deckDocumentView(snapshot.body);
+      })),
+      rowCount: page.rows.length,
+      cellCount: page.rows.reduce((total, row) => total + row.cells.length, 0),
+      hasTextLayer: page.rows.length > 0
+    }))
+  };
 }
 
 /**
- * Handles `document-tree`: the content pane's tree canvas for a JSON, YAML
- * or XML document (`document-view`, studio plan §3.4, issue #94's 5a), off
- * the same cached snapshot `take-snapshot`/`inspect-page` already use.
+ * Runs a `table` extract's options against an already-read PDF (studio plan
+ * §3.4, issue #94's 5b: the live preview) — a pure function of the document
+ * and the options, so re-running it on every keystroke as the person edits
+ * `selector`/`until`/`columns` costs nothing: no re-fetch, no re-parse
+ * (`readPdf` already ran once, when `take-snapshot` captured the document).
  *
- * @param state - The server state.
- * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
- * @returns The tree.
- * @throws Error when no workspace is open, `command.path` has no cached snapshot yet, or the snapshot's document is not JSON/YAML/XML (no parsed body at all in web mode; PDF/workbook/deck in api mode — see `documentTreeView`'s own doc comment).
- */
-function handleDocumentTree(state, command) {
-  const snapshot = cachedSnapshot(state.snapshots, command.recipeId, command.path);
-  if (snapshot === undefined) throw new Error(`no cached snapshot for "${command.recipeId}" at "${command.path}": call take-snapshot first`);
-  if (snapshot.body === undefined) throw new Error(`"${command.recipeId}" at "${command.path}" is a web-mode (HTML) snapshot: the tree canvas only reads a JSON/YAML/XML document`);
-  return documentTreeView(snapshot.body);
-}
-
-/**
- * Finds and parses one input recipe of a workspace folder, and the output
- * recipe it names.
+ * The workbook grid's live preview (issue #94's 5c) is `previewGridTable`,
+ * below: the same idea (a pure re-run of the options against the cached
+ * document), but its own result shape — a workbook table has no page, no
+ * column bands, no wrapped-row regrouping, so folding it into
+ * `TablePreviewMatch`/`TablePreviewResult` would leave most of those fields
+ * meaningless for a grid pick; a `GridTablePreviewMatch`/`GridTablePreviewResult`
+ * sibling reads honestly instead.
  *
- * @param folder - The workspace folder.
- * @param recipeId - The input recipe's id.
- * @returns The parsed pair.
- * @throws RecipeValidationError when either recipe does not parse.
- * @throws Error when the input or its output is not in the folder.
+ * @param document - The already-read PDF.
+ * @param options - The `table` extract's options, not yet compiled to `RegExp`.
+ * @returns Every match, each with the exact row indices to highlight — or `error` (and no matches) when a pattern is not a valid regular expression, expected while the person is still typing it.
  */
-async function loadRecipePair(folder, recipeId) {
-  const documents = await readRecipeSource(folder);
-  const inputDocument = documents.find(document => kindOf(document.content) === 'input' && idOf(document.content) === recipeId);
-  if (inputDocument === undefined) throw new Error(`no input recipe "${recipeId}" in this workspace`);
-  const input = parseInputRecipe(inputDocument.content, inputDocument.source);
-  const outputDocument = documents.find(document => kindOf(document.content) === 'output' && idOf(document.content) === input.output);
-  if (outputDocument === undefined) throw new Error(`no output recipe "${input.output}" in this workspace`);
+function previewPdfTable(document, options) {
+  let query;
+  try {
+    query = {
+      header: compile(options.header, 'selector'),
+      until: options.until === undefined ? undefined : compile(options.until, 'until'),
+      columns: options.columns === undefined ? undefined : Object.fromEntries(Object.entries(options.columns).map(([key, pattern]) => [key, compile(pattern, `columns.${key}`)])),
+      align: options.align
+    };
+  } catch (error) {
+    return {
+      matches: [],
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+  const analyses = analyzeTables(document, query);
   return {
-    input,
-    output: parseOutputRecipe(outputDocument.content, outputDocument.source)
+    matches: analyses.map(analysis => ({
+      page: analysis.page,
+      headerRowIndex: analysis.headerRowIndex,
+      matchedRowIndices: rowIndicesOf(analysis),
+      bands: analysis.bands,
+      bandTolerance: analysis.bandTolerance,
+      table: analysis.table
+    }))
   };
 }
-function kindOf(content) {
-  return content?.kind;
+function rowIndicesOf(analysis) {
+  const indices = new Set([analysis.headerRowIndex, ...analysis.rowGroups.flat()]);
+  if (analysis.untilRowIndex !== undefined) indices.add(analysis.untilRowIndex);
+  return [...indices].sort((a, b) => a - b);
 }
-function idOf(content) {
-  return content?.id;
+function compile(source, where) {
+  try {
+    return new RegExp(source, 'i');
+  } catch (error) {
+    throw new Error(`${where}: invalid pattern ${source} (${error.message})`, {
+      cause: error
+    });
+  }
 }
-
 /**
- * The hooks a sample run uses: the ones Studio was started with, except that
- *
- * - a hook the person stubbed returns the stub's value and calls nothing, and
- * - a hook that calls outside the process says so in the trace, once per call, because it may be slow
- *   and it may cost money.
+ * Runs a `table` extract's options against an already-read workbook (studio
+ * plan §3.4, issue #94's 5c: the live preview) — a pure function of the
+ * document and the options, exactly like `previewPdfTable` above: no
+ * re-fetch, no re-parse (`csvWorkbook`/`readXlsxWorkbook` already ran once,
+ * when `take-snapshot` captured the document).
  *
- * @param hooks - The hooks Studio was started with.
- * @param stubs - Values to answer with instead of calling a hook, by hook name. A name that is not a hook is ignored.
- * @param announce - Where the trace lines go.
- * @returns The hooks to run the sample with.
+ * @param document - The already-read workbook.
+ * @param options - The `table` extract's options, not yet compiled to `RegExp`.
+ * @returns Every matched table — or `error` (and no matches) when a pattern is not a valid regular expression, expected while the person is still typing it.
  */
-function calloutHooks(hooks, stubs, announce) {
-  if (hooks === undefined) return undefined;
-  const prepared = {};
-  for (const [name, hook] of Object.entries(hooks)) {
-    if (stubs !== undefined && Object.hasOwn(stubs, name)) {
-      const stub = stubs[name];
-      prepared[name] = () => {
-        announce(`☎ hook "${name}" is stubbed: answering ${JSON.stringify(stub) ?? 'undefined'} without calling it`);
-        return stub;
-      };
-      continue;
-    }
-    const label = calloutLabel(hook);
-    prepared[name] = label === undefined ? hook : async (input, args, context) => {
-      announce(`☎ hook "${name}" calls ${label} (slow, and it may cost: stub it to skip the call)`);
-      return await hook(input, args, context);
+function previewGridTable(document, options) {
+  let query;
+  try {
+    query = {
+      header: compile(options.header, 'selector'),
+      until: options.until === undefined ? undefined : compile(options.until, 'until'),
+      columns: options.columns === undefined ? undefined : Object.fromEntries(Object.entries(options.columns).map(([key, pattern]) => [key, compile(pattern, `columns.${key}`)])),
+      sheet: options.sheet === undefined ? undefined : compile(options.sheet, 'sheet'),
+      headerRows: options.headerRows,
+      fillDown: options.fillDown,
+      includeHidden: options.includeHidden
+    };
+  } catch (error) {
+    return {
+      matches: [],
+      error: error instanceof Error ? error.message : String(error)
     };
   }
-  return prepared;
-}
-
-/**
- * Runs one input recipe of a workspace folder as a sample: `debug: true` (so
- * each `record:emit` carries its scope snapshot and mapping trace, and each
- * `record:reject` its scope), an in-memory sink, and `budget` as the
- * crawler's `sample` (`@opencraw/core`'s `CrawlOptions.sample`, #89). Every
- * engine event becomes a trace line with the same `traceLine` formatter the
- * cli's `--trace` uses; every emitted record reaches `callbacks.onRecord` as
- * it happens, not only in the final result. Step events (`step:start`,
- * `step:skip`, `step:retry`) are aggregated by path into `result.steps`, so
- * `explain-why` (#92) can later say whether the step that bound a mapping's
- * source id ran, was skipped, or retried — without a second run.
- *
- * @param folder - The workspace folder the recipe lives in.
- * @param recipeId - The input recipe to run.
- * @param budget - The sample budget; unset runs the recipe to completion (still capped by its own `limits`).
- * @param callbacks - Where trace lines and records go as the run proceeds.
- * @param browser - Browser launch settings for a web-mode recipe (an executable path override, headless…); the server-wide setting `studio-http.use-case.ts`'s `StudioServerOptions.browser` carries in, e.g. `OPENCRAW_CHROMIUM` in a sandbox with no full Playwright install.
- * @param plugins - Hooks, access plugins and captcha solvers the person started Studio with (`--hooks`, issue #150); none when it was started without.
- * @param stubs - Values a hook answers with instead of being called, by hook name, for this run only (issue #201): how a sample skips a slow or paid callout.
- * @returns A handle: `stop` closes the crawler cleanly, `result` resolves when the run ends.
- * @throws RecipeValidationError, RecipeBindingError, Error when the recipe or its output cannot be loaded or bound.
- */
-async function runSample(folder, recipeId, budget, callbacks, browser, plugins, stubs) {
-  const {
-    input,
-    output
-  } = await loadRecipePair(folder, recipeId);
-  const set = bindRecipeSet(output, [input]);
-  const sink = memorySink();
-  const records = [];
-  const rejectedRecords = [];
-  const steps = new Map();
-  const crawler = createCrawler({
-    sink,
-    debug: true,
-    sample: budget,
-    browser,
-    hooks: calloutHooks(plugins?.hooks, stubs, callbacks.onTraceLine),
-    accessPlugins: plugins?.accessPlugins,
-    captchaSolvers: plugins?.captchaSolvers,
-    onEvent: event => {
-      const line = traceLine(event);
-      if (line !== undefined) callbacks.onTraceLine(line);
-      trackStep(steps, event);
-      if (event.type === 'record:emit') {
-        const record = {
-          key: event.key,
-          data: event.data,
-          scope: event.scope,
-          mapping: event.mapping
-        };
-        records.push(record);
-        callbacks.onRecord(record);
-      } else if (event.type === 'record:reject') {
-        const rejected = {
-          field: event.field,
-          reason: event.reason,
-          url: event.url,
-          scope: event.scope
-        };
-        rejectedRecords.push(rejected);
-        callbacks.onRejected?.(rejected);
-      }
-    }
-  });
-  const result = runToResult(crawler, set, recipeId, records, rejectedRecords, steps, plugins);
+  const tables = findGridTables(document, query);
   return {
-    stop: () => crawler.close(),
-    result
+    matches: tables.map(table => ({
+      sheet: table.sheet,
+      title: table.title,
+      header: table.header,
+      rows: table.rows
+    }))
   };
 }
 /**
- * Folds one `step:*` event into `steps`, by path: `skip` always wins over an
- * earlier `ran`/`retried` outcome for the same path (a step skipped even
- * once is worth flagging), `retry` wins over a plain `ran`, and a path seen
- * only as `finish`/`start` (no skip, no retry) settles on `ran`. A `forEach`
- * runs its body once per item, so the same path folds repeatedly; this is
- * deliberately a summary across the whole sample, not a per-record trace.
- */
-function trackStep(steps, event) {
-  if (event.type === 'step:start') {
-    if (!steps.has(event.path)) steps.set(event.path, {
-      path: event.path,
-      stepType: event.stepType,
-      stepId: event.stepId,
-      outcome: 'ran'
-    });
-    return;
-  }
-  if (event.type === 'step:retry') {
-    steps.set(event.path, {
-      path: event.path,
-      stepType: event.stepType,
-      stepId: event.stepId,
-      outcome: 'retried',
-      error: event.error
-    });
-    return;
-  }
-  if (event.type === 'step:skip') {
-    steps.set(event.path, {
-      path: event.path,
-      stepType: event.stepType,
-      stepId: event.stepId,
-      outcome: 'skipped',
-      error: event.error
-    });
+ * Runs a `table` extract's options against an already-read deck (studio plan
+ * §3.4, issue #94's 5d: the live preview) — a pure function of the document
+ * and the options, exactly like `previewPdfTable`/`previewGridTable` above:
+ * no re-fetch, no re-parse (`readPptxDeck` already ran once, when
+ * `take-snapshot` captured the document).
+ *
+ * @param document - The already-read deck.
+ * @param options - The `table` extract's options, not yet compiled to `RegExp`.
+ * @returns Every matched table — or `error` (and no matches) when a pattern is not a valid regular expression, expected while the person is still typing it.
+ */
+function previewDeckTable(document, options) {
+  let query;
+  try {
+    query = {
+      slide: options.slide === undefined ? undefined : compile(options.slide, 'slide'),
+      shapes: options.shapes,
+      align: options.align,
+      header: compile(options.header, 'selector'),
+      until: options.until === undefined ? undefined : compile(options.until, 'until'),
+      columns: options.columns === undefined ? undefined : Object.fromEntries(Object.entries(options.columns).map(([key, pattern]) => [key, compile(pattern, `columns.${key}`)])),
+      headerRows: options.headerRows,
+      fillDown: options.fillDown,
+      includeHidden: options.includeHidden
+    };
+  } catch (error) {
+    return {
+      matches: [],
+      error: error instanceof Error ? error.message : String(error)
+    };
   }
+  const tables = findDeckTables(document, query);
+  return {
+    matches: tables.map(table => ({
+      slide: table.slide,
+      slideTitle: table.slideTitle,
+      title: table.title,
+      header: table.header,
+      rows: table.rows
+    }))
+  };
 }
+
 /**
- * Awaits the run and shapes its result. A throw from `crawler.run` (an unknown
- * hook, a recipe that cannot start) becomes the run's `error` instead of a
- * rejection: nothing awaits `result` but a `.then`, and an unhandled rejection
- * would take the whole Studio server down (issue #148).
+ * Runs a `region` extract's selector against an already-read PDF or deck
+ * (issues #121 and #122: the canvases' click-to-snap selection) — the
+ * engine's own `regionText` / `deckRegionText`, so what the canvas
+ * highlights and the text it shows are exactly what the step will read,
+ * and a pure function of the document, so re-running it on every change
+ * of the box costs nothing. A `slide=` on a PDF (or a `page=` on a deck)
+ * is the same mismatch the step would fail with, reported as `error`.
+ *
+ * @param document - The read PDF or deck (`take-snapshot`'s cached body).
+ * @param selector - The `region` selector, `page=1 x=72..252 y=640..664` or `slide=2 x=60..900 y=30..90`.
+ * @returns The matches, or `error` when the selector does not parse or does not fit the document.
  */
-async function runToResult(crawler, set, recipeId, records, rejectedRecords, steps, plugins) {
+function previewRegion(document, selector) {
   try {
-    const report = await crawler.run(set);
-    const recipe = report.recipes[0];
+    const region = parseRegion(selector);
+    if (document.kind === 'pdf') {
+      if (region.on !== 'page') return {
+        matches: [],
+        error: 'region: "slide=" reads a deck; this document is a PDF (name a "page=")'
+      };
+      return {
+        matches: regionText(document, region).map(match => ({
+          page: match.page,
+          text: match.text,
+          cells: match.cells,
+          shapes: []
+        }))
+      };
+    }
+    if (region.on !== 'slide') return {
+      matches: [],
+      error: 'region: "page=" reads a PDF; this document is a deck (name a "slide=")'
+    };
     return {
-      recipeId: recipe.recipeId,
-      emitted: recipe.emitted,
-      rejected: recipe.rejected,
-      duplicates: recipe.duplicates,
-      durationMs: recipe.durationMs,
-      error: recipe.error,
-      stoppedBy: recipe.stoppedBy,
-      records,
-      rejectedRecords,
-      // eslint-disable-next-line unicorn/prefer-iterator-to-array -- `.toArray()` needs a `lib` newer than this repo's `es2022` (tsconfig.base.json)
-      steps: [...steps.values()]
+      matches: deckRegionText(document, region).map(match => ({
+        page: match.slide,
+        text: match.text,
+        cells: [],
+        shapes: match.shapes
+      }))
     };
   } catch (error) {
     return {
-      recipeId,
-      emitted: 0,
-      rejected: 0,
-      duplicates: 0,
-      durationMs: 0,
-      error: failureMessage(error, plugins),
-      records,
-      rejectedRecords,
-      // eslint-disable-next-line unicorn/prefer-iterator-to-array -- `.toArray()` needs a `lib` newer than this repo's `es2022` (tsconfig.base.json)
-      steps: [...steps.values()]
+      matches: [],
+      error: error instanceof Error ? error.message : String(error)
     };
-  } finally {
-    await crawler.close();
-  }
-}
-/** What a run that could not start reports. A hook is the author's own code, which Studio only runs when it was started with `--hooks` (issue #150): say which case this is, instead of leaving "unknown hook" to read as a typo. */
-function failureMessage(error, plugins) {
-  if (error instanceof UnknownHookError) {
-    const message = stripVTControlCharacters(error.message);
-    if (plugins !== undefined) return `${message}. It is not one of the hooks in ${plugins.source}: ${Object.keys(plugins.hooks).join(', ') || 'none exported'}.`;
-    return `${message}. Studio was started without hooks: restart it with \`opencraw studio --hooks <file>\` (a module you trust; it runs as your code), or temporarily replace the hook step to preview the rest.`;
   }
-  if (error instanceof Error) return stripVTControlCharacters(error.message);
-  return stripVTControlCharacters(String(error));
 }
 
-/** @returns A fresh, empty cache. */
-function createLastRunCache() {
-  return {
-    entries: new Map()
-  };
+/**
+ * Handles `deck-preview`: the deck canvas's live preview of a `table`
+ * extract's options (`document-view`'s `table-preview.use-case.ts`'s
+ * `previewDeckTable`, studio plan §3.4, issue #94's 5d), off the same cached
+ * snapshot `take-snapshot`/`deck-view` already captured — a pure computation
+ * over it, so this answers instantly on every option change, no re-fetch or
+ * re-parse.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The matched tables, or `error` when an option's pattern does not compile.
+ * @throws Error when no workspace is open, or `command.path` has no cached snapshot yet.
+ */
+function handleDeckPreview(state, command) {
+  const snapshot = cachedSnapshot(state.snapshots, command.recipeId, command.path);
+  if (snapshot === undefined) throw new Error(`no cached snapshot for "${command.recipeId}" at "${command.path}": call take-snapshot first`);
+  if (!isDeckDocument(snapshot.body)) throw new Error(`"${command.recipeId}" at "${command.path}" is not a deck snapshot: deck-preview only reads a read PowerPoint document`);
+  return previewDeckTable(snapshot.body, command.options);
 }
-/** Records a finished sample run, replacing whatever this recipe's cache entry held before. */
-function recordLastRun(cache, recipeId, result) {
-  cache.entries.set(recipeId, {
-    recipeId,
-    result
-  });
+
+/**
+ * Handles `deck-view`: the deck canvas's slides, shapes, tables, charts and
+ * notes (`document-view`'s `deck-view.mapper.ts`, studio plan §3.4, issue
+ * #94's 5d), off the same cached snapshot `take-snapshot`/`document-tree`
+ * already use.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The document's view.
+ * @throws Error when no workspace is open, `command.path` has no cached snapshot yet, or the snapshot's document is not a read deck.
+ */
+function handleDeckView(state, command) {
+  const snapshot = cachedSnapshot(state.snapshots, command.recipeId, command.path);
+  if (snapshot === undefined) throw new Error(`no cached snapshot for "${command.recipeId}" at "${command.path}": call take-snapshot first`);
+  if (!isDeckDocument(snapshot.body)) throw new Error(`"${command.recipeId}" at "${command.path}" is not a deck snapshot: the deck canvas only reads a read PowerPoint document`);
+  return deckDocumentView(snapshot.body);
 }
-/** @returns The recipe's last completed sample run, or `undefined` when none has finished yet. */
-function lastRunOf(cache, recipeId) {
-  return cache.entries.get(recipeId);
+
+/**
+ * Handles `document-tree`: the content pane's tree canvas for a JSON, YAML
+ * or XML document (`document-view`, studio plan §3.4, issue #94's 5a), off
+ * the same cached snapshot `take-snapshot`/`inspect-page` already use.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The tree.
+ * @throws Error when no workspace is open, `command.path` has no cached snapshot yet, or the snapshot's document is not JSON/YAML/XML (no parsed body at all in web mode; PDF/workbook/deck in api mode — see `documentTreeView`'s own doc comment).
+ */
+function handleDocumentTree(state, command) {
+  const snapshot = cachedSnapshot(state.snapshots, command.recipeId, command.path);
+  if (snapshot === undefined) throw new Error(`no cached snapshot for "${command.recipeId}" at "${command.path}": call take-snapshot first`);
+  if (snapshot.body === undefined) throw new Error(`"${command.recipeId}" at "${command.path}" is a web-mode (HTML) snapshot: the tree canvas only reads a JSON/YAML/XML document`);
+  return documentTreeView(snapshot.body);
 }
 
 /**
@@ -4835,38 +5058,6 @@ function remoteCallouts(plugins) {
   return found.sort((a, b) => order[a.kind] - order[b.kind] || a.name.localeCompare(b.name));
 }
 
-/** Where the studio's own recorder profile lives when `StudioServerOptions.recorderProfileDir` is not given: never a crawl's own `session.browserProfile` directory, never the person's default browser profile. */
-function defaultRecorderProfileDir() {
-  return join(tmpdir(), 'opencraw-studio', 'recorder-profile');
-}
-/** @returns Fresh state for a new server instance: no workspace open, no run, no recording, no sockets, an empty snapshot cache, no last runs, Playwright's own default browser, the default recorder profile directory. */
-function createStudioState() {
-  return {
-    sockets: new Set(),
-    snapshots: createSnapshotCache(),
-    lastRuns: createLastRunCache(),
-    recorderProfileDir: defaultRecorderProfileDir()
-  };
-}
-/**
- * Sends one event to every connected client. A socket that errors while
- * sending (gone away without a clean close yet reaching us) is dropped
- * rather than left to fail every later broadcast too.
- *
- * @param state - The server state holding the connected sockets.
- * @param event - The event to send.
- */
-function broadcast(state, event) {
-  const text = JSON.stringify(event);
-  for (const socket of state.sockets) {
-    try {
-      socket.send(text);
-    } catch {
-      state.sockets.delete(socket);
-    }
-  }
-}
-
 /**
  * Handles `open-workspace`: reads the folder, remembers it as the server's
  * current workspace (every later command that names a recipe resolves it
@@ -5711,6 +5902,52 @@ function handleRegionPreview(state, command) {
   return previewRegion(snapshot.body, command.selector);
 }
 
+/** How many records and rejections a status carries: enough to judge a run, the rest stay in Studio. */
+const FIRST = 20;
+/**
+ * Handles `run-status`: how a recipe's sample run is going, for a controller that started it and cannot watch
+ * the event stream. A run in progress is `running`; one that finished carries its counts and first records.
+ *
+ * @param state - The server state holding the run in progress and the last runs.
+ * @param command - The recipe asked about.
+ * @returns The state of the recipe's sample run.
+ */
+function handleRunStatus(state, command) {
+  if (state.activeRun !== undefined && state.activeRunId === command.recipeId) return {
+    recipeId: command.recipeId,
+    state: 'running'
+  };
+  const last = lastRunOf(state.lastRuns, command.recipeId);
+  if (last === undefined) return {
+    recipeId: command.recipeId,
+    state: 'never-run'
+  };
+  const {
+    result
+  } = last;
+  return {
+    recipeId: command.recipeId,
+    state: 'finished',
+    result: {
+      emitted: result.emitted,
+      rejected: result.rejected,
+      duplicates: result.duplicates,
+      durationMs: result.durationMs,
+      error: result.error,
+      stoppedBy: result.stoppedBy,
+      records: result.records.slice(0, FIRST).map(record => ({
+        key: record.key,
+        data: record.data
+      })),
+      rejections: result.rejectedRecords.slice(0, FIRST).map(rejection => ({
+        field: rejection.field,
+        reason: rejection.reason,
+        url: rejection.url
+      }))
+    }
+  };
+}
+
 /**
  * Handles `run-sample`: stops whatever sample was still running (one run at
  * a time), starts the new one, and returns once it has started, not once it
@@ -5753,6 +5990,7 @@ async function handleRunSample(state, command) {
     }
   }, state.browser, state.plugins, command.stubs);
   state.activeRun = handle;
+  state.activeRunId = command.recipeId;
   void handle.result.then(result => {
     if (state.activeRun === handle) state.activeRun = undefined;
     recordLastRun(state.lastRuns, command.recipeId, result);
@@ -5875,6 +6113,20 @@ function serveStatic(root, pathname, response) {
   createReadStream(file).pipe(response);
 }
 
+/**
+ * Handles `studio-status`: what Studio is doing right now.
+ *
+ * @param state - The server state.
+ * @returns The open workspace, how many pages are open and the recipe being sampled.
+ */
+function handleStudioStatus(state) {
+  return {
+    folder: state.folder,
+    pages: state.sockets.size,
+    running: state.activeRun === undefined ? undefined : state.activeRunId
+  };
+}
+
 /**
  * Handles `table-preview`: the PDF canvas's live preview of a `table`
  * extract's options (`document-view`'s `table-preview.use-case.ts`, studio
@@ -6114,6 +6366,15 @@ async function startStudioServer(options = {}) {
   const port = typeof address === 'object' && address !== null ? address.port : 0;
   const folderParam = options.initialFolder === undefined ? '' : `&folder=${encodeURIComponent(options.initialFolder)}`;
   const base = `http://127.0.0.1:${port}/?token=${token}`;
+  const instancesDir = options.instancesDir ?? defaultInstancesDirectory();
+  const instance = {
+    pid: process.pid,
+    url: `http://127.0.0.1:${port}`,
+    token,
+    folder: options.initialFolder,
+    startedAt: new Date().toISOString()
+  };
+  await announceInstance(instance, instancesDir);
   return {
     url: `${base}${folderParam}`,
     token,
@@ -6122,7 +6383,10 @@ async function startStudioServer(options = {}) {
       const open = target?.open === undefined ? '' : `&open=${encodeURIComponent(target.open)}`;
       return `${base}${workspace === undefined ? '' : `&folder=${encodeURIComponent(workspace)}`}${open}`;
     },
-    close: () => stop(server, state)
+    close: async () => {
+      await withdrawInstance(instance, instancesDir);
+      await stop(server, state);
+    }
   };
 }
 async function stop(server, state) {
@@ -6321,6 +6585,26 @@ function dispatch(command, state) {
       {
         return handleStopRecording(state);
       }
+    case 'ask-ui':
+      {
+        return Promise.resolve(handleAskUi(state, command));
+      }
+    case 'ui-report':
+      {
+        return Promise.resolve(handleUiReport(state, command));
+      }
+    case 'ui-outcome':
+      {
+        return Promise.resolve(handleUiOutcome(state, command));
+      }
+    case 'studio-status':
+      {
+        return Promise.resolve(handleStudioStatus(state));
+      }
+    case 'run-status':
+      {
+        return Promise.resolve(handleRunStatus(state, command));
+      }
   }
 }
 function respondJson(response, status, body) {
@@ -6388,5 +6672,5 @@ async function main(argv, options = {}) {
   process.on('SIGTERM', shutdown);
 }
 
-export { chooseFolderCommandSchema, chooseFolderViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, deckDocumentViewSchema, deckPreviewCommandSchema, deckPreviewOptionsSchema, deckShapeViewSchema, deckSlideViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, deckViewCommandSchema, detectUrlCommandSchema, detectUrlViewSchema, documentTreeCommandSchema, documentTreeNodeViewSchema, documentTreeViewSchema, domTreeNodeViewSchema, explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, gridCellViewSchema, gridMergeViewSchema, gridPreviewCommandSchema, gridPreviewOptionsSchema, gridRowsCommandSchema, gridRowsViewSchema, gridSheetViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, gridViewCommandSchema, importDocument, importDocumentCommandSchema, importDocumentViewSchema, inferSelectorCommandSchema, inferSelectorViewSchema, inspectPageCommandSchema, inspectViewSchema, loadRecipePair, loadedHooksSchema, main, missingWhyTargetSchema, observedResponseSchema, openPathCommandSchema, openPathViewSchema, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, pageDataFindingSchema, pdfCellViewSchema, pdfDocumentViewSchema, pdfPageViewSchema, pdfRowViewSchema, pdfViewCommandSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, recordRejectedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, rejectedWhyTargetSchema, responsesSeenCommandSchema, responsesSeenViewSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, selectorAlternativeSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startRecordingCommandSchema, startStudioServer, stopRecordingCommandSchema, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, tablePreviewBandSchema, tablePreviewCommandSchema, tablePreviewMatchSchema, tablePreviewOptionsSchema, tablePreviewTableSchema, tablePreviewViewSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, whyTargetSchema, whyViewSchema, workbookDocumentViewSchema, workspaceChangedEventSchema, workspaceViewSchema };
+export { chooseFolderCommandSchema, chooseFolderViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, deckDocumentViewSchema, deckPreviewCommandSchema, deckPreviewOptionsSchema, deckShapeViewSchema, deckSlideViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, deckViewCommandSchema, defaultInstancesDirectory, detectUrlCommandSchema, detectUrlViewSchema, documentTreeCommandSchema, documentTreeNodeViewSchema, documentTreeViewSchema, domTreeNodeViewSchema, explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, gridCellViewSchema, gridMergeViewSchema, gridPreviewCommandSchema, gridPreviewOptionsSchema, gridRowsCommandSchema, gridRowsViewSchema, gridSheetViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, gridViewCommandSchema, importDocument, importDocumentCommandSchema, importDocumentViewSchema, inferSelectorCommandSchema, inferSelectorViewSchema, inspectPageCommandSchema, inspectViewSchema, loadRecipePair, loadedHooksSchema, main, missingWhyTargetSchema, observedResponseSchema, openPathCommandSchema, openPathViewSchema, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, pageDataFindingSchema, pdfCellViewSchema, pdfDocumentViewSchema, pdfPageViewSchema, pdfRowViewSchema, pdfViewCommandSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, recordRejectedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, rejectedWhyTargetSchema, responsesSeenCommandSchema, responsesSeenViewSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, selectorAlternativeSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startRecordingCommandSchema, startStudioServer, stopRecordingCommandSchema, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, tablePreviewBandSchema, tablePreviewCommandSchema, tablePreviewMatchSchema, tablePreviewOptionsSchema, tablePreviewTableSchema, tablePreviewViewSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, whyTargetSchema, whyViewSchema, workbookDocumentViewSchema, workspaceChangedEventSchema, workspaceViewSchema };
 //# sourceMappingURL=index.esm.js.map