@opencraw/studio 0.0.6 → 0.0.7

package/dist/src/explain-why/index.d.ts

@@ -0,0 +1,5 @@
+export { explainWhy } from './why.use-case.js';
+export { buildWhySentence } from './why-sentence.mapper.js';
+export type { WhyFacts, WhyStepFact } from './why-sentence.mapper.js';
+export { hintFor } from './item-hint.algorithm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/explain-why/item-hint.algorithm.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export declare function hintFor(scope: Record<string, unknown> | undefined, boundId: string | undefined): string | undefined;
+//# sourceMappingURL=item-hint.algorithm.d.ts.map

package/dist/src/explain-why/why-sentence.mapper.d.ts

@@ -0,0 +1,48 @@
+import type { FieldTrace } from '@opencraw/core';
+/** One step of the recipe that may have bound the missing value's source id, and how it went over the whole sample run (`sample-run`'s `SampleStepSummary`). */
+export interface WhyStepFact {
+    path: string;
+    stepType: string;
+    stepId?: string;
+    outcome: 'ran' | 'skipped' | 'retried' | 'not-found';
+    error?: string;
+}
+/** Everything `buildWhySentence` needs to explain one missing or rejected value; gathered by `why.use-case.ts` from the last sample run's kept trace, scope and step summary. */
+export interface WhyFacts {
+    field: string;
+    outcome: 'missing' | 'rejected';
+    /** The engine's own rejection reason (`record:reject`'s `reason`), for a rejected record. */
+    reason?: string;
+    /** The resolved missing-value policy (`nullable`, `default`, `null`, `fail`, `skip-record`), when the field could be found in the output recipe. */
+    policy?: string;
+    /** The field's mapping trace, when the record itself was emitted (a `missing` outcome only — a rejected record never reached `data`). */
+    trace?: FieldTrace;
+    /** The leading id the rule's `from` reads (`item` of `item.description`), when the rule could be found. */
+    boundId?: string;
+    /** The step that binds `boundId`, when one was found in the recipe. */
+    step?: WhyStepFact;
+    /** A best-effort hint about what the bound value actually held (phase 2's item snapshot gives a richer one for a CSS pick; this is the scope-only fallback — see this module's doc comment). */
+    hint?: string;
+}
+/**
+ * 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.
+ */
+export declare function buildWhySentence(facts: WhyFacts): string;
+//# sourceMappingURL=why-sentence.mapper.d.ts.map

package/dist/src/explain-why/why.use-case.d.ts

@@ -0,0 +1,26 @@
+import type { InputRecipe, OutputRecipe } from '@opencraw/core';
+import type { LastRunCache } from '../sample-run/index.js';
+import type { WhyTarget, WhyView } from '../studio-api/index.js';
+/**
+ * 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.
+ */
+export declare function explainWhy(folder: string, cache: LastRunCache, loadPair: (folder: string, recipeId: string) => Promise<{
+    input: InputRecipe;
+    output: OutputRecipe;
+}>, target: WhyTarget): Promise<WhyView>;
+//# sourceMappingURL=why.use-case.d.ts.map

package/dist/src/index.d.ts

@@ -3,8 +3,9 @@ export { startStudioServer } from './studio-server/index.js';
 export type { StudioServer, StudioServerOptions } from './studio-server/index.js';
 export { openWorkspace, saveRecipe } from './recipe-workspace/index.js';
 export { runSample, loadRecipePair } from './sample-run/index.js';
-export type { RecipePair, SampleRunCallbacks, SampleRunHandle, SampleRunRecord, SampleRunResult, SampleStoppedBy } from './sample-run/index.js';
+export type { RecipePair, SampleRunCallbacks, SampleRunHandle, SampleRunRecord, SampleRunRejected, SampleRunResult, SampleStepSummary, SampleStoppedBy } from './sample-run/index.js';
 export { fetchStartPage } from './page-snapshot/index.js';
