@opencraw/studio 0.0.5 → 0.0.6

package/dist/src/index.d.ts

@@ -5,6 +5,6 @@ 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 { 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 { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, studioCommandSchema, stoppedBySchema, traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, snapshotViewSchema, verifySelectorViewSchema, fieldPickSchema, inferSelectorViewSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, } from './studio-api/index.js';
+export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, StudioCommand, StoppedBy, TraceLineEvent, RecordEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, SnapshotView, VerifySelectorView, FieldPick, InferSelectorView, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, } 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/run-sample.use-case.d.ts

@@ -1,3 +1,4 @@
+import type { BrowserSessionConfig } from '@opencraw/core';
 import type { SampleBudget } from '../studio-api/index.js';
 import type { SampleRunRecord, SampleRunResult } from './sample-run-record.contract.js';
 /** Where trace lines and records go as a sample run proceeds. */
@@ -23,8 +24,9 @@ export interface SampleRunHandle {
  * @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/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

package/dist/src/studio-api/command.contract.d.ts

@@ -50,6 +50,33 @@ export declare const saveOutlineCommandSchema: z.ZodObject<{
     path: z.ZodString;
     outline: z.ZodType<import("./outline-view.contract").OutlineView, unknown, z.core.$ZodTypeInternals<import("./outline-view.contract").OutlineView, unknown>>;
 }, z.core.$strip>;
+/**
+ * Captures the snapshot the content pane shows for a step (`page-snapshot`'s
+ * `take-snapshot.use-case.ts`), caching it by recipe and step path so
+ * switching the selected step does not always re-run the recipe.
+ */
+export declare const takeSnapshotCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"take-snapshot">;
+    recipeId: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Verifies a candidate selector against the cached snapshot and, when
+ * reachable, the live page — the studio's own selection (`@opencraw/core`'s
+ * `countMatches`), never the browser's or a guess (issue #91).
+ */
+export declare const verifySelectorCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"verify-selector">;
+    recipeId: z.ZodString;
+    path: z.ZodString;
+    selector: z.ZodString;
+}, z.core.$strip>;
+export declare const inferSelectorCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"infer-selector">;
+    recipeId: z.ZodString;
+    path: z.ZodString;
+    nodeIds: z.ZodUnion<readonly [z.ZodTuple<[z.ZodString], null>, z.ZodTuple<[z.ZodString, z.ZodString], null>]>;
+}, z.core.$strip>;
 export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"open-workspace">;
     folder: z.ZodString;
@@ -74,6 +101,20 @@ export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"save-outline">;
     path: z.ZodString;
     outline: z.ZodType<import("./outline-view.contract").OutlineView, unknown, z.core.$ZodTypeInternals<import("./outline-view.contract").OutlineView, unknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"take-snapshot">;
+    recipeId: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"verify-selector">;
+    recipeId: z.ZodString;
+    path: z.ZodString;
+    selector: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"infer-selector">;
+    recipeId: z.ZodString;
+    path: z.ZodString;
+    nodeIds: z.ZodUnion<readonly [z.ZodTuple<[z.ZodString], null>, z.ZodTuple<[z.ZodString, z.ZodString], null>]>;
 }, z.core.$strip>], "type">;
 export type SampleBudget = z.infer<typeof sampleBudgetSchema>;
 export type OpenWorkspaceCommand = z.infer<typeof openWorkspaceCommandSchema>;
@@ -82,6 +123,9 @@ export type StopRunCommand = z.infer<typeof stopRunCommandSchema>;
 export type SaveRecipeCommand = z.infer<typeof saveRecipeCommandSchema>;
 export type FetchStartPageCommand = z.infer<typeof fetchStartPageCommandSchema>;
 export type SaveOutlineCommand = z.infer<typeof saveOutlineCommandSchema>;
