@opencraw/studio 0.0.18 → 0.0.19

package/dist/browser-provisioning/ensure-browser-launch.use-case.d.ts

@@ -0,0 +1,12 @@
+import type { BrowserSessionConfig } from '@opencraw/core';
+/**
+ * Runs a browser-launching function, and — only when it fails with Playwright's own "no browser
+ * downloaded" error, only for a default chromium launch with no explicit binary configured — installs
+ * Chromium once and retries, instead of letting Playwright's raw error reach the studio's caller.
+ *
+ * An explicit `executablePath` or `OPENCRAW_CHROMIUM` means the person (or this repo's own sandbox)
+ * already chose a specific binary; a missing-browser failure there is their setup to fix, not
+ * something to silently install over.
+ */
+export declare function ensureBrowserLaunch<T>(browser: BrowserSessionConfig | undefined, launch: () => Promise<T>, installChromium?: (run?: () => Promise<void>) => Promise<void>): Promise<T>;
+//# sourceMappingURL=ensure-browser-launch.use-case.d.ts.map

package/dist/browser-provisioning/index.d.ts

@@ -0,0 +1,2 @@
+export { ensureBrowserLaunch } from './ensure-browser-launch.use-case';
+//# sourceMappingURL=index.d.ts.map

package/dist/browser-provisioning/install-chromium.use-case.d.ts