-export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, studioCommandSchema, stoppedBySchema, traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, snapshotViewSchema, verifySelectorViewSchema, fieldPickSchema, inferSelectorViewSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, } from './studio-api/index.js';
-export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, StudioCommand, StoppedBy, TraceLineEvent, RecordEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, SnapshotView, VerifySelectorView, FieldPick, InferSelectorView, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, } from './studio-api/index.js';
+export type { WhyFacts, WhyStepFact } from './explain-why/index.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, studioCommandSchema, stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, snapshotViewSchema, verifySelectorViewSchema, fieldPickSchema, inferSelectorViewSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, whyViewSchema, } from './studio-api/index.js';
+export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, StudioCommand, StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, SnapshotView, VerifySelectorView, FieldPick, InferSelectorView, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, WhyView, } from './studio-api/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/sample-run/index.d.ts

@@ -2,5 +2,7 @@ export { loadRecipePair } from './load-recipe-pair.use-case.js';
 export type { RecipePair } from './load-recipe-pair.use-case.js';
 export { runSample } from './run-sample.use-case.js';
 export type { SampleRunCallbacks, SampleRunHandle } from './run-sample.use-case.js';
-export type { SampleRunRecord, SampleRunResult, SampleStoppedBy } from './sample-run-record.contract.js';
+export type { SampleRunRecord, SampleRunRejected, SampleRunResult, SampleStepSummary, SampleStoppedBy } from './sample-run-record.contract.js';
+export { createLastRunCache, lastRunOf, recordLastRun } from './last-run.store.js';
+export type { LastRunCache, LastRunEntry } from './last-run.store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/sample-run/last-run.store.d.ts

@@ -0,0 +1,17 @@
+import type { SampleRunResult } from './sample-run-record.contract.js';
+/** The last completed sample run of one input recipe: its records, rejections, mapping traces and step summary, kept for `explain-why` (issue #92) so a Why? click needs no second run. */
+export interface LastRunEntry {
+    recipeId: string;
+    result: SampleRunResult;
+}
+/** One server's worth of last-run entries, by recipe id: a run replaces the previous one for the same recipe. */
+export interface LastRunCache {
+    entries: Map<string, LastRunEntry>;
+}
+/** @returns A fresh, empty cache. */
+export declare function createLastRunCache(): LastRunCache;
+/** Records a finished sample run, replacing whatever this recipe's cache entry held before. */
+export declare function recordLastRun(cache: LastRunCache, recipeId: string, result: SampleRunResult): void;
+/** @returns The recipe's last completed sample run, or `undefined` when none has finished yet. */
+export declare function lastRunOf(cache: LastRunCache, recipeId: string): LastRunEntry | undefined;
+//# sourceMappingURL=last-run.store.d.ts.map

package/dist/src/sample-run/run-sample.use-case.d.ts

@@ -1,10 +1,12 @@
 import type { BrowserSessionConfig } from '@opencraw/core';
 import type { SampleBudget } from '../studio-api/index.js';
