@opencraw/studio 0.0.18 → 0.0.19

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

@@ -0,0 +1,60 @@
+import type { BodyKind, BrowserSessionConfig, HookMap, HttpBody, InputRecipe } from '@opencraw/core';
+export interface SnapshotResult {
+    /** The rewritten document, ready for the content pane's sandboxed iframe. */
+    html: string;
+    /** How many elements carry a `data-oc-node` id. */
+    nodeCount: number;
+    /** The page's own URL, used to resolve every relative URL and as the `<base>`. */
+    baseUrl: string;
+    /**
+     * The document as captured, before `rewriteDocument` strips every
+     * `<script>` for the sandboxed iframe — server-side only, never sent to the
+     * UI (`studio-api`'s `SnapshotView` does not carry it): `page-inspector`'s
+     * `page-data.algorithm.ts` (issue #93) needs the JSON-LD, inline state and
+     * `application/json` blocks a script tag can hold, which the display
+     * snapshot no longer has by the time it is cached.
+     */
+    rawHtml: string;
+    /**
+     * The format `http.client.ts` read the body as (api mode only; `undefined`
+     * in web mode, whose document is always HTML) — what the content pane
+     * uses to pick a canvas: `document-view`'s tree/pdf/grid/deck for
+     * `json`/`yaml`/`xml`/`pdf`/`csv`/`xlsx`/`pptx`, the snapshot iframe for
+     * `html` (and `docx`/`markdown`, which `http.client.ts` already turns into
+     * HTML), studio plan §3.4, issue #94.
+     */
+    format?: BodyKind;
+    /**
+     * The parsed body itself (api mode only), for `document-view`'s mappers to
+     * read — server-side only, never sent to the UI as-is (`studio-api`'s
+     * `SnapshotView` carries only `format`; a canvas asks for its own view
+     * model with a follow-up command, `inspect-page`'s own pattern).
+     */
+    body?: HttpBody;
+}
+/**
+ * Captures the snapshot the content pane shows (studio plan §3.1, issue
+ * #91): runs the recipe up to `stepPath`, serialises the document, marks
+ * hidden elements in web mode, and hands it to `rewrite-document.mapper.ts`
+ * for display.
+ *
+ * `stepPath` is accepted (and cached against, by `snapshot.store.ts`) for
+ * the API the UI needs — one snapshot per selected step — but v1 only
+ * actually *captures* `"start"`: the first `start` point, before any step
+ * of the recipe has run, the same reach `fetch-start-page.use-case.ts` (phase
+ * 0) already had. Snapshotting mid-recipe (after an arbitrary later step)
+ * needs a "stop the crawl after step X and hand back the live page/document"
+ * hook in `crawl-execution` that does not exist yet; building one was out of
+ * this phase's budget (see this phase's final report for the tradeoff this
+ * was weighed against). Any other `stepPath` throws, clearly, rather than
+ * silently returning the start page under a misleading label.
+ *
+ * @param input - The input recipe; only `mode` and the first `start` point are used.
+ * @param stepPath - The step to snapshot after, e.g. `"start"` or `"steps.2"` (`scope-outline`'s path format).
+ * @param browser - Browser launch settings for web mode.
+ * @param hooks - The hooks a login bootstrap may call (the ones Studio was started with, issue #150).
+ * @returns The rewritten snapshot.
+ * @throws Error when the recipe has no start point, or `stepPath` is not `"start"`.
+ */
+export declare function takeSnapshot(input: InputRecipe, stepPath: string, browser?: BrowserSessionConfig, hooks?: HookMap): Promise<SnapshotResult>;
+//# sourceMappingURL=take-snapshot.use-case.d.ts.map

package/dist/recipe-workspace/import-document.use-case.d.ts

