@opencraw/studio 0.0.5 → 0.0.7

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

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

package/dist/src/explain-why/item-hint.algorithm.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A best-effort hint about what a missing value's bound id actually held in
+ * the scope snapshot: the keys of an object, or the length of a list — the
+ * fallback when there is no per-item DOM snapshot to compare a selector
+ * against (see `why-sentence.mapper.ts`'s doc comment for why the richer,
+ * "the item has `.price_new`" hint is out of this phase's scope).
+ *
+ * @param scope - The record's scope snapshot (`SampleRunRecord.scope`/`SampleRunRejected.scope`).
+ * @param boundId - The leading id the rule's `from` reads.
+ * @returns A short clause (no leading punctuation), or `undefined` when the id is not in scope or nothing useful can be said about it.
+ */
+export declare function hintFor(scope: Record<string, unknown> | undefined, boundId: string | undefined): string | undefined;
+//# sourceMappingURL=item-hint.algorithm.d.ts.map

package/dist/src/explain-why/why-sentence.mapper.d.ts

@@ -0,0 +1,48 @@
+import type { FieldTrace } from '@opencraw/core';
+/** One step of the recipe that may have bound the missing value's source id, and how it went over the whole sample run (`sample-run`'s `SampleStepSummary`). */
+export interface WhyStepFact {
+    path: string;
+    stepType: string;
+    stepId?: string;
+    outcome: 'ran' | 'skipped' | 'retried' | 'not-found';
+    error?: string;
+}
+/** Everything `buildWhySentence` needs to explain one missing or rejected value; gathered by `why.use-case.ts` from the last sample run's kept trace, scope and step summary. */
+export interface WhyFacts {
+    field: string;
+    outcome: 'missing' | 'rejected';
+    /** The engine's own rejection reason (`record:reject`'s `reason`), for a rejected record. */
+    reason?: string;
+    /** The resolved missing-value policy (`nullable`, `default`, `null`, `fail`, `skip-record`), when the field could be found in the output recipe. */
+    policy?: string;
+    /** The field's mapping trace, when the record itself was emitted (a `missing` outcome only — a rejected record never reached `data`). */
+    trace?: FieldTrace;
+    /** The leading id the rule's `from` reads (`item` of `item.description`), when the rule could be found. */
+    boundId?: string;
+    /** The step that binds `boundId`, when one was found in the recipe. */
+    step?: WhyStepFact;
+    /** A best-effort hint about what the bound value actually held (phase 2's item snapshot gives a richer one for a CSS pick; this is the scope-only fallback — see this module's doc comment). */
+    hint?: string;
+}
+/**
+ * Builds the Why? tab's sentence (studio plan §4.4, issue #92) from the
+ * facts `why.use-case.ts` gathers: the value the mapping read (and each
+ * transform's effect on it), the step that bound its source id and whether
+ * it ran, was skipped, or bound nothing this recipe knows of, the
+ * missing-value policy that applied, and a hint about what was actually
+ * there instead.
+ *
+ * This is the scope-snapshot-only half of the design: phase 2's per-item DOM
+ * snapshot (the CSS-selector "the item has `.price_new`" hint the issue's
+ * example shows) is not wired in here — `sample-run` keeps the mapping's
+ * scope snapshot (bound ids and their values), not a per-`forEach`-item DOM
+ * capture, and building that link is a bigger integration than this phase's
+ * budget covers (see this package's `page-snapshot` slice, which captures a
+ * step's page for the content pane, not per-iteration). `hint`, when given,
+ * is instead built from the scope snapshot itself (`item-hint.algorithm.ts`).
+ *
+ * @param facts - What is known about the value.
+ * @returns One sentence, always ending in a period.
+ */
+export declare function buildWhySentence(facts: WhyFacts): string;
+//# sourceMappingURL=why-sentence.mapper.d.ts.map

package/dist/src/explain-why/why.use-case.d.ts

@@ -0,0 +1,26 @@
+import type { InputRecipe, OutputRecipe } from '@opencraw/core';
+import type { LastRunCache } from '../sample-run/index.js';
+import type { WhyTarget, WhyView } from '../studio-api/index.js';
+/**
+ * Explains one missing or rejected value from a recipe's last sample run
+ * (issue #92's Why? tab, studio plan §4.4): the mapping trace and scope
+ * snapshot `run-sample` kept, the recipe's own rule and field for the
+ * missing-value policy, and the step that bound the value's source id — did
+ * it run, was it skipped, or does no step in this recipe bind it at all.
+ *
+ * @param folder - The workspace folder (to re-read the recipe pair: the last
+ *   run only kept the run's own data, not the recipe text, and a save may
+ *   have happened since).
+ * @param cache - The server's last-run cache (`sample-run`'s `LastRunCache`).
+ * @param loadPair - Loads the input/output recipe pair; injected so this
+ *   stays testable without a real workspace folder (`sample-run`'s
+ *   `loadRecipePair` in production).
+ * @param target - What was clicked.
+ * @returns The explanation.
+ * @throws Error when no sample run has finished for this recipe yet, or the target does not name a real record/field.
+ */
+export declare function explainWhy(folder: string, cache: LastRunCache, loadPair: (folder: string, recipeId: string) => Promise<{
+    input: InputRecipe;
+    output: OutputRecipe;
+}>, target: WhyTarget): Promise<WhyView>;
+//# sourceMappingURL=why.use-case.d.ts.map

package/dist/src/index.d.ts

@@ -3,8 +3,9 @@ export { startStudioServer } from './studio-server/index.js';
 export type { StudioServer, StudioServerOptions } from './studio-server/index.js';
 export { openWorkspace, saveRecipe } from './recipe-workspace/index.js';
 export { runSample, loadRecipePair } from './sample-run/index.js';
-export type { RecipePair, SampleRunCallbacks, SampleRunHandle, SampleRunRecord, SampleRunResult, SampleStoppedBy } from './sample-run/index.js';
+export type { RecipePair, SampleRunCallbacks, SampleRunHandle, SampleRunRecord, SampleRunRejected, SampleRunResult, SampleStepSummary, SampleStoppedBy } from './sample-run/index.js';
 export { fetchStartPage } from './page-snapshot/index.js';
-export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, studioCommandSchema, stoppedBySchema, traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, } from './studio-api/index.js';
-export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, StudioCommand, StoppedBy, TraceLineEvent, RecordEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, } from './studio-api/index.js';
+export type { WhyFacts, WhyStepFact } from './explain-why/index.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, studioCommandSchema, stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, snapshotViewSchema, verifySelectorViewSchema, fieldPickSchema, inferSelectorViewSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, whyViewSchema, } from './studio-api/index.js';
+export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, StudioCommand, StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, SnapshotView, VerifySelectorView, FieldPick, InferSelectorView, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, WhyView, } from './studio-api/index.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,2 +1,9 @@
 export { fetchStartPage } from './fetch-start-page.use-case.js';
