@opencraw/studio 0.0.18 → 0.0.20

package/dist/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/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/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';
+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/flow-recording/secret-field.policy.d.ts

@@ -0,0 +1,33 @@
+import type { RecordedField } from './recorded-action.contract';
+/**
+ * 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/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/index.d.ts

@@ -1 +1,14 @@
-export * from "./src/index.js";
+export { main } from './main';
+export type { StudioMainOptions } from './main';
+export type { TrustedPlugins } from './trusted-plugins';
+export { startStudioServer } from './studio-server';
+export type { StudioServer, StudioServerOptions } from './studio-server';
+export { openWorkspace, saveRecipe, importDocument } from './recipe-workspace';
+export type { ImportedDocument } from './recipe-workspace';
+export { runSample, loadRecipePair } from './sample-run';
+export type { RecipePair, SampleRunCallbacks, SampleRunHandle, SampleRunRecord, SampleRunRejected, SampleRunResult, SampleStepSummary, SampleStoppedBy } from './sample-run';
+export { fetchStartPage } from './page-snapshot';
+export type { WhyFacts, WhyStepFact } from './explain-why';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, studioCommandSchema, importDocumentViewSchema, stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, loadedHooksSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, snapshotViewSchema, verifySelectorViewSchema, fieldPickSchema, inferSelectorViewSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, whyViewSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, 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';
+export type { SampleBudget, OpenWorkspaceCommand, ImportDocumentCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, RegionPreviewCommand, GridViewCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StudioCommand, ImportDocumentView, RegionPreviewMatchView, RegionPreviewView, StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, LoadedHooks, 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/main.d.ts

@@ -0,0 +1,18 @@
+import type { TrustedPlugins } from './trusted-plugins';
+/** What the caller of `main` decided beyond the command-line arguments. */
+export interface StudioMainOptions {
+    /** Hooks and plugins loaded from a file the person named at launch (`opencraw studio --hooks <file>`, issue #150). `main` never loads code itself. */
+    plugins?: TrustedPlugins;
+}
+/**
+ * Runs `opencraw-studio`: starts the server, opens `folder` (if given) as
+ * the workspace right away, and prints the URL with the token, the way
+ * `docs/research/recipe-studio.md` §2 shows it: `http://127.0.0.1:<port>/?token=…`.
+ * The process stays up (the server keeps the event loop alive) until it is
+ * interrupted (Ctrl+C).
+ *
+ * @param argv - Arguments after the program name: an optional recipe folder, `.` when omitted.
+ * @param options - What the caller loaded beforehand: the trusted plugins, if any.
+ */
+export declare function main(argv: readonly string[], options?: StudioMainOptions): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

package/dist/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/page-inspector/index.d.ts

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

package/dist/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/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/page-snapshot/fetch-start-page.use-case.d.ts

@@ -0,0 +1,20 @@
+import type { BrowserSessionConfig, InputRecipe } from '@opencraw/core';
+/**
+ * Fetches an input recipe's start page as the engine would see it: a fresh
+ * Playwright page in web mode, core's HTTP client in api mode. Returns plain
+ * text: the page's HTML, or a readable rendering of a non-HTML api response.
+ * No rewriting, no script stripping, no node ids yet: that is phase 2's
+ * `page-snapshot` proper (studio plan, #91). Provisional for phase 0 in two
+ * ways, both worth knowing before relying on it: it opens a bare page
+ * without running the recipe's own steps first, so a start point behind a
+ * `session.bootstrap` login shows what an anonymous visitor sees; and it
+ * launches a fresh browser or HTTP context per call, one page then closes
+ * it, rather than reusing whatever the last sample run had open.
+ *
+ * @param input - The input recipe; only `mode` and the first `start` point are used.
+ * @param browser - Browser launch settings for web mode (an executable path override, headless…).
+ * @returns The page's content as plain text.
+ * @throws Error when the recipe has no start point.
+ */
+export declare function fetchStartPage(input: InputRecipe, browser?: BrowserSessionConfig): Promise<string>;
+//# sourceMappingURL=fetch-start-page.use-case.d.ts.map

package/dist/page-snapshot/hidden-marks.algorithm.d.ts

@@ -0,0 +1,23 @@
+/** The attribute `hiddenMarksScript` stamps on an element hidden on the live page. */
+export declare const HIDDEN_ATTRIBUTE = "data-oc-hidden";
+/**
+ * The in-page script `take-snapshot.use-case.ts` runs with `page.evaluate`
+ * *before* `page.content()`, so a `display: none`/`visibility: hidden`/
+ * zero-size element carries `data-oc-hidden="1"` into the captured markup
+ * (studio plan §3.1, issue #91) — the only way to know an element was
+ * hidden on the live page, since a static parse of the HTML afterwards has
+ * no computed style to ask.
+ *
+ * Kept as a plain string, not a TypeScript function passed to
+ * `page.evaluate`, because it references `window`/`document` as globals: `AGENTS.md`'s
+ * "things that bit before" calls out that in-page functions must not do
+ * that (the repo's `isolated-functions` lint rule), and every existing
+ * `page.evaluate` call with real DOM logic in this codebase (see
+ * `packages/core/src/captcha/resolve-captcha.use-case.ts`) already uses
+ * this same string-template shape.
+ *
+ * @param attribute - The attribute to stamp; defaults to `HIDDEN_ATTRIBUTE` (parameterised for tests and for a future caller that wants a different name).
+ * @returns A self-invoking script, ready for `page.evaluate(hiddenMarksScript())`.
+ */
+export declare function hiddenMarksScript(attribute?: string): string;
+//# sourceMappingURL=hidden-marks.algorithm.d.ts.map

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