@@ -0,0 +1,22 @@
+export interface ImportedDocument {
+    /** The copy's path on disk, inside `folder`. */
+    path: string;
+    /** The copy as a `file:` URL: what the recipe's `start.url` becomes. */
+    url: string;
+}
+/**
+ * Copies a document into a workspace folder, so a recipe can read it with a
+ * `file:` URL the same way a run would read any downloaded file (core's
+ * `HttpClient` handles `file:` itself). The folder is created when missing,
+ * so dropping a file is also a way to start a workspace. A name already in
+ * the folder is never overwritten: the copy gets the next free numbered
+ * name (`report-2.pdf`), and the returned `path`/`url` say which.
+ *
+ * @param folder - The workspace folder; created (recursively) when it does not exist.
+ * @param name - The file's own name, no directories: the copy keeps it, extension included.
+ * @param bytes - The file's content.
+ * @returns Where the copy landed.
+ * @throws Error when `name` is not a plain file name, or the folder already holds too many same-named copies.
+ */
+export declare function importDocument(folder: string, name: string, bytes: Uint8Array): Promise<ImportedDocument>;
+//# sourceMappingURL=import-document.use-case.d.ts.map

package/dist/recipe-workspace/index.d.ts

@@ -0,0 +1,5 @@
+export { openWorkspace } from './open-workspace.use-case';
+export { saveRecipe } from './save-recipe.use-case';
+export { importDocument } from './import-document.use-case';
+export type { ImportedDocument } from './import-document.use-case';
+//# sourceMappingURL=index.d.ts.map

package/dist/recipe-workspace/open-workspace.use-case.d.ts

@@ -0,0 +1,15 @@
+import type { WorkspaceView } from '../studio-api';
+/**
+ * Opens a recipe folder: every `.json`/`.jsonl` recipe directly inside it
+ * (core's own directory reading, so relative `file:` URLs resolve the same
+ * way a real run would), parsed and, for each output recipe found, bound to
+ * the input recipes that name it. Nothing throws for a bad recipe or a
+ * recipe that does not bind: every problem is reported on its file with the
+ * JSON path core already computes, exactly as `opencraw validate` prints it.
+ *
+ * @param folder - The workspace folder.
+ * @returns Every recipe file found, each with its validation and binding issues.
+ * @throws Error when the folder does not exist or cannot be read.
+ */
+export declare function openWorkspace(folder: string): Promise<WorkspaceView>;
+//# sourceMappingURL=open-workspace.use-case.d.ts.map

package/dist/recipe-workspace/save-recipe.use-case.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Writes a recipe back to its file: pretty JSON, a 2-space indent, a
+ * trailing newline. Phase 0 takes the JSON tab's whole parsed object rather
+ * than a patch, so this is a full replacement, not a splice: loading a file
+ * the studio has not touched and saving it again keeps every key, value and
+ * key order (`JSON.parse` preserves insertion order, and `JSON.stringify`
+ * writes it back), but not necessarily the file's exact original formatting
+ * (alignment, how arrays wrap, a trailing comment). Byte-identical
+ * round-trip for a hand-formatted file is future work; see this file's test
+ * for what is guaranteed today.
+ *
+ * The text goes to a sibling temporary file that is then renamed over the
+ * recipe, so a reader (or a crash) never sees a half-written file. Windows
+ * refuses a rename over a file another process has open (`EPERM`, `EBUSY`),
+ * so the rename is retried briefly and then gives way to a plain write.
+ *
+ * @param path - The recipe file to write.
+ * @param recipe - The whole recipe object.
+ */
+export declare function saveRecipe(path: string, recipe: unknown): Promise<void>;
+//# sourceMappingURL=save-recipe.use-case.d.ts.map

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

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

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

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

package/dist/sample-run/load-recipe-pair.use-case.d.ts

@@ -0,0 +1,18 @@
+import type { InputRecipe, OutputRecipe } from '@opencraw/core';
+/** An input recipe and the output recipe it names, both parsed. */
+export interface RecipePair {
+    input: InputRecipe;
+    output: OutputRecipe;
+}
+/**
+ * Finds and parses one input recipe of a workspace folder, and the output
+ * recipe it names.
+ *
+ * @param folder - The workspace folder.
+ * @param recipeId - The input recipe's id.
+ * @returns The parsed pair.
+ * @throws RecipeValidationError when either recipe does not parse.
+ * @throws Error when the input or its output is not in the folder.
+ */
+export declare function loadRecipePair(folder: string, recipeId: string): Promise<RecipePair>;
+//# sourceMappingURL=load-recipe-pair.use-case.d.ts.map

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

