@opencraw/studio 0.0.6 → 0.0.8

package/dist/src/flow-recording/recorder-script.client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The in-page script `recorder-session.use-case.ts` installs on every page
+ * of the studio's own headed browser window (`context.addInitScript`),
+ * reporting the person's actions to the binding it also exposes on the
+ * context (`context.exposeBinding`) — issue #95's "a script injected into
+ * every page ... reports the user's actions: click, type, select, key
+ * press, scroll".
+ *
+ * Kept as a plain string, not a TypeScript function passed to
+ * `page.evaluate`/`addInitScript`, for the same reason as
+ * `page-snapshot/hidden-marks.algorithm.ts`'s `hiddenMarksScript`: it
+ * references `window`/`document` as globals, which `AGENTS.md`'s "things
+ * that bit before" and the repo's `isolated-functions` lint rule forbid for
+ * an in-page TypeScript function.
+ *
+ * What it reports, and what it deliberately does not:
+ *
+ * - **click**: the nearest clickable ancestor (`a`, `button`,
+ *   `input[type=submit|button]`) of the element clicked, or the element
+ *   itself; for an `<a>`, also its `rel`, text and `aria-label` —
+ *   `next-link.policy.ts`'s only input.
+ * - **fill**: on `blur` of a text-like input/textarea whose value changed
+ *   since it was focused (never on every keystroke) — the field's `type`,
+ *   `name` and `id`, and the value *as typed*; whether that value is a
+ *   secret, and what replaces it, is `secret-field.policy.ts`'s call,
+ *   server-side, not this script's.
+ * - **select**: on `change` of a `<select>`.
+ * - **keypress**: `Enter` only (issue #95's own example, "Press Enter");
+ *   every other key is noise a recipe step has no shape for.
+ * - **scroll**: once per "scroll session" (debounced), when the page has
+ *   been scrolled within `NEAR_BOTTOM_PX` of its bottom.
+ * - **unsupported**: once, the first time an event's target sits inside a
+ *   shadow root, or this script runs in a frame that is not the top window
+ *   (an iframe) — issue #95's explicit out-of-scope cases, reported instead
+ *   of attempted.
+ *
+ * Every reported element is marked with `attribute` (`data-oc-node` by
+ * default, `@opencraw/core`'s `NODE_ID_ATTRIBUTE`) if it does not already
+ * carry one, the same attribute `selector-inference`'s `pathToNode` reads —
+ * so `recorder-session.use-case.ts` can turn a report straight into a
+ * verified selector with the phase 2 generator, never inventing its own.
+ *
+ * @param bindingName - The name Playwright's `exposeBinding` gave the reporting function (`window[bindingName]`).
+ * @param attribute - The marker attribute; defaults to `NODE_ID_ATTRIBUTE`.
+ * @returns A self-invoking script, ready for `context.addInitScript({ content: recorderScript(...) })`.
+ */
+export declare function recorderScript(bindingName: string, attribute?: string): string;
+//# sourceMappingURL=recorder-script.client.d.ts.map

package/dist/src/flow-recording/recorder-session.use-case.d.ts

@@ -0,0 +1,67 @@
+import type { Page } from 'playwright';
+import type { BrowserSessionConfig } from '@opencraw/core';
+import type { OutlineNode } from '../studio-api/index.js';
+export interface RecorderNote {
+    kind: 'next-link' | 'unsupported' | 'info';
+    message: string;
+}
+/** Where recorded actions and notices go as a recording proceeds. */
+export interface RecorderCallbacks {
+    onCard: (node: OutlineNode, secret: boolean) => void;
+    onNote: (note: RecorderNote) => void;
+}
+export interface RecorderSessionOptions {
+    /** The page the headed window opens on. */
+    startUrl: string;
+    /** Where the studio's own recorder profiles live — see `BrowserProfiles`; never the folder a crawl's own `session.browserProfile` uses. */
+    profileDir: string;
+    /** Browser launch settings; `headless` is always forced `false` — a recording is, by definition, a window the person watches and drives. */
+    browser?: BrowserSessionConfig;
+}
+/**
+ * A recording in progress: `stop` closes the window and hands back every
+ * step recorded, in order. `page` is the window's own live Playwright page
+ * — public the same way `BrowserSession.page` already is, for a caller (a
+ * future embedded view, this phase's own e2e test driving the window "as
+ * the person would") that needs to reach the live window itself, not just
+ * the reported actions.
+ */
+export interface RecorderSessionHandle {
+    page: Page;
+    stop: () => Promise<{
+        steps: Record<string, unknown>[];
+    }>;
+}
+/**
+ * Opens the headed browser window a flow is recorded in (issue #95, studio
+ * plan §3.1's last paragraph / phase 6): a Playwright persistent context, in
+ * the studio's own profile (`BrowserProfiles`, `headless: false` — the only
+ * precedent this codebase already has for a headed launch,
+ * `packages/core/src/browser-session/browser-profile.store.ts`), with
+ * `recorder-script.client.ts` installed on every page
+ * (`context.addInitScript`) and reporting through a context-wide binding
+ * (`context.exposeBinding`, so a page opened mid-recording — a link with
+ * `target=_blank`, say — is covered too, not only the first page).
+ *
+ * Each reported action is resolved into a verified selector
+ * (`selector-inference`, against the page's own current markup — issue
+ * #95's "verified against the page"), turned into a step
+ * (`action-to-step.mapper.ts`), and broadcast as an outline card built by
+ * `scope-outline`'s own `recipeToOutline` — the same sentence/bracket logic
+ * every other phase's cards already go through, never a second card format.
+ * A secret field's value is replaced by its `{{env.NAME}}` placeholder
+ * before it reaches a step, a card, or this function's return value: the
+ * real value is discarded the instant `secret-field.policy.ts` flags the
+ * field, never logged, never kept.
+ *
+ * Recording inside an iframe or shadow DOM is out of this phase's scope
+ * (issue #95): `recorder-script.client.ts` detects both and reports them as
+ * `unsupported` notes instead of guessing at a selector that would not
+ * verify.
+ *
+ * @param options - The start URL, the profile directory, and browser launch settings.
+ * @param callbacks - Where cards and notices go as they happen.
+ * @returns A handle: `stop` closes the window and returns every step recorded.
+ */
+export declare function openRecorderSession(options: RecorderSessionOptions, callbacks: RecorderCallbacks): Promise<RecorderSessionHandle>;
+//# sourceMappingURL=recorder-session.use-case.d.ts.map

package/dist/src/flow-recording/secret-field.policy.d.ts

@@ -0,0 +1,33 @@
+import type { RecordedField } from './recorded-action.contract.js';
+/**
+ * Whether a recorded `fill`/`select` field's typed value is a secret: a
+ * `type="password"` input, or a field the person explicitly marked (`marked`,
+ * a future "mark as secret" UI action — not built by this phase, but the
+ * flag is honoured wherever it comes from), or a name/id matching `token`,
+ * `secret` or `api[-_]?key` (issue #95's exact wording).
+ *
+ * @param field - The field's type/name/id, as reported by `recorder-script.client.ts`.
+ * @param marked - The person explicitly marked this field as secret; default `false`.
+ * @returns Whether the field's value must become `{{env.NAME}}` instead of the real text.
+ */
+export declare function isSecretField(field: RecordedField, marked?: boolean): boolean;
+/**
+ * The `{{env.NAME}}` variable name a secret field suggests, from its own
+ * name/id (falling back to `PASSWORD` for a bare `type="password"` field
+ * with neither): `camelCase`/`kebab-case`/`snake_case` all become
+ * `SCREAMING_SNAKE_CASE`, punctuation dropped, so `user-pass`, `userPass`
+ * and `user_pass` all suggest `USER_PASS`.
+ *
+ * @param field - The field's type/name/id.
+ * @returns A valid env-var-shaped name (letters, digits, underscores, not starting with a digit).
+ */
+export declare function secretEnvName(field: RecordedField): string;
+/**
+ * The placeholder a secret field's value becomes in the recorded recipe:
+ * never the real text, in the recipe JSON or anywhere the studio logs.
+ *
+ * @param field - The field's type/name/id.
+ * @returns `{{env.NAME}}`.
+ */
+export declare function secretPlaceholder(field: RecordedField): string;
+//# sourceMappingURL=secret-field.policy.d.ts.map

package/dist/src/flow-recording/wait-insertion.policy.d.ts

@@ -0,0 +1,26 @@
+import type { Step } from '@opencraw/core';
+export type WaitStep = Extract<Step, {
+    type: 'wait';
+}>;
+/** What happened right after the previous recorded action, before this one. */
+export interface WaitContext {
+    /** The previous action's click/key press changed the page. */
+    navigated: boolean;
+    /** The page fetched something (XHR/`fetch`) since the previous action, without necessarily navigating. */
+    xhr: boolean;
+}
+/**
+ * Whether a `Wait for <selector>` step belongs between the action that just
+ * happened and the next one (issue #95): after a navigation or an XHR, the
+ * recorder inserts a wait for the element the person interacts with next, so
+ * a replayed recipe does not race the page's own load. Nothing to wait for
+ * without a next selector (a page-level key press, a scroll) — and no
+ * navigation or fetch either: a recording of a page that never moves should
+ * not fill up with waits nobody asked for.
+ *
+ * @param context - What happened since the previous action.
+ * @param nextSelector - The next action's own resolved selector, when it has one.
+ * @returns The wait step to insert before the next action's own step, or `undefined`.
+ */
+export declare function insertWaitStep(context: WaitContext, nextSelector: string | undefined): WaitStep | undefined;
+//# sourceMappingURL=wait-insertion.policy.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, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, gridViewCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, domTreeNodeViewSchema, pageDataFindingSchema, inspectViewSchema, observedResponseSchema, responsesSeenViewSchema, documentTreeNodeViewSchema, documentTreeViewSchema, pdfCellViewSchema, pdfRowViewSchema, pdfPageViewSchema, pdfDocumentViewSchema, tablePreviewTableSchema, tablePreviewBandSchema, tablePreviewMatchSchema, tablePreviewViewSchema, gridCellViewSchema, gridMergeViewSchema, gridSheetViewSchema, workbookDocumentViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, deckShapeViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, deckSlideViewSchema, deckDocumentViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, startRecordingCommandSchema, stopRecordingCommandSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, } from './studio-api/index.js';
+export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, GridViewCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StudioCommand, StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, SnapshotView, VerifySelectorView, FieldPick, InferSelectorView, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, WhyView, DomTreeNodeView, PageDataKind, PageDataFindingView, InspectView, ObservedResponseView, ResponsesSeenView, DocumentTreeNodeView, DocumentTreeView, PdfCellView, PdfRowView, PdfPageView, PdfDocumentView, TablePreviewTableView, TablePreviewBandView, TablePreviewMatchView, TablePreviewView, GridCellView, GridMergeView, GridSheetView, WorkbookDocumentView, GridTablePreviewMatchView, GridTablePreviewView, DeckShapeView, DeckChartSeriesView, DeckChartView, DeckSlideView, DeckDocumentView, DeckTablePreviewMatchView, DeckTablePreviewView, StartRecordingCommand, StopRecordingCommand, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, } from './studio-api/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/page-inspector/dom-tree.mapper.d.ts

@@ -0,0 +1,32 @@
+/** One row of the Inspect panel's DOM tree (studio plan §3.3, issue #93): a snapshot element, or a collapsed run of identical siblings. */
+export interface DomTreeNode {
+    /** The snapshot's own `data-oc-node` id — what a pick addresses. Present on every real element; absent only on the synthetic wrapper a collapsed run never needs (a run always keeps its first member's id here). */
+    nodeId: string;
+    tag: string;
+    id?: string;
+    classes?: string[];
+    /** Every other attribute (the internal `data-oc-node`/`data-oc-hidden` marks stripped). */
+    attributes: Record<string, string>;
+    /** This element's own text, trimmed and cut to `TEXT_LIMIT`, when it has no element children (mixed element+text content shows only the element children — see this file's `buildNode`). */
+    text?: string;
+    /** From the snapshot's `data-oc-hidden` mark (`hidden-marks.algorithm.ts`, phase 2). */
+    hidden: boolean;
+    children: DomTreeNode[];
+    /** Set when this row stands for a run of `repeatCount` structurally identical consecutive siblings (same tag, attributes and subtree — ids aside): the issue's `×20`. `repeatNodeIds` carries every collapsed sibling's own id, so a pick still knows every node the row represents. */
+    repeatCount?: number;
+    repeatNodeIds?: string[];
+}
+/**
+ * Builds the Inspect panel's DOM tree from a captured snapshot (studio plan
+ * §3.3, issue #93): the same rewritten, marked-up document the content pane's
+ * iframe shows (`page-snapshot`'s `take-snapshot.use-case.ts`), so a tree
+ * row's `nodeId` addresses exactly the element the iframe would highlight —
+ * no separate capture, per issue #93's scope note to reuse phase 2's
+ * snapshot rather than recapture.
+ *
+ * @param snapshotHtml - The cached, rewritten snapshot (`SnapshotResult.html`).
+ * @returns The tree's root (the document's `<html>` element).
+ * @throws Error when the document has no `<html>` element (should not happen: `rewriteDocument` always produces one).
+ */
+export declare function domTree(snapshotHtml: string): DomTreeNode;
+//# sourceMappingURL=dom-tree.mapper.d.ts.map

package/dist/src/page-inspector/index.d.ts

@@ -0,0 +1,7 @@
+export { domTree } from './dom-tree.mapper.js';
+export type { DomTreeNode } from './dom-tree.mapper.js';
+export { pageData } from './page-data.algorithm.js';
+export type { PageDataFinding, PageDataKind } from './page-data.algorithm.js';
+export { responsesSeen } from './responses-seen.use-case.js';
+export type { ObservedResponse } from './responses-seen.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/page-inspector/page-data.algorithm.d.ts

@@ -0,0 +1,39 @@
+export type PageDataKind = 'ld-json' | 'json-script' | 'inline-state' | 'meta' | 'link';
+/** One pickable value in "data in the page" (studio plan §3.3, issue #93): a `<script type="application/ld+json">`/`"application/json">` block, an inline state assignment, a `<meta>`, or a `<link rel>`. */
+export interface PageDataFinding {
+    kind: PageDataKind;
+    /** What the UI shows for this row: the JSON-LD `@type`, the global name assigned (`__NEXT_DATA__`), or `meta:`/`link:` and its name/rel. */
+    label: string;
+    /** A selector verified against the real page (never the sanitised snapshot: `ld-json`/`json-script`/`inline-state` live inside a `<script>`, which the snapshot's `rewriteDocument` strips for the sandboxed iframe — see this file's own doc comment). */
+    selector: string;
+    selectorKind: 'css';
+    /** How many elements this selector reaches on the real page — always 1 by construction (`structuralSelector` is a full ancestor path), kept as a field so the UI's "N matches" confidence reads the same as a tree pick's. */
+    matches: number;
+    /** The parsed value's top-level keys, each pickable as its own `$.<key>` `jsonpath` card — absent when the value is not a JSON object (an array, a scalar, or text that did not parse). */
+    keys?: string[];
+    /** `meta`/`link` only: which attribute holds the pickable value (`content`/`href`). */
+    attribute?: string;
+}
+/**
+ * Finds the data-in-the-page findings the Inspect panel lists apart from the
+ * DOM tree (studio plan §3.3, issue #93): JSON-LD and `application/json`
+ * script blocks, inline state assignments, `<meta>` name/property values and
+ * `<link rel>`s — reusing `@opencraw/probe`'s `describeJson` for a found
+ * value's shape (its own `find-data.algorithm.ts`/`html-findings.mapper.ts`
+ * scan a page's raw text for *reporting*, with no element to point a pick at;
+ * this function's own job — locating each finding's element so a pick can
+ * reach it — is new).
+ *
+ * Takes the **raw** captured document, not the display snapshot
+ * (`page-snapshot`'s `SnapshotResult.html`): `rewriteDocument` strips every
+ * `<script>` for the sandboxed iframe, which would make JSON-LD, inline
+ * state and other script-tag data invisible here. `<meta>`/`<link>` survive
+ * rewriting untouched, so using the raw document for every kind (rather than
+ * mixing two documents) keeps this function simple and its selectors
+ * verified against what the engine will actually crawl.
+ *
+ * @param rawHtml - The document as fetched/rendered, before `rewriteDocument` strips scripts.
+ * @returns The findings, in document order.
+ */
+export declare function pageData(rawHtml: string): PageDataFinding[];
+//# sourceMappingURL=page-data.algorithm.d.ts.map

package/dist/src/page-inspector/responses-seen.use-case.d.ts

@@ -0,0 +1,36 @@
+import type { BrowserSessionConfig, InputRecipe } from '@opencraw/core';
+/** One JSON response the page fetched while it rendered (studio plan §3.3, issue #93): what "responses seen" lists, and what picking one switches the recipe to api mode on. */
+export interface ObservedResponse {
+    url: string;
+    status: number;
+    /** The response body's size in bytes (its UTF-8 text length). */
+    size: number;
+    /** The top-level shape (`describeJson`'s own `type`: `"object"`, `"array (12) of object"`…), or `"text"` when the body did not parse as JSON despite its content type. */
+    shape: string;
+}
+/**
+ * Records the JSON responses seen while an input recipe's start page
+ * rendered (studio plan §3.3, issue #93): the same technique `packages/cli`'s
+ * `probe --browser` uses (`observeBrowserJson`) — render the page, listen for
+ * `response` events whose content type is JSON, give it a few seconds to
+ * settle. Kept as its own capture, independent of `page-snapshot`'s
+ * `take-snapshot.use-case.ts`: that capture reads `page.content()` right
+ * after `goto` resolves, with no observation window, and changing its shape
+ * to also collect responses was a larger, riskier change to already-shipped,
+ * tested code than this phase's budget allowed (see this phase's final
+ * report) — so this opens its own short-lived browser session instead of
+ * piggy-backing on the cached snapshot.
+ *
+ * Only `"start"` is supported, mirroring `take-snapshot.use-case.ts`'s own
+ * reach; api-mode recipes have no page load to observe, so they always
+ * answer with an empty list rather than an error (there is nothing wrong
+ * with asking, the answer is just "none").
+ *
+ * @param input - The input recipe; only `mode` and the first `start` point are used.
+ * @param stepPath - The step to observe after, e.g. `"start"`.
+ * @param browser - Browser launch settings, shared with `take-snapshot`/`verify-selector`/`run-sample`.
+ * @returns The distinct JSON responses observed, at most `RESPONSE_LIMIT`.
+ * @throws Error when the recipe has no start point, or `stepPath` is not `"start"`.
+ */
+export declare function responsesSeen(input: InputRecipe, stepPath: string, browser?: BrowserSessionConfig): Promise<ObservedResponse[]>;
+//# sourceMappingURL=responses-seen.use-case.d.ts.map

package/dist/src/page-snapshot/index.d.ts

@@ -6,4 +6,7 @@ export type { RewrittenDocument } from './rewrite-document.mapper.js';
 export { hiddenMarksScript, HIDDEN_ATTRIBUTE } from './hidden-marks.algorithm.js';
 export { createSnapshotCache, cachedSnapshot, putSnapshot, invalidateRecipe } from './snapshot.store.js';
 export type { SnapshotCache } from './snapshot.store.js';
+export { pdfBytes } from './pdf-bytes.use-case.js';
+export { rereadCsv } from './reread-csv.use-case.js';
+export type { CsvOverride } from './reread-csv.use-case.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/page-snapshot/pdf-bytes.use-case.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fetches a PDF's raw bytes for the PDF canvas's `pdf.js` to render in the
+ * browser (studio plan §3.4, issue #94's 5b: "the PDF bytes served by the
+ * studio"). `take-snapshot` already read this same document with
+ * `@opencraw/core`'s `readPdf` for the cells/rows `document-view` maps, but
+ * `HttpClient`/`readPdf` parse the bytes and keep only the result — pdf.js
+ * needs the file itself, so this re-fetches it from the same URL a cached
+ * snapshot's own `SnapshotResult.baseUrl` gives, the way `HttpClient`'s own
+ * `file:` branch (`readLocalFile`) and its HTTP fetch do.
+ *
+ * @param url - The document's URL — a `file:` URL or an `http(s):` URL.
+ * @returns The raw bytes.
+ * @throws Error when a `file:` URL cannot be read, or the fetch does not succeed.
+ */
+export declare function pdfBytes(url: string): Promise<Uint8Array>;
+//# sourceMappingURL=pdf-bytes.use-case.d.ts.map

package/dist/src/page-snapshot/reread-csv.use-case.d.ts

@@ -0,0 +1,22 @@
+import type { WorkbookDocument } from '@opencraw/core';
+/** `delimiter`/`encoding` on a `grid-view` request overriding what was auto-detected (issue #94's 5c: "the detected delimiter and encoding shown and overridable"); either, both, or neither. */
+export interface CsvOverride {
+    delimiter?: string;
+    encoding?: string;
+}
+/**
+ * Re-reads a CSV document with an overridden delimiter and/or encoding
+ * (studio plan §3.4, issue #94's 5c). `take-snapshot` already read this same
+ * document once with auto-detection (`http.client.ts`'s own `csvWorkbook`
+ * call); it keeps only the parsed result, not the raw bytes, so re-reading
+ * the file/URL is the only way to apply a different choice — the same
+ * "the studio re-fetches, the reader keeps no bytes around" tradeoff
+ * `pdf-bytes.use-case.ts` documents for pdf.js.
+ *
+ * @param url - The document's URL — a `file:` URL or an `http(s):` URL (`page-snapshot`'s cached `SnapshotResult.baseUrl`).
+ * @param override - The delimiter and/or encoding to force; `HttpClient` still detects whichever one is left out.
+ * @returns The freshly read workbook.
+ * @throws Error when the URL cannot be read, or it no longer reads back as a workbook.
+ */
+export declare function rereadCsv(url: string, override: CsvOverride): Promise<WorkbookDocument>;
+//# sourceMappingURL=reread-csv.use-case.d.ts.map

package/dist/src/page-snapshot/take-snapshot.use-case.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserSessionConfig, InputRecipe } from '@opencraw/core';
+import type { BodyKind, BrowserSessionConfig, HttpBody, InputRecipe } from '@opencraw/core';
 export interface SnapshotResult {
     /** The rewritten document, ready for the content pane's sandboxed iframe. */
     html: string;
@@ -6,6 +6,31 @@ export interface SnapshotResult {
     nodeCount: number;
     /** The page's own URL, used to resolve every relative URL and as the `<base>`. */
     baseUrl: string;
+    /**
+     * The document as captured, before `rewriteDocument` strips every
+     * `<script>` for the sandboxed iframe — server-side only, never sent to the
+     * UI (`studio-api`'s `SnapshotView` does not carry it): `page-inspector`'s
+     * `page-data.algorithm.ts` (issue #93) needs the JSON-LD, inline state and
+     * `application/json` blocks a script tag can hold, which the display
+     * snapshot no longer has by the time it is cached.
+     */
+    rawHtml: string;
+    /**
+     * The format `http.client.ts` read the body as (api mode only; `undefined`
+     * in web mode, whose document is always HTML) — what the content pane
+     * uses to pick a canvas: `document-view`'s tree/pdf/grid/deck for
+     * `json`/`yaml`/`xml`/`pdf`/`csv`/`xlsx`/`pptx`, the snapshot iframe for
+     * `html` (and `docx`/`markdown`, which `http.client.ts` already turns into
+     * HTML), studio plan §3.4, issue #94.
+     */
+    format?: BodyKind;
+    /**
+     * The parsed body itself (api mode only), for `document-view`'s mappers to
+     * read — server-side only, never sent to the UI as-is (`studio-api`'s
+     * `SnapshotView` carries only `format`; a canvas asks for its own view
+     * model with a follow-up command, `inspect-page`'s own pattern).
+     */
+    body?: HttpBody;
 }
 /**
  * Captures the snapshot the content pane shows (studio plan §3.1, issue

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