@opencraw/studio 0.0.7 → 0.0.8

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

@@ -0,0 +1,70 @@
+import type { DeckDocument } from '@opencraw/core';
+import type { GridSheetView } from './workbook-view.mapper.js';
+/** 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/src/document-view/index.d.ts

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

package/dist/src/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/src/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/src/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/src/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/src/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.js';
+/**
+ * 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/src/flow-recording/index.d.ts

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

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

@@ -0,0 +1,27 @@
+import type { Step } from '@opencraw/core';
+import type { RecordedLink } from './recorded-action.contract.js';
+/** `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

package/dist/src/flow-recording/recorded-action.contract.d.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+/** The kinds of user action the in-page recorder script (`recorder-script.client.ts`) reports. */
+export declare const RECORDED_ACTION_KINDS: readonly ["click", "fill", "select", "keypress", "scroll"];
+export type RecordedActionKind = typeof RECORDED_ACTION_KINDS[number];
+/** Why a report was refused before it became an action: out of this phase's scope (issue #95). */
+export declare const UNSUPPORTED_REASONS: readonly ["iframe", "shadow-dom"];
+export type UnsupportedReason = typeof UNSUPPORTED_REASONS[number];
+/**
+ * The type/name/id of the form field a `fill`/`select` landed on, exactly as
+ * the live DOM reports them — `secret-field.policy.ts`'s only input. Never
+ * carries the field's value: that travels separately, on the action itself.
+ */
+export declare const recordedFieldSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RecordedField = z.infer<typeof recordedFieldSchema>;
+/** What `next-link.policy.ts` needs off a clicked anchor: never the whole element. */
+export declare const recordedLinkSchema: z.ZodObject<{
+    rel: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    ariaLabel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RecordedLink = z.infer<typeof recordedLinkSchema>;
+/**
+ * The wire shape of one action as `recorder-script.client.ts` reports it,
+ * over the Playwright binding `recorder-session.use-case.ts` exposes: the
+ * `data-oc-node` id of the element involved (`selector-inference`'s own
+ * marker attribute, `@opencraw/core`'s `NODE_ID_ATTRIBUTE`), never a
+ * selector — the studio, not the page, decides that (studio plan §3.2,
+ * issue #95). Never the field's real value when it might be a secret: the
+ * script itself does not know which fields are secret (`secret-field.policy.ts`
+ * runs server-side, once a `RecordedField` is known), but nothing here
+ * *requires* a value to be typed out either way — `recorder-session.use-case.ts`
+ * discards it the moment a secret is detected.
+ *
+ * `html` is the document's own markup, captured by the script itself at the
+ * moment of the event (`document.documentElement.outerHTML`), not fetched
+ * again afterwards: a click that navigates can leave the page before a
+ * later `page.content()` call would resolve, reading the *next* page's
+ * markup instead of the one the click actually happened on. Capturing it
+ * synchronously, in the same event the node id is stamped in, means the
+ * selector is always resolved against the exact document the action
+ * happened on — still "verified against the page" (issue #95), just without
+ * the race a second round trip would risk.
+ */
+export declare const rawActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"click">;
+    nodeId: z.ZodString;
+    html: z.ZodString;
+    link: z.ZodOptional<z.ZodObject<{
+        rel: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        ariaLabel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"fill">;
+    nodeId: z.ZodString;
+    html: z.ZodString;
+    value: z.ZodString;
+    field: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"select">;
+    nodeId: z.ZodString;
+    html: z.ZodString;
+    value: z.ZodString;
+    field: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"keypress">;
+    nodeId: z.ZodOptional<z.ZodString>;
+    html: z.ZodOptional<z.ZodString>;
+    key: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"scroll">;
+    to: z.ZodLiteral<"bottom">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"unsupported">;
+    reason: z.ZodEnum<{
+        iframe: "iframe";
+        "shadow-dom": "shadow-dom";
+    }>;
+}, z.core.$strip>], "kind">;
+export type RawAction = z.infer<typeof rawActionSchema>;
+/**
+ * One action once `recorder-session.use-case.ts` has resolved it against the
+ * live page: `selector` comes from the phase 2 generator
+ * (`selector-inference`'s `candidatesFor`/`rankCandidates`), verified
+ * against the page it was recorded on, per issue #95. `value` already holds
+ * a `{{env.NAME}}` placeholder, never a real secret, once `secret-field.policy.ts`
+ * has flagged the field. `navigated` is set when the action's page changed
+ * (a click or a key press that submitted a form/followed a link).
+ */
+export interface ResolvedAction {
+    kind: RecordedActionKind;
+    selector?: string;
+    value?: string;
+    key?: string;
+    field?: RecordedField;
+    link?: RecordedLink;
+    navigated?: {
+        url: string;
+        status?: number;
+    };
+}
+//# sourceMappingURL=recorded-action.contract.d.ts.map

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