-import type { SampleRunRecord, SampleRunResult } from './sample-run-record.contract.js';
+import type { SampleRunRecord, SampleRunRejected, SampleRunResult } from './sample-run-record.contract.js';
 /** Where trace lines and records go as a sample run proceeds. */
 export interface SampleRunCallbacks {
     onTraceLine: (line: string) => void;
     onRecord: (record: SampleRunRecord) => void;
+    /** A record was rejected (a field's `skip-record` missing/coercion policy); optional, most callers only need the final `rejectedRecords` list. */
+    onRejected?: (rejected: SampleRunRejected) => void;
 }
 /** A sample run in progress. */
 export interface SampleRunHandle {
@@ -14,11 +16,15 @@ export interface SampleRunHandle {
 }
 /**
  * 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.

package/dist/src/sample-run/sample-run-record.contract.d.ts

@@ -1,10 +1,37 @@
-/** One record streamed or kept from a sample run. */
+import type { MappingTrace } from '@opencraw/core';
+/**
+ * One record streamed or kept from a sample run. `scope` (the snapshot it
+ * was mapped from) and `mapping` (each field's source value and its value
+ * after every transform, `@opencraw/core`'s `record:emit.mapping`, core
+ * since 0.1.12) are always present: `runSample` runs with `debug: true`.
+ * Kept per record (studio plan §4.2/§4.4, issue #92) so the Record tab can
+ * show a transform chain's real values and the Why? tab can explain a
+ * missing one, without a second run.
+ */
 export interface SampleRunRecord {
     key: string | null;
     data: Record<string, unknown>;
+    scope?: Record<string, unknown>;
+    mapping?: MappingTrace;
+}
+/** One record a sample run rejected (`RecordRejectedError`, a field's `skip-record` policy), kept for the Why? tab. */
+export interface SampleRunRejected {
+    field: string;
+    reason: string;
+    url: string;
+    scope?: Record<string, unknown>;
 }
 /** A sample run's stopping reason: mirrors `@opencraw/core`'s `RecipeReport.stoppedBy`. */
 export type SampleStoppedBy = 'sample-maxRecords' | 'sample-maxPages' | 'sample-maxMs';
+/** One outcome of a step during a sample run, aggregated over every time its path ran: whether it ever ran cleanly, was skipped, or retried, kept for the Why? tab (issue #92) — which step bound a mapping's source id, and whether it found nothing. */
+export interface SampleStepSummary {
+    path: string;
+    stepType: string;
+    stepId?: string;
+    as?: string;
+    outcome: 'ran' | 'skipped' | 'retried';
+    error?: string;
+}
 /** What a sample run finished with. */
 export interface SampleRunResult {
     recipeId: string;
@@ -15,5 +42,7 @@ export interface SampleRunResult {
     error?: string;
     stoppedBy?: SampleStoppedBy;
     records: SampleRunRecord[];
+    rejectedRecords: SampleRunRejected[];
+    steps: SampleStepSummary[];
 }
 //# sourceMappingURL=sample-run-record.contract.d.ts.map

package/dist/src/studio-api/command.contract.d.ts

@@ -77,6 +77,49 @@ export declare const inferSelectorCommandSchema: z.ZodObject<{
     path: z.ZodString;
     nodeIds: z.ZodUnion<readonly [z.ZodTuple<[z.ZodString], null>, z.ZodTuple<[z.ZodString, z.ZodString], null>]>;
 }, z.core.$strip>;
+/** 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). */
+export declare const missingWhyTargetSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"missing">;
+    recipeId: z.ZodString;
+    recordIndex: z.ZodInt;
+    field: z.ZodString;
+}, z.core.$strip>;
+/** A rejected record, by its position in the last sample run's `rejectedRecords`. */
+export declare const rejectedWhyTargetSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"rejected">;
+    recipeId: z.ZodString;
+    rejectedIndex: z.ZodInt;
+}, z.core.$strip>;
+export declare const whyTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"missing">;
+    recipeId: z.ZodString;
+    recordIndex: z.ZodInt;
+    field: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"rejected">;
+    recipeId: z.ZodString;
+    rejectedIndex: z.ZodInt;
+}, z.core.$strip>], "kind">;
+/**
+ * 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.
+ */
+export declare const explainWhyCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"explain-why">;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"missing">;
+        recipeId: z.ZodString;
+        recordIndex: z.ZodInt;
+        field: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"rejected">;
+        recipeId: z.ZodString;
+        rejectedIndex: z.ZodInt;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
 export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"open-workspace">;
     folder: z.ZodString;
@@ -115,6 +158,18 @@ export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     recipeId: z.ZodString;
     path: z.ZodString;
     nodeIds: z.ZodUnion<readonly [z.ZodTuple<[z.ZodString], null>, z.ZodTuple<[z.ZodString, z.ZodString], null>]>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"explain-why">;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"missing">;