@@ -0,0 +1,40 @@
+import type { BrowserSessionConfig } from '@opencraw/core';
+import type { SampleBudget } from '../studio-api';
+import type { TrustedPlugins } from '../trusted-plugins';
+import type { SampleRunRecord, SampleRunRejected, SampleRunResult } from './sample-run-record.contract';
+/** Where trace lines and records go as a sample run proceeds. */
+export interface SampleRunCallbacks {
+    onTraceLine: (line: string) => void;
+    onRecord: (record: SampleRunRecord) => void;
+    /** A record was rejected (a field's `skip-record` missing/coercion policy); optional, most callers only need the final `rejectedRecords` list. */
+    onRejected?: (rejected: SampleRunRejected) => void;
+}
+/** A sample run in progress. */
+export interface SampleRunHandle {
+    /** Closes the crawler; the run's `result` still resolves, typically with an error from the interrupted request. */
+    stop: () => Promise<void>;
+    result: Promise<SampleRunResult>;
+}
+/**
+ * Runs one input recipe of a workspace folder as a sample: `debug: true` (so
+ * each `record:emit` carries its scope snapshot and mapping trace, and each
+ * `record:reject` its scope), an in-memory sink, and `budget` as the
+ * crawler's `sample` (`@opencraw/core`'s `CrawlOptions.sample`, #89). Every
+ * engine event becomes a trace line with the same `traceLine` formatter the
+ * cli's `--trace` uses; every emitted record reaches `callbacks.onRecord` as
+ * it happens, not only in the final result. Step events (`step:start`,
+ * `step:skip`, `step:retry`) are aggregated by path into `result.steps`, so
+ * `explain-why` (#92) can later say whether the step that bound a mapping's
+ * source id ran, was skipped, or retried — without a second run.
+ *
+ * @param folder - The workspace folder the recipe lives in.
+ * @param recipeId - The input recipe to run.
+ * @param budget - The sample budget; unset runs the recipe to completion (still capped by its own `limits`).
+ * @param callbacks - Where trace lines and records go as the run proceeds.
+ * @param browser - Browser launch settings for a web-mode recipe (an executable path override, headless…); the server-wide setting `studio-http.use-case.ts`'s `StudioServerOptions.browser` carries in, e.g. `OPENCRAW_CHROMIUM` in a sandbox with no full Playwright install.
+ * @param plugins - Hooks, access plugins and captcha solvers the person started Studio with (`--hooks`, issue #150); none when it was started without.
+ * @returns A handle: `stop` closes the crawler cleanly, `result` resolves when the run ends.
+ * @throws RecipeValidationError, RecipeBindingError, Error when the recipe or its output cannot be loaded or bound.
+ */
+export declare function runSample(folder: string, recipeId: string, budget: SampleBudget | undefined, callbacks: SampleRunCallbacks, browser?: BrowserSessionConfig, plugins?: TrustedPlugins): Promise<SampleRunHandle>;
+//# sourceMappingURL=run-sample.use-case.d.ts.map

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

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

package/dist/scope-outline/card-sentence.mapper.d.ts

@@ -0,0 +1,18 @@
+import type { SentencePart } from './outline.model';
+export interface StepSentence {
+    parts: SentencePart[];
+    /** `true` when this is a fallback (an unrecognised type, or one of `ALWAYS_CUSTOM`): the UI shows `step`'s raw JSON instead of trusting `parts` alone. */
+    custom: boolean;
+}
+/**
+ * Turns one step's raw JSON into its sentence parts (word/pill/code), the
+ * way the plan doc's examples read: *Go to…*, *Read… from…*, *For each… in…
+ * → one record*, and so on. Never throws: a step type this cannot read
+ * becomes a short, honest fallback with `custom: true`, so the outline never
+ * drops a step for looking unfamiliar.
+ *
+ * @param step - A step's raw JSON (its `type` and whatever fields it has).
+ * @returns The sentence parts, and whether they are a real reading or a fallback.
+ */
+export declare function cardSentence(step: Record<string, unknown>): StepSentence;
+//# sourceMappingURL=card-sentence.mapper.d.ts.map

