@opencraw/studio 0.0.6 → 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 { BrowserClient, HttpClient, NODE_ID_ATTRIBUTE, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, 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,13 +121,210 @@ const inferSelectorCommandSchema = z.object({
   path: z.string().min(1),
   nodeIds: z.union([onePickedNodeSchema, twoPickedNodesSchema])
 });
-const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema]);
+/**
+ * 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'),
+  recipeId: z.string().min(1),
+  recordIndex: z.int().nonnegative(),
+  field: z.string().min(1)
+});
+/** A rejected record, by its position in the last sample run's `rejectedRecords`. */
+const rejectedWhyTargetSchema = z.object({
+  kind: z.literal('rejected'),
+  recipeId: z.string().min(1),
+  rejectedIndex: z.int().nonnegative()
+});
+const whyTargetSchema = z.discriminatedUnion('kind', [missingWhyTargetSchema, rejectedWhyTargetSchema]);
+/**
+ * Explains one missing or rejected value from the recipe's last sample run
+ * (`explain-why.use-case.ts`, issue #92's Why? tab): the mapping trace and
+ * scope snapshot `run-sample` already kept, the step that bound the value's
+ * source id and whether it ran, was skipped or found nothing, and the
+ * missing-value policy that applied.
+ */
+const explainWhyCommandSchema = z.object({
+  type: z.literal('explain-why'),
+  target: whyTargetSchema
+});
+/**
+ * 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()
 });
 
 /**
@@ -186,12 +385,32 @@ const traceLineEventSchema = z.object({
   type: z.literal('trace-line'),
   line: z.string()
 });
-/** One record a sample run emitted. */
+/** One transform's effect within a field's trace: its `op` and the value it returned. */
+const traceStepSchema = z.object({
+  op: z.string(),
+  value: z.unknown()
+});
+/** One entry of a mapping trace field: what a rule's `from` read, and the value after each transform, in order (`@opencraw/core`'s `FieldTrace`). */
+const fieldTraceSchema = z.object({
+  from: z.unknown(),
+  steps: z.array(traceStepSchema)
+});
+/** One record a sample run emitted: `scope` (what it was mapped from) and `mapping` (each field's trace) ride along, so the Record tab (#92) can show a transform chain's real values without a second round trip. */
 const recordEventSchema = z.object({
   type: z.literal('record'),
   recipeId: z.string(),
   key: z.string().nullable(),
-  data: z.record(z.string(), z.unknown())
+  data: z.record(z.string(), z.unknown()),
+  scope: z.record(z.string(), z.unknown()).optional(),
+  mapping: z.record(z.string(), fieldTraceSchema).optional()
+});
+/** One record a sample run rejected (a field's `skip-record` policy on a missing or uncoercible value). */
+const recordRejectedEventSchema = z.object({
+  type: z.literal('record-rejected'),
+  recipeId: z.string(),
+  field: z.string(),
+  reason: z.string(),
+  scope: z.record(z.string(), z.unknown()).optional()
 });
 /** A sample run ended: how many records, and why it stopped when it did not finish on its own. */
 const runFinishedEventSchema = z.object({
@@ -208,7 +427,32 @@ const runFinishedEventSchema = z.object({
 const workspaceChangedEventSchema = z.object({
   type: z.literal('workspace-changed')
 });
-const studioEventSchema = z.discriminatedUnion('type', [traceLineEventSchema, recordEventSchema, 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({
@@ -256,6 +500,250 @@ const startPageViewSchema = z.object({
   html: z.string()
 });
 
+/** What `explain-why` answers with: the sentence (`why-sentence.mapper.ts`'s `buildWhySentence`), plus the structured facts a click can act on — a link back to the step that bound the value, the policy that applied. */
+const whyViewSchema = z.object({
+  sentence: z.string(),
+  field: z.string(),
+  recipeId: z.string(),
+  outcome: z.enum(['missing', 'rejected']),
+  /** The JSON path (`steps.2.steps.0`) of the step that bound the value's source id, when one was found in the recipe. */
+  stepPath: z.string().optional(),
+  /** The missing-value policy that applied (`nullable`, `default`, `null`, `fail`, `skip-record`), when one could be resolved. */
+  policy: z.string().optional(),
+  /** The engine's own rejection reason, for a rejected record. */
+  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. */
@@ -340,13 +828,13 @@ async function fetchApi(url) {
     const response = await client.send({
       url
     });
-    return textOf$1(response.body);
+    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$1(body) {
+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);
@@ -508,7 +996,8 @@ async function snapshotWeb(url, browser) {
       const rewritten = rewriteDocument(html, baseUrl);
       return {
         ...rewritten,
-        baseUrl
+        baseUrl,
+        rawHtml: html
       };
     } finally {
       await session.close();
@@ -523,17 +1012,21 @@ async function snapshotApi(url) {
     const response = await client.send({
       url
     });
-    const rewritten = rewriteDocument(textOf(response.body), url);
+    const text = textOf$1(response.body);
+    const rewritten = rewriteDocument(text, url);
     return {
       ...rewritten,
-      baseUrl: url
+      baseUrl: url,
+      rawHtml: text,
+      format: response.format,
+      body: response.body
     };
   } finally {
     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(body) {
+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>`;
@@ -559,1035 +1052,3189 @@ function keyOf(recipeId, path) {
 }
 
 /**
- * Finds and parses one input recipe of a workspace folder, and the output
- * recipe it names.
+ * 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 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 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.
  */
-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)
-  };
-}
-function kindOf(content) {
-  return content?.kind;
-}
-function idOf(content) {
-  return content?.id;
+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());
 }
 
 /**
- * Runs one input recipe of a workspace folder as a sample: `debug: true` (so
- * each `record:emit` carries its data), 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.
+ * 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 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.
+ * @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.
  */
-async function runSample(folder, recipeId, budget, callbacks, browser) {
-  const {
-    input,
-    output
-  } = await loadRecipePair(folder, recipeId);
-  const set = bindRecipeSet(output, [input]);
-  const sink = memorySink();
-  const crawler = createCrawler({
-    sink,
-    debug: true,
-    sample: budget,
-    browser,
-    onEvent: event => {
-      const line = traceLine(event);
-      if (line !== undefined) callbacks.onTraceLine(line);
-      if (event.type === 'record:emit') callbacks.onRecord({
-        key: event.key,
-        data: event.data
-      });
-    }
-  });
-  const result = runToResult(crawler, set, sink);
-  return {
-    stop: () => crawler.close(),
-    result
-  };
-}
-async function runToResult(crawler, set, sink) {
+async function rereadCsv(url, override) {
+  const client = await HttpClient.open({});
   try {
-    const report = await crawler.run(set);
-    const recipe = report.recipes[0];
-    return {
-      recipeId: recipe.recipeId,
-      emitted: recipe.emitted,
-      rejected: recipe.rejected,
-      duplicates: recipe.duplicates,
-      durationMs: recipe.durationMs,
-      error: recipe.error,
-      stoppedBy: recipe.stoppedBy,
-      records: sink.records.map(record => ({
-        key: record.key,
-        data: record.data
-      }))
-    };
+    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 crawler.close();
+    await client.dispose();
   }
 }
 
+/** 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}$/;
 /**
- * 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).
+ * 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 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 document - The read workbook (a spreadsheet or a CSV).
+ * @returns The view.
  */
-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);
+function workbookDocumentView(document) {
   return {
-    html
+    sheets: document.sheets.map(sheet => sheetView(sheet)),
+    ...(document.csv !== undefined && {
+      csv: document.csv
+    })
+  };
+}
+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 cellView(cell) {
+  return {
+    value: cell,
+    type: cellType(cell)
+  };
+}
+function cellType(cell) {
+  if (typeof cell === 'number') return 'number';
+  if (typeof cell === 'boolean') return 'boolean';
+  return ISO_DATE_OR_TIME.test(cell) ? 'date' : 'string';
+}
+/** `B10:B13` (or a single cell, `A1`) as 0-based inclusive bounds; `undefined` for anything else — mirrors `@opencraw/core`'s own (unexported) `rangeOf`/`cellOf` in `grid-table.algorithm.ts`: a small pure parse, kept here rather than reached for across the package boundary (a sibling slice's non-`index.ts` file is never imported, and this is `@opencraw/core`'s own private helper, not even on its barrel). */
+function rangeOf(reference) {
+  const [from, to = from] = reference.split(':', 2);
+  const start = cellOf(from);
+  const end = cellOf(to);
+  if (start === undefined || end === undefined) return undefined;
+  return {
+    top: Math.min(start.row, end.row),
+    left: Math.min(start.column, end.column),
+    bottom: Math.max(start.row, end.row),
+    right: Math.max(start.column, end.column)
+  };
+}
+function cellOf(reference) {
+  const match = /^\$?([A-Z]+)\$?(\d+)$/i.exec(reference.trim());
+  if (match === null) return undefined;
+  const letters = match[1].toUpperCase();
+  let column = 0;
+  for (const char of letters) column = column * 26 + (char.codePointAt(0) ?? 64) - 64;
+  return {
+    row: Number(match[2]) - 1,
+    column: column - 1
   };
 }
 
-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 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 $ - The parsed document.
- * @param node - The element to describe.
- * @returns The path, root first.
+ * @param document - The read deck.
+ * @returns The view.
  */
-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 deckDocumentView(document) {
+  return {
+    width: document.width,
+    height: document.height,
+    slides: document.slides.map(slide => slideView(slide, document.height))
+  };
 }
-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;
+function slideView(slide, slideHeight) {
   return {
-    tag,
-    id: attrs.id,
-    classes,
-    attrs,
-    index: Math.max(index, 1),
-    siblingCount: Math.max(siblings.length, 1)
+    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 isElement(node) {
-  return node !== undefined && node.type === 'tag';
+function shapeView(shape) {
+  return {
+    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]
+    }))
+  };
 }
 /**
- * Whether `id` looks handed by a framework (`react-`, a CSS-module or a
- * `radix-`/`mui-` autogenerated one) rather than by the site's own markup —
- * `class-token.policy.ts` has the equivalent check for class tokens, kept
- * separate because ids and classes are ranked at different tiers.
+ * 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 isStableId(id) {
-  return id.length > 0 && !GENERATED_ID.test(id);
+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;
 /**
- * Whether `path` failed to reach the real document root. `domPathOf` walks
- * up through cheerio's own `.parent()`, which (matching real DOM semantics)
- * never crosses from a `<template>`'s content into the light DOM outside
- * it — a `<template shadowrootmode>` is exactly declarative shadow DOM, the
- * only shadow-DOM shape that can show up in static, server-captured markup
- * at all (imperative `attachShadow()` content never serialises into
- * `page.content()`/a fetched response in the first place, so that case
- * cannot reach this slice and needs no separate detection). A path whose
- * first level is not `html` was cut short at exactly this kind of boundary:
- * v1 does not pierce it, so callers report a clear "shadow DOM is not
- * supported" error instead of building ancestor-based candidates over a
- * chain that stops partway up.
+ * 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.
+ *
+ * @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 crossesShadowRoot(path) {
-  return path.length === 0 || path[0].tag !== 'html';
+function documentTreeView(body) {
+  if (body.kind === 'json') return {
+    format: 'json',
+    root: jsonNode(body.data, '$', 'root')
+  };
+  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)`);
 }
-/** Parses `html` and returns cheerio's API, for callers that need more than one path from the same document. */
-function parseDocument$1(html) {
-  return load(html);
+function listFields(path, context) {
+  if (context === undefined) return {};
+  return {
+    listPath: context.generalPrefix + path.slice(context.itemPrefix.length),
+    listCount: context.count
+  };
+}
+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 (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 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);
+}
+
 /**
- * The path to the element the snapshot stamped with `nodeId` (its
- * `data-oc-node` attribute — `@opencraw/core`'s `NODE_ID_ATTRIBUTE`,
- * `packages/studio/src/page-snapshot/rewrite-document.mapper.ts`). This is
- * how a click in the content pane's iframe — which only ever needs to read
- * that one attribute off the element the user clicked — turns into
- * something `selector-inference`'s other algorithms can work with, without
- * the browser-side picker script needing to know anything about ancestry,
- * classes or candidate ranking itself.
+ * 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 html - The snapshot document (already stamped with node ids).
- * @param nodeId - The `data-oc-node` value to find.
- * @returns The node's path, or `undefined` when no element carries that id.
+ * @param document - The read PDF.
+ * @returns The view.
  */
-function pathToNode(html, nodeId) {
-  const $ = parseDocument$1(html);
-  const found = $(`[${NODE_ID_ATTRIBUTE}="${cssAttributeValue(nodeId)}"]`);
-  return found.length === 0 ? undefined : domPathOf($, found.first());
-}
-function cssAttributeValue(value) {
-  return value.replaceAll('\\', String.raw`\\`).replaceAll('"', String.raw`\"`);
+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
+    }))
+  };
 }
 
-/** Attributes worth reading instead of text, in preference order, when the clicked element has one. */
-const PREFERRED_ATTRS = {
-  a: ['href'],
-  img: ['src', 'alt']
-};
 /**
- * What a `Read` card's `take` should be for the element a pick landed on
- * (issue #91, studio plan §3.2): `attr:href` for an `<a>`, `attr:src` for an
- * `<img>`, `attr:<name>` for the first `data-*` attribute otherwise, `json`
- * for a `<script type="application/json">`, else the default, `text`.
+ * 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 level - The clicked element's own level (the last entry of its `DomPath`).
- * @returns The `take` value to put on the `extract` step.
+ * The workbook grid's live preview (issue #94's 5c) is `previewGridTable`,
+ * below: the same idea (a pure re-run of the options against the cached
+ * document), but its own result shape — a workbook table has no page, no
+ * column bands, no wrapped-row regrouping, so folding it into
+ * `TablePreviewMatch`/`TablePreviewResult` would leave most of those fields
+ * meaningless for a grid pick; a `GridTablePreviewMatch`/`GridTablePreviewResult`
+ * sibling reads honestly instead.
+ *
+ * @param document - The already-read PDF.
+ * @param options - The `table` extract's options, not yet compiled to `RegExp`.
+ * @returns Every match, each with the exact row indices to highlight — or `error` (and no matches) when a pattern is not a valid regular expression, expected while the person is still typing it.
  */
-function takeKindFor(level) {
-  if (level.tag === 'script' && (level.attrs.type ?? '').toLowerCase() === 'application/json') return 'json';
-  const preferred = PREFERRED_ATTRS[level.tag];
-  if (preferred !== undefined) {
-    const attribute = preferred.find(name => level.attrs[name] !== undefined);
-    if (attribute !== undefined) return `attr:${attribute}`;
+function previewPdfTable(document, options) {
+  let query;
+  try {
+    query = {
+      header: compile(options.header, 'selector'),
+      until: options.until === undefined ? undefined : compile(options.until, 'until'),
+      columns: options.columns === undefined ? undefined : Object.fromEntries(Object.entries(options.columns).map(([key, pattern]) => [key, compile(pattern, `columns.${key}`)])),
+      align: options.align
+    };
+  } catch (error) {
+    return {
+      matches: [],
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+  const analyses = analyzeTables(document, query);
+  return {
+    matches: analyses.map(analysis => ({
+      page: analysis.page,
+      headerRowIndex: analysis.headerRowIndex,
+      matchedRowIndices: rowIndicesOf(analysis),
+      bands: analysis.bands,
+      bandTolerance: analysis.bandTolerance,
+      table: analysis.table
+    }))
+  };
+}
+function rowIndicesOf(analysis) {
+  const indices = new Set([analysis.headerRowIndex, ...analysis.rowGroups.flat()]);
+  if (analysis.untilRowIndex !== undefined) indices.add(analysis.untilRowIndex);
+  return [...indices].sort((a, b) => a - b);
+}
+function compile(source, where) {
+  try {
+    return new RegExp(source, 'i');
+  } catch (error) {
+    throw new Error(`${where}: invalid pattern ${source} (${error.message})`, {
+      cause: error
+    });
   }
-  const dataAttribute = Object.keys(level.attrs).find(name => name.startsWith('data-') && name !== 'data-oc-node' && name !== 'data-oc-hidden');
-  if (dataAttribute !== undefined) return `attr:${dataAttribute}`;
-  return 'text';
 }
-
 /**
- * Which class tokens are worth building a selector on. A hand-authored class
- * (`product_pod`, `price_color`) survives a rebuild; a generated one
- * (a content hash, a CSS-module suffix, a styled-components token) does not,
- * so a candidate built on it looks fine on the snapshot it was picked from
- * and breaks on the very next deploy. This is the "generated/hashed class
- * names" tradeoff issue #91 calls out explicitly: the heuristics below are a
- * reasoned judgement call, not a guarantee — see the doc comments on each
- * pattern for what real-world tool it targets.
+ * 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.
  */
-const GENERATED_TOKEN_PATTERNS = [/** styled-components / emotion: `sc-bdVaJa`, `css-1x2y3z4` */
-/^(?:sc|css)-[a-z0-9]+$/i, /** CSS Modules, most bundlers' default hash suffix: `wrapper__3fA9k`, `Button-module_root__aB3dK` */
-/__[a-z0-9]{4,10}$/i, /** JSS / MUI: `jss123`, `MuiButton-root-145` */
-/^(?:jss|mui[a-z]*-)[a-z0-9-]*\d{2}$/i, /** A token that is only digits: not a class a human would type. */
-/^\d+$/, /** A bare hex hash: `a3f9c21`, `1a2b3c4d` (6+ hex chars, nothing else). */
-/^[0-9a-f]{6,}$/i, /** Tailwind/atomic-CSS-in-JS runtime classes some bundlers emit: `_1a2b3c` */
-/^_[0-9a-z]{5,}$/i];
+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
+    }))
+  };
+}
 /**
- * Whether a class token looks hand-authored and safe to build a selector on.
+ * 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 token - One class, no surrounding whitespace.
- * @returns `false` for anything matching a known generated-class shape.
+ * @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 isStableClassToken(token) {
-  return token.length > 0 && GENERATED_TOKEN_PATTERNS.every(pattern => !pattern.test(token));
+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 subset of `tokens` worth ranking a selector candidate on, order kept.
+ * Handles `deck-preview`: the deck canvas's live preview of a `table`
+ * extract's options (`document-view`'s `table-preview.use-case.ts`'s
+ * `previewDeckTable`, studio plan §3.4, issue #94's 5d), off the same cached
+ * snapshot `take-snapshot`/`deck-view` already captured — a pure computation
+ * over it, so this answers instantly on every option change, no re-fetch or
+ * re-parse.
  *
- * @param tokens - An element's class list.
- * @returns Only the stable tokens.
+ * @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 stableClasses(tokens) {
-  return tokens.filter(token => isStableClassToken(token));
+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);
 }
+
 /**
- * Whether two class lists describe "the same kind of element" for list
- * inference: same stable classes, generated tokens (which often differ
- * per-instance, e.g. a React `key`-derived class) ignored on both sides.
+ * 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 a - One element's classes.
- * @param b - Another element's classes.
- * @returns Whether their stable class sets are equal, order ignored.
+ * @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 sameClassSignature(a, b) {
-  const left = new Set(stableClasses(a));
-  const right = new Set(stableClasses(b));
-  if (left.size !== right.size) return false;
-  return [...left].every(token => right.has(token));
+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);
 }
 
 /**
- * Thrown when a pick or a list-inference walk crosses a declarative shadow
- * root (`<template shadowrootmode>`). v1 does not pierce shadow DOM: rather
- * than infer a selector that silently matches the wrong thing (or nothing,
- * once the page hydrates), the studio surfaces this and stops.
+ * Handles `document-tree`: the content pane's tree canvas for a JSON, YAML
+ * or XML document (`document-view`, studio plan §3.4, issue #94's 5a), off
+ * the same cached snapshot `take-snapshot`/`inspect-page` already use.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The tree.
+ * @throws Error when no workspace is open, `command.path` has no cached snapshot yet, or the snapshot's document is not JSON/YAML/XML (no parsed body at all in web mode; PDF/workbook/deck in api mode — see `documentTreeView`'s own doc comment).
  */
-class ShadowDomUnsupportedError extends Error {
-  path;
-  constructor(path) {
-    super(`"${path}" is inside a shadow root: shadow DOM is not supported for picking (v1)`);
-    this.path = path;
-    this.name = 'ShadowDomUnsupportedError';
-  }
+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);
 }
 
-/** Attributes ranked just under `id`: named explicitly, not "any `data-*`", because a generated `data-reactid` is no more stable than a generated class. */
-const STABLE_ATTRS = ['data-testid', 'data-id', 'itemprop'];
-const TIER_ORDER$1 = {
-  'id': 0,
-  'data-attr': 1,
-  'class': 2,
-  'structure': 3,
-  'position': 4
-};
 /**
- * Every selector candidate worth trying for the last node of `path`, ranked
- * best-first: `id` > stable `data-*`/`itemprop` attributes > stable class
- * tokens > ancestor structure (`parent > tag`) > position (`nth-of-type`) as
- * a last resort (issue #91's ranking, studio plan §3.2). Structure and
- * position candidates only look as far up as `path` itself goes — pass a
- * sub-path (e.g. from an item's root down) to keep a field's selector
- * relative to its item instead of absolute to the document.
+ * Finds and parses one input recipe of a workspace folder, and the output
+ * recipe it names.
  *
- * @param path - The node's ancestry, root (or scope root) first, itself last.
- * @param includePosition - `false` for an item selector: a position candidate would only ever match one of the items, which is never what an item selector should do.
- * @returns Candidates, best tier first; ties keep this function's own order.
+ * @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 candidatesFor(path, includePosition = true) {
-  const node = path.at(-1);
-  if (node === undefined) return [];
-  const candidates = [];
-  if (node.id !== undefined && isStableId(node.id)) candidates.push({
-    selector: `#${cssEscape(node.id)}`,
-    tier: 'id'
+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)
+  };
+}
+function kindOf(content) {
+  return content?.kind;
+}
+function idOf(content) {
+  return content?.id;
+}
+
+/**
+ * Runs one input recipe of a workspace folder as a sample: `debug: true` (so
+ * each `record:emit` carries its scope snapshot and mapping trace, and each
+ * `record:reject` its scope), an in-memory sink, and `budget` as the
+ * crawler's `sample` (`@opencraw/core`'s `CrawlOptions.sample`, #89). Every
+ * engine event becomes a trace line with the same `traceLine` formatter the
+ * cli's `--trace` uses; every emitted record reaches `callbacks.onRecord` as
+ * it happens, not only in the final result. Step events (`step:start`,
+ * `step:skip`, `step:retry`) are aggregated by path into `result.steps`, so
+ * `explain-why` (#92) can later say whether the step that bound a mapping's
+ * source id ran, was skipped, or retried — without a second run.
+ *
+ * @param folder - The workspace folder the recipe lives in.
+ * @param recipeId - The input recipe to run.
+ * @param budget - The sample budget; unset runs the recipe to completion (still capped by its own `limits`).
+ * @param callbacks - Where trace lines and records go as the run proceeds.
+ * @param browser - Browser launch settings for a web-mode recipe (an executable path override, headless…); the server-wide setting `studio-http.use-case.ts`'s `StudioServerOptions.browser` carries in, e.g. `OPENCRAW_CHROMIUM` in a sandbox with no full Playwright install.
+ * @returns A handle: `stop` closes the crawler cleanly, `result` resolves when the run ends.
+ * @throws RecipeValidationError, RecipeBindingError, Error when the recipe or its output cannot be loaded or bound.
+ */
+async function runSample(folder, recipeId, budget, callbacks, browser) {
+  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);
+      }
+    }
   });
-  for (const name of STABLE_ATTRS) {
-    const value = node.attrs[name];
-    if (value !== undefined && value.length > 0) candidates.push({
-      selector: `${node.tag}[${name}="${cssValue(value)}"]`,
-      tier: 'data-attr'
+  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;
   }
-  const classes = stableClasses(node.classes);
-  if (classes.length > 0) candidates.push({
-    selector: `${node.tag}.${classes.map(token => cssEscape(token)).join('.')}`,
-    tier: 'class'
-  });
-  candidates.push(...structureCandidates(path));
-  if (includePosition) candidates.push(...positionCandidates(path));
-  return sortByTier(candidates);
-}
-/** `ancestor > ... > tag`, growing from 2 to 4 levels (or to the top of `path`), each ancestor named by its own best simple form. */
-function structureCandidates(path) {
-  const node = path.at(-1);
-  if (node === undefined) return [];
-  const candidates = [];
-  const maxDepth = Math.min(path.length - 1, 3);
-  for (let depth = 1; depth <= maxDepth; depth++) {
-    const ancestor = path.at(-1 - depth);
-    if (ancestor === undefined) break;
-    const between = Array.from({
-      length: depth - 1
-    }, (_, index) => path.at(-depth + index)?.tag ?? '');
-    const parts = [simpleSelector(ancestor), ...between, node.tag];
-    candidates.push({
-      selector: parts.join(' > '),
-      tier: 'structure'
+  if (event.type === 'step:skip') {
+    steps.set(event.path, {
+      path: event.path,
+      stepType: event.stepType,
+      stepId: event.stepId,
+      outcome: 'skipped',
+      error: event.error
     });
   }
-  return candidates;
 }
-/** `parent > tag:nth-of-type(n)`, the position-only fallback; never `nth-child`, which counts every sibling tag, not just this element's own. */
-function positionCandidates(path) {
-  const node = path.at(-1);
-  if (node === undefined) return [];
-  const own = node.siblingCount > 1 ? `${node.tag}:nth-of-type(${node.index})` : node.tag;
-  const parent = path.at(-2);
-  if (parent === undefined) return [{
-    selector: own,
-    tier: 'position'
-  }];
-  return [{
-    selector: `${simpleSelector(parent)} > ${own}`,
-    tier: 'position'
-  }];
+async function runToResult(crawler, set, records, rejectedRecords, steps) {
+  try {
+    const report = await crawler.run(set);
+    const recipe = report.recipes[0];
+    return {
+      recipeId: recipe.recipeId,
+      emitted: recipe.emitted,
+      rejected: recipe.rejected,
+      duplicates: recipe.duplicates,
+      durationMs: recipe.durationMs,
+      error: recipe.error,
+      stoppedBy: recipe.stoppedBy,
+      records,
+      rejectedRecords,
+      // eslint-disable-next-line unicorn/prefer-iterator-to-array -- `.toArray()` needs a `lib` newer than this repo's `es2022` (tsconfig.base.json)
+      steps: [...steps.values()]
+    };
+  } finally {
+    await crawler.close();
+  }
 }
-/** A level's own selector fragment, no combinators: id, else stable classes, else the bare tag. */
-function simpleSelector(level) {
-  if (level.id !== undefined && isStableId(level.id)) return `#${cssEscape(level.id)}`;
-  const classes = stableClasses(level.classes);
-  return classes.length > 0 ? `${level.tag}.${classes.map(token => cssEscape(token)).join('.')}` : level.tag;
+
+/** @returns A fresh, empty cache. */
+function createLastRunCache() {
+  return {
+    entries: new Map()
+  };
 }
-function sortByTier(candidates) {
-  return [...candidates].sort((a, b) => TIER_ORDER$1[a.tier] - TIER_ORDER$1[b.tier]);
+/** 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
+  });
 }
-/** Escapes a CSS identifier segment (an id or a class token) well enough for the shapes real sites use; not a full CSS.escape polyfill. */
-function cssEscape(token) {
-  return token.replaceAll(/([^\w-])/gi, String.raw`\$1`);
+/** @returns The recipe's last completed sample run, or `undefined` when none has finished yet. */
+function lastRunOf(cache, recipeId) {
+  return cache.entries.get(recipeId);
 }
-/** Escapes a value inside `[name="…"]`. */
-function cssValue(value) {
-  return value.replaceAll(/(["\\])/g, String.raw`\$1`);
+
+/**
+ * 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 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.
+ */
+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 TIER_ORDER = {
-  'id': 0,
-  'data-attr': 1,
-  'class': 2,
-  'structure': 3,
-  'position': 4
-};
 /**
- * Verifies and orders selector candidates against real markup, by running
- * each one through the engine's own CSS matching (`@opencraw/core`'s
- * `countMatches`/`matchesOf`) rather than reimplementing it — issue #91's
- * "every candidate is verified" requirement.
+ * 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.
  *
- * Ordering: candidates that do not match `targetNodeId` (when given) sort
- * last; among the rest, best tier first, and within a tier the fewest
- * matches first (the most specific selector that still hits the target).
- * A candidate matching nothing is dropped entirely: it is not a real option.
+ * 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 html - The document to verify against (the snapshot, or the live page for the second, cross-check pass).
- * @param candidates - Unranked candidates, e.g. from `candidatesFor`.
- * @param targetNodeId - The `data-oc-node` id the pick landed on, when the document carries those stamps (the snapshot does; a live page fetched separately does not).
- * @returns Every candidate that matched at least one element, ranked best first.
+ * @param facts - What is known about the value.
+ * @returns One sentence, always ending in a period.
  */
-function rankCandidates(html, candidates, targetNodeId) {
-  const ranked = candidates.map(candidate => {
-    const matches = countMatches(html, candidate.selector);
-    const hitsTarget = targetNodeId === undefined ;
-    return {
-      ...candidate,
-      matches,
-      hitsTarget
-    };
-  });
-  return ranked.filter(candidate => candidate.matches > 0).sort((a, b) => Number(b.hitsTarget) - Number(a.hitsTarget) || TIER_ORDER[a.tier] - TIER_ORDER[b.tier] || a.matches - b.matches);
+function buildWhySentence(facts) {
+  return facts.outcome === 'rejected' ? rejectedSentence(facts) : missingSentence(facts);
 }
-/** The single best candidate, or `undefined` when none of them matched anything. */
-function bestCandidate(html, candidates, targetNodeId) {
-  return rankCandidates(html, candidates, targetNodeId)[0];
+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`;
+      }
+  }
 }
 
 /**
- * Infers "these two picks are the same field on two items of a list" from
- * two node paths, by walking up from both to the nearest ancestors that are
- * real siblings (the same parent) with the same tag and stable-class
- * signature — studio plan §3.2, issue #91. That ancestor is the item; the
- * remainder of each path is the field, relative to it.
- *
- * Because a `DomPath` is built root-down (`dom-path.model.ts`), two paths
- * from the same document are byte-for-byte identical up to their real
- * common ancestor and diverge exactly at its differing children — so the
- * *first* level where they differ is always the nearest-sibling test point;
- * there is no need to look further down. This also makes the "wrapper trap"
- * (an extra single-child element around each item) resolve itself: a
- * wrapper's own instances are never one another's siblings, only the
- * genuine repeating element is, so the walk naturally lands there instead of
- * on the wrapper (see the wrapper-trap fixture in this slice's tests).
+ * 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 pathA - The first click's path.
- * @param pathB - The second click's path.
- * @returns The item and field shapes (generalised) plus each pick's raw path, or `null` when the two picks are not on a coherent list (different branches entirely, the same node twice, or one path nested inside the other).
- * @throws ShadowDomUnsupportedError when either path crosses a declarative shadow root.
+ * @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.
  */
-function inferList(pathA, pathB) {
-  if (crossesShadowRoot(pathA)) throw new ShadowDomUnsupportedError(pathToString(pathA));
-  if (crossesShadowRoot(pathB)) throw new ShadowDomUnsupportedError(pathToString(pathB));
-  let divergedAt = -1;
-  const limit = Math.min(pathA.length, pathB.length);
-  for (let index = 0; index < limit; index++) {
-    if (!sameLevel(pathA[index], pathB[index])) {
-      divergedAt = index;
-      break;
-    }
-  }
-  // Identical paths, or one a strict prefix of the other (the same node picked twice, or one element nested inside the other): not a list.
-  if (divergedAt <= 0) return null;
-  const branchA = pathA[divergedAt];
-  const branchB = pathB[divergedAt];
-  if (branchA.tag !== branchB.tag || !sameClassSignature(branchA.classes, branchB.classes)) return null;
-  if (branchA.index === branchB.index) return null; // Same position: not two different items.
-  const ancestors = pathA.slice(0, divergedAt);
-  const fieldPathA = pathA.slice(divergedAt);
-  const fieldPathB = pathB.slice(divergedAt);
-  const fieldPath = mergeRelativePaths(fieldPathA, fieldPathB);
+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 {
-    itemPath: [...ancestors, fieldPath[0]],
-    fieldPath,
-    fieldPathA,
-    fieldPathB
+    sentence,
+    field: rejected.field,
+    recipeId,
+    outcome: 'rejected',
+    reason: rejected.reason,
+    policy,
+    stepPath: step?.path
   };
 }
-function sameLevel(a, b) {
-  return a.tag === b.tag && a.id === b.id && a.index === b.index && a.siblingCount === b.siblingCount && sameClassSignature(a.classes, b.classes);
+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
+  };
 }
 /**
- * Zips two item-relative paths (item first) level by level into one that
- * only keeps what both share: the tag (must already match, checked by the
- * caller for level 0), the intersection of stable classes, and attributes
- * present with the same value on both sides. Shorter than the other when
- * the two picks' local structure differs in depth (a real possibility once
- * a field is missing on one item; `list-inference.algorithm.test.ts`'s
- * shifted-field fixture is exactly this) — the merge just stops there,
- * which is fine: a field selector only needs to reach as deep as the
- * shallower of the two picks.
+ * 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 mergeRelativePaths(a, b) {
-  const length = Math.min(a.length, b.length);
-  const merged = [];
-  for (let index = 0; index < length; index++) {
-    const left = a[index];
-    const right = b[index];
-    if (left.tag !== right.tag) break;
-    merged.push(mergeLevel(left, right));
-  }
-  return merged.length > 0 ? merged : [a[0]];
+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;
 }
-function mergeLevel(a, b) {
-  const classes = stableClasses(a.classes).filter(token => b.classes.includes(token));
-  const attrs = {};
-  for (const [name, value] of Object.entries(a.attrs)) {
-    if (name !== 'class' && name !== 'id' && b.attrs[name] === value) attrs[name] = value;
+/** 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 {
-    tag: a.tag,
-    id: a.id !== undefined && a.id === b.id ? a.id : undefined,
-    classes,
-    attrs,
-    index: 1,
-    siblingCount: Math.max(a.siblingCount, b.siblingCount, 1)
-  };
+  return field;
 }
-function pathToString(path) {
-  return path.map(level => level.tag + (level.id === undefined ? '' : `#${level.id}`)).join(' > ');
+/** 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];
 }
-
 /**
- * Handles `infer-selector`: turns one or two picked nodes (their
- * `data-oc-node` ids, off the cached snapshot) into a verified selector —
- * one id for a `Read` card's field, two for the safe item+field list shape
- * `selector-inference`'s `inferList` builds by construction (issue #91,
- * studio plan §3.2). All the actual candidate/ranking/list-inference work
- * is `selector-inference`'s (pure); this handler only locates the clicked
- * nodes in the cached document and calls into it.
+ * 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).
  *
- * @param state - The server state.
- * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
- * @returns A field pick, a list pick, or `"unsupported"` with why.
- * @throws Error when no workspace is open, or `command.path` has no cached snapshot yet.
+ * @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 handleInferSelector(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 html = snapshot.html;
-  const paths = command.nodeIds.map(nodeId => pathToNode(html, nodeId));
-  if (paths.includes(undefined)) return {
-    kind: 'unsupported',
-    reason: 'one of the picked nodes is no longer in the snapshot; take a fresh snapshot and try again'
+function findStep(steps, boundId, stepSummaries) {
+  const found = search(steps, boundId, 'steps');
+  if (found === undefined) return {
+    path: '',
+    stepType: '',
+    outcome: 'not-found'
   };
-  const [pathA, pathB] = paths;
-  if (pathB === undefined) return {
-    kind: 'field',
-    field: fieldPick(html, pathA)
+  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
   };
-  try {
-    const result = inferList(pathA, pathB);
-    if (result === null) return {
-      kind: 'unsupported',
-      reason: 'these two picks do not belong to the same list: pick the same field on two similar items'
-    };
-    const item = bestCandidate(html, candidatesFor(result.itemPath, false));
-    if (item === undefined) return {
-      kind: 'unsupported',
-      reason: 'no selector matches every item of this list; try picking two items closer to each other in the markup'
-    };
-    const field = fieldPick(html, result.fieldPathA, result.fieldPath);
-    return {
-      kind: 'list',
-      item: {
-        selector: item.selector,
-        tier: item.tier,
-        matches: item.matches
-      },
-      field
-    };
-  } catch (error) {
-    if (error instanceof ShadowDomUnsupportedError) return {
-      kind: 'unsupported',
-      reason: error.message
+}
+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
     };
-    throw error;
+    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;
 }
-/** The best selector for one clicked node, `take` decided from the concrete clicked element; `rankSource` (a generalised path) is used for candidate generation when given, so a per-item-unique attribute of the one node picked cannot end up in the selector. */
-function fieldPick(html, clicked, rankSource = clicked) {
-  const leaf = clicked.at(-1);
-  const take = leaf === undefined ? 'text' : takeKindFor(leaf);
-  const best = bestCandidate(html, candidatesFor(rankSource));
-  if (best === undefined) throw new Error('no selector matches the picked node — this should not happen, since the node came from this same document');
+
+/**
+ * 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 {
-    selector: best.selector,
-    tier: best.tier,
-    take,
-    matches: best.matches
+    html
   };
 }
 
 /**
- * The outline model: an `InputRecipe`'s `steps` (and only `steps`; the rest
- * of the recipe passes through untouched, see `recipe-to-outline.mapper.ts`)
- * read as a tree of cards and brackets instead of raw JSON.
+ * 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.
  *
- * A **card** is one step that reads as a sentence (`sentence`, built by
- * `card-sentence.mapper.ts`). A **bracket** is a container step (`forEach`,
- * `paginate`, `if`) whose body is itself a list of cards/brackets: the
- * indentation the plan doc describes is this nesting, not a separate layout
- * concept. Both kinds carry `step`, the step's own raw JSON exactly as
- * parsed (every key, in its original order): `outline-to-recipe.mapper.ts`
- * rebuilds the recipe from it, substituting only the (possibly edited)
- * `children`/`elseChildren` for whatever `steps`/`else` value `step` itself
- * holds, so an edit to one field never disturbs another's position or a
- * step type this outline cannot make sense of.
+ * @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.
  */
-/** The step types the outline renders as a bracket: their body is nested steps, not a single value. */
-const BRACKET_STEP_TYPES = ['forEach', 'paginate', 'if'];
-function isBracket(node) {
-  return node.kind === 'bracket';
+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);
 }
-function isBracketStepType(type) {
-  return BRACKET_STEP_TYPES.includes(type);
+
+/**
+ * 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);
 }
 
-/** Step types the plan doc names as always going to a "custom" card: nothing here renders their meaning as a sentence. */
-const ALWAYS_CUSTOM = new Set(['evaluate', 'hook', 'captcha']);
+const GENERATED_ID = /^(?:react-|radix-|:r|ember|css-|mui-|headlessui-)/i;
 /**
- * Turns one step's raw JSON into its sentence parts (word/pill/code), the
- * way the plan doc's examples read: *Go to…*, *Read… from…*, *For each… in…
- * → one record*, and so on. Never throws: a step type this cannot read
- * becomes a short, honest fallback with `custom: true`, so the outline never
- * drops a step for looking unfamiliar.
+ * 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 step - A step's raw JSON (its `type` and whatever fields it has).
- * @returns The sentence parts, and whether they are a real reading or a fallback.
+ * @param $ - The parsed document.
+ * @param node - The element to describe.
+ * @returns The path, root first.
  */
-function cardSentence(step) {
-  const type = typeof step.type === 'string' ? step.type : undefined;
-  if (type === undefined || ALWAYS_CUSTOM.has(type)) return fallback(type);
-  const build = BUILDERS[type];
-  if (build === undefined) return fallback(type);
-  try {
-    return {
-      parts: build(step),
-      custom: false
-    };
-  } catch {
-    return fallback(type);
+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 fallback(type) {
+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 {
-    parts: [word(type ?? 'custom step')],
-    custom: true
+    tag,
+    id: attrs.id,
+    classes,
+    attrs,
+    index: Math.max(index, 1),
+    siblingCount: Math.max(siblings.length, 1)
   };
 }
-function word(text) {
-  return {
-    kind: 'word',
-    text
-  };
+function isElement(node) {
+  return node !== undefined && node.type === 'tag';
 }
-function pill(text) {
-  return {
-    kind: 'pill',
-    text
-  };
+/**
+ * Whether `id` looks handed by a framework (`react-`, a CSS-module or a
+ * `radix-`/`mui-` autogenerated one) rather than by the site's own markup —
+ * `class-token.policy.ts` has the equivalent check for class tokens, kept
+ * separate because ids and classes are ranked at different tiers.
+ */
+function isStableId(id) {
+  return id.length > 0 && !GENERATED_ID.test(id);
 }
-function code(text) {
-  return {
-    kind: 'code',
-    text
-  };
+/**
+ * Whether `path` failed to reach the real document root. `domPathOf` walks
+ * up through cheerio's own `.parent()`, which (matching real DOM semantics)
+ * never crosses from a `<template>`'s content into the light DOM outside
+ * it — a `<template shadowrootmode>` is exactly declarative shadow DOM, the
+ * only shadow-DOM shape that can show up in static, server-captured markup
+ * at all (imperative `attachShadow()` content never serialises into
+ * `page.content()`/a fetched response in the first place, so that case
+ * cannot reach this slice and needs no separate detection). A path whose
+ * first level is not `html` was cut short at exactly this kind of boundary:
+ * v1 does not pierce it, so callers report a clear "shadow DOM is not
+ * supported" error instead of building ancestor-based candidates over a
+ * chain that stops partway up.
+ */
+function crossesShadowRoot(path) {
+  return path.length === 0 || path[0].tag !== 'html';
 }
-/** A field that names an id: shown as a pill, `fallbackText` when it is absent. */
+/** Parses `html` and returns cheerio's API, for callers that need more than one path from the same document. */
+function parseDocument$1(html) {
+  return load(html);
+}
+/**
+ * The path to the element the snapshot stamped with `nodeId` (its
+ * `data-oc-node` attribute — `@opencraw/core`'s `NODE_ID_ATTRIBUTE`,
+ * `packages/studio/src/page-snapshot/rewrite-document.mapper.ts`). This is
+ * how a click in the content pane's iframe — which only ever needs to read
+ * that one attribute off the element the user clicked — turns into
+ * something `selector-inference`'s other algorithms can work with, without
+ * the browser-side picker script needing to know anything about ancestry,
+ * classes or candidate ranking itself.
+ *
+ * @param html - The snapshot document (already stamped with node ids).
+ * @param nodeId - The `data-oc-node` value to find.
+ * @returns The node's path, or `undefined` when no element carries that id.
+ */
+function pathToNode(html, nodeId) {
+  const $ = parseDocument$1(html);
+  const found = $(`[${NODE_ID_ATTRIBUTE}="${cssAttributeValue(nodeId)}"]`);
+  return found.length === 0 ? undefined : domPathOf($, found.first());
+}
+function cssAttributeValue(value) {
+  return value.replaceAll('\\', String.raw`\\`).replaceAll('"', String.raw`\"`);
+}
+
+/** Attributes worth reading instead of text, in preference order, when the clicked element has one. */
+const PREFERRED_ATTRS = {
+  a: ['href'],
+  img: ['src', 'alt']
+};
+/**
+ * What a `Read` card's `take` should be for the element a pick landed on
+ * (issue #91, studio plan §3.2): `attr:href` for an `<a>`, `attr:src` for an
+ * `<img>`, `attr:<name>` for the first `data-*` attribute otherwise, `json`
+ * for a `<script type="application/json">`, else the default, `text`.
+ *
+ * @param level - The clicked element's own level (the last entry of its `DomPath`).
+ * @returns The `take` value to put on the `extract` step.
+ */
+function takeKindFor(level) {
+  if (level.tag === 'script' && (level.attrs.type ?? '').toLowerCase() === 'application/json') return 'json';
+  const preferred = PREFERRED_ATTRS[level.tag];
+  if (preferred !== undefined) {
+    const attribute = preferred.find(name => level.attrs[name] !== undefined);
+    if (attribute !== undefined) return `attr:${attribute}`;
+  }
+  const dataAttribute = Object.keys(level.attrs).find(name => name.startsWith('data-') && name !== 'data-oc-node' && name !== 'data-oc-hidden');
+  if (dataAttribute !== undefined) return `attr:${dataAttribute}`;
+  return 'text';
+}
+
+/**
+ * Which class tokens are worth building a selector on. A hand-authored class
+ * (`product_pod`, `price_color`) survives a rebuild; a generated one
+ * (a content hash, a CSS-module suffix, a styled-components token) does not,
+ * so a candidate built on it looks fine on the snapshot it was picked from
+ * and breaks on the very next deploy. This is the "generated/hashed class
+ * names" tradeoff issue #91 calls out explicitly: the heuristics below are a
+ * reasoned judgement call, not a guarantee — see the doc comments on each
+ * pattern for what real-world tool it targets.
+ */
+const GENERATED_TOKEN_PATTERNS = [/** styled-components / emotion: `sc-bdVaJa`, `css-1x2y3z4` */
+/^(?:sc|css)-[a-z0-9]+$/i, /** CSS Modules, most bundlers' default hash suffix: `wrapper__3fA9k`, `Button-module_root__aB3dK` */
+/__[a-z0-9]{4,10}$/i, /** JSS / MUI: `jss123`, `MuiButton-root-145` */
+/^(?:jss|mui[a-z]*-)[a-z0-9-]*\d{2}$/i, /** A token that is only digits: not a class a human would type. */
+/^\d+$/, /** A bare hex hash: `a3f9c21`, `1a2b3c4d` (6+ hex chars, nothing else). */
+/^[0-9a-f]{6,}$/i, /** Tailwind/atomic-CSS-in-JS runtime classes some bundlers emit: `_1a2b3c` */
+/^_[0-9a-z]{5,}$/i];
+/**
+ * Whether a class token looks hand-authored and safe to build a selector on.
+ *
+ * @param token - One class, no surrounding whitespace.
+ * @returns `false` for anything matching a known generated-class shape.
+ */
+function isStableClassToken(token) {
+  return token.length > 0 && GENERATED_TOKEN_PATTERNS.every(pattern => !pattern.test(token));
+}
+/**
+ * The subset of `tokens` worth ranking a selector candidate on, order kept.
+ *
+ * @param tokens - An element's class list.
+ * @returns Only the stable tokens.
+ */
+function stableClasses(tokens) {
+  return tokens.filter(token => isStableClassToken(token));
+}
+/**
+ * Whether two class lists describe "the same kind of element" for list
+ * inference: same stable classes, generated tokens (which often differ
+ * per-instance, e.g. a React `key`-derived class) ignored on both sides.
+ *
+ * @param a - One element's classes.
+ * @param b - Another element's classes.
+ * @returns Whether their stable class sets are equal, order ignored.
+ */
+function sameClassSignature(a, b) {
+  const left = new Set(stableClasses(a));
+  const right = new Set(stableClasses(b));
+  if (left.size !== right.size) return false;
+  return [...left].every(token => right.has(token));
+}
+
+/**
+ * Thrown when a pick or a list-inference walk crosses a declarative shadow
+ * root (`<template shadowrootmode>`). v1 does not pierce shadow DOM: rather
+ * than infer a selector that silently matches the wrong thing (or nothing,
+ * once the page hydrates), the studio surfaces this and stops.
+ */
+class ShadowDomUnsupportedError extends Error {
+  path;
+  constructor(path) {
+    super(`"${path}" is inside a shadow root: shadow DOM is not supported for picking (v1)`);
+    this.path = path;
+    this.name = 'ShadowDomUnsupportedError';
+  }
+}
+
+/** Attributes ranked just under `id`: named explicitly, not "any `data-*`", because a generated `data-reactid` is no more stable than a generated class. */
+const STABLE_ATTRS = ['data-testid', 'data-id', 'itemprop'];
+const TIER_ORDER$1 = {
+  'id': 0,
+  'data-attr': 1,
+  'class': 2,
+  'structure': 3,
+  'position': 4
+};
+/**
+ * Every selector candidate worth trying for the last node of `path`, ranked
+ * best-first: `id` > stable `data-*`/`itemprop` attributes > stable class
+ * tokens > ancestor structure (`parent > tag`) > position (`nth-of-type`) as
+ * a last resort (issue #91's ranking, studio plan §3.2). Structure and
+ * position candidates only look as far up as `path` itself goes — pass a
+ * sub-path (e.g. from an item's root down) to keep a field's selector
+ * relative to its item instead of absolute to the document.
+ *
+ * @param path - The node's ancestry, root (or scope root) first, itself last.
+ * @param includePosition - `false` for an item selector: a position candidate would only ever match one of the items, which is never what an item selector should do.
+ * @returns Candidates, best tier first; ties keep this function's own order.
+ */
+function candidatesFor(path, includePosition = true) {
+  const node = path.at(-1);
+  if (node === undefined) return [];
+  const candidates = [];
+  if (node.id !== undefined && isStableId(node.id)) candidates.push({
+    selector: `#${cssEscape(node.id)}`,
+    tier: 'id'
+  });
+  for (const name of STABLE_ATTRS) {
+    const value = node.attrs[name];
+    if (value !== undefined && value.length > 0) candidates.push({
+      selector: `${node.tag}[${name}="${cssValue(value)}"]`,
+      tier: 'data-attr'
+    });
+  }
+  const classes = stableClasses(node.classes);
+  if (classes.length > 0) candidates.push({
+    selector: `${node.tag}.${classes.map(token => cssEscape(token)).join('.')}`,
+    tier: 'class'
+  });
+  candidates.push(...structureCandidates(path));
+  if (includePosition) candidates.push(...positionCandidates(path));
+  return sortByTier(candidates);
+}
+/** `ancestor > ... > tag`, growing from 2 to 4 levels (or to the top of `path`), each ancestor named by its own best simple form. */
+function structureCandidates(path) {
+  const node = path.at(-1);
+  if (node === undefined) return [];
+  const candidates = [];
+  const maxDepth = Math.min(path.length - 1, 3);
+  for (let depth = 1; depth <= maxDepth; depth++) {
+    const ancestor = path.at(-1 - depth);
+    if (ancestor === undefined) break;
+    const between = Array.from({
+      length: depth - 1
+    }, (_, index) => path.at(-depth + index)?.tag ?? '');
+    const parts = [simpleSelector(ancestor), ...between, node.tag];
+    candidates.push({
+      selector: parts.join(' > '),
+      tier: 'structure'
+    });
+  }
+  return candidates;
+}
+/** `parent > tag:nth-of-type(n)`, the position-only fallback; never `nth-child`, which counts every sibling tag, not just this element's own. */
+function positionCandidates(path) {
+  const node = path.at(-1);
+  if (node === undefined) return [];
+  const own = node.siblingCount > 1 ? `${node.tag}:nth-of-type(${node.index})` : node.tag;
+  const parent = path.at(-2);
+  if (parent === undefined) return [{
+    selector: own,
+    tier: 'position'
+  }];
+  return [{
+    selector: `${simpleSelector(parent)} > ${own}`,
+    tier: 'position'
+  }];
+}
+/** A level's own selector fragment, no combinators: id, else stable classes, else the bare tag. */
+function simpleSelector(level) {
+  if (level.id !== undefined && isStableId(level.id)) return `#${cssEscape(level.id)}`;
+  const classes = stableClasses(level.classes);
+  return classes.length > 0 ? `${level.tag}.${classes.map(token => cssEscape(token)).join('.')}` : level.tag;
+}
+function sortByTier(candidates) {
+  return [...candidates].sort((a, b) => TIER_ORDER$1[a.tier] - TIER_ORDER$1[b.tier]);
+}
+/** Escapes a CSS identifier segment (an id or a class token) well enough for the shapes real sites use; not a full CSS.escape polyfill. */
+function cssEscape(token) {
+  return token.replaceAll(/([^\w-])/gi, String.raw`\$1`);
+}
+/** Escapes a value inside `[name="…"]`. */
+function cssValue(value) {
+  return value.replaceAll(/(["\\])/g, String.raw`\$1`);
+}
+
+const TIER_ORDER = {
+  'id': 0,
+  'data-attr': 1,
+  'class': 2,
+  'structure': 3,
+  'position': 4
+};
+/**
+ * Verifies and orders selector candidates against real markup, by running
+ * each one through the engine's own CSS matching (`@opencraw/core`'s
+ * `countMatches`/`matchesOf`) rather than reimplementing it — issue #91's
+ * "every candidate is verified" requirement.
+ *
+ * Ordering: candidates that do not match `targetNodeId` (when given) sort
+ * last; among the rest, best tier first, and within a tier the fewest
+ * matches first (the most specific selector that still hits the target).
+ * A candidate matching nothing is dropped entirely: it is not a real option.
+ *
+ * @param html - The document to verify against (the snapshot, or the live page for the second, cross-check pass).
+ * @param candidates - Unranked candidates, e.g. from `candidatesFor`.
+ * @param targetNodeId - The `data-oc-node` id the pick landed on, when the document carries those stamps (the snapshot does; a live page fetched separately does not).
+ * @returns Every candidate that matched at least one element, ranked best first.
+ */
+function rankCandidates(html, candidates, targetNodeId) {
+  const ranked = candidates.map(candidate => {
+    const matches = countMatches(html, candidate.selector);
+    const hitsTarget = targetNodeId === undefined || matches === 0 ? targetNodeId === undefined : matchesOf(html, candidate.selector).includes(targetNodeId);
+    return {
+      ...candidate,
+      matches,
+      hitsTarget
+    };
+  });
+  return ranked.filter(candidate => candidate.matches > 0).sort((a, b) => Number(b.hitsTarget) - Number(a.hitsTarget) || TIER_ORDER[a.tier] - TIER_ORDER[b.tier] || a.matches - b.matches);
+}
+/** The single best candidate, or `undefined` when none of them matched anything. */
+function bestCandidate(html, candidates, targetNodeId) {
+  return rankCandidates(html, candidates, targetNodeId)[0];
+}
+
+/**
+ * Infers "these two picks are the same field on two items of a list" from
+ * two node paths, by walking up from both to the nearest ancestors that are
+ * real siblings (the same parent) with the same tag and stable-class
+ * signature — studio plan §3.2, issue #91. That ancestor is the item; the
+ * remainder of each path is the field, relative to it.
+ *
+ * Because a `DomPath` is built root-down (`dom-path.model.ts`), two paths
+ * from the same document are byte-for-byte identical up to their real
+ * common ancestor and diverge exactly at its differing children — so the
+ * *first* level where they differ is always the nearest-sibling test point;
+ * there is no need to look further down. This also makes the "wrapper trap"
+ * (an extra single-child element around each item) resolve itself: a
+ * wrapper's own instances are never one another's siblings, only the
+ * genuine repeating element is, so the walk naturally lands there instead of
+ * on the wrapper (see the wrapper-trap fixture in this slice's tests).
+ *
+ * @param pathA - The first click's path.
+ * @param pathB - The second click's path.
+ * @returns The item and field shapes (generalised) plus each pick's raw path, or `null` when the two picks are not on a coherent list (different branches entirely, the same node twice, or one path nested inside the other).
+ * @throws ShadowDomUnsupportedError when either path crosses a declarative shadow root.
+ */
+function inferList(pathA, pathB) {
+  if (crossesShadowRoot(pathA)) throw new ShadowDomUnsupportedError(pathToString(pathA));
+  if (crossesShadowRoot(pathB)) throw new ShadowDomUnsupportedError(pathToString(pathB));
+  let divergedAt = -1;
+  const limit = Math.min(pathA.length, pathB.length);
+  for (let index = 0; index < limit; index++) {
+    if (!sameLevel(pathA[index], pathB[index])) {
+      divergedAt = index;
+      break;
+    }
+  }
+  // Identical paths, or one a strict prefix of the other (the same node picked twice, or one element nested inside the other): not a list.
+  if (divergedAt <= 0) return null;
+  const branchA = pathA[divergedAt];
+  const branchB = pathB[divergedAt];
+  if (branchA.tag !== branchB.tag || !sameClassSignature(branchA.classes, branchB.classes)) return null;
+  if (branchA.index === branchB.index) return null; // Same position: not two different items.
+  const ancestors = pathA.slice(0, divergedAt);
+  const fieldPathA = pathA.slice(divergedAt);
+  const fieldPathB = pathB.slice(divergedAt);
+  const fieldPath = mergeRelativePaths(fieldPathA, fieldPathB);
+  return {
+    itemPath: [...ancestors, fieldPath[0]],
+    fieldPath,
+    fieldPathA,
+    fieldPathB
+  };
+}
+function sameLevel(a, b) {
+  return a.tag === b.tag && a.id === b.id && a.index === b.index && a.siblingCount === b.siblingCount && sameClassSignature(a.classes, b.classes);
+}
+/**
+ * Zips two item-relative paths (item first) level by level into one that
+ * only keeps what both share: the tag (must already match, checked by the
+ * caller for level 0), the intersection of stable classes, and attributes
+ * present with the same value on both sides. Shorter than the other when
+ * the two picks' local structure differs in depth (a real possibility once
+ * a field is missing on one item; `list-inference.algorithm.test.ts`'s
+ * shifted-field fixture is exactly this) — the merge just stops there,
+ * which is fine: a field selector only needs to reach as deep as the
+ * shallower of the two picks.
+ */
+function mergeRelativePaths(a, b) {
+  const length = Math.min(a.length, b.length);
+  const merged = [];
+  for (let index = 0; index < length; index++) {
+    const left = a[index];
+    const right = b[index];
+    if (left.tag !== right.tag) break;
+    merged.push(mergeLevel(left, right));
+  }
+  return merged.length > 0 ? merged : [a[0]];
+}
+function mergeLevel(a, b) {
+  const classes = stableClasses(a.classes).filter(token => b.classes.includes(token));
+  const attrs = {};
+  for (const [name, value] of Object.entries(a.attrs)) {
+    if (name !== 'class' && name !== 'id' && b.attrs[name] === value) attrs[name] = value;
+  }
+  return {
+    tag: a.tag,
+    id: a.id !== undefined && a.id === b.id ? a.id : undefined,
+    classes,
+    attrs,
+    index: 1,
+    siblingCount: Math.max(a.siblingCount, b.siblingCount, 1)
+  };
+}
+function pathToString(path) {
+  return path.map(level => level.tag + (level.id === undefined ? '' : `#${level.id}`)).join(' > ');
+}
+
+/**
+ * Handles `infer-selector`: turns one or two picked nodes (their
+ * `data-oc-node` ids, off the cached snapshot) into a verified selector —
+ * one id for a `Read` card's field, two for the safe item+field list shape
+ * `selector-inference`'s `inferList` builds by construction (issue #91,
+ * studio plan §3.2). All the actual candidate/ranking/list-inference work
+ * is `selector-inference`'s (pure); this handler only locates the clicked
+ * nodes in the cached document and calls into it.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns A field pick, a list pick, or `"unsupported"` with why.
+ * @throws Error when no workspace is open, or `command.path` has no cached snapshot yet.
+ */
+function handleInferSelector(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 html = snapshot.html;
+  const paths = command.nodeIds.map(nodeId => pathToNode(html, nodeId));
+  if (paths.includes(undefined)) return {
+    kind: 'unsupported',
+    reason: 'one of the picked nodes is no longer in the snapshot; take a fresh snapshot and try again'
+  };
+  const [pathA, pathB] = paths;
+  if (pathB === undefined) return {
+    kind: 'field',
+    field: fieldPick(html, pathA)
+  };
+  try {
+    const result = inferList(pathA, pathB);
+    if (result === null) return {
+      kind: 'unsupported',
+      reason: 'these two picks do not belong to the same list: pick the same field on two similar items'
+    };
+    const item = bestCandidate(html, candidatesFor(result.itemPath, false));
+    if (item === undefined) return {
+      kind: 'unsupported',
+      reason: 'no selector matches every item of this list; try picking two items closer to each other in the markup'
+    };
+    const field = fieldPick(html, result.fieldPathA, result.fieldPath);
+    return {
+      kind: 'list',
+      item: {
+        selector: item.selector,
+        tier: item.tier,
+        matches: item.matches
+      },
+      field
+    };
+  } catch (error) {
+    if (error instanceof ShadowDomUnsupportedError) return {
+      kind: 'unsupported',
+      reason: error.message
+    };
+    throw error;
+  }
+}
+/** The best selector for one clicked node, `take` decided from the concrete clicked element; `rankSource` (a generalised path) is used for candidate generation when given, so a per-item-unique attribute of the one node picked cannot end up in the selector. */
+function fieldPick(html, clicked, rankSource = clicked) {
+  const leaf = clicked.at(-1);
+  const take = leaf === undefined ? 'text' : takeKindFor(leaf);
+  const best = bestCandidate(html, candidatesFor(rankSource));
+  if (best === undefined) throw new Error('no selector matches the picked node — this should not happen, since the node came from this same document');
+  return {
+    selector: best.selector,
+    tier: best.tier,
+    take,
+    matches: best.matches
+  };
+}
+
+/** 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`)
+ * read as a tree of cards and brackets instead of raw JSON.
+ *
+ * A **card** is one step that reads as a sentence (`sentence`, built by
+ * `card-sentence.mapper.ts`). A **bracket** is a container step (`forEach`,
+ * `paginate`, `if`) whose body is itself a list of cards/brackets: the
+ * indentation the plan doc describes is this nesting, not a separate layout
+ * concept. Both kinds carry `step`, the step's own raw JSON exactly as
+ * parsed (every key, in its original order): `outline-to-recipe.mapper.ts`
+ * rebuilds the recipe from it, substituting only the (possibly edited)
+ * `children`/`elseChildren` for whatever `steps`/`else` value `step` itself
+ * holds, so an edit to one field never disturbs another's position or a
+ * step type this outline cannot make sense of.
+ */
+/** The step types the outline renders as a bracket: their body is nested steps, not a single value. */
+const BRACKET_STEP_TYPES = ['forEach', 'paginate', 'if'];
+function isBracket(node) {
+  return node.kind === 'bracket';
+}
+function isBracketStepType(type) {
+  return BRACKET_STEP_TYPES.includes(type);
+}
+
+/** Step types the plan doc names as always going to a "custom" card: nothing here renders their meaning as a sentence. */
+const ALWAYS_CUSTOM = new Set(['evaluate', 'hook', 'captcha']);
+/**
+ * Turns one step's raw JSON into its sentence parts (word/pill/code), the
+ * way the plan doc's examples read: *Go to…*, *Read… from…*, *For each… in…
+ * → one record*, and so on. Never throws: a step type this cannot read
+ * becomes a short, honest fallback with `custom: true`, so the outline never
+ * drops a step for looking unfamiliar.
+ *
+ * @param step - A step's raw JSON (its `type` and whatever fields it has).
+ * @returns The sentence parts, and whether they are a real reading or a fallback.
+ */
+function cardSentence(step) {
+  const type = typeof step.type === 'string' ? step.type : undefined;
+  if (type === undefined || ALWAYS_CUSTOM.has(type)) return fallback(type);
+  const build = BUILDERS[type];
+  if (build === undefined) return fallback(type);
+  try {
+    return {
+      parts: build(step),
+      custom: false
+    };
+  } catch {
+    return fallback(type);
+  }
+}
+function fallback(type) {
+  return {
+    parts: [word(type ?? 'custom step')],
+    custom: true
+  };
+}
+function word(text) {
+  return {
+    kind: 'word',
+    text
+  };
+}
+function pill(text) {
+  return {
+    kind: 'pill',
+    text
+  };
+}
+function code(text) {
+  return {
+    kind: 'code',
+    text
+  };
+}
+/** A field that names an id: shown as a pill, `fallbackText` when it is absent. */
 function pillField(step, key, fallbackText) {
   const value = step[key];
   return pill(typeof value === 'string' && value.length > 0 ? value : fallbackText);
 }
-/** A field shown as a literal (a selector, a template, a value): stringified when it is not already a string. */
-function codeField(step, key, fallbackText = '') {
-  const value = step[key];
-  if (typeof value === 'string') return code(value);
-  if (value === undefined) return code(fallbackText);
-  return code(safeJson(value));
+/** A field shown as a literal (a selector, a template, a value): stringified when it is not already a string. */
+function codeField(step, key, fallbackText = '') {
+  const value = step[key];
+  if (typeof value === 'string') return code(value);
+  if (value === undefined) return code(fallbackText);
+  return code(safeJson(value));
+}
+function safeJson(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+/** `selector` or `target`, whichever the step gives (`step.contract.ts`'s `TargetFields`: exactly one is present). */
+function targetField(step) {
+  if (typeof step.target === 'string') return code(step.target);
+  return codeField(step, 'selector');
+}
+const BUILDERS = {
+  goto: step => [word('Go to'), codeField(step, 'url')],
+  click: step => [word('Click'), targetField(step)],
+  fill: step => [word('Fill'), targetField(step), word('with'), codeField(step, 'value')],
+  press: step => [word('Press'), codeField(step, 'key'), word('in'), targetField(step)],
+  select: step => [word('Choose'), selectChoice(step), word('in'), targetField(step)],
+  scroll: step => [word('Scroll to'), codeField(step, 'to')],
+  wait: step => [word('Wait for'), waitFor(step)],
+  screenshot: step => [word('Screenshot'), codeField(step, 'path')],
+  request: step => [word('Request'), code(`${typeof step.method === 'string' ? step.method : 'GET'} `), codeField(step, 'url')],
+  extract: step => [word('Read'), pillField(step, 'id', '(unnamed)'), word('from'), pillField(step, 'from', 'page'), word('←'), codeField(step, 'selector')],
+  set: step => [word('Set'), pillField(step, 'id', '(unnamed)'), word('to'), codeField(step, 'value')],
+  collect: step => [word('Collect'), codeField(step, 'value'), word('into'), pillField(step, 'into', '(unnamed)')],
+  forEach: step => forEachSentence(step),
+  paginate: step => paginateSentence(step),
+  if: step => [word('If'), codeField(step, 'test')],
+  emit: step => emitSentence(step)
+};
+function selectChoice(step) {
+  if (typeof step.value === 'string') return code(step.value);
+  if (typeof step.label === 'string') return code(step.label);
+  if (typeof step.index === 'number') return code(String(step.index));
+  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 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 safeJson(value) {
+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 {
-    return JSON.stringify(value) ?? String(value);
-  } catch {
-    return String(value);
+    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');
+}
+/** @returns Fresh state for a new server instance: no workspace open, no run, no recording, no sockets, an empty snapshot cache, no last runs, Playwright's own default browser, the default recorder profile directory. */
+function createStudioState() {
+  return {
+    sockets: new Set(),
+    snapshots: createSnapshotCache(),
+    lastRuns: createLastRunCache(),
+    recorderProfileDir: defaultRecorderProfileDir()
+  };
+}
+/**
+ * Sends one event to every connected client. A socket that errors while
+ * sending (gone away without a clean close yet reaching us) is dropped
+ * rather than left to fail every later broadcast too.
+ *
+ * @param state - The server state holding the connected sockets.
+ * @param event - The event to send.
+ */
+function broadcast(state, event) {
+  const text = JSON.stringify(event);
+  for (const socket of state.sockets) {
+    try {
+      socket.send(text);
+    } catch {
+      state.sockets.delete(socket);
+    }
   }
 }
-/** `selector` or `target`, whichever the step gives (`step.contract.ts`'s `TargetFields`: exactly one is present). */
-function targetField(step) {
-  if (typeof step.target === 'string') return code(step.target);
-  return codeField(step, 'selector');
-}
-const BUILDERS = {
-  goto: step => [word('Go to'), codeField(step, 'url')],
-  click: step => [word('Click'), targetField(step)],
-  fill: step => [word('Fill'), targetField(step), word('with'), codeField(step, 'value')],
-  press: step => [word('Press'), codeField(step, 'key'), word('in'), targetField(step)],
-  select: step => [word('Choose'), selectChoice(step), word('in'), targetField(step)],
-  scroll: step => [word('Scroll to'), codeField(step, 'to')],
-  wait: step => [word('Wait for'), waitFor(step)],
-  screenshot: step => [word('Screenshot'), codeField(step, 'path')],
-  request: step => [word('Request'), code(`${typeof step.method === 'string' ? step.method : 'GET'} `), codeField(step, 'url')],
-  extract: step => [word('Read'), pillField(step, 'id', '(unnamed)'), word('from'), pillField(step, 'from', 'page'), word('←'), codeField(step, 'selector')],
-  set: step => [word('Set'), pillField(step, 'id', '(unnamed)'), word('to'), codeField(step, 'value')],
-  collect: step => [word('Collect'), codeField(step, 'value'), word('into'), pillField(step, 'into', '(unnamed)')],
-  forEach: step => forEachSentence(step),
-  paginate: step => paginateSentence(step),
-  if: step => [word('If'), codeField(step, 'test')],
-  emit: step => emitSentence(step)
-};
-function selectChoice(step) {
-  if (typeof step.value === 'string') return code(step.value);
-  if (typeof step.label === 'string') return code(step.label);
-  if (typeof step.index === 'number') return code(String(step.index));
-  if (Array.isArray(step.values)) return code(step.values.join(', '));
-  return code('');
+
+/**
+ * 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;
 }
-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('');
+
+/**
+ * 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 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.
+ */
+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 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;
+
+/**
+ * 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 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));
+
+/**
+ * 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;
+      }
   }
-  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')];
+
+/** 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'];
 /**
- * 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.
+ * 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 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.
+ * `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 recipeToOutline(content) {
-  const recipe = isRecord(content) ? content : {};
-  const steps = Array.isArray(recipe.steps) ? recipe.steps : [];
-  return {
-    recipe,
-    steps: stepsToNodes(steps, '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 stepsToNodes(steps, pathPrefix) {
-  return steps.map((step, index) => stepToNode(step, `${pathPrefix}.${index}`));
+
+/** 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 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
-    })
-  };
+/**
+ * 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;
 }
-function isRecord(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * 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)}}}`;
 }
 
 /**
- * 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.
+ * 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 outline - An outline, from `recipe-to-outline.mapper.ts` or edited by the UI.
- * @returns The recipe's plain JSON, ready for `save-recipe`.
+ * @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 outlineToRecipe(outline) {
-  if (!('steps' in outline.recipe) && outline.steps.length === 0) return {
-    ...outline.recipe
-  };
+function insertWaitStep(context, nextSelector) {
+  if (nextSelector === undefined || !context.navigated && !context.xhr) return undefined;
   return {
-    ...outline.recipe,
-    steps: nodesToSteps(outline.steps)
+    type: 'wait',
+    selector: nextSelector
   };
 }
-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;
-}
 
+/** 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 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.
+ * 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).
  *
- * @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.
+ * 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 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, 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()
+    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
+  };
 }
 
 /**
@@ -1616,13 +4263,25 @@ async function handleRunSample(state, command) {
         type: 'record',
         recipeId: command.recipeId,
         key: record.key,
-        data: record.data
+        data: record.data,
+        scope: record.scope,
+        mapping: record.mapping
+      });
+    },
+    onRejected: rejected => {
+      broadcast(state, {
+        type: 'record-rejected',
+        recipeId: command.recipeId,
+        field: rejected.field,
+        reason: rejected.reason,
+        scope: rejected.scope
       });
     }
   }, state.browser);
   state.activeRun = handle;
   void handle.result.then(result => {
     if (state.activeRun === handle) state.activeRun = undefined;
+    recordLastRun(state.lastRuns, command.recipeId, result);
     broadcast(state, {
       type: 'run-finished',
       recipeId: result.recipeId,
@@ -1738,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
@@ -1753,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
+    })
+  };
 }
 
 /**
@@ -1925,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);
   });
@@ -1946,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));
@@ -1966,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 {
@@ -2033,6 +4756,54 @@ function dispatch(command, state) {
       {
         return Promise.resolve(handleInferSelector(state, command));
       }
+    case 'explain-why':
+      {
+        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) {
@@ -2089,5 +4860,5 @@ async function main(argv) {
   process.on('SIGTERM', shutdown);
 }
 
-export { fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, inferSelectorCommandSchema, inferSelectorViewSchema, loadRecipePair, main, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startStudioServer, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, 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