@opencraw/studio 0.0.9 → 0.0.10

package/dist/index.esm.js

@@ -1,14 +1,14 @@
-import { join, dirname, normalize, sep, extname, resolve } from 'node:path';
+import { join, dirname, basename, extname, normalize, sep, resolve } from 'node:path';
 import { createServer } from 'node:http';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { z } from 'zod';
-import { BODY_KINDS, HttpClient, BrowserClient, NODE_ID_ATTRIBUTE, rowsOfCells, parseXml, findDeckTables, findGridTables, analyzeTables, isDeckDocument, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, resolveMissingPolicy, isWorkbookDocument, countMatches, matchesOf, tryParseJson, RecipeBindingError, RecipeValidationError, isPdfDocument, BrowserProfiles } from '@opencraw/core';
+import { BODY_KINDS, HttpClient, BrowserClient, NODE_ID_ATTRIBUTE, rowsOfCells, parseXml, findDeckTables, findGridTables, analyzeTables, parseRegion, regionText, deckRegionText, isDeckDocument, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, resolveMissingPolicy, isWorkbookDocument, RecipeBindingError, RecipeValidationError, countMatches, matchesOf, tryParseJson, isPdfDocument, BrowserProfiles } from '@opencraw/core';
 import { randomBytes, createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { promisify } from 'node:util';
 import { load } from 'cheerio';
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { describeJson } from '@opencraw/probe';
 import { tmpdir } from 'node:os';
 import { existsSync, createReadStream } from 'node:fs';
@@ -189,6 +189,19 @@ const tablePreviewCommandSchema = z.object({
   path: z.string().min(1),
   options: tablePreviewOptionsSchema
 });
+/**
+ * The live preview of a `region` extract's selector against a cached PDF
+ * snapshot (`document-view`'s `region-preview.use-case.ts`, issue #121: the
+ * PDF canvas's click-to-snap selection): the text the step would bind and
+ * the cells to highlight, recomputed as the box changes — call
+ * `take-snapshot` first.
+ */
+const regionPreviewCommandSchema = z.object({
+  type: z.literal('region-preview'),
+  recipeId: z.string().min(1),
+  path: z.string().min(1),
+  selector: z.string().min(1)
+});
 /**
  * The grid canvas's sheets and cells (`document-view`'s `workbook-view.mapper.ts`,
  * studio plan §3.4, issue #94's 5c), off the same cached snapshot
@@ -313,7 +326,23 @@ const startRecordingCommandSchema = z.object({
 const stopRecordingCommandSchema = z.object({
   type: z.literal('stop-recording')
 });
-const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewCommandSchema, gridViewCommandSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema]);
+/**
+ * Copies a document the person dropped on (or opened in) the studio into a
+ * workspace folder, so a recipe can point at it with a `file:` URL (issue
+ * #120). The bytes travel base64-encoded inside the JSON command envelope
+ * every other command uses: a local tool's own files are a few megabytes at
+ * most, not worth a second, multipart endpoint. `folder` is created when it
+ * does not exist yet, so a dropped file can also start a workspace; `name`
+ * is a plain file name (no directories), kept as the copy's name unless one
+ * is already there, in which case a numbered one is used.
+ */
+const importDocumentCommandSchema = z.object({
+  type: z.literal('import-document'),
+  folder: z.string().min(1),
+  name: z.string().min(1),
+  bytes: z.string()
+});
+const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, explainWhyCommandSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, gridViewCommandSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewCommandSchema, startRecordingCommandSchema, stopRecordingCommandSchema]);
 
 /**
  * What `take-snapshot` answers with: the rewritten document ready for the
@@ -480,6 +509,12 @@ const workspaceViewSchema = z.object({
   recipes: z.array(recipeListingSchema)
 });
 
+/** `import-document`'s answer: where the copy landed, and the `file:` URL a recipe's `start.url` points at it with. */
+const importDocumentViewSchema = z.object({
+  path: z.string().min(1),
+  url: z.string().startsWith('file:')
+});
+
 /** One record of a sample run's result, kept for the Records tab. */
 const sampleRunRecordSchema = z.object({
   key: z.string().nullable(),
@@ -669,25 +704,6 @@ const workbookDocumentViewSchema = z.object({
   csv: csvFormatViewSchema.optional()
 });
 
-const gridPreviewRowSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]));
-/** One table matched by a `table` extract's options against a workbook — mirrors `@opencraw/core`'s `GridTable`. */
-const gridTablePreviewMatchSchema = z.object({
-  sheet: z.string(),
-  title: z.string(),
-  header: z.array(z.string()),
-  rows: z.array(gridPreviewRowSchema)
-});
-/**
- * What `grid-preview` answers with (studio plan §3.4, issue #94's 5c: the
- * live preview): every matched table, or `error` when a pattern in the
- * options does not compile — expected while the person is still typing it,
- * not thrown.
- */
-const gridTablePreviewViewSchema = z.object({
-  matches: z.array(gridTablePreviewMatchSchema),
-  error: z.string().optional()
-});
-
 /** One text box on a slide, in points — mirrors `document-view/deck-view.mapper.ts`'s `DeckShapeView`, the wire shape for the UI (studio plan §3.4, issue #94's 5d). */
 const deckShapeViewSchema = z.object({
   x: z.number(),
@@ -727,6 +743,45 @@ const deckDocumentViewSchema = z.object({
   slides: z.array(deckSlideViewSchema)
 });
 
+/** One page of a PDF, or one slide of a deck, a `region` extract's box reads text off — mirrors `document-view/region-preview.use-case.ts`'s `RegionPreviewMatch`: `cells` for a PDF, `shapes` for a deck, the other empty. */
+const regionPreviewMatchSchema = z.object({
+  /** The page number of a PDF, or the slide number of a deck. */
+  page: z.number().int(),
+  text: z.string(),
+  cells: z.array(pdfCellViewSchema),
+  shapes: z.array(deckShapeViewSchema)
+});
+/**
+ * What `region-preview` answers with (issues #121 and #122: the PDF and
+ * deck canvases' click-to-snap selection): the engine's own matches for
+ * the selector — the text the step would bind, and the cells or text boxes
+ * to highlight — or `error` when the selector does not parse yet, or names
+ * the other document's keyword, reported rather than thrown.
+ */
+const regionPreviewViewSchema = z.object({
+  matches: z.array(regionPreviewMatchSchema),
+  error: z.string().optional()
+});
+
+const gridPreviewRowSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]));
+/** One table matched by a `table` extract's options against a workbook — mirrors `@opencraw/core`'s `GridTable`. */
+const gridTablePreviewMatchSchema = z.object({
+  sheet: z.string(),
+  title: z.string(),
+  header: z.array(z.string()),
+  rows: z.array(gridPreviewRowSchema)
+});
+/**
+ * What `grid-preview` answers with (studio plan §3.4, issue #94's 5c: the
+ * live preview): every matched table, or `error` when a pattern in the
+ * options does not compile — expected while the person is still typing it,
+ * not thrown.
+ */
+const gridTablePreviewViewSchema = z.object({
+  matches: z.array(gridTablePreviewMatchSchema),
+  error: z.string().optional()
+});
+
 const deckPreviewRowSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]));
 /** One table matched by a `table` extract's options against a deck — mirrors `@opencraw/core`'s `DeckTable`. */
 const deckTablePreviewMatchSchema = z.object({
@@ -1719,6 +1774,56 @@ function previewDeckTable(document, options) {
   };
 }
 
+/**
+ * Runs a `region` extract's selector against an already-read PDF or deck
+ * (issues #121 and #122: the canvases' click-to-snap selection) — the
+ * engine's own `regionText` / `deckRegionText`, so what the canvas
+ * highlights and the text it shows are exactly what the step will read,
+ * and a pure function of the document, so re-running it on every change
+ * of the box costs nothing. A `slide=` on a PDF (or a `page=` on a deck)
+ * is the same mismatch the step would fail with, reported as `error`.
+ *
+ * @param document - The read PDF or deck (`take-snapshot`'s cached body).
+ * @param selector - The `region` selector, `page=1 x=72..252 y=640..664` or `slide=2 x=60..900 y=30..90`.
+ * @returns The matches, or `error` when the selector does not parse or does not fit the document.
+ */
+function previewRegion(document, selector) {
+  try {
+    const region = parseRegion(selector);
+    if (document.kind === 'pdf') {
+      if (region.on !== 'page') return {
+        matches: [],
+        error: 'region: "slide=" reads a deck; this document is a PDF (name a "page=")'
+      };
+      return {
+        matches: regionText(document, region).map(match => ({
+          page: match.page,
+          text: match.text,
+          cells: match.cells,
+          shapes: []
+        }))
+      };
+    }
+    if (region.on !== 'slide') return {
+      matches: [],
+      error: 'region: "page=" reads a PDF; this document is a deck (name a "slide=")'
+    };
+    return {
+      matches: deckRegionText(document, region).map(match => ({
+        page: match.slide,
+        text: match.text,
+        cells: [],
+        shapes: match.shapes
+      }))
+    };
+  } catch (error) {
+    return {
+      matches: [],
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
 /**
  * Handles `deck-preview`: the deck canvas's live preview of a `table`
  * extract's options (`document-view`'s `table-preview.use-case.ts`'s
@@ -2302,1204 +2407,1271 @@ async function handleGridView(state, command) {
   return workbookDocumentView(body);
 }
 
-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.
+ * The outline model: an `InputRecipe`'s `steps` (and only `steps`; the rest
+ * of the recipe passes through untouched, see `recipe-to-outline.mapper.ts`)
+ * read as a tree of cards and brackets instead of raw JSON.
  *
- * @param $ - The parsed document.
- * @param node - The element to describe.
- * @returns The path, root first.
+ * A **card** is one step that reads as a sentence (`sentence`, built by
+ * `card-sentence.mapper.ts`). A **bracket** is a container step (`forEach`,
+ * `paginate`, `if`) whose body is itself a list of cards/brackets: the
+ * indentation the plan doc describes is this nesting, not a separate layout
+ * concept. Both kinds carry `step`, the step's own raw JSON exactly as
+ * parsed (every key, in its original order): `outline-to-recipe.mapper.ts`
+ * rebuilds the recipe from it, substituting only the (possibly edited)
+ * `children`/`elseChildren` for whatever `steps`/`else` value `step` itself
+ * holds, so an edit to one field never disturbs another's position or a
+ * step type this outline cannot make sense of.
  */
-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;
+/** The step types the outline renders as a bracket: their body is nested steps, not a single value. */
+const BRACKET_STEP_TYPES = ['forEach', 'paginate', 'if'];
+function isBracket(node) {
+  return node.kind === 'bracket';
+}
+function isBracketStepType(type) {
+  return BRACKET_STEP_TYPES.includes(type);
+}
+
+/** Step types the plan doc names as always going to a "custom" card: nothing here renders their meaning as a sentence. */
+const ALWAYS_CUSTOM = new Set(['evaluate', 'hook', 'captcha']);
+/**
+ * Turns one step's raw JSON into its sentence parts (word/pill/code), the
+ * way the plan doc's examples read: *Go to…*, *Read… from…*, *For each… in…
+ * → one record*, and so on. Never throws: a step type this cannot read
+ * becomes a short, honest fallback with `custom: true`, so the outline never
+ * drops a step for looking unfamiliar.
+ *
+ * @param step - A step's raw JSON (its `type` and whatever fields it has).
+ * @returns The sentence parts, and whether they are a real reading or a fallback.
+ */
+function cardSentence(step) {
+  const type = typeof step.type === 'string' ? step.type : undefined;
+  if (type === undefined || ALWAYS_CUSTOM.has(type)) return fallback(type);
+  const build = BUILDERS[type];
+  if (build === undefined) return fallback(type);
+  try {
+    return {
+      parts: build(step),
+      custom: false
+    };
+  } catch {
+    return fallback(type);
   }
-  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;
+function fallback(type) {
   return {
-    tag,
-    id: attrs.id,
-    classes,
-    attrs,
-    index: Math.max(index, 1),
-    siblingCount: Math.max(siblings.length, 1)
+    parts: [word(type ?? 'custom step')],
+    custom: true
   };
 }
-function isElement(node) {
-  return node !== undefined && node.type === 'tag';
+function word(text) {
+  return {
+    kind: 'word',
+    text
+  };
 }
-/**
- * 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);
+function pill(text) {
+  return {
+    kind: 'pill',
+    text
+  };
 }
-/**
- * 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';
+function code(text) {
+  return {
+    kind: 'code',
+    text
+  };
 }
-/** 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);
+/** A field that names an id: shown as a pill, `fallbackText` when it is absent. */
+function pillField(step, key, fallbackText) {
+  const value = step[key];
+  return pill(typeof value === 'string' && value.length > 0 ? value : fallbackText);
 }
-/**
- * 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());
+/** A field shown as a literal (a selector, a template, a value): stringified when it is not already a string. */
+function codeField(step, key, fallbackText = '') {
+  const value = step[key];
+  if (typeof value === 'string') return code(value);
+  if (value === undefined) return code(fallbackText);
+  return code(safeJson(value));
 }
-function cssAttributeValue(value) {
-  return value.replaceAll('\\', String.raw`\\`).replaceAll('"', String.raw`\"`);
+function safeJson(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
 }
-
-/** 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}`;
+/** `selector` or `target`, whichever the step gives (`step.contract.ts`'s `TargetFields`: exactly one is present). */
+function targetField(step) {
+  if (typeof step.target === 'string') return code(step.target);
+  return codeField(step, 'selector');
+}
+const BUILDERS = {
+  goto: step => [word('Go to'), codeField(step, 'url')],
+  click: step => [word('Click'), targetField(step)],
+  fill: step => [word('Fill'), targetField(step), word('with'), codeField(step, 'value')],
+  press: step => [word('Press'), codeField(step, 'key'), word('in'), targetField(step)],
+  select: step => [word('Choose'), selectChoice(step), word('in'), targetField(step)],
+  scroll: step => [word('Scroll to'), codeField(step, 'to')],
+  wait: step => [word('Wait for'), waitFor(step)],
+  screenshot: step => [word('Screenshot'), codeField(step, 'path')],
+  request: step => [word('Request'), code(`${typeof step.method === 'string' ? step.method : 'GET'} `), codeField(step, 'url')],
+  extract: step => [word('Read'), pillField(step, 'id', '(unnamed)'), word('from'), pillField(step, 'from', 'page'), word('←'), codeField(step, 'selector')],
+  set: step => [word('Set'), pillField(step, 'id', '(unnamed)'), word('to'), codeField(step, 'value')],
+  collect: step => [word('Collect'), codeField(step, 'value'), word('into'), pillField(step, 'into', '(unnamed)')],
+  forEach: step => forEachSentence(step),
+  paginate: step => paginateSentence(step),
+  if: step => [word('If'), codeField(step, 'test')],
+  emit: step => emitSentence(step)
+};
+function selectChoice(step) {
+  if (typeof step.value === 'string') return code(step.value);
+  if (typeof step.label === 'string') return code(step.label);
+  if (typeof step.index === 'number') return code(String(step.index));
+  if (Array.isArray(step.values)) return code(step.values.join(', '));
+  return code('');
+}
+function waitFor(step) {
+  if (typeof step.selector === 'string') return code(step.selector);
+  if (typeof step.ms === 'number') return code(`${step.ms}ms`);
+  if (typeof step.state === 'string') return code(step.state);
+  return code('');
+}
+function forEachSentence(step) {
+  const parts = [word('For each'), pillField(step, 'as', '(item)'), word('in'), typeof step.over === 'string' ? pill(step.over) : targetField(step)];
+  if (step.emit !== undefined) parts.push(word('→'), word('one record'));
+  return parts;
+}
+function paginateSentence(step) {
+  const parts = [word('For every page')];
+  const next = step.next;
+  if (next !== null && typeof next === 'object') {
+    const record = next;
+    if (typeof record.selector === 'string') parts.push(word('via'), code(record.selector));else if (typeof record.url === 'string') parts.push(word('via'), code(record.url));else if (typeof record.jsonpath === 'string') parts.push(word('via'), code(record.jsonpath));
   }
-  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';
+  if (typeof step.until === 'string') parts.push(word('until'), code(step.until));
+  return parts;
+}
+function emitSentence(step) {
+  if (typeof step.output === 'string') return [word('Emit'), word('to'), pill(step.output)];
+  return [word('Emit')];
 }
 
 /**
- * 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.
+ * Reads a recipe's `steps` as an outline. Works on whatever JSON parsed
+ * (not a validated `InputRecipe`): a recipe mid-edit in the JSON tab may be
+ * missing fields or have the wrong shape, and the outline still has to
+ * render something rather than crash the tab. Anything that is not a
+ * well-formed step becomes a custom card holding what was there; anything
+ * that is not an object at the top becomes an outline with no steps.
  *
- * @param token - One class, no surrounding whitespace.
- * @returns `false` for anything matching a known generated-class shape.
+ * @param content - The recipe's parsed JSON (the JSON tab's own `JSON.parse` of its text).
+ * @returns The outline: the untouched top-level record plus the step tree.
  */
-function isStableClassToken(token) {
-  return token.length > 0 && GENERATED_TOKEN_PATTERNS.every(pattern => !pattern.test(token));
+function recipeToOutline(content) {
+  const recipe = isRecord(content) ? content : {};
+  const steps = Array.isArray(recipe.steps) ? recipe.steps : [];
+  return {
+    recipe,
+    steps: stepsToNodes(steps, 'steps')
+  };
 }
-/**
- * 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));
+function stepsToNodes(steps, pathPrefix) {
+  return steps.map((step, index) => stepToNode(step, `${pathPrefix}.${index}`));
 }
-/**
- * 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));
+function stepToNode(step, path) {
+  if (!isRecord(step)) {
+    return {
+      kind: 'card',
+      path,
+      stepType: 'unknown',
+      sentence: [{
+        kind: 'word',
+        text: 'custom step'
+      }],
+      step: {},
+      custom: true
+    };
+  }
+  const stepType = typeof step.type === 'string' ? step.type : 'unknown';
+  const {
+    parts,
+    custom
+  } = cardSentence(step);
+  if (!isBracketStepType(stepType)) return {
+    kind: 'card',
+    path,
+    stepType,
+    sentence: parts,
+    step,
+    custom
+  };
+  const children = Array.isArray(step.steps) ? stepsToNodes(step.steps, `${path}.steps`) : [];
+  const elseChildren = stepType === 'if' && Array.isArray(step.else) ? stepsToNodes(step.else, `${path}.else`) : undefined;
+  return {
+    kind: 'bracket',
+    path,
+    stepType,
+    sentence: parts,
+    step,
+    children,
+    ...(elseChildren !== undefined && {
+      elseChildren
+    })
+  };
+}
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
 /**
- * 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.
+ * Rebuilds a recipe from its outline: `recipe`'s keys, in their original
+ * order, with `steps` (when the recipe had one) replaced by the outline's
+ * (possibly edited) step tree. A card's own raw `step` is used as-is; a
+ * bracket's `step` supplies every field but `steps`/`else`, which come from
+ * `children`/`elseChildren` instead, put back at the position `step` itself
+ * held that key at (or appended, for a bracket a `+` menu just added, whose
+ * `step` never had one) — this, together with `recipe-to-outline.mapper.ts`
+ * always keeping the step's whole original object, is what makes
+ * `recipe → outline → recipe` preserve every key and its order.
+ *
+ * @param outline - An outline, from `recipe-to-outline.mapper.ts` or edited by the UI.
+ * @returns The recipe's plain JSON, ready for `save-recipe`.
  */
-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';
+function outlineToRecipe(outline) {
+  if (!('steps' in outline.recipe) && outline.steps.length === 0) return {
+    ...outline.recipe
+  };
+  return {
+    ...outline.recipe,
+    steps: nodesToSteps(outline.steps)
+  };
+}
+function nodesToSteps(nodes) {
+  return nodes.map(node => nodeToStep(node));
+}
+function nodeToStep(node) {
+  if (!isBracket(node)) return node.step;
+  const keys = Object.keys(node.step);
+  const step = {};
+  for (const key of keys) {
+    if (key === 'steps') step.steps = nodesToSteps(node.children);else if (key === 'else' && node.stepType === 'if') step.else = nodesToSteps(node.elseChildren ?? []);else step[key] = node.step[key];
   }
+  if (!keys.includes('steps')) step.steps = nodesToSteps(node.children);
+  if (node.stepType === 'if' && node.elseChildren !== undefined && !keys.includes('else')) step.else = nodesToSteps(node.elseChildren);
+  return step;
 }
 
-/** 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.
+ * Opens a recipe folder: every `.json`/`.jsonl` recipe directly inside it
+ * (core's own directory reading, so relative `file:` URLs resolve the same
+ * way a real run would), parsed and, for each output recipe found, bound to
+ * the input recipes that name it. Nothing throws for a bad recipe or a
+ * recipe that does not bind: every problem is reported on its file with the
+ * JSON path core already computes, exactly as `opencraw validate` prints it.
  *
- * @param 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.
+ * @param folder - The workspace folder.
+ * @returns Every recipe file found, each with its validation and binding issues.
+ * @throws Error when the folder does not exist or cannot be read.
  */
-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'
-    });
+async function openWorkspace(folder) {
+  const documents = await readRecipeSource(folder);
+  const entries = documents.map(document => parseDocument$1(document));
+  const outputs = entries.filter(isParsed('output'));
+  const inputs = entries.filter(isParsed('input'));
+  for (const output of outputs) bindOutput(output, inputs);
+  for (const input of inputs) {
+    if (outputs.every(output => output.recipe.id !== input.recipe.output)) {
+      input.issues.push({
+        path: 'output',
+        message: `no output recipe "${input.recipe.output}" in this workspace`,
+        kind: 'binding'
+      });
+    }
   }
-  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'
-  }];
+  return {
+    folder,
+    recipes: entries.map(({
+      file,
+      kind,
+      id,
+      issues,
+      content
+    }) => ({
+      file,
+      kind,
+      id,
+      issues,
+      text: `${JSON.stringify(content, null, 2)}\n`,
+      // The Steps tab needs steps to render: an output/unknown file has none. recipeToOutline never
+      // throws, so this covers a file that fails validation too (its outline just has "custom" cards).
+      outline: kind === 'input' ? recipeToOutline(content) : undefined
+    }))
+  };
 }
-/** 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;
+/** Binds one output recipe to the inputs that name it, filing every binding issue back on the recipe it names. */
+function bindOutput(output, inputs) {
+  const matching = inputs.filter(input => input.recipe.output === output.recipe.id);
+  try {
+    bindRecipeSet(output.recipe, matching.map(input => input.recipe));
+  } catch (error) {
+    if (!(error instanceof RecipeBindingError)) throw error;
+    for (const issue of error.issues) {
+      const target = issue.recipeId === output.recipe.id ? output : matching.find(input => input.recipe.id === issue.recipeId);
+      target?.issues.push({
+        path: issue.path,
+        message: issue.message,
+        kind: 'binding'
+      });
+    }
+  }
 }
-function sortByTier(candidates) {
-  return [...candidates].sort((a, b) => TIER_ORDER$1[a.tier] - TIER_ORDER$1[b.tier]);
+function isParsed(kind) {
+  return entry => entry.kind === kind && entry.recipe !== undefined;
 }
-/** 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`);
+function parseDocument$1(document) {
+  const kind = document.content?.kind;
+  if (kind === 'output') return parseOne(document.source, document.content, 'output', parseOutputRecipe);
+  if (kind === 'input') return parseOne(document.source, document.content, 'input', parseInputRecipe);
+  return {
+    file: document.source,
+    kind: 'unknown',
+    content: document.content,
+    issues: [{
+      path: 'kind',
+      message: '"kind" is missing or not "input"/"output"',
+      kind: 'validation'
+    }]
+  };
 }
-/** Escapes a value inside `[name="…"]`. */
-function cssValue(value) {
-  return value.replaceAll(/(["\\])/g, String.raw`\$1`);
+function parseOne(file, content, kind, parse) {
+  try {
+    const recipe = parse(content, file);
+    return {
+      file,
+      kind,
+      content,
+      id: recipe.id,
+      issues: [],
+      recipe
+    };
+  } catch (error) {
+    if (!(error instanceof RecipeValidationError)) throw error;
+    return {
+      file,
+      kind,
+      content,
+      issues: error.issues.map(issue => ({
+        path: issue.path === '' ? '(root)' : issue.path,
+        message: issue.message,
+        kind: 'validation'
+      }))
+    };
+  }
 }
 
-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.
+ * Writes a recipe back to its file: pretty JSON, a 2-space indent, a
+ * trailing newline. Phase 0 takes the JSON tab's whole parsed object rather
+ * than a patch, so this is a full replacement, not a splice: loading a file
+ * the studio has not touched and saving it again keeps every key, value and
+ * key order (`JSON.parse` preserves insertion order, and `JSON.stringify`
+ * writes it back), but not necessarily the file's exact original formatting
+ * (alignment, how arrays wrap, a trailing comment). Byte-identical
+ * round-trip for a hand-formatted file is future work; see this file's test
+ * for what is guaranteed today.
  *
- * @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.
+ * @param path - The recipe file to write.
+ * @param recipe - The whole recipe object.
  */
-function rankCandidates(html, candidates, targetNodeId) {
-  const ranked = candidates.map(candidate => {
-    const matches = countMatches(html, candidate.selector);
-    const hitsTarget = targetNodeId === undefined || matches === 0 ? targetNodeId === undefined : matchesOf(html, candidate.selector).includes(targetNodeId);
-    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];
+async function saveRecipe(path, recipe) {
+  await writeFile(path, `${JSON.stringify(recipe, null, 2)}\n`, 'utf8');
 }
 
+/** How many `name-2.ext`, `name-3.ext`… are tried before giving up on a folder full of same-named copies. */
+const MAX_NUMBERED_COPIES = 100;
 /**
- * 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).
+ * Copies a document into a workspace folder, so a recipe can read it with a
+ * `file:` URL the same way a run would read any downloaded file (core's
+ * `HttpClient` handles `file:` itself). The folder is created when missing,
+ * so dropping a file is also a way to start a workspace. A name already in
+ * the folder is never overwritten: the copy gets the next free numbered
+ * name (`report-2.pdf`), and the returned `path`/`url` say which.
  *
- * @param 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.
+ * @param folder - The workspace folder; created (recursively) when it does not exist.
+ * @param name - The file's own name, no directories: the copy keeps it, extension included.
+ * @param bytes - The file's content.
+ * @returns Where the copy landed.
+ * @throws Error when `name` is not a plain file name, or the folder already holds too many same-named copies.
  */
-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;
+async function importDocument(folder, name, bytes) {
+  assertPlainName(name);
+  await mkdir(folder, {
+    recursive: true
+  });
+  for (const candidate of candidateNames(name)) {
+    const path = join(folder, candidate);
+    try {
+      await writeFile(path, bytes, {
+        flag: 'wx'
+      });
+      return {
+        path,
+        url: pathToFileURL(path).href
+      };
+    } catch (error) {
+      if (!isAlreadyThere(error)) throw error;
     }
   }
-  // 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
-  };
+  throw new Error(`"${name}" and ${MAX_NUMBERED_COPIES} numbered copies of it are already in ${folder}`);
 }
-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);
+function assertPlainName(name) {
+  if (name === '.' || name === '..' || name.includes('\0') || name !== basename(name)) {
+    throw new Error(`"${name}" is not a plain file name`);
+  }
 }
+function* candidateNames(name) {
+  yield name;
+  const extension = extname(name);
+  const stem = name.slice(0, name.length - extension.length);
+  for (let copy = 2; copy <= MAX_NUMBERED_COPIES + 1; copy += 1) yield `${stem}-${copy}${extension}`;
+}
+function isAlreadyThere(error) {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'EEXIST';
+}
+
 /**
- * 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.
+ * Handles `import-document` (issue #120): decodes the base64 bytes and copies
+ * the file into the folder (see `recipe-workspace/import-document.use-case.ts`
+ * for the folder creation and the no-overwrite numbering). Nothing is
+ * broadcast: the copy is not a recipe, the workspace listing does not change
+ * until the UI saves the recipe pair that points at it, which `save-recipe`
+ * announces as usual.
+ *
+ * @param command - The folder, the file's name and its base64 content.
+ * @returns Where the copy landed and its `file:` URL.
  */
-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));
+async function handleImportDocument(command) {
+  return importDocument(command.folder, command.name, new Uint8Array(Buffer.from(command.bytes, 'base64')));
+}
+
+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 merged.length > 0 ? merged : [a[0]];
+  return chain.map(element => levelOf($, element));
 }
-function mergeLevel(a, b) {
-  const classes = stableClasses(a.classes).filter(token => b.classes.includes(token));
+function levelOf($, element) {
+  const node = element.get(0);
+  const tag = node.tagName.toLowerCase();
   const attrs = {};
-  for (const [name, value] of Object.entries(a.attrs)) {
-    if (name !== 'class' && name !== 'id' && b.attrs[name] === value) attrs[name] = value;
-  }
+  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: a.tag,
-    id: a.id !== undefined && a.id === b.id ? a.id : undefined,
+    tag,
+    id: attrs.id,
     classes,
     attrs,
-    index: 1,
-    siblingCount: Math.max(a.siblingCount, b.siblingCount, 1)
+    index: Math.max(index, 1),
+    siblingCount: Math.max(siblings.length, 1)
   };
 }
-function pathToString(path) {
-  return path.map(level => level.tag + (level.id === undefined ? '' : `#${level.id}`)).join(' > ');
+function isElement(node) {
+  return node !== undefined && node.type === 'tag';
 }
-
 /**
- * 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.
+ * 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 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
-  };
+function isStableId(id) {
+  return id.length > 0 && !GENERATED_ID.test(id);
 }
-
-/** A leaf element's own text longer than this is cut, with an ellipsis. */
-const TEXT_LIMIT = 80;
-/** Consecutive siblings whose subtree is identical (ids aside) collapse into one row once there are at least this many — a real page can have tens of thousands of `<li>`s, and showing all of them is not "inspecting" it (issue #93). */
-const MIN_REPEAT_RUN = 3;
 /**
- * Builds the Inspect panel's DOM tree from a captured snapshot (studio plan
- * §3.3, issue #93): the same rewritten, marked-up document the content pane's
- * iframe shows (`page-snapshot`'s `take-snapshot.use-case.ts`), so a tree
- * row's `nodeId` addresses exactly the element the iframe would highlight —
- * no separate capture, per issue #93's scope note to reuse phase 2's
- * snapshot rather than recapture.
- *
- * @param snapshotHtml - The cached, rewritten snapshot (`SnapshotResult.html`).
- * @returns The tree's root (the document's `<html>` element).
- * @throws Error when the document has no `<html>` element (should not happen: `rewriteDocument` always produces one).
+ * 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 domTree(snapshotHtml) {
-  const $ = load(snapshotHtml);
-  const html = $('html').get(0);
-  if (html === undefined) throw new Error('domTree: the snapshot has no <html> element');
-  return buildNode($, html);
+function crossesShadowRoot(path) {
+  return path.length === 0 || path[0].tag !== 'html';
 }
-function buildNode($, element) {
-  const $el = $(element);
-  const attributes = {
-    ...element.attribs
-  };
-  const nodeId = attributes[NODE_ID_ATTRIBUTE] ?? '';
-  const hidden = attributes[HIDDEN_ATTRIBUTE] === '1';
-  delete attributes[NODE_ID_ATTRIBUTE];
-  delete attributes[HIDDEN_ATTRIBUTE];
-  const id = attributes.id;
-  const classes = (attributes.class ?? '').split(/\s+/).filter(token => token !== '');
-  const childElements = $el.children().toArray();
-  const children = collapseRepeats(childElements.map(child => buildNode($, child)));
-  const text = childElements.length === 0 ? abbreviate($el.text()) : undefined;
-  return {
-    nodeId,
-    tag: element.tagName.toLowerCase(),
-    ...(id !== undefined && id !== '' && {
-      id
-    }),
-    ...(classes.length > 0 && {
-      classes
-    }),
-    attributes,
-    ...(text !== undefined && text !== '' && {
-      text
-    }),
-    hidden,
-    children
-  };
+/** Parses `html` and returns cheerio's API, for callers that need more than one path from the same document. */
+function parseDocument(html) {
+  return load(html);
 }
 /**
- * Merges runs of `MIN_REPEAT_RUN` or more consecutive siblings whose subtree
- * is identical (their own `nodeId`s aside) into one representative row, the
- * issue's `×20` — real pages have tens of thousands of nodes, and this is
- * what makes the tree usable rather than merely correct.
+ * 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 nodes - Already-built sibling rows, in document order.
- * @returns The same rows, with each long-enough identical run replaced by one.
+ * @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 collapseRepeats(nodes) {
-  const result = [];
-  let at = 0;
-  while (at < nodes.length) {
-    const signature = signatureOf(nodes[at]);
-    let end = at + 1;
-    while (end < nodes.length && signatureOf(nodes[end]) === signature) end += 1;
-    const run = nodes.slice(at, end);
-    if (run.length >= MIN_REPEAT_RUN) {
-      result.push({
-        ...run[0],
-        repeatCount: run.length,
-        repeatNodeIds: run.map(node => node.nodeId)
-      });
-    } else {
-      result.push(...run);
-    }
-    at = end;
-  }
-  return result;
-}
-/** A run member's identity for collapsing: everything but its own `nodeId` (every instance has a different one by construction). */
-function signatureOf(node) {
-  return JSON.stringify({
-    ...node,
-    nodeId: undefined,
-    children: node.children.map(child => signatureOf(child))
-  });
+function pathToNode(html, nodeId) {
+  const $ = parseDocument(html);
+  const found = $(`[${NODE_ID_ATTRIBUTE}="${cssAttributeValue(nodeId)}"]`);
+  return found.length === 0 ? undefined : domPathOf($, found.first());
 }
-function abbreviate(text) {
-  const trimmed = text.trim().replaceAll(/\s+/g, ' ');
-  return trimmed.length > TEXT_LIMIT ? `${trimmed.slice(0, TEXT_LIMIT)}…` : trimmed;
+function cssAttributeValue(value) {
+  return value.replaceAll('\\', String.raw`\\`).replaceAll('"', String.raw`\"`);
 }
 
-/** The global names sites hydrate state into, that `describeHtml`'s own JSON-LD/table scan does not cover (issue #93's "inline state assignments"). */
-const INLINE_STATE_NAMES = ['__NEXT_DATA__', '__NUXT__', '__INITIAL_STATE__', '__APOLLO_STATE__', '__PRELOADED_STATE__', '__STATE__'];
-const INLINE_STATE_PATTERN = new RegExp(String.raw`(?:window\.)?(${INLINE_STATE_NAMES.join('|')})\s*=`);
+/** Attributes worth reading instead of text, in preference order, when the clicked element has one. */
+const PREFERRED_ATTRS = {
+  a: ['href'],
+  img: ['src', 'alt']
+};
 /**
- * Finds the data-in-the-page findings the Inspect panel lists apart from the
- * DOM tree (studio plan §3.3, issue #93): JSON-LD and `application/json`
- * script blocks, inline state assignments, `<meta>` name/property values and
- * `<link rel>`s — reusing `@opencraw/probe`'s `describeJson` for a found
- * value's shape (its own `find-data.algorithm.ts`/`html-findings.mapper.ts`
- * scan a page's raw text for *reporting*, with no element to point a pick at;
- * this function's own job — locating each finding's element so a pick can
- * reach it — is new).
- *
- * Takes the **raw** captured document, not the display snapshot
- * (`page-snapshot`'s `SnapshotResult.html`): `rewriteDocument` strips every
- * `<script>` for the sandboxed iframe, which would make JSON-LD, inline
- * state and other script-tag data invisible here. `<meta>`/`<link>` survive
- * rewriting untouched, so using the raw document for every kind (rather than
- * mixing two documents) keeps this function simple and its selectors
- * verified against what the engine will actually crawl.
+ * 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 rawHtml - The document as fetched/rendered, before `rewriteDocument` strips scripts.
- * @returns The findings, in document order.
+ * @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 pageData(rawHtml) {
-  const $ = load(rawHtml);
-  const findings = [];
-  $('script[type="application/ld+json"]').each((_index, element) => {
-    findings.push(...scriptFinding($, element, rawHtml, 'ld-json', ldJsonLabel));
-  });
-  $('script[type="application/json"]').each((_index, element) => {
-    findings.push(...scriptFinding($, element, rawHtml, 'json-script', () => `json: ${structuralSelector($, element)}`));
-  });
-  $('script').each((_index, element) => {
-    const type = $(element).attr('type');
-    if (type !== undefined && type !== 'text/javascript' && type !== 'module') return;
-    const text = $(element).text();
-    const match = INLINE_STATE_PATTERN.exec(text);
-    if (match === null) return;
-    const value = tryParseJson(text);
-    const selector = structuralSelector($, element);
-    findings.push({
-      kind: 'inline-state',
-      label: match[1],
-      selector,
-      selectorKind: 'css',
-      matches: countMatches(rawHtml, selector),
-      keys: keysOf(value)
-    });
-  });
-  $('meta[name], meta[property]').each((_index, element) => {
-    const name = $(element).attr('name') ?? $(element).attr('property') ?? '';
-    const selector = structuralSelector($, element);
-    findings.push({
-      kind: 'meta',
-      label: `meta: ${name}`,
-      selector,
-      selectorKind: 'css',
-      matches: countMatches(rawHtml, selector),
-      attribute: 'content'
-    });
-  });
-  $('link[rel]').each((_index, element) => {
-    const rel = $(element).attr('rel') ?? '';
-    const selector = structuralSelector($, element);
-    findings.push({
-      kind: 'link',
-      label: `link: ${rel}`,
-      selector,
-      selectorKind: 'css',
-      matches: countMatches(rawHtml, selector),
-      attribute: 'href'
-    });
-  });
-  return findings;
-}
-function scriptFinding($, element, rawHtml, kind, labelOf) {
-  const value = tryParseJson($(element).text());
-  if (value === undefined) return [];
-  const selector = structuralSelector($, element);
-  return [{
-    kind,
-    label: labelOf(value),
-    selector,
-    selectorKind: 'css',
-    matches: countMatches(rawHtml, selector),
-    keys: keysOf(value)
-  }];
-}
-function ldJsonLabel(value) {
-  if (Array.isArray(value)) return `ld+json: array (${value.length})`;
-  if (typeof value === 'object' && value !== null) {
-    const type = value['@type'];
-    if (typeof type === 'string') return `ld+json: ${type}`;
+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}`;
   }
-  return `ld+json: ${describeJson(value, 'json').type}`;
-}
-function keysOf(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value) ? Object.keys(value) : undefined;
+  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';
 }
+
 /**
- * A unique CSS path for an element with no stable attribute of its own
- * (a `<script>` tag has no id or class to speak of): `<ancestor> > tag`
- * from `<html>` down, `:nth-of-type` added only where a tag has siblings of
- * the same name under the same parent. Always resolves to exactly one
- * element, on the raw document this ran against and on the real page (a
- * purely structural selector, unaffected by the snapshot's own rewriting).
+ * 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 $ - The document.
- * @param element - The element to address.
- * @returns The selector.
+ * @param token - One class, no surrounding whitespace.
+ * @returns `false` for anything matching a known generated-class shape.
  */
-function structuralSelector($, element) {
-  const segments = [];
-  let $current = $(element);
-  while ($current.length > 0) {
-    const tag = $current.prop('tagName')?.toLowerCase();
-    if (tag === undefined) break;
-    const $parent = $current.parent();
-    const siblingsOfType = $parent.length > 0 ? $parent.children(tag) : $current;
-    const index = siblingsOfType.toArray().indexOf($current.get(0)) + 1;
-    segments.unshift(siblingsOfType.length > 1 ? `${tag}:nth-of-type(${index})` : tag);
-    if (tag === 'html' || $parent.length === 0) break;
-    $current = $parent;
-  }
-  return segments.join(' > ');
+function isStableClassToken(token) {
+  return token.length > 0 && GENERATED_TOKEN_PATTERNS.every(pattern => !pattern.test(token));
 }
-
-/** How long the browser is given to settle after `goto`, watching for JSON responses (mirrors `packages/cli`'s `probe --browser`, `observeBrowserJson`). */
-const OBSERVE_MS = 4000;
-/** Responses kept, largest/most-recent-first ordering left to the caller; just a sane cap on what the panel lists. */
-const RESPONSE_LIMIT = 15;
 /**
- * Records the JSON responses seen while an input recipe's start page
- * rendered (studio plan §3.3, issue #93): the same technique `packages/cli`'s
- * `probe --browser` uses (`observeBrowserJson`) — render the page, listen for
- * `response` events whose content type is JSON, give it a few seconds to
- * settle. Kept as its own capture, independent of `page-snapshot`'s
- * `take-snapshot.use-case.ts`: that capture reads `page.content()` right
- * after `goto` resolves, with no observation window, and changing its shape
- * to also collect responses was a larger, riskier change to already-shipped,
- * tested code than this phase's budget allowed (see this phase's final
- * report) — so this opens its own short-lived browser session instead of
- * piggy-backing on the cached snapshot.
+ * The subset of `tokens` worth ranking a selector candidate on, order kept.
  *
- * Only `"start"` is supported, mirroring `take-snapshot.use-case.ts`'s own
- * reach; api-mode recipes have no page load to observe, so they always
- * answer with an empty list rather than an error (there is nothing wrong
- * with asking, the answer is just "none").
+ * @param 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 input - The input recipe; only `mode` and the first `start` point are used.
- * @param stepPath - The step to observe after, e.g. `"start"`.
- * @param browser - Browser launch settings, shared with `take-snapshot`/`verify-selector`/`run-sample`.
- * @returns The distinct JSON responses observed, at most `RESPONSE_LIMIT`.
- * @throws Error when the recipe has no start point, or `stepPath` is not `"start"`.
+ * @param a - One element's classes.
+ * @param b - Another element's classes.
+ * @returns Whether their stable class sets are equal, order ignored.
  */
-async function responsesSeen(input, stepPath, browser) {
-  if (stepPath !== 'start') throw new Error(`responsesSeen: "${stepPath}" is not supported yet — only "start" (the first start point, before any step ran) is`);
-  if (input.mode !== 'web') return [];
-  const point = input.start[0];
-  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
-  const client = await ensureBrowserLaunch(browser, () => BrowserClient.launch(browser));
-  try {
-    const session = await client.newSession();
-    try {
-      const responses = [];
-      const seen = new Set();
-      const pending = [];
-      session.page.on('response', response => {
-        if (!(response.headers()['content-type'] ?? '').includes('json')) return;
-        const key = `${response.status()} ${response.url()}`;
-        if (seen.has(key)) return;
-        seen.add(key);
-        pending.push(recordResponse(response, responses));
-      });
-      try {
-        await session.page.goto(point.url, {
-          waitUntil: 'networkidle'
-        });
-      } catch {
-        // a page that never idles (long-poll, websocket) still yields whatever was observed by the timeout below
-      }
-      await session.page.waitForTimeout(OBSERVE_MS);
-      await Promise.all(pending);
-      return responses.slice(0, RESPONSE_LIMIT);
-    } finally {
-      await session.close();
-    }
-  } finally {
-    await client.close();
-  }
+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));
 }
-/** Reads one response's body, when it still can be (not aborted, not redirected away); a response that cannot be read is silently left out rather than failing the whole capture. */
-async function recordResponse(response, into) {
-  try {
-    const body = await response.text();
-    const value = tryParseJson(body);
-    into.push({
-      url: response.url(),
-      status: response.status(),
-      size: body.length,
-      shape: value === undefined ? 'text' : describeJson(value, 'json').type
-    });
-  } catch {
-    // response body unavailable (aborted, redirected, the page navigated away) — skip it
+
+/**
+ * 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
+};
 /**
- * Handles `inspect-page`: the Inspect panel's DOM tree and data-in-the-page
- * findings, off the same cached snapshot `take-snapshot`/`infer-selector`
- * already use (`page-inspector`, issue #93). `domTree` reads the cached,
- * rewritten snapshot (the same markup the content pane's iframe shows, so a
- * tree row's `nodeId` lines up with it exactly); `pageData` reads the raw
- * capture (`SnapshotResult.rawHtml`), since the display snapshot has had its
- * `<script>` tags stripped for the sandboxed iframe.
+ * 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 state - The server state.
- * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
- * @returns The tree and the data-in-the-page findings.
- * @throws Error when no workspace is open, or `command.path` has no cached snapshot yet.
+ * @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 handleInspectPage(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`);
-  return {
-    tree: domTree(snapshot.html),
-    pageData: pageData(snapshot.rawHtml)
-  };
+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
+};
 /**
- * The outline model: an `InputRecipe`'s `steps` (and only `steps`; the rest
- * of the recipe passes through untouched, see `recipe-to-outline.mapper.ts`)
- * read as a tree of cards and brackets instead of raw JSON.
+ * 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.
  *
- * A **card** is one step that reads as a sentence (`sentence`, built by
- * `card-sentence.mapper.ts`). A **bracket** is a container step (`forEach`,
- * `paginate`, `if`) whose body is itself a list of cards/brackets: the
- * indentation the plan doc describes is this nesting, not a separate layout
- * concept. Both kinds carry `step`, the step's own raw JSON exactly as
- * parsed (every key, in its original order): `outline-to-recipe.mapper.ts`
- * rebuilds the recipe from it, substituting only the (possibly edited)
- * `children`/`elseChildren` for whatever `steps`/`else` value `step` itself
- * holds, so an edit to one field never disturbs another's position or a
- * step type this outline cannot make sense of.
+ * 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.
  */
-/** The step types the outline renders as a bracket: their body is nested steps, not a single value. */
-const BRACKET_STEP_TYPES = ['forEach', 'paginate', 'if'];
-function isBracket(node) {
-  return node.kind === 'bracket';
+function rankCandidates(html, candidates, targetNodeId) {
+  const ranked = candidates.map(candidate => {
+    const matches = countMatches(html, candidate.selector);
+    const hitsTarget = targetNodeId === undefined || matches === 0 ? targetNodeId === undefined : matchesOf(html, candidate.selector).includes(targetNodeId);
+    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);
 }
-function isBracketStepType(type) {
-  return BRACKET_STEP_TYPES.includes(type);
+/** The single best candidate, or `undefined` when none of them matched anything. */
+function bestCandidate(html, candidates, targetNodeId) {
+  return rankCandidates(html, candidates, targetNodeId)[0];
 }
 
-/** Step types the plan doc names as always going to a "custom" card: nothing here renders their meaning as a sentence. */
-const ALWAYS_CUSTOM = new Set(['evaluate', 'hook', 'captcha']);
 /**
- * Turns one step's raw JSON into its sentence parts (word/pill/code), the
- * way the plan doc's examples read: *Go to…*, *Read… from…*, *For each… in…
- * → one record*, and so on. Never throws: a step type this cannot read
- * becomes a short, honest fallback with `custom: true`, so the outline never
- * drops a step for looking unfamiliar.
+ * 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.
  *
- * @param step - A step's raw JSON (its `type` and whatever fields it has).
- * @returns The sentence parts, and whether they are a real reading or a fallback.
+ * 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 cardSentence(step) {
-  const type = typeof step.type === 'string' ? step.type : undefined;
-  if (type === undefined || ALWAYS_CUSTOM.has(type)) return fallback(type);
-  const build = BUILDERS[type];
-  if (build === undefined) return fallback(type);
-  try {
-    return {
-      parts: build(step),
-      custom: false
-    };
-  } catch {
-    return fallback(type);
+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;
+    }
   }
-}
-function fallback(type) {
+  // 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 {
-    parts: [word(type ?? 'custom step')],
-    custom: true
+    itemPath: [...ancestors, fieldPath[0]],
+    fieldPath,
+    fieldPathA,
+    fieldPathB
   };
 }
-function word(text) {
-  return {
-    kind: 'word',
-    text
-  };
+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);
 }
-function pill(text) {
-  return {
-    kind: 'pill',
-    text
-  };
+/**
+ * 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 code(text) {
+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 {
-    kind: 'code',
-    text
+    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)
   };
 }
-/** A field that names an id: shown as a pill, `fallbackText` when it is absent. */
-function pillField(step, key, fallbackText) {
-  const value = step[key];
-  return pill(typeof value === 'string' && value.length > 0 ? value : fallbackText);
-}
-/** A field shown as a literal (a selector, a template, a value): stringified when it is not already a string. */
-function codeField(step, key, fallbackText = '') {
-  const value = step[key];
-  if (typeof value === 'string') return code(value);
-  if (value === undefined) return code(fallbackText);
-  return code(safeJson(value));
+function pathToString(path) {
+  return path.map(level => level.tag + (level.id === undefined ? '' : `#${level.id}`)).join(' > ');
 }
-function safeJson(value) {
+
+/**
+ * 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 {
-    return JSON.stringify(value) ?? String(value);
-  } catch {
-    return String(value);
-  }
-}
-/** `selector` or `target`, whichever the step gives (`step.contract.ts`'s `TargetFields`: exactly one is present). */
-function targetField(step) {
-  if (typeof step.target === 'string') return code(step.target);
-  return codeField(step, 'selector');
-}
-const BUILDERS = {
-  goto: step => [word('Go to'), codeField(step, 'url')],
-  click: step => [word('Click'), targetField(step)],
-  fill: step => [word('Fill'), targetField(step), word('with'), codeField(step, 'value')],
-  press: step => [word('Press'), codeField(step, 'key'), word('in'), targetField(step)],
-  select: step => [word('Choose'), selectChoice(step), word('in'), targetField(step)],
-  scroll: step => [word('Scroll to'), codeField(step, 'to')],
-  wait: step => [word('Wait for'), waitFor(step)],
-  screenshot: step => [word('Screenshot'), codeField(step, 'path')],
-  request: step => [word('Request'), code(`${typeof step.method === 'string' ? step.method : 'GET'} `), codeField(step, 'url')],
-  extract: step => [word('Read'), pillField(step, 'id', '(unnamed)'), word('from'), pillField(step, 'from', 'page'), word('←'), codeField(step, 'selector')],
-  set: step => [word('Set'), pillField(step, 'id', '(unnamed)'), word('to'), codeField(step, 'value')],
-  collect: step => [word('Collect'), codeField(step, 'value'), word('into'), pillField(step, 'into', '(unnamed)')],
-  forEach: step => forEachSentence(step),
-  paginate: step => paginateSentence(step),
-  if: step => [word('If'), codeField(step, 'test')],
-  emit: step => emitSentence(step)
-};
-function selectChoice(step) {
-  if (typeof step.value === 'string') return code(step.value);
-  if (typeof step.label === 'string') return code(step.label);
-  if (typeof step.index === 'number') return code(String(step.index));
-  if (Array.isArray(step.values)) return code(step.values.join(', '));
-  return code('');
-}
-function waitFor(step) {
-  if (typeof step.selector === 'string') return code(step.selector);
-  if (typeof step.ms === 'number') return code(`${step.ms}ms`);
-  if (typeof step.state === 'string') return code(step.state);
-  return code('');
-}
-function forEachSentence(step) {
-  const parts = [word('For each'), pillField(step, 'as', '(item)'), word('in'), typeof step.over === 'string' ? pill(step.over) : targetField(step)];
-  if (step.emit !== undefined) parts.push(word('→'), word('one record'));
-  return parts;
-}
-function paginateSentence(step) {
-  const parts = [word('For every page')];
-  const next = step.next;
-  if (next !== null && typeof next === 'object') {
-    const record = next;
-    if (typeof record.selector === 'string') parts.push(word('via'), code(record.selector));else if (typeof record.url === 'string') parts.push(word('via'), code(record.url));else if (typeof record.jsonpath === 'string') parts.push(word('via'), code(record.jsonpath));
+    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;
   }
-  if (typeof step.until === 'string') parts.push(word('until'), code(step.until));
-  return parts;
-}
-function emitSentence(step) {
-  if (typeof step.output === 'string') return [word('Emit'), word('to'), pill(step.output)];
-  return [word('Emit')];
+}
+/** 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
+  };
 }
 
+/** A leaf element's own text longer than this is cut, with an ellipsis. */
+const TEXT_LIMIT = 80;
+/** Consecutive siblings whose subtree is identical (ids aside) collapse into one row once there are at least this many — a real page can have tens of thousands of `<li>`s, and showing all of them is not "inspecting" it (issue #93). */
+const MIN_REPEAT_RUN = 3;
 /**
- * Reads a recipe's `steps` as an outline. Works on whatever JSON parsed
- * (not a validated `InputRecipe`): a recipe mid-edit in the JSON tab may be
- * missing fields or have the wrong shape, and the outline still has to
- * render something rather than crash the tab. Anything that is not a
- * well-formed step becomes a custom card holding what was there; anything
- * that is not an object at the top becomes an outline with no steps.
+ * Builds the Inspect panel's DOM tree from a captured snapshot (studio plan
+ * §3.3, issue #93): the same rewritten, marked-up document the content pane's
+ * iframe shows (`page-snapshot`'s `take-snapshot.use-case.ts`), so a tree
+ * row's `nodeId` addresses exactly the element the iframe would highlight —
+ * no separate capture, per issue #93's scope note to reuse phase 2's
+ * snapshot rather than recapture.
  *
- * @param content - The recipe's parsed JSON (the JSON tab's own `JSON.parse` of its text).
- * @returns The outline: the untouched top-level record plus the step tree.
+ * @param snapshotHtml - The cached, rewritten snapshot (`SnapshotResult.html`).
+ * @returns The tree's root (the document's `<html>` element).
+ * @throws Error when the document has no `<html>` element (should not happen: `rewriteDocument` always produces one).
  */
-function recipeToOutline(content) {
-  const recipe = isRecord(content) ? content : {};
-  const steps = Array.isArray(recipe.steps) ? recipe.steps : [];
-  return {
-    recipe,
-    steps: stepsToNodes(steps, 'steps')
-  };
-}
-function stepsToNodes(steps, pathPrefix) {
-  return steps.map((step, index) => stepToNode(step, `${pathPrefix}.${index}`));
+function domTree(snapshotHtml) {
+  const $ = load(snapshotHtml);
+  const html = $('html').get(0);
+  if (html === undefined) throw new Error('domTree: the snapshot has no <html> element');
+  return buildNode($, html);
 }
-function stepToNode(step, path) {
-  if (!isRecord(step)) {
-    return {
-      kind: 'card',
-      path,
-      stepType: 'unknown',
-      sentence: [{
-        kind: 'word',
-        text: 'custom step'
-      }],
-      step: {},
-      custom: true
-    };
-  }
-  const stepType = typeof step.type === 'string' ? step.type : 'unknown';
-  const {
-    parts,
-    custom
-  } = cardSentence(step);
-  if (!isBracketStepType(stepType)) return {
-    kind: 'card',
-    path,
-    stepType,
-    sentence: parts,
-    step,
-    custom
+function buildNode($, element) {
+  const $el = $(element);
+  const attributes = {
+    ...element.attribs
   };
-  const children = Array.isArray(step.steps) ? stepsToNodes(step.steps, `${path}.steps`) : [];
-  const elseChildren = stepType === 'if' && Array.isArray(step.else) ? stepsToNodes(step.else, `${path}.else`) : undefined;
+  const nodeId = attributes[NODE_ID_ATTRIBUTE] ?? '';
+  const hidden = attributes[HIDDEN_ATTRIBUTE] === '1';
+  delete attributes[NODE_ID_ATTRIBUTE];
+  delete attributes[HIDDEN_ATTRIBUTE];
+  const id = attributes.id;
+  const classes = (attributes.class ?? '').split(/\s+/).filter(token => token !== '');
+  const childElements = $el.children().toArray();
+  const children = collapseRepeats(childElements.map(child => buildNode($, child)));
+  const text = childElements.length === 0 ? abbreviate($el.text()) : undefined;
   return {
-    kind: 'bracket',
-    path,
-    stepType,
-    sentence: parts,
-    step,
-    children,
-    ...(elseChildren !== undefined && {
-      elseChildren
-    })
+    nodeId,
+    tag: element.tagName.toLowerCase(),
+    ...(id !== undefined && id !== '' && {
+      id
+    }),
+    ...(classes.length > 0 && {
+      classes
+    }),
+    attributes,
+    ...(text !== undefined && text !== '' && {
+      text
+    }),
+    hidden,
+    children
   };
 }
-function isRecord(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Merges runs of `MIN_REPEAT_RUN` or more consecutive siblings whose subtree
+ * is identical (their own `nodeId`s aside) into one representative row, the
+ * issue's `×20` — real pages have tens of thousands of nodes, and this is
+ * what makes the tree usable rather than merely correct.
+ *
+ * @param nodes - Already-built sibling rows, in document order.
+ * @returns The same rows, with each long-enough identical run replaced by one.
+ */
+function collapseRepeats(nodes) {
+  const result = [];
+  let at = 0;
+  while (at < nodes.length) {
+    const signature = signatureOf(nodes[at]);
+    let end = at + 1;
+    while (end < nodes.length && signatureOf(nodes[end]) === signature) end += 1;
+    const run = nodes.slice(at, end);
+    if (run.length >= MIN_REPEAT_RUN) {
+      result.push({
+        ...run[0],
+        repeatCount: run.length,
+        repeatNodeIds: run.map(node => node.nodeId)
+      });
+    } else {
+      result.push(...run);
+    }
+    at = end;
+  }
+  return result;
+}
+/** A run member's identity for collapsing: everything but its own `nodeId` (every instance has a different one by construction). */
+function signatureOf(node) {
+  return JSON.stringify({
+    ...node,
+    nodeId: undefined,
+    children: node.children.map(child => signatureOf(child))
+  });
+}
+function abbreviate(text) {
+  const trimmed = text.trim().replaceAll(/\s+/g, ' ');
+  return trimmed.length > TEXT_LIMIT ? `${trimmed.slice(0, TEXT_LIMIT)}…` : trimmed;
 }
 
+/** The global names sites hydrate state into, that `describeHtml`'s own JSON-LD/table scan does not cover (issue #93's "inline state assignments"). */
+const INLINE_STATE_NAMES = ['__NEXT_DATA__', '__NUXT__', '__INITIAL_STATE__', '__APOLLO_STATE__', '__PRELOADED_STATE__', '__STATE__'];
+const INLINE_STATE_PATTERN = new RegExp(String.raw`(?:window\.)?(${INLINE_STATE_NAMES.join('|')})\s*=`);
 /**
- * Rebuilds a recipe from its outline: `recipe`'s keys, in their original
- * order, with `steps` (when the recipe had one) replaced by the outline's
- * (possibly edited) step tree. A card's own raw `step` is used as-is; a
- * bracket's `step` supplies every field but `steps`/`else`, which come from
- * `children`/`elseChildren` instead, put back at the position `step` itself
- * held that key at (or appended, for a bracket a `+` menu just added, whose
- * `step` never had one) — this, together with `recipe-to-outline.mapper.ts`
- * always keeping the step's whole original object, is what makes
- * `recipe → outline → recipe` preserve every key and its order.
+ * Finds the data-in-the-page findings the Inspect panel lists apart from the
+ * DOM tree (studio plan §3.3, issue #93): JSON-LD and `application/json`
+ * script blocks, inline state assignments, `<meta>` name/property values and
+ * `<link rel>`s — reusing `@opencraw/probe`'s `describeJson` for a found
+ * value's shape (its own `find-data.algorithm.ts`/`html-findings.mapper.ts`
+ * scan a page's raw text for *reporting*, with no element to point a pick at;
+ * this function's own job — locating each finding's element so a pick can
+ * reach it — is new).
  *
- * @param outline - An outline, from `recipe-to-outline.mapper.ts` or edited by the UI.
- * @returns The recipe's plain JSON, ready for `save-recipe`.
+ * Takes the **raw** captured document, not the display snapshot
+ * (`page-snapshot`'s `SnapshotResult.html`): `rewriteDocument` strips every
+ * `<script>` for the sandboxed iframe, which would make JSON-LD, inline
+ * state and other script-tag data invisible here. `<meta>`/`<link>` survive
+ * rewriting untouched, so using the raw document for every kind (rather than
+ * mixing two documents) keeps this function simple and its selectors
+ * verified against what the engine will actually crawl.
+ *
+ * @param rawHtml - The document as fetched/rendered, before `rewriteDocument` strips scripts.
+ * @returns The findings, in document order.
  */
-function outlineToRecipe(outline) {
-  if (!('steps' in outline.recipe) && outline.steps.length === 0) return {
-    ...outline.recipe
-  };
-  return {
-    ...outline.recipe,
-    steps: nodesToSteps(outline.steps)
-  };
+function pageData(rawHtml) {
+  const $ = load(rawHtml);
+  const findings = [];
+  $('script[type="application/ld+json"]').each((_index, element) => {
+    findings.push(...scriptFinding($, element, rawHtml, 'ld-json', ldJsonLabel));
+  });
+  $('script[type="application/json"]').each((_index, element) => {
+    findings.push(...scriptFinding($, element, rawHtml, 'json-script', () => `json: ${structuralSelector($, element)}`));
+  });
+  $('script').each((_index, element) => {
+    const type = $(element).attr('type');
+    if (type !== undefined && type !== 'text/javascript' && type !== 'module') return;
+    const text = $(element).text();
+    const match = INLINE_STATE_PATTERN.exec(text);
+    if (match === null) return;
+    const value = tryParseJson(text);
+    const selector = structuralSelector($, element);
+    findings.push({
+      kind: 'inline-state',
+      label: match[1],
+      selector,
+      selectorKind: 'css',
+      matches: countMatches(rawHtml, selector),
+      keys: keysOf(value)
+    });
+  });
+  $('meta[name], meta[property]').each((_index, element) => {
+    const name = $(element).attr('name') ?? $(element).attr('property') ?? '';
+    const selector = structuralSelector($, element);
+    findings.push({
+      kind: 'meta',
+      label: `meta: ${name}`,
+      selector,
+      selectorKind: 'css',
+      matches: countMatches(rawHtml, selector),
+      attribute: 'content'
+    });
+  });
+  $('link[rel]').each((_index, element) => {
+    const rel = $(element).attr('rel') ?? '';
+    const selector = structuralSelector($, element);
+    findings.push({
+      kind: 'link',
+      label: `link: ${rel}`,
+      selector,
+      selectorKind: 'css',
+      matches: countMatches(rawHtml, selector),
+      attribute: 'href'
+    });
+  });
+  return findings;
 }
-function nodesToSteps(nodes) {
-  return nodes.map(node => nodeToStep(node));
+function scriptFinding($, element, rawHtml, kind, labelOf) {
+  const value = tryParseJson($(element).text());
+  if (value === undefined) return [];
+  const selector = structuralSelector($, element);
+  return [{
+    kind,
+    label: labelOf(value),
+    selector,
+    selectorKind: 'css',
+    matches: countMatches(rawHtml, selector),
+    keys: keysOf(value)
+  }];
 }
-function nodeToStep(node) {
-  if (!isBracket(node)) return node.step;
-  const keys = Object.keys(node.step);
-  const step = {};
-  for (const key of keys) {
-    if (key === 'steps') step.steps = nodesToSteps(node.children);else if (key === 'else' && node.stepType === 'if') step.else = nodesToSteps(node.elseChildren ?? []);else step[key] = node.step[key];
+function ldJsonLabel(value) {
+  if (Array.isArray(value)) return `ld+json: array (${value.length})`;
+  if (typeof value === 'object' && value !== null) {
+    const type = value['@type'];
+    if (typeof type === 'string') return `ld+json: ${type}`;
   }
-  if (!keys.includes('steps')) step.steps = nodesToSteps(node.children);
-  if (node.stepType === 'if' && node.elseChildren !== undefined && !keys.includes('else')) step.else = nodesToSteps(node.elseChildren);
-  return step;
+  return `ld+json: ${describeJson(value, 'json').type}`;
+}
+function keysOf(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? Object.keys(value) : undefined;
 }
-
 /**
- * Opens a recipe folder: every `.json`/`.jsonl` recipe directly inside it
- * (core's own directory reading, so relative `file:` URLs resolve the same
- * way a real run would), parsed and, for each output recipe found, bound to
- * the input recipes that name it. Nothing throws for a bad recipe or a
- * recipe that does not bind: every problem is reported on its file with the
- * JSON path core already computes, exactly as `opencraw validate` prints it.
+ * A unique CSS path for an element with no stable attribute of its own
+ * (a `<script>` tag has no id or class to speak of): `<ancestor> > tag`
+ * from `<html>` down, `:nth-of-type` added only where a tag has siblings of
+ * the same name under the same parent. Always resolves to exactly one
+ * element, on the raw document this ran against and on the real page (a
+ * purely structural selector, unaffected by the snapshot's own rewriting).
  *
- * @param folder - The workspace folder.
- * @returns Every recipe file found, each with its validation and binding issues.
- * @throws Error when the folder does not exist or cannot be read.
+ * @param $ - The document.
+ * @param element - The element to address.
+ * @returns The selector.
  */
-async function openWorkspace(folder) {
-  const documents = await readRecipeSource(folder);
-  const entries = documents.map(document => parseDocument(document));
-  const outputs = entries.filter(isParsed('output'));
-  const inputs = entries.filter(isParsed('input'));
-  for (const output of outputs) bindOutput(output, inputs);
-  for (const input of inputs) {
-    if (outputs.every(output => output.recipe.id !== input.recipe.output)) {
-      input.issues.push({
-        path: 'output',
-        message: `no output recipe "${input.recipe.output}" in this workspace`,
-        kind: 'binding'
-      });
-    }
+function structuralSelector($, element) {
+  const segments = [];
+  let $current = $(element);
+  while ($current.length > 0) {
+    const tag = $current.prop('tagName')?.toLowerCase();
+    if (tag === undefined) break;
+    const $parent = $current.parent();
+    const siblingsOfType = $parent.length > 0 ? $parent.children(tag) : $current;
+    const index = siblingsOfType.toArray().indexOf($current.get(0)) + 1;
+    segments.unshift(siblingsOfType.length > 1 ? `${tag}:nth-of-type(${index})` : tag);
+    if (tag === 'html' || $parent.length === 0) break;
+    $current = $parent;
   }
-  return {
-    folder,
-    recipes: entries.map(({
-      file,
-      kind,
-      id,
-      issues,
-      content
-    }) => ({
-      file,
-      kind,
-      id,
-      issues,
-      text: `${JSON.stringify(content, null, 2)}\n`,
-      // The Steps tab needs steps to render: an output/unknown file has none. recipeToOutline never
-      // throws, so this covers a file that fails validation too (its outline just has "custom" cards).
-      outline: kind === 'input' ? recipeToOutline(content) : undefined
-    }))
-  };
+  return segments.join(' > ');
 }
-/** Binds one output recipe to the inputs that name it, filing every binding issue back on the recipe it names. */
-function bindOutput(output, inputs) {
-  const matching = inputs.filter(input => input.recipe.output === output.recipe.id);
+
+/** How long the browser is given to settle after `goto`, watching for JSON responses (mirrors `packages/cli`'s `probe --browser`, `observeBrowserJson`). */
+const OBSERVE_MS = 4000;
+/** Responses kept, largest/most-recent-first ordering left to the caller; just a sane cap on what the panel lists. */
+const RESPONSE_LIMIT = 15;
+/**
+ * Records the JSON responses seen while an input recipe's start page
+ * rendered (studio plan §3.3, issue #93): the same technique `packages/cli`'s
+ * `probe --browser` uses (`observeBrowserJson`) — render the page, listen for
+ * `response` events whose content type is JSON, give it a few seconds to
+ * settle. Kept as its own capture, independent of `page-snapshot`'s
+ * `take-snapshot.use-case.ts`: that capture reads `page.content()` right
+ * after `goto` resolves, with no observation window, and changing its shape
+ * to also collect responses was a larger, riskier change to already-shipped,
+ * tested code than this phase's budget allowed (see this phase's final
+ * report) — so this opens its own short-lived browser session instead of
+ * piggy-backing on the cached snapshot.
+ *
+ * Only `"start"` is supported, mirroring `take-snapshot.use-case.ts`'s own
+ * reach; api-mode recipes have no page load to observe, so they always
+ * answer with an empty list rather than an error (there is nothing wrong
+ * with asking, the answer is just "none").
+ *
+ * @param input - The input recipe; only `mode` and the first `start` point are used.
+ * @param stepPath - The step to observe after, e.g. `"start"`.
+ * @param browser - Browser launch settings, shared with `take-snapshot`/`verify-selector`/`run-sample`.
+ * @returns The distinct JSON responses observed, at most `RESPONSE_LIMIT`.
+ * @throws Error when the recipe has no start point, or `stepPath` is not `"start"`.
+ */
+async function responsesSeen(input, stepPath, browser) {
+  if (stepPath !== 'start') throw new Error(`responsesSeen: "${stepPath}" is not supported yet — only "start" (the first start point, before any step ran) is`);
+  if (input.mode !== 'web') return [];
+  const point = input.start[0];
+  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
+  const client = await ensureBrowserLaunch(browser, () => BrowserClient.launch(browser));
   try {
-    bindRecipeSet(output.recipe, matching.map(input => input.recipe));
-  } catch (error) {
-    if (!(error instanceof RecipeBindingError)) throw error;
-    for (const issue of error.issues) {
-      const target = issue.recipeId === output.recipe.id ? output : matching.find(input => input.recipe.id === issue.recipeId);
-      target?.issues.push({
-        path: issue.path,
-        message: issue.message,
-        kind: 'binding'
+    const session = await client.newSession();
+    try {
+      const responses = [];
+      const seen = new Set();
+      const pending = [];
+      session.page.on('response', response => {
+        if (!(response.headers()['content-type'] ?? '').includes('json')) return;
+        const key = `${response.status()} ${response.url()}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        pending.push(recordResponse(response, responses));
       });
+      try {
+        await session.page.goto(point.url, {
+          waitUntil: 'networkidle'
+        });
+      } catch {
+        // a page that never idles (long-poll, websocket) still yields whatever was observed by the timeout below
+      }
+      await session.page.waitForTimeout(OBSERVE_MS);
+      await Promise.all(pending);
+      return responses.slice(0, RESPONSE_LIMIT);
+    } finally {
+      await session.close();
     }
+  } finally {
+    await client.close();
   }
 }
-function isParsed(kind) {
-  return entry => entry.kind === kind && entry.recipe !== undefined;
-}
-function parseDocument(document) {
-  const kind = document.content?.kind;
-  if (kind === 'output') return parseOne(document.source, document.content, 'output', parseOutputRecipe);
-  if (kind === 'input') return parseOne(document.source, document.content, 'input', parseInputRecipe);
-  return {
-    file: document.source,
-    kind: 'unknown',
-    content: document.content,
-    issues: [{
-      path: 'kind',
-      message: '"kind" is missing or not "input"/"output"',
-      kind: 'validation'
-    }]
-  };
-}
-function parseOne(file, content, kind, parse) {
+/** Reads one response's body, when it still can be (not aborted, not redirected away); a response that cannot be read is silently left out rather than failing the whole capture. */
+async function recordResponse(response, into) {
   try {
-    const recipe = parse(content, file);
-    return {
-      file,
-      kind,
-      content,
-      id: recipe.id,
-      issues: [],
-      recipe
-    };
-  } catch (error) {
-    if (!(error instanceof RecipeValidationError)) throw error;
-    return {
-      file,
-      kind,
-      content,
-      issues: error.issues.map(issue => ({
-        path: issue.path === '' ? '(root)' : issue.path,
-        message: issue.message,
-        kind: 'validation'
-      }))
-    };
+    const body = await response.text();
+    const value = tryParseJson(body);
+    into.push({
+      url: response.url(),
+      status: response.status(),
+      size: body.length,
+      shape: value === undefined ? 'text' : describeJson(value, 'json').type
+    });
+  } catch {
+    // response body unavailable (aborted, redirected, the page navigated away) — skip it
   }
 }
 
 /**
- * Writes a recipe back to its file: pretty JSON, a 2-space indent, a
- * trailing newline. Phase 0 takes the JSON tab's whole parsed object rather
- * than a patch, so this is a full replacement, not a splice: loading a file
- * the studio has not touched and saving it again keeps every key, value and
- * key order (`JSON.parse` preserves insertion order, and `JSON.stringify`
- * writes it back), but not necessarily the file's exact original formatting
- * (alignment, how arrays wrap, a trailing comment). Byte-identical
- * round-trip for a hand-formatted file is future work; see this file's test
- * for what is guaranteed today.
+ * Handles `inspect-page`: the Inspect panel's DOM tree and data-in-the-page
+ * findings, off the same cached snapshot `take-snapshot`/`infer-selector`
+ * already use (`page-inspector`, issue #93). `domTree` reads the cached,
+ * rewritten snapshot (the same markup the content pane's iframe shows, so a
+ * tree row's `nodeId` lines up with it exactly); `pageData` reads the raw
+ * capture (`SnapshotResult.rawHtml`), since the display snapshot has had its
+ * `<script>` tags stripped for the sandboxed iframe.
  *
- * @param path - The recipe file to write.
- * @param recipe - The whole recipe object.
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The tree and the data-in-the-page findings.
+ * @throws Error when no workspace is open, or `command.path` has no cached snapshot yet.
  */
-async function saveRecipe(path, recipe) {
-  await writeFile(path, `${JSON.stringify(recipe, null, 2)}\n`, 'utf8');
+function handleInspectPage(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`);
+  return {
+    tree: domTree(snapshot.html),
+    pageData: pageData(snapshot.rawHtml)
+  };
 }
 
 /** Where the studio's own recorder profile lives when `StudioServerOptions.recorderProfileDir` is not given: never a crawl's own `session.browserProfile` directory, never the person's default browser profile. */
@@ -3537,7 +3709,14 @@ function broadcast(state, event) {
 /**
  * Handles `open-workspace`: reads the folder, remembers it as the server's
  * current workspace (every later command that names a recipe resolves it
- * against this folder), and tells every connected client the workspace changed.
+ * against this folder), and, when that is a different folder than before,
+ * tells every connected client the workspace changed.
+ *
+ * Only on an actual switch: the UI answers `workspace-changed` with another
+ * `open-workspace` of the same folder (its workspace query re-fetches), so a
+ * broadcast on every open would answer that re-fetch with another broadcast,
+ * for ever — and each round cancels the fetch in flight, so a recipe saved
+ * meanwhile never showed up in the listing (found by issue #120's drop flow).
  *
  * @param state - The server state to update.
  * @param command - The command.
@@ -3545,8 +3724,9 @@ function broadcast(state, event) {
  */
 async function handleOpenWorkspace(state, command) {
   const view = await openWorkspace(command.folder);
+  const switched = state.folder !== command.folder;
   state.folder = command.folder;
-  broadcast(state, {
+  if (switched) broadcast(state, {
     type: 'workspace-changed'
   });
   return view;
@@ -4319,6 +4499,26 @@ async function handleResponsesSeen(state, command) {
   };
 }
 
+/**
+ * Handles `region-preview`: the PDF and deck canvases' live preview of a
+ * `region` extract's selector (`document-view`'s
+ * `region-preview.use-case.ts`, issues #121 and #122), off the same cached
+ * snapshot `take-snapshot` already captured — a pure computation over it,
+ * so this answers instantly on every change of the box, no re-fetch or
+ * re-parse (mirrors `table-preview.handler.ts`).
+ *
+ * @param state - The server state.
+ * @param command - The command; `command.path` must already have a cached snapshot (call `take-snapshot` first).
+ * @returns The matches, or `error` when the selector does not parse or does not fit the document.
+ * @throws Error when `command.path` has no cached snapshot yet, or the snapshot is neither a PDF nor a deck.
+ */
+function handleRegionPreview(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`);
+  if (!isPdfDocument(snapshot.body) && !isDeckDocument(snapshot.body)) throw new Error(`"${command.recipeId}" at "${command.path}" is neither a PDF nor a deck snapshot: region-preview only reads a read PDF or PowerPoint document`);
+  return previewRegion(snapshot.body, command.selector);
+}
+
 /**
  * Handles `run-sample`: stops whatever sample was still running (one run at
  * a time), starts the new one, and returns once it has started, not once it
@@ -4806,6 +5006,10 @@ function dispatch(command, state) {
       {
         return handleOpenWorkspace(state, command);
       }
+    case 'import-document':
+      {
+        return handleImportDocument(command);
+      }
     case 'run-sample':
       {
         return handleRunSample(state, command);
@@ -4862,6 +5066,10 @@ function dispatch(command, state) {
       {
         return Promise.resolve(handleTablePreview(state, command));
       }
+    case 'region-preview':
+      {
+        return Promise.resolve(handleRegionPreview(state, command));
+      }
     case 'grid-view':
       {
         return handleGridView(state, command);
@@ -4942,5 +5150,5 @@ async function main(argv) {
   process.on('SIGTERM', shutdown);
 }
 
-export { deckChartSeriesViewSchema, deckChartViewSchema, deckDocumentViewSchema, deckPreviewCommandSchema, deckPreviewOptionsSchema, deckShapeViewSchema, deckSlideViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, deckViewCommandSchema, documentTreeCommandSchema, documentTreeNodeViewSchema, documentTreeViewSchema, domTreeNodeViewSchema, explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, gridCellViewSchema, gridMergeViewSchema, gridPreviewCommandSchema, gridPreviewOptionsSchema, gridSheetViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, gridViewCommandSchema, inferSelectorCommandSchema, inferSelectorViewSchema, inspectPageCommandSchema, inspectViewSchema, loadRecipePair, main, missingWhyTargetSchema, observedResponseSchema, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, pageDataFindingSchema, pdfCellViewSchema, pdfDocumentViewSchema, pdfPageViewSchema, pdfRowViewSchema, pdfViewCommandSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, recordRejectedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, rejectedWhyTargetSchema, responsesSeenCommandSchema, responsesSeenViewSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startRecordingCommandSchema, startStudioServer, stopRecordingCommandSchema, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, tablePreviewBandSchema, tablePreviewCommandSchema, tablePreviewMatchSchema, tablePreviewOptionsSchema, tablePreviewTableSchema, tablePreviewViewSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, whyTargetSchema, whyViewSchema, workbookDocumentViewSchema, workspaceChangedEventSchema, workspaceViewSchema };
+export { deckChartSeriesViewSchema, deckChartViewSchema, deckDocumentViewSchema, deckPreviewCommandSchema, deckPreviewOptionsSchema, deckShapeViewSchema, deckSlideViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, deckViewCommandSchema, documentTreeCommandSchema, documentTreeNodeViewSchema, documentTreeViewSchema, domTreeNodeViewSchema, explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, gridCellViewSchema, gridMergeViewSchema, gridPreviewCommandSchema, gridPreviewOptionsSchema, gridSheetViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, gridViewCommandSchema, importDocument, importDocumentCommandSchema, importDocumentViewSchema, inferSelectorCommandSchema, inferSelectorViewSchema, inspectPageCommandSchema, inspectViewSchema, loadRecipePair, main, missingWhyTargetSchema, observedResponseSchema, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, pageDataFindingSchema, pdfCellViewSchema, pdfDocumentViewSchema, pdfPageViewSchema, pdfRowViewSchema, pdfViewCommandSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, recordRejectedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, rejectedWhyTargetSchema, responsesSeenCommandSchema, responsesSeenViewSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startRecordingCommandSchema, startStudioServer, stopRecordingCommandSchema, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, tablePreviewBandSchema, tablePreviewCommandSchema, tablePreviewMatchSchema, tablePreviewOptionsSchema, tablePreviewTableSchema, tablePreviewViewSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, whyTargetSchema, whyViewSchema, workbookDocumentViewSchema, workspaceChangedEventSchema, workspaceViewSchema };
 //# sourceMappingURL=index.esm.js.map