package/dist/scope-outline/index.d.ts

@@ -0,0 +1,8 @@
+export { BRACKET_STEP_TYPES, isBracket, isBracketStepType } from './outline.model';
+export type { OutlineBracket, OutlineCard, OutlineNode, RecipeOutline, SentencePart, BracketStepType } from './outline.model';
+export { cardSentence } from './card-sentence.mapper';
+export type { StepSentence } from './card-sentence.mapper';
+export { recipeToOutline } from './recipe-to-outline.mapper';
+export { outlineToRecipe } from './outline-to-recipe.mapper';
+export { scopeAtPath } from './scope-at-path.algorithm';
+//# sourceMappingURL=index.d.ts.map

package/dist/scope-outline/outline-to-recipe.mapper.d.ts

@@ -0,0 +1,17 @@
+import type { RecipeOutline } from './outline.model';
+/**
+ * Rebuilds a recipe from its outline: `recipe`'s keys, in their original
+ * order, with `steps` (when the recipe had one) replaced by the outline's
+ * (possibly edited) step tree. A card's own raw `step` is used as-is; a
+ * bracket's `step` supplies every field but `steps`/`else`, which come from
+ * `children`/`elseChildren` instead, put back at the position `step` itself
+ * held that key at (or appended, for a bracket a `+` menu just added, whose
+ * `step` never had one) — this, together with `recipe-to-outline.mapper.ts`
+ * always keeping the step's whole original object, is what makes
+ * `recipe → outline → recipe` preserve every key and its order.
+ *
+ * @param outline - An outline, from `recipe-to-outline.mapper.ts` or edited by the UI.
+ * @returns The recipe's plain JSON, ready for `save-recipe`.
+ */
+export declare function outlineToRecipe(outline: RecipeOutline): Record<string, unknown>;
+//# sourceMappingURL=outline-to-recipe.mapper.d.ts.map

package/dist/scope-outline/outline.model.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The outline model: an `InputRecipe`'s `steps` (and only `steps`; the rest
+ * of the recipe passes through untouched, see `recipe-to-outline.mapper.ts`)
+ * read as a tree of cards and brackets instead of raw JSON.
+ *
+ * A **card** is one step that reads as a sentence (`sentence`, built by
+ * `card-sentence.mapper.ts`). A **bracket** is a container step (`forEach`,
+ * `paginate`, `if`) whose body is itself a list of cards/brackets: the
+ * indentation the plan doc describes is this nesting, not a separate layout
+ * concept. Both kinds carry `step`, the step's own raw JSON exactly as
+ * parsed (every key, in its original order): `outline-to-recipe.mapper.ts`
+ * rebuilds the recipe from it, substituting only the (possibly edited)
+ * `children`/`elseChildren` for whatever `steps`/`else` value `step` itself
+ * holds, so an edit to one field never disturbs another's position or a
+ * step type this outline cannot make sense of.
+ */
+/** One piece of a card's sentence: plain wording, a bound id (a "pill"), or a literal (a selector, a template, a value) shown as code. */
+export interface SentencePart {
+    kind: 'word' | 'pill' | 'code';
+    text: string;
+}
+/** The step types the outline renders as a bracket: their body is nested steps, not a single value. */
+export declare const BRACKET_STEP_TYPES: readonly ['forEach', 'paginate', 'if'];
+export type BracketStepType = typeof BRACKET_STEP_TYPES[number];
+interface OutlineNodeBase {
+    /** The step's JSON path in the recipe, e.g. `steps.3.steps.1`. */
+    path: string;
+    /** The step's own `type`, or `'unknown'` when `step` has none. */
+    stepType: string;
+    sentence: SentencePart[];
+    /** The step's raw JSON, exactly as parsed: never dropped, always editable as JSON. */
+    step: Record<string, unknown>;
+}
+/** One step the outline could not, or chose not to, read as a bracket: a leaf card. */
+export interface OutlineCard extends OutlineNodeBase {
+    kind: 'card';
+    /** `true` when `card-sentence.mapper.ts` could not build a real sentence: the UI shows `step` as raw, editable JSON instead. */
+    custom: boolean;
+}
+/** A container step (`forEach`, `paginate`, `if`): its body nested one level in. */
+export interface OutlineBracket extends OutlineNodeBase {
+    kind: 'bracket';
+    stepType: BracketStepType;
+    children: OutlineNode[];
+    /** `if` only: the `else` branch, when the step has one. */
+    elseChildren?: OutlineNode[];
+}
+export type OutlineNode = OutlineCard | OutlineBracket;
+/** A recipe read as an outline: `recipe` is everything but the derived view of `steps`, kept so the mapper back can restore it untouched. */
+export interface RecipeOutline {
+    recipe: Record<string, unknown>;
+    steps: OutlineNode[];
+}
+export declare function isBracket(node: OutlineNode): node is OutlineBracket;
+export declare function isBracketStepType(type: string): type is BracketStepType;
+export {};
+//# sourceMappingURL=outline.model.d.ts.map