+        recipeId: z.ZodString;
+        recordIndex: z.ZodInt;
+        field: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"rejected">;
+        recipeId: z.ZodString;
+        rejectedIndex: z.ZodInt;
+    }, z.core.$strip>], "kind">;
 }, z.core.$strip>], "type">;
 export type SampleBudget = z.infer<typeof sampleBudgetSchema>;
 export type OpenWorkspaceCommand = z.infer<typeof openWorkspaceCommandSchema>;
@@ -126,6 +181,10 @@ export type SaveOutlineCommand = z.infer<typeof saveOutlineCommandSchema>;
 export type TakeSnapshotCommand = z.infer<typeof takeSnapshotCommandSchema>;
 export type VerifySelectorCommand = z.infer<typeof verifySelectorCommandSchema>;
 export type InferSelectorCommand = z.infer<typeof inferSelectorCommandSchema>;
+export type MissingWhyTarget = z.infer<typeof missingWhyTargetSchema>;
+export type RejectedWhyTarget = z.infer<typeof rejectedWhyTargetSchema>;
+export type WhyTarget = z.infer<typeof whyTargetSchema>;
+export type ExplainWhyCommand = z.infer<typeof explainWhyCommandSchema>;
 /** Every command the UI can send the server, over HTTP POST. */
 export type StudioCommand = z.infer<typeof studioCommandSchema>;
 //# sourceMappingURL=command.contract.d.ts.map

package/dist/src/studio-api/event.contract.d.ts

@@ -10,12 +10,36 @@ export declare const traceLineEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"trace-line">;
     line: z.ZodString;
 }, z.core.$strip>;