@@ -0,0 +1,13 @@
+export { fetchStartPage } from './fetch-start-page.use-case';
+export { takeSnapshot } from './take-snapshot.use-case';
+export type { SnapshotResult } from './take-snapshot.use-case';
+export { rewriteDocument } from './rewrite-document.mapper';
+export type { RewrittenDocument } from './rewrite-document.mapper';
+export { hiddenMarksScript, HIDDEN_ATTRIBUTE } from './hidden-marks.algorithm';
+export { createSnapshotCache, cachedSnapshot, putSnapshot, invalidateRecipe } from './snapshot.store';
+export type { SnapshotCache } from './snapshot.store';
+export { pdfBytes } from './pdf-bytes.use-case';
+export { rereadCsv } from './reread-csv.use-case';
+export type { CsvOverride } from './reread-csv.use-case';
+export { invalidateStaleSnapshot } from './invalidate-stale-snapshot.use-case';
+//# sourceMappingURL=index.d.ts.map

package/dist/page-snapshot/invalidate-stale-snapshot.use-case.d.ts

@@ -0,0 +1,12 @@
+import type { SnapshotCache } from './snapshot.store';
+/**
+ * Drops a recipe's cached snapshots when the edit about to be saved changes
+ * its start point (issue #159). Call it before the file is written: it reads
+ * the recipe as it is on disk now to compare.
+ *
+ * @param cache - The workspace's snapshot cache.
+ * @param file - The recipe file being saved.
+ * @param next - The recipe being saved.
+ */
+export declare function invalidateStaleSnapshot(cache: SnapshotCache, file: string, next: unknown): Promise<void>;
+//# sourceMappingURL=invalidate-stale-snapshot.use-case.d.ts.map

package/dist/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/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/page-snapshot/rewrite-document.mapper.d.ts

@@ -0,0 +1,27 @@
+export interface RewrittenDocument {
+    /** The document, ready for the sandboxed iframe: absolute URLs, a `<base>`, no `<script>`, forms disabled, `<meta http-equiv="refresh">` stripped, every element carrying a `data-oc-node` id. */
+    html: string;
+    /** How many elements were stamped with a node id — the same count `page-inspector` (phase 4) and the picker's match counts can be checked against. */
+    nodeCount: number;
+}
+/**
+ * Rewrites captured HTML into what the content pane's sandboxed iframe shows
+ * (studio plan §3.1, issue #91): every URL made absolute against `baseUrl`,
+ * a `<base>` injected, every `<script>` removed, forms disabled (`onsubmit`
+ * stripped, fields made read-only), `<meta http-equiv="refresh">` stripped
+ * (it would otherwise navigate the sandboxed frame on its own), and every
+ * element given a stable `data-oc-node` id, in document order, for the
+ * picker overlay and `selector-inference` to address specific nodes by.
+ *
+ * Purely a markup transform: it does not know whether an element is hidden
+ * on the live page (`display: none`, `visibility: hidden`, zero size) — in
+ * web mode that is `hidden-marks.algorithm.ts`'s job, run against the live
+ * page *before* this function ever sees the markup, so a `data-oc-hidden`
+ * attribute it wrote just survives serialisation untouched here.
+ *
+ * @param html - The captured document (`page.content()` in web mode, the fetched body in api mode).
+ * @param baseUrl - The page's own URL, for resolving relative links and as the `<base>`.
+ * @returns The rewritten document and how many elements it stamped.
+ */
+export declare function rewriteDocument(html: string, baseUrl: string): RewrittenDocument;
+//# sourceMappingURL=rewrite-document.mapper.d.ts.map

package/dist/page-snapshot/snapshot.store.d.ts

@@ -0,0 +1,14 @@
+import type { SnapshotResult } from './take-snapshot.use-case';
+/** A cache of the last snapshot taken per step path, so switching the selected step in the Steps outline does not always re-run the recipe (studio plan §3.1, issue #91). One per open recipe: key by `${recipeId}:${path}`. */
+export interface SnapshotCache {
+    entries: Map<string, SnapshotResult>;
+}
+/** @returns An empty cache, for a freshly opened workspace. */
+export declare function createSnapshotCache(): SnapshotCache;
+/** @returns The cached snapshot for `recipeId`/`path`, or `undefined` when none was taken yet. */
+export declare function cachedSnapshot(cache: SnapshotCache, recipeId: string, path: string): SnapshotResult | undefined;
+/** Records a freshly taken snapshot, replacing whatever was cached for the same recipe and step path. */
+export declare function putSnapshot(cache: SnapshotCache, recipeId: string, path: string, snapshot: SnapshotResult): void;
+/** Drops every cached snapshot of one recipe — called after a save, since the steps up to any path may now capture something different. */
+export declare function invalidateRecipe(cache: SnapshotCache, recipeId: string): void;
+//# sourceMappingURL=snapshot.store.d.ts.map

package/dist/page-snapshot/start-point.policy.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether an edit changes the page a recipe's start snapshot shows (issue
+ * #159): its start URLs, mode, session, vars, headers… anything but the steps
+ * and mapping that run after it. A pick only adds steps, so it keeps the
+ * snapshot already taken instead of fetching the page again.
+ *
+ * @param before - The recipe as last saved (`undefined` when there was none).
+ * @param after - The recipe being saved.
+ * @returns `true` when the cached start snapshot may now be out of date.
+ */
+export declare function startPointChanged(before: unknown, after: unknown): boolean;
+//# sourceMappingURL=start-point.policy.d.ts.map