package/dist/scope-outline/recipe-to-outline.mapper.d.ts

@@ -0,0 +1,14 @@
+import type { RecipeOutline } from './outline.model';
+/**
+ * Reads a recipe's `steps` as an outline. Works on whatever JSON parsed
+ * (not a validated `InputRecipe`): a recipe mid-edit in the JSON tab may be
+ * missing fields or have the wrong shape, and the outline still has to
+ * render something rather than crash the tab. Anything that is not a
+ * well-formed step becomes a custom card holding what was there; anything
+ * that is not an object at the top becomes an outline with no steps.
+ *
+ * @param content - The recipe's parsed JSON (the JSON tab's own `JSON.parse` of its text).
+ * @returns The outline: the untouched top-level record plus the step tree.
+ */
+export declare function recipeToOutline(content: unknown): RecipeOutline;
+//# sourceMappingURL=recipe-to-outline.mapper.d.ts.map

package/dist/scope-outline/scope-at-path.algorithm.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The ids visible at a step path: the built-ins (`page`, `start`, `vars`),
+ * every id bound above it on the same path, and the `as`/`next.as` name of
+ * every loop it sits inside. This is core's own binding rule
+ * (`bindingsAt`, `recipe-loading/recipe-binding.validator.ts`): the walk
+ * that decides what a `{{ }}` template, `from` or `over` can name is the one
+ * `opencraw validate` already runs, not a copy of it.
+ *
+ * `content` is the recipe's raw parsed JSON, the same loosely-typed value
+ * `recipe-to-outline.mapper.ts` reads: a recipe mid-edit may not parse as a
+ * valid `InputRecipe` (a missing `mode`, a step with the wrong shape), and
+ * this never throws for that — it falls back to just the built-ins.
+ *
+ * @param content - The recipe's parsed JSON.
+ * @param path - A step's JSON path, e.g. `steps.3.steps.1`.
+ * @returns The ids in scope at that path, `page`/`start`/`vars` first.
+ */
+export declare function scopeAtPath(content: unknown, path: string): string[];
+//# sourceMappingURL=scope-at-path.algorithm.d.ts.map

