@opencraw/studio 0.0.5 → 0.0.6

package/dist/index.esm.js

@@ -3,7 +3,8 @@ import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { randomBytes, createHash } from 'node:crypto';
-import { BrowserClient, HttpClient, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, RecipeBindingError, RecipeValidationError } from '@opencraw/core';
+import { BrowserClient, HttpClient, NODE_ID_ATTRIBUTE, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, countMatches, RecipeBindingError, RecipeValidationError } from '@opencraw/core';
+import { load } from 'cheerio';
 import { writeFile } from 'node:fs/promises';
 import { existsSync, createReadStream } from 'node:fs';
 
@@ -82,7 +83,101 @@ const saveOutlineCommandSchema = z.object({
   path: z.string().min(1),
   outline: outlineViewSchema
 });
-const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema]);
+/**
+ * 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.
+ */
+const takeSnapshotCommandSchema = z.object({
+  type: z.literal('take-snapshot'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1)
+});
+/**
+ * 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).
+ */
+const verifySelectorCommandSchema = z.object({
+  type: z.literal('verify-selector'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1),
+  selector: z.string().min(1)
+});
+/**
+ * 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).
+ */
+const pickedNodeIdSchema = z.string().min(1);
+const onePickedNodeSchema = z.tuple([pickedNodeIdSchema]);
+const twoPickedNodesSchema = z.tuple([pickedNodeIdSchema, pickedNodeIdSchema]);
+const inferSelectorCommandSchema = z.object({
+  type: z.literal('infer-selector'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1),
+  nodeIds: z.union([onePickedNodeSchema, twoPickedNodesSchema])
+});
+const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema]);
+
+/** What `take-snapshot` answers with: the rewritten document ready for the content pane's sandboxed iframe (studio plan §3.1, issue #91). */
+const snapshotViewSchema = z.object({
+  html: z.string(),
+  nodeCount: z.number(),
+  baseUrl: z.string()
+});
+
+/**
+ * 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".
+ */
+const verifySelectorViewSchema = z.object({
+  selector: z.string(),
+  snapshotMatches: z.number(),
+  liveChecked: z.boolean(),
+  liveMatches: z.number().optional(),
+  liveError: z.string().optional()
+});
+
+/** The candidate tiers `selector-inference`'s ranking works through, best first — see `selector-candidates.algorithm.ts`. */
+const candidateTierSchema = z.enum(['id', 'data-attr', 'class', 'structure', 'position']);
+/** One clicked node's field: the best selector found for it, verified against the snapshot. */
+const fieldPickSchema = z.object({
+  selector: z.string(),
+  tier: candidateTierSchema,
+  take: z.string(),
+  matches: z.number()
+});
+/** A list's item shape: the best selector that matches every item, verified against the snapshot. */
+const itemPickSchema = z.object({
+  selector: z.string(),
+  tier: candidateTierSchema,
+  matches: z.number()
+});
+/**
+ * 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.
+ */
+const inferSelectorViewSchema = z.discriminatedUnion('kind', [z.object({
+  kind: z.literal('field'),
+  field: fieldPickSchema
+}), z.object({
+  kind: z.literal('list'),
+  item: itemPickSchema,
+  field: fieldPickSchema
+}), z.object({
+  kind: z.literal('unsupported'),
+  reason: z.string()
+})]);
 
 /** Why a sample run stopped before finishing on its own; mirrors `@opencraw/core`'s `RecipeReport.stoppedBy`. */
 const stoppedBySchema = z.enum(['sample-maxRecords', 'sample-maxPages', 'sample-maxMs']);
@@ -245,19 +340,224 @@ async function fetchApi(url) {
     const response = await client.send({
       url
     });
-    return textOf(response.body);
+    return textOf$1(response.body);
   } finally {
     await client.dispose();
   }
 }
 /** Every body kind the studio can show as text today; others get a placeholder rather than a crash. */