@@ -0,0 +1,2 @@
+export declare function installChromiumOnce(run?: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=install-chromium.use-case.d.ts.map

package/dist/browser-provisioning/missing-browser.policy.d.ts

@@ -0,0 +1,3 @@
+/** Recognises Playwright's own "no browser downloaded" failure so a launch can be retried after installing one, instead of surfacing Playwright's raw ASCII-art error. */
+export declare function isMissingBrowserError(error: unknown): boolean;
+//# sourceMappingURL=missing-browser.policy.d.ts.map

package/dist/document-view/deck-view.mapper.d.ts

@@ -0,0 +1,70 @@
+import type { DeckDocument } from '@opencraw/core';
+import type { GridSheetView } from './workbook-view.mapper';
+/** One text box on a slide, in points from the slide's top-left corner — mirrors `@opencraw/core`'s `DeckShape`. */
+export interface DeckShapeView {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    text: string;
+    placeholder?: string;
+}
+/** One series of a chart — mirrors `@opencraw/core`'s `DeckChart`'s own series entries. */
+export interface DeckChartSeriesView {
+    name: string;
+    categories: string[];
+    values: (number | null)[];
+}
+/** One chart on a slide — mirrors `@opencraw/core`'s `DeckChart`. */
+export interface DeckChartView {
+    type: string;
+    title?: string;
+    series: DeckChartSeriesView[];
+}
+/** One slide's geometry, tables, charts and notes for the deck canvas (studio plan §3.4, issue #94's 5d). */
+export interface DeckSlideView {
+    number: number;
+    title?: string;
+    hidden: boolean;
+    /** Text boxes in reading order, ready to draw as absolutely-positioned boxes. */
+    shapes: DeckShapeView[];
+    /**
+     * `shapes` grouped into visual rows, left to right — indices into
+     * `shapes` — the same grouping `findDeckTables`'s `shapes: true` reading
+     * groups a slide's text boxes into (`rowsOfCells`, the pure algorithm
+     * `@opencraw/core`'s own `deck-table.algorithm.ts`'s `shapeTables` uses).
+     * The deck canvas's text-box-grid pick (issue #94's 5d) reads this to find
+     * the row a clicked shape sits in, and that row's own leftmost shape's
+     * text, without recomputing the grouping client-side or reaching for a
+     * core-internal helper: the exact row `findDeckTables` would match a
+     * `header`/`until` pattern against at run time.
+     */
+    shapeRows: number[][];
+    /** Native tables, as the grid canvas's own sheet view (`workbook-view.mapper.ts`'s `GridSheetView`) — reused wholesale rather than a parallel shape, since a deck's native table *is* a sheet (`@opencraw/core`'s own `DeckSlide.tables`). */
+    tables: GridSheetView[];
+    charts: DeckChartView[];
+    notes: string;
+}
+/** What `deck-view` answers with (studio plan §3.4, issue #94's 5d): the slide size in points and every slide's shapes, tables, charts and notes, for the deck canvas to draw and pick from. */
+export interface DeckDocumentView {
+    width: number;
+    height: number;
+    slides: DeckSlideView[];
+}
+/**
+ * Builds the deck canvas's view model (studio plan §3.4, issue #94's 5d)
+ * from an already-read `DeckDocument` (`take-snapshot`'s cached body — no
+ * second read of the file): every slide's shapes (with their visual-row
+ * grouping, for the text-box-grid pick), native tables (through
+ * `workbook-view.mapper.ts`'s own sheet view — a deck table *is* a sheet),
+ * charts and notes. Table-specific diagnostics for a `table` extract's own
+ * options (the live preview) are not here — they come from
+ * `table-preview.use-case.ts`'s `previewDeckTable` instead, computed live as
+ * those options change, the same split `pdf-view.mapper.ts`/`workbook-view.mapper.ts`
+ * already use.
+ *
+ * @param document - The read deck.
+ * @returns The view.
+ */
+export declare function deckDocumentView(document: DeckDocument): DeckDocumentView;
+//# sourceMappingURL=deck-view.mapper.d.ts.map

package/dist/document-view/index.d.ts

@@ -0,0 +1,13 @@
+export { deckDocumentView } from './deck-view.mapper';
+export type { DeckChartSeriesView, DeckChartView, DeckDocumentView, DeckShapeView, DeckSlideView } from './deck-view.mapper';
+export { documentTreeView } from './tree-view.mapper';
+export type { DocumentTreeNode, DocumentTreeView, TreeValueType } from './tree-view.mapper';
+export { pdfDocumentView } from './pdf-view.mapper';
+export type { PdfCellView, PdfDocumentView, PdfPageView, PdfRowView } from './pdf-view.mapper';
+export { previewDeckTable, previewGridTable, previewPdfTable } from './table-preview.use-case';
+export type { DeckTablePreviewMatch, DeckTablePreviewOptions, DeckTablePreviewResult, GridTablePreviewMatch, GridTablePreviewOptions, GridTablePreviewResult, TablePreviewMatch, TablePreviewOptions, TablePreviewResult } from './table-preview.use-case';
+export { previewRegion } from './region-preview.use-case';
+export type { RegionPreviewResult, RegionPreviewMatch } from './region-preview.use-case';
+export { workbookDocumentView } from './workbook-view.mapper';
+export type { GridCellType, GridCellView, GridMergeView, GridSheetView, WorkbookDocumentView } from './workbook-view.mapper';
+//# sourceMappingURL=index.d.ts.map

package/dist/document-view/pdf-view.mapper.d.ts

@@ -0,0 +1,47 @@
+import type { PdfDocument } from '@opencraw/core';
+/** One text cell, in PDF points (y growing upwards from the bottom edge) — mirrors `@opencraw/core`'s `PdfCell`. */
+export interface PdfCellView {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    text: string;
+}
+/** One row of cells, top to bottom. */
+export interface PdfRowView {
+    top: number;
+    bottom: number;
+    cells: PdfCellView[];
+}
+/** One page's geometry and diagnostics for the PDF canvas (studio plan §3.4, issue #94's 5b). */
+export interface PdfPageView {
+    number: number;
+    /** In PDF points, the size `pdf.js` renders the page at scale 1. */
+    width: number;
+    height: number;
+    rows: PdfRowView[];
+    /** `rows.length`, for the diagnostics line ("N rows, M cells"). */
+    rowCount: number;
+    cellCount: number;
+    /** Whether `readPdf` found any text on this page — `false` means a scan: the person sees at once there is nothing here to read (issue #94's 5b). */
+    hasTextLayer: boolean;
+}
+/** The PDF canvas's view of a read document: every page's cells and rows, ready to draw over `pdf.js`'s own rendering. */
+export interface PdfDocumentView {
+    pages: PdfPageView[];
+}
+/**
+ * Builds the PDF canvas's view model (studio plan §3.4, issue #94's 5b) from
+ * an already-read `PdfDocument` (`take-snapshot`'s cached body — no second
+ * read of the file): every cell and row `readPdf` found, in PDF points, plus
+ * per-page counts and whether the page has a text layer at all. Table-specific
+ * diagnostics (the header row, the column bands, the wrapped-row regrouping)
+ * are not here — they depend on a `table` extract's own options, so they come
+ * from `table-preview.use-case.ts` instead, computed live as those options
+ * change.
+ *
+ * @param document - The read PDF.
+ * @returns The view.
+ */
+export declare function pdfDocumentView(document: PdfDocument): PdfDocumentView;
+//# sourceMappingURL=pdf-view.mapper.d.ts.map

package/dist/document-view/region-preview.use-case.d.ts

@@ -0,0 +1,30 @@
+import type { DeckDocument, DeckShape, PdfCell, PdfDocument } from '@opencraw/core';
+/** One page (or slide) a `region` extract's box reads text off: the text the step binds, and what it was read from — a PDF's cells or a deck's text boxes (what the canvas highlights). */
+export interface RegionPreviewMatch {
+    /** The page number of a PDF, or the slide number of a deck. */
+    page: number;
+    text: string;
+    cells: PdfCell[];
+    shapes: DeckShape[];
+}
+/** What a `region` extract's selector reads off the already-read document: one match per page or slide with text in the box. */
+export interface RegionPreviewResult {
+    matches: RegionPreviewMatch[];
+    /** The selector does not parse yet (the person is still typing it, or dragging a box into shape), or names a `page=` on a deck (or a `slide=` on a PDF): reported, not thrown. */
+    error?: string;
+}
+/**
+ * Runs a `region` extract's selector against an already-read PDF or deck
+ * (issues #121 and #122: the canvases' click-to-snap selection) — the
+ * engine's own `regionText` / `deckRegionText`, so what the canvas
+ * highlights and the text it shows are exactly what the step will read,
+ * and a pure function of the document, so re-running it on every change
+ * of the box costs nothing. A `slide=` on a PDF (or a `page=` on a deck)
+ * is the same mismatch the step would fail with, reported as `error`.
+ *
+ * @param document - The read PDF or deck (`take-snapshot`'s cached body).
+ * @param selector - The `region` selector, `page=1 x=72..252 y=640..664` or `slide=2 x=60..900 y=30..90`.
+ * @returns The matches, or `error` when the selector does not parse or does not fit the document.
+ */
+export declare function previewRegion(document: PdfDocument | DeckDocument, selector: string): RegionPreviewResult;
+//# sourceMappingURL=region-preview.use-case.d.ts.map

package/dist/document-view/table-preview.use-case.d.ts

@@ -0,0 +1,152 @@
+import type { DeckDocument, PdfDocument, PdfTable, TableAlign, TableBandDiagnostics, WorkbookCell, WorkbookDocument } from '@opencraw/core';
+/**
+ * A `table` extract's own options, as the studio's picks build them: string
+ * patterns, not yet compiled — the same shape `ExtractStep`'s `table`-kind
+ * fields have, kept separate so this slice does not import the engine's
+ * recipe schema for one interface.
+ */
+export interface TablePreviewOptions {
+    /** Matches the header row (the recipe's `selector`). */
+    header: string;
+    /** Matches the row that ends the table. */
+    until?: string;
+    /** Output key -> a pattern for that column's header cell. */
+    columns?: Record<string, string>;
+    align?: TableAlign;
+}
+/** One matched table, with the exact rows to highlight on the page. */
+export interface TablePreviewMatch {
+    page: number;
+    /** Index into that page's rows of the header row. */
+    headerRowIndex: number;
+    /** Every row index (into that page's rows) this match highlights: the header, every regrouped body row, and the `until` row when there is one — sorted, deduplicated. */
+    matchedRowIndices: number[];
+    /** The column bands the body's cells clustered into, left to right — a column band pick reads its `name` (issue #94's 5b). */
+    bands: TableBandDiagnostics[];
+    /** The gap (in points) two cell edges may differ by and still share a band — shown while dragging a band edge. */
+    bandTolerance: number;
+    table: PdfTable;
+}
+/** What `previewPdfTable` answers with: either the matches, or, when a pattern does not compile, why. */
+export interface TablePreviewResult {
+    matches: TablePreviewMatch[];
+    error?: string;
+}
+/**
+ * Runs a `table` extract's options against an already-read PDF (studio plan
+ * §3.4, issue #94's 5b: the live preview) — a pure function of the document
+ * and the options, so re-running it on every keystroke as the person edits
+ * `selector`/`until`/`columns` costs nothing: no re-fetch, no re-parse
+ * (`readPdf` already ran once, when `take-snapshot` captured the document).
+ *
+ * The workbook grid's live preview (issue #94's 5c) is `previewGridTable`,
+ * below: the same idea (a pure re-run of the options against the cached
+ * document), but its own result shape — a workbook table has no page, no
+ * column bands, no wrapped-row regrouping, so folding it into
+ * `TablePreviewMatch`/`TablePreviewResult` would leave most of those fields
+ * meaningless for a grid pick; a `GridTablePreviewMatch`/`GridTablePreviewResult`
+ * sibling reads honestly instead.
+ *
+ * @param document - The already-read PDF.
+ * @param options - The `table` extract's options, not yet compiled to `RegExp`.
+ * @returns Every match, each with the exact row indices to highlight — or `error` (and no matches) when a pattern is not a valid regular expression, expected while the person is still typing it.
+ */
+export declare function previewPdfTable(document: PdfDocument, options: TablePreviewOptions): TablePreviewResult;
+/**
+ * A `table` extract's own options for a workbook (CSV or spreadsheet), as
+ * the studio's grid canvas picks build them (issue #94's 5c) — mirrors
+ * `@opencraw/core`'s `GridTableQuery`, kept as strings (not yet compiled)
+ * the same way `TablePreviewOptions` does for PDF.
+ */
+export interface GridTablePreviewOptions {
+    /** Matches the names of the sheets to read; default every sheet. */
+    sheet?: string;
+    /** Matches the header row (the recipe's `selector`). */
+    header: string;
+    /** Matches the row that ends the table. */
+    until?: string;
+    /** Output key -> a pattern for that column's header cell. */
+    columns?: Record<string, string>;
+    /** How many rows the header spans; default 1. */
+    headerRows?: number;
+    /** Output keys whose empty cells take the value of the row above (a merged-group label pick, issue #94's 5c). */
+    fillDown?: string[];
+    /** Read hidden sheets and rows too. */
+    includeHidden?: boolean;
+}
+/** One table matched by a `table` extract's options against a workbook — mirrors `@opencraw/core`'s `GridTable`. */
+export interface GridTablePreviewMatch {
+    sheet: string;
+    title: string;
+    header: string[];
+    rows: Record<string, WorkbookCell>[];
+}
+/** What `previewGridTable` answers with: either the matches, or, when a pattern does not compile, why (mirrors `TablePreviewResult`). */
+export interface GridTablePreviewResult {
+    matches: GridTablePreviewMatch[];
+    error?: string;
+}
+/**
+ * Runs a `table` extract's options against an already-read workbook (studio
+ * plan §3.4, issue #94's 5c: the live preview) — a pure function of the
+ * document and the options, exactly like `previewPdfTable` above: no
+ * re-fetch, no re-parse (`csvWorkbook`/`readXlsxWorkbook` already ran once,
+ * when `take-snapshot` captured the document).
+ *
+ * @param document - The already-read workbook.
+ * @param options - The `table` extract's options, not yet compiled to `RegExp`.
+ * @returns Every matched table — or `error` (and no matches) when a pattern is not a valid regular expression, expected while the person is still typing it.
+ */
+export declare function previewGridTable(document: WorkbookDocument, options: GridTablePreviewOptions): GridTablePreviewResult;
+/**
+ * A `table` extract's own options for a deck, as the studio's deck canvas
+ * picks build them (issue #94's 5d) — mirrors `@opencraw/core`'s
+ * `DeckTableQuery`, kept as strings (not yet compiled) the same way
+ * `TablePreviewOptions`/`GridTablePreviewOptions` do for PDF/workbook.
+ */
+export interface DeckTablePreviewOptions {
+    /** Matches the titles of the slides to read; default every slide. */
+    slide?: string;
+    /** Read text boxes laid out as a table instead of native tables. */
+    shapes?: boolean;
+    /** With `shapes`: how a row's values sit against a box wrapped over several lines. */
+    align?: TableAlign;
+    /** Matches the header row (the recipe's `selector`). */
+    header: string;
+    /** Matches the row that ends the table. */
+    until?: string;
+    /** Output key -> a pattern for that column's header cell. */
+    columns?: Record<string, string>;
+    /** How many rows the header spans; default 1 (native tables only). */
+    headerRows?: number;
+    /** Output keys whose empty cells take the value of the row above (native tables only). */
+    fillDown?: string[];
+    /** Read hidden slides too. */
+    includeHidden?: boolean;
+}
+/** One table matched by a `table` extract's options against a deck — mirrors `@opencraw/core`'s `DeckTable`. */
+export interface DeckTablePreviewMatch {
+    slide: number;
+    slideTitle: string;
+    title: string;
+    header: string[];
+    rows: Record<string, WorkbookCell>[];
+}
+/** What `previewDeckTable` answers with: either the matches, or, when a pattern does not compile, why (mirrors `TablePreviewResult`/`GridTablePreviewResult`). */
+export interface DeckTablePreviewResult {
+    matches: DeckTablePreviewMatch[];
+    error?: string;
+}
+/**
+ * Runs a `table` extract's options against an already-read deck (studio plan
+ * §3.4, issue #94's 5d: the live preview) — a pure function of the document
+ * and the options, exactly like `previewPdfTable`/`previewGridTable` above:
+ * no re-fetch, no re-parse (`readPptxDeck` already ran once, when
+ * `take-snapshot` captured the document).
+ *
+ * @param document - The already-read deck.
+ * @param options - The `table` extract's options, not yet compiled to `RegExp`.
+ * @returns Every matched table — or `error` (and no matches) when a pattern is not a valid regular expression, expected while the person is still typing it.
+ */
+export declare function previewDeckTable(document: DeckDocument, options: DeckTablePreviewOptions): DeckTablePreviewResult;
+//# sourceMappingURL=table-preview.use-case.d.ts.map

package/dist/document-view/tree-view.mapper.d.ts

@@ -0,0 +1,47 @@
+import type { HttpBody } from '@opencraw/core';
+/** A JSON/XML value's shape, for the tree's icon and for deciding whether a node can generalise to a list. */
+export type TreeValueType = 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null' | 'element';
+/** One row of the document tree (studio plan §3.4, issue #94's 5a): a JSON/YAML value or an XML element/attribute. */
+export interface DocumentTreeNode {
+    /** A stable key for React lists: the node's own path. */
+    id: string;
+    /** The property name, array index or element/attribute name to show. */
+    label: string;
+    valueType: TreeValueType;
+    /** A short rendering of a leaf's value; absent for `object`/`array`/`element`. */
+    preview?: string;
+    /** This exact node's JSONPath (JSON/YAML documents only). */
+    jsonpath?: string;
+    /** This exact node's XPath (XML documents only). */
+    xpath?: string;
+    /**
+     * Set when this node is one item of an array (JSON) or one of several
+     * same-named siblings (XML): the path generalised to every item —
+     * `$.results[*]` instead of `$.results[2]` — and how many there are, so a
+     * pick can offer "the whole list" per studio plan §3.4.
+     */
+    listPath?: string;
+    listCount?: number;
+    /** XML only: the element's own attributes, name -> value (also reachable as child rows). */
+    attributes?: Record<string, string>;
+    children: DocumentTreeNode[];
+}
+/** What `document-tree` answers with: the parsed document as a tree, and (XML only) the namespace prefixes it declares or that reading synthesised for an unprefixed default namespace, offered so a pick's `extract` can reference them (studio plan §3.4). */
+export interface DocumentTreeView {
+    format: 'json' | 'xml';
+    root: DocumentTreeNode;
+    namespaces?: Record<string, string>;
+}
+/**
+ * Builds the document tree for `document-tree` (studio plan §3.4, issue
+ * #94's 5a) from the body `page-snapshot`'s `take-snapshot.use-case.ts`
+ * already fetched — no second read of the document.
+ *
+ * @param body - The parsed body (`HttpBody`); YAML and JSON Lines both
+ * arrive here already normalised to `{ kind: 'json' }` by `http.client.ts`.
+ * @returns The tree.
+ * @throws Error when `body`'s kind is not `json` or `xml` (PDF, workbook and
+ * deck documents get their own canvases — 5b/5c/5d, not this mapper).
+ */
+export declare function documentTreeView(body: HttpBody): DocumentTreeView;
+//# sourceMappingURL=tree-view.mapper.d.ts.map

package/dist/document-view/workbook-view.mapper.d.ts

@@ -0,0 +1,51 @@
+import type { WorkbookCell, WorkbookDocument } from '@opencraw/core';
+/** A cell's type, for the grid to show it as (issue #94's 5c): a number and a boolean keep their runtime type; a date is a string that reads as one of the ISO shapes `read-xlsx.client.ts` writes (a day, a moment, or both) — the workbook model itself has no separate date type (`WorkbookCell` is `string | number | boolean`), so this is the same "does it look like one" a person reading the cell would make. */
+export type GridCellType = 'string' | 'number' | 'boolean' | 'date';
+/** One cell, with the type the grid shows it as. */
+export interface GridCellView {
+    value: WorkbookCell;
+    type: GridCellType;
+}
+/** One merged range, 0-based and inclusive — mirrors `@opencraw/core`'s A1 references (`Sheet.merges`), already resolved to bounds so the grid can draw it as one cell (`rowSpan`/`colSpan`) instead of parsing `B10:B13` itself. */
+export interface GridMergeView {
+    ref: string;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+/** One sheet of the grid canvas (issue #94's 5c). */
+export interface GridSheetView {
+    name: string;
+    hidden: boolean;
+    /** 0-based row indices hidden in the sheet. */
+    hiddenRows: number[];
+    /** The widest row's own length, ragged rows included — for the grid to size its columns. */
+    columnCount: number;
+    rows: GridCellView[][];
+    merges: GridMergeView[];
+}
+/** What `grid-view` answers with (studio plan §3.4, issue #94's 5c): every sheet's cells, typed, with hidden sheets/rows marked and merged ranges resolved — the CSV/workbook grid's own view of the document, structurally the same idea as `pdf-view.mapper.ts`'s `PdfDocumentView`. */
+export interface WorkbookDocumentView {
+    sheets: GridSheetView[];
+    /** Present when the workbook came from a CSV — the detected (or overridden) delimiter and encoding, shown and overridable (issue #94's 5c). */
+    csv?: {
+        encoding: string;
+        delimiter: string;
+    };
+}
+/**
+ * Builds the grid canvas's view model (studio plan §3.4, issue #94's 5c) from
+ * an already-read `WorkbookDocument` (`take-snapshot`'s cached body — no
+ * second read of the file): every sheet's cells, typed, with hidden sheets
+ * and rows marked, and merged ranges resolved to bounds so the grid draws
+ * them as one cell. Table-specific diagnostics (the matched rows of the
+ * current `table` extract's options) are not here — they depend on the
+ * picks so far, so they come from `table-preview.use-case.ts`'s
+ * `previewGridTable` instead, computed live as those options change.
+ *
+ * @param document - The read workbook (a spreadsheet or a CSV).
+ * @returns The view.
+ */
+export declare function workbookDocumentView(document: WorkbookDocument): WorkbookDocumentView;
+//# sourceMappingURL=workbook-view.mapper.d.ts.map

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

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

package/dist/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/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/explain-why/why.use-case.d.ts

@@ -0,0 +1,26 @@
+import type { InputRecipe, OutputRecipe } from '@opencraw/core';
+import type { LastRunCache } from '../sample-run';
+import type { WhyTarget, WhyView } from '../studio-api';
+/**
+ * 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/flow-recording/action-to-step.mapper.d.ts

@@ -0,0 +1,16 @@
+import type { Step } from '@opencraw/core';
+import type { ResolvedAction } from './recorded-action.contract';
+/**
+ * Turns one resolved recorded action into the recipe step it reads as
+ * (issue #95's card sentences): `Click <selector>`, `Fill <selector> with
+ * <value>`, `Select <selector> = <value>`, `Press <key>`, `Scroll to
+ * bottom`. Pure: `recorder-session.use-case.ts` has already resolved the
+ * selector (`selector-inference`) and, for a secret field, already replaced
+ * `value` with its `{{env.NAME}}` placeholder (`secret-field.policy.ts`) —
+ * this mapper never sees, and so can never leak, a real secret value.
+ *
+ * @param action - The resolved action.
+ * @returns The step it becomes, or `undefined` for an action this mapper cannot place (a click/fill/select with no verified selector).
+ */
+export declare function actionToStep(action: ResolvedAction): Step | undefined;
+//# sourceMappingURL=action-to-step.mapper.d.ts.map

package/dist/flow-recording/index.d.ts

@@ -0,0 +1,13 @@
+export { openRecorderSession } from './recorder-session.use-case';
+export type { RecorderCallbacks, RecorderNote, RecorderSessionHandle, RecorderSessionOptions } from './recorder-session.use-case';
+export { rawActionSchema, recordedFieldSchema, recordedLinkSchema, RECORDED_ACTION_KINDS, UNSUPPORTED_REASONS } from './recorded-action.contract';
+export type { RawAction, RecordedActionKind, RecordedField, RecordedLink, ResolvedAction, UnsupportedReason } from './recorded-action.contract';
+export { actionToStep } from './action-to-step.mapper';
+export { isSecretField, secretEnvName, secretPlaceholder } from './secret-field.policy';
+export { looksLikeNextLink, paginateStepFor } from './next-link.policy';
+export type { PaginateStep } from './next-link.policy';
+export { insertWaitStep } from './wait-insertion.policy';
+export type { WaitContext, WaitStep } from './wait-insertion.policy';
+export { recorderScript } from './recorder-script.client';
+export type { Page } from 'playwright';
+//# sourceMappingURL=index.d.ts.map

package/dist/flow-recording/next-link.policy.d.ts

@@ -0,0 +1,27 @@
+import type { Step } from '@opencraw/core';
+import type { RecordedLink } from './recorded-action.contract';
+/** `paginate`'s own `next` shape, `selector` form only — the only one a recorded click can offer. */
+export type PaginateStep = Extract<Step, {
+    type: 'paginate';
+}>;
+/**
+ * Whether a clicked, navigating element looks like a "next" link (issue
+ * #95's exact heuristics): `rel="next"`, link text matching "next", or the
+ * resolved selector itself carrying `li.next a`/`a[aria-label=Next]`. Only
+ * meaningful for a click that navigated — the caller checks that first.
+ *
+ * @param link - The anchor's own `rel`/text/`aria-label`, as reported by `recorder-script.client.ts`.
+ * @param selector - The action's resolved selector (`selector-inference`'s own candidate).
+ * @returns Whether the studio should offer to turn this click into a `paginate` step.
+ */
+export declare function looksLikeNextLink(link: RecordedLink | undefined, selector: string | undefined): boolean;
+/**
+ * The `paginate` step a "next" link's selector offers (studio plan §3.1/#95:
+ * `For every page — click <selector>`), with an empty body: the studio
+ * offers this shape, the person fills in what runs on each page.
+ *
+ * @param selector - The next link's resolved, verified selector.
+ * @returns A `paginate` step, `next.selector` only.
+ */
+export declare function paginateStepFor(selector: string): PaginateStep;
+//# sourceMappingURL=next-link.policy.d.ts.map