package/dist/selector-inference/class-token.policy.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Which class tokens are worth building a selector on. A hand-authored class
+ * (`product_pod`, `price_color`) survives a rebuild; a generated one
+ * (a content hash, a CSS-module suffix, a styled-components token) does not,
+ * so a candidate built on it looks fine on the snapshot it was picked from
+ * and breaks on the very next deploy. This is the "generated/hashed class
+ * names" tradeoff issue #91 calls out explicitly: the heuristics below are a
+ * reasoned judgement call, not a guarantee — see the doc comments on each
+ * pattern for what real-world tool it targets.
+ */
+/**
+ * Whether a class token looks hand-authored and safe to build a selector on.
+ *
+ * @param token - One class, no surrounding whitespace.
+ * @returns `false` for anything matching a known generated-class shape.
+ */
+export declare function isStableClassToken(token: string): boolean;
+/**
+ * The subset of `tokens` worth ranking a selector candidate on, order kept.
+ *
+ * @param tokens - An element's class list.
+ * @returns Only the stable tokens.
+ */
+export declare function stableClasses(tokens: readonly string[]): string[];
+/**
+ * Whether two class lists describe "the same kind of element" for list
+ * inference: same stable classes, generated tokens (which often differ
+ * per-instance, e.g. a React `key`-derived class) ignored on both sides.
+ *
+ * @param a - One element's classes.
+ * @param b - Another element's classes.
+ * @returns Whether their stable class sets are equal, order ignored.
+ */
+export declare function sameClassSignature(a: readonly string[], b: readonly string[]): boolean;
+//# sourceMappingURL=class-token.policy.d.ts.map

package/dist/selector-inference/dom-path.model.d.ts

@@ -0,0 +1,73 @@
+import type { AnyNode } from 'domhandler';
+import type { Cheerio, CheerioAPI } from 'cheerio';
+/**
+ * One level of a node's ancestry, root first: the element's own shape (tag,
+ * id, classes, attributes) plus where it sits among its same-tag siblings.
+ * Built over parsed HTML (cheerio), never a live DOM: the studio infers
+ * selectors from the snapshot the server captured, not from a browser
+ * window in the UI process (studio plan §3.1/§3.2, issue #91).
+ */
+export interface DomPathLevel {
+    tag: string;
+    id?: string;
+    classes: string[];
+    attrs: Record<string, string>;
+    /** 1-based position among same-tag siblings under the same parent (an `nth-of-type` index). */
+    index: number;
+    /** How many same-tag siblings share the parent, `index` included. */
+    siblingCount: number;
+}
+/** A node's whole ancestry, root first, the node itself last. */
+export type DomPath = DomPathLevel[];
+/**
+ * The path from the document root to `node`, one level per ancestor. Two
+ * elements that share an ancestor produce identical levels up to that
+ * ancestor and diverge exactly where their parents stop being the same node
+ * — `list-inference.algorithm.ts` leans on that to find the nearest pair of
+ * siblings two picks belong to, without ever touching cheerio again.
+ *
+ * @param $ - The parsed document.
+ * @param node - The element to describe.
+ * @returns The path, root first.
+ */
+export declare function domPathOf($: CheerioAPI, node: Cheerio<AnyNode>): DomPath;
+/**
+ * Whether `id` looks handed by a framework (`react-`, a CSS-module or a
+ * `radix-`/`mui-` autogenerated one) rather than by the site's own markup —
+ * `class-token.policy.ts` has the equivalent check for class tokens, kept
+ * separate because ids and classes are ranked at different tiers.
+ */
+export declare function isStableId(id: string): boolean;
+/**
+ * Whether `path` failed to reach the real document root. `domPathOf` walks
+ * up through cheerio's own `.parent()`, which (matching real DOM semantics)
+ * never crosses from a `<template>`'s content into the light DOM outside
+ * it — a `<template shadowrootmode>` is exactly declarative shadow DOM, the
+ * only shadow-DOM shape that can show up in static, server-captured markup
+ * at all (imperative `attachShadow()` content never serialises into
+ * `page.content()`/a fetched response in the first place, so that case
+ * cannot reach this slice and needs no separate detection). A path whose
+ * first level is not `html` was cut short at exactly this kind of boundary:
+ * v1 does not pierce it, so callers report a clear "shadow DOM is not
+ * supported" error instead of building ancestor-based candidates over a
+ * chain that stops partway up.
+ */
+export declare function crossesShadowRoot(path: DomPath): boolean;
+/** Parses `html` and returns cheerio's API, for callers that need more than one path from the same document. */
+export declare function parseDocument(html: string): CheerioAPI;
+/**
+ * The path to the element the snapshot stamped with `nodeId` (its
+ * `data-oc-node` attribute — `@opencraw/core`'s `NODE_ID_ATTRIBUTE`,
+ * `packages/studio/src/page-snapshot/rewrite-document.mapper.ts`). This is
+ * how a click in the content pane's iframe — which only ever needs to read
+ * that one attribute off the element the user clicked — turns into
+ * something `selector-inference`'s other algorithms can work with, without
+ * the browser-side picker script needing to know anything about ancestry,
+ * classes or candidate ranking itself.
+ *
+ * @param html - The snapshot document (already stamped with node ids).
+ * @param nodeId - The `data-oc-node` value to find.
+ * @returns The node's path, or `undefined` when no element carries that id.
+ */
+export declare function pathToNode(html: string, nodeId: string): DomPath | undefined;
+//# sourceMappingURL=dom-path.model.d.ts.map