-function textOf(body) {
+function textOf$1(body) {
   if (body.kind === 'html') return body.html;
   if (body.kind === 'text') return body.text;
   if (body.kind === 'json') return JSON.stringify(body.data, null, 2);
   return `[${body.kind} document: the content pane shows HTML and JSON responses for now]`;
 }
 
+/** The attribute `hiddenMarksScript` stamps on an element hidden on the live page. */
+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())`.
+ */
+function hiddenMarksScript(attribute = HIDDEN_ATTRIBUTE) {
+  return `(() => {
+    var attribute = ${JSON.stringify(attribute)}
+    var elements = document.querySelectorAll('*')
+    for (var i = 0; i < elements.length; i++) {
+      var element = elements[i]
+      var style = window.getComputedStyle(element)
+      var rect = element.getBoundingClientRect()
+      var hidden = style.display === 'none' || style.visibility === 'hidden' || (rect.width === 0 && rect.height === 0)
+      if (hidden) element.setAttribute(attribute, '1')
+    }
+  })()`;
+}
+
+/** Attributes that carry a URL and are rewritten to absolute; `srcset` is handled separately (it carries several). */
+const URL_ATTRIBUTES = ['href', 'src', 'action', 'poster'];
+/** Schemes left untouched: they are not a location `new URL(value, base)` should resolve, or already carry their own meaning. */
+const SKIP_SCHEME = /^(?:javascript|mailto|tel|data|about):/i;
+/**
+ * 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.
+ */
+function rewriteDocument(html, baseUrl) {
+  const $ = load(html);
+  if ($('head').length === 0) $('html').prepend('<head></head>');
+  const head = $('head').first();
+  head.find('base').remove();
+  head.prepend(`<base href="${escapeAttribute(baseUrl)}">`);
+  $('meta').each((_index, element) => {
+    if (($(element).attr('http-equiv') ?? '').toLowerCase() === 'refresh') $(element).remove();
+  });
+  $('script').remove();
+  $('form').removeAttr('onsubmit');
+  $('input, textarea').attr('readonly', 'readonly');
+  $('select, button, input[type="submit"], input[type="button"]').attr('disabled', 'disabled');
+  $('*').each((_index, element) => {
+    const node = $(element);
+    for (const attribute of URL_ATTRIBUTES) {
+      const value = node.attr(attribute);
+      if (value !== undefined) node.attr(attribute, resolveUrl(value, baseUrl) ?? value);
+    }
+    const srcset = node.attr('srcset');
+    if (srcset !== undefined) node.attr('srcset', rewriteSrcset(srcset, baseUrl));
+  });
+  let nodeCount = 0;
+  $('*').each((_index, element) => {
+    $(element).attr(NODE_ID_ATTRIBUTE, `n${nodeCount}`);
+    nodeCount += 1;
+  });
+  return {
+    html: $.html(),
+    nodeCount
+  };
+}
+/** Resolves one URL against `baseUrl`; a scheme that is not a location (`javascript:`, `data:`…), or a value `new URL` cannot parse, is left as it was. */
+function resolveUrl(value, baseUrl) {
+  const trimmed = value.trim();
+  if (trimmed === '' || SKIP_SCHEME.test(trimmed)) return undefined;
+  try {
+    return new URL(trimmed, baseUrl).href;
+  } catch {
+    return undefined;
+  }
+}
+/** `srcset`'s own micro-syntax: comma-separated `url descriptor?` pairs. Malformed entries are passed through unresolved rather than dropped. */
+function rewriteSrcset(value, baseUrl) {
+  return value.split(',').map(candidate => {
+    const trimmed = candidate.trim();
+    const spaceAt = trimmed.indexOf(' ');
+    const url = spaceAt === -1 ? trimmed : trimmed.slice(0, spaceAt);
+    const descriptor = spaceAt === -1 ? '' : trimmed.slice(spaceAt);
+    return `${resolveUrl(url, baseUrl) ?? url}${descriptor}`;
+  }).join(', ');
+}
+function escapeAttribute(value) {
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
+}
+
+/**
+ * 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"`.
+ */
+async function takeSnapshot(input, stepPath, browser) {
+  if (stepPath !== 'start') throw new Error(`takeSnapshot: "${stepPath}" is not supported yet — only "start" (the first start point, before any step runs) is; see this function's doc comment`);
+  const point = input.start[0];
+  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
+  return input.mode === 'web' ? snapshotWeb(point.url, browser) : snapshotApi(point.url);
+}
+async function snapshotWeb(url, browser) {
+  const client = await BrowserClient.launch(browser);
+  try {
+    const session = await client.newSession();
+    try {
+      await session.page.goto(url);
+      await session.page.evaluate(hiddenMarksScript(HIDDEN_ATTRIBUTE));
+      const html = await session.page.content();
+      const baseUrl = session.page.url();
+      const rewritten = rewriteDocument(html, baseUrl);
+      return {
+        ...rewritten,
+        baseUrl
+      };
+    } finally {
+      await session.close();
+    }
+  } finally {
+    await client.close();
+  }
+}
+async function snapshotApi(url) {
+  const client = await HttpClient.open({});
+  try {
+    const response = await client.send({
+      url
+    });
+    const rewritten = rewriteDocument(textOf(response.body), url);
+    return {
+      ...rewritten,
+      baseUrl: url
+    };
+  } finally {
+    await client.dispose();
+  }
+}
+/** Every body kind the studio can show as text today; others get a placeholder rather than a crash (mirrors `fetch-start-page.use-case.ts`'s own `textOf`). */
+function textOf(body) {
+  if (body.kind === 'html') return body.html;
+  if (body.kind === 'text') return body.text;
+  if (body.kind === 'json') return `<pre>${JSON.stringify(body.data, null, 2)}</pre>`;
+  return `<p>[${body.kind} document: the content pane shows HTML and JSON responses for now]</p>`;
+}
+
+/** @returns An empty cache, for a freshly opened workspace. */
+function createSnapshotCache() {
+  return {
+    entries: new Map()
+  };
+}
+/** @returns The cached snapshot for `recipeId`/`path`, or `undefined` when none was taken yet. */
+function cachedSnapshot(cache, recipeId, path) {
+  return cache.entries.get(keyOf(recipeId, path));
+}
+/** Records a freshly taken snapshot, replacing whatever was cached for the same recipe and step path. */
+function putSnapshot(cache, recipeId, path, snapshot) {
+  cache.entries.set(keyOf(recipeId, path), snapshot);
+}
+function keyOf(recipeId, path) {
+  return `${recipeId}:${path}`;
+}
+
 /**
  * Finds and parses one input recipe of a workspace folder, and the output
  * recipe it names.
@@ -299,10 +599,11 @@ function idOf(content) {
  * @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.
  */
