@opencraw/studio 0.0.7 → 0.0.8

package/dist/index.esm.js

@@ -1,11 +1,13 @@
-import { normalize, sep, join, extname, dirname, resolve } from 'node:path';
+import { join, normalize, sep, extname, dirname, resolve } from 'node:path';
 import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
+import { BODY_KINDS, BrowserClient, HttpClient, NODE_ID_ATTRIBUTE, rowsOfCells, parseXml, findDeckTables, findGridTables, analyzeTables, isDeckDocument, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, resolveMissingPolicy, isWorkbookDocument, countMatches, matchesOf, tryParseJson, RecipeBindingError, RecipeValidationError, isPdfDocument, BrowserProfiles } from '@opencraw/core';
 import { randomBytes, createHash } from 'node:crypto';
-import { readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, resolveMissingPolicy, BrowserClient, HttpClient, NODE_ID_ATTRIBUTE, countMatches, RecipeBindingError, RecipeValidationError } from '@opencraw/core';
 import { load } from 'cheerio';
-import { writeFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
+import { describeJson } from '@opencraw/probe';
+import { tmpdir } from 'node:os';
 import { existsSync, createReadStream } from 'node:fs';
 
 const sentencePartSchema = z.object({
@@ -119,6 +121,151 @@ const inferSelectorCommandSchema = z.object({
   path: z.string().min(1),
   nodeIds: z.union([onePickedNodeSchema, twoPickedNodesSchema])
 });
+/**
+ * The Inspect panel's DOM tree and data-in-the-page findings, off the same
+ * cached snapshot `take-snapshot`/`infer-selector` already use (`page-inspector`,
+ * issue #93). Call `take-snapshot` first, same as `infer-selector`.
+ */
+const inspectPageCommandSchema = z.object({
+  type: z.literal('inspect-page'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1)
+});
+/**
+ * The JSON responses seen while a recipe's start page rendered
+ * (`page-inspector`'s `responses-seen.use-case.ts`, issue #93), for the
+ * Inspect panel's "responses seen" list. Opens its own browser session
+ * (see that use-case's doc comment for why); slower than `inspect-page`.
+ */
+const responsesSeenCommandSchema = z.object({
+  type: z.literal('responses-seen'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1)
+});
+/**
+ * The document tree for the content pane's tree canvas (`document-view`'s
+ * `tree-view.mapper.ts`, studio plan §3.4, issue #94's 5a), off the same
+ * cached snapshot `take-snapshot`/`inspect-page` already use — call
+ * `take-snapshot` first, same as `inspect-page`. Only a JSON/YAML/XML
+ * snapshot has one; PDF, workbook and deck documents get their own canvases
+ * (5b/5c/5d).
+ */
+const documentTreeCommandSchema = z.object({
+  type: z.literal('document-tree'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1)
+});
+/**
+ * The PDF canvas's cells and rows (`document-view`'s `pdf-view.mapper.ts`,
+ * studio plan §3.4, issue #94's 5b), off the same cached snapshot
+ * `take-snapshot`/`document-tree` already use — call `take-snapshot` first.
+ * Only a PDF snapshot has one; JSON/YAML/XML get the tree canvas (5a), the
+ * workbook and deck their own canvases (5c/5d).
+ */
+const pdfViewCommandSchema = z.object({
+  type: z.literal('pdf-view'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1)
+});
+/** A `table` extract's options, as the studio's PDF canvas picks build them — mirrors `document-view/table-preview.use-case.ts`'s `TablePreviewOptions`. */
+const tablePreviewOptionsSchema = z.object({
+  header: z.string().min(1),
+  until: z.string().min(1).optional(),
+  columns: z.record(z.string(), z.string().min(1)).optional(),
+  align: z.enum(['auto', 'top', 'center', 'bottom']).optional()
+});
+/**
+ * The live preview of a `table` extract's options against a cached PDF
+ * snapshot (`document-view`'s `table-preview.use-case.ts`, studio plan §3.4,
+ * issue #94's 5b): the matched rows to highlight on the page, recomputed as
+ * the person edits the options — call `take-snapshot` first.
+ */
+const tablePreviewCommandSchema = z.object({
+  type: z.literal('table-preview'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1),
+  options: tablePreviewOptionsSchema
+});
+/**
+ * The grid canvas's sheets and cells (`document-view`'s `workbook-view.mapper.ts`,
+ * studio plan §3.4, issue #94's 5c), off the same cached snapshot
+ * `take-snapshot`/`document-tree` already use — call `take-snapshot` first.
+ * Only a CSV/spreadsheet snapshot has one; JSON/YAML/XML get the tree canvas
+ * (5a), PDF the PDF canvas (5b), the deck its own canvas (5d).
+ *
+ * `delimiter`/`encoding` override a CSV's auto-detected format (issue #94's
+ * 5c: "the detected delimiter and encoding shown and overridable"); the
+ * server re-reads the file with the override applied and keeps it cached, so
+ * a later `grid-preview` sees the same reading. Both are rejected on a
+ * spreadsheet snapshot (there is nothing to detect).
+ */
+const gridViewCommandSchema = z.object({
+  type: z.literal('grid-view'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1),
+  delimiter: z.string().min(1).optional(),
+  encoding: z.string().min(1).optional()
+});
+/** A `table` extract's options for a workbook, as the studio's grid canvas picks build them — mirrors `document-view/table-preview.use-case.ts`'s `GridTablePreviewOptions`. */
+const gridPreviewOptionsSchema = z.object({
+  sheet: z.string().min(1).optional(),
+  header: z.string().min(1),
+  until: z.string().min(1).optional(),
+  columns: z.record(z.string(), z.string().min(1)).optional(),
+  headerRows: z.int().min(1).optional(),
+  fillDown: z.array(z.string().min(1)).min(1).optional(),
+  includeHidden: z.boolean().optional()
+});
+/**
+ * The live preview of a `table` extract's options against a cached CSV/
+ * spreadsheet snapshot (`document-view`'s `table-preview.use-case.ts`'s
+ * `previewGridTable`, studio plan §3.4, issue #94's 5c): the matched
+ * table(s), recomputed as the person edits the options — call `take-snapshot`
+ * and `grid-view` first.
+ */
+const gridPreviewCommandSchema = z.object({
+  type: z.literal('grid-preview'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1),
+  options: gridPreviewOptionsSchema
+});
+/**
+ * The deck canvas's slides, shapes, tables, charts and notes for a deck
+ * (PowerPoint) snapshot (`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 — call `take-snapshot` first.
+ * Only a `.pptx` snapshot has one; JSON/YAML/XML get the tree canvas (5a),
+ * PDF the PDF canvas (5b), the workbook the grid canvas (5c).
+ */
+const deckViewCommandSchema = z.object({
+  type: z.literal('deck-view'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1)
+});
+/** A `table` extract's options for a deck, as the studio's deck canvas picks build them — mirrors `document-view/table-preview.use-case.ts`'s `DeckTablePreviewOptions`. */
+const deckPreviewOptionsSchema = z.object({
+  slide: z.string().min(1).optional(),
+  shapes: z.boolean().optional(),
+  align: z.enum(['auto', 'top', 'center', 'bottom']).optional(),
+  header: z.string().min(1),
+  until: z.string().min(1).optional(),
+  columns: z.record(z.string(), z.string().min(1)).optional(),
+  headerRows: z.int().min(1).optional(),
+  fillDown: z.array(z.string().min(1)).min(1).optional(),
+  includeHidden: z.boolean().optional()
+});
+/**
+ * The live preview of a `table` extract's options against a cached deck
+ * snapshot (`document-view`'s `table-preview.use-case.ts`'s `previewDeckTable`,
+ * studio plan §3.4, issue #94's 5d): the matched table(s), recomputed as the
+ * person edits the options — call `take-snapshot` and `deck-view` first.
+ */
+const deckPreviewCommandSchema = z.object({
+  type: z.literal('deck-preview'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1),
+  options: deckPreviewOptionsSchema
+});
 /** A missing value in an emitted record, by its position in the last sample run's records (the order they streamed in, matching the UI's own `records` list). */
 const missingWhyTargetSchema = z.object({
   kind: z.literal('missing'),
@@ -144,13 +291,40 @@ const explainWhyCommandSchema = z.object({
   type: z.literal('explain-why'),
   target: whyTargetSchema
 });
-const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, explainWhyCommandSchema]);
+/**
+ * Opens the studio's own headed browser window and starts recording user
+ * actions on it (issue #95, phase 6): clicks, fills, selects, key presses
+ * and scrolls stream back as `recording-card` events, each already a
+ * verified step. `recipeId`'s start point is where the window opens.
+ */
+const startRecordingCommandSchema = z.object({
+  type: z.literal('start-recording'),
+  recipeId: z.string().min(1)
+});
+/**
+ * Closes the recording window, if one is open; a no-op otherwise. Answers
+ * with every step recorded, in order, so the caller can offer "make this
+ * the login" (writes them under `session.bootstrap`) or "keep as steps"
+ * (appends them to the recipe's own `steps`) without a second round trip.
+ */
+const stopRecordingCommandSchema = z.object({
+  type: z.literal('stop-recording')
+});
+const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewCommandSchema, gridViewCommandSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema]);
 
-/** What `take-snapshot` answers with: the rewritten document ready for the content pane's sandboxed iframe (studio plan §3.1, issue #91). */
+/**
+ * What `take-snapshot` answers with: the rewritten document ready for the
+ * content pane's sandboxed iframe (studio plan §3.1, issue #91). `format`
+ * (api mode only; absent in web mode, whose document is always HTML) is
+ * what the content pane uses to choose a canvas — the snapshot iframe for
+ * `html` (and `docx`/`markdown`, already turned into HTML), else
+ * `document-view`'s tree/pdf/grid/deck canvas (studio plan §3.4, issue #94).
+ */
 const snapshotViewSchema = z.object({
   html: z.string(),
   nodeCount: z.number(),
-  baseUrl: z.string()
+  baseUrl: z.string(),
+  format: z.enum(BODY_KINDS).optional()
 });
 
 /**
@@ -253,7 +427,32 @@ const runFinishedEventSchema = z.object({
 const workspaceChangedEventSchema = z.object({
   type: z.literal('workspace-changed')
 });
-const studioEventSchema = z.discriminatedUnion('type', [traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema]);
+/**
+ * One recorded action landed as a step (issue #95): the card it becomes
+ * (`scope-outline`'s own `OutlineCard`/`OutlineBracket` shape — the wire
+ * form `outline-view.contract.ts` already defines, never a second card
+ * format) and whether its value is a secret placeholder, for the secret
+ * pill styling.
+ */
+const recordingCardEventSchema = z.object({
+  type: z.literal('recording-card'),
+  node: outlineNodeSchema,
+  secret: z.boolean()
+});
+/** A notice from the recording session that is not itself a step: a "next" link offer, or an unsupported iframe/shadow-DOM report. */
+const recordingNoteEventSchema = z.object({
+  type: z.literal('recording-note'),
+  kind: z.enum(['next-link', 'unsupported', 'info']),
+  message: z.string()
+});
+/** One recorded step's raw JSON, exactly as `flow-recording` built it. */
+const recordedStepSchema = z.record(z.string(), z.unknown());
+/** The recording window closed — `stop-recording` completed, or the window was closed some other way. `steps` is every step recorded, in order, exactly as `stop-recording`'s own response carries them. */
+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]);
 
 /** One problem found on a recipe file, with the JSON path it lives at. */
 const recipeIssueSchema = z.object({
@@ -315,6 +514,236 @@ const whyViewSchema = z.object({
   reason: z.string().optional()
 });
 
+const domTreeNodeViewSchema = z.lazy(() => z.object({
+  nodeId: z.string(),
+  tag: z.string(),
+  id: z.string().optional(),
+  classes: z.array(z.string()).optional(),
+  attributes: z.record(z.string(), z.string()),
+  text: z.string().optional(),
+  hidden: z.boolean(),
+  children: z.array(domTreeNodeViewSchema),
+  repeatCount: z.number().int().optional(),
+  repeatNodeIds: z.array(z.string()).optional()
+}));
+const pageDataKindSchema = z.enum(['ld-json', 'json-script', 'inline-state', 'meta', 'link']);
+/** One "data in the page" entry — mirrors `page-inspector/page-data.algorithm.ts`'s `PageDataFinding`. */
+const pageDataFindingSchema = z.object({
+  kind: pageDataKindSchema,
+  label: z.string(),
+  selector: z.string(),
+  selectorKind: z.literal('css'),
+  matches: z.number(),
+  keys: z.array(z.string()).optional(),
+  attribute: z.string().optional()
+});
+/** What `inspect-page` answers with (studio plan §3.3, issue #93): the DOM tree and the data-in-the-page findings, in one round trip — both come from the same cached snapshot/raw capture, so there is no reason to ask twice. */
+const inspectViewSchema = z.object({
+  tree: domTreeNodeViewSchema,
+  pageData: z.array(pageDataFindingSchema)
+});
+
+/** One JSON response seen — mirrors `page-inspector/responses-seen.use-case.ts`'s `ObservedResponse`. */
+const observedResponseSchema = z.object({
+  url: z.string(),
+  status: z.number(),
+  size: z.number(),
+  shape: z.string()
+});
+/** What `responses-seen` answers with (studio plan §3.3, issue #93): the JSON responses the page fetched while it rendered, for the panel's "responses seen" list. */
+const responsesSeenViewSchema = z.object({
+  responses: z.array(observedResponseSchema)
+});
+
+const documentTreeNodeViewSchema = z.lazy(() => z.object({
+  id: z.string(),
+  label: z.string(),
+  valueType: z.enum(['object', 'array', 'string', 'number', 'boolean', 'null', 'element']),
+  preview: z.string().optional(),
+  jsonpath: z.string().optional(),
+  xpath: z.string().optional(),
+  listPath: z.string().optional(),
+  listCount: z.number().optional(),
+  attributes: z.record(z.string(), z.string()).optional(),
+  children: z.array(documentTreeNodeViewSchema)
+}));
+/** What `document-tree` answers with (studio plan §3.4, issue #94's 5a): the parsed JSON/XML document as a tree, and, for XML, the namespace prefixes a pick's `extract` can use in `namespaces`. */
+const documentTreeViewSchema = z.object({
+  format: z.enum(['json', 'xml']),
+  root: documentTreeNodeViewSchema,
+  namespaces: z.record(z.string(), z.string()).optional()
+});
+
+/** One text cell, in PDF points — mirrors `document-view/pdf-view.mapper.ts`'s `PdfCellView`, the wire shape for the UI (studio plan §3.4, issue #94's 5b). */
+const pdfCellViewSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+  width: z.number(),
+  height: z.number(),
+  text: z.string()
+});
+const pdfRowViewSchema = z.object({
+  top: z.number(),
+  bottom: z.number(),
+  cells: z.array(pdfCellViewSchema)
+});
+const pdfPageViewSchema = z.object({
+  number: z.number().int(),
+  width: z.number(),
+  height: z.number(),
+  rows: z.array(pdfRowViewSchema),
+  rowCount: z.number().int(),
+  cellCount: z.number().int(),
+  hasTextLayer: z.boolean()
+});
+/** What `pdf-view` answers with (studio plan §3.4, issue #94's 5b): every page's cells and rows, for the PDF canvas to draw over its own `pdf.js` rendering. */
+const pdfDocumentViewSchema = z.object({
+  pages: z.array(pdfPageViewSchema)
+});
+
+const tablePreviewRowSchema = z.record(z.string(), z.string());
+/** One table matched by a `table` extract's options — mirrors `@opencraw/core`'s `PdfTable`. */
+const tablePreviewTableSchema = z.object({
+  page: z.number().int(),
+  title: z.string(),
+  header: z.array(z.string()),
+  rows: z.array(tablePreviewRowSchema)
+});
+/** One column band a matched table's body clustered into — mirrors `@opencraw/core`'s `TableBandDiagnostics`. */
+const tablePreviewBandSchema = z.object({
+  start: z.number(),
+  end: z.number(),
+  column: z.number().int(),
+  name: z.string()
+});
+/** One matched table, with the exact page rows to highlight — mirrors `document-view/table-preview.use-case.ts`'s `TablePreviewMatch`. */
+const tablePreviewMatchSchema = z.object({
+  page: z.number().int(),
+  headerRowIndex: z.number().int(),
+  matchedRowIndices: z.array(z.number().int()),
+  bands: z.array(tablePreviewBandSchema),
+  bandTolerance: z.number(),
+  table: tablePreviewTableSchema
+});
+/**
+ * What `table-preview` answers with (studio plan §3.4, issue #94's 5b: the
+ * live preview): every match, or `error` when a pattern in the options does
+ * not compile — expected while the person is still typing it, not thrown.
+ */
+const tablePreviewViewSchema = z.object({
+  matches: z.array(tablePreviewMatchSchema),
+  error: z.string().optional()
+});
+
+/** One cell's value, and the type the grid shows it as — mirrors `document-view/workbook-view.mapper.ts`'s `GridCellView`, the wire shape for the UI (studio plan §3.4, issue #94's 5c). */
+const gridCellViewSchema = z.object({
+  value: z.union([z.string(), z.number(), z.boolean()]),
+  type: z.enum(['string', 'number', 'boolean', 'date'])
+});
+/** One merged range, 0-based and inclusive. */
+const gridMergeViewSchema = z.object({
+  ref: z.string(),
+  top: z.number().int(),
+  left: z.number().int(),
+  bottom: z.number().int(),
+  right: z.number().int()
+});
+const gridSheetViewSchema = z.object({
+  name: z.string(),
+  hidden: z.boolean(),
+  hiddenRows: z.array(z.number().int()),
+  columnCount: z.number().int(),
+  rows: z.array(z.array(gridCellViewSchema)),
+  merges: z.array(gridMergeViewSchema)
+});
+const csvFormatViewSchema = z.object({
+  encoding: z.string(),
+  delimiter: z.string()
+});
+/** What `grid-view` answers with (studio plan §3.4, issue #94's 5c): every sheet's cells, typed, with hidden sheets/rows marked and merged ranges resolved, for the grid canvas to draw. */
+const workbookDocumentViewSchema = z.object({
+  sheets: z.array(gridSheetViewSchema),
+  csv: csvFormatViewSchema.optional()
+});
+
+const gridPreviewRowSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]));
+/** One table matched by a `table` extract's options against a workbook — mirrors `@opencraw/core`'s `GridTable`. */
+const gridTablePreviewMatchSchema = z.object({
+  sheet: z.string(),
+  title: z.string(),
+  header: z.array(z.string()),
+  rows: z.array(gridPreviewRowSchema)
+});
+/**
+ * What `grid-preview` answers with (studio plan §3.4, issue #94's 5c: the
+ * live preview): every matched table, or `error` when a pattern in the
+ * options does not compile — expected while the person is still typing it,
+ * not thrown.
+ */
+const gridTablePreviewViewSchema = z.object({
+  matches: z.array(gridTablePreviewMatchSchema),
+  error: z.string().optional()
+});
+
+/** One text box on a slide, in points — mirrors `document-view/deck-view.mapper.ts`'s `DeckShapeView`, the wire shape for the UI (studio plan §3.4, issue #94's 5d). */
+const deckShapeViewSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+  width: z.number(),
+  height: z.number(),
+  text: z.string(),
+  placeholder: z.string().optional()
+});
+const deckChartValueSchema = z.union([z.number(), z.null()]);
+const deckChartSeriesViewSchema = z.object({
+  name: z.string(),
+  categories: z.array(z.string()),
+  values: z.array(deckChartValueSchema)
+});
+const deckChartViewSchema = z.object({
+  type: z.string(),
+  title: z.string().optional(),
+  series: z.array(deckChartSeriesViewSchema)
+});
+const deckShapeRowSchema = z.array(z.number().int());
+const deckSlideViewSchema = z.object({
+  number: z.number().int(),
+  title: z.string().optional(),
+  hidden: z.boolean(),
+  shapes: z.array(deckShapeViewSchema),
+  /** Indices into `shapes`, grouped into visual rows — see `deck-view.mapper.ts`'s own doc comment. */
+  shapeRows: z.array(deckShapeRowSchema),
+  tables: z.array(gridSheetViewSchema),
+  charts: z.array(deckChartViewSchema),
+  notes: z.string()
+});
+/** What `deck-view` answers with (studio plan §3.4, issue #94's 5d): the slide size in points and every slide's shapes, tables, charts and notes, for the deck canvas to draw and pick from. */
+const deckDocumentViewSchema = z.object({
+  width: z.number(),
+  height: z.number(),
+  slides: z.array(deckSlideViewSchema)
+});
+
+const deckPreviewRowSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]));
+/** One table matched by a `table` extract's options against a deck — mirrors `@opencraw/core`'s `DeckTable`. */
+const deckTablePreviewMatchSchema = z.object({
+  slide: z.number().int(),
+  slideTitle: z.string(),
+  title: z.string(),
+  header: z.array(z.string()),
+  rows: z.array(deckPreviewRowSchema)
+});
+/**
+ * What `deck-preview` answers with (studio plan §3.4, issue #94's 5d: the
+ * live preview): every matched table, or `error` when a pattern in the
+ * options does not compile — expected while the person is still typing it,
+ * not thrown.
+ */
+const deckTablePreviewViewSchema = z.object({
+  matches: z.array(deckTablePreviewMatchSchema),
+  error: z.string().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. */
@@ -358,779 +787,1481 @@ function cookieToken(header) {
 }
 
 /**
- * Finds and parses one input recipe of a workspace folder, and the output
- * recipe it names.
+ * Fetches an input recipe's start page as the engine would see it: a fresh
+ * Playwright page in web mode, core's HTTP client in api mode. Returns plain
+ * text: the page's HTML, or a readable rendering of a non-HTML api response.
+ * No rewriting, no script stripping, no node ids yet: that is phase 2's
+ * `page-snapshot` proper (studio plan, #91). Provisional for phase 0 in two
+ * ways, both worth knowing before relying on it: it opens a bare page
+ * without running the recipe's own steps first, so a start point behind a
+ * `session.bootstrap` login shows what an anonymous visitor sees; and it
+ * launches a fresh browser or HTTP context per call, one page then closes
+ * it, rather than reusing whatever the last sample run had open.
  *
- * @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 input - The input recipe; only `mode` and the first `start` point are used.
+ * @param browser - Browser launch settings for web mode (an executable path override, headless…).
+ * @returns The page's content as plain text.
+ * @throws Error when the recipe has no start point.
  */
-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 {
-    input,
-    output: parseOutputRecipe(outputDocument.content, outputDocument.source)
-  };
+async function fetchStartPage(input, browser) {
+  const point = input.start[0];
+  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
+  return input.mode === 'web' ? fetchWeb(point.url, browser) : fetchApi(point.url);
 }
-function kindOf(content) {
-  return content?.kind;
+async function fetchWeb(url, browser) {
+  const client = await BrowserClient.launch(browser);
+  try {
+    const session = await client.newSession();
+    try {
+      await session.page.goto(url);
+      return await session.page.content();
+    } finally {
+      await session.close();
+    }
+  } finally {
+    await client.close();
+  }
 }
-function idOf(content) {
-  return content?.id;
+async function fetchApi(url) {
+  const client = await HttpClient.open({});
+  try {
+    const response = await client.send({
+      url
+    });
+    return textOf$2(response.body);
+  } finally {
+    await client.dispose();
+  }
+}
+/** Every body kind the studio can show as text today; others get a placeholder rather than a crash. */
+function textOf$2(body) {
+  if (body.kind === 'html') return body.html;
+  if (body.kind === 'text') return body.text;
+  if (body.kind === 'json') return JSON.stringify(body.data, null, 2);
+  return `[${body.kind} document: the content pane shows HTML and JSON responses for now]`;
 }
 
+/** The attribute `hiddenMarksScript` stamps on an element hidden on the live page. */
+const HIDDEN_ATTRIBUTE = 'data-oc-hidden';
 /**
- * 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.
+ * The in-page script `take-snapshot.use-case.ts` runs with `page.evaluate`
+ * *before* `page.content()`, so a `display: none`/`visibility: hidden`/
+ * zero-size element carries `data-oc-hidden="1"` into the captured markup
+ * (studio plan §3.1, issue #91) — the only way to know an element was
+ * hidden on the live page, since a static parse of the HTML afterwards has
+ * no computed style to ask.
  *
- * @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.
- * @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.
+ * Kept as a plain string, not a TypeScript function passed to
+ * `page.evaluate`, because it references `window`/`document` as globals: `AGENTS.md`'s
+ * "things that bit before" calls out that in-page functions must not do
+ * that (the repo's `isolated-functions` lint rule), and every existing
+ * `page.evaluate` call with real DOM logic in this codebase (see
+ * `packages/core/src/captcha/resolve-captcha.use-case.ts`) already uses
+ * this same string-template shape.
+ *
+ * @param attribute - The attribute to stamp; defaults to `HIDDEN_ATTRIBUTE` (parameterised for tests and for a future caller that wants a different name).
+ * @returns A self-invoking script, ready for `page.evaluate(hiddenMarksScript())`.
  */
-async function runSample(folder, recipeId, budget, callbacks, browser) {
-  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,
-    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, records, rejectedRecords, steps);
-  return {
-    stop: () => crawler.close(),
-    result
-  };
+function hiddenMarksScript(attribute = HIDDEN_ATTRIBUTE) {
+  return `(() => {
+    var attribute = ${JSON.stringify(attribute)}
+    var elements = document.querySelectorAll('*')
+    for (var i = 0; i < elements.length; i++) {
+      var element = elements[i]
+      var style = window.getComputedStyle(element)
+      var rect = element.getBoundingClientRect()
+      var hidden = style.display === 'none' || style.visibility === 'hidden' || (rect.width === 0 && rect.height === 0)
+      if (hidden) element.setAttribute(attribute, '1')
+    }
+  })()`;
 }
+
+/** Attributes that carry a URL and are rewritten to absolute; `srcset` is handled separately (it carries several). */
+const URL_ATTRIBUTES = ['href', 'src', 'action', 'poster'];
+/** Schemes left untouched: they are not a location `new URL(value, base)` should resolve, or already carry their own meaning. */
+const SKIP_SCHEME = /^(?:javascript|mailto|tel|data|about):/i;
 /**
- * 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.
+ * Rewrites captured HTML into what the content pane's sandboxed iframe shows
+ * (studio plan §3.1, issue #91): every URL made absolute against `baseUrl`,
+ * a `<base>` injected, every `<script>` removed, forms disabled (`onsubmit`
+ * stripped, fields made read-only), `<meta http-equiv="refresh">` stripped
+ * (it would otherwise navigate the sandboxed frame on its own), and every
+ * element given a stable `data-oc-node` id, in document order, for the
+ * picker overlay and `selector-inference` to address specific nodes by.
+ *
+ * Purely a markup transform: it does not know whether an element is hidden
+ * on the live page (`display: none`, `visibility: hidden`, zero size) — in
+ * web mode that is `hidden-marks.algorithm.ts`'s job, run against the live
+ * page *before* this function ever sees the markup, so a `data-oc-hidden`
+ * attribute it wrote just survives serialisation untouched here.
+ *
+ * @param html - The captured document (`page.content()` in web mode, the fetched body in api mode).
+ * @param baseUrl - The page's own URL, for resolving relative links and as the `<base>`.
+ * @returns The rewritten document and how many elements it stamped.
  */
-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;
+function rewriteDocument(html, baseUrl) {
+  const $ = load(html);
+  if ($('head').length === 0) $('html').prepend('<head></head>');
+  const head = $('head').first();
+  head.find('base').remove();
+  head.prepend(`<base href="${escapeAttribute(baseUrl)}">`);
+  $('meta').each((_index, element) => {
+    if (($(element).attr('http-equiv') ?? '').toLowerCase() === 'refresh') $(element).remove();
+  });
+  $('script').remove();
+  $('form').removeAttr('onsubmit');
+  $('input, textarea').attr('readonly', 'readonly');
+  $('select, button, input[type="submit"], input[type="button"]').attr('disabled', 'disabled');
+  $('*').each((_index, element) => {
+    const node = $(element);
+    for (const attribute of URL_ATTRIBUTES) {
+      const value = node.attr(attribute);
+      if (value !== undefined) node.attr(attribute, resolveUrl(value, baseUrl) ?? value);
+    }
+    const srcset = node.attr('srcset');
+    if (srcset !== undefined) node.attr('srcset', rewriteSrcset(srcset, baseUrl));
+  });
+  let nodeCount = 0;
+  $('*').each((_index, element) => {
+    $(element).attr(NODE_ID_ATTRIBUTE, `n${nodeCount}`);
+    nodeCount += 1;
+  });
+  return {
+    html: $.html(),
+    nodeCount
+  };
+}
+/** Resolves one URL against `baseUrl`; a scheme that is not a location (`javascript:`, `data:`…), or a value `new URL` cannot parse, is left as it was. */
+function resolveUrl(value, baseUrl) {
+  const trimmed = value.trim();
+  if (trimmed === '' || SKIP_SCHEME.test(trimmed)) return undefined;
+  try {
+    return new URL(trimmed, baseUrl).href;
+  } catch {
+    return undefined;
   }
-  if (event.type === 'step:skip') {
-    steps.set(event.path, {
-      path: event.path,
-      stepType: event.stepType,
-      stepId: event.stepId,
-      outcome: 'skipped',
-      error: event.error
-    });
+}
+/** `srcset`'s own micro-syntax: comma-separated `url descriptor?` pairs. Malformed entries are passed through unresolved rather than dropped. */
+function rewriteSrcset(value, baseUrl) {
+  return value.split(',').map(candidate => {
+    const trimmed = candidate.trim();
+    const spaceAt = trimmed.indexOf(' ');
+    const url = spaceAt === -1 ? trimmed : trimmed.slice(0, spaceAt);
+    const descriptor = spaceAt === -1 ? '' : trimmed.slice(spaceAt);
+    return `${resolveUrl(url, baseUrl) ?? url}${descriptor}`;
+  }).join(', ');
+}
+function escapeAttribute(value) {
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
+}
+
+/**
+ * Captures the snapshot the content pane shows (studio plan §3.1, issue
+ * #91): runs the recipe up to `stepPath`, serialises the document, marks
+ * hidden elements in web mode, and hands it to `rewrite-document.mapper.ts`
+ * for display.
+ *
+ * `stepPath` is accepted (and cached against, by `snapshot.store.ts`) for
+ * the API the UI needs — one snapshot per selected step — but v1 only
+ * actually *captures* `"start"`: the first `start` point, before any step
+ * of the recipe has run, the same reach `fetch-start-page.use-case.ts` (phase
+ * 0) already had. Snapshotting mid-recipe (after an arbitrary later step)
+ * needs a "stop the crawl after step X and hand back the live page/document"
+ * hook in `crawl-execution` that does not exist yet; building one was out of
+ * this phase's budget (see this phase's final report for the tradeoff this
+ * was weighed against). Any other `stepPath` throws, clearly, rather than
+ * silently returning the start page under a misleading label.
+ *
+ * @param input - The input recipe; only `mode` and the first `start` point are used.
+ * @param stepPath - The step to snapshot after, e.g. `"start"` or `"steps.2"` (`scope-outline`'s path format).
+ * @param browser - Browser launch settings for web mode.
+ * @returns The rewritten snapshot.
+ * @throws Error when the recipe has no start point, or `stepPath` is not `"start"`.
+ */
+async function takeSnapshot(input, stepPath, browser) {
+  if (stepPath !== 'start') throw new Error(`takeSnapshot: "${stepPath}" is not supported yet — only "start" (the first start point, before any step runs) is; see this function's doc comment`);
+  const point = input.start[0];
+  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
+  return input.mode === 'web' ? snapshotWeb(point.url, browser) : snapshotApi(point.url);
+}
+async function snapshotWeb(url, browser) {
+  const client = await BrowserClient.launch(browser);
+  try {
+    const session = await client.newSession();
+    try {
+      await session.page.goto(url);
+      await session.page.evaluate(hiddenMarksScript(HIDDEN_ATTRIBUTE));
+      const html = await session.page.content();
+      const baseUrl = session.page.url();
+      const rewritten = rewriteDocument(html, baseUrl);
+      return {
+        ...rewritten,
+        baseUrl,
+        rawHtml: html
+      };
+    } finally {
+      await session.close();
+    }
+  } finally {
+    await client.close();
   }
 }
-async function runToResult(crawler, set, records, rejectedRecords, steps) {
+async function snapshotApi(url) {
+  const client = await HttpClient.open({});
   try {
-    const report = await crawler.run(set);
-    const recipe = report.recipes[0];
+    const response = await client.send({
+      url
+    });
+    const text = textOf$1(response.body);
+    const rewritten = rewriteDocument(text, url);
     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()]
+      ...rewritten,
+      baseUrl: url,
+      rawHtml: text,
+      format: response.format,
+      body: response.body
     };
   } finally {
-    await crawler.close();
+    await client.dispose();
   }
 }
+/** Every body kind the studio can show as text today; others get a placeholder rather than a crash (mirrors `fetch-start-page.use-case.ts`'s own `textOf`). */
+function textOf$1(body) {
+  if (body.kind === 'html') return body.html;
+  if (body.kind === 'text') return body.text;
+  if (body.kind === 'json') return `<pre>${JSON.stringify(body.data, null, 2)}</pre>`;
+  return `<p>[${body.kind} document: the content pane shows HTML and JSON responses for now]</p>`;
+}
 
-/** @returns A fresh, empty cache. */
-function createLastRunCache() {
+/** @returns An empty cache, for a freshly opened workspace. */
+function createSnapshotCache() {
   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 cached snapshot for `recipeId`/`path`, or `undefined` when none was taken yet. */
+function cachedSnapshot(cache, recipeId, path) {
+  return cache.entries.get(keyOf(recipeId, path));
 }
-/** @returns The recipe's last completed sample run, or `undefined` when none has finished yet. */
-function lastRunOf(cache, recipeId) {
-  return cache.entries.get(recipeId);
+/** Records a freshly taken snapshot, replacing whatever was cached for the same recipe and step path. */
+function putSnapshot(cache, recipeId, path, snapshot) {
+  cache.entries.set(keyOf(recipeId, path), snapshot);
+}
+function keyOf(recipeId, path) {
+  return `${recipeId}:${path}`;
 }
 
 /**
- * A best-effort hint about what a missing value's bound id actually held in
- * the scope snapshot: the keys of an object, or the length of a list — the
- * fallback when there is no per-item DOM snapshot to compare a selector
- * against (see `why-sentence.mapper.ts`'s doc comment for why the richer,
- * "the item has `.price_new`" hint is out of this phase's scope).
+ * Fetches a PDF's raw bytes for the PDF canvas's `pdf.js` to render in the
+ * browser (studio plan §3.4, issue #94's 5b: "the PDF bytes served by the
+ * studio"). `take-snapshot` already read this same document with
+ * `@opencraw/core`'s `readPdf` for the cells/rows `document-view` maps, but
+ * `HttpClient`/`readPdf` parse the bytes and keep only the result — pdf.js
+ * needs the file itself, so this re-fetches it from the same URL a cached
+ * snapshot's own `SnapshotResult.baseUrl` gives, the way `HttpClient`'s own
+ * `file:` branch (`readLocalFile`) and its HTTP fetch do.
  *
- * @param scope - The record's scope snapshot (`SampleRunRecord.scope`/`SampleRunRejected.scope`).
- * @param boundId - The leading id the rule's `from` reads.
- * @returns A short clause (no leading punctuation), or `undefined` when the id is not in scope or nothing useful can be said about it.
+ * @param url - The document's URL — a `file:` URL or an `http(s):` URL.
+ * @returns The raw bytes.
+ * @throws Error when a `file:` URL cannot be read, or the fetch does not succeed.
  */
-function hintFor(scope, boundId) {
-  if (scope === undefined || boundId === undefined) return undefined;
-  const value = scope[boundId];
-  if (value === undefined) return undefined;
-  if (Array.isArray(value)) return value.length === 0 ? undefined : `"${boundId}" is a list of ${value.length}, not a single value`;
-  if (typeof value === 'object' && value !== null) {
-    const keys = Object.keys(value);
-    return keys.length === 0 ? undefined : `"${boundId}" has: ${keys.slice(0, 5).join(', ')}`;
-  }
-  return undefined;
+async function pdfBytes(url) {
+  if (url.startsWith('file:')) return new Uint8Array(await readFile(fileURLToPath(url)));
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`pdfBytes: ${String(response.status)} fetching ${url}`);
+  return new Uint8Array(await response.arrayBuffer());
 }
 
 /**
- * Builds the Why? tab's sentence (studio plan §4.4, issue #92) from the
- * facts `why.use-case.ts` gathers: the value the mapping read (and each
- * transform's effect on it), the step that bound its source id and whether
- * it ran, was skipped, or bound nothing this recipe knows of, the
- * missing-value policy that applied, and a hint about what was actually
- * there instead.
- *
- * This is the scope-snapshot-only half of the design: phase 2's per-item DOM
- * snapshot (the CSS-selector "the item has `.price_new`" hint the issue's
- * example shows) is not wired in here — `sample-run` keeps the mapping's
- * scope snapshot (bound ids and their values), not a per-`forEach`-item DOM
- * capture, and building that link is a bigger integration than this phase's
- * budget covers (see this package's `page-snapshot` slice, which captures a
- * step's page for the content pane, not per-iteration). `hint`, when given,
- * is instead built from the scope snapshot itself (`item-hint.algorithm.ts`).
+ * Re-reads a CSV document with an overridden delimiter and/or encoding
+ * (studio plan §3.4, issue #94's 5c). `take-snapshot` already read this same
+ * document once with auto-detection (`http.client.ts`'s own `csvWorkbook`
+ * call); it keeps only the parsed result, not the raw bytes, so re-reading
+ * the file/URL is the only way to apply a different choice — the same
+ * "the studio re-fetches, the reader keeps no bytes around" tradeoff
+ * `pdf-bytes.use-case.ts` documents for pdf.js.
  *
- * @param facts - What is known about the value.
- * @returns One sentence, always ending in a period.
+ * @param url - The document's URL — a `file:` URL or an `http(s):` URL (`page-snapshot`'s cached `SnapshotResult.baseUrl`).
+ * @param override - The delimiter and/or encoding to force; `HttpClient` still detects whichever one is left out.
+ * @returns The freshly read workbook.
+ * @throws Error when the URL cannot be read, or it no longer reads back as a workbook.
  */
-function buildWhySentence(facts) {
-  return facts.outcome === 'rejected' ? rejectedSentence(facts) : missingSentence(facts);
+async function rereadCsv(url, override) {
+  const client = await HttpClient.open({});
+  try {
+    const response = await client.send({
+      url,
+      as: 'csv',
+      delimiter: override.delimiter,
+      encoding: override.encoding
+    });
+    if (response.body.kind !== 'workbook') throw new Error(`rereadCsv: ${url} did not read back as a workbook`);
+    return response.body;
+  } finally {
+    await client.dispose();
+  }
 }
-function rejectedSentence(facts) {
-  const parts = [`"${facts.field}" was rejected: ${facts.reason ?? 'the engine gave no reason'}`];
-  if (facts.policy !== undefined) parts.push(` (policy: ${facts.policy})`);
-  return `${parts.join('')}.`;
+
+/** 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) {
+  return {
+    sheets: document.sheets.map(sheet => sheetView(sheet)),
+    ...(document.csv !== undefined && {
+      csv: document.csv
+    })
+  };
 }
-function missingSentence(facts) {
-  const parts = [`"${facts.field}" is missing`, stepClause(facts)];
-  if (facts.policy !== undefined) parts.push(`; left ${facts.policy === 'null' ? 'null' : facts.policy} by policy`);
-  if (facts.hint !== undefined) parts.push(`; ${facts.hint}`);
-  return `${parts.join('')}.`;
+function sheetView(sheet) {
+  return {
+    name: sheet.name,
+    hidden: sheet.hidden === true,
+    hiddenRows: sheet.hiddenRows === undefined ? [] : [...sheet.hiddenRows],
+    columnCount: Math.max(0, ...sheet.rows.map(row => row.length)),
+    rows: sheet.rows.map(row => row.map(cell => cellView(cell))),
+    merges: (sheet.merges ?? []).flatMap(reference => {
+      const range = rangeOf(reference);
+      return range === undefined ? [] : [{
+        ref: reference,
+        ...range
+      }];
+    })
+  };
 }
-function stepClause(facts) {
-  const boundId = facts.boundId ?? facts.field;
-  const step = facts.step;
-  if (step === undefined) return ': no step in this recipe binds its source';
-  const label = step.stepId === undefined ? describeStepType(step.stepType) : `${describeStepType(step.stepType)} "${step.stepId}"`;
-  if (step.outcome === 'not-found') return `: no step in this recipe binds "${boundId}"`;
-  if (step.outcome === 'skipped') return `: ${label} (${step.path}), which binds "${boundId}", was skipped${step.error === undefined ? '' : ` (${step.error})`}`;
-  if (step.outcome === 'retried') return `: ${label} (${step.path}), which binds "${boundId}", had to retry${step.error === undefined ? '' : ` (${step.error})`} and still found nothing for "${facts.field}"`;
-  return `: ${label} (${step.path}) ran and bound "${boundId}", but "${facts.field}" reads ${sourceOf(facts)} from it, which was empty`;
+function cellView(cell) {
+  return {
+    value: cell,
+    type: cellType(cell)
+  };
 }
-function sourceOf(facts) {
-  return facts.trace?.from === undefined ? 'a path' : JSON.stringify(facts.trace.from);
+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)
+  };
 }
-/** A step's type read as a short phrase, matching the Steps outline's own vocabulary (studio plan §4.1: "Go to…", "Read… from…"). */
-function describeStepType(stepType) {
-  switch (stepType) {
-    case 'extract':
-      {
-        return 'the Read step';
-      }
-    case 'request':
-      {
-        return 'the request step';
-      }
-    case 'forEach':
-      {
-        return 'the loop';
-      }
-    case 'paginate':
-      {
-        return 'the pagination';
-      }
-    case 'goto':
-      {
-        return 'the Go to step';
-      }
-    default:
-      {
-        return `the ${stepType} step`;
-      }
-  }
+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
+  };
 }
 
 /**
- * Explains one missing or rejected value from a recipe's last sample run
- * (issue #92's Why? tab, studio plan §4.4): the mapping trace and scope
- * snapshot `run-sample` kept, the recipe's own rule and field for the
- * missing-value policy, and the step that bound the value's source id — did
- * it run, was it skipped, or does no step in this recipe bind it at all.
+ * 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 folder - The workspace folder (to re-read the recipe pair: the last
- *   run only kept the run's own data, not the recipe text, and a save may
- *   have happened since).
- * @param cache - The server's last-run cache (`sample-run`'s `LastRunCache`).
- * @param loadPair - Loads the input/output recipe pair; injected so this
- *   stays testable without a real workspace folder (`sample-run`'s
- *   `loadRecipePair` in production).
- * @param target - What was clicked.
- * @returns The explanation.
- * @throws Error when no sample run has finished for this recipe yet, or the target does not name a real record/field.
+ * @param document - The read deck.
+ * @returns The view.
  */
-async function explainWhy(folder, cache, loadPair, target) {
-  const entry = lastRunOf(cache, target.recipeId);
-  if (entry === undefined) throw new Error(`no finished sample run for "${target.recipeId}" yet — run a sample first`);
-  const {
-    input,
-    output
-  } = await loadPair(folder, target.recipeId);
-  return target.kind === 'rejected' ? explainRejected(target.recipeId, input, output, entry.result.rejectedRecords, entry.result.steps, target.rejectedIndex) : explainMissing(target.recipeId, input, output, entry.result.records, entry.result.steps, target.recordIndex, target.field);
+function deckDocumentView(document) {
+  return {
+    width: document.width,
+    height: document.height,
+    slides: document.slides.map(slide => slideView(slide, document.height))
+  };
 }
-function explainRejected(recipeId, input, output, rejectedRecords, steps, index) {
-  const rejected = rejectedRecords[index];
-  if (rejected === undefined) throw new Error(`no rejected record at index ${index}`);
-  const rule = ruleFor(input.mapping, rejected.field);
-  const field = fieldFor(output.fields, rejected.field);
-  const policy = field === undefined ? undefined : resolveMissingPolicy(field, output, rule);
-  const boundId = boundIdOf(rule);
-  const step = boundId === undefined ? undefined : findStep(input.steps, boundId, steps);
-  const hint = hintFor(rejected.scope, boundId);
-  const sentence = buildWhySentence({
-    field: rejected.field,
-    outcome: 'rejected',
-    reason: rejected.reason,
-    policy,
-    boundId,
-    step,
-    hint
-  });
+function slideView(slide, slideHeight) {
   return {
-    sentence,
-    field: rejected.field,
-    recipeId,
-    outcome: 'rejected',
-    reason: rejected.reason,
-    policy,
-    stepPath: step?.path
+    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 explainMissing(recipeId, input, output, records, steps, index, field) {
-  const record = records[index];
-  if (record === undefined) throw new Error(`no record at index ${index}`);
-  const trace = record.mapping?.[field];
-  const rule = ruleFor(input.mapping, field);
-  const fieldSpec = fieldFor(output.fields, field);
-  const policy = fieldSpec === undefined ? undefined : resolveMissingPolicy(fieldSpec, output, rule);
-  const boundId = boundIdOf(rule);
-  const step = boundId === undefined ? undefined : findStep(input.steps, boundId, steps);
-  const hint = hintFor(record.scope, boundId);
-  const sentence = buildWhySentence({
-    field,
-    outcome: 'missing',
-    policy,
-    trace,
-    boundId,
-    step,
-    hint
-  });
+function shapeView(shape) {
   return {
-    sentence,
-    field,
-    recipeId,
-    outcome: 'missing',
-    policy,
-    stepPath: step?.path
+    x: shape.x,
+    y: shape.y,
+    width: shape.width,
+    height: shape.height,
+    text: shape.text,
+    ...(shape.placeholder !== undefined && {
+      placeholder: shape.placeholder
+    })
+  };
+}
+function chartView(chart) {
+  return {
+    type: chart.type,
+    ...(chart.title !== undefined && {
+      title: chart.title
+    }),
+    series: chart.series.map(series => ({
+      name: series.name,
+      categories: [...series.categories],
+      values: [...series.values]
+    }))
   };
 }
 /**
- * The rule bound to one output field path: a direct match on `input.mapping`
- * (its keys are themselves dotted target paths — `stock.inStock`, `tax` —
- * `map-record.use-case.ts` writes each with `setPath`), or, for a path
- * inside an `each` list's items (`variants[1].size`), the item's own rule
- * inside the list rule's `fields`. Only one level of `each` nesting is
- * resolved; a field inside a nested `each` (an `each` of `each`) is not —
- * out of this phase's scope.
+ * Groups a slide's shapes into visual rows the same way `deck-table.algorithm.ts`'s
+ * own (core-internal) `shapeTables` does: each shape is one cell, `y`
+ * flipped to the PDF-style bottom-up convention `rowsOfCells` (and the whole
+ * table-reading pipeline it feeds) works in, so the grouping this returns is
+ * byte-for-byte what `findDeckTables(document, { shapes: true })` groups at
+ * run time — a pick built from it matches for real, not just visually.
+ *
+ * @param shapes - The slide's shapes, in reading order.
+ * @param slideHeight - The deck's slide height, in points (`DeckDocument.height`).
+ * @returns Each row's shape indices, left to right; a blank shape (whitespace-only text) is never part of a row.
  */
-function ruleFor(mapping, path) {
-  const direct = mapping[path];
-  if (direct !== undefined) return direct;
-  const match = /^([^[]+)\[\d+\]\.(.+)$/.exec(path);
-  if (match === null) return undefined;
-  const parent = mapping[match[1]];
-  return parent !== undefined && 'each' in parent ? parent.fields[match[2]] : undefined;
-}
-/** The output field spec at one dotted path (`stock.inStock`, `variants[1].size`), walking `object`/`array` members the same way `map-record.use-case.ts` builds them. */
-function fieldFor(fields, path) {
-  let current = fields;
-  let field;
-  for (const token of path.split('.')) {
-    const match = /^([^[]+)(\[\d+\])?$/.exec(token);
-    if (match === null || current === undefined) return undefined;
-    field = current[match[1]];
-    if (field === undefined) return undefined;
-    current = match[2] === undefined ? field.fields : field.items?.fields;
-  }
-  return field;
-}
-/** The leading id a `from` rule reads (`item` of `item.description`, `price` of `price`); `undefined` for an `each` rule, a `.` (self), or a rule this run found nothing to say about. */
-function boundIdOf(rule) {
-  if (rule === undefined || !('from' in rule)) return undefined;
-  const first = Array.isArray(rule.from) ? rule.from[0] : rule.from;
-  const match = /^([A-Z_][\w-]*)/i.exec(first);
-  return match?.[1];
+function shapeRowsOf(shapes, slideHeight) {
+  const indexOf = new Map();
+  const cells = shapes.flatMap((shape, index) => {
+    const text = shape.text.replaceAll(/\s+/g, ' ').trim();
+    if (text === '') return [];
+    const cell = {
+      x: shape.x,
+      y: slideHeight - shape.y - shape.height,
+      width: shape.width,
+      height: shape.height,
+      text
+    };
+    indexOf.set(cell, index);
+    return [cell];
+  });
+  return rowsOfCells(cells).map(row => row.cells.map(cell => indexOf.get(cell)));
 }
+
+const TEXT_LIMIT$1 = 120;
 /**
- * Finds the step of the recipe whose `id` or `as` (a `forEach`'s loop
- * variable) is `boundId`, walking into `forEach`/`paginate`/`if` bodies the
- * same way `scope-outline`'s outline does, and reports how it went over the
- * whole sample run from `stepSummaries` (`sample-run`'s per-path summary).
+ * Builds the document tree for `document-tree` (studio plan §3.4, issue
+ * #94's 5a) from the body `page-snapshot`'s `take-snapshot.use-case.ts`
+ * already fetched — no second read of the document.
  *
- * @returns `undefined` only when nothing in `steps` looks like a step at all; a `boundId` that names no real step still gets a fact, with `outcome: 'not-found'`.
+ * @param body - The parsed body (`HttpBody`); YAML and JSON Lines both
+ * arrive here already normalised to `{ kind: 'json' }` by `http.client.ts`.
+ * @returns The tree.
+ * @throws Error when `body`'s kind is not `json` or `xml` (PDF, workbook and
+ * deck documents get their own canvases — 5b/5c/5d, not this mapper).
  */
-function findStep(steps, boundId, stepSummaries) {
-  const found = search(steps, boundId, 'steps');
-  if (found === undefined) return {
-    path: '',
-    stepType: '',
-    outcome: 'not-found'
+function documentTreeView(body) {
+  if (body.kind === 'json') return {
+    format: 'json',
+    root: jsonNode(body.data, '$', 'root')
   };
-  const summary = stepSummaries.find(entry => entry.path === found.path);
+  if (body.kind === 'xml') return xmlTreeView(body.xml);
+  throw new Error(`document-tree: "${body.kind}" has no tree canvas (only "json" and "xml" bodies do)`);
+}
+function listFields(path, context) {
+  if (context === undefined) return {};
   return {
-    path: found.path,
-    stepType: found.step.type ?? 'unknown',
-    stepId: found.step.id,
-    outcome: summary?.outcome ?? 'ran',
-    error: summary?.error
+    listPath: context.generalPrefix + path.slice(context.itemPrefix.length),
+    listCount: context.count
   };
 }
-function search(steps, boundId, prefix) {
-  for (const [index, step] of steps.entries()) {
-    const path = `${prefix}.${index}`;
-    if (step.id === boundId || step.as === boundId) return {
-      path,
-      step
+function jsonNode(value, path, label, context) {
+  if (Array.isArray(value)) {
+    const children = value.map((item, index) => {
+      const itemPath = `${path}[${index}]`;
+      return jsonNode(item, itemPath, String(index), {
+        itemPrefix: itemPath,
+        generalPrefix: `${path}[*]`,
+        count: value.length
+      });
+    });
+    return {
+      id: path,
+      label,
+      valueType: 'array',
+      jsonpath: path,
+      ...listFields(path, context),
+      children
     };
-    if (step.steps !== undefined) {
-      const nested = search(step.steps, boundId, `${path}.steps`);
-      if (nested !== undefined) return nested;
-    }
-    if (step.else !== undefined) {
-      const nested = search(step.else, boundId, `${path}.else`);
-      if (nested !== undefined) return nested;
+  }
+  if (value !== null && typeof value === 'object') {
+    const entries = Object.entries(value);
+    // A plain object passes its own context through unchanged: only an array (or, in XML, a repeated element) starts a new one.
+    const children = entries.map(([key, item]) => jsonNode(item, `${path}${propertyAccess(key)}`, key, context));
+    return {
+      id: path,
+      label,
+      valueType: 'object',
+      jsonpath: path,
+      ...listFields(path, context),
+      children
+    };
+  }
+  return {
+    id: path,
+    label,
+    valueType: leafType(value),
+    jsonpath: path,
+    preview: previewOf(value),
+    ...listFields(path, context),
+    children: []
+  };
+}
+function leafType(value) {
+  if (value === null) return 'null';
+  if (typeof value === 'string') return 'string';
+  if (typeof value === 'number') return 'number';
+  if (typeof value === 'boolean') return 'boolean';
+  return 'string';
+}
+function previewOf(value) {
+  const text = value === null ? 'null' : typeof value === 'string' ? value : JSON.stringify(value);
+  return text.length > TEXT_LIMIT$1 ? `${text.slice(0, TEXT_LIMIT$1)}…` : text;
+}
+/** A JSONPath property step: dot notation for a plain identifier, bracket notation (quoted) otherwise — jsonpath-plus accepts both, but only dot notation round-trips through a person reading the card. */
+function propertyAccess(key) {
+  return /^[A-Z_]\w*$/i.test(key) ? `.${key}` : `[${JSON.stringify(key)}]`;
+}
+// --- XML ---
+const DEFAULT_NS_PREFIX = 'ns';
+function xmlTreeView(xml) {
+  const document = parseXml(xml, 'document.xml');
+  const root = document.documentElement;
+  if (root === null) throw new Error('document-tree: the XML document has no root element');
+  const namespaces = declaredNamespaces(root);
+  const tree = xmlNode(root, '', namespaces, undefined);
+  return {
+    format: 'xml',
+    root: tree,
+    ...(Object.keys(namespaces).length > 0 && {
+      namespaces
+    })
+  };
+}
+/** Every `xmlns:*` the root declares, plus a synthesised prefix (`ns`, `ns2`, …) for a bare default `xmlns="…"` — XPath 1.0 has no default namespace, so a query needs a prefix even when the markup does not use one (mirrors `xpath.algorithm.ts`'s own `declaredPrefixes`, extended for the default case that function leaves out on purpose — it is resolved automatically there, but a *picked* card still needs to name it explicitly in `namespaces`). */
+function declaredNamespaces(root) {
+  const namespaces = {};
+  let synthetic = 0;
+  for (const attribute of root.attributes) {
+    if (attribute.prefix === 'xmlns') namespaces[attribute.localName] = attribute.value;else if (attribute.name === 'xmlns') {
+      synthetic += 1;
+      namespaces[synthetic === 1 ? DEFAULT_NS_PREFIX : `${DEFAULT_NS_PREFIX}${synthetic}`] = attribute.value;
     }
   }
-  return undefined;
+  return namespaces;
+}
+function prefixFor(element, namespaces) {
+  if (element.namespaceURI === null || element.namespaceURI === undefined) return undefined;
+  if (element.prefix !== null && element.prefix !== undefined && element.prefix !== '') return element.prefix;
+  return Object.entries(namespaces).find(([, uri]) => uri === element.namespaceURI)?.[0];
+}
+function qualifiedName(element, namespaces) {
+  const prefix = prefixFor(element, namespaces);
+  return prefix === undefined ? element.localName ?? element.tagName : `${prefix}:${element.localName ?? element.tagName}`;
+}
+function xmlNode(element, parentPath, namespaces, context) {
+  const name = qualifiedName(element, namespaces);
+  const siblingIndex = elementSiblingIndex(element);
+  const siblingCount = elementSiblingCount(element);
+  const step = siblingCount > 1 ? `${name}[${siblingIndex}]` : name;
+  const path = `${parentPath}/${step}`;
+  // I am one of several same-named siblings: my own listPath generalises myself, and my children inherit *my* context (innermost repetition wins) instead of whatever ancestor context I received.
+  const selfContext = siblingCount > 1 ? {
+    itemPrefix: path,
+    generalPrefix: `${parentPath}/${name}`,
+    count: siblingCount
+  } : context;
+  const childContext = siblingCount > 1 ? selfContext : context;
+  const attributes = elementAttributes(element);
+  const childElements = [...element.childNodes].filter(node => node.nodeType === 1);
+  const children = [...Object.entries(attributes).map(([key, value]) => attributeNode(key, value, path, childContext)), ...childElements.map(child => xmlNode(child, path, namespaces, childContext))];
+  const text = childElements.length === 0 ? textOf(element) : undefined;
+  return {
+    id: path,
+    label: name,
+    valueType: 'element',
+    xpath: path,
+    ...listFields(path, selfContext),
+    ...(Object.keys(attributes).length > 0 && {
+      attributes
+    }),
+    ...(text !== undefined && {
+      preview: text,
+      valueType: childElements.length === 0 ? 'string' : 'element'
+    }),
+    children
+  };
+}
+function attributeNode(name, value, elementPath, context) {
+  const path = `${elementPath}/@${name}`;
+  return {
+    id: path,
+    label: `@${name}`,
+    valueType: 'string',
+    xpath: path,
+    preview: previewOf(value),
+    ...listFields(path, context),
+    children: []
+  };
+}
+function elementAttributes(element) {
+  return Object.fromEntries([...element.attributes].filter(attribute => attribute.prefix !== 'xmlns' && attribute.name !== 'xmlns').map(attribute => [attribute.name, attribute.value]));
+}
+function elementSiblingIndex(element) {
+  let index = 1;
+  let sibling = element.previousSibling;
+  while (sibling !== null) {
+    if (sibling.nodeType === 1 && sibling.tagName === element.tagName) index += 1;
+    sibling = sibling.previousSibling;
+  }
+  return index;
+}
+function elementSiblingCount(element) {
+  const parent = element.parentNode;
+  if (parent === null) return 1;
+  return [...parent.childNodes].filter(node => node.nodeType === 1 && node.tagName === element.tagName).length;
+}
+function textOf(element) {
+  const text = (element.textContent ?? '').trim().replaceAll(/\s+/g, ' ');
+  return text === '' ? undefined : previewOf(text);
 }
 
 /**
- * Handles `explain-why` (issue #92's Why? tab): builds the sentence for a
- * missing or rejected value from the recipe's last sample run, kept in
- * `state.lastRuns` by `handleRunSample`.
+ * Builds the PDF canvas's view model (studio plan §3.4, issue #94's 5b) from
+ * an already-read `PdfDocument` (`take-snapshot`'s cached body — no second
+ * read of the file): every cell and row `readPdf` found, in PDF points, plus
+ * per-page counts and whether the page has a text layer at all. Table-specific
+ * diagnostics (the header row, the column bands, the wrapped-row regrouping)
+ * are not here — they depend on a `table` extract's own options, so they come
+ * from `table-preview.use-case.ts` instead, computed live as those options
+ * change.
  *
- * @param state - The server state: `folder` must already be set (`open-workspace` first).
- * @param command - The command.
- * @returns The explanation.
- * @throws Error when no workspace is open, no sample run has finished for the target's recipe, or the target does not name a real record/field.
+ * @param document - The read PDF.
+ * @returns The view.
  */
-async function handleExplainWhy(state, command) {
-  if (state.folder === undefined) throw new Error('open a workspace first');
-  return explainWhy(state.folder, state.lastRuns, loadRecipePair, command.target);
+function pdfDocumentView(document) {
+  return {
+    pages: document.pages.map(page => ({
+      number: page.number,
+      width: page.width,
+      height: page.height,
+      rows: page.rows.map(row => ({
+        top: row.top,
+        bottom: row.bottom,
+        cells: row.cells.map(cell => ({
+          x: cell.x,
+          y: cell.y,
+          width: cell.width,
+          height: cell.height,
+          text: cell.text
+        }))
+      })),
+      rowCount: page.rows.length,
+      cellCount: page.rows.reduce((total, row) => total + row.cells.length, 0),
+      hasTextLayer: page.rows.length > 0
+    }))
+  };
 }
 
 /**
- * Fetches an input recipe's start page as the engine would see it: a fresh
- * Playwright page in web mode, core's HTTP client in api mode. Returns plain
- * text: the page's HTML, or a readable rendering of a non-HTML api response.
- * No rewriting, no script stripping, no node ids yet: that is phase 2's
- * `page-snapshot` proper (studio plan, #91). Provisional for phase 0 in two
- * ways, both worth knowing before relying on it: it opens a bare page
- * without running the recipe's own steps first, so a start point behind a
- * `session.bootstrap` login shows what an anonymous visitor sees; and it
- * launches a fresh browser or HTTP context per call, one page then closes
- * it, rather than reusing whatever the last sample run had open.
+ * 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 input - The input recipe; only `mode` and the first `start` point are used.
- * @param browser - Browser launch settings for web mode (an executable path override, headless…).
- * @returns The page's content as plain text.
- * @throws Error when the recipe has no start point.
+ * 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.
  */
-async function fetchStartPage(input, browser) {
-  const point = input.start[0];
-  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
-  return input.mode === 'web' ? fetchWeb(point.url, browser) : fetchApi(point.url);
-}
-async function fetchWeb(url, browser) {
-  const client = await BrowserClient.launch(browser);
+function previewPdfTable(document, options) {
+  let query;
   try {
-    const session = await client.newSession();
-    try {
-      await session.page.goto(url);
-      return await session.page.content();
-    } finally {
-      await session.close();
-    }
-  } finally {
-    await client.close();
+    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
+    }))
+  };
 }
-async function fetchApi(url) {
-  const client = await HttpClient.open({});
+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 {
-    const response = await client.send({
-      url
+    return new RegExp(source, 'i');
+  } catch (error) {
+    throw new Error(`${where}: invalid pattern ${source} (${error.message})`, {
+      cause: error
     });
-    return textOf$1(response.body);
-  } finally {
-    await client.dispose();
   }
 }
-/** Every body kind the studio can show as text today; others get a placeholder rather than a crash. */
-function textOf$1(body) {
-  if (body.kind === 'html') return body.html;
-  if (body.kind === 'text') return body.text;
-  if (body.kind === 'json') return JSON.stringify(body.data, null, 2);
-  return `[${body.kind} document: the content pane shows HTML and JSON responses for now]`;
+/**
+ * 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
+    }))
+  };
 }
 
-/** The attribute `hiddenMarksScript` stamps on an element hidden on the live page. */
-const HIDDEN_ATTRIBUTE = 'data-oc-hidden';
 /**
- * The in-page script `take-snapshot.use-case.ts` runs with `page.evaluate`
- * *before* `page.content()`, so a `display: none`/`visibility: hidden`/
- * zero-size element carries `data-oc-hidden="1"` into the captured markup
- * (studio plan §3.1, issue #91) — the only way to know an element was
- * hidden on the live page, since a static parse of the HTML afterwards has
- * no computed style to ask.
+ * 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.
  *
- * Kept as a plain string, not a TypeScript function passed to
- * `page.evaluate`, because it references `window`/`document` as globals: `AGENTS.md`'s
- * "things that bit before" calls out that in-page functions must not do
- * that (the repo's `isolated-functions` lint rule), and every existing
- * `page.evaluate` call with real DOM logic in this codebase (see
- * `packages/core/src/captcha/resolve-captcha.use-case.ts`) already uses
- * this same string-template shape.
+ * @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 attribute - The attribute to stamp; defaults to `HIDDEN_ATTRIBUTE` (parameterised for tests and for a future caller that wants a different name).
- * @returns A self-invoking script, ready for `page.evaluate(hiddenMarksScript())`.
+ * @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 hiddenMarksScript(attribute = HIDDEN_ATTRIBUTE) {
-  return `(() => {
-    var attribute = ${JSON.stringify(attribute)}
-    var elements = document.querySelectorAll('*')
-    for (var i = 0; i < elements.length; i++) {
-      var element = elements[i]
-      var style = window.getComputedStyle(element)
-      var rect = element.getBoundingClientRect()
-      var hidden = style.display === 'none' || style.visibility === 'hidden' || (rect.width === 0 && rect.height === 0)
-      if (hidden) element.setAttribute(attribute, '1')
-    }
-  })()`;
+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);
 }
 
-/** Attributes that carry a URL and are rewritten to absolute; `srcset` is handled separately (it carries several). */
-const URL_ATTRIBUTES = ['href', 'src', 'action', 'poster'];
-/** Schemes left untouched: they are not a location `new URL(value, base)` should resolve, or already carry their own meaning. */
-const SKIP_SCHEME = /^(?:javascript|mailto|tel|data|about):/i;
 /**
- * Rewrites captured HTML into what the content pane's sandboxed iframe shows
- * (studio plan §3.1, issue #91): every URL made absolute against `baseUrl`,
- * a `<base>` injected, every `<script>` removed, forms disabled (`onsubmit`
- * stripped, fields made read-only), `<meta http-equiv="refresh">` stripped
- * (it would otherwise navigate the sandboxed frame on its own), and every
- * element given a stable `data-oc-node` id, in document order, for the
- * picker overlay and `selector-inference` to address specific nodes by.
+ * 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.
  *
- * Purely a markup transform: it does not know whether an element is hidden
- * on the live page (`display: none`, `visibility: hidden`, zero size) — in
- * web mode that is `hidden-marks.algorithm.ts`'s job, run against the live
- * page *before* this function ever sees the markup, so a `data-oc-hidden`
- * attribute it wrote just survives serialisation untouched here.
+ * @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.
  *
- * @param html - The captured document (`page.content()` in web mode, the fetched body in api mode).
- * @param baseUrl - The page's own URL, for resolving relative links and as the `<base>`.
- * @returns The rewritten document and how many elements it stamped.
+ * @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 rewriteDocument(html, baseUrl) {
-  const $ = load(html);
-  if ($('head').length === 0) $('html').prepend('<head></head>');
-  const head = $('head').first();
-  head.find('base').remove();
-  head.prepend(`<base href="${escapeAttribute(baseUrl)}">`);
-  $('meta').each((_index, element) => {
-    if (($(element).attr('http-equiv') ?? '').toLowerCase() === 'refresh') $(element).remove();
-  });
-  $('script').remove();
-  $('form').removeAttr('onsubmit');
-  $('input, textarea').attr('readonly', 'readonly');
-  $('select, button, input[type="submit"], input[type="button"]').attr('disabled', 'disabled');
-  $('*').each((_index, element) => {
-    const node = $(element);
-    for (const attribute of URL_ATTRIBUTES) {
-      const value = node.attr(attribute);
-      if (value !== undefined) node.attr(attribute, resolveUrl(value, baseUrl) ?? value);
-    }
-    const srcset = node.attr('srcset');
-    if (srcset !== undefined) node.attr('srcset', rewriteSrcset(srcset, baseUrl));
-  });
-  let nodeCount = 0;
-  $('*').each((_index, element) => {
-    $(element).attr(NODE_ID_ATTRIBUTE, `n${nodeCount}`);
-    nodeCount += 1;
-  });
+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 {
-    html: $.html(),
-    nodeCount
+    input,
+    output: parseOutputRecipe(outputDocument.content, outputDocument.source)
   };
 }
-/** Resolves one URL against `baseUrl`; a scheme that is not a location (`javascript:`, `data:`…), or a value `new URL` cannot parse, is left as it was. */
-function resolveUrl(value, baseUrl) {
-  const trimmed = value.trim();
-  if (trimmed === '' || SKIP_SCHEME.test(trimmed)) return undefined;
-  try {
-    return new URL(trimmed, baseUrl).href;
-  } catch {
-    return undefined;
-  }
-}
-/** `srcset`'s own micro-syntax: comma-separated `url descriptor?` pairs. Malformed entries are passed through unresolved rather than dropped. */
-function rewriteSrcset(value, baseUrl) {
-  return value.split(',').map(candidate => {
-    const trimmed = candidate.trim();
-    const spaceAt = trimmed.indexOf(' ');
-    const url = spaceAt === -1 ? trimmed : trimmed.slice(0, spaceAt);
-    const descriptor = spaceAt === -1 ? '' : trimmed.slice(spaceAt);
-    return `${resolveUrl(url, baseUrl) ?? url}${descriptor}`;
-  }).join(', ');
+function kindOf(content) {
+  return content?.kind;
 }
-function escapeAttribute(value) {
-  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
+function idOf(content) {
+  return content?.id;
 }
 
 /**
- * Captures the snapshot the content pane shows (studio plan §3.1, issue
- * #91): runs the recipe up to `stepPath`, serialises the document, marks
- * hidden elements in web mode, and hands it to `rewrite-document.mapper.ts`
- * for display.
- *
- * `stepPath` is accepted (and cached against, by `snapshot.store.ts`) for
- * the API the UI needs — one snapshot per selected step — but v1 only
- * actually *captures* `"start"`: the first `start` point, before any step
- * of the recipe has run, the same reach `fetch-start-page.use-case.ts` (phase
- * 0) already had. Snapshotting mid-recipe (after an arbitrary later step)
- * needs a "stop the crawl after step X and hand back the live page/document"
- * hook in `crawl-execution` that does not exist yet; building one was out of
- * this phase's budget (see this phase's final report for the tradeoff this
- * was weighed against). Any other `stepPath` throws, clearly, rather than
- * silently returning the start page under a misleading label.
+ * 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 input - The input recipe; only `mode` and the first `start` point are used.
- * @param stepPath - The step to snapshot after, e.g. `"start"` or `"steps.2"` (`scope-outline`'s path format).
- * @param browser - Browser launch settings for web mode.
- * @returns The rewritten snapshot.
- * @throws Error when the recipe has no start point, or `stepPath` is not `"start"`.
+ * @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.
+ * @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 takeSnapshot(input, stepPath, browser) {
-  if (stepPath !== 'start') throw new Error(`takeSnapshot: "${stepPath}" is not supported yet — only "start" (the first start point, before any step runs) is; see this function's doc comment`);
-  const point = input.start[0];
-  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
-  return input.mode === 'web' ? snapshotWeb(point.url, browser) : snapshotApi(point.url);
-}
-async function snapshotWeb(url, browser) {
-  const client = await BrowserClient.launch(browser);
-  try {
-    const session = await client.newSession();
-    try {
-      await session.page.goto(url);
-      await session.page.evaluate(hiddenMarksScript(HIDDEN_ATTRIBUTE));
-      const html = await session.page.content();
-      const baseUrl = session.page.url();
-      const rewritten = rewriteDocument(html, baseUrl);
-      return {
-        ...rewritten,
-        baseUrl
-      };
-    } finally {
-      await session.close();
+async function runSample(folder, recipeId, budget, callbacks, browser) {
+  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,
+    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);
+      }
     }
-  } finally {
-    await client.close();
+  });
+  const result = runToResult(crawler, set, records, rejectedRecords, steps);
+  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
+    });
   }
 }
-async function snapshotApi(url) {
-  const client = await HttpClient.open({});
+async function runToResult(crawler, set, records, rejectedRecords, steps) {
   try {
-    const response = await client.send({
-      url
-    });
-    const rewritten = rewriteDocument(textOf(response.body), url);
+    const report = await crawler.run(set);
+    const recipe = report.recipes[0];
     return {
-      ...rewritten,
-      baseUrl: url
+      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()]
     };
   } finally {
-    await client.dispose();
+    await crawler.close();
   }
 }
-/** Every body kind the studio can show as text today; others get a placeholder rather than a crash (mirrors `fetch-start-page.use-case.ts`'s own `textOf`). */
-function textOf(body) {
-  if (body.kind === 'html') return body.html;
-  if (body.kind === 'text') return body.text;
-  if (body.kind === 'json') return `<pre>${JSON.stringify(body.data, null, 2)}</pre>`;
-  return `<p>[${body.kind} document: the content pane shows HTML and JSON responses for now]</p>`;
-}
 
-/** @returns An empty cache, for a freshly opened workspace. */
-function createSnapshotCache() {
+/** @returns A fresh, empty cache. */
+function createLastRunCache() {
   return {
     entries: new Map()
   };
 }
-/** @returns The cached snapshot for `recipeId`/`path`, or `undefined` when none was taken yet. */
-function cachedSnapshot(cache, recipeId, path) {
-  return cache.entries.get(keyOf(recipeId, path));
-}
-/** Records a freshly taken snapshot, replacing whatever was cached for the same recipe and step path. */
-function putSnapshot(cache, recipeId, path, snapshot) {
-  cache.entries.set(keyOf(recipeId, path), snapshot);
+/** 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
+  });
 }
-function keyOf(recipeId, path) {
-  return `${recipeId}:${path}`;
+/** @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 `fetch-start-page`: loads the named input recipe from the current
- * workspace and fetches its start point (see `page-snapshot`'s own caveats:
- * no session bootstrap, a fresh browser or HTTP context per call).
+ * A best-effort hint about what a missing value's bound id actually held in
+ * the scope snapshot: the keys of an object, or the length of a list — the
+ * fallback when there is no per-item DOM snapshot to compare a selector
+ * against (see `why-sentence.mapper.ts`'s doc comment for why the richer,
+ * "the item has `.price_new`" hint is out of this phase's scope).
  *
- * @param state - The server state: `folder` must already be set.
- * @param command - The command.
- * @returns The page's content as plain text.
- * @throws Error when no workspace is open, or the recipe cannot be found or loaded.
+ * @param scope - The record's scope snapshot (`SampleRunRecord.scope`/`SampleRunRejected.scope`).
+ * @param boundId - The leading id the rule's `from` reads.
+ * @returns A short clause (no leading punctuation), or `undefined` when the id is not in scope or nothing useful can be said about it.
  */
-async function handleFetchStartPage(state, command) {
-  if (state.folder === undefined) throw new Error('open a workspace first');
-  const {
-    input
-  } = await loadRecipePair(state.folder, command.recipeId);
-  const html = await fetchStartPage(input, state.browser);
-  return {
-    html
-  };
+function hintFor(scope, boundId) {
+  if (scope === undefined || boundId === undefined) return undefined;
+  const value = scope[boundId];
+  if (value === undefined) return undefined;
+  if (Array.isArray(value)) return value.length === 0 ? undefined : `"${boundId}" is a list of ${value.length}, not a single value`;
+  if (typeof value === 'object' && value !== null) {
+    const keys = Object.keys(value);
+    return keys.length === 0 ? undefined : `"${boundId}" has: ${keys.slice(0, 5).join(', ')}`;
+  }
+  return undefined;
 }
 
-const GENERATED_ID = /^(?:react-|radix-|:r|ember|css-|mui-|headlessui-)/i;
 /**
- * The path from the document root to `node`, one level per ancestor. Two
- * elements that share an ancestor produce identical levels up to that
- * ancestor and diverge exactly where their parents stop being the same node
- * — `list-inference.algorithm.ts` leans on that to find the nearest pair of
- * siblings two picks belong to, without ever touching cheerio again.
+ * Builds the Why? tab's sentence (studio plan §4.4, issue #92) from the
+ * facts `why.use-case.ts` gathers: the value the mapping read (and each
+ * transform's effect on it), the step that bound its source id and whether
+ * it ran, was skipped, or bound nothing this recipe knows of, the
+ * missing-value policy that applied, and a hint about what was actually
+ * there instead.
  *
- * @param $ - The parsed document.
- * @param node - The element to describe.
- * @returns The path, root first.
+ * This is the scope-snapshot-only half of the design: phase 2's per-item DOM
+ * snapshot (the CSS-selector "the item has `.price_new`" hint the issue's
+ * example shows) is not wired in here — `sample-run` keeps the mapping's
+ * scope snapshot (bound ids and their values), not a per-`forEach`-item DOM
+ * capture, and building that link is a bigger integration than this phase's
+ * budget covers (see this package's `page-snapshot` slice, which captures a
+ * step's page for the content pane, not per-iteration). `hint`, when given,
+ * is instead built from the scope snapshot itself (`item-hint.algorithm.ts`).
+ *
+ * @param facts - What is known about the value.
+ * @returns One sentence, always ending in a period.
  */
-function domPathOf($, node) {
-  const chain = [];
-  let current = node;
-  while (current !== undefined && current.length > 0 && isElement(current.get(0))) {
-    chain.unshift(current);
-    const parent = current.parent();
-    current = parent.length > 0 ? parent : undefined;
-  }
-  return chain.map(element => levelOf($, element));
-}
-function levelOf($, element) {
-  const node = element.get(0);
-  const tag = node.tagName.toLowerCase();
-  const attrs = {};
-  const entries = Object.entries(node.attribs ?? {});
-  for (const [name, value] of entries) attrs[name] = value;
-  const classes = (attrs.class ?? '').split(/\s+/).filter(token => token.length > 0);
-  const siblings = element.parent().length > 0 ? element.parent().children(tag) : $.root().children(tag);
-  const index = siblings.toArray().indexOf(node) + 1;
-  return {
-    tag,
-    id: attrs.id,
-    classes,
-    attrs,
-    index: Math.max(index, 1),
-    siblingCount: Math.max(siblings.length, 1)
-  };
+function buildWhySentence(facts) {
+  return facts.outcome === 'rejected' ? rejectedSentence(facts) : missingSentence(facts);
 }
-function isElement(node) {
-  return node !== undefined && node.type === 'tag';
+function rejectedSentence(facts) {
+  const parts = [`"${facts.field}" was rejected: ${facts.reason ?? 'the engine gave no reason'}`];
+  if (facts.policy !== undefined) parts.push(` (policy: ${facts.policy})`);
+  return `${parts.join('')}.`;
+}
+function missingSentence(facts) {
+  const parts = [`"${facts.field}" is missing`, stepClause(facts)];
+  if (facts.policy !== undefined) parts.push(`; left ${facts.policy === 'null' ? 'null' : facts.policy} by policy`);
+  if (facts.hint !== undefined) parts.push(`; ${facts.hint}`);
+  return `${parts.join('')}.`;
+}
+function stepClause(facts) {
+  const boundId = facts.boundId ?? facts.field;
+  const step = facts.step;
+  if (step === undefined) return ': no step in this recipe binds its source';
+  const label = step.stepId === undefined ? describeStepType(step.stepType) : `${describeStepType(step.stepType)} "${step.stepId}"`;
+  if (step.outcome === 'not-found') return `: no step in this recipe binds "${boundId}"`;
+  if (step.outcome === 'skipped') return `: ${label} (${step.path}), which binds "${boundId}", was skipped${step.error === undefined ? '' : ` (${step.error})`}`;
+  if (step.outcome === 'retried') return `: ${label} (${step.path}), which binds "${boundId}", had to retry${step.error === undefined ? '' : ` (${step.error})`} and still found nothing for "${facts.field}"`;
+  return `: ${label} (${step.path}) ran and bound "${boundId}", but "${facts.field}" reads ${sourceOf(facts)} from it, which was empty`;
+}
+function sourceOf(facts) {
+  return facts.trace?.from === undefined ? 'a path' : JSON.stringify(facts.trace.from);
+}
+/** A step's type read as a short phrase, matching the Steps outline's own vocabulary (studio plan §4.1: "Go to…", "Read… from…"). */
+function describeStepType(stepType) {
+  switch (stepType) {
+    case 'extract':
+      {
+        return 'the Read step';
+      }
+    case 'request':
+      {
+        return 'the request step';
+      }
+    case 'forEach':
+      {
+        return 'the loop';
+      }
+    case 'paginate':
+      {
+        return 'the pagination';
+      }
+    case 'goto':
+      {
+        return 'the Go to step';
+      }
+    default:
+      {
+        return `the ${stepType} step`;
+      }
+  }
+}
+
+/**
+ * Explains one missing or rejected value from a recipe's last sample run
+ * (issue #92's Why? tab, studio plan §4.4): the mapping trace and scope
+ * snapshot `run-sample` kept, the recipe's own rule and field for the
+ * missing-value policy, and the step that bound the value's source id — did
+ * it run, was it skipped, or does no step in this recipe bind it at all.
+ *
+ * @param folder - The workspace folder (to re-read the recipe pair: the last
+ *   run only kept the run's own data, not the recipe text, and a save may
+ *   have happened since).
+ * @param cache - The server's last-run cache (`sample-run`'s `LastRunCache`).
+ * @param loadPair - Loads the input/output recipe pair; injected so this
+ *   stays testable without a real workspace folder (`sample-run`'s
+ *   `loadRecipePair` in production).
+ * @param target - What was clicked.
+ * @returns The explanation.
+ * @throws Error when no sample run has finished for this recipe yet, or the target does not name a real record/field.
+ */
+async function explainWhy(folder, cache, loadPair, target) {
+  const entry = lastRunOf(cache, target.recipeId);
+  if (entry === undefined) throw new Error(`no finished sample run for "${target.recipeId}" yet — run a sample first`);
+  const {
+    input,
+    output
+  } = await loadPair(folder, target.recipeId);
+  return target.kind === 'rejected' ? explainRejected(target.recipeId, input, output, entry.result.rejectedRecords, entry.result.steps, target.rejectedIndex) : explainMissing(target.recipeId, input, output, entry.result.records, entry.result.steps, target.recordIndex, target.field);
+}
+function explainRejected(recipeId, input, output, rejectedRecords, steps, index) {
+  const rejected = rejectedRecords[index];
+  if (rejected === undefined) throw new Error(`no rejected record at index ${index}`);
+  const rule = ruleFor(input.mapping, rejected.field);
+  const field = fieldFor(output.fields, rejected.field);
+  const policy = field === undefined ? undefined : resolveMissingPolicy(field, output, rule);
+  const boundId = boundIdOf(rule);
+  const step = boundId === undefined ? undefined : findStep(input.steps, boundId, steps);
+  const hint = hintFor(rejected.scope, boundId);
+  const sentence = buildWhySentence({
+    field: rejected.field,
+    outcome: 'rejected',
+    reason: rejected.reason,
+    policy,
+    boundId,
+    step,
+    hint
+  });
+  return {
+    sentence,
+    field: rejected.field,
+    recipeId,
+    outcome: 'rejected',
+    reason: rejected.reason,
+    policy,
+    stepPath: step?.path
+  };
+}
+function explainMissing(recipeId, input, output, records, steps, index, field) {
+  const record = records[index];
+  if (record === undefined) throw new Error(`no record at index ${index}`);
+  const trace = record.mapping?.[field];
+  const rule = ruleFor(input.mapping, field);
+  const fieldSpec = fieldFor(output.fields, field);
+  const policy = fieldSpec === undefined ? undefined : resolveMissingPolicy(fieldSpec, output, rule);
+  const boundId = boundIdOf(rule);
+  const step = boundId === undefined ? undefined : findStep(input.steps, boundId, steps);
+  const hint = hintFor(record.scope, boundId);
+  const sentence = buildWhySentence({
+    field,
+    outcome: 'missing',
+    policy,
+    trace,
+    boundId,
+    step,
+    hint
+  });
+  return {
+    sentence,
+    field,
+    recipeId,
+    outcome: 'missing',
+    policy,
+    stepPath: step?.path
+  };
+}
+/**
+ * The rule bound to one output field path: a direct match on `input.mapping`
+ * (its keys are themselves dotted target paths — `stock.inStock`, `tax` —
+ * `map-record.use-case.ts` writes each with `setPath`), or, for a path
+ * inside an `each` list's items (`variants[1].size`), the item's own rule
+ * inside the list rule's `fields`. Only one level of `each` nesting is
+ * resolved; a field inside a nested `each` (an `each` of `each`) is not —
+ * out of this phase's scope.
+ */
+function ruleFor(mapping, path) {
+  const direct = mapping[path];
+  if (direct !== undefined) return direct;
+  const match = /^([^[]+)\[\d+\]\.(.+)$/.exec(path);
+  if (match === null) return undefined;
+  const parent = mapping[match[1]];
+  return parent !== undefined && 'each' in parent ? parent.fields[match[2]] : undefined;
+}
+/** The output field spec at one dotted path (`stock.inStock`, `variants[1].size`), walking `object`/`array` members the same way `map-record.use-case.ts` builds them. */
+function fieldFor(fields, path) {
+  let current = fields;
+  let field;
+  for (const token of path.split('.')) {
+    const match = /^([^[]+)(\[\d+\])?$/.exec(token);
+    if (match === null || current === undefined) return undefined;
+    field = current[match[1]];
+    if (field === undefined) return undefined;
+    current = match[2] === undefined ? field.fields : field.items?.fields;
+  }
+  return field;
+}
+/** The leading id a `from` rule reads (`item` of `item.description`, `price` of `price`); `undefined` for an `each` rule, a `.` (self), or a rule this run found nothing to say about. */
+function boundIdOf(rule) {
+  if (rule === undefined || !('from' in rule)) return undefined;
+  const first = Array.isArray(rule.from) ? rule.from[0] : rule.from;
+  const match = /^([A-Z_][\w-]*)/i.exec(first);
+  return match?.[1];
+}
+/**
+ * Finds the step of the recipe whose `id` or `as` (a `forEach`'s loop
+ * variable) is `boundId`, walking into `forEach`/`paginate`/`if` bodies the
+ * same way `scope-outline`'s outline does, and reports how it went over the
+ * whole sample run from `stepSummaries` (`sample-run`'s per-path summary).
+ *
+ * @returns `undefined` only when nothing in `steps` looks like a step at all; a `boundId` that names no real step still gets a fact, with `outcome: 'not-found'`.
+ */
+function findStep(steps, boundId, stepSummaries) {
+  const found = search(steps, boundId, 'steps');
+  if (found === undefined) return {
+    path: '',
+    stepType: '',
+    outcome: 'not-found'
+  };
+  const summary = stepSummaries.find(entry => entry.path === found.path);
+  return {
+    path: found.path,
+    stepType: found.step.type ?? 'unknown',
+    stepId: found.step.id,
+    outcome: summary?.outcome ?? 'ran',
+    error: summary?.error
+  };
+}
+function search(steps, boundId, prefix) {
+  for (const [index, step] of steps.entries()) {
+    const path = `${prefix}.${index}`;
+    if (step.id === boundId || step.as === boundId) return {
+      path,
+      step
+    };
+    if (step.steps !== undefined) {
+      const nested = search(step.steps, boundId, `${path}.steps`);
+      if (nested !== undefined) return nested;
+    }
+    if (step.else !== undefined) {
+      const nested = search(step.else, boundId, `${path}.else`);
+      if (nested !== undefined) return nested;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Handles `explain-why` (issue #92's Why? tab): builds the sentence for a
+ * missing or rejected value from the recipe's last sample run, kept in
+ * `state.lastRuns` by `handleRunSample`.
+ *
+ * @param state - The server state: `folder` must already be set (`open-workspace` first).
+ * @param command - The command.
+ * @returns The explanation.
+ * @throws Error when no workspace is open, no sample run has finished for the target's recipe, or the target does not name a real record/field.
+ */
+async function handleExplainWhy(state, command) {
+  if (state.folder === undefined) throw new Error('open a workspace first');
+  return explainWhy(state.folder, state.lastRuns, loadRecipePair, command.target);
+}
+
+/**
+ * Handles `fetch-start-page`: loads the named input recipe from the current
+ * workspace and fetches its start point (see `page-snapshot`'s own caveats:
+ * no session bootstrap, a fresh browser or HTTP context per call).
+ *
+ * @param state - The server state: `folder` must already be set.
+ * @param command - The command.
+ * @returns The page's content as plain text.
+ * @throws Error when no workspace is open, or the recipe cannot be found or loaded.
+ */
+async function handleFetchStartPage(state, command) {
+  if (state.folder === undefined) throw new Error('open a workspace first');
+  const {
+    input
+  } = await loadRecipePair(state.folder, command.recipeId);
+  const html = await fetchStartPage(input, state.browser);
+  return {
+    html
+  };
+}
+
+/**
+ * Handles `grid-preview`: the grid canvas's live preview of a `table`
+ * extract's options (`document-view`'s `table-preview.use-case.ts`'s
+ * `previewGridTable`, studio plan §3.4, issue #94's 5c), off the same
+ * cached snapshot `take-snapshot`/`grid-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 handleGridPreview(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 (!isWorkbookDocument(snapshot.body)) throw new Error(`"${command.recipeId}" at "${command.path}" is not a workbook snapshot: grid-preview only reads a read CSV/spreadsheet document`);
+  return previewGridTable(snapshot.body, command.options);
+}
+
+/**
+ * Handles `grid-view`: the grid canvas's sheets and cells (`document-view`'s
+ * `workbook-view.mapper.ts`, studio plan §3.4, issue #94's 5c), off the same
+ * cached snapshot `take-snapshot`/`document-tree`/`pdf-view` already use.
+ *
+ * `delimiter`/`encoding` re-read a CSV with the override applied
+ * (`page-snapshot`'s `rereadCsv`) and replace the cached snapshot's body with
+ * the fresh reading, so a following `grid-preview` (and another `grid-view`
+ * with no override) sees the same one — the override sticks until
+ * `take-snapshot` recaptures.
+ *
+ * @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, an override is given for a snapshot that is not a CSV, or the snapshot's document is not a read workbook.
+ */
+async function handleGridView(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`);
+  const overriding = command.delimiter !== undefined || command.encoding !== undefined;
+  if (!overriding) {
+    if (!isWorkbookDocument(snapshot.body)) throw new Error(`"${command.recipeId}" at "${command.path}" is not a workbook snapshot: the grid canvas only reads a read CSV/spreadsheet document`);
+    return workbookDocumentView(snapshot.body);
+  }
+  if (snapshot.format !== 'csv') throw new Error(`"${command.recipeId}" at "${command.path}" is not a CSV snapshot: "delimiter"/"encoding" only override a CSV reading`);
+  const body = await rereadCsv(snapshot.baseUrl, {
+    delimiter: command.delimiter,
+    encoding: command.encoding
+  });
+  putSnapshot(state.snapshots, command.recipeId, command.path, {
+    ...snapshot,
+    body
+  });
+  return workbookDocumentView(body);
+}
+
+const GENERATED_ID = /^(?:react-|radix-|:r|ember|css-|mui-|headlessui-)/i;
+/**
+ * The path from the document root to `node`, one level per ancestor. Two
+ * elements that share an ancestor produce identical levels up to that
+ * ancestor and diverge exactly where their parents stop being the same node
+ * — `list-inference.algorithm.ts` leans on that to find the nearest pair of
+ * siblings two picks belong to, without ever touching cheerio again.
+ *
+ * @param $ - The parsed document.
+ * @param node - The element to describe.
+ * @returns The path, root first.
+ */
+function domPathOf($, node) {
+  const chain = [];
+  let current = node;
+  while (current !== undefined && current.length > 0 && isElement(current.get(0))) {
+    chain.unshift(current);
+    const parent = current.parent();
+    current = parent.length > 0 ? parent : undefined;
+  }
+  return chain.map(element => levelOf($, element));
+}
+function levelOf($, element) {
+  const node = element.get(0);
+  const tag = node.tagName.toLowerCase();
+  const attrs = {};
+  const entries = Object.entries(node.attribs ?? {});
+  for (const [name, value] of entries) attrs[name] = value;
+  const classes = (attrs.class ?? '').split(/\s+/).filter(token => token.length > 0);
+  const siblings = element.parent().length > 0 ? element.parent().children(tag) : $.root().children(tag);
+  const index = siblings.toArray().indexOf(node) + 1;
+  return {
+    tag,
+    id: attrs.id,
+    classes,
+    attrs,
+    index: Math.max(index, 1),
+    siblingCount: Math.max(siblings.length, 1)
+  };
+}
+function isElement(node) {
+  return node !== undefined && node.type === 'tag';
 }
 /**
  * Whether `id` looks handed by a framework (`react-`, a CSS-module or a
@@ -1402,7 +2533,7 @@ const TIER_ORDER = {
 function rankCandidates(html, candidates, targetNodeId) {
   const ranked = candidates.map(candidate => {
     const matches = countMatches(html, candidate.selector);
-    const hitsTarget = targetNodeId === undefined ;
+    const hitsTarget = targetNodeId === undefined || matches === 0 ? targetNodeId === undefined : matchesOf(html, candidate.selector).includes(targetNodeId);
     return {
       ...candidate,
       matches,
@@ -1581,6 +2712,333 @@ function fieldPick(html, clicked, rankSource = clicked) {
   };
 }
 
+/** A leaf element's own text longer than this is cut, with an ellipsis. */
+const TEXT_LIMIT = 80;
+/** Consecutive siblings whose subtree is identical (ids aside) collapse into one row once there are at least this many — a real page can have tens of thousands of `<li>`s, and showing all of them is not "inspecting" it (issue #93). */
+const MIN_REPEAT_RUN = 3;
+/**
+ * Builds the Inspect panel's DOM tree from a captured snapshot (studio plan
+ * §3.3, issue #93): the same rewritten, marked-up document the content pane's
+ * iframe shows (`page-snapshot`'s `take-snapshot.use-case.ts`), so a tree
+ * row's `nodeId` addresses exactly the element the iframe would highlight —
+ * no separate capture, per issue #93's scope note to reuse phase 2's
+ * snapshot rather than recapture.
+ *
+ * @param snapshotHtml - The cached, rewritten snapshot (`SnapshotResult.html`).
+ * @returns The tree's root (the document's `<html>` element).
+ * @throws Error when the document has no `<html>` element (should not happen: `rewriteDocument` always produces one).
+ */
+function domTree(snapshotHtml) {
+  const $ = load(snapshotHtml);
+  const html = $('html').get(0);
+  if (html === undefined) throw new Error('domTree: the snapshot has no <html> element');
+  return buildNode($, html);
+}
+function buildNode($, element) {
+  const $el = $(element);
+  const attributes = {
+    ...element.attribs
+  };
+  const nodeId = attributes[NODE_ID_ATTRIBUTE] ?? '';
+  const hidden = attributes[HIDDEN_ATTRIBUTE] === '1';
+  delete attributes[NODE_ID_ATTRIBUTE];
+  delete attributes[HIDDEN_ATTRIBUTE];
+  const id = attributes.id;
+  const classes = (attributes.class ?? '').split(/\s+/).filter(token => token !== '');
+  const childElements = $el.children().toArray();
+  const children = collapseRepeats(childElements.map(child => buildNode($, child)));
+  const text = childElements.length === 0 ? abbreviate($el.text()) : undefined;
+  return {
+    nodeId,
+    tag: element.tagName.toLowerCase(),
+    ...(id !== undefined && id !== '' && {
+      id
+    }),
+    ...(classes.length > 0 && {
+      classes
+    }),
+    attributes,
+    ...(text !== undefined && text !== '' && {
+      text
+    }),
+    hidden,
+    children
+  };
+}
+/**
+ * Merges runs of `MIN_REPEAT_RUN` or more consecutive siblings whose subtree
+ * is identical (their own `nodeId`s aside) into one representative row, the
+ * issue's `×20` — real pages have tens of thousands of nodes, and this is
+ * what makes the tree usable rather than merely correct.
+ *
+ * @param nodes - Already-built sibling rows, in document order.
+ * @returns The same rows, with each long-enough identical run replaced by one.
+ */
+function collapseRepeats(nodes) {
+  const result = [];
+  let at = 0;
+  while (at < nodes.length) {
+    const signature = signatureOf(nodes[at]);
+    let end = at + 1;
+    while (end < nodes.length && signatureOf(nodes[end]) === signature) end += 1;
+    const run = nodes.slice(at, end);
+    if (run.length >= MIN_REPEAT_RUN) {
+      result.push({
+        ...run[0],
+        repeatCount: run.length,
+        repeatNodeIds: run.map(node => node.nodeId)
+      });
+    } else {
+      result.push(...run);
+    }
+    at = end;
+  }
+  return result;
+}
+/** A run member's identity for collapsing: everything but its own `nodeId` (every instance has a different one by construction). */
+function signatureOf(node) {
+  return JSON.stringify({
+    ...node,
+    nodeId: undefined,
+    children: node.children.map(child => signatureOf(child))
+  });
+}
+function abbreviate(text) {
+  const trimmed = text.trim().replaceAll(/\s+/g, ' ');
+  return trimmed.length > TEXT_LIMIT ? `${trimmed.slice(0, TEXT_LIMIT)}…` : trimmed;
+}
+
+/** The global names sites hydrate state into, that `describeHtml`'s own JSON-LD/table scan does not cover (issue #93's "inline state assignments"). */
+const INLINE_STATE_NAMES = ['__NEXT_DATA__', '__NUXT__', '__INITIAL_STATE__', '__APOLLO_STATE__', '__PRELOADED_STATE__', '__STATE__'];
+const INLINE_STATE_PATTERN = new RegExp(String.raw`(?:window\.)?(${INLINE_STATE_NAMES.join('|')})\s*=`);
+/**
+ * Finds the data-in-the-page findings the Inspect panel lists apart from the
+ * DOM tree (studio plan §3.3, issue #93): JSON-LD and `application/json`
+ * script blocks, inline state assignments, `<meta>` name/property values and
+ * `<link rel>`s — reusing `@opencraw/probe`'s `describeJson` for a found
+ * value's shape (its own `find-data.algorithm.ts`/`html-findings.mapper.ts`
+ * scan a page's raw text for *reporting*, with no element to point a pick at;
+ * this function's own job — locating each finding's element so a pick can
+ * reach it — is new).
+ *
+ * Takes the **raw** captured document, not the display snapshot
+ * (`page-snapshot`'s `SnapshotResult.html`): `rewriteDocument` strips every
+ * `<script>` for the sandboxed iframe, which would make JSON-LD, inline
+ * state and other script-tag data invisible here. `<meta>`/`<link>` survive
+ * rewriting untouched, so using the raw document for every kind (rather than
+ * mixing two documents) keeps this function simple and its selectors
+ * verified against what the engine will actually crawl.
+ *
+ * @param rawHtml - The document as fetched/rendered, before `rewriteDocument` strips scripts.
+ * @returns The findings, in document order.
+ */
+function pageData(rawHtml) {
+  const $ = load(rawHtml);
+  const findings = [];
+  $('script[type="application/ld+json"]').each((_index, element) => {
+    findings.push(...scriptFinding($, element, rawHtml, 'ld-json', ldJsonLabel));
+  });
+  $('script[type="application/json"]').each((_index, element) => {
+    findings.push(...scriptFinding($, element, rawHtml, 'json-script', () => `json: ${structuralSelector($, element)}`));
+  });
+  $('script').each((_index, element) => {
+    const type = $(element).attr('type');
+    if (type !== undefined && type !== 'text/javascript' && type !== 'module') return;
+    const text = $(element).text();
+    const match = INLINE_STATE_PATTERN.exec(text);
+    if (match === null) return;
+    const value = tryParseJson(text);
+    const selector = structuralSelector($, element);
+    findings.push({
+      kind: 'inline-state',
+      label: match[1],
+      selector,
+      selectorKind: 'css',
+      matches: countMatches(rawHtml, selector),
+      keys: keysOf(value)
+    });
+  });
+  $('meta[name], meta[property]').each((_index, element) => {
+    const name = $(element).attr('name') ?? $(element).attr('property') ?? '';
+    const selector = structuralSelector($, element);
+    findings.push({
+      kind: 'meta',
+      label: `meta: ${name}`,
+      selector,
+      selectorKind: 'css',
+      matches: countMatches(rawHtml, selector),
+      attribute: 'content'
+    });
+  });
+  $('link[rel]').each((_index, element) => {
+    const rel = $(element).attr('rel') ?? '';
+    const selector = structuralSelector($, element);
+    findings.push({
+      kind: 'link',
+      label: `link: ${rel}`,
+      selector,
+      selectorKind: 'css',
+      matches: countMatches(rawHtml, selector),
+      attribute: 'href'
+    });
+  });
+  return findings;
+}
+function scriptFinding($, element, rawHtml, kind, labelOf) {
+  const value = tryParseJson($(element).text());
+  if (value === undefined) return [];
+  const selector = structuralSelector($, element);
+  return [{
+    kind,
+    label: labelOf(value),
+    selector,
+    selectorKind: 'css',
+    matches: countMatches(rawHtml, selector),
+    keys: keysOf(value)
+  }];
+}
+function ldJsonLabel(value) {
+  if (Array.isArray(value)) return `ld+json: array (${value.length})`;
+  if (typeof value === 'object' && value !== null) {
+    const type = value['@type'];
+    if (typeof type === 'string') return `ld+json: ${type}`;
+  }
+  return `ld+json: ${describeJson(value, 'json').type}`;
+}
+function keysOf(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? Object.keys(value) : undefined;
+}
+/**
+ * A unique CSS path for an element with no stable attribute of its own
+ * (a `<script>` tag has no id or class to speak of): `<ancestor> > tag`
+ * from `<html>` down, `:nth-of-type` added only where a tag has siblings of
+ * the same name under the same parent. Always resolves to exactly one
+ * element, on the raw document this ran against and on the real page (a
+ * purely structural selector, unaffected by the snapshot's own rewriting).
+ *
+ * @param $ - The document.
+ * @param element - The element to address.
+ * @returns The selector.
+ */
+function structuralSelector($, element) {
+  const segments = [];
+  let $current = $(element);
+  while ($current.length > 0) {
+    const tag = $current.prop('tagName')?.toLowerCase();
+    if (tag === undefined) break;
+    const $parent = $current.parent();
+    const siblingsOfType = $parent.length > 0 ? $parent.children(tag) : $current;
+    const index = siblingsOfType.toArray().indexOf($current.get(0)) + 1;
+    segments.unshift(siblingsOfType.length > 1 ? `${tag}:nth-of-type(${index})` : tag);
+    if (tag === 'html' || $parent.length === 0) break;
+    $current = $parent;
+  }
+  return segments.join(' > ');
+}
+
+/** How long the browser is given to settle after `goto`, watching for JSON responses (mirrors `packages/cli`'s `probe --browser`, `observeBrowserJson`). */
+const OBSERVE_MS = 4000;
+/** Responses kept, largest/most-recent-first ordering left to the caller; just a sane cap on what the panel lists. */
+const RESPONSE_LIMIT = 15;
+/**
+ * Records the JSON responses seen while an input recipe's start page
+ * rendered (studio plan §3.3, issue #93): the same technique `packages/cli`'s
+ * `probe --browser` uses (`observeBrowserJson`) — render the page, listen for
+ * `response` events whose content type is JSON, give it a few seconds to
+ * settle. Kept as its own capture, independent of `page-snapshot`'s
+ * `take-snapshot.use-case.ts`: that capture reads `page.content()` right
+ * after `goto` resolves, with no observation window, and changing its shape
+ * to also collect responses was a larger, riskier change to already-shipped,
+ * tested code than this phase's budget allowed (see this phase's final
+ * report) — so this opens its own short-lived browser session instead of
+ * piggy-backing on the cached snapshot.
+ *
+ * Only `"start"` is supported, mirroring `take-snapshot.use-case.ts`'s own
+ * reach; api-mode recipes have no page load to observe, so they always
+ * answer with an empty list rather than an error (there is nothing wrong
+ * with asking, the answer is just "none").
+ *
+ * @param input - The input recipe; only `mode` and the first `start` point are used.
+ * @param stepPath - The step to observe after, e.g. `"start"`.
+ * @param browser - Browser launch settings, shared with `take-snapshot`/`verify-selector`/`run-sample`.
+ * @returns The distinct JSON responses observed, at most `RESPONSE_LIMIT`.
+ * @throws Error when the recipe has no start point, or `stepPath` is not `"start"`.
+ */
+async function responsesSeen(input, stepPath, browser) {
+  if (stepPath !== 'start') throw new Error(`responsesSeen: "${stepPath}" is not supported yet — only "start" (the first start point, before any step ran) is`);
+  if (input.mode !== 'web') return [];
+  const point = input.start[0];
+  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
+  const client = await BrowserClient.launch(browser);
+  try {
+    const session = await client.newSession();
+    try {
+      const responses = [];
+      const seen = new Set();
+      const pending = [];
+      session.page.on('response', response => {
+        if (!(response.headers()['content-type'] ?? '').includes('json')) return;
+        const key = `${response.status()} ${response.url()}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        pending.push(recordResponse(response, responses));
+      });
+      try {
+        await session.page.goto(point.url, {
+          waitUntil: 'networkidle'
+        });
+      } catch {
+        // a page that never idles (long-poll, websocket) still yields whatever was observed by the timeout below
+      }
+      await session.page.waitForTimeout(OBSERVE_MS);
+      await Promise.all(pending);
+      return responses.slice(0, RESPONSE_LIMIT);
+    } finally {
+      await session.close();
+    }
+  } finally {
+    await client.close();
+  }
+}
+/** Reads one response's body, when it still can be (not aborted, not redirected away); a response that cannot be read is silently left out rather than failing the whole capture. */
+async function recordResponse(response, into) {
+  try {
+    const body = await response.text();
+    const value = tryParseJson(body);
+    into.push({
+      url: response.url(),
+      status: response.status(),
+      size: body.length,
+      shape: value === undefined ? 'text' : describeJson(value, 'json').type
+    });
+  } catch {
+    // response body unavailable (aborted, redirected, the page navigated away) — skip it
+  }
+}
+
+/**
+ * Handles `inspect-page`: the Inspect panel's DOM tree and data-in-the-page
+ * findings, off the same cached snapshot `take-snapshot`/`infer-selector`
+ * already use (`page-inspector`, issue #93). `domTree` reads the cached,
+ * rewritten snapshot (the same markup the content pane's iframe shows, so a
+ * tree row's `nodeId` lines up with it exactly); `pageData` reads the raw
+ * capture (`SnapshotResult.rawHtml`), since the display snapshot has had its
+ * `<script>` tags stripped for the sandboxed iframe.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The tree and the data-in-the-page findings.
+ * @throws Error when no workspace is open, or `command.path` has no cached snapshot yet.
+ */
+function handleInspectPage(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`);
+  return {
+    tree: domTree(snapshot.html),
+    pageData: pageData(snapshot.rawHtml)
+  };
+}
+
 /**
  * The outline model: an `InputRecipe`'s `steps` (and only `steps`; the rest
  * of the recipe passes through untouched, see `recipe-to-outline.mapper.ts`)
@@ -1705,306 +3163,1078 @@ function selectChoice(step) {
   if (Array.isArray(step.values)) return code(step.values.join(', '));
   return code('');
 }
-function waitFor(step) {
-  if (typeof step.selector === 'string') return code(step.selector);
-  if (typeof step.ms === 'number') return code(`${step.ms}ms`);
-  if (typeof step.state === 'string') return code(step.state);
-  return code('');
+function waitFor(step) {
+  if (typeof step.selector === 'string') return code(step.selector);
+  if (typeof step.ms === 'number') return code(`${step.ms}ms`);
+  if (typeof step.state === 'string') return code(step.state);
+  return code('');
+}
+function forEachSentence(step) {
+  const parts = [word('For each'), pillField(step, 'as', '(item)'), word('in'), typeof step.over === 'string' ? pill(step.over) : targetField(step)];
+  if (step.emit !== undefined) parts.push(word('→'), word('one record'));
+  return parts;
+}
+function paginateSentence(step) {
+  const parts = [word('For every page')];
+  const next = step.next;
+  if (next !== null && typeof next === 'object') {
+    const record = next;
+    if (typeof record.selector === 'string') parts.push(word('via'), code(record.selector));else if (typeof record.url === 'string') parts.push(word('via'), code(record.url));else if (typeof record.jsonpath === 'string') parts.push(word('via'), code(record.jsonpath));
+  }
+  if (typeof step.until === 'string') parts.push(word('until'), code(step.until));
+  return parts;
+}
+function emitSentence(step) {
+  if (typeof step.output === 'string') return [word('Emit'), word('to'), pill(step.output)];
+  return [word('Emit')];
+}
+
+/**
+ * Reads a recipe's `steps` as an outline. Works on whatever JSON parsed
+ * (not a validated `InputRecipe`): a recipe mid-edit in the JSON tab may be
+ * missing fields or have the wrong shape, and the outline still has to
+ * render something rather than crash the tab. Anything that is not a
+ * well-formed step becomes a custom card holding what was there; anything
+ * that is not an object at the top becomes an outline with no steps.
+ *
+ * @param content - The recipe's parsed JSON (the JSON tab's own `JSON.parse` of its text).
+ * @returns The outline: the untouched top-level record plus the step tree.
+ */
+function recipeToOutline(content) {
+  const recipe = isRecord(content) ? content : {};
+  const steps = Array.isArray(recipe.steps) ? recipe.steps : [];
+  return {
+    recipe,
+    steps: stepsToNodes(steps, 'steps')
+  };
+}
+function stepsToNodes(steps, pathPrefix) {
+  return steps.map((step, index) => stepToNode(step, `${pathPrefix}.${index}`));
+}
+function stepToNode(step, path) {
+  if (!isRecord(step)) {
+    return {
+      kind: 'card',
+      path,
+      stepType: 'unknown',
+      sentence: [{
+        kind: 'word',
+        text: 'custom step'
+      }],
+      step: {},
+      custom: true
+    };
+  }
+  const stepType = typeof step.type === 'string' ? step.type : 'unknown';
+  const {
+    parts,
+    custom
+  } = cardSentence(step);
+  if (!isBracketStepType(stepType)) return {
+    kind: 'card',
+    path,
+    stepType,
+    sentence: parts,
+    step,
+    custom
+  };
+  const children = Array.isArray(step.steps) ? stepsToNodes(step.steps, `${path}.steps`) : [];
+  const elseChildren = stepType === 'if' && Array.isArray(step.else) ? stepsToNodes(step.else, `${path}.else`) : undefined;
+  return {
+    kind: 'bracket',
+    path,
+    stepType,
+    sentence: parts,
+    step,
+    children,
+    ...(elseChildren !== undefined && {
+      elseChildren
+    })
+  };
+}
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Rebuilds a recipe from its outline: `recipe`'s keys, in their original
+ * order, with `steps` (when the recipe had one) replaced by the outline's
+ * (possibly edited) step tree. A card's own raw `step` is used as-is; a
+ * bracket's `step` supplies every field but `steps`/`else`, which come from
+ * `children`/`elseChildren` instead, put back at the position `step` itself
+ * held that key at (or appended, for a bracket a `+` menu just added, whose
+ * `step` never had one) — this, together with `recipe-to-outline.mapper.ts`
+ * always keeping the step's whole original object, is what makes
+ * `recipe → outline → recipe` preserve every key and its order.
+ *
+ * @param outline - An outline, from `recipe-to-outline.mapper.ts` or edited by the UI.
+ * @returns The recipe's plain JSON, ready for `save-recipe`.
+ */
+function outlineToRecipe(outline) {
+  if (!('steps' in outline.recipe) && outline.steps.length === 0) return {
+    ...outline.recipe
+  };
+  return {
+    ...outline.recipe,
+    steps: nodesToSteps(outline.steps)
+  };
+}
+function nodesToSteps(nodes) {
+  return nodes.map(node => nodeToStep(node));
+}
+function nodeToStep(node) {
+  if (!isBracket(node)) return node.step;
+  const keys = Object.keys(node.step);
+  const step = {};
+  for (const key of keys) {
+    if (key === 'steps') step.steps = nodesToSteps(node.children);else if (key === 'else' && node.stepType === 'if') step.else = nodesToSteps(node.elseChildren ?? []);else step[key] = node.step[key];
+  }
+  if (!keys.includes('steps')) step.steps = nodesToSteps(node.children);
+  if (node.stepType === 'if' && node.elseChildren !== undefined && !keys.includes('else')) step.else = nodesToSteps(node.elseChildren);
+  return step;
+}
+
+/**
+ * Opens a recipe folder: every `.json`/`.jsonl` recipe directly inside it
+ * (core's own directory reading, so relative `file:` URLs resolve the same
+ * way a real run would), parsed and, for each output recipe found, bound to
+ * the input recipes that name it. Nothing throws for a bad recipe or a
+ * recipe that does not bind: every problem is reported on its file with the
+ * JSON path core already computes, exactly as `opencraw validate` prints it.
+ *
+ * @param folder - The workspace folder.
+ * @returns Every recipe file found, each with its validation and binding issues.
+ * @throws Error when the folder does not exist or cannot be read.
+ */
+async function openWorkspace(folder) {
+  const documents = await readRecipeSource(folder);
+  const entries = documents.map(document => parseDocument(document));
+  const outputs = entries.filter(isParsed('output'));
+  const inputs = entries.filter(isParsed('input'));
+  for (const output of outputs) bindOutput(output, inputs);
+  for (const input of inputs) {
+    if (outputs.every(output => output.recipe.id !== input.recipe.output)) {
+      input.issues.push({
+        path: 'output',
+        message: `no output recipe "${input.recipe.output}" in this workspace`,
+        kind: 'binding'
+      });
+    }
+  }
+  return {
+    folder,
+    recipes: entries.map(({
+      file,
+      kind,
+      id,
+      issues,
+      content
+    }) => ({
+      file,
+      kind,
+      id,
+      issues,
+      text: `${JSON.stringify(content, null, 2)}\n`,
+      // The Steps tab needs steps to render: an output/unknown file has none. recipeToOutline never
+      // throws, so this covers a file that fails validation too (its outline just has "custom" cards).
+      outline: kind === 'input' ? recipeToOutline(content) : undefined
+    }))
+  };
+}
+/** Binds one output recipe to the inputs that name it, filing every binding issue back on the recipe it names. */
+function bindOutput(output, inputs) {
+  const matching = inputs.filter(input => input.recipe.output === output.recipe.id);
+  try {
+    bindRecipeSet(output.recipe, matching.map(input => input.recipe));
+  } catch (error) {
+    if (!(error instanceof RecipeBindingError)) throw error;
+    for (const issue of error.issues) {
+      const target = issue.recipeId === output.recipe.id ? output : matching.find(input => input.recipe.id === issue.recipeId);
+      target?.issues.push({
+        path: issue.path,
+        message: issue.message,
+        kind: 'binding'
+      });
+    }
+  }
+}
+function isParsed(kind) {
+  return entry => entry.kind === kind && entry.recipe !== undefined;
+}
+function parseDocument(document) {
+  const kind = document.content?.kind;
+  if (kind === 'output') return parseOne(document.source, document.content, 'output', parseOutputRecipe);
+  if (kind === 'input') return parseOne(document.source, document.content, 'input', parseInputRecipe);
+  return {
+    file: document.source,
+    kind: 'unknown',
+    content: document.content,
+    issues: [{
+      path: 'kind',
+      message: '"kind" is missing or not "input"/"output"',
+      kind: 'validation'
+    }]
+  };
+}
+function parseOne(file, content, kind, parse) {
+  try {
+    const recipe = parse(content, file);
+    return {
+      file,
+      kind,
+      content,
+      id: recipe.id,
+      issues: [],
+      recipe
+    };
+  } catch (error) {
+    if (!(error instanceof RecipeValidationError)) throw error;
+    return {
+      file,
+      kind,
+      content,
+      issues: error.issues.map(issue => ({
+        path: issue.path === '' ? '(root)' : issue.path,
+        message: issue.message,
+        kind: 'validation'
+      }))
+    };
+  }
+}
+
+/**
+ * Writes a recipe back to its file: pretty JSON, a 2-space indent, a
+ * trailing newline. Phase 0 takes the JSON tab's whole parsed object rather
+ * than a patch, so this is a full replacement, not a splice: loading a file
+ * the studio has not touched and saving it again keeps every key, value and
+ * key order (`JSON.parse` preserves insertion order, and `JSON.stringify`
+ * writes it back), but not necessarily the file's exact original formatting
+ * (alignment, how arrays wrap, a trailing comment). Byte-identical
+ * round-trip for a hand-formatted file is future work; see this file's test
+ * for what is guaranteed today.
+ *
+ * @param path - The recipe file to write.
+ * @param recipe - The whole recipe object.
+ */
+async function saveRecipe(path, recipe) {
+  await writeFile(path, `${JSON.stringify(recipe, null, 2)}\n`, 'utf8');
+}
+
+/** 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');
 }
-function forEachSentence(step) {
-  const parts = [word('For each'), pillField(step, 'as', '(item)'), word('in'), typeof step.over === 'string' ? pill(step.over) : targetField(step)];
-  if (step.emit !== undefined) parts.push(word('→'), word('one record'));
-  return parts;
+/** @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()
+  };
 }
-function paginateSentence(step) {
-  const parts = [word('For every page')];
-  const next = step.next;
-  if (next !== null && typeof next === 'object') {
-    const record = next;
-    if (typeof record.selector === 'string') parts.push(word('via'), code(record.selector));else if (typeof record.url === 'string') parts.push(word('via'), code(record.url));else if (typeof record.jsonpath === 'string') parts.push(word('via'), code(record.jsonpath));
+/**
+ * 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);
+    }
   }
-  if (typeof step.until === 'string') parts.push(word('until'), code(step.until));
-  return parts;
 }
-function emitSentence(step) {
-  if (typeof step.output === 'string') return [word('Emit'), word('to'), pill(step.output)];
-  return [word('Emit')];
+
+/**
+ * Handles `open-workspace`: reads the folder, remembers it as the server's
+ * current workspace (every later command that names a recipe resolves it
+ * against this folder), and tells every connected client the workspace changed.
+ *
+ * @param state - The server state to update.
+ * @param command - The command.
+ * @returns The workspace's recipes and their issues.
+ */
+async function handleOpenWorkspace(state, command) {
+  const view = await openWorkspace(command.folder);
+  state.folder = command.folder;
+  broadcast(state, {
+    type: 'workspace-changed'
+  });
+  return view;
 }
 
 /**
- * Reads a recipe's `steps` as an outline. Works on whatever JSON parsed
- * (not a validated `InputRecipe`): a recipe mid-edit in the JSON tab may be
- * missing fields or have the wrong shape, and the outline still has to
- * render something rather than crash the tab. Anything that is not a
- * well-formed step becomes a custom card holding what was there; anything
- * that is not an object at the top becomes an outline with no steps.
+ * Handles `GET /api/pdf-bytes`: the raw bytes of a cached PDF snapshot, for
+ * the PDF canvas's `pdf.js` to render in the browser (studio plan §3.4,
+ * issue #94's 5b). Not a `studio-api` command — the other commands all
+ * answer JSON, and pdf.js wants the file itself — so this is its own route,
+ * read directly by `studio-http.use-case.ts` (mirrors `static-file.handler.ts`'s
+ * own reach outside the command dispatch).
  *
- * @param content - The recipe's parsed JSON (the JSON tab's own `JSON.parse` of its text).
- * @returns The outline: the untouched top-level record plus the step tree.
+ * @param state - The server state.
+ * @param recipeId - The recipe.
+ * @param path - The step path; must already have a cached PDF snapshot (call `take-snapshot` first).
+ * @returns The raw PDF bytes.
+ * @throws Error when `path` has no cached snapshot yet, or the snapshot's document is not a PDF.
  */
-function recipeToOutline(content) {
-  const recipe = isRecord(content) ? content : {};
-  const steps = Array.isArray(recipe.steps) ? recipe.steps : [];
-  return {
-    recipe,
-    steps: stepsToNodes(steps, 'steps')
-  };
+async function handlePdfBytes(state, recipeId, path) {
+  const snapshot = cachedSnapshot(state.snapshots, recipeId, path);
+  if (snapshot === undefined) throw new Error(`no cached snapshot for "${recipeId}" at "${path}": call take-snapshot first`);
+  if (snapshot.format !== 'pdf') throw new Error(`"${recipeId}" at "${path}" is not a PDF snapshot`);
+  return pdfBytes(snapshot.baseUrl);
 }
-function stepsToNodes(steps, pathPrefix) {
-  return steps.map((step, index) => stepToNode(step, `${pathPrefix}.${index}`));
+
+/**
+ * Handles `pdf-view`: the PDF canvas's cells and rows (`document-view`'s
+ * `pdf-view.mapper.ts`, studio plan §3.4, issue #94's 5b), 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 PDF.
+ */
+function handlePdfView(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 (!isPdfDocument(snapshot.body)) throw new Error(`"${command.recipeId}" at "${command.path}" is not a PDF snapshot: the PDF canvas only reads a read PDF document`);
+  return pdfDocumentView(snapshot.body);
 }
-function stepToNode(step, path) {
-  if (!isRecord(step)) {
-    return {
-      kind: 'card',
-      path,
-      stepType: 'unknown',
-      sentence: [{
-        kind: 'word',
-        text: 'custom step'
-      }],
-      step: {},
-      custom: true
-    };
+
+/**
+ * Turns one resolved recorded action into the recipe step it reads as
+ * (issue #95's card sentences): `Click <selector>`, `Fill <selector> with
+ * <value>`, `Select <selector> = <value>`, `Press <key>`, `Scroll to
+ * bottom`. Pure: `recorder-session.use-case.ts` has already resolved the
+ * selector (`selector-inference`) and, for a secret field, already replaced
+ * `value` with its `{{env.NAME}}` placeholder (`secret-field.policy.ts`) —
+ * this mapper never sees, and so can never leak, a real secret value.
+ *
+ * @param action - The resolved action.
+ * @returns The step it becomes, or `undefined` for an action this mapper cannot place (a click/fill/select with no verified selector).
+ */
+function actionToStep(action) {
+  switch (action.kind) {
+    case 'click':
+      {
+        if (action.selector === undefined) return undefined;
+        const step = {
+          type: 'click',
+          selector: action.selector
+        };
+        return step;
+      }
+    case 'fill':
+      {
+        if (action.selector === undefined) return undefined;
+        const step = {
+          type: 'fill',
+          selector: action.selector,
+          value: action.value ?? ''
+        };
+        return step;
+      }
+    case 'select':
+      {
+        if (action.selector === undefined) return undefined;
+        const step = {
+          type: 'select',
+          selector: action.selector,
+          value: action.value
+        };
+        return step;
+      }
+    case 'keypress':
+      {
+        const key = action.key ?? 'Enter';
+        const step = action.selector === undefined ? {
+          type: 'press',
+          key
+        } : {
+          type: 'press',
+          selector: action.selector,
+          key
+        };
+        return step;
+      }
+    case 'scroll':
+      {
+        const step = {
+          type: 'scroll',
+          to: 'bottom'
+        };
+        return step;
+      }
   }
-  const stepType = typeof step.type === 'string' ? step.type : 'unknown';
-  const {
-    parts,
-    custom
-  } = cardSentence(step);
-  if (!isBracketStepType(stepType)) return {
-    kind: 'card',
-    path,
-    stepType,
-    sentence: parts,
-    step,
-    custom
-  };
-  const children = Array.isArray(step.steps) ? stepsToNodes(step.steps, `${path}.steps`) : [];
-  const elseChildren = stepType === 'if' && Array.isArray(step.else) ? stepsToNodes(step.else, `${path}.else`) : undefined;
-  return {
-    kind: 'bracket',
-    path,
-    stepType,
-    sentence: parts,
-    step,
-    children,
-    ...(elseChildren !== undefined && {
-      elseChildren
-    })
-  };
 }
-function isRecord(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** A `rel` token that means "the next page" on an `<a>`/`<link>`. */
+const REL_NEXT = /(?:^|\s)next(?:\s|$)/i;
+/** Link text that reads as "next", loosely: "Next", "Next »", "Next page", punctuation and arrows ignored. */
+const TEXT_NEXT = /^\s*next(?:\s*page)?\s*(?:[›»>]\s*)?$/i;
+/** The selector itself names the pattern (`li.next a`, `a[aria-label=Next]`) even when the reported text/rel do not. */
+const SELECTOR_NEXT = /(?:^|[\s>.])li\.next\b|\[aria-label\s*=\s*['"]?next['"]?\]/i;
+/**
+ * Whether a clicked, navigating element looks like a "next" link (issue
+ * #95's exact heuristics): `rel="next"`, link text matching "next", or the
+ * resolved selector itself carrying `li.next a`/`a[aria-label=Next]`. Only
+ * meaningful for a click that navigated — the caller checks that first.
+ *
+ * @param link - The anchor's own `rel`/text/`aria-label`, as reported by `recorder-script.client.ts`.
+ * @param selector - The action's resolved selector (`selector-inference`'s own candidate).
+ * @returns Whether the studio should offer to turn this click into a `paginate` step.
+ */
+function looksLikeNextLink(link, selector) {
+  if (link?.rel !== undefined && REL_NEXT.test(link.rel)) return true;
+  if (link?.ariaLabel !== undefined && /^next$/i.test(link.ariaLabel.trim())) return true;
+  if (link?.text !== undefined && TEXT_NEXT.test(link.text)) return true;
+  if (selector !== undefined && SELECTOR_NEXT.test(selector)) return true;
+  return false;
 }
 
+/** Why a report was refused before it became an action: out of this phase's scope (issue #95). */
+const UNSUPPORTED_REASONS = ['iframe', 'shadow-dom'];
 /**
- * Rebuilds a recipe from its outline: `recipe`'s keys, in their original
- * order, with `steps` (when the recipe had one) replaced by the outline's
- * (possibly edited) step tree. A card's own raw `step` is used as-is; a
- * bracket's `step` supplies every field but `steps`/`else`, which come from
- * `children`/`elseChildren` instead, put back at the position `step` itself
- * held that key at (or appended, for a bracket a `+` menu just added, whose
- * `step` never had one) — this, together with `recipe-to-outline.mapper.ts`
- * always keeping the step's whole original object, is what makes
- * `recipe → outline → recipe` preserve every key and its order.
+ * The type/name/id of the form field a `fill`/`select` landed on, exactly as
+ * the live DOM reports them — `secret-field.policy.ts`'s only input. Never
+ * carries the field's value: that travels separately, on the action itself.
+ */
+const recordedFieldSchema = z.object({
+  type: z.string().optional(),
+  name: z.string().optional(),
+  id: z.string().optional()
+});
+/** What `next-link.policy.ts` needs off a clicked anchor: never the whole element. */
+const recordedLinkSchema = z.object({
+  rel: z.string().optional(),
+  text: z.string().optional(),
+  ariaLabel: z.string().optional()
+});
+/**
+ * The wire shape of one action as `recorder-script.client.ts` reports it,
+ * over the Playwright binding `recorder-session.use-case.ts` exposes: the
+ * `data-oc-node` id of the element involved (`selector-inference`'s own
+ * marker attribute, `@opencraw/core`'s `NODE_ID_ATTRIBUTE`), never a
+ * selector — the studio, not the page, decides that (studio plan §3.2,
+ * issue #95). Never the field's real value when it might be a secret: the
+ * script itself does not know which fields are secret (`secret-field.policy.ts`
+ * runs server-side, once a `RecordedField` is known), but nothing here
+ * *requires* a value to be typed out either way — `recorder-session.use-case.ts`
+ * discards it the moment a secret is detected.
  *
- * @param outline - An outline, from `recipe-to-outline.mapper.ts` or edited by the UI.
- * @returns The recipe's plain JSON, ready for `save-recipe`.
+ * `html` is the document's own markup, captured by the script itself at the
+ * moment of the event (`document.documentElement.outerHTML`), not fetched
+ * again afterwards: a click that navigates can leave the page before a
+ * later `page.content()` call would resolve, reading the *next* page's
+ * markup instead of the one the click actually happened on. Capturing it
+ * synchronously, in the same event the node id is stamped in, means the
+ * selector is always resolved against the exact document the action
+ * happened on — still "verified against the page" (issue #95), just without
+ * the race a second round trip would risk.
  */
-function outlineToRecipe(outline) {
-  if (!('steps' in outline.recipe) && outline.steps.length === 0) return {
-    ...outline.recipe
-  };
-  return {
-    ...outline.recipe,
-    steps: nodesToSteps(outline.steps)
-  };
+const rawActionSchema = z.discriminatedUnion('kind', [z.object({
+  kind: z.literal('click'),
+  nodeId: z.string().min(1),
+  html: z.string().min(1),
+  link: recordedLinkSchema.optional()
+}), z.object({
+  kind: z.literal('fill'),
+  nodeId: z.string().min(1),
+  html: z.string().min(1),
+  value: z.string(),
+  field: recordedFieldSchema.optional()
+}), z.object({
+  kind: z.literal('select'),
+  nodeId: z.string().min(1),
+  html: z.string().min(1),
+  value: z.string(),
+  field: recordedFieldSchema.optional()
+}), z.object({
+  kind: z.literal('keypress'),
+  nodeId: z.string().min(1).optional(),
+  html: z.string().optional(),
+  key: z.string().min(1)
+}), z.object({
+  kind: z.literal('scroll'),
+  to: z.literal('bottom')
+}), z.object({
+  kind: z.literal('unsupported'),
+  reason: z.enum(UNSUPPORTED_REASONS)
+})]);
+
+/**
+ * The in-page script `recorder-session.use-case.ts` installs on every page
+ * of the studio's own headed browser window (`context.addInitScript`),
+ * reporting the person's actions to the binding it also exposes on the
+ * context (`context.exposeBinding`) — issue #95's "a script injected into
+ * every page ... reports the user's actions: click, type, select, key
+ * press, scroll".
+ *
+ * Kept as a plain string, not a TypeScript function passed to
+ * `page.evaluate`/`addInitScript`, for the same reason as
+ * `page-snapshot/hidden-marks.algorithm.ts`'s `hiddenMarksScript`: it
+ * references `window`/`document` as globals, which `AGENTS.md`'s "things
+ * that bit before" and the repo's `isolated-functions` lint rule forbid for
+ * an in-page TypeScript function.
+ *
+ * What it reports, and what it deliberately does not:
+ *
+ * - **click**: the nearest clickable ancestor (`a`, `button`,
+ *   `input[type=submit|button]`) of the element clicked, or the element
+ *   itself; for an `<a>`, also its `rel`, text and `aria-label` —
+ *   `next-link.policy.ts`'s only input.
+ * - **fill**: on `blur` of a text-like input/textarea whose value changed
+ *   since it was focused (never on every keystroke) — the field's `type`,
+ *   `name` and `id`, and the value *as typed*; whether that value is a
+ *   secret, and what replaces it, is `secret-field.policy.ts`'s call,
+ *   server-side, not this script's.
+ * - **select**: on `change` of a `<select>`.
+ * - **keypress**: `Enter` only (issue #95's own example, "Press Enter");
+ *   every other key is noise a recipe step has no shape for.
+ * - **scroll**: once per "scroll session" (debounced), when the page has
+ *   been scrolled within `NEAR_BOTTOM_PX` of its bottom.
+ * - **unsupported**: once, the first time an event's target sits inside a
+ *   shadow root, or this script runs in a frame that is not the top window
+ *   (an iframe) — issue #95's explicit out-of-scope cases, reported instead
+ *   of attempted.
+ *
+ * Every reported element is marked with `attribute` (`data-oc-node` by
+ * default, `@opencraw/core`'s `NODE_ID_ATTRIBUTE`) if it does not already
+ * carry one, the same attribute `selector-inference`'s `pathToNode` reads —
+ * so `recorder-session.use-case.ts` can turn a report straight into a
+ * verified selector with the phase 2 generator, never inventing its own.
+ *
+ * @param bindingName - The name Playwright's `exposeBinding` gave the reporting function (`window[bindingName]`).
+ * @param attribute - The marker attribute; defaults to `NODE_ID_ATTRIBUTE`.
+ * @returns A self-invoking script, ready for `context.addInitScript({ content: recorderScript(...) })`.
+ */
+function recorderScript(bindingName, attribute = NODE_ID_ATTRIBUTE) {
+  return `(() => {
+    if (window.top !== window.self) {
+      try { window.${bindingName}({ kind: 'unsupported', reason: 'iframe' }) } catch (e) {}
+      return
+    }
+    var attribute = ${JSON.stringify(attribute)}
+    var seq = 0
+    var unsupportedReported = false
+    var scrollTimer = null
+    var focusValues = new WeakMap()
+
+    function report (payload) {
+      try { window.${bindingName}(payload) } catch (e) {}
+    }
+
+    function inShadowDom (element) {
+      var root = element.getRootNode ? element.getRootNode() : document
+      return root !== document
+    }
+
+    function reportUnsupportedOnce (reason) {
+      if (unsupportedReported) return
+      unsupportedReported = true
+      report({ kind: 'unsupported', reason: reason })
+    }
+
+    function markNode (element) {
+      var id = element.getAttribute(attribute)
+      if (id) return id
+      seq += 1
+      id = 'rec-' + Date.now().toString(36) + '-' + seq
+      element.setAttribute(attribute, id)
+      return id
+    }
+
+    function clickable (element) {
+      return element.closest('a, button, input[type="submit"], input[type="button"]') || element
+    }
+
+    function isTextEntry (element) {
+      var tag = element.tagName
+      if (tag === 'TEXTAREA' || tag === 'SELECT') return true
+      if (tag !== 'INPUT') return false
+      var type = (element.getAttribute('type') || 'text').toLowerCase()
+      return type !== 'submit' && type !== 'button' && type !== 'reset'
+    }
+
+    function linkInfo (element) {
+      if (element.tagName !== 'A') return undefined
+      var aria = element.getAttribute('aria-label')
+      return {
+        rel:       element.getAttribute('rel') || undefined,
+        text:      (element.textContent || '').trim() || undefined,
+        ariaLabel: aria || undefined,
+      }
+    }
+
+    document.addEventListener('click', function (event) {
+      var target = event.target
+      if (!(target instanceof Element)) return
+      if (inShadowDom(target)) { reportUnsupportedOnce('shadow-dom'); return }
+      // Clicking into a text field, a textarea or a select to focus it is not itself a recordable
+      // action — the fill/select the person then does is what becomes a step, on blur/change.
+      if (isTextEntry(target)) return
+      var element = clickable(target)
+      var id = markNode(element)
+      report({ kind: 'click', nodeId: id, html: document.documentElement.outerHTML, link: linkInfo(element) })
+    }, true)
+
+    function flushFill (target) {
+      if (!(target instanceof HTMLInputElement) && !(target instanceof HTMLTextAreaElement)) return
+      if (!focusValues.has(target)) return
+      var before = focusValues.get(target)
+      focusValues.delete(target)
+      if (before === target.value) return
+      if (inShadowDom(target)) { reportUnsupportedOnce('shadow-dom'); return }
+      var id = markNode(target)
+      report({
+        kind:  'fill',
+        nodeId: id,
+        html:  document.documentElement.outerHTML,
+        value: target.value,
+        field: { type: target.type || undefined, name: target.name || undefined, id: target.id || undefined },
+      })
+    }
+
+    document.addEventListener('focusin', function (event) {
+      var target = event.target
+      if (!(target instanceof HTMLInputElement) && !(target instanceof HTMLTextAreaElement)) return
+      focusValues.set(target, target.value)
+    }, true)
+
+    // Losing focus (Tab, clicking elsewhere) is the ordinary way a fill is reported.
+    document.addEventListener('focusout', function (event) { flushFill(event.target) }, true)
+
+    document.addEventListener('change', function (event) {
+      var target = event.target
+      if (!(target instanceof HTMLSelectElement)) return
+      if (inShadowDom(target)) { reportUnsupportedOnce('shadow-dom'); return }
+      var id = markNode(target)
+      report({
+        kind:  'select',
+        nodeId: id,
+        html:  document.documentElement.outerHTML,
+        value: target.value,
+        field: { type: 'select', name: target.name || undefined, id: target.id || undefined },
+      })
+    }, true)
+
+    document.addEventListener('keydown', function (event) {
+      if (event.key !== 'Enter') return
+      var target = event.target
+      // Enter often submits the very field it was pressed in, which never blurs first — flush its
+      // fill now, so typing a query then pressing Enter still reports the fill before the press.
+      flushFill(target)
+      var id = target instanceof Element && target !== document.body ? markNode(target) : undefined
+      report({ kind: 'keypress', nodeId: id, html: id === undefined ? undefined : document.documentElement.outerHTML, key: 'Enter' })
+    }, true)
+
+    var NEAR_BOTTOM_PX = 40
+    window.addEventListener('scroll', function () {
+      if (scrollTimer !== null) clearTimeout(scrollTimer)
+      scrollTimer = setTimeout(function () {
+        scrollTimer = null
+        var atBottom = window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - NEAR_BOTTOM_PX
+        if (atBottom) report({ kind: 'scroll', to: 'bottom' })
+      }, 300)
+    }, true)
+  })()`;
 }
-function nodesToSteps(nodes) {
-  return nodes.map(node => nodeToStep(node));
+
+/** Field names that mark a value as a secret even outside a `type="password"` input (issue #95). */
+const SECRET_NAME = /token|secret|api[-_]?key/i;
+/**
+ * Whether a recorded `fill`/`select` field's typed value is a secret: a
+ * `type="password"` input, or a field the person explicitly marked (`marked`,
+ * a future "mark as secret" UI action — not built by this phase, but the
+ * flag is honoured wherever it comes from), or a name/id matching `token`,
+ * `secret` or `api[-_]?key` (issue #95's exact wording).
+ *
+ * @param field - The field's type/name/id, as reported by `recorder-script.client.ts`.
+ * @param marked - The person explicitly marked this field as secret; default `false`.
+ * @returns Whether the field's value must become `{{env.NAME}}` instead of the real text.
+ */
+function isSecretField(field, marked = false) {
+  if (marked) return true;
+  if (field.type === 'password') return true;
+  const name = field.name ?? field.id ?? '';
+  return name.length > 0 && SECRET_NAME.test(name);
 }
-function nodeToStep(node) {
-  if (!isBracket(node)) return node.step;
-  const keys = Object.keys(node.step);
-  const step = {};
-  for (const key of keys) {
-    if (key === 'steps') step.steps = nodesToSteps(node.children);else if (key === 'else' && node.stepType === 'if') step.else = nodesToSteps(node.elseChildren ?? []);else step[key] = node.step[key];
-  }
-  if (!keys.includes('steps')) step.steps = nodesToSteps(node.children);
-  if (node.stepType === 'if' && node.elseChildren !== undefined && !keys.includes('else')) step.else = nodesToSteps(node.elseChildren);
-  return step;
+/**
+ * The `{{env.NAME}}` variable name a secret field suggests, from its own
+ * name/id (falling back to `PASSWORD` for a bare `type="password"` field
+ * with neither): `camelCase`/`kebab-case`/`snake_case` all become
+ * `SCREAMING_SNAKE_CASE`, punctuation dropped, so `user-pass`, `userPass`
+ * and `user_pass` all suggest `USER_PASS`.
+ *
+ * @param field - The field's type/name/id.
+ * @returns A valid env-var-shaped name (letters, digits, underscores, not starting with a digit).
+ */
+function secretEnvName(field) {
+  const source = field.name ?? field.id ?? (field.type === 'password' ? 'password' : 'secret');
+  const withBoundaries = source.replaceAll(/([a-z0-9])([A-Z])/g, '$1_$2');
+  const screaming = withBoundaries.replaceAll(/[^A-Z0-9]+/gi, '_').toUpperCase().replace(/^_+/, '').replace(/_+$/, '');
+  const named = screaming.length === 0 ? 'SECRET' : screaming;
+  return /^\d/.test(named) ? `_${named}` : named;
+}
+/**
+ * The placeholder a secret field's value becomes in the recorded recipe:
+ * never the real text, in the recipe JSON or anywhere the studio logs.
+ *
+ * @param field - The field's type/name/id.
+ * @returns `{{env.NAME}}`.
+ */
+function secretPlaceholder(field) {
+  return `{{env.${secretEnvName(field)}}}`;
 }
 
 /**
- * Opens a recipe folder: every `.json`/`.jsonl` recipe directly inside it
- * (core's own directory reading, so relative `file:` URLs resolve the same
- * way a real run would), parsed and, for each output recipe found, bound to
- * the input recipes that name it. Nothing throws for a bad recipe or a
- * recipe that does not bind: every problem is reported on its file with the
- * JSON path core already computes, exactly as `opencraw validate` prints it.
+ * Whether a `Wait for <selector>` step belongs between the action that just
+ * happened and the next one (issue #95): after a navigation or an XHR, the
+ * recorder inserts a wait for the element the person interacts with next, so
+ * a replayed recipe does not race the page's own load. Nothing to wait for
+ * without a next selector (a page-level key press, a scroll) — and no
+ * navigation or fetch either: a recording of a page that never moves should
+ * not fill up with waits nobody asked for.
+ *
+ * @param context - What happened since the previous action.
+ * @param nextSelector - The next action's own resolved selector, when it has one.
+ * @returns The wait step to insert before the next action's own step, or `undefined`.
+ */
+function insertWaitStep(context, nextSelector) {
+  if (nextSelector === undefined || !context.navigated && !context.xhr) return undefined;
+  return {
+    type: 'wait',
+    selector: nextSelector
+  };
+}
+
+/** The name Playwright's `context.exposeBinding` gives the function `recorder-script.client.ts` calls. */
+const REPORT_BINDING = '__opencraw_recorder_report__';
+/** The studio's own recorder profile: never a crawl's own profile, never the person's default browser (issue #95). */
+const RECORDER_PROFILE_NAME = 'studio-recorder';
+/** How long a click/key press is given to start a navigation before it counts as not having navigated. */
+const NAVIGATION_GRACE_MS = 600;
+/**
+ * Opens the headed browser window a flow is recorded in (issue #95, studio
+ * plan §3.1's last paragraph / phase 6): a Playwright persistent context, in
+ * the studio's own profile (`BrowserProfiles`, `headless: false` — the only
+ * precedent this codebase already has for a headed launch,
+ * `packages/core/src/browser-session/browser-profile.store.ts`), with
+ * `recorder-script.client.ts` installed on every page
+ * (`context.addInitScript`) and reporting through a context-wide binding
+ * (`context.exposeBinding`, so a page opened mid-recording — a link with
+ * `target=_blank`, say — is covered too, not only the first page).
+ *
+ * Each reported action is resolved into a verified selector
+ * (`selector-inference`, against the page's own current markup — issue
+ * #95's "verified against the page"), turned into a step
+ * (`action-to-step.mapper.ts`), and broadcast as an outline card built by
+ * `scope-outline`'s own `recipeToOutline` — the same sentence/bracket logic
+ * every other phase's cards already go through, never a second card format.
+ * A secret field's value is replaced by its `{{env.NAME}}` placeholder
+ * before it reaches a step, a card, or this function's return value: the
+ * real value is discarded the instant `secret-field.policy.ts` flags the
+ * field, never logged, never kept.
+ *
+ * Recording inside an iframe or shadow DOM is out of this phase's scope
+ * (issue #95): `recorder-script.client.ts` detects both and reports them as
+ * `unsupported` notes instead of guessing at a selector that would not
+ * verify.
  *
- * @param folder - The workspace folder.
- * @returns Every recipe file found, each with its validation and binding issues.
- * @throws Error when the folder does not exist or cannot be read.
+ * @param options - The start URL, the profile directory, and browser launch settings.
+ * @param callbacks - Where cards and notices go as they happen.
+ * @returns A handle: `stop` closes the window and returns every step recorded.
  */
-async function openWorkspace(folder) {
-  const documents = await readRecipeSource(folder);
-  const entries = documents.map(document => parseDocument(document));
-  const outputs = entries.filter(isParsed('output'));
-  const inputs = entries.filter(isParsed('input'));
-  for (const output of outputs) bindOutput(output, inputs);
-  for (const input of inputs) {
-    if (outputs.every(output => output.recipe.id !== input.recipe.output)) {
-      input.issues.push({
-        path: 'output',
-        message: `no output recipe "${input.recipe.output}" in this workspace`,
-        kind: 'binding'
+async function openRecorderSession(options, callbacks) {
+  const profiles = new BrowserProfiles(options.profileDir, {
+    ...options.browser,
+    headless: false
+  });
+  const session = await profiles.open(RECORDER_PROFILE_NAME, {}, {});
+  const context = session.context;
+  const steps = [];
+  let closed = false;
+  let waitPending = {
+    navigated: false,
+    xhr: false
+  };
+  let xhrSeen = false;
+  context.on('response', response => {
+    const type = response.request().resourceType();
+    if (type === 'xhr' || type === 'fetch') xhrSeen = true;
+  });
+  await context.exposeBinding(REPORT_BINDING, (_source, raw) => {
+    void handleRaw(raw);
+  });
+  await context.addInitScript({
+    content: recorderScript(REPORT_BINDING)
+  });
+  await session.page.goto(options.startUrl);
+  async function handleRaw(raw) {
+    if (closed) return;
+    const parsed = rawActionSchema.safeParse(raw);
+    if (!parsed.success) return;
+    const action = parsed.data;
+    if (action.kind === 'unsupported') {
+      callbacks.onNote({
+        kind: 'unsupported',
+        message: `recording inside ${action.reason === 'iframe' ? 'an iframe' : 'shadow DOM'} is not supported; continue outside it, or add this step by hand`
       });
+      return;
     }
+    await handleAction(action);
   }
-  return {
-    folder,
-    recipes: entries.map(({
-      file,
-      kind,
-      id,
-      issues,
-      content
-    }) => ({
-      file,
-      kind,
-      id,
-      issues,
-      text: `${JSON.stringify(content, null, 2)}\n`,
-      // The Steps tab needs steps to render: an output/unknown file has none. recipeToOutline never
-      // throws, so this covers a file that fails validation too (its outline just has "custom" cards).
-      outline: kind === 'input' ? recipeToOutline(content) : undefined
-    }))
-  };
-}
-/** Binds one output recipe to the inputs that name it, filing every binding issue back on the recipe it names. */
-function bindOutput(output, inputs) {
-  const matching = inputs.filter(input => input.recipe.output === output.recipe.id);
-  try {
-    bindRecipeSet(output.recipe, matching.map(input => input.recipe));
-  } catch (error) {
-    if (!(error instanceof RecipeBindingError)) throw error;
-    for (const issue of error.issues) {
-      const target = issue.recipeId === output.recipe.id ? output : matching.find(input => input.recipe.id === issue.recipeId);
-      target?.issues.push({
-        path: issue.path,
-        message: issue.message,
-        kind: 'binding'
+  async function handleAction(action) {
+    const page = session.page;
+    const urlBefore = page.url();
+    xhrSeen = false;
+    const resolved = resolveAction(action);
+    if (resolved === undefined) return;
+    if (action.kind === 'click' || action.kind === 'keypress') resolved.navigated = await detectNavigation(page, urlBefore);
+    if (resolved.field !== undefined && resolved.value !== undefined && isSecretField(resolved.field)) resolved.value = secretPlaceholder(resolved.field);
+    const waitStep = insertWaitStep(waitPending, resolved.selector);
+    if (waitStep !== undefined) pushStep(waitStep, false);
+    waitPending = {
+      navigated: resolved.navigated !== undefined,
+      xhr: xhrSeen
+    };
+    const step = actionToStep(resolved);
+    if (step === undefined) return;
+    pushStep(step, resolved.field !== undefined && isSecretField(resolved.field));
+    if (resolved.navigated !== undefined && action.kind === 'click' && looksLikeNextLink(resolved.link, resolved.selector)) {
+      callbacks.onNote({
+        kind: 'next-link',
+        message: `this click looks like a "next" link — turn it into "For every page — click ${resolved.selector ?? ''}"?`
       });
     }
   }
-}
-function isParsed(kind) {
-  return entry => entry.kind === kind && entry.recipe !== undefined;
-}
-function parseDocument(document) {
-  const kind = document.content?.kind;
-  if (kind === 'output') return parseOne(document.source, document.content, 'output', parseOutputRecipe);
-  if (kind === 'input') return parseOne(document.source, document.content, 'input', parseInputRecipe);
+  function pushStep(step, secret) {
+    steps.push(step);
+    const outline = recipeToOutline({
+      steps
+    });
+    const node = outline.steps.at(-1);
+    if (node !== undefined) callbacks.onCard(node, secret);
+  }
   return {
-    file: document.source,
-    kind: 'unknown',
-    content: document.content,
-    issues: [{
-      path: 'kind',
-      message: '"kind" is missing or not "input"/"output"',
-      kind: 'validation'
-    }]
+    page: session.page,
+    stop: async () => {
+      if (!closed) {
+        closed = true;
+        await session.close();
+      }
+      return {
+        steps: steps
+      };
+    }
   };
 }
-function parseOne(file, content, kind, parse) {
-  try {
-    const recipe = parse(content, file);
-    return {
-      file,
-      kind,
-      content,
-      id: recipe.id,
-      issues: [],
-      recipe
-    };
-  } catch (error) {
-    if (!(error instanceof RecipeValidationError)) throw error;
-    return {
-      file,
-      kind,
-      content,
-      issues: error.issues.map(issue => ({
-        path: issue.path === '' ? '(root)' : issue.path,
-        message: issue.message,
-        kind: 'validation'
-      }))
-    };
+/**
+ * Resolves one raw action's `nodeId` (when it has one — `scroll` and a
+ * page-level `keypress` do not) into a verified selector, the same way
+ * `infer-selector.handler.ts` does for a pick: `pathToNode` off the
+ * document the action itself carries (`action.html`, captured by
+ * `recorder-script.client.ts` at the moment of the event — see
+ * `recorded-action.contract.ts` for why that beats a later `page.content()`),
+ * `candidatesFor`/`bestCandidate` off that path.
+ *
+ * @param action - The raw action, `unsupported` already ruled out by the caller.
+ * @returns The resolved action (selector filled in where relevant), or `undefined` when no candidate verified — the action is dropped rather than recorded with a guessed, unverified selector.
+ */
+function resolveAction(action) {
+  if (action.kind === 'scroll') return {
+    kind: 'scroll'
+  };
+  if (action.kind === 'keypress' && action.nodeId === undefined) return {
+    kind: 'keypress',
+    key: action.key
+  };
+  const nodeId = action.nodeId;
+  const html = action.html;
+  if (nodeId === undefined || html === undefined) return undefined;
+  const path = pathToNode(html, nodeId);
+  if (path === undefined || crossesShadowRoot(path)) return undefined;
+  const best = bestCandidate(html, candidatesFor(path), nodeId);
+  if (best === undefined) return undefined;
+  switch (action.kind) {
+    case 'click':
+      {
+        return {
+          kind: 'click',
+          selector: best.selector,
+          link: action.link
+        };
+      }
+    case 'fill':
+      {
+        return {
+          kind: 'fill',
+          selector: best.selector,
+          value: action.value,
+          field: action.field
+        };
+      }
+    case 'select':
+      {
+        return {
+          kind: 'select',
+          selector: best.selector,
+          value: action.value,
+          field: action.field
+        };
+      }
+    case 'keypress':
+      {
+        return {
+          kind: 'keypress',
+          selector: best.selector,
+          key: action.key
+        };
+      }
   }
 }
-
 /**
- * Writes a recipe back to its file: pretty JSON, a 2-space indent, a
- * trailing newline. Phase 0 takes the JSON tab's whole parsed object rather
- * than a patch, so this is a full replacement, not a splice: loading a file
- * the studio has not touched and saving it again keeps every key, value and
- * key order (`JSON.parse` preserves insertion order, and `JSON.stringify`
- * writes it back), but not necessarily the file's exact original formatting
- * (alignment, how arrays wrap, a trailing comment). Byte-identical
- * round-trip for a hand-formatted file is future work; see this file's test
- * for what is guaranteed today.
+ * Whether, and where to, the page navigated within `NAVIGATION_GRACE_MS` of
+ * a click or key press: polled rather than driven (the navigation, if any,
+ * was started by the person in the live window, not by this function), with
+ * the main frame's own navigation response (for its status) picked up
+ * alongside.
  *
- * @param path - The recipe file to write.
- * @param recipe - The whole recipe object.
+ * @param page - The recorder's own page.
+ * @param urlBefore - `page.url()` right before the action was reported.
+ * @returns The page reached and its status, or `undefined` when the URL never changed.
  */
-async function saveRecipe(path, recipe) {
-  await writeFile(path, `${JSON.stringify(recipe, null, 2)}\n`, 'utf8');
+async function detectNavigation(page, urlBefore) {
+  let response;
+  const onResponse = candidate => {
+    if (candidate.request().isNavigationRequest() && candidate.frame() === page.mainFrame()) response = candidate;
+  };
+  page.on('response', onResponse);
+  const deadline = Date.now() + NAVIGATION_GRACE_MS;
+  try {
+    while (Date.now() < deadline && page.url() === urlBefore) {
+      await new Promise(resolve => setTimeout(resolve, 25));
+    }
+  } finally {
+    page.off('response', onResponse);
+  }
+  if (page.url() === urlBefore) return undefined;
+  try {
+    await page.waitForLoadState('load', {
+      timeout: NAVIGATION_GRACE_MS
+    });
+  } catch {
+    // The load event never fired within the grace period; the page still moved, so report it anyway.
+  }
+  return {
+    url: page.url(),
+    status: response?.status()
+  };
 }
 
-/** @returns Fresh state for a new server instance: no workspace open, no run, no sockets, an empty snapshot cache, no last runs, Playwright's own default browser. */
-function createStudioState() {
+/**
+ * Handles `start-recording`: opens the studio's own headed browser window
+ * on the named recipe's start point (issue #95, phase 6) and streams
+ * `recording-card`/`recording-note` events as the person drives it. One
+ * recording at a time, like one sample run at a time: a second
+ * `start-recording` stops whatever was already open first.
+ *
+ * @param state - The server state: `folder` must already be set, `recorderProfileDir` names the studio's own recorder profile (never a crawl's own, never the person's default browser).
+ * @param command - The command.
+ * @returns `{ started: true }` once the window is open.
+ * @throws Error when no workspace is open, or the recipe cannot be found or loaded.
+ */
+async function handleStartRecording(state, command) {
+  if (state.folder === undefined) throw new Error('open a workspace first');
+  await state.activeRecording?.stop();
+  const {
+    input
+  } = await loadRecipePair(state.folder, command.recipeId);
+  const point = input.start[0];
+  if (point === undefined) throw new Error(`recipe "${command.recipeId}" has no start point`);
+  const handle = await openRecorderSession({
+    startUrl: point.url,
+    profileDir: state.recorderProfileDir,
+    browser: state.browser
+  }, {
+    onCard: (node, secret) => {
+      broadcast(state, {
+        type: 'recording-card',
+        node,
+        secret
+      });
+    },
+    onNote: note => {
+      broadcast(state, {
+        type: 'recording-note',
+        kind: note.kind,
+        message: note.message
+      });
+    }
+  });
+  state.activeRecording = handle;
   return {
-    sockets: new Set(),
-    snapshots: createSnapshotCache(),
-    lastRuns: createLastRunCache()
+    started: true
   };
 }
 /**
- * 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.
+ * Handles `stop-recording`: closes the recording window, if one is open,
+ * and answers with every step recorded, in order — enough for the caller to
+ * build "make this the login" (`session.bootstrap`) or "keep as steps"
+ * without asking the server again. Also broadcasts `recording-stopped`, so
+ * every connected client (not only the one that asked) knows the window
+ * closed.
  *
- * @param state - The server state holding the connected sockets.
- * @param event - The event to send.
+ * @param state - The server state holding the active recording, if any.
+ * @param _command - The command (carries nothing beyond its type).
+ * @returns Every step recorded, in order; empty when nothing was recording.
  */
-function broadcast(state, event) {
-  const text = JSON.stringify(event);
-  for (const socket of state.sockets) {
-    try {
-      socket.send(text);
-    } catch {
-      state.sockets.delete(socket);
-    }
-  }
+async function handleStopRecording(state, _command) {
+  const recording = state.activeRecording;
+  state.activeRecording = undefined;
+  if (recording === undefined) return {
+    steps: []
+  };
+  const {
+    steps
+  } = await recording.stop();
+  broadcast(state, {
+    type: 'recording-stopped',
+    steps
+  });
+  return {
+    steps
+  };
 }
 
 /**
- * Handles `open-workspace`: reads the folder, remembers it as the server's
- * current workspace (every later command that names a recipe resolves it
- * against this folder), and tells every connected client the workspace changed.
+ * Handles `responses-seen`: the JSON responses observed while a recipe's
+ * start page rendered (`page-inspector`'s `responses-seen.use-case.ts`,
+ * issue #93), for the Inspect panel's "responses seen" list — picking one
+ * is the seam the UI uses to switch the recipe to api mode (issue #93's
+ * acceptance; the JSON tree canvas that follows is phase 5's).
  *
- * @param state - The server state to update.
+ * @param state - The server state: `folder` must already be set.
  * @param command - The command.
- * @returns The workspace's recipes and their issues.
+ * @returns The observed responses.
+ * @throws Error when no workspace is open, or the recipe cannot be found or loaded.
  */
-async function handleOpenWorkspace(state, command) {
-  const view = await openWorkspace(command.folder);
-  state.folder = command.folder;
-  broadcast(state, {
-    type: 'workspace-changed'
-  });
-  return view;
+async function handleResponsesSeen(state, command) {
+  if (state.folder === undefined) throw new Error('open a workspace first');
+  const {
+    input
+  } = await loadRecipePair(state.folder, command.recipeId);
+  const responses = await responsesSeen(input, command.path, state.browser);
+  return {
+    responses
+  };
 }
 
 /**
@@ -2167,6 +4397,25 @@ function serveStatic(root, pathname, response) {
   createReadStream(file).pipe(response);
 }
 
+/**
+ * Handles `table-preview`: the PDF canvas's live preview of a `table`
+ * extract's options (`document-view`'s `table-preview.use-case.ts`, studio
+ * plan §3.4, issue #94's 5b), off the same cached snapshot `take-snapshot`
+ * 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 matches, 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 handleTablePreview(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 (!isPdfDocument(snapshot.body)) throw new Error(`"${command.recipeId}" at "${command.path}" is not a PDF snapshot: table-preview only reads a read PDF document`);
+  return previewPdfTable(snapshot.body, command.options);
+}
+
 /**
  * Handles `take-snapshot`: loads the named input recipe, captures its
  * snapshot at `command.path` (only `"start"` is captured for now — see
@@ -2182,13 +4431,24 @@ function serveStatic(root, pathname, response) {
 async function handleTakeSnapshot(state, command) {
   if (state.folder === undefined) throw new Error('open a workspace first');
   const cached = cachedSnapshot(state.snapshots, command.recipeId, command.path);
-  if (cached !== undefined) return cached;
+  if (cached !== undefined) return snapshotView(cached);
   const {
     input
   } = await loadRecipePair(state.folder, command.recipeId);
   const snapshot = await takeSnapshot(input, command.path, state.browser);
   putSnapshot(state.snapshots, command.recipeId, command.path, snapshot);
-  return snapshot;
+  return snapshotView(snapshot);
+}
+/** The wire view of a cached snapshot: `html`/`nodeCount`/`baseUrl`/`format`, never `rawHtml` or the parsed `body` (server-side only — see `SnapshotResult`'s own doc comments). */
+function snapshotView(snapshot) {
+  return {
+    html: snapshot.html,
+    nodeCount: snapshot.nodeCount,
+    baseUrl: snapshot.baseUrl,
+    ...(snapshot.format !== undefined && {
+      format: snapshot.format
+    })
+  };
 }
 
 /**
@@ -2354,6 +4614,7 @@ async function startStudioServer(options = {}) {
   const state = createStudioState();
   if (options.initialFolder !== undefined) state.folder = options.initialFolder;
   state.browser = options.browser;
+  if (options.recorderProfileDir !== undefined) state.recorderProfileDir = options.recorderProfileDir;
   const server = createServer((request, response) => {
     void handleRequest(request, response, token, state, uiRoot);
   });
@@ -2375,6 +4636,7 @@ async function startStudioServer(options = {}) {
 }
 async function stop(server, state) {
   await state.activeRun?.stop();
+  await state.activeRecording?.stop();
   server.closeAllConnections();
   await new Promise((resolve, reject) => {
     server.close(error => error === undefined ? resolve() : reject(error));
@@ -2395,9 +4657,41 @@ async function handleRequest(request, response, token, state, uiRoot) {
     await handleCommand(request, response, state);
     return;
   }
-  if (url.pathname === '/' && url.searchParams.get('token') !== null) response.setHeader('set-cookie', `${TOKEN_COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/`);
+  if (url.pathname === '/api/pdf-bytes' && request.method === 'GET') {
+    await handlePdfBytesRequest(response, state, url.searchParams);
+    return;
+  }
+  if (url.pathname === '/' && url.searchParams.has('token')) response.setHeader('set-cookie', `${TOKEN_COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/`);
   serveStatic(uiRoot, url.pathname, response);
 }
+/**
+ * `GET /api/pdf-bytes?recipeId=…&path=…`: the raw bytes of a cached PDF
+ * snapshot (`pdf-bytes.handler.ts`, studio plan §3.4, issue #94's 5b) — the
+ * PDF canvas's `pdf.js` fetches this URL directly, so it answers bytes, not
+ * the JSON envelope every `/api/command` response uses.
+ */
+async function handlePdfBytesRequest(response, state, query) {
+  const recipeId = query.get('recipeId');
+  const path = query.get('path');
+  if (recipeId === null || path === null) {
+    respondJson(response, 400, {
+      error: '"recipeId" and "path" are required query params'
+    });
+    return;
+  }
+  try {
+    const bytes = await handlePdfBytes(state, recipeId, path);
+    response.writeHead(200, {
+      'content-type': 'application/pdf',
+      'content-length': bytes.byteLength
+    });
+    response.end(Buffer.from(bytes));
+  } catch (error) {
+    respondJson(response, 500, {
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+}
 async function handleCommand(request, response, state) {
   let command;
   try {
@@ -2466,6 +4760,50 @@ function dispatch(command, state) {
       {
         return handleExplainWhy(state, command);
       }
+    case 'inspect-page':
+      {
+        return Promise.resolve(handleInspectPage(state, command));
+      }
+    case 'responses-seen':
+      {
+        return handleResponsesSeen(state, command);
+      }
+    case 'document-tree':
+      {
+        return Promise.resolve(handleDocumentTree(state, command));
+      }
+    case 'pdf-view':
+      {
+        return Promise.resolve(handlePdfView(state, command));
+      }
+    case 'table-preview':
+      {
+        return Promise.resolve(handleTablePreview(state, command));
+      }
+    case 'grid-view':
+      {
+        return handleGridView(state, command);
+      }
+    case 'grid-preview':
+      {
+        return Promise.resolve(handleGridPreview(state, command));
+      }
+    case 'deck-view':
+      {
+        return Promise.resolve(handleDeckView(state, command));
+      }
+    case 'deck-preview':
+      {
+        return Promise.resolve(handleDeckPreview(state, command));
+      }
+    case 'start-recording':
+      {
+        return handleStartRecording(state, command);
+      }
+    case 'stop-recording':
+      {
+        return handleStopRecording(state);
+      }
   }
 }
 function respondJson(response, status, body) {
@@ -2522,5 +4860,5 @@ async function main(argv) {
   process.on('SIGTERM', shutdown);
 }
 
-export { explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, inferSelectorCommandSchema, inferSelectorViewSchema, loadRecipePair, main, missingWhyTargetSchema, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, recordRejectedEventSchema, rejectedWhyTargetSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startStudioServer, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, whyTargetSchema, whyViewSchema, workspaceChangedEventSchema, workspaceViewSchema };
+export { deckChartSeriesViewSchema, deckChartViewSchema, deckDocumentViewSchema, deckPreviewCommandSchema, deckPreviewOptionsSchema, deckShapeViewSchema, deckSlideViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, deckViewCommandSchema, documentTreeCommandSchema, documentTreeNodeViewSchema, documentTreeViewSchema, domTreeNodeViewSchema, explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, gridCellViewSchema, gridMergeViewSchema, gridPreviewCommandSchema, gridPreviewOptionsSchema, gridSheetViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, gridViewCommandSchema, inferSelectorCommandSchema, inferSelectorViewSchema, inspectPageCommandSchema, inspectViewSchema, loadRecipePair, main, missingWhyTargetSchema, observedResponseSchema, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, pageDataFindingSchema, pdfCellViewSchema, pdfDocumentViewSchema, pdfPageViewSchema, pdfRowViewSchema, pdfViewCommandSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, recordRejectedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, rejectedWhyTargetSchema, responsesSeenCommandSchema, responsesSeenViewSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, 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