-/** One record a sample run emitted. */
+/** 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`). */
+export declare const fieldTraceSchema: z.ZodObject<{
+    from: z.ZodUnknown;
+    steps: z.ZodArray<z.ZodObject<{
+        op: z.ZodString;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** 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. */
 export declare const recordEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"record">;
     recipeId: z.ZodString;
     key: z.ZodNullable<z.ZodString>;
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    mapping: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        from: z.ZodUnknown;
+        steps: z.ZodArray<z.ZodObject<{
+            op: z.ZodString;
+            value: z.ZodUnknown;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** One record a sample run rejected (a field's `skip-record` policy on a missing or uncoercible value). */
+export declare const recordRejectedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"record-rejected">;
+    recipeId: z.ZodString;
+    field: z.ZodString;
+    reason: z.ZodString;
+    scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 /** A sample run ended: how many records, and why it stopped when it did not finish on its own. */
 export declare const runFinishedEventSchema: z.ZodObject<{
@@ -44,6 +68,20 @@ export declare const studioEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     recipeId: z.ZodString;
     key: z.ZodNullable<z.ZodString>;
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    mapping: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        from: z.ZodUnknown;
+        steps: z.ZodArray<z.ZodObject<{
+            op: z.ZodString;
+            value: z.ZodUnknown;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"record-rejected">;
+    recipeId: z.ZodString;
+    field: z.ZodString;
+    reason: z.ZodString;
+    scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"run-finished">;
     recipeId: z.ZodString;
@@ -62,7 +100,9 @@ export declare const studioEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "type">;
 export type StoppedBy = z.infer<typeof stoppedBySchema>;
 export type TraceLineEvent = z.infer<typeof traceLineEventSchema>;
+export type FieldTraceView = z.infer<typeof fieldTraceSchema>;
 export type RecordEvent = z.infer<typeof recordEventSchema>;
+export type RecordRejectedEvent = z.infer<typeof recordRejectedEventSchema>;
 export type RunFinishedEvent = z.infer<typeof runFinishedEventSchema>;
 export type WorkspaceChangedEvent = z.infer<typeof workspaceChangedEventSchema>;
 /** Every event the server pushes to the UI over the WebSocket. */

package/dist/src/studio-api/index.d.ts

@@ -1,13 +1,13 @@
-export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, studioCommandSchema } from './command.contract.js';
-export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, StudioCommand } from './command.contract.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, studioCommandSchema } from './command.contract.js';
+export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, StudioCommand } from './command.contract.js';
 export { snapshotViewSchema } from './snapshot-view.contract.js';
 export type { SnapshotView } from './snapshot-view.contract.js';
 export { verifySelectorViewSchema } from './verify-selector-view.contract.js';
 export type { VerifySelectorView } from './verify-selector-view.contract.js';
 export { fieldPickSchema, inferSelectorViewSchema } from './infer-selector-view.contract.js';
 export type { FieldPick, InferSelectorView } from './infer-selector-view.contract.js';
-export { stoppedBySchema, traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema } from './event.contract.js';
-export type { StoppedBy, TraceLineEvent, RecordEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent } from './event.contract.js';
+export { stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema } from './event.contract.js';
+export type { StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent } from './event.contract.js';
 export { recipeIssueSchema, recipeListingSchema, workspaceViewSchema } from './workspace-view.contract.js';
 export type { RecipeIssue, RecipeListing, WorkspaceView } from './workspace-view.contract.js';
 export { sampleRunRecordSchema, sampleRunViewSchema } from './sample-run-view.contract.js';
@@ -16,4 +16,6 @@ export { startPageViewSchema } from './start-page-view.contract.js';
 export type { StartPageView } from './start-page-view.contract.js';
 export { sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema } from './outline-view.contract.js';
 export type { SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView } from './outline-view.contract.js';
+export { whyViewSchema } from './why-view.contract.js';
+export type { WhyView } from './why-view.contract.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/studio-api/why-view.contract.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/** 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. */
+export declare const whyViewSchema: z.ZodObject<{
+    sentence: z.ZodString;
+    field: z.ZodString;
+    recipeId: z.ZodString;
+    outcome: z.ZodEnum<{
+        missing: "missing";
+        rejected: "rejected";
+    }>;
+    stepPath: z.ZodOptional<z.ZodString>;
+    policy: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WhyView = z.infer<typeof whyViewSchema>;
+//# sourceMappingURL=why-view.contract.d.ts.map

package/dist/src/studio-server/explain-why.handler.d.ts

@@ -0,0 +1,14 @@
+import type { ExplainWhyCommand, WhyView } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * 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.
+ */
+export declare function handleExplainWhy(state: StudioState, command: ExplainWhyCommand): Promise<WhyView>;
+//# sourceMappingURL=explain-why.handler.d.ts.map

package/dist/src/studio-server/workspace.store.d.ts

@@ -1,18 +1,19 @@
 import type { BrowserSessionConfig } from '@opencraw/core';
 import type { SnapshotCache } from '../page-snapshot/index.js';
-import type { SampleRunHandle } from '../sample-run/index.js';
+import type { LastRunCache, SampleRunHandle } from '../sample-run/index.js';
 import type { StudioEvent } from '../studio-api/index.js';
 import type { WsConnection } from './websocket.client.js';
-/** The server's mutable state: the opened folder, the run in progress (if any), the connected event sockets, the per-recipe snapshot cache `take-snapshot`/`verify-selector`/`infer-selector` share, and the browser launch settings every web-mode command (`take-snapshot`, `verify-selector`, `run-sample`) shares. */
+/** The server's mutable state: the opened folder, the run in progress (if any), the connected event sockets, the per-recipe snapshot cache `take-snapshot`/`verify-selector`/`infer-selector` share, each recipe's last finished sample run (`explain-why`, issue #92), and the browser launch settings every web-mode command (`take-snapshot`, `verify-selector`, `run-sample`) shares. */
 export interface StudioState {
     folder?: string;
     activeRun?: SampleRunHandle;
     sockets: Set<WsConnection>;
     snapshots: SnapshotCache;
+    lastRuns: LastRunCache;
     /** Set once at server start (`StudioServerOptions.browser`); every web-mode command reads it from here rather than each accepting its own. */
     browser?: BrowserSessionConfig;
 }
-/** @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. */
 export declare function createStudioState(): StudioState;
 /**
  * Sends one event to every connected client. A socket that errors while