-async function runSample(folder, recipeId, budget, callbacks) {
+async function runSample(folder, recipeId, budget, callbacks, browser) {
   const {
     input,
     output
@@ -313,6 +614,7 @@ async function runSample(folder, recipeId, budget, callbacks) {
     sink,
     debug: true,
     sample: budget,
+    browser,
     onEvent: event => {
       const line = traceLine(event);
       if (line !== undefined) callbacks.onTraceLine(line);
@@ -365,12 +667,504 @@ async function handleFetchStartPage(state, command) {
   const {
     input
   } = await loadRecipePair(state.folder, command.recipeId);
-  const html = await fetchStartPage(input);
+  const html = await fetchStartPage(input, state.browser);
   return {
     html
   };
 }
 
+const GENERATED_ID = /^(?:react-|radix-|:r|ember|css-|mui-|headlessui-)/i;
+/**
+ * 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.
+ */
+function domPathOf($, node) {
+  const chain = [];
+  let current = node;
+  while (current !== undefined && current.length > 0 && isElement(current.get(0))) {
+    chain.unshift(current);
+    const parent = current.parent();
+    current = parent.length > 0 ? parent : undefined;
+  }
+  return chain.map(element => levelOf($, element));
+}
+function levelOf($, element) {
+  const node = element.get(0);
+  const tag = node.tagName.toLowerCase();
+  const attrs = {};
+  const entries = Object.entries(node.attribs ?? {});
+  for (const [name, value] of entries) attrs[name] = value;
+  const classes = (attrs.class ?? '').split(/\s+/).filter(token => token.length > 0);
+  const siblings = element.parent().length > 0 ? element.parent().children(tag) : $.root().children(tag);
+  const index = siblings.toArray().indexOf(node) + 1;
+  return {
+    tag,
+    id: attrs.id,
+    classes,
+    attrs,
+    index: Math.max(index, 1),
+    siblingCount: Math.max(siblings.length, 1)
+  };
+}
+function isElement(node) {
+  return node !== undefined && node.type === 'tag';
+}
+/**
+ * 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.
+ */
+function isStableId(id) {
+  return id.length > 0 && !GENERATED_ID.test(id);
+}
+/**
+ * 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.
+ */
+function crossesShadowRoot(path) {
+  return path.length === 0 || path[0].tag !== 'html';
+}
+/** Parses `html` and returns cheerio's API, for callers that need more than one path from the same document. */
+function parseDocument$1(html) {
+  return load(html);
+}
+/**
+ * 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.
+ */
+function pathToNode(html, nodeId) {
+  const $ = parseDocument$1(html);
+  const found = $(`[${NODE_ID_ATTRIBUTE}="${cssAttributeValue(nodeId)}"]`);
+  return found.length === 0 ? undefined : domPathOf($, found.first());
+}
+function cssAttributeValue(value) {
+  return value.replaceAll('\\', String.raw`\\`).replaceAll('"', String.raw`\"`);
+}
+
+/** Attributes worth reading instead of text, in preference order, when the clicked element has one. */
+const PREFERRED_ATTRS = {
+  a: ['href'],
+  img: ['src', 'alt']
+};
+/**
+ * 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.
+ */
+function takeKindFor(level) {
+  if (level.tag === 'script' && (level.attrs.type ?? '').toLowerCase() === 'application/json') return 'json';
+  const preferred = PREFERRED_ATTRS[level.tag];
+  if (preferred !== undefined) {
+    const attribute = preferred.find(name => level.attrs[name] !== undefined);
+    if (attribute !== undefined) return `attr:${attribute}`;
+  }
+  const dataAttribute = Object.keys(level.attrs).find(name => name.startsWith('data-') && name !== 'data-oc-node' && name !== 'data-oc-hidden');
+  if (dataAttribute !== undefined) return `attr:${dataAttribute}`;
+  return 'text';
+}
+
+/**
+ * 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.
+ */
+const GENERATED_TOKEN_PATTERNS = [/** styled-components / emotion: `sc-bdVaJa`, `css-1x2y3z4` */
+/^(?:sc|css)-[a-z0-9]+$/i, /** CSS Modules, most bundlers' default hash suffix: `wrapper__3fA9k`, `Button-module_root__aB3dK` */
+/__[a-z0-9]{4,10}$/i, /** JSS / MUI: `jss123`, `MuiButton-root-145` */
+/^(?:jss|mui[a-z]*-)[a-z0-9-]*\d{2}$/i, /** A token that is only digits: not a class a human would type. */
+/^\d+$/, /** A bare hex hash: `a3f9c21`, `1a2b3c4d` (6+ hex chars, nothing else). */
+/^[0-9a-f]{6,}$/i, /** Tailwind/atomic-CSS-in-JS runtime classes some bundlers emit: `_1a2b3c` */
+/^_[0-9a-z]{5,}$/i];
+/**
+ * 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.
+ */
+function isStableClassToken(token) {
+  return token.length > 0 && GENERATED_TOKEN_PATTERNS.every(pattern => !pattern.test(token));
+}
+/**
+ * The subset of `tokens` worth ranking a selector candidate on, order kept.
+ *
+ * @param tokens - An element's class list.
+ * @returns Only the stable tokens.
+ */
+function stableClasses(tokens) {
+  return tokens.filter(token => isStableClassToken(token));
+}
+/**
+ * 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.
+ */
+function sameClassSignature(a, b) {
+  const left = new Set(stableClasses(a));
+  const right = new Set(stableClasses(b));
+  if (left.size !== right.size) return false;
+  return [...left].every(token => right.has(token));
+}
+
+/**
+ * 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.
+ */
+class ShadowDomUnsupportedError extends Error {
+  path;
+  constructor(path) {
+    super(`"${path}" is inside a shadow root: shadow DOM is not supported for picking (v1)`);
+    this.path = path;
+    this.name = 'ShadowDomUnsupportedError';
+  }
+}
+
+/** Attributes ranked just under `id`: named explicitly, not "any `data-*`", because a generated `data-reactid` is no more stable than a generated class. */
+const STABLE_ATTRS = ['data-testid', 'data-id', 'itemprop'];
+const TIER_ORDER$1 = {
+  'id': 0,
+  'data-attr': 1,
+  'class': 2,
+  'structure': 3,
+  'position': 4
+};
+/**
+ * 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.
+ */
+function candidatesFor(path, includePosition = true) {
+  const node = path.at(-1);
+  if (node === undefined) return [];
+  const candidates = [];
+  if (node.id !== undefined && isStableId(node.id)) candidates.push({
+    selector: `#${cssEscape(node.id)}`,
+    tier: 'id'
+  });
+  for (const name of STABLE_ATTRS) {
+    const value = node.attrs[name];
+    if (value !== undefined && value.length > 0) candidates.push({
+      selector: `${node.tag}[${name}="${cssValue(value)}"]`,
+      tier: 'data-attr'
+    });
+  }
+  const classes = stableClasses(node.classes);
+  if (classes.length > 0) candidates.push({
+    selector: `${node.tag}.${classes.map(token => cssEscape(token)).join('.')}`,
+    tier: 'class'
+  });
+  candidates.push(...structureCandidates(path));
+  if (includePosition) candidates.push(...positionCandidates(path));
+  return sortByTier(candidates);
+}
+/** `ancestor > ... > tag`, growing from 2 to 4 levels (or to the top of `path`), each ancestor named by its own best simple form. */
+function structureCandidates(path) {
+  const node = path.at(-1);
+  if (node === undefined) return [];
+  const candidates = [];
+  const maxDepth = Math.min(path.length - 1, 3);
+  for (let depth = 1; depth <= maxDepth; depth++) {
+    const ancestor = path.at(-1 - depth);
+    if (ancestor === undefined) break;
+    const between = Array.from({
+      length: depth - 1
+    }, (_, index) => path.at(-depth + index)?.tag ?? '');
+    const parts = [simpleSelector(ancestor), ...between, node.tag];
+    candidates.push({
+      selector: parts.join(' > '),
+      tier: 'structure'
+    });
+  }
+  return candidates;
+}
+/** `parent > tag:nth-of-type(n)`, the position-only fallback; never `nth-child`, which counts every sibling tag, not just this element's own. */
+function positionCandidates(path) {
+  const node = path.at(-1);
+  if (node === undefined) return [];
+  const own = node.siblingCount > 1 ? `${node.tag}:nth-of-type(${node.index})` : node.tag;
+  const parent = path.at(-2);
+  if (parent === undefined) return [{
+    selector: own,
+    tier: 'position'
+  }];
+  return [{
+    selector: `${simpleSelector(parent)} > ${own}`,
+    tier: 'position'
+  }];
+}
+/** A level's own selector fragment, no combinators: id, else stable classes, else the bare tag. */
+function simpleSelector(level) {
+  if (level.id !== undefined && isStableId(level.id)) return `#${cssEscape(level.id)}`;
+  const classes = stableClasses(level.classes);
+  return classes.length > 0 ? `${level.tag}.${classes.map(token => cssEscape(token)).join('.')}` : level.tag;
+}
+function sortByTier(candidates) {
+  return [...candidates].sort((a, b) => TIER_ORDER$1[a.tier] - TIER_ORDER$1[b.tier]);
+}
+/** Escapes a CSS identifier segment (an id or a class token) well enough for the shapes real sites use; not a full CSS.escape polyfill. */
+function cssEscape(token) {
+  return token.replaceAll(/([^\w-])/gi, String.raw`\$1`);
+}
+/** Escapes a value inside `[name="…"]`. */
+function cssValue(value) {
+  return value.replaceAll(/(["\\])/g, String.raw`\$1`);
+}
+
+const TIER_ORDER = {
+  'id': 0,
+  'data-attr': 1,
+  'class': 2,
+  'structure': 3,
+  'position': 4
+};
+/**
+ * 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.
+ */
+function rankCandidates(html, candidates, targetNodeId) {
+  const ranked = candidates.map(candidate => {
+    const matches = countMatches(html, candidate.selector);
+    const hitsTarget = targetNodeId === undefined ;
+    return {
+      ...candidate,
+      matches,
+      hitsTarget
+    };
+  });
+  return ranked.filter(candidate => candidate.matches > 0).sort((a, b) => Number(b.hitsTarget) - Number(a.hitsTarget) || TIER_ORDER[a.tier] - TIER_ORDER[b.tier] || a.matches - b.matches);
+}
+/** The single best candidate, or `undefined` when none of them matched anything. */
+function bestCandidate(html, candidates, targetNodeId) {
+  return rankCandidates(html, candidates, targetNodeId)[0];
+}
+
+/**
+ * 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.
+ */
+function inferList(pathA, pathB) {
+  if (crossesShadowRoot(pathA)) throw new ShadowDomUnsupportedError(pathToString(pathA));
+  if (crossesShadowRoot(pathB)) throw new ShadowDomUnsupportedError(pathToString(pathB));
+  let divergedAt = -1;
+  const limit = Math.min(pathA.length, pathB.length);
+  for (let index = 0; index < limit; index++) {
+    if (!sameLevel(pathA[index], pathB[index])) {
+      divergedAt = index;
+      break;
+    }
+  }
+  // Identical paths, or one a strict prefix of the other (the same node picked twice, or one element nested inside the other): not a list.
+  if (divergedAt <= 0) return null;
+  const branchA = pathA[divergedAt];
+  const branchB = pathB[divergedAt];
+  if (branchA.tag !== branchB.tag || !sameClassSignature(branchA.classes, branchB.classes)) return null;
+  if (branchA.index === branchB.index) return null; // Same position: not two different items.
+  const ancestors = pathA.slice(0, divergedAt);
+  const fieldPathA = pathA.slice(divergedAt);
+  const fieldPathB = pathB.slice(divergedAt);
+  const fieldPath = mergeRelativePaths(fieldPathA, fieldPathB);
+  return {
+    itemPath: [...ancestors, fieldPath[0]],
+    fieldPath,
+    fieldPathA,
+    fieldPathB
+  };
+}
+function sameLevel(a, b) {
+  return a.tag === b.tag && a.id === b.id && a.index === b.index && a.siblingCount === b.siblingCount && sameClassSignature(a.classes, b.classes);
+}
+/**
+ * Zips two item-relative paths (item first) level by level into one that
+ * only keeps what both share: the tag (must already match, checked by the
+ * caller for level 0), the intersection of stable classes, and attributes
+ * present with the same value on both sides. Shorter than the other when
+ * the two picks' local structure differs in depth (a real possibility once
+ * a field is missing on one item; `list-inference.algorithm.test.ts`'s
+ * shifted-field fixture is exactly this) — the merge just stops there,
+ * which is fine: a field selector only needs to reach as deep as the
+ * shallower of the two picks.
+ */
+function mergeRelativePaths(a, b) {
+  const length = Math.min(a.length, b.length);
+  const merged = [];
+  for (let index = 0; index < length; index++) {
+    const left = a[index];
+    const right = b[index];
+    if (left.tag !== right.tag) break;
+    merged.push(mergeLevel(left, right));
+  }
+  return merged.length > 0 ? merged : [a[0]];
+}
+function mergeLevel(a, b) {
+  const classes = stableClasses(a.classes).filter(token => b.classes.includes(token));
+  const attrs = {};
+  for (const [name, value] of Object.entries(a.attrs)) {
+    if (name !== 'class' && name !== 'id' && b.attrs[name] === value) attrs[name] = value;
+  }
+  return {
+    tag: a.tag,
+    id: a.id !== undefined && a.id === b.id ? a.id : undefined,
+    classes,
+    attrs,
+    index: 1,
+    siblingCount: Math.max(a.siblingCount, b.siblingCount, 1)
+  };
+}
+function pathToString(path) {
+  return path.map(level => level.tag + (level.id === undefined ? '' : `#${level.id}`)).join(' > ');
+}
+
+/**
+ * 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.
+ */
+function handleInferSelector(state, command) {
+  const snapshot = cachedSnapshot(state.snapshots, command.recipeId, command.path);
+  if (snapshot === undefined) throw new Error(`no cached snapshot for "${command.recipeId}" at "${command.path}": call take-snapshot first`);
+  const html = snapshot.html;
+  const paths = command.nodeIds.map(nodeId => pathToNode(html, nodeId));
+  if (paths.includes(undefined)) return {
+    kind: 'unsupported',
+    reason: 'one of the picked nodes is no longer in the snapshot; take a fresh snapshot and try again'
+  };
+  const [pathA, pathB] = paths;
+  if (pathB === undefined) return {
+    kind: 'field',
+    field: fieldPick(html, pathA)
+  };
+  try {
+    const result = inferList(pathA, pathB);
+    if (result === null) return {
+      kind: 'unsupported',
+      reason: 'these two picks do not belong to the same list: pick the same field on two similar items'
+    };
+    const item = bestCandidate(html, candidatesFor(result.itemPath, false));
+    if (item === undefined) return {
+      kind: 'unsupported',
+      reason: 'no selector matches every item of this list; try picking two items closer to each other in the markup'
+    };
+    const field = fieldPick(html, result.fieldPathA, result.fieldPath);
+    return {
+      kind: 'list',
+      item: {
+        selector: item.selector,
+        tier: item.tier,
+        matches: item.matches
+      },
+      field
+    };
+  } catch (error) {
+    if (error instanceof ShadowDomUnsupportedError) return {
+      kind: 'unsupported',
+      reason: error.message
+    };
+    throw error;
+  }
+}
+/** The best selector for one clicked node, `take` decided from the concrete clicked element; `rankSource` (a generalised path) is used for candidate generation when given, so a per-item-unique attribute of the one node picked cannot end up in the selector. */
+function fieldPick(html, clicked, rankSource = clicked) {
+  const leaf = clicked.at(-1);
+  const take = leaf === undefined ? 'text' : takeKindFor(leaf);
+  const best = bestCandidate(html, candidatesFor(rankSource));
+  if (best === undefined) throw new Error('no selector matches the picked node — this should not happen, since the node came from this same document');
+  return {
+    selector: best.selector,
+    tier: best.tier,
+    take,
+    matches: best.matches
+  };
+}
+
 /**
  * The outline model: an `InputRecipe`'s `steps` (and only `steps`; the rest
  * of the recipe passes through untouched, see `recipe-to-outline.mapper.ts`)
@@ -752,10 +1546,11 @@ async function saveRecipe(path, recipe) {
   await writeFile(path, `${JSON.stringify(recipe, null, 2)}\n`, 'utf8');
 }
 
-/** @returns Fresh state for a new server instance: no workspace open, no run, no sockets. */
+/** @returns Fresh state for a new server instance: no workspace open, no run, no sockets, an empty snapshot cache, Playwright's own default browser. */
 function createStudioState() {
   return {
-    sockets: new Set()
+    sockets: new Set(),
+    snapshots: createSnapshotCache()
   };
 }
 /**
@@ -824,7 +1619,7 @@ async function handleRunSample(state, command) {
         data: record.data
       });
     }
-  });
+  }, state.browser);
   state.activeRun = handle;
   void handle.result.then(result => {
     if (state.activeRun === handle) state.activeRun = undefined;
@@ -943,6 +1738,76 @@ function serveStatic(root, pathname, response) {
   createReadStream(file).pipe(response);
 }
 
+/**
+ * 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.
+ */
+async function handleTakeSnapshot(state, command) {
+  if (state.folder === undefined) throw new Error('open a workspace first');
+  const cached = cachedSnapshot(state.snapshots, command.recipeId, command.path);
+  if (cached !== undefined) return cached;
+  const {
+    input
+  } = await loadRecipePair(state.folder, command.recipeId);
+  const snapshot = await takeSnapshot(input, command.path, state.browser);
+  putSnapshot(state.snapshots, command.recipeId, command.path, snapshot);
+  return snapshot;
+}
+
+/**
+ * Handles `verify-selector`: runs a candidate through the engine's own
+ * selection (`@opencraw/core`'s `countMatches`) against the cached
+ * snapshot, and, best-effort, against the live page too — issue #91's "flag
+ * a selector that matches the snapshot but not the live page". The live
+ * page is fetched raw (`page-snapshot`'s `fetchStartPage`, the same reach
+ * `take-snapshot` has: only `"start"` today), not through the rewritten
+ * snapshot, so its match count is the site's own, not the studio's.
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The match counts.
+ * @throws Error when no workspace is open, the recipe cannot be found, or `command.path` has no cached snapshot yet.
+ */
+async function handleVerifySelector(state, command) {
+  if (state.folder === undefined) throw new Error('open a workspace first');
+  const snapshot = cachedSnapshot(state.snapshots, command.recipeId, command.path);
+  if (snapshot === undefined) throw new Error(`no cached snapshot for "${command.recipeId}" at "${command.path}": call take-snapshot first`);
+  const snapshotMatches = countMatches(snapshot.html, command.selector);
+  if (command.path !== 'start') return {
+    selector: command.selector,
+    snapshotMatches,
+    liveChecked: false,
+    liveError: 'only the start page can be checked against the live site for now'
+  };
+  try {
+    const {
+      input
+    } = await loadRecipePair(state.folder, command.recipeId);
+    const live = await fetchStartPage(input, state.browser);
+    return {
+      selector: command.selector,
+      snapshotMatches,
+      liveChecked: true,
+      liveMatches: countMatches(live, command.selector)
+    };
+  } catch (error) {
+    return {
+      selector: command.selector,
+      snapshotMatches,
+      liveChecked: false,
+      liveError: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
 /** RFC 6455's fixed handshake suffix. */
 const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
 /**
@@ -1059,6 +1924,7 @@ async function startStudioServer(options = {}) {
   const uiRoot = options.uiRoot ?? defaultUiRoot();
   const state = createStudioState();
   if (options.initialFolder !== undefined) state.folder = options.initialFolder;
+  state.browser = options.browser;
   const server = createServer((request, response) => {
     void handleRequest(request, response, token, state, uiRoot);
   });
@@ -1155,6 +2021,18 @@ function dispatch(command, state) {
       {
         return handleSaveOutline(state, command);
       }
+    case 'take-snapshot':
+      {
+        return handleTakeSnapshot(state, command);
+      }
+    case 'verify-selector':
+      {
+        return handleVerifySelector(state, command);
+      }
+    case 'infer-selector':
+      {
+        return Promise.resolve(handleInferSelector(state, command));
+      }
   }
 }
 function respondJson(response, status, body) {
@@ -1211,5 +2089,5 @@ async function main(argv) {
   process.on('SIGTERM', shutdown);
 }
 
-export { fetchStartPage, fetchStartPageCommandSchema, loadRecipePair, main, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, startPageViewSchema, startStudioServer, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, traceLineEventSchema, workspaceChangedEventSchema, workspaceViewSchema };
+export { fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, inferSelectorCommandSchema, inferSelectorViewSchema, loadRecipePair, main, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startStudioServer, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, workspaceChangedEventSchema, workspaceViewSchema };
 //# sourceMappingURL=index.esm.js.map