+export { takeSnapshot } from './take-snapshot.use-case.js';
+export type { SnapshotResult } from './take-snapshot.use-case.js';
+export { rewriteDocument } from './rewrite-document.mapper.js';
+export type { RewrittenDocument } from './rewrite-document.mapper.js';
+export { hiddenMarksScript, HIDDEN_ATTRIBUTE } from './hidden-marks.algorithm.js';
+export { createSnapshotCache, cachedSnapshot, putSnapshot, invalidateRecipe } from './snapshot.store.js';
+export type { SnapshotCache } from './snapshot.store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/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/src/page-snapshot/snapshot.store.d.ts

@@ -0,0 +1,14 @@
+import type { SnapshotResult } from './take-snapshot.use-case.js';
+/** 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/src/page-snapshot/take-snapshot.use-case.d.ts

@@ -0,0 +1,34 @@
+import type { BrowserSessionConfig, 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;
+}
+/**
+ * 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.
+ * @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): Promise<SnapshotResult>;
+//# sourceMappingURL=take-snapshot.use-case.d.ts.map

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

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

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

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

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

@@ -1,9 +1,12 @@
+import type { BrowserSessionConfig } from '@opencraw/core';
 import type { SampleBudget } from '../studio-api/index.js';
-import type { SampleRunRecord, SampleRunResult } from './sample-run-record.contract.js';
+import type { SampleRunRecord, SampleRunRejected, SampleRunResult } from './sample-run-record.contract.js';
 /** Where trace lines and records go as a sample run proceeds. */
 export interface SampleRunCallbacks {
     onTraceLine: (line: string) => void;
     onRecord: (record: SampleRunRecord) => void;
+    /** A record was rejected (a field's `skip-record` missing/coercion policy); optional, most callers only need the final `rejectedRecords` list. */
+    onRejected?: (rejected: SampleRunRejected) => void;
 }
 /** A sample run in progress. */
 export interface SampleRunHandle {
@@ -13,18 +16,23 @@ export interface SampleRunHandle {
 }
 /**
  * Runs one input recipe of a workspace folder as a sample: `debug: true` (so
- * each `record:emit` carries its data), an in-memory sink, and `budget` as
- * the crawler's `sample` (`@opencraw/core`'s `CrawlOptions.sample`, #89).
- * Every engine event becomes a trace line with the same `traceLine`
- * formatter the cli's `--trace` uses; every emitted record reaches
- * `callbacks.onRecord` as it happens, not only in the final result.
+ * each `record:emit` carries its scope snapshot and mapping trace, and each
+ * `record:reject` its scope), an in-memory sink, and `budget` as the
+ * crawler's `sample` (`@opencraw/core`'s `CrawlOptions.sample`, #89). Every
+ * engine event becomes a trace line with the same `traceLine` formatter the
+ * cli's `--trace` uses; every emitted record reaches `callbacks.onRecord` as
+ * it happens, not only in the final result. Step events (`step:start`,
+ * `step:skip`, `step:retry`) are aggregated by path into `result.steps`, so
+ * `explain-why` (#92) can later say whether the step that bound a mapping's
+ * source id ran, was skipped, or retried — without a second run.
  *
  * @param folder - The workspace folder the recipe lives in.
  * @param recipeId - The input recipe to run.
  * @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.
  * @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): Promise<SampleRunHandle>;
+export declare function runSample(folder: string, recipeId: string, budget: SampleBudget | undefined, callbacks: SampleRunCallbacks, browser?: BrowserSessionConfig): Promise<SampleRunHandle>;
 //# sourceMappingURL=run-sample.use-case.d.ts.map

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

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

package/dist/src/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/src/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/src/selector-inference/index.d.ts

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

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

@@ -0,0 +1,43 @@
+import type { DomPath } from './dom-path.model.js';
+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/src/selector-inference/selector-candidates.algorithm.d.ts

@@ -0,0 +1,22 @@
+import type { DomPath } from './dom-path.model.js';
+/** 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/src/selector-inference/selector-ranking.policy.d.ts

@@ -0,0 +1,27 @@
+import type { SelectorCandidate } from './selector-candidates.algorithm.js';
+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

package/dist/src/selector-inference/shadow-dom.error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Thrown when a pick or a list-inference walk crosses a declarative shadow
+ * root (`<template shadowrootmode>`). v1 does not pierce shadow DOM: rather
+ * than infer a selector that silently matches the wrong thing (or nothing,
+ * once the page hydrates), the studio surfaces this and stops.
+ */
+export declare class ShadowDomUnsupportedError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+//# sourceMappingURL=shadow-dom.error.d.ts.map

package/dist/src/selector-inference/take-kind.policy.d.ts

@@ -0,0 +1,12 @@
+import type { DomPathLevel } from './dom-path.model.js';
+/**
+ * What a `Read` card's `take` should be for the element a pick landed on
+ * (issue #91, studio plan §3.2): `attr:href` for an `<a>`, `attr:src` for an
+ * `<img>`, `attr:<name>` for the first `data-*` attribute otherwise, `json`
+ * for a `<script type="application/json">`, else the default, `text`.
+ *
+ * @param level - The clicked element's own level (the last entry of its `DomPath`).
+ * @returns The `take` value to put on the `extract` step.
+ */
+export declare function takeKindFor(level: DomPathLevel): string;
+//# sourceMappingURL=take-kind.policy.d.ts.map