package/dist/selector-inference/index.d.ts

@@ -0,0 +1,12 @@
+export { domPathOf, isStableId, crossesShadowRoot, parseDocument, pathToNode } from './dom-path.model';
+export type { DomPath, DomPathLevel } from './dom-path.model';
+export { takeKindFor } from './take-kind.policy';
+export { isStableClassToken, stableClasses, sameClassSignature } from './class-token.policy';
+export { ShadowDomUnsupportedError } from './shadow-dom.error';
+export { candidatesFor } from './selector-candidates.algorithm';
+export type { SelectorCandidate, CandidateTier } from './selector-candidates.algorithm';
+export { rankCandidates, bestCandidate } from './selector-ranking.policy';
+export type { RankedCandidate } from './selector-ranking.policy';
+export { inferList } from './list-inference.algorithm';
+export type { ListInferenceResult } from './list-inference.algorithm';
+//# sourceMappingURL=index.d.ts.map

package/dist/selector-inference/list-inference.algorithm.d.ts

@@ -0,0 +1,43 @@
+import type { DomPath } from './dom-path.model';
+export interface ListInferenceResult {
+    /**
+     * The item's shape, generalised across both picks (root first, item
+     * last): only the tag, the stable classes and the attributes the two
+     * picked items actually share survive the merge. An id or a `data-id`
+     * that differs per item (the ordinary case) is dropped here on purpose —
+     * built into a selector it would match one item and silently miss every
+     * other, which is a shifted-field-shaped bug in its own right even though
+     * it is not the one issue #91 names.
+     */
+    itemPath: DomPath;
+    /** The field's shape from the item down to the click, generalised the same way as `itemPath`, for a selector that reads `from` the item and still works on every item, not just the one it was picked from. */
+    fieldPath: DomPath;
+    /** The concrete path of the first click, item-relative (index 0 = the item), kept for provenance (e.g. the value the pick actually read). */
+    fieldPathA: DomPath;
+    /** Same, for the second click. */
+    fieldPathB: DomPath;
+}
+/**
+ * Infers "these two picks are the same field on two items of a list" from
+ * two node paths, by walking up from both to the nearest ancestors that are
+ * real siblings (the same parent) with the same tag and stable-class
+ * signature — studio plan §3.2, issue #91. That ancestor is the item; the
+ * remainder of each path is the field, relative to it.
+ *
+ * Because a `DomPath` is built root-down (`dom-path.model.ts`), two paths
+ * from the same document are byte-for-byte identical up to their real
+ * common ancestor and diverge exactly at its differing children — so the
+ * *first* level where they differ is always the nearest-sibling test point;
+ * there is no need to look further down. This also makes the "wrapper trap"
+ * (an extra single-child element around each item) resolve itself: a
+ * wrapper's own instances are never one another's siblings, only the
+ * genuine repeating element is, so the walk naturally lands there instead of
+ * on the wrapper (see the wrapper-trap fixture in this slice's tests).
+ *
+ * @param pathA - The first click's path.
+ * @param pathB - The second click's path.
+ * @returns The item and field shapes (generalised) plus each pick's raw path, or `null` when the two picks are not on a coherent list (different branches entirely, the same node twice, or one path nested inside the other).
+ * @throws ShadowDomUnsupportedError when either path crosses a declarative shadow root.
+ */
+export declare function inferList(pathA: DomPath, pathB: DomPath): ListInferenceResult | null;
+//# sourceMappingURL=list-inference.algorithm.d.ts.map