+export type TakeSnapshotCommand = z.infer<typeof takeSnapshotCommandSchema>;
+export type VerifySelectorCommand = z.infer<typeof verifySelectorCommandSchema>;
+export type InferSelectorCommand = z.infer<typeof inferSelectorCommandSchema>;
 /** Every command the UI can send the server, over HTTP POST. */
 export type StudioCommand = z.infer<typeof studioCommandSchema>;
 //# sourceMappingURL=command.contract.d.ts.map

package/dist/src/studio-api/index.d.ts

@@ -1,5 +1,11 @@
-export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, studioCommandSchema } from './command.contract.js';
-export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, StudioCommand } from './command.contract.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, studioCommandSchema } from './command.contract.js';
+export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, StudioCommand } from './command.contract.js';
+export { snapshotViewSchema } from './snapshot-view.contract.js';
+export type { SnapshotView } from './snapshot-view.contract.js';
+export { verifySelectorViewSchema } from './verify-selector-view.contract.js';
+export type { VerifySelectorView } from './verify-selector-view.contract.js';
+export { fieldPickSchema, inferSelectorViewSchema } from './infer-selector-view.contract.js';
+export type { FieldPick, InferSelectorView } from './infer-selector-view.contract.js';
 export { stoppedBySchema, traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema } from './event.contract.js';
 export type { StoppedBy, TraceLineEvent, RecordEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent } from './event.contract.js';
 export { recipeIssueSchema, recipeListingSchema, workspaceViewSchema } from './workspace-view.contract.js';

