@opencraw/studio 0.0.6 → 0.0.7

package/dist/index.esm.js

@@ -3,7 +3,7 @@ import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 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 { 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';
@@ -119,7 +119,32 @@ 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]);
+/** 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({
@@ -186,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({
@@ -208,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({
@@ -256,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. */
@@ -298,6 +357,457 @@ function cookieToken(header) {
   return undefined;
 }
 
+/**
+ * Finds and parses one input recipe of a workspace folder, and the output
+ * recipe it names.
+ *
+ * @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.
+ */
+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);
+      }
+    }
+  });
+  const result = runToResult(crawler, set, records, rejectedRecords, steps);
+  return {
+    stop: () => crawler.close(),
+    result
+  };
+}
+/**
+ * Folds one `step:*` event into `steps`, by path: `skip` always wins over an
+ * earlier `ran`/`retried` outcome for the same path (a step skipped even
+ * once is worth flagging), `retry` wins over a plain `ran`, and a path seen
+ * only as `finish`/`start` (no skip, no retry) settles on `ran`. A `forEach`
+ * runs its body once per item, so the same path folds repeatedly; this is
+ * deliberately a summary across the whole sample, not a per-record trace.
+ */
+function trackStep(steps, event) {
+  if (event.type === 'step:start') {
+    if (!steps.has(event.path)) steps.set(event.path, {
+      path: event.path,
+      stepType: event.stepType,
+      stepId: event.stepId,
+      outcome: 'ran'
+    });
+    return;
+  }
+  if (event.type === 'step:retry') {
+    steps.set(event.path, {
+      path: event.path,
+      stepType: event.stepType,
+      stepId: event.stepId,
+      outcome: 'retried',
+      error: event.error
+    });
+    return;
+  }
+  if (event.type === 'step:skip') {
+    steps.set(event.path, {
+      path: event.path,
+      stepType: event.stepType,
+      stepId: event.stepId,
+      outcome: 'skipped',
+      error: event.error
+    });
+  }
+}
+async function 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();
+  }
+}
+
+/** @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
@@ -558,100 +1068,6 @@ function keyOf(recipeId, path) {
   return `${recipeId}:${path}`;
 }
 
-/**
- * Finds and parses one input recipe of a workspace folder, and the output
- * recipe it names.
- *
- * @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.
- */
-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 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.
- *
- * @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 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) {
-  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
-      }))
-    };
-  } finally {
-    await crawler.close();
-  }
-}
-
 /**
  * Handles `fetch-start-page`: loads the named input recipe from the current
  * workspace and fetches its start point (see `page-snapshot`'s own caveats:
@@ -1546,11 +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, an empty snapshot cache, Playwright's own default browser. */
+/** @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(),
-    snapshots: createSnapshotCache()
+    snapshots: createSnapshotCache(),
+    lastRuns: createLastRunCache()
   };
 }
 /**
@@ -1616,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,
@@ -2033,6 +2462,10 @@ function dispatch(command, state) {
       {
         return Promise.resolve(handleInferSelector(state, command));
       }
+    case 'explain-why':
+      {
+        return handleExplainWhy(state, command);
+      }
   }
 }
 function respondJson(response, status, body) {
@@ -2089,5 +2522,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 { 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