package/dist/selector-inference/selector-candidates.algorithm.d.ts

@@ -0,0 +1,22 @@
+import type { DomPath } from './dom-path.model';
+/** The engine only ever runs `css` selectors from the studio (studio plan §3.2); xpath is a separate, text-only fallback the UI builds by hand. */
+export type CandidateTier = 'id' | 'data-attr' | 'class' | 'structure' | 'position';
+export interface SelectorCandidate {
+    selector: string;
+    tier: CandidateTier;
+}
+/**
+ * Every selector candidate worth trying for the last node of `path`, ranked
+ * best-first: `id` > stable `data-*`/`itemprop` attributes > stable class
+ * tokens > ancestor structure (`parent > tag`) > position (`nth-of-type`) as
+ * a last resort (issue #91's ranking, studio plan §3.2). Structure and
+ * position candidates only look as far up as `path` itself goes — pass a
+ * sub-path (e.g. from an item's root down) to keep a field's selector
+ * relative to its item instead of absolute to the document.
+ *
+ * @param path - The node's ancestry, root (or scope root) first, itself last.
+ * @param includePosition - `false` for an item selector: a position candidate would only ever match one of the items, which is never what an item selector should do.
+ * @returns Candidates, best tier first; ties keep this function's own order.
+ */
+export declare function candidatesFor(path: DomPath, includePosition?: boolean): SelectorCandidate[];
+//# sourceMappingURL=selector-candidates.algorithm.d.ts.map

package/dist/selector-inference/selector-ranking.policy.d.ts

@@ -0,0 +1,27 @@
+import type { SelectorCandidate } from './selector-candidates.algorithm';
+export interface RankedCandidate extends SelectorCandidate {
+    /** How many elements this candidate matches in the document it was verified against. */
+    matches: number;
+    /** Whether it matches `targetNodeId` (when one was given); a candidate that misses its own target is worse than useless. */
+    hitsTarget: boolean;
+}
+/**
+ * Verifies and orders selector candidates against real markup, by running
+ * each one through the engine's own CSS matching (`@opencraw/core`'s
+ * `countMatches`/`matchesOf`) rather than reimplementing it — issue #91's
+ * "every candidate is verified" requirement.
+ *
+ * Ordering: candidates that do not match `targetNodeId` (when given) sort
+ * last; among the rest, best tier first, and within a tier the fewest
+ * matches first (the most specific selector that still hits the target).
+ * A candidate matching nothing is dropped entirely: it is not a real option.
+ *
+ * @param html - The document to verify against (the snapshot, or the live page for the second, cross-check pass).
+ * @param candidates - Unranked candidates, e.g. from `candidatesFor`.
+ * @param targetNodeId - The `data-oc-node` id the pick landed on, when the document carries those stamps (the snapshot does; a live page fetched separately does not).
+ * @returns Every candidate that matched at least one element, ranked best first.
+ */
+export declare function rankCandidates(html: string, candidates: readonly SelectorCandidate[], targetNodeId?: string): RankedCandidate[];
+/** The single best candidate, or `undefined` when none of them matched anything. */
+export declare function bestCandidate(html: string, candidates: readonly SelectorCandidate[], targetNodeId?: string): RankedCandidate | undefined;
+//# sourceMappingURL=selector-ranking.policy.d.ts.map