@opencraw/studio 0.0.5 → 0.0.7

package/dist/index.esm.js

@@ -3,7 +3,8 @@ import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { randomBytes, createHash } from 'node:crypto';
-import { BrowserClient, HttpClient, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, RecipeBindingError, RecipeValidationError } from '@opencraw/core';
+import { readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, resolveMissingPolicy, BrowserClient, HttpClient, NODE_ID_ATTRIBUTE, countMatches, RecipeBindingError, RecipeValidationError } from '@opencraw/core';
+import { load } from 'cheerio';
 import { writeFile } from 'node:fs/promises';
 import { existsSync, createReadStream } from 'node:fs';
 
@@ -82,7 +83,126 @@ const saveOutlineCommandSchema = z.object({
   path: z.string().min(1),
   outline: outlineViewSchema
 });
-const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema]);
+/**
+ * Captures the snapshot the content pane shows for a step (`page-snapshot`'s
+ * `take-snapshot.use-case.ts`), caching it by recipe and step path so
+ * switching the selected step does not always re-run the recipe.
+ */
+const takeSnapshotCommandSchema = z.object({
+  type: z.literal('take-snapshot'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1)
+});
+/**
+ * Verifies a candidate selector against the cached snapshot and, when
+ * reachable, the live page — the studio's own selection (`@opencraw/core`'s
+ * `countMatches`), never the browser's or a guess (issue #91).
+ */
+const verifySelectorCommandSchema = z.object({
+  type: z.literal('verify-selector'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1),
+  selector: z.string().min(1)
+});
+/**
+ * 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).
+ */
+const pickedNodeIdSchema = z.string().min(1);
+const onePickedNodeSchema = z.tuple([pickedNodeIdSchema]);
+const twoPickedNodesSchema = z.tuple([pickedNodeIdSchema, pickedNodeIdSchema]);
+const inferSelectorCommandSchema = z.object({
+  type: z.literal('infer-selector'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1),
+  nodeIds: z.union([onePickedNodeSchema, twoPickedNodesSchema])
+});
+/** 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
+});
+const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, explainWhyCommandSchema]);
+
+/** What `take-snapshot` answers with: the rewritten document ready for the content pane's sandboxed iframe (studio plan §3.1, issue #91). */
+const snapshotViewSchema = z.object({
+  html: z.string(),
+  nodeCount: z.number(),
+  baseUrl: z.string()
+});
+
+/**
+ * What `verify-selector` answers with: the match count against the snapshot
+ * and, when the live page could be reached, against it too (issue #91's
+ * "flag a selector that matches the snapshot but not the live page").
+ * `liveChecked` is `false` when the live page could not be fetched (offline,
+ * blocked by `allowedHosts`, a transient error) — the card shows the
+ * snapshot count alone rather than a misleading "0 on the live page".
+ */
+const verifySelectorViewSchema = z.object({
+  selector: z.string(),
+  snapshotMatches: z.number(),
+  liveChecked: z.boolean(),
+  liveMatches: z.number().optional(),
+  liveError: z.string().optional()
+});
+
+/** The candidate tiers `selector-inference`'s ranking works through, best first — see `selector-candidates.algorithm.ts`. */
+const candidateTierSchema = z.enum(['id', 'data-attr', 'class', 'structure', 'position']);
+/** One clicked node's field: the best selector found for it, verified against the snapshot. */
+const fieldPickSchema = z.object({
+  selector: z.string(),
+  tier: candidateTierSchema,
+  take: z.string(),
+  matches: z.number()
+});
+/** A list's item shape: the best selector that matches every item, verified against the snapshot. */
+const itemPickSchema = z.object({
+  selector: z.string(),
+  tier: candidateTierSchema,
+  matches: z.number()
+});
+/**
+ * What `infer-selector` answers with (issue #91, studio plan §3.2):
+ * `"field"` for one clicked node — a `Read` card's shape; `"list"` for two
+ * similar nodes — the safe `extract`(items)+`forEach`(field) shape, item and
+ * field each verified separately; `"unsupported"` when the two picks are not
+ * a coherent list (different branches, the same node twice, or shadow DOM),
+ * with a message the card can show as-is.
+ */
+const inferSelectorViewSchema = z.discriminatedUnion('kind', [z.object({
+  kind: z.literal('field'),
+  field: fieldPickSchema
+}), z.object({
+  kind: z.literal('list'),
+  item: itemPickSchema,
+  field: fieldPickSchema
+}), z.object({
+  kind: z.literal('unsupported'),
+  reason: z.string()
+})]);
 
 /** Why a sample run stopped before finishing on its own; mirrors `@opencraw/core`'s `RecipeReport.stoppedBy`. */
 const stoppedBySchema = z.enum(['sample-maxRecords', 'sample-maxPages', 'sample-maxMs']);