package/dist/src/studio-api/infer-selector-view.contract.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+/** One clicked node's field: the best selector found for it, verified against the snapshot. */
+export declare const fieldPickSchema: z.ZodObject<{
+    selector: z.ZodString;
+    tier: z.ZodEnum<{
+        id: "id";
+        "data-attr": "data-attr";
+        class: "class";
+        structure: "structure";
+        position: "position";
+    }>;
+    take: z.ZodString;
+    matches: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * What `infer-selector` answers with (issue #91, studio plan §3.2):
+ * `"field"` for one clicked node — a `Read` card's shape; `"list"` for two
+ * similar nodes — the safe `extract`(items)+`forEach`(field) shape, item and
+ * field each verified separately; `"unsupported"` when the two picks are not
+ * a coherent list (different branches, the same node twice, or shadow DOM),
+ * with a message the card can show as-is.
+ */
+export declare const inferSelectorViewSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"field">;
+    field: z.ZodObject<{
+        selector: z.ZodString;
+        tier: z.ZodEnum<{
+            id: "id";
+            "data-attr": "data-attr";
+            class: "class";
+            structure: "structure";
+            position: "position";
+        }>;
+        take: z.ZodString;
+        matches: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"list">;
+    item: z.ZodObject<{
+        selector: z.ZodString;
+        tier: z.ZodEnum<{
+            id: "id";
+            "data-attr": "data-attr";
+            class: "class";
+            structure: "structure";
+            position: "position";
+        }>;
+        matches: z.ZodNumber;
+    }, z.core.$strip>;
+    field: z.ZodObject<{
+        selector: z.ZodString;
+        tier: z.ZodEnum<{
+            id: "id";
+            "data-attr": "data-attr";
+            class: "class";
+            structure: "structure";
+            position: "position";
+        }>;
+        take: z.ZodString;
+        matches: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"unsupported">;
+    reason: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type FieldPick = z.infer<typeof fieldPickSchema>;
+export type InferSelectorView = z.infer<typeof inferSelectorViewSchema>;
+//# sourceMappingURL=infer-selector-view.contract.d.ts.map

package/dist/src/studio-api/snapshot-view.contract.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/** What `take-snapshot` answers with: the rewritten document ready for the content pane's sandboxed iframe (studio plan §3.1, issue #91). */
+export declare const snapshotViewSchema: z.ZodObject<{
+    html: z.ZodString;
+    nodeCount: z.ZodNumber;
+    baseUrl: z.ZodString;
+}, z.core.$strip>;
+export type SnapshotView = z.infer<typeof snapshotViewSchema>;
+//# sourceMappingURL=snapshot-view.contract.d.ts.map

package/dist/src/studio-api/verify-selector-view.contract.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+/**
+ * What `verify-selector` answers with: the match count against the snapshot
+ * and, when the live page could be reached, against it too (issue #91's
+ * "flag a selector that matches the snapshot but not the live page").
+ * `liveChecked` is `false` when the live page could not be fetched (offline,
+ * blocked by `allowedHosts`, a transient error) — the card shows the
+ * snapshot count alone rather than a misleading "0 on the live page".
+ */
+export declare const verifySelectorViewSchema: z.ZodObject<{
+    selector: z.ZodString;
+    snapshotMatches: z.ZodNumber;
+    liveChecked: z.ZodBoolean;
+    liveMatches: z.ZodOptional<z.ZodNumber>;
+    liveError: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type VerifySelectorView = z.infer<typeof verifySelectorViewSchema>;
+//# sourceMappingURL=verify-selector-view.contract.d.ts.map

package/dist/src/studio-server/infer-selector.handler.d.ts

@@ -0,0 +1,18 @@
+import type { InferSelectorCommand, InferSelectorView } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * Handles `infer-selector`: turns one or two picked nodes (their
+ * `data-oc-node` ids, off the cached snapshot) into a verified selector —
+ * one id for a `Read` card's field, two for the safe item+field list shape
+ * `selector-inference`'s `inferList` builds by construction (issue #91,
+ * studio plan §3.2). All the actual candidate/ranking/list-inference work
+ * is `selector-inference`'s (pure); this handler only locates the clicked
+ * nodes in the cached document and calls into it.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns A field pick, a list pick, or `"unsupported"` with why.
+ * @throws Error when no workspace is open, or `command.path` has no cached snapshot yet.
+ */
+export declare function handleInferSelector(state: StudioState, command: InferSelectorCommand): InferSelectorView;
+//# sourceMappingURL=infer-selector.handler.d.ts.map

package/dist/src/studio-server/studio-http.use-case.d.ts

@@ -1,3 +1,4 @@
+import type { BrowserSessionConfig } from '@opencraw/core';
 export interface StudioServerOptions {
     /** Where the built UI lives; default: `dist/ui` next to the running server code. */
     uiRoot?: string;
@@ -11,6 +12,8 @@ export interface StudioServerOptions {
      * the folder reaches it through the URL's `folder` query param).
      */
     initialFolder?: string;
+    /** Browser launch settings every web-mode command shares (`take-snapshot`, `verify-selector`, `run-sample`); an executable path override (e.g. `OPENCRAW_CHROMIUM`, read by the caller — the server itself has no opinion on env vars) for a sandbox with no full Playwright install. Default: Playwright's own bundled browser. */
+    browser?: BrowserSessionConfig;
 }
 /** The running server: its URL (token included, ready to open), the token alone, and how to stop it. */
 export interface StudioServer {

package/dist/src/studio-server/take-snapshot.handler.d.ts

@@ -0,0 +1,16 @@
+import type { SnapshotView, TakeSnapshotCommand } from '../studio-api/index.js';
+import type { StudioState } from './workspace.store.js';
+/**
+ * Handles `take-snapshot`: loads the named input recipe, captures its
+ * snapshot at `command.path` (only `"start"` is captured for now — see
+ * `page-snapshot`'s `take-snapshot.use-case.ts`), and caches it so a later
+ * `verify-selector`/`infer-selector` against the same recipe and path, or
+ * the UI reselecting the same step, does not recapture it.
+ *
+ * @param state - The server state: `folder` must already be set.
+ * @param command - The command.
+ * @returns The rewritten snapshot.
+ * @throws Error when no workspace is open, or the recipe cannot be found or loaded.
+ */
+export declare function handleTakeSnapshot(state: StudioState, command: TakeSnapshotCommand): Promise<SnapshotView>;
+//# sourceMappingURL=take-snapshot.handler.d.ts.map