@@ -91,12 +211,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({
@@ -113,7 +253,7 @@ const runFinishedEventSchema = z.object({
 const workspaceChangedEventSchema = z.object({
   type: z.literal('workspace-changed')
 });
-const studioEventSchema = z.discriminatedUnion('type', [traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema]);
+const studioEventSchema = z.discriminatedUnion('type', [traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema]);
 
 /** One problem found on a recipe file, with the JSON path it lives at. */
 const recipeIssueSchema = z.object({
@@ -161,6 +301,20 @@ 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()
+});
+
 /** 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. */
@@ -203,61 +357,6 @@ function cookieToken(header) {
   return undefined;
 }
 
-/**
- * Fetches an input recipe's start page as the engine would see it: a fresh
- * Playwright page in web mode, core's HTTP client in api mode. Returns plain
- * text: the page's HTML, or a readable rendering of a non-HTML api response.
- * No rewriting, no script stripping, no node ids yet: that is phase 2's
- * `page-snapshot` proper (studio plan, #91). Provisional for phase 0 in two
- * ways, both worth knowing before relying on it: it opens a bare page
- * without running the recipe's own steps first, so a start point behind a
- * `session.bootstrap` login shows what an anonymous visitor sees; and it
- * launches a fresh browser or HTTP context per call, one page then closes
- * it, rather than reusing whatever the last sample run had open.
- *
- * @param input - The input recipe; only `mode` and the first `start` point are used.
- * @param browser - Browser launch settings for web mode (an executable path override, headless…).
- * @returns The page's content as plain text.
- * @throws Error when the recipe has no start point.
- */
-async function fetchStartPage(input, browser) {
-  const point = input.start[0];
-  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
-  return input.mode === 'web' ? fetchWeb(point.url, browser) : fetchApi(point.url);
-}
-async function fetchWeb(url, browser) {
-  const client = await BrowserClient.launch(browser);
-  try {
-    const session = await client.newSession();
-    try {
-      await session.page.goto(url);
-      return await session.page.content();
-    } finally {
-      await session.close();
-    }
-  } finally {
-    await client.close();
-  }
-}
-async function fetchApi(url) {
-  const client = await HttpClient.open({});
-  try {
-    const response = await client.send({
-      url
-    });
-    return textOf(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(body) {
-  if (body.kind === 'html') return body.html;
-  if (body.kind === 'text') return body.text;
-  if (body.kind === 'json') return JSON.stringify(body.data, null, 2);
-  return `[${body.kind} document: the content pane shows HTML and JSON responses for now]`;
-}
-
 /**
  * Finds and parses one input recipe of a workspace folder, and the output
  * recipe it names.
@@ -289,46 +388,109 @@ function idOf(content) {
 
 /**
  * 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.
+ * 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) {
+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);
-      if (event.type === 'record:emit') callbacks.onRecord({
-        key: event.key,
-        data: event.data
-      });
+      trackStep(steps, event);
+      if (event.type === 'record:emit') {
+        const record = {
+          key: event.key,
+          data: event.data,
+          scope: event.scope,
+          mapping: event.mapping
+        };
+        records.push(record);
+        callbacks.onRecord(record);
+      } else if (event.type === 'record:reject') {
+        const rejected = {
+          field: event.field,
+          reason: event.reason,
+          url: event.url,
+          scope: event.scope
+        };
+        rejectedRecords.push(rejected);
+        callbacks.onRejected?.(rejected);
+      }
     }
   });
-  const result = runToResult(crawler, set, sink);
+  const result = runToResult(crawler, set, records, rejectedRecords, steps);
   return {
     stop: () => crawler.close(),
     result
   };
 }
-async function runToResult(crawler, set, sink) {
+/**
+ * Folds one `step:*` event into `steps`, by path: `skip` always wins over an
+ * earlier `ran`/`retried` outcome for the same path (a step skipped even
+ * once is worth flagging), `retry` wins over a plain `ran`, and a path seen
+ * only as `finish`/`start` (no skip, no retry) settles on `ran`. A `forEach`
+ * runs its body once per item, so the same path folds repeatedly; this is
+ * deliberately a summary across the whole sample, not a per-record trace.
+ */
+function trackStep(steps, event) {
+  if (event.type === 'step:start') {
+    if (!steps.has(event.path)) steps.set(event.path, {
+      path: event.path,
+      stepType: event.stepType,
+      stepId: event.stepId,
+      outcome: 'ran'
+    });
+    return;
+  }
+  if (event.type === 'step:retry') {
+    steps.set(event.path, {
+      path: event.path,
+      stepType: event.stepType,
+      stepId: event.stepId,
+      outcome: 'retried',
+      error: event.error
+    });
+    return;
+  }
+  if (event.type === 'step:skip') {
+    steps.set(event.path, {
+      path: event.path,
+      stepType: event.stepType,
+      stepId: event.stepId,
+      outcome: 'skipped',
+      error: event.error
+    });
+  }
+}
+async function runToResult(crawler, set, records, rejectedRecords, steps) {
   try {
     const report = await crawler.run(set);
     const recipe = report.recipes[0];
@@ -340,16 +502,572 @@ async function runToResult(crawler, set, sink) {
       durationMs: recipe.durationMs,
       error: recipe.error,
       stoppedBy: recipe.stoppedBy,
-      records: sink.records.map(record => ({
-        key: record.key,
-        data: record.data
-      }))
+      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();
   }
 }
 
+/** @returns A fresh, empty cache. */
+function createLastRunCache() {
+  return {
+    entries: new Map()
+  };
+}
+/** Records a finished sample run, replacing whatever this recipe's cache entry held before. */
+function recordLastRun(cache, recipeId, result) {
+  cache.entries.set(recipeId, {
+    recipeId,
+    result
+  });
+}
+/** @returns The recipe's last completed sample run, or `undefined` when none has finished yet. */
+function lastRunOf(cache, recipeId) {
+  return cache.entries.get(recipeId);
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Builds the Why? tab's sentence (studio plan §4.4, issue #92) from the
+ * facts `why.use-case.ts` gathers: the value the mapping read (and each
+ * transform's effect on it), the step that bound its source id and whether
+ * it ran, was skipped, or bound nothing this recipe knows of, the
+ * missing-value policy that applied, and a hint about what was actually
+ * there instead.
+ *
+ * This is the scope-snapshot-only half of the design: phase 2's per-item DOM
+ * snapshot (the CSS-selector "the item has `.price_new`" hint the issue's
+ * example shows) is not wired in here — `sample-run` keeps the mapping's
+ * scope snapshot (bound ids and their values), not a per-`forEach`-item DOM
+ * capture, and building that link is a bigger integration than this phase's
+ * budget covers (see this package's `page-snapshot` slice, which captures a
+ * step's page for the content pane, not per-iteration). `hint`, when given,
+ * is instead built from the scope snapshot itself (`item-hint.algorithm.ts`).
+ *
+ * @param facts - What is known about the value.
+ * @returns One sentence, always ending in a period.
+ */
+function buildWhySentence(facts) {
+  return facts.outcome === 'rejected' ? rejectedSentence(facts) : missingSentence(facts);
+}
+function rejectedSentence(facts) {
+  const parts = [`"${facts.field}" was rejected: ${facts.reason ?? 'the engine gave no reason'}`];
+  if (facts.policy !== undefined) parts.push(` (policy: ${facts.policy})`);
+  return `${parts.join('')}.`;
+}
+function missingSentence(facts) {
+  const parts = [`"${facts.field}" is missing`, stepClause(facts)];
+  if (facts.policy !== undefined) parts.push(`; left ${facts.policy === 'null' ? 'null' : facts.policy} by policy`);
+  if (facts.hint !== undefined) parts.push(`; ${facts.hint}`);
+  return `${parts.join('')}.`;
+}
+function stepClause(facts) {
+  const boundId = facts.boundId ?? facts.field;
+  const step = facts.step;
+  if (step === undefined) return ': no step in this recipe binds its source';
+  const label = step.stepId === undefined ? describeStepType(step.stepType) : `${describeStepType(step.stepType)} "${step.stepId}"`;
+  if (step.outcome === 'not-found') return `: no step in this recipe binds "${boundId}"`;
+  if (step.outcome === 'skipped') return `: ${label} (${step.path}), which binds "${boundId}", was skipped${step.error === undefined ? '' : ` (${step.error})`}`;
+  if (step.outcome === 'retried') return `: ${label} (${step.path}), which binds "${boundId}", had to retry${step.error === undefined ? '' : ` (${step.error})`} and still found nothing for "${facts.field}"`;
+  return `: ${label} (${step.path}) ran and bound "${boundId}", but "${facts.field}" reads ${sourceOf(facts)} from it, which was empty`;
+}
+function sourceOf(facts) {
+  return facts.trace?.from === undefined ? 'a path' : JSON.stringify(facts.trace.from);
+}
+/** A step's type read as a short phrase, matching the Steps outline's own vocabulary (studio plan §4.1: "Go to…", "Read… from…"). */
+function describeStepType(stepType) {
+  switch (stepType) {
+    case 'extract':
+      {
+        return 'the Read step';
+      }
+    case 'request':
+      {
+        return 'the request step';
+      }
+    case 'forEach':
+      {
+        return 'the loop';
+      }
+    case 'paginate':
+      {
+        return 'the pagination';
+      }
+    case 'goto':
+      {
+        return 'the Go to step';
+      }
+    default:
+      {
+        return `the ${stepType} step`;
+      }
+  }
+}
+
+/**
+ * Explains one missing or rejected value from a recipe's last sample run
+ * (issue #92's Why? tab, studio plan §4.4): the mapping trace and scope
+ * snapshot `run-sample` kept, the recipe's own rule and field for the
+ * missing-value policy, and the step that bound the value's source id — did
+ * it run, was it skipped, or does no step in this recipe bind it at all.
+ *
+ * @param folder - The workspace folder (to re-read the recipe pair: the last
+ *   run only kept the run's own data, not the recipe text, and a save may
+ *   have happened since).
+ * @param cache - The server's last-run cache (`sample-run`'s `LastRunCache`).
+ * @param loadPair - Loads the input/output recipe pair; injected so this
+ *   stays testable without a real workspace folder (`sample-run`'s
+ *   `loadRecipePair` in production).
+ * @param target - What was clicked.
+ * @returns The explanation.
+ * @throws Error when no sample run has finished for this recipe yet, or the target does not name a real record/field.
+ */
+async function explainWhy(folder, cache, loadPair, target) {
+  const entry = lastRunOf(cache, target.recipeId);
+  if (entry === undefined) throw new Error(`no finished sample run for "${target.recipeId}" yet — run a sample first`);
+  const {
+    input,
+    output
+  } = await loadPair(folder, target.recipeId);
+  return target.kind === 'rejected' ? explainRejected(target.recipeId, input, output, entry.result.rejectedRecords, entry.result.steps, target.rejectedIndex) : explainMissing(target.recipeId, input, output, entry.result.records, entry.result.steps, target.recordIndex, target.field);
+}
+function explainRejected(recipeId, input, output, rejectedRecords, steps, index) {
+  const rejected = rejectedRecords[index];
+  if (rejected === undefined) throw new Error(`no rejected record at index ${index}`);
+  const rule = ruleFor(input.mapping, rejected.field);
+  const field = fieldFor(output.fields, rejected.field);
+  const policy = field === undefined ? undefined : resolveMissingPolicy(field, output, rule);
+  const boundId = boundIdOf(rule);
+  const step = boundId === undefined ? undefined : findStep(input.steps, boundId, steps);
+  const hint = hintFor(rejected.scope, boundId);
+  const sentence = buildWhySentence({
+    field: rejected.field,
+    outcome: 'rejected',
+    reason: rejected.reason,
+    policy,
+    boundId,
+    step,
+    hint
+  });
+  return {
+    sentence,
+    field: rejected.field,
+    recipeId,
+    outcome: 'rejected',
+    reason: rejected.reason,
+    policy,
+    stepPath: step?.path
+  };
+}
+function explainMissing(recipeId, input, output, records, steps, index, field) {
+  const record = records[index];
+  if (record === undefined) throw new Error(`no record at index ${index}`);
+  const trace = record.mapping?.[field];
+  const rule = ruleFor(input.mapping, field);
+  const fieldSpec = fieldFor(output.fields, field);
+  const policy = fieldSpec === undefined ? undefined : resolveMissingPolicy(fieldSpec, output, rule);
+  const boundId = boundIdOf(rule);
+  const step = boundId === undefined ? undefined : findStep(input.steps, boundId, steps);
+  const hint = hintFor(record.scope, boundId);
+  const sentence = buildWhySentence({
+    field,
+    outcome: 'missing',
+    policy,
+    trace,
+    boundId,
+    step,
+    hint
+  });
+  return {
+    sentence,
+    field,
+    recipeId,
+    outcome: 'missing',
+    policy,
+    stepPath: step?.path
+  };
+}
+/**
+ * The rule bound to one output field path: a direct match on `input.mapping`
+ * (its keys are themselves dotted target paths — `stock.inStock`, `tax` —
+ * `map-record.use-case.ts` writes each with `setPath`), or, for a path
+ * inside an `each` list's items (`variants[1].size`), the item's own rule
+ * inside the list rule's `fields`. Only one level of `each` nesting is
+ * resolved; a field inside a nested `each` (an `each` of `each`) is not —
+ * out of this phase's scope.
+ */
+function ruleFor(mapping, path) {
+  const direct = mapping[path];
+  if (direct !== undefined) return direct;
+  const match = /^([^[]+)\[\d+\]\.(.+)$/.exec(path);
+  if (match === null) return undefined;
+  const parent = mapping[match[1]];
+  return parent !== undefined && 'each' in parent ? parent.fields[match[2]] : undefined;
+}
+/** The output field spec at one dotted path (`stock.inStock`, `variants[1].size`), walking `object`/`array` members the same way `map-record.use-case.ts` builds them. */
+function fieldFor(fields, path) {
+  let current = fields;
+  let field;
+  for (const token of path.split('.')) {
+    const match = /^([^[]+)(\[\d+\])?$/.exec(token);
+    if (match === null || current === undefined) return undefined;
+    field = current[match[1]];
+    if (field === undefined) return undefined;
+    current = match[2] === undefined ? field.fields : field.items?.fields;
+  }
+  return field;
+}
+/** The leading id a `from` rule reads (`item` of `item.description`, `price` of `price`); `undefined` for an `each` rule, a `.` (self), or a rule this run found nothing to say about. */
+function boundIdOf(rule) {
+  if (rule === undefined || !('from' in rule)) return undefined;
+  const first = Array.isArray(rule.from) ? rule.from[0] : rule.from;
+  const match = /^([A-Z_][\w-]*)/i.exec(first);
+  return match?.[1];
+}
+/**
+ * Finds the step of the recipe whose `id` or `as` (a `forEach`'s loop
+ * variable) is `boundId`, walking into `forEach`/`paginate`/`if` bodies the
+ * same way `scope-outline`'s outline does, and reports how it went over the
+ * whole sample run from `stepSummaries` (`sample-run`'s per-path summary).
+ *
+ * @returns `undefined` only when nothing in `steps` looks like a step at all; a `boundId` that names no real step still gets a fact, with `outcome: 'not-found'`.
+ */
+function findStep(steps, boundId, stepSummaries) {
+  const found = search(steps, boundId, 'steps');
+  if (found === undefined) return {
+    path: '',
+    stepType: '',
+    outcome: 'not-found'
+  };
+  const summary = stepSummaries.find(entry => entry.path === found.path);
+  return {
+    path: found.path,
+    stepType: found.step.type ?? 'unknown',
+    stepId: found.step.id,
+    outcome: summary?.outcome ?? 'ran',
+    error: summary?.error
+  };
+}
+function search(steps, boundId, prefix) {
+  for (const [index, step] of steps.entries()) {
+    const path = `${prefix}.${index}`;
+    if (step.id === boundId || step.as === boundId) return {
+      path,
+      step
+    };
+    if (step.steps !== undefined) {
+      const nested = search(step.steps, boundId, `${path}.steps`);
+      if (nested !== undefined) return nested;
+    }
+    if (step.else !== undefined) {
+      const nested = search(step.else, boundId, `${path}.else`);
+      if (nested !== undefined) return nested;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Handles `explain-why` (issue #92's Why? tab): builds the sentence for a
+ * missing or rejected value from the recipe's last sample run, kept in
+ * `state.lastRuns` by `handleRunSample`.
+ *
+ * @param state - The server state: `folder` must already be set (`open-workspace` first).
+ * @param command - The command.
+ * @returns The explanation.
+ * @throws Error when no workspace is open, no sample run has finished for the target's recipe, or the target does not name a real record/field.
+ */
+async function handleExplainWhy(state, command) {
+  if (state.folder === undefined) throw new Error('open a workspace first');
+  return explainWhy(state.folder, state.lastRuns, loadRecipePair, command.target);
+}
+
+/**
+ * Fetches an input recipe's start page as the engine would see it: a fresh
+ * Playwright page in web mode, core's HTTP client in api mode. Returns plain
+ * text: the page's HTML, or a readable rendering of a non-HTML api response.
+ * No rewriting, no script stripping, no node ids yet: that is phase 2's
+ * `page-snapshot` proper (studio plan, #91). Provisional for phase 0 in two
+ * ways, both worth knowing before relying on it: it opens a bare page
+ * without running the recipe's own steps first, so a start point behind a
+ * `session.bootstrap` login shows what an anonymous visitor sees; and it
+ * launches a fresh browser or HTTP context per call, one page then closes
+ * it, rather than reusing whatever the last sample run had open.
+ *
+ * @param input - The input recipe; only `mode` and the first `start` point are used.
+ * @param browser - Browser launch settings for web mode (an executable path override, headless…).
+ * @returns The page's content as plain text.
+ * @throws Error when the recipe has no start point.
+ */
+async function fetchStartPage(input, browser) {
+  const point = input.start[0];
+  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
+  return input.mode === 'web' ? fetchWeb(point.url, browser) : fetchApi(point.url);
+}
+async function fetchWeb(url, browser) {
+  const client = await BrowserClient.launch(browser);
+  try {
+    const session = await client.newSession();
+    try {
+      await session.page.goto(url);
+      return await session.page.content();
+    } finally {
+      await session.close();
+    }
+  } finally {
+    await client.close();
+  }
+}
+async function fetchApi(url) {
+  const client = await HttpClient.open({});
+  try {
+    const response = await client.send({
+      url
+    });
+    return textOf$1(response.body);
+  } finally {
+    await client.dispose();
+  }
+}
+/** Every body kind the studio can show as text today; others get a placeholder rather than a crash. */
+function textOf$1(body) {
+  if (body.kind === 'html') return body.html;
+  if (body.kind === 'text') return body.text;
+  if (body.kind === 'json') return JSON.stringify(body.data, null, 2);
+  return `[${body.kind} document: the content pane shows HTML and JSON responses for now]`;
+}
+
+/** The attribute `hiddenMarksScript` stamps on an element hidden on the live page. */
+const HIDDEN_ATTRIBUTE = 'data-oc-hidden';
+/**
+ * The in-page script `take-snapshot.use-case.ts` runs with `page.evaluate`
+ * *before* `page.content()`, so a `display: none`/`visibility: hidden`/
+ * zero-size element carries `data-oc-hidden="1"` into the captured markup
+ * (studio plan §3.1, issue #91) — the only way to know an element was
+ * hidden on the live page, since a static parse of the HTML afterwards has
+ * no computed style to ask.
+ *
+ * Kept as a plain string, not a TypeScript function passed to
+ * `page.evaluate`, because it references `window`/`document` as globals: `AGENTS.md`'s
+ * "things that bit before" calls out that in-page functions must not do
+ * that (the repo's `isolated-functions` lint rule), and every existing
+ * `page.evaluate` call with real DOM logic in this codebase (see
+ * `packages/core/src/captcha/resolve-captcha.use-case.ts`) already uses
+ * this same string-template shape.
+ *
+ * @param attribute - The attribute to stamp; defaults to `HIDDEN_ATTRIBUTE` (parameterised for tests and for a future caller that wants a different name).
+ * @returns A self-invoking script, ready for `page.evaluate(hiddenMarksScript())`.
+ */
+function hiddenMarksScript(attribute = HIDDEN_ATTRIBUTE) {
+  return `(() => {
+    var attribute = ${JSON.stringify(attribute)}
+    var elements = document.querySelectorAll('*')
+    for (var i = 0; i < elements.length; i++) {
+      var element = elements[i]
+      var style = window.getComputedStyle(element)
+      var rect = element.getBoundingClientRect()
+      var hidden = style.display === 'none' || style.visibility === 'hidden' || (rect.width === 0 && rect.height === 0)
+      if (hidden) element.setAttribute(attribute, '1')
+    }
+  })()`;
+}
+
+/** Attributes that carry a URL and are rewritten to absolute; `srcset` is handled separately (it carries several). */
+const URL_ATTRIBUTES = ['href', 'src', 'action', 'poster'];
+/** Schemes left untouched: they are not a location `new URL(value, base)` should resolve, or already carry their own meaning. */
+const SKIP_SCHEME = /^(?:javascript|mailto|tel|data|about):/i;
+/**
+ * Rewrites captured HTML into what the content pane's sandboxed iframe shows
+ * (studio plan §3.1, issue #91): every URL made absolute against `baseUrl`,
+ * a `<base>` injected, every `<script>` removed, forms disabled (`onsubmit`
+ * stripped, fields made read-only), `<meta http-equiv="refresh">` stripped
+ * (it would otherwise navigate the sandboxed frame on its own), and every
+ * element given a stable `data-oc-node` id, in document order, for the
+ * picker overlay and `selector-inference` to address specific nodes by.
+ *
+ * Purely a markup transform: it does not know whether an element is hidden
+ * on the live page (`display: none`, `visibility: hidden`, zero size) — in
+ * web mode that is `hidden-marks.algorithm.ts`'s job, run against the live
+ * page *before* this function ever sees the markup, so a `data-oc-hidden`
+ * attribute it wrote just survives serialisation untouched here.
+ *
+ * @param html - The captured document (`page.content()` in web mode, the fetched body in api mode).
+ * @param baseUrl - The page's own URL, for resolving relative links and as the `<base>`.
+ * @returns The rewritten document and how many elements it stamped.
+ */
+function rewriteDocument(html, baseUrl) {
+  const $ = load(html);
+  if ($('head').length === 0) $('html').prepend('<head></head>');
+  const head = $('head').first();
+  head.find('base').remove();
+  head.prepend(`<base href="${escapeAttribute(baseUrl)}">`);
+  $('meta').each((_index, element) => {
+    if (($(element).attr('http-equiv') ?? '').toLowerCase() === 'refresh') $(element).remove();
+  });
+  $('script').remove();
+  $('form').removeAttr('onsubmit');
+  $('input, textarea').attr('readonly', 'readonly');
+  $('select, button, input[type="submit"], input[type="button"]').attr('disabled', 'disabled');
+  $('*').each((_index, element) => {
+    const node = $(element);
+    for (const attribute of URL_ATTRIBUTES) {
+      const value = node.attr(attribute);
+      if (value !== undefined) node.attr(attribute, resolveUrl(value, baseUrl) ?? value);
+    }
+    const srcset = node.attr('srcset');
+    if (srcset !== undefined) node.attr('srcset', rewriteSrcset(srcset, baseUrl));
+  });
+  let nodeCount = 0;
+  $('*').each((_index, element) => {
+    $(element).attr(NODE_ID_ATTRIBUTE, `n${nodeCount}`);
+    nodeCount += 1;
+  });
+  return {
+    html: $.html(),
+    nodeCount
+  };
+}
+/** Resolves one URL against `baseUrl`; a scheme that is not a location (`javascript:`, `data:`…), or a value `new URL` cannot parse, is left as it was. */
+function resolveUrl(value, baseUrl) {
+  const trimmed = value.trim();
+  if (trimmed === '' || SKIP_SCHEME.test(trimmed)) return undefined;
+  try {
+    return new URL(trimmed, baseUrl).href;
+  } catch {
+    return undefined;
+  }
+}
+/** `srcset`'s own micro-syntax: comma-separated `url descriptor?` pairs. Malformed entries are passed through unresolved rather than dropped. */
+function rewriteSrcset(value, baseUrl) {
+  return value.split(',').map(candidate => {
+    const trimmed = candidate.trim();
+    const spaceAt = trimmed.indexOf(' ');
+    const url = spaceAt === -1 ? trimmed : trimmed.slice(0, spaceAt);
+    const descriptor = spaceAt === -1 ? '' : trimmed.slice(spaceAt);
+    return `${resolveUrl(url, baseUrl) ?? url}${descriptor}`;
+  }).join(', ');
+}
+function escapeAttribute(value) {
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
+}
+
+/**
+ * Captures the snapshot the content pane shows (studio plan §3.1, issue
+ * #91): runs the recipe up to `stepPath`, serialises the document, marks
+ * hidden elements in web mode, and hands it to `rewrite-document.mapper.ts`
+ * for display.
+ *
+ * `stepPath` is accepted (and cached against, by `snapshot.store.ts`) for
+ * the API the UI needs — one snapshot per selected step — but v1 only
+ * actually *captures* `"start"`: the first `start` point, before any step
+ * of the recipe has run, the same reach `fetch-start-page.use-case.ts` (phase
+ * 0) already had. Snapshotting mid-recipe (after an arbitrary later step)
+ * needs a "stop the crawl after step X and hand back the live page/document"
+ * hook in `crawl-execution` that does not exist yet; building one was out of
+ * this phase's budget (see this phase's final report for the tradeoff this
+ * was weighed against). Any other `stepPath` throws, clearly, rather than
+ * silently returning the start page under a misleading label.
+ *
+ * @param input - The input recipe; only `mode` and the first `start` point are used.
+ * @param stepPath - The step to snapshot after, e.g. `"start"` or `"steps.2"` (`scope-outline`'s path format).
+ * @param browser - Browser launch settings for web mode.
+ * @returns The rewritten snapshot.
+ * @throws Error when the recipe has no start point, or `stepPath` is not `"start"`.
+ */
+async function takeSnapshot(input, stepPath, browser) {
+  if (stepPath !== 'start') throw new Error(`takeSnapshot: "${stepPath}" is not supported yet — only "start" (the first start point, before any step runs) is; see this function's doc comment`);
+  const point = input.start[0];
+  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
+  return input.mode === 'web' ? snapshotWeb(point.url, browser) : snapshotApi(point.url);
+}
+async function snapshotWeb(url, browser) {
+  const client = await BrowserClient.launch(browser);
+  try {
+    const session = await client.newSession();
+    try {
+      await session.page.goto(url);
+      await session.page.evaluate(hiddenMarksScript(HIDDEN_ATTRIBUTE));
+      const html = await session.page.content();
+      const baseUrl = session.page.url();
+      const rewritten = rewriteDocument(html, baseUrl);
+      return {
+        ...rewritten,
+        baseUrl
+      };
+    } finally {
+      await session.close();
+    }
+  } finally {
+    await client.close();
+  }
+}
+async function snapshotApi(url) {
+  const client = await HttpClient.open({});
+  try {
+    const response = await client.send({
+      url
+    });
+    const rewritten = rewriteDocument(textOf(response.body), url);
+    return {
+      ...rewritten,
+      baseUrl: url
+    };
+  } 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) {
+  if (body.kind === 'html') return body.html;
+  if (body.kind === 'text') return body.text;
+  if (body.kind === 'json') return `<pre>${JSON.stringify(body.data, null, 2)}</pre>`;
+  return `<p>[${body.kind} document: the content pane shows HTML and JSON responses for now]</p>`;
+}
+
+/** @returns An empty cache, for a freshly opened workspace. */
+function createSnapshotCache() {
+  return {
+    entries: new Map()
+  };
+}
+/** @returns The cached snapshot for `recipeId`/`path`, or `undefined` when none was taken yet. */
+function cachedSnapshot(cache, recipeId, path) {
+  return cache.entries.get(keyOf(recipeId, path));
+}
+/** Records a freshly taken snapshot, replacing whatever was cached for the same recipe and step path. */
+function putSnapshot(cache, recipeId, path, snapshot) {
+  cache.entries.set(keyOf(recipeId, path), snapshot);
+}
+function keyOf(recipeId, path) {
+  return `${recipeId}:${path}`;
+}
+
 /**
  * Handles `fetch-start-page`: loads the named input recipe from the current
  * workspace and fetches its start point (see `page-snapshot`'s own caveats:
@@ -365,12 +1083,504 @@ async function handleFetchStartPage(state, command) {
   const {
     input
   } = await loadRecipePair(state.folder, command.recipeId);
-  const html = await fetchStartPage(input);
+  const html = await fetchStartPage(input, state.browser);
   return {
     html
   };
 }
 
+const GENERATED_ID = /^(?:react-|radix-|:r|ember|css-|mui-|headlessui-)/i;
+/**
+ * The path from the document root to `node`, one level per ancestor. Two
+ * elements that share an ancestor produce identical levels up to that
+ * ancestor and diverge exactly where their parents stop being the same node
+ * — `list-inference.algorithm.ts` leans on that to find the nearest pair of
+ * siblings two picks belong to, without ever touching cheerio again.
+ *
+ * @param $ - The parsed document.
+ * @param node - The element to describe.
+ * @returns The path, root first.
+ */
+function domPathOf($, node) {
+  const chain = [];
+  let current = node;
+  while (current !== undefined && current.length > 0 && isElement(current.get(0))) {
+    chain.unshift(current);
+    const parent = current.parent();
+    current = parent.length > 0 ? parent : undefined;
+  }
+  return chain.map(element => levelOf($, element));
+}
+function levelOf($, element) {
+  const node = element.get(0);
+  const tag = node.tagName.toLowerCase();
+  const attrs = {};
+  const entries = Object.entries(node.attribs ?? {});
+  for (const [name, value] of entries) attrs[name] = value;
+  const classes = (attrs.class ?? '').split(/\s+/).filter(token => token.length > 0);
+  const siblings = element.parent().length > 0 ? element.parent().children(tag) : $.root().children(tag);
+  const index = siblings.toArray().indexOf(node) + 1;
+  return {
+    tag,
+    id: attrs.id,
+    classes,
+    attrs,
+    index: Math.max(index, 1),
+    siblingCount: Math.max(siblings.length, 1)
+  };
+}
+function isElement(node) {
+  return node !== undefined && node.type === 'tag';
+}
+/**
+ * Whether `id` looks handed by a framework (`react-`, a CSS-module or a
+ * `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);
+}
+/**
+ * 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';
+}
+/** 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 ;
+    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
+  };
+}
+
 /**
  * The outline model: an `InputRecipe`'s `steps` (and only `steps`; the rest
  * of the recipe passes through untouched, see `recipe-to-outline.mapper.ts`)
@@ -752,10 +1962,12 @@ async function saveRecipe(path, recipe) {
   await writeFile(path, `${JSON.stringify(recipe, null, 2)}\n`, 'utf8');
 }
 
-/** @returns Fresh state for a new server instance: no workspace open, no run, no sockets. */
+/** @returns Fresh state for a new server instance: no workspace open, no run, no sockets, an empty snapshot cache, no last runs, Playwright's own default browser. */
 function createStudioState() {
   return {
-    sockets: new Set()
+    sockets: new Set(),
+    snapshots: createSnapshotCache(),
+    lastRuns: createLastRunCache()
   };
 }
 /**
@@ -821,13 +2033,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,
@@ -943,6 +2167,76 @@ function serveStatic(root, pathname, response) {
   createReadStream(file).pipe(response);
 }
 
+/**
+ * Handles `take-snapshot`: loads the named input recipe, captures its
+ * snapshot at `command.path` (only `"start"` is captured for now — see
+ * `page-snapshot`'s `take-snapshot.use-case.ts`), and caches it so a later
+ * `verify-selector`/`infer-selector` against the same recipe and path, or
+ * the UI reselecting the same step, does not recapture it.
+ *
+ * @param state - The server state: `folder` must already be set.
+ * @param command - The command.
+ * @returns The rewritten snapshot.
+ * @throws Error when no workspace is open, or the recipe cannot be found or loaded.
+ */
+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;
+  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;
+}
+
+/**
+ * Handles `verify-selector`: runs a candidate through the engine's own
+ * selection (`@opencraw/core`'s `countMatches`) against the cached
+ * snapshot, and, best-effort, against the live page too — issue #91's "flag
+ * a selector that matches the snapshot but not the live page". The live
+ * page is fetched raw (`page-snapshot`'s `fetchStartPage`, the same reach
+ * `take-snapshot` has: only `"start"` today), not through the rewritten
+ * snapshot, so its match count is the site's own, not the studio's.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The match counts.
+ * @throws Error when no workspace is open, the recipe cannot be found, or `command.path` has no cached snapshot yet.
+ */
+async function handleVerifySelector(state, command) {
+  if (state.folder === undefined) throw new Error('open a workspace first');
+  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 snapshotMatches = countMatches(snapshot.html, command.selector);
+  if (command.path !== 'start') return {
+    selector: command.selector,
+    snapshotMatches,
+    liveChecked: false,
+    liveError: 'only the start page can be checked against the live site for now'
+  };
+  try {
+    const {
+      input
+    } = await loadRecipePair(state.folder, command.recipeId);
+    const live = await fetchStartPage(input, state.browser);
+    return {
+      selector: command.selector,
+      snapshotMatches,
+      liveChecked: true,
+      liveMatches: countMatches(live, command.selector)
+    };
+  } catch (error) {
+    return {
+      selector: command.selector,
+      snapshotMatches,
+      liveChecked: false,
+      liveError: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
 /** RFC 6455's fixed handshake suffix. */
 const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
 /**
@@ -1059,6 +2353,7 @@ async function startStudioServer(options = {}) {
   const uiRoot = options.uiRoot ?? defaultUiRoot();
   const state = createStudioState();
   if (options.initialFolder !== undefined) state.folder = options.initialFolder;
+  state.browser = options.browser;
   const server = createServer((request, response) => {
     void handleRequest(request, response, token, state, uiRoot);
   });
@@ -1155,6 +2450,22 @@ function dispatch(command, state) {
       {
         return handleSaveOutline(state, command);
       }
+    case 'take-snapshot':
+      {
+        return handleTakeSnapshot(state, command);
+      }
+    case 'verify-selector':
+      {
+        return handleVerifySelector(state, command);
+      }
+    case 'infer-selector':
+      {
+        return Promise.resolve(handleInferSelector(state, command));
+      }
+    case 'explain-why':
+      {
+        return handleExplainWhy(state, command);
+      }
   }
 }
 function respondJson(response, status, body) {
@@ -1211,5 +2522,5 @@ async function main(argv) {
   process.on('SIGTERM', shutdown);
 }
 
-export { fetchStartPage, fetchStartPageCommandSchema, loadRecipePair, main, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, startPageViewSchema, startStudioServer, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, traceLineEventSchema, workspaceChangedEventSchema, workspaceViewSchema };
+export { explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, inferSelectorCommandSchema, inferSelectorViewSchema, loadRecipePair, main, missingWhyTargetSchema, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, recordRejectedEventSchema, rejectedWhyTargetSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startStudioServer, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, whyTargetSchema, whyViewSchema, workspaceChangedEventSchema, workspaceViewSchema };
 //# sourceMappingURL=index.esm.js.map