sitelooper 0.3.0

package/dist/spec/emit.js

@@ -0,0 +1,2084 @@
+import { TRANSIENT_LINE } from '../skills/compile.js';
+import { OPENER_LINE, consequentialExpectations, waitsForAbsence } from '../skills/replay.js';
+import { candidateSources, chainSource, maskedMatcherSource, matcherSource, stringSource } from './locators.js';
+import { diagnosticNote, formatDiagnostic } from './diagnostics.js';
+/**
+ * The diagnostics that belong ABOVE a step's body, per flow step id.
+ *
+ * Only the record-level ones: a demoted pin and a record-time no-op are both
+ * "this recording is wrong", which is exactly what a reader of the generated
+ * file cannot otherwise tell from a locator error. A rethread warning is about
+ * a binding, not about the step's existence, and belongs in the compile
+ * report, not in every reviewer's diff.
+ */
+const FLAGGED = ['demoted-pin', 'noop-step'];
+function flaggedByStep(diagnostics) {
+    const out = new Map();
+    for (const d of diagnostics ?? []) {
+        if (!d.step || !FLAGGED.includes(d.code))
+            continue;
+        out.set(d.step, [...(out.get(d.step) ?? []), d]);
+    }
+    return out;
+}
+/**
+ * The one-line note a FLAGGED step's failure carries, or none.
+ *
+ * WHY. fwod34's 08-open is pinned to a demoted skill whose first action clicks
+ * a Cancel button that no longer exists, and the emitted spec said only "none
+ * of 3 recorded locators resolved" — which reads as app drift and sends the
+ * reader hunting for a changed selector. The step's own error is the one place
+ * the reader is guaranteed to look, so the reason and the fix go there too.
+ * Only a demoted pin: a no-op step still replays, so failing it with that note
+ * would be a guess about a failure it did not cause.
+ */
+function stepNote(flagged) {
+    const d = flagged?.find((x) => x.code === 'demoted-pin');
+    return d ? diagnosticNote(d) : undefined;
+}
+/** Markers LIFT reads the FLOW constant back out of. Changing either breaks the round trip. */
+const BEGIN_MARKER = '// @sitelooper-flow-begin';
+const END_MARKER = '// @sitelooper-flow-end';
+/**
+ * What the inlined `pick` waits, mirroring replay's own resolve window
+ * (resolveWaitMs / RESOLVE_POLL_MS): a spec has no observation turns, and an
+ * app that renders a beat late is the normal case, not a failure.
+ */
+const PICK_WAIT_MS = 3_000;
+const PICK_POLL_MS = 100;
+/**
+ * What the inlined `urlPartsWhen` waits for the url a step navigated TO.
+ *
+ * Longer than `pick`'s window because that is what replay effectively allows a
+ * url: runOneStep lets the DOM go quiet first (settleDom, capped at 2s) and
+ * only then does `expectedUrl` poll for another resolveWaitMs (3s) before it
+ * judges the url wrong. A spec that gave up after 3s bound an EMPTY part and
+ * built a pattern that could never match — odoo populates `action=` late, and
+ * fwod34's 01-signin asserted `#action=&cids=1&menu_id=81` against a browser
+ * that was, a beat later, exactly where the recording left it.
+ */
+const URL_WAIT_MS = 5_000;
+/** How long a segment's identity marker has to appear before the segment is on the wrong record. */
+const IDENTITY_WAIT_MS = 5_000;
+/**
+ * What the inlined `settle` waits, mirroring replay's `settleDom` constants
+ * exactly (SETTLE_QUIET_MS / SETTLE_MAX_MS / SETTLE_PROBE_MS in
+ * src/skills/replay.ts): a page shows it is busy within the probe, must then
+ * be mutation-free for the quiet window, and is called quiet after the cap
+ * whatever it is still doing.
+ */
+const SETTLE_QUIET_MS = 250;
+const SETTLE_MAX_MS = 2_000;
+const SETTLE_PROBE_MS = 60;
+/** Playwright's own default; only a different timeout is worth carrying over. */
+const DEFAULT_WAIT_MS = 10_000;
+/** How long a recorded template may run inside a generated comment. */
+const COMMENT_CLIP = 120;
+/** How far a chain's `.or(` continuation lines sit in from the statement that opens them. */
+const CONT_INDENT = '  ';
+/** Default iterations a folded loop may run when the recording set no cap. */
+const DEFAULT_LOOP_MAX = 20;
+const clip = (s, max = COMMENT_CLIP) => (s.length <= max ? s : s.slice(0, max) + '…');
+/** One line of comment text: no newlines, and nothing that would close a doc comment. */
+const commentSafe = (s) => clip(String(s).replace(/\s+/g, ' ').replace(/\*\//g, '* /').trim(), 200);
+/** A slot marker anywhere in the text — the mark of a value this run supplies. */
+const SLOT_LINE = /\{\{v\d+\}\}/;
+/** How a recorded slot renders inside generated source: as the step's own param. */
+const slotAsParam = (s) => '${p.' + s + '}';
+/** A JS single-quoted literal (mirrors recorder.q, which this module cannot import without pulling in playwright types). */
+function q(value) {
+    return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\r/g, '').replace(/\n/g, '\\n')}'`;
+}
+/** An object key as source: bare when it is an identifier, quoted otherwise. */
+function key(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : q(name);
+}
+/** Literal text inside a template literal: a backtick or a `${` would end it or open a hole. */
+function templateSafe(text) {
+    return text.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Per-tier budget for the inlined `click` helper, mirroring the 10s
+ * `timeout` tools.ts hands robustClick, but cut so that ALL THREE tiers plus
+ * the scroll ahead of tier 2 fit well inside a default 60s Playwright test:
+ * grafana's viz-picker burned the whole 60s on tier 1 alone before this.
+ */
+const CLICK_TIER_MS = 5_000;
+/**
+ * What the inlined `fill` waits, mirroring reactSafeFill in
+ * src/daemon/inputs.ts: the field must be visible (its own 10s), and the focus
+ * click is a best-effort 5s that some widgets need and most ignore.
+ */
+const FILL_WAIT_MS = 10_000;
+const FILL_FOCUS_MS = 5_000;
+/**
+ * The two settles inside the editor recipe, taken from `editorSetValue` in
+ * src/skills/components.ts verbatim: 400ms for the insert to be absorbed
+ * before Escape, 200ms after the blur for the commit the app hangs off it.
+ */
+const EDITOR_SETTLE_MS = 400;
+const EDITOR_BLUR_SETTLE_MS = 200;
+/** The inlined helpers, keyed by the token that proves the body (or another helper) uses one. */
+const HELPERS = [
+    {
+        // Shared by `pick` and `urlPartsWhen`: one poll cadence. The token is the
+        // POLL constant, because that is the one BOTH of them name.
+        token: 'PICK_POLL_MS',
+        source: [`const PICK_WAIT_MS = ${PICK_WAIT_MS};`, `const PICK_POLL_MS = ${PICK_POLL_MS};`],
+    },
+    {
+        token: 'await settle(',
+        source: [
+            `const SETTLE_QUIET_MS = ${SETTLE_QUIET_MS};`,
+            `const SETTLE_MAX_MS = ${SETTLE_MAX_MS};`,
+            `const SETTLE_PROBE_MS = ${SETTLE_PROBE_MS};`,
+            '/**',
+            ' * Let the DOM go quiet before this step looks at the page at all.',
+            ' *',
+            " * WHICH REPLAY RULE THIS MIRRORS. runOneStep's very first act, before the",
+            ' * already-in-effect check and before any chain is resolved, is',
+            ' * `await settleDom(page)` (src/skills/replay.ts): the agent that recorded',
+            ' * the flow had observation turns, which were implicit waits, and a replay',
+            ' * — or a spec — has none. Same constants: a page gets SETTLE_PROBE_MS to',
+            ' * show it is busy at all, then must be mutation-free for SETTLE_QUIET_MS,',
+            ' * and is called quiet regardless after SETTLE_MAX_MS. Instant on a static',
+            ' * page, which is why it can sit on every step.',
+            ' *',
+            ' * WHY EVERY STEP NEEDS IT, not just the resolving ones. The odoo recording',
+            " * toggles the home menu open and shut seven times before clicking `Sales`.",
+            ' * Each toggle click is an opener, so each is guarded by "is the recorded',
+            ' * popup already showing?" — and asked in the same tick as the CLOSING click',
+            ' * that preceded it, that question is answered off a DOM still mid-transition:',
+            ' * the menu is on its way out but still visible, the guard says "already in',
+            ' * effect", the opening click is skipped, and eight steps later there is no',
+            " * `Sales` menuitem because the menu is shut. Replay never sees this, because",
+            ' * its own presence check happens only AFTER settleDom. So the settle goes',
+            ' * ahead of the guard, not merely ahead of the action.',
+            ' *',
+            ' * Errors are swallowed: a page that is navigating or detached cannot be',
+            ' * scripted, and that is the locator resolution\'s failure to report, not this.',
+            ' */',
+            'async function settle(page: Page): Promise<void> {',
+            '  try {',
+            '    await page.evaluate(',
+            '      ({ probe, quiet, max }: { probe: number; quiet: number; max: number }) =>',
+            '        new Promise<void>((resolve) => {',
+            '          let timer = setTimeout(resolve, probe);',
+            '          const stop = setTimeout(() => {',
+            '            observer.disconnect();',
+            '            resolve();',
+            '          }, max);',
+            '          const observer = new MutationObserver(() => {',
+            '            clearTimeout(timer);',
+            '            timer = setTimeout(() => {',
+            '              observer.disconnect();',
+            '              clearTimeout(stop);',
+            '              resolve();',
+            '            }, quiet);',
+            '          });',
+            '          observer.observe(document, { childList: true, subtree: true, attributes: true, characterData: true });',
+            '        }),',
+            '      { probe: SETTLE_PROBE_MS, quiet: SETTLE_QUIET_MS, max: SETTLE_MAX_MS },',
+            '    );',
+            '  } catch {',
+            '    // navigating / detached — the locator resolution will report it',
+            '  }',
+            '}',
+        ],
+    },
+    {
+        token: 'urlPart(',
+        source: [
+            '/**',
+            " * The addressable parts of a url, labelled as the recorder labels them:",
+            ' * path segments `p<i>`, hash-route segments `h<i>`, hash-state values `q.<key>`.',
+            ' * Inlined so the spec depends on nothing but Playwright.',
+            ' */',
+            'function urlPart(url: string, label: string): string {',
+            '  let u: URL;',
+            '  try {',
+            '    u = new URL(url);',
+            '  } catch {',
+            "    return '';",
+            '  }',
+            '  const dec = (s: string) => {',
+            '    try {',
+            '      return decodeURIComponent(s);',
+            '    } catch {',
+            '      return s;',
+            '    }',
+            '  };',
+            '  const parts: Record<string, string> = {};',
+            "  u.pathname.split('/').filter(Boolean).forEach((v, i) => (parts[`p${i}`] ??= dec(v)));",
+            "  const body = u.hash.length > 1 ? u.hash.slice(1).split('?')[0] : '';",
+            "  if (body.startsWith('/') || (body && !body.includes('='))) {",
+            "    body.split('/').filter(Boolean).forEach((v, i) => (parts[`h${i}`] ??= dec(v)));",
+            '  } else if (body) {',
+            "    for (const pair of body.split('&').filter(Boolean)) {",
+            "      const eq = pair.indexOf('=');",
+            '      const k = eq < 0 ? pair : pair.slice(0, eq);',
+            "      parts[`q.${k}`] ??= eq < 0 ? '' : dec(pair.slice(eq + 1));",
+            '    }',
+            '  }',
+            "  return parts[label] ?? '';",
+            '}',
+        ],
+    },
+    {
+        token: 'urlPartsWhen(',
+        source: [
+            `const URL_WAIT_MS = ${URL_WAIT_MS};`,
+            '/**',
+            ' * The url parts a step mints, read AFTER the navigation it started has landed.',
+            ' *',
+            ' * WHICH REPLAY RULE THIS MIRRORS. runOneStep captures the url before the',
+            ' * action and, when the action changed it, awaits settleDom before binding',
+            " * the step's derived values — the value a spec needs is the one on the url",
+            ' * the step navigated TO, and `page.url()` read in the same tick as the',
+            ' * click still says where the page came FROM. Bound empty, every pattern',
+            ' * built from these parts (`toHaveURL`, an identity marker) can only fail.',
+            ' *',
+            ' * ALL of them together, not one at a time, because they are read into ONE',
+            ' * pattern: an app is free to populate its state fragment key by key (odoo',
+            ' * lands on `#cids=1&menu_id=81` and adds `action=` a beat later), so a part',
+            ' * that binds the instant IT is non-empty can be bound off a half-built url',
+            ' * while its neighbour is still missing. The step is not where it was',
+            ' * recorded until every part is there.',
+            ' *',
+            ' * A spec has no settleDom, so it polls on `pick`\'s cadence within the window',
+            ' * replay effectively allows a url (URL_WAIT_MS), and takes one last reading',
+            ' * at the deadline: a step whose url genuinely does not change (the parts were',
+            ' * already there) must still bind what is there rather than hang or throw.',
+            ' */',
+            "async function urlPartsWhen(page: Page, labels: string[], urlBefore = ''): Promise<string[]> {",
+            '  const read = (url: string) => labels.map((label) => urlPart(url, label));',
+            '  for (let waited = 0; waited < URL_WAIT_MS; waited += PICK_POLL_MS) {',
+            '    const url = page.url();',
+            '    const values = read(url);',
+            '    if (url !== urlBefore && values.every(Boolean)) {',
+            '      // The parts are there — but an app is free to redirect AGAIN from',
+            '      // the url that first carried them, and the value that matters is',
+            '      // the one on the url the step SETTLES on. Replay never sees this,',
+            '      // because it binds derived values only after settleDom absorbs the',
+            '      // whole redirect chain. So: let the DOM go quiet, and if the url',
+            '      // moved while it did, settle once more before reading.',
+            '      for (let pass = 0; pass < 2; pass++) {',
+            '        const before = page.url();',
+            '        await settle(page);',
+            '        if (page.url() === before) break;',
+            '      }',
+            '      return read(page.url());',
+            '    }',
+            '    await page.waitForTimeout(PICK_POLL_MS);',
+            '  }',
+            '  return read(page.url());',
+            '}',
+        ],
+    },
+    {
+        token: 'urlPartWhen(',
+        source: [
+            '/** One part, on the same terms. `urlBefore` is omitted where no action of this step',
+            "  * moved the page: then the wait is simply for the part to be there at all, which is",
+            '  * what the flow runner does before it publishes a step\'s url outputs (consumedUrlOutputs). */',
+            "async function urlPartWhen(page: Page, label: string, urlBefore = ''): Promise<string> {",
+            '  return (await urlPartsWhen(page, [label], urlBefore))[0];',
+            '}',
+        ],
+    },
+    {
+        token: 'hashState(',
+        source: [
+            '/**',
+            ' * A query-shaped hash fragment (`#action=1&cids=2`, which is odoo) as its',
+            ' * key/value state, or null when the fragment is a route (`#/orders/7`) or',
+            ' * absent. Mirrors urlShapeOf in src/skills/compile.ts, decoding included.',
+            ' */',
+            'function hashState(href: string): Map<string, string> | null {',
+            '  let u: URL;',
+            '  try {',
+            '    u = new URL(href);',
+            '  } catch {',
+            '    return null;',
+            '  }',
+            "  const body = u.hash.length > 1 ? u.hash.slice(1).split('?')[0] : '';",
+            "  if (!body || body.startsWith('/') || !body.includes('=')) return null;",
+            '  const out = new Map<string, string>();',
+            "  for (const pair of body.split('&').filter(Boolean)) {",
+            "    const eq = pair.indexOf('=');",
+            '    const k = eq < 0 ? pair : pair.slice(0, eq);',
+            "    let v = eq < 0 ? '' : pair.slice(eq + 1);",
+            '    try {',
+            '      v = decodeURIComponent(v);',
+            '    } catch {',
+            '      // an invalid escape is data too: keep it raw',
+            '    }',
+            '    if (!out.has(k)) out.set(k, v);',
+            '  }',
+            '  return out;',
+            '}',
+        ],
+    },
+    {
+        token: 'hashMatch(',
+        source: [
+            '/**',
+            ' * A url expectation whose pattern carries a query-shaped hash, checked the',
+            ' * way replay checks it (urlDiff/urlMatches in src/skills/compile.ts) rather',
+            ' * than as one regex over the whole url.',
+            ' *',
+            ' * A state fragment is application STATE, and state has no ORDER: odoo emits',
+            " * `#action=316&cids=1&menu_id=194&model=sale.order` on one run and",
+            ' * `#action=316&model=sale.order&view_type=list&cids=1&menu_id=194` on the',
+            ' * next, and a regex fails on the reordering alone — which is the only thing',
+            " * wrong with fwod34's second cloud run. So: every pair the recording named",
+            ' * must be present with the same value, extra live pairs are fine (state',
+            ' * accumulates), and order means nothing. A `null` value is a `:id`/`:var`',
+            ' * wildcard — app-minted state, which urlDiff lets be anything or absent.',
+            ' *',
+            ' * The head (origin + path) keeps the regex form: a path IS ordered.',
+            ' */',
+            'function hashMatch(url: URL, head: RegExp, want: [string, string | null][]): boolean {',
+            '  if (!head.test(url.origin + url.pathname)) return false;',
+            '  const state = hashState(url.href);',
+            '  if (!state) return false;',
+            '  return want.every(([k, v]) => v === null || state.get(k) === v);',
+            '}',
+        ],
+    },
+    {
+        token: 'await click(',
+        source: [
+            '/**',
+            " * A click that lands, mirroring replay's robustClick (src/agent/tools.ts)",
+            ' * tier for tier, in the same order. A plain `locator.click()` waits for',
+            ' * actionability and NOTHING else, so a control an overlay covers — or one',
+            ' * the app re-mounts between frames — burns the whole test timeout on a',
+            ' * single attempt: grafana\'s `toggle-viz-picker` resolved fine and then sat',
+            ' * behind an `<svg>` in a `data-overlay-container` for 60s.',
+            ' *',
+            ' *  1. Playwright\'s own click, actionability checks and all. What a healthy',
+            ' *     app answers on, and the only tier that proves the control was really',
+            ' *     clickable the way a user would find it.',
+            ' *  2. Scrolled into view and FORCED past the checks. This is the overlay',
+            ' *     tier: a decorative layer that intercepts pointer events, or a sticky',
+            ' *     header over the target, is exactly what the checks refuse and what',
+            ' *     the app itself treats as fine.',
+            ' *  3. A synthetic DOM event dispatched at the element. React and friends',
+            " *     hang delegated handlers off the document, so they see this even when",
+            ' *     the element is not "clickable" by any geometric rule at all.',
+            ' *',
+            ' * Each tier gets its own bounded budget so all three (plus the scroll)',
+            ' * finish well inside one test timeout — replay could afford 10s a tier',
+            ' * because it had turns left afterwards; a spec has one shot.',
+            ' *',
+            ' * A strict-mode violation is rethrown at once, as robustClick does: two',
+            ' * matches is a locator that names the wrong thing, and no tier can fix it —',
+            ' * forcing or dispatching would just act on an arbitrary one of them.',
+            ' * Not mirrored: the re-render window tier (fireWhenAttached), which needs',
+            " * to poll element handles; tier 3's dispatch covers the same apps.",
+            ' */',
+            `const CLICK_TIER_MS = ${CLICK_TIER_MS};`,
+            'async function click(loc: Locator, opts: { dbl?: boolean } = {}): Promise<void> {',
+            '  const act = (o: { timeout: number; force?: boolean }) => (opts.dbl ? loc.dblclick(o) : loc.click(o));',
+            '  let firstFailure: unknown;',
+            '  try {',
+            '    return await act({ timeout: CLICK_TIER_MS });',
+            '  } catch (err) {',
+            '    firstFailure = err;',
+            "    if (/strict mode violation/i.test(err instanceof Error ? err.message : String(err))) throw err;",
+            '  }',
+            '  try {',
+            '    await loc.scrollIntoViewIfNeeded({ timeout: CLICK_TIER_MS }).catch(() => {});',
+            '    return await act({ timeout: CLICK_TIER_MS, force: true });',
+            '  } catch {',
+            '    // the overlay is a real one, or the element moved: fall through',
+            '  }',
+            '  try {',
+            '    await loc',
+            '      .first()',
+            '      .evaluate((el: Element, dbl: boolean) => {',
+            "        const fire = (type: string) => el.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true, view: window }));",
+            "        fire('click');",
+            '        if (dbl) {',
+            "          fire('click');",
+            "          fire('dblclick');",
+            '        }',
+            '      }, Boolean(opts.dbl));',
+            '  } catch {',
+            '    // Every tier lost. The FIRST failure is the one worth reporting: it says',
+            '    // what a normal click was actually waiting for.',
+            '    throw firstFailure;',
+            '  }',
+            '}',
+        ],
+    },
+    {
+        token: 'await fill(',
+        source: [
+            '/**',
+            ' * A fill the app actually SEES — mirror of daemon/inputs.ts reactSafeFill',
+            " * (which is how replay executes every recorded `fill`): Playwright's fill",
+            ' * fires only `input`, and apps that commit on `change` (Odoo, React',
+            " * controlled inputs) never see a plain fill. Odoo's sp4od run failed",
+            ' * deterministically on exactly that: `02-create s_c99d6c/6` filled a',
+            ' * quantity of 3, the field never committed, and the recorded row',
+            ' * ("20% £ 36.00") that the next expectation waits for never appeared.',
+            ' *',
+            ' * Same waits and the same event order as the daemon: visible, scrolled',
+            ' * into view, clicked for focus (both best-effort), then the NATIVE',
+            " * prototype value setter — the one React's value tracker cannot see",
+            ' * through — clear-then-set (a number input otherwise appends), an `input`',
+            ' * event after each set and a `change` after the last. An element with no',
+            ' * value property or no prototype setter (contenteditable, a custom',
+            " * widget) falls back to Playwright's own fill, exactly as the daemon does.",
+            ' *',
+            ' * But reactSafeFill is only the SECOND half of what replay does. The',
+            " * daemon's `case 'fill'` (src/agent/tools.ts) asks `tryRecipe(page, target,",
+            " * 'set-value', value)` FIRST (src/skills/components.ts), and only falls back",
+            ' * to reactSafeFill when no widget was recognised or the recipe could not',
+            ' * verify its own effect. That first half is what a keyboard-driven editor',
+            ' * needs: monaco has no value property to set — its `<textarea>` is an input',
+            ' * sink, and the text you see is a rendered `.view-lines` div — so the native',
+            ' * setter writes into a box the editor never reads. Local grafana run',
+            ' * `03-add s_e4d3e5/6` did exactly that: no error, and the saved text panel',
+            " * kept grafana's default markdown, so the objective failed on a step that",
+            ' * reported success. So the ladder is mirrored here too, recipe first.',
+            ' */',
+            `const FILL_WAIT_MS = ${FILL_WAIT_MS};`,
+            `const FILL_FOCUS_MS = ${FILL_FOCUS_MS};`,
+            `const EDITOR_SETTLE_MS = ${EDITOR_SETTLE_MS};`,
+            `const EDITOR_BLUR_SETTLE_MS = ${EDITOR_BLUR_SETTLE_MS};`,
+            '/**',
+            ' * The widget families whose set-value recipe a fill goes through, in the',
+            ' * FAMILIES order of src/skills/components.ts (most specific first —',
+            " * CodeMirror's .cm-content IS contenteditable, and monaco embeds a",
+            ' * textarea), with each recipe\'s click/blur/verify targets as the seeds',
+            ' * name them. `aria-combobox` is deliberately absent: it carries a',
+            ' * select-option recipe only, and never a set-value one.',
+            ' *',
+            ' * `up` is the same `closest(root)` walk expressed as a locator, so the',
+            ' * root can be CLICKED and READ rather than merely detected; the class',
+            ' * test is token-wise (`" monaco-editor "`), because `contains(@class,',
+            ' * "monaco-editor")` would also match `monaco-editor-background`.',
+            ' */',
+            'const EDITORS: { root: string; up: string; click?: string; blur?: string; read?: string }[] = [',
+            '  {',
+            "    root: '.monaco-editor',",
+            '    up: \'xpath=ancestor-or-self::*[contains(concat(" ", normalize-space(@class), " "), " monaco-editor ")]\',',
+            "    blur: 'textarea',",
+            "    read: '.view-lines',",
+            '  },',
+            '  {',
+            "    root: '.cm-editor',",
+            '    up: \'xpath=ancestor-or-self::*[contains(concat(" ", normalize-space(@class), " "), " cm-editor ")]\',',
+            "    click: '.cm-content',",
+            "    blur: '.cm-content',",
+            "    read: '.cm-content',",
+            '  },',
+            '  {',
+            "    root: '.ProseMirror',",
+            '    up: \'xpath=ancestor-or-self::*[contains(concat(" ", normalize-space(@class), " "), " ProseMirror ")]\',',
+            '  },',
+            '  {',
+            '    root: \'[contenteditable="true"]\',',
+            '    up: \'xpath=ancestor-or-self::*[@contenteditable="true"]\',',
+            '  },',
+            '];',
+            '/**',
+            ' * The set-value recipe, run with Playwright primitives — a transcription of',
+            ' * `editorSetValue` in src/skills/components.ts (click, ControlOrMeta+a,',
+            ' * insertText, settle 400, Escape, blur, settle 200) followed by the',
+            ' * verification read `verifyRecipe` makes: the family\'s verifyRead node must',
+            ' * re-observe the payload, whitespace-squashed (monaco renders spaces as',
+            ' * NBSP and rewraps lines). True only when it did — a recipe that cannot',
+            ' * prove its own effect is a failure, and the caller falls back, exactly as',
+            ' * `tryRecipe` does.',
+            ' */',
+            'async function editorSetValue(loc: Locator, value: string): Promise<boolean> {',
+            '  const which = await loc',
+            '    .evaluate((el: Element, roots: string[]) => roots.findIndex((sel) => Boolean(el.closest(sel))), EDITORS.map((e) => e.root))',
+            '    .catch(() => -1);',
+            '  if (which < 0) return false;',
+            '  const ed = EDITORS[which];',
+            '  const page = loc.page();',
+            '  const root = loc.locator(ed.up).last(); // ancestor-or-self is document order: nearest is last',
+            '  const within = (sel?: string) => (sel ? root.locator(sel).first() : root);',
+            '  try {',
+            '    await within(ed.click).click({ timeout: FILL_FOCUS_MS });',
+            "    await page.keyboard.press('ControlOrMeta+a');",
+            '    await page.keyboard.insertText(value);',
+            '    await page.waitForTimeout(EDITOR_SETTLE_MS);',
+            "    await page.keyboard.press('Escape');",
+            '    // A blur target the recipe names but the widget does not have is simply',
+            '    // skipped (stepHandle returns null, and the daemon blurs nothing).',
+            '    await within(ed.blur)',
+            '      .evaluate((el: Element) => (el as HTMLElement).blur?.())',
+            '      .catch(() => {});',
+            '    await page.waitForTimeout(EDITOR_BLUR_SETTLE_MS);',
+            '  } catch {',
+            '    return false; // a step that could not run at all: fall back',
+            '  }',
+            '  const seen = await within(ed.read)',
+            '    .evaluate((el: Element) => {',
+            '      const v = (el as HTMLInputElement).value;',
+            "      return typeof v === 'string' ? v : ((el as HTMLElement).innerText ?? el.textContent ?? '');",
+            '    })',
+            '    .catch(() => null);',
+            '  if (seen === null) return false;',
+            "  const squash = (s: string) => s.replace(/\\u00a0/g, ' ').replace(/\\s+/g, ' ').trim();",
+            '  return !value || squash(seen).includes(squash(value));',
+            '}',
+            'async function fill(loc: Locator, value: string): Promise<void> {',
+            "  await loc.waitFor({ state: 'visible', timeout: FILL_WAIT_MS });",
+            '  await loc.scrollIntoViewIfNeeded().catch(() => {});',
+            '  // The recipe half of the ladder, ahead of the native setter exactly as',
+            "  // tools.ts puts tryRecipe ahead of reactSafeFill. Verified, or nothing.",
+            '  if (await editorSetValue(loc, value)) return;',
+            '  await loc.click({ timeout: FILL_FOCUS_MS }).catch(() => {}); // focus; some widgets need it',
+            '  const handled = await loc.evaluate((el: Element, val: string) => {',
+            '    const input = el as HTMLInputElement | HTMLTextAreaElement;',
+            "    if (!('value' in input)) return false;",
+            '    const proto =',
+            '      input instanceof HTMLTextAreaElement',
+            '        ? HTMLTextAreaElement.prototype',
+            '        : input instanceof HTMLInputElement',
+            '          ? HTMLInputElement.prototype',
+            '          : null;',
+            '    if (!proto) return false;',
+            "    const setter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;",
+            '    if (!setter) return false;',
+            "    setter.call(input, ''); // clear-then-set: number inputs otherwise append",
+            "    input.dispatchEvent(new Event('input', { bubbles: true }));",
+            '    setter.call(input, val);',
+            "    input.dispatchEvent(new Event('input', { bubbles: true }));",
+            "    input.dispatchEvent(new Event('change', { bubbles: true }));",
+            '    return true;',
+            '  }, value);',
+            '  if (!handled) {',
+            '    // contenteditable or non-standard widget — fall back to Playwright fill',
+            '    await loc.fill(value);',
+            '  }',
+            '}',
+        ],
+    },
+    {
+        token: 'await select(',
+        source: [
+            '/**',
+            ' * An option chosen the way the daemon chooses it — mirror of',
+            ' * daemon/inputs.ts reactSafeSelect, which is how replay executes every',
+            ' * recorded `select`.',
+            ' *',
+            ' * The LABEL is what the procedure means ("the project I just created");',
+            " * the VALUE is whatever the app keys that option by, and apps mint those",
+            ' * per record as often as not — fwat3 03-add selected a project by its id,',
+            ' * and both replays timed out looking for an id that run never minted. So',
+            ' * the recording carries the visible label as `option` and the value it saw',
+            ' * only as `optionValue`, a last resort.',
+            ' *',
+            ' * Same order as the daemon, and it LOOKS before it waits: an option that',
+            ' * is present right now is taken at once (by label, else by value, else by',
+            ' * the recorded fallback value), so a stale fallback is never paid for with',
+            " * the label matcher's full timeout. Only when nothing matches yet does the",
+            ' * label form wait for options that may still be loading, and a plain',
+            ' * `selectOption(label)` — value/index matching — is the final attempt.',
+            ' */',
+            'async function select(loc: Locator, label: string, fallbackValue?: string): Promise<void> {',
+            '  const present = await loc',
+            '    .evaluate(',
+            '      (el: Element, [v, f]: [string, string]) => {',
+            '        if (!(el instanceof HTMLSelectElement)) return null;',
+            '        const opts = Array.from(el.options);',
+            "        if (opts.some((o) => o.label.trim() === v)) return 'label';",
+            "        if (opts.some((o) => o.value === v)) return 'value';",
+            "        if (f && opts.some((o) => o.value === f)) return 'fallback';",
+            '        return null;',
+            '      },',
+            "      [label, fallbackValue ?? ''] as [string, string],",
+            '    )',
+            '    .catch(() => null);',
+            "  if (present === 'fallback') {",
+            '    await loc.selectOption(fallbackValue!);',
+            '    return;',
+            '  }',
+            "  if (present === 'value') {",
+            '    await loc.selectOption(label);',
+            '    return;',
+            '  }',
+            '  const result = await loc.selectOption({ label }).catch(() => null);',
+            '  if (result) return;',
+            '  await loc.selectOption(label); // fall back to value/index matching',
+            '}',
+        ],
+    },
+    {
+        token: 'await hover(',
+        source: [
+            '/**',
+            ' * A hover the widget actually notices — mirror of daemon/inputs.ts',
+            ' * syntheticHover, which is how replay executes every recorded `hover`.',
+            ' *',
+            " * Playwright's own hover moves the mouse, and CSS `:hover` follows; an",
+            ' * autocomplete or listbox that opens on `mouseenter` (or a menu that keys',
+            ' * off `pointerover`) may never see an event at all when the element is',
+            ' * covered, or when the pointer was already inside it. So the real move is',
+            ' * best-effort, and the events are then dispatched at the element itself.',
+            ' * `mouseenter` does not bubble — that is the one difference between it and',
+            ' * its neighbours, and a bubbling `mouseenter` would fire delegated',
+            ' * handlers no real pointer ever fires.',
+            ' */',
+            'async function hover(loc: Locator): Promise<void> {',
+            '  await loc.hover().catch(() => {});',
+            '  await loc.evaluate((el: Element) => {',
+            "    for (const type of ['pointerover', 'mouseover', 'mouseenter', 'mousemove']) {",
+            "      el.dispatchEvent(new MouseEvent(type, { bubbles: type !== 'mouseenter' }));",
+            '    }',
+            '  });',
+            '}',
+        ],
+    },
+    {
+        token: 'pick(',
+        source: [
+            '/**',
+            ' * The first recorded way of naming the control that resolves to exactly ONE',
+            ' * element, tried in the order the recording measured. Not `.or()`: that is a',
+            ' * union, so a fallback matching several elements (a dialog-wide input selector,',
+            ' * say) would make the action a strict-mode violation, where the replay it',
+            ' * mirrors simply skips a candidate that is not unique and tries the next.',
+            ' *',
+            ' * It polls, because a spec has none of the observation turns that used to hide',
+            " * an app rendering a beat late (resolveChain's waitMs). `any` is for the two",
+            ' * places ambiguity is the normal shape: reading across every match, and a loop',
+            ' * body whose per-record locator matches every record.',
+            ' *',
+            ' * `where` (`"<stepId> <segmentId>/<stepIndex> target|source"`, baked in at each',
+            ' * call site) is what turns a silent fallthrough into telemetry: when the',
+            ' * winning candidate is not the primary (index 0), that IS drift — the recorded',
+            ' * locator missed and a later one covered for it — so it is worth one stable,',
+            ' * grep-able line, not a passing test that quietly stopped proving what it did',
+            ' * on the day it was recorded.',
+            ' *',
+            ' * WHICH RESOLVER RULE THIS MIRRORS. replay never resolves a step against a',
+            ' * DOM that is still painting: runOneStep awaits settleDom first, and',
+            " * resolveChain's own comment states the principle: a candidate that missed",
+            ' * while the page was still painting and hits on the next poll is not',
+            ' * volatile — it was early. A spec has no settleDom, and a pass here is not',
+            ' * one instant: every count() is its own round trip, so candidate #1 is',
+            ' * sampled several milliseconds before candidate #2. Measured on the',
+            ' * repair-desk bench (fwrd42, which defers its parts refetch ~500ms BY',
+            " * DESIGN, landing on a poll boundary): the scoped primary",
+            " * `locator('tr', { hasText }).locator('td:nth-of-type(1)')` counted 0 at t,",
+            ' * `getByText` counted 1 at t+3ms, and the',
+            ' * recorded primary counted 1 again 3ms later — a phantom drift on ~40% of',
+            ' * runs, twice taking a purely structural fallback. So a fallback wins only',
+            ' * after everything ahead of it has had a SECOND, later look and still',
+            ' * missed. That is the settleDom guarantee expressed with the only clock a',
+            ' * plain spec has.',
+            ' *',
+            ' * WHAT IT CANNOT MIRROR. Four resolveChain rules need state a Tier 2 file',
+            ' * does not carry, so a candidate that is merely ambiguous (count > 1) is',
+            ' * still skipped here rather than narrowed:',
+            " *  - `ambiguousNth` / the recorded `nth`: emitted as `.nth(n)` when the",
+            ' *    recording stored one, but replay can also invent one per loop pass.',
+            " *  - `plausible()`: needs the recorded bounding box, and the `point`",
+            ' *    candidate that carries it is dropped (a spec cannot find an element by',
+            ' *    where it was).',
+            " *  - the structural `held`/`guess` hold: needs to know which candidate is",
+            ' *    positional rather than named. Mirrored statically instead, and more',
+            ' *    strictly, by the identity `.filter({ hasText })` guards locators.ts',
+            ' *    puts on every non-identity candidate.',
+            " *  - `byEvidence` (retired candidates last): per-candidate replay evidence",
+            ' *    lives in the skill store, not in the spec.',
+            ' *',
+            ' * `note` is passed only at a FLAGGED step (compile found the step itself',
+            ' * wrong — a demoted pin, say — see spec/diagnostics.ts). Appended to the',
+            ' * throw, it is what stops "none of 3 recorded locators resolved" from',
+            ' * reading as app drift when the recording is what needs redoing.',
+            ' */',
+            'async function pick(page: Page, candidates: Locator[], where: string, opts: { any?: boolean } = {}, note?: string): Promise<Locator> {',
+            '  const enough = (n: number) => (opts.any ? n > 0 : n === 1);',
+            '  const hits = async (i: number) => enough(await candidates[i].count().catch(() => 0));',
+            '  /** The first candidate ahead of `i` that is there after all — see the re-check below. */',
+            '  const ahead = async (i: number) => {',
+            '    for (let j = 0; j < i; j++) if (await hits(j)) return j;',
+            '    return -1;',
+            '  };',
+            '  for (let waited = 0; ; waited += PICK_POLL_MS) {',
+            '    for (let i = 0; i < candidates.length; i++) {',
+            '      if (await hits(i)) {',
+            '        // Confirm the miss before demoting the recorded locator. Each',
+            '        // count() is its own round trip, so one pass samples candidate #1',
+            '        // some milliseconds BEFORE candidate #2 — and an app that paints',
+            '        // in that gap makes the earlier candidate look absent when it was',
+            '        // merely early. Re-sampling everything ahead of the winner gives',
+            '        // them a second, later look, which is the guarantee replay gets',
+            '        // for free by letting the DOM go quiet before it resolves at all.',
+            '        const back = i === 0 ? -1 : await ahead(i);',
+            '        const won = back >= 0 ? back : i;',
+            '        if (won > 0) {',
+            '          const line = `[sitelooper drift] ${where}: primary ${String(candidates[0])} missed; used #${won + 1} ${String(candidates[won])}`;',
+            '          console.warn(line);',
+            '          DRIFT.push(line);',
+            '        }',
+            '        return candidates[won];',
+            '      }',
+            '    }',
+            '    if (waited >= PICK_WAIT_MS) break;',
+            '    await page.waitForTimeout(PICK_POLL_MS);',
+            '  }',
+            '  throw new Error(',
+            '    // The url and the recorded step are half the answer whenever a chain',
+            '    // misses wholesale: a locator that named the control on the day it was',
+            '    // recorded usually misses because the page is not the page the step',
+            '    // expected, and the log otherwise says only that nothing resolved.',
+            '    `none of ${candidates.length} recorded locators resolved at ${where} (page is at ${page.url()}): ` +',
+            "      candidates.slice(0, 3).map((c) => String(c)).join(' | ') +",
+            "      (note ? `\\n  ${note}` : ''),",
+            '  );',
+            '}',
+        ],
+    },
+    {
+        token: 'readOptional(',
+        source: [
+            '/**',
+            ' * A recorded READ, which never fails the flow.',
+            ' *',
+            ' * WHICH REPLAY RULE THIS MIRRORS. runOneStep treats `read`/`read_all` as an',
+            ' * OBSERVATION, not a state change: a read whose target cannot be resolved —',
+            ' * or whose read itself errors — is skipped with a warning and the replay',
+            ' * CONTINUES ("skipped read — no element matched any known locator"). Failing',
+            ' * to re-capture a value says nothing about whether the procedure ran; the',
+            ' * step after it is exactly as valid as it was. A spec that threw here turned',
+            " * a missing observation into a failed test: grafana's `panel_content` read is",
+            ' * a freshly applied text panel whose body the verifier goes on to confirm,',
+            ' * and none of the three recorded ways of naming it resolved inside the pick',
+            ' * window — one lost value, and the run reported as a broken procedure.',
+            ' *',
+            ' * So: the pick and the read together, and on any failure one grep-able line',
+            ' * and an EMPTY value. Assertions and outputs built from an empty read are',
+            ' * left exactly as they were — the emptiness is the honest report.',
+            ' */',
+            'async function readOptional(',
+            '  page: Page,',
+            '  candidates: Locator[],',
+            '  where: string,',
+            '  read: (loc: Locator) => Promise<string>,',
+            '  opts: { any?: boolean } = {},',
+            '): Promise<string> {',
+            '  try {',
+            '    return await read(await pick(page, candidates, where, opts));',
+            '  } catch {',
+            '    console.warn(`[sitelooper skip] ${where}: read target not found — value left empty`);',
+            "    return '';",
+            '  }',
+            '}',
+        ],
+    },
+    {
+        token: 'present(page, ',
+        source: [
+            '/**',
+            ' * Is `text` on the page — as TEXT, or as the current VALUE of a field?',
+            ' *',
+            " * WHICH REPLAY RULE THIS MIRRORS. checkIdentity (src/skills/replay.ts) asks",
+            ' * `presentOnPage`, which captures a fresh daemon SNAPSHOT and substring-matches',
+            ' * the marker against its lines. Those lines carry field values —',
+            ' * `textbox "Name": sp5odb Bench Customer` — so on a form in EDIT mode the',
+            " * marker is found in an <input>'s value, where `getByText` can never see it:",
+            ' * the DOM has no text node for it at all. Cloud run sp5odb died on exactly',
+            ' * that, at the very first gate of `03-open`, on an odoo customer form.',
+            ' *',
+            ' * So this is the snapshot line test in the two dialects a spec has: visible',
+            ' * text, or the live value of a visible input/textarea/select (a select',
+            ' * reports its selected option label, which is what the snapshot shows).',
+            ' * Whitespace-normalised and case-insensitive on the value half, because the',
+            " * snapshot's own comparison is whitespace-insensitive and a rendered value",
+            ' * is not always cased as it was typed.',
+            ' */',
+            'async function present(page: Page, text: string): Promise<boolean> {',
+            "  const want = text.replace(/\\s+/g, ' ').trim();",
+            '  if (!want) return false;',
+            '  if (await page.getByText(text).first().isVisible().catch(() => false)) return true;',
+            '  return await page',
+            "    .locator('input, textarea, select')",
+            '    .evaluateAll((els, needle: string) => {',
+            "      const norm = (s: string) => s.replace(/\\s+/g, ' ').trim().toLowerCase();",
+            '      const target = norm(needle);',
+            '      return els.some((el) => {',
+            '        const e = el as HTMLElement & { checkVisibility?: () => boolean };',
+            "        const shown = typeof e.checkVisibility === 'function' ? e.checkVisibility() : e.getClientRects().length > 0;",
+            '        if (!shown) return false;',
+            "        if (el instanceof HTMLSelectElement) return norm(el.selectedOptions[0]?.textContent ?? '').includes(target);",
+            '        const v = (el as HTMLInputElement | HTMLTextAreaElement).value;',
+            "        return typeof v === 'string' && norm(v).includes(target);",
+            '      });',
+            '    }, want)',
+            '    .catch(() => false);',
+            '}',
+        ],
+    },
+    {
+        token: 'satisfied(page, ',
+        source: [
+            '/**',
+            " * Is this step's work already DONE on the record it names?",
+            ' *',
+            " * WHICH REPLAY RULE THIS MIRRORS. `goalSatisfied` (src/skills/replay.ts):",
+            ' * two halves, and both are load-bearing. The IDENTITY texts say the page is',
+            ' * showing THIS record — the url and the page shape only ever say "a page of',
+            ' * this template" — and the GOAL texts say that record is already in the',
+            " * state this step exists to produce. Identity alone would skip a step",
+            ' * because the right record is open; a goal alone would skip it because some',
+            ' * OTHER record happens to read "Cancelled".',
+            ' *',
+            ' * Conservative by construction: no goal, or no identity, is never satisfied.',
+            ' * Being wrong the other way costs one re-run of a step that had already',
+            ' * happened; being wrong THIS way skips work that never happened at all.',
+            ' */',
+            'async function satisfied(page: Page, identity: string[], goal: string[]): Promise<boolean> {',
+            '  if (!identity.length || !goal.length) return false;',
+            '  for (const want of [...identity, ...goal]) {',
+            '    if (!(await present(page, want))) return false;',
+            '  }',
+            '  return true;',
+            '}',
+        ],
+    },
+    {
+        token: 'escapeRe(',
+        source: [
+            '/** A value interpolated into a pattern is DATA: its own metacharacters must not become pattern. */',
+            'function escapeRe(s: string): string {',
+            "  return s.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');",
+            '}',
+        ],
+    },
+    {
+        token: 'looseText(',
+        source: [
+            '/**',
+            " * A recorded NAME as a `hasText` matcher that tolerates the daemon's spacing.",
+            ' *',
+            " * WHY. The daemon names an element from `innerText` (describeInPage in",
+            ' * src/daemon/diff.ts), which inserts a line break at every BLOCK boundary,',
+            ' * and `clean()` collapses those to single spaces. Playwright matches',
+            ' * `hasText` against `textContent`, which inserts NOTHING between block',
+            ' * children. For a container named from its contents the two disagree by',
+            ' * exactly the separators — measured against the bench grafana, the refresh',
+            ' * menu (twelve <button> children) is',
+            ' *   innerText   "Off\\nAuto\\n5s\\n10s\\n…"   -> recorded "Off Auto 5s 10s …"',
+            ' *   textContent "OffAuto5s10s…"',
+            ' * so `filter({ hasText: \'Off Auto 5s …\' })` counted 0 while',
+            " * `getByRole('menu')` counted 1. Whitespace NORMALISATION cannot bridge",
+            ' * that, because the whitespace is not there to normalise; that is why cloud',
+            ' * runs sp5gr/sp6gr still died at `04-add s_0c4807/5` on the union that',
+            ' * already carried a hasText half.',
+            ' *',
+            ' * So every space the daemon put between two words becomes `\\s*`: it stood',
+            ' * for real whitespace OR for a block boundary, and the pattern has to accept',
+            ' * both. Everything else is escaped, so the matcher still says exactly what',
+            " * the line said, and `i` mirrors a string hasText's case-insensitivity.",
+            ' */',
+            'function looseText(text: string | RegExp): RegExp {',
+            "  const source = typeof text === 'string' ? escapeRe(text) : text.source;",
+            "  return new RegExp(source.replace(/ +/g, '\\\\s*'), typeof text === 'string' ? 'i' : text.flags);",
+            '}',
+        ],
+    },
+];
+/**
+ * The helpers this body needs, in declaration order — transitively, because a
+ * helper may use another (`urlPartWhen` reads `urlPart`; both poll on `pick`'s
+ * constants). Anything else would emit a file that references a function it
+ * does not carry, which is the one defect a generated spec cannot survive.
+ */
+function neededHelpers(body) {
+    const chosen = new Set();
+    for (;;) {
+        const text = [body, ...[...chosen].map((h) => h.source.join('\n'))].join('\n');
+        const added = HELPERS.filter((h) => !chosen.has(h) && text.includes(h.token));
+        if (!added.length)
+            return HELPERS.filter((h) => chosen.has(h));
+        for (const h of added)
+            chosen.add(h);
+    }
+}
+const src = (text) => stringSource(text, { slot: slotAsParam });
+const match = (text) => matcherSource(text, { slot: slotAsParam });
+/**
+ * A url pattern as a RegExp source for `toHaveURL`, mirroring `urlMatches`:
+ * `:id`/`:var` stand for any one segment, a slot for this run's own value
+ * (escaped — it is data), the query is not part of the identity of a page
+ * and the hash route is. Null when the pattern is not a url at all.
+ */
+function urlRegexSource(pattern) {
+    if (!/^[a-z]+:\/\//i.test(pattern))
+        return null;
+    const hashAt = pattern.indexOf('#');
+    const head = hashAt < 0 ? pattern : pattern.slice(0, hashAt);
+    const hash = hashAt < 0 ? '' : pattern.slice(hashAt);
+    const queryAt = head.indexOf('?');
+    const headSource = urlPatternBody(queryAt < 0 ? head : head.slice(0, queryAt));
+    // The query is dropped from the pattern, so the live url may still carry
+    // one: allow it exactly where it would sit, before the hash route.
+    return hash ? `^${headSource}(?:\\\\?[^#]*)?${urlPatternBody(hash)}$` : `^${headSource}(?:[?#].*)?$`;
+}
+/** One piece of a url pattern as regex source: `:id`/`:var` any segment, a slot this run's own value. */
+function urlPatternBody(piece) {
+    let out = '';
+    let last = 0;
+    const token = /\{\{([vd]\d+)\}\}|:id\b|:var\b/g;
+    for (const m of piece.matchAll(token)) {
+        const at = m.index ?? 0;
+        out += templateSafe(escapeRe(piece.slice(last, at)));
+        out += m[1] ? '${escapeRe(p.' + m[1] + ')}' : '[^/]+';
+        last = at + m[0].length;
+    }
+    return out + templateSafe(escapeRe(piece.slice(last)));
+}
+const safeDecode = (s) => {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return s;
+    }
+};
+/**
+ * The argument `toHaveURL` is given for a recorded url pattern, or null when
+ * the pattern is not a url at all.
+ *
+ * A regex for a path-shaped url, because a path IS ordered. But a QUERY-SHAPED
+ * hash (`#action=1&cids=2`, which is odoo) is application state, and `urlMatches`
+ * — the rule replay judges by — compares it as an unordered SET of pairs: every
+ * pair the recording named must be present with the same value, extra live pairs
+ * are fine, order means nothing. A regex cannot say that, and the whole of what
+ * was wrong with fwod34's second cloud run was the ordering: every value right,
+ * `#action=…&model=…&cids=…` where the recording saw `#action=…&cids=…&model=…`.
+ * Playwright takes a `(url: URL) => boolean` predicate, so that case is emitted
+ * as one, over the same inlined comparison replay makes.
+ */
+function urlExpectSource(pattern) {
+    if (!/^[a-z]+:\/\//i.test(pattern))
+        return null;
+    const hashAt = pattern.indexOf('#');
+    const body = hashAt < 0 ? '' : pattern.slice(hashAt + 1).split('?')[0];
+    if (!body || body.startsWith('/') || !body.includes('=')) {
+        const re = urlRegexSource(pattern);
+        return re ? `new RegExp(\`${re}\`)` : null;
+    }
+    const head = pattern.slice(0, hashAt);
+    const queryAt = head.indexOf('?');
+    const headSource = urlPatternBody(queryAt < 0 ? head : head.slice(0, queryAt));
+    const pairs = body
+        .split('&')
+        .filter(Boolean)
+        .map((pair) => {
+        const eq = pair.indexOf('=');
+        const k = eq < 0 ? pair : pair.slice(0, eq);
+        const value = eq < 0 ? '' : pair.slice(eq + 1);
+        // `:id`/`:var` is app-minted state: urlDiff lets such a key hold anything,
+        // or be absent altogether. Anything else — a literal, or a slot this run
+        // binds — must be there and equal.
+        if (value === ':id' || value === ':var')
+            return `[${q(k)}, null]`;
+        return `[${q(k)}, ${src(safeDecode(value))}]`;
+    });
+    return `(url: URL) => hashMatch(url, new RegExp(\`^${headSource}$\`), [${pairs.join(', ')}])`;
+}
+/**
+ * The roles the daemon gives an <input>/<textarea> (roleOf in
+ * src/daemon/diff.ts), plus `combobox`, which an app can also put on an input
+ * by hand. These are the roles whose recorded NAME can disagree with
+ * Playwright's accessible name for the very same element.
+ *
+ * WHY. The daemon's `nameOf` names an element aria-label -> aria-labelledby ->
+ * alt -> title -> placeholder -> ancestor <label> -> innerText, and never looks
+ * at a `<label for=id>`. Playwright computes the real accessible name, which
+ * PREFERS that label over title and placeholder. So an input carrying both —
+ * grafana's tag field, `<label for>` "Tags" over placeholder "New tag (enter
+ * key to add)" — is recorded under the placeholder and is unfindable by
+ * `getByRole(name)`. That is exactly how the compiled spec died in cloud run
+ * sp4gr, deterministically, on a step whose live replay passed (replay compares
+ * daemon lines to daemon lines, so it never asks Playwright to find the name).
+ *
+ * The fix is a union over the three ways the name could have been minted, in
+ * the daemon's own order of preference. Only these roles get it: a
+ * button/link/heading name has no placeholder to disagree with.
+ */
+const INPUT_LIKE_ROLES = new Set(['textbox', 'searchbox', 'combobox', 'spinbutton']);
+/**
+ * WHY EVERY ROLED LINE GETS A `hasText` UNION.
+ *
+ * `describeInPage` (src/daemon/diff.ts) falls back to `innerText` (up to 80
+ * chars) whenever aria-label/labelledby/alt/title/placeholder/<label> give it
+ * nothing — for EVERY role, because a recorded line is a description for a
+ * human and a diff, not a locator. Playwright's `getByRole(role, { name })`
+ * matches the real ACCESSIBLE NAME. The two readings diverge in two distinct
+ * ways, and a locator built off the recorded line has to survive both.
+ *
+ *   1. The role is not named from its contents at all. Grafana's
+ *      refresh-interval popup is recorded as
+ *        - menu "Off Auto 5s 10s 30s 1m 5m 15m 30m 1h 2h 1d"
+ *      and Playwright's accessible name for that `role=menu` is the empty
+ *      string: cloud run sp5gr failed at `04-add s_0c4807/5` on exactly that
+ *      locator, every attempt. The odoo home menu (`- menu "6 3 YourCompany"`)
+ *      is the same defect.
+ *
+ *   2. The role IS named from its contents — but the element contains FORM
+ *      CONTROLS, and the accessible-name computation substitutes each
+ *      control's VALUE where innerText renders nothing. This is why the first
+ *      cut of this restricted the union to a "name from author, contents"
+ *      allow-list and cloud run sp7od still died at `04-open s_059a1e/1`. That
+ *      step clicks an odoo quotation's quantity cell, which puts the order
+ *      line into inline edit mode; measured against the local bench odoo, the
+ *      same `<tr>` reads
+ *        innerText (daemon)  "20% £ 36.00"
+ *        accessible name     "Chair floor protection Chair floor protection
+ *                             Office chairs can harm your floor: protect it.
+ *                             3.00 12.00 20% Delete £ 36.00 Delete row"
+ *      — the product combobox, the description textbox and the qty/price
+ *      textboxes contribute their values, and a Delete link even lands
+ *      BETWEEN "20%" and "£ 36.00", so the recorded name is not so much as a
+ *      SUBSTRING of the accessible name. `getByRole('row', { name: '20% £
+ *      36.00' })` counted 0. The identical line shape passes in step 02-create
+ *      because the row is read-only there and the two readings agree.
+ *
+ * Both failures are repaired by the same union, so there is no allow-list any
+ * more: any roled line may have been named from innerText, and hasText is the
+ * only half that reads the element the way the daemon did.
+ *
+ * But hasText is NOT `clean(innerText)` either, which is what an earlier cut
+ * assumed and why sp6gr failed identically with a union already in place.
+ * Playwright matches hasText against `textContent`, which puts no separator
+ * between block children, so the recorded "Off Auto 5s …" was compared against
+ * "OffAuto5s…" and matched nothing — and the odoo row's textContent is
+ * "20%£ 36.00", no space, so a plain string hasText misses it too. The hasText
+ * half therefore goes through `looseText` (see the helper), which turns each
+ * recorded space back into `\s*` — the only form that matches both readings
+ * of the same subtree. Verified live: `getByRole('row').filter({ hasText:
+ * /20%\s*£\s*36\.00/i })` counts 1 on that edit-mode row.
+ *
+ * The union is inherently a SUBSTRING test — `exact` cannot be expressed on
+ * the hasText half — so the guard callers (wrapAlreadyInEffect, which reads
+ * presence as a reason NOT to act) keep their anchored matcher on the role
+ * half and accept the looser hasText half. That is deliberate: the alternative
+ * is a guard whose role half never matches at all, which is the bug being
+ * fixed. Guards are built from POPUP lines only (menu/dialog/listbox), whose
+ * roles were already taking the union before this change, so widening the
+ * allow-list does not widen any guard.
+ */
+/**
+ * A Playwright locator for one recorded page line (`- role "name"`,
+ * `- text: foo`). Null when the line names nothing findable — an unnamed
+ * control, or a value with no role — in which case the caller leaves the
+ * observation as a comment rather than inventing an assertion.
+ */
+function lineLocator(line, exact = false) {
+    // `exact: false` by default, unlike an action's locator. A recorded line's name comes
+    // from the daemon's own accessible-name walk (describeInPage in
+    // src/daemon/diff.ts), which composes a name out of the subtree and can
+    // disagree with Playwright's exact matcher on spacing, punctuation and
+    // decorative children - `link "RD Repair Desk"` is a real example. An
+    // ACTION must name one control exactly; a presence check only has to find
+    // the evidence, and replay's own lineShows matches loosely too.
+    //
+    // `exact` is for the one caller that reads presence as a reason NOT to act
+    // (the already-in-effect guard): there a false positive silently drops a
+    // click, and replay's own check is line-exact — `lineShows` looks for the
+    // whole rendered line, quotes and all, so a `button "6"` never matches a
+    // button called "17.6". Loose is safe when it only widens the evidence a
+    // step accepts; it is not safe when it decides the step is unnecessary.
+    //
+    // A recorded line has ALREADY been through maskVolatile, so its clock and
+    // calendar tokens arrive as the `{{*}}` wildcard. Rendered as the literal
+    // string it looks like, that names nothing on any page — kanboard's
+    // `textbox "{{*}} {{*}}"` is a due-date field the app titles with the
+    // current date and time — so it comes back as a RegExp instead (see
+    // maskedMatcherSource), and a line that is nothing but wildcards names no
+    // element at all and is left to the caller's observation comment.
+    const roled = /^-?\s*([a-zA-Z]+)\s+"((?:[^"\\]|\\.)*)"/.exec(line);
+    if (roled) {
+        const name = roled[2].replace(/\\(.)/g, '$1');
+        if (!name.trim())
+            return null;
+        const matcher = lineName(name, exact);
+        if (!matcher)
+            return null;
+        // `exact` rides along as it always has; Playwright ignores it for a RegExp
+        // name, where the anchoring above carries the same decision.
+        const roleName = roled[1].toLowerCase();
+        const role = `page.getByRole(${q(roled[1])}, { name: ${matcher}, exact: ${exact} })`;
+        if (INPUT_LIKE_ROLES.has(roleName)) {
+            return `${role}.or(page.getByTitle(${matcher}, { exact: ${exact} })).or(page.getByPlaceholder(${matcher}, { exact: ${exact} }))`;
+        }
+        // Every other role: the daemon named this element from innerText, so the
+        // same text also has to be looked for as TEXT. Same matcher in both
+        // halves, so the two can never disagree about what the line said; hasText
+        // is a substring test whatever `exact` says.
+        //
+        // Not restricted to the roles ARIA names from their contents. A row/cell
+        // that holds form controls IS named from its contents, and the accessible
+        // name still diverges from innerText because the controls' VALUES are
+        // substituted in — see the block comment above for the odoo edit-mode row
+        // that killed sp7od with the allow-list in place.
+        //
+        // Through `looseText`, because the two halves read the element's text by
+        // DIFFERENT rules: the daemon's innerText separates block children, the
+        // hasText Playwright compares against (textContent) does not. See the
+        // helper — this is the half that has to survive that gap.
+        return `${role}.or(page.getByRole(${q(roled[1])}).filter({ hasText: looseText(${matcher}) }))`;
+    }
+    const text = /^-?\s*(?:text:)?\s*(.+?)\s*$/.exec(line);
+    const value = text?.[1];
+    if (!value || value.includes('"'))
+        return null;
+    const matcher = lineName(value, exact);
+    return matcher ? `page.getByText(${matcher}, { exact: ${exact} })` : null;
+}
+/** The name matcher for one recorded line, wildcards included; null when the line names nothing. */
+function lineName(text, exact) {
+    return maskedMatcherSource(text, { slot: slotAsParam, anchor: exact });
+}
+/**
+ * One any-of assertion for a group of recorded lines.
+ *
+ * `lineShows` is ANY-of: replay stops only when NONE of the parameterised
+ * lines is on the page, and separately when NONE of the plain ones is. A spec
+ * asserting each line on its own would be strictly stricter than the gate it
+ * claims to mirror, and fails on the single line whose recorded name the
+ * daemon composed differently — which is what `link "RD Repair Desk"` did on
+ * the first real run. `.or()` is a union, so a union taken `.first()` is
+ * exactly "at least one of these is showing".
+ */
+function anyOfAssertion(lines, label, out) {
+    const { source, listed, unnameable, count } = lineUnion(lines);
+    for (const line of unnameable)
+        out.push(`// observed (nothing nameable in it): ${commentSafe(line)}`);
+    if (!source)
+        return;
+    out.push(`// ${label} — any one of these, as replay's effect gate has it:`);
+    for (const line of listed)
+        out.push(`//   ${commentSafe(line)}`);
+    out.push(`await expect(${source}${count === 1 ? '' : `\n${CONT_INDENT}`}.first()).toBeVisible();`);
+}
+/**
+ * A group of recorded lines as ONE union locator — the shape both the effect
+ * gate above and the already-in-effect guard below need, built once so the
+ * two can never disagree about what a recorded line means.
+ */
+function lineUnion(lines, exact = false) {
+    const usable = [];
+    const listed = [];
+    const unnameable = [];
+    for (const line of lines) {
+        const loc = lineLocator(line, exact);
+        if (!loc)
+            unnameable.push(line);
+        else if (!usable.includes(loc)) {
+            usable.push(loc);
+            listed.push(line);
+        }
+    }
+    const source = usable.length ? usable[0] + usable.slice(1).map((u) => `\n${CONT_INDENT}.or(${u})`).join('') : '';
+    return { source, listed, unnameable, count: usable.length };
+}
+/**
+ * The step's recorded page changes as assertions, mirroring the
+ * `expectedChanges` gate: the lines carrying a slot are HARD as a GROUP —
+ * they are what distinguishes this run from the recorded one, so none of them
+ * showing means the step acted on the wrong thing — and the plain lines are a
+ * second group, because a step none of whose recorded effects appeared did
+ * not have its recorded effect.
+ */
+function expectationLines(step, out) {
+    const recorded = step.expect?.addedContains ?? [];
+    let lines = recorded.filter((l) => !TRANSIENT_LINE.test(l));
+    if (!lines.length)
+        return;
+    // A fill's own echo in a same-role element is no evidence — the WRONG
+    // textbox produces it too. Same choice replay makes, made visible here.
+    if (step.tool === 'fill' && typeof step.args.value === 'string') {
+        lines = consequentialExpectations(lines, step.args.value);
+    }
+    const hard = lines.filter((l) => SLOT_LINE.test(l));
+    const plain = lines.filter((l) => !SLOT_LINE.test(l));
+    if (hard.length)
+        anyOfAssertion(hard, "this run's own values must show", out);
+    if (plain.length)
+        anyOfAssertion(plain, "the step's recorded effect must show", out);
+}
+/** The url and alert halves of a step's expectation. */
+function effectLines(step, ctx, out) {
+    const pattern = step.expect?.urlPattern;
+    if (pattern && pattern !== ctx.lastUrl) {
+        ctx.lastUrl = pattern;
+        const check = urlExpectSource(pattern);
+        if (check)
+            out.push(`await expect(page).toHaveURL(${check});`);
+        else
+            out.push(`// expected url ${commentSafe(pattern)} (not a url pattern this compiler can express)`);
+    }
+    // Toasts are volatile: recorded soft in replay, and a spec that asserted
+    // one would fail on timing rather than on behaviour.
+    if (step.expect?.alertContains)
+        out.push(`// expected alert containing ${JSON.stringify(commentSafe(step.expect.alertContains))}`);
+}
+/** Collect the slots a piece of recorded text needs from `p`. */
+function noteSlots(value, ctx) {
+    if (typeof value === 'string') {
+        for (const m of value.matchAll(/\{\{([vd]\d+)\}\}/g))
+            ctx.slots.add(m[1]);
+        return;
+    }
+    if (Array.isArray(value))
+        for (const v of value)
+            noteSlots(v, ctx);
+    else if (value && typeof value === 'object')
+        for (const v of Object.values(value))
+            noteSlots(v, ctx);
+}
+/**
+ * Wraps everything a click step emitted from `actionStart` on in the
+ * already-in-effect guard, or leaves it alone when the recorded effect opens
+ * no popup.
+ *
+ * WHICH REPLAY RULE THIS MIRRORS. runOneStep, before it acts: a click that
+ * OPENS a popup is a TOGGLE, so re-clicking it while the popup is showing
+ * closes the very thing the next step depends on — and the click that ought
+ * to be a no-op is instead intercepted by the modal overlay it raised, which
+ * on kanboard meant 60s of Playwright waiting for an `#modal-overlay` to stop
+ * eating pointer events. Replay skips such a click ("already in effect"); the
+ * spec asks the same question of the same recorded lines and skips the pick
+ * and the click together, because resolving a control under an open modal is
+ * no more meaningful than clicking it.
+ */
+function wrapAlreadyInEffect(step, ctx, out, actionStart) {
+    const opener = openerExpectations(step);
+    if (!opener.length)
+        return;
+    const { source, listed, count } = lineUnion(opener, true);
+    if (!source)
+        return;
+    const where = `${ctx.stepId} ${ctx.segmentId}/${ctx.stepIndex}`;
+    const acted = out
+        .splice(actionStart)
+        .flatMap((l) => l.split('\n'))
+        .map((l) => (l ? '  ' + l : l));
+    out.push("// This click OPENS a popup, which makes it a toggle: replay skips it when the", '// recorded effect is already showing (runOneStep, "skipped (already in effect)"),', '// because clicking again would close what the next step needs. Same rule here,', '// off the same recorded lines:', ...listed.map((l) => `//   ${commentSafe(l)}`), `if (await ${source}${count === 1 ? '' : `\n${CONT_INDENT}`}.first().isVisible().catch(() => false)) {`, '  // already in effect: the popup is on the page, so the recorded click has nothing left to do.', 
+    // A skipped click is invisible in a passing-until-it-isn't spec, and a
+    // guard that fires for the WRONG reason (one of these lines is on the page
+    // for some other reason than "the popup is open") silently drops the step
+    // that everything after it depends on. One line on stdout is what makes
+    // that legible in a bench log.
+    `  console.log(${q(`[sitelooper skip] ${where}: recorded popup already showing — click skipped`)});`, '} else {', ...acted, '}');
+}
+/**
+ * The expression an action acts on, emitting the resolution above it when the
+ * recording measured more than one way of naming the element.
+ *
+ * A single candidate is used inline. Several become one `pick(...)` call: the
+ * chain is an ORDERED list of ways to name one control, not a union of
+ * elements, and only `pick` preserves that. Returns null when nothing in the
+ * chain could be expressed — the caller then emits a TODO rather than a
+ * statement it cannot target.
+ */
+function actionTarget(step, key, ctx, out, opts = {}) {
+    const chain = step.locators?.[key] ?? [];
+    noteSlots(chain, ctx);
+    const { sources } = candidateSources(chain, { slot: slotAsParam });
+    if (!sources.length)
+        return null;
+    // In a loop the cursor is always the first match: the record this pass acts on.
+    if (sources.length === 1)
+        return opts.first ? `(${sources[0]}).first()` : sources[0];
+    const name = `el${++ctx.picks}`;
+    const where = `${ctx.stepId} ${ctx.segmentId}/${ctx.stepIndex} ${key}`;
+    out.push(`const ${name} = await pick(page, [`);
+    for (const source of sources)
+        out.push(`${CONT_INDENT}${source},`);
+    // `note` is the trailing argument, so a step with nothing wrong emits the
+    // call exactly as it always did.
+    const tail = ctx.note ? `, ${opts.any ? '{ any: true }' : '{}'}, ${q(ctx.note)}` : opts.any ? ', { any: true }' : '';
+    out.push(`], ${q(where)}${tail});`);
+    return opts.first ? `${name}.first()` : name;
+}
+/** The `point` candidates a step lost, as one honest comment. */
+function droppedNotes(step, out) {
+    const lost = [];
+    for (const key of ['target', 'source']) {
+        for (const c of step.locators?.[key] ?? [])
+            if (c.kind === 'point')
+                lost.push(c);
+    }
+    if (!lost.length)
+        return;
+    const where = lost
+        .map((c) => (c.kind === 'point' ? `${c.role ?? c.tag} at ${c.x},${c.y}` : ''))
+        .filter(Boolean)
+        .join(', ');
+    out.push(`// TODO: dropped the recorded position fallback (${where}) — a spec cannot find an element by where it was.`);
+}
+/** The names this step mints, in the order the segment declares them. */
+function derivedHere(segment, index) {
+    return Object.entries(segment.derived ?? {}).filter(([, d]) => d.step === index);
+}
+/**
+ * `p.dN = …` for every value this step mints, bound before the assertions
+ * read it.
+ *
+ * `settled` says the url is already the one the step navigated to — true
+ * after a `goto`, which awaits its own navigation. Anywhere else the action
+ * only STARTS the navigation, so the part has to be read the way replay reads
+ * it: after the url changed and the page stopped moving (see `urlPartWhen`).
+ * Read in the same tick instead, every part comes back empty and the
+ * `toHaveURL` built from them can never match — which is what odoo's
+ * `#action=&cids=&menu_id=` did on the first cloud run.
+ */
+function derivedLines(segment, index, ctx, out, urlBefore = '') {
+    const here = derivedHere(segment, index);
+    for (const [name] of here)
+        ctx.slots.add(name);
+    if (!here.length)
+        return;
+    const example = (d) => `// recorded example: ${commentSafe(d.example)}`;
+    if (!urlBefore) {
+        for (const [name, d] of here)
+            out.push(`p.${name} = urlPart(page.url(), ${q(d.at)}); ${example(d)}`);
+        return;
+    }
+    if (here.length === 1) {
+        out.push(`p.${here[0][0]} = await urlPartWhen(page, ${q(here[0][1].at)}, ${urlBefore}); ${example(here[0][1])}`);
+        return;
+    }
+    // ONE wait for ALL of them: a part bound the instant IT is non-empty can be
+    // read off a half-built url while its neighbour is still missing, and the
+    // pattern the three of them go into is then unmatchable by construction.
+    const name = `bound${++ctx.binds}`;
+    out.push(`const ${name} = await urlPartsWhen(page, [${here.map(([, d]) => q(d.at)).join(', ')}], ${urlBefore});`);
+    here.forEach(([slot, d], i) => out.push(`p.${slot} = ${name}[${i}]; ${example(d)}`));
+}
+/**
+ * The recorded popup lines that make a click a TOGGLE, or empty.
+ *
+ * Mirrors replay's `openerLines`: only the plain (unparameterised, non
+ * transient) effects count, and they count only when at least one of them
+ * names a popup — a dialog, menu, listbox or tooltip is the thing a second
+ * click closes again, where another row of textboxes is an effect worth
+ * re-producing. Widened to `dblclick` here for the same reason it applies to
+ * `click`; replay only ever recorded the case for `click`.
+ */
+function openerExpectations(step) {
+    if (step.tool !== 'click' && step.tool !== 'dblclick')
+        return [];
+    const lines = (step.expect?.addedContains ?? []).filter((l) => !TRANSIENT_LINE.test(l) && !SLOT_LINE.test(l));
+    // Only the popup lines decide, as replay's openerLines: the other effects
+    // a dialog-opening click recorded (the row it was about to fill, the
+    // combobox it typed into) were on the page BEFORE the click too, and an
+    // any-of guard over them skipped fwod34's product-option click on every
+    // run, so the configurator dialog its next step confirms never opened.
+    return lines.filter((l) => OPENER_LINE.test(l));
+}
+/**
+ * One recorded step as source. `first` marks a loop body, where every target
+ * is taken at its first match (see emitLoop).
+ */
+function emitSkillStep(step, segment, index, ctx, first = false) {
+    const out = [];
+    // A location comment ahead of everything this step emits, so a Playwright
+    // stack line (or a `[sitelooper drift]` warning, which shares this same
+    // "<stepId> <segmentId>/<stepIndex>" shape) can be mapped back to the
+    // recorded step that produced it.
+    out.push(`// @step ${ctx.stepId} ${segment.id}/${index}`);
+    // Ahead of EVERYTHING this step does — the already-in-effect guard, the pick,
+    // a bare locator action — because that is where replay's own settleDom sits
+    // (runOneStep). See the helper's comment for the odoo toggle sequence this
+    // ordering is what saves.
+    out.push('await settle(page);');
+    ctx.segmentId = segment.id;
+    ctx.stepIndex = index;
+    const args = step.args ?? {};
+    noteSlots(args, ctx);
+    const str = (name, fallback = '') => String(args[name] ?? fallback);
+    const num = (name) => (typeof args[name] === 'number' ? args[name] : undefined);
+    // Steps that act on the page itself, before any locator is needed.
+    switch (step.tool) {
+        case 'goto':
+            out.push(`await page.goto(${src(str('url'))});`);
+            // A navigation renders a route skeleton first: replay lets it hydrate
+            // before its effect gates look for the recorded content (runOneStep's
+            // `if (page.url() !== urlBefore) await settleDom(page)`), and the
+            // assertions and url reads below are exactly those gates.
+            out.push('await settle(page);');
+            effectLines(step, ctx, out);
+            // page.goto awaits its own navigation: the url is already the landed one.
+            derivedLines(segment, index, ctx, out);
+            return out;
+        case 'back':
+            out.push('await page.goBack();');
+            return out;
+        case 'set_viewport':
+            out.push(`await page.setViewportSize({ width: ${num('width') ?? 0}, height: ${num('height') ?? 0} });`);
+            return out;
+        case 'set_offline':
+            out.push(`await page.context().setOffline(${Boolean(args.offline)});`);
+            return out;
+        case 'eval':
+            out.push(`await page.evaluate(${src(str('expression'))});`);
+            return out;
+        case 'screenshot':
+            out.push(`await page.screenshot({ path: ${src(args.path ? str('path') : 'screenshot.jpg')}${args.full_page ? ', fullPage: true' : ''} });`);
+            return out;
+        case 'dialog_expect': {
+            const action = args.action === 'accept' ? 'accept' : 'dismiss';
+            const arg = action === 'accept' && args.prompt_text ? src(str('prompt_text')) : '';
+            const count = num('count') ?? 1;
+            out.push(`page.${count > 1 ? 'on' : 'once'}('dialog', (dialog) => dialog.${action}(${arg}));`);
+            return out;
+        }
+        case 'tabs':
+            // A second page needs a real handle, and inventing one would silently
+            // re-point every later `page.` line.
+            out.push(`// TODO: the recording switched to tab ${String(args.switch_to)} here — take the handle yourself.`);
+            return out;
+        case 'press':
+            if (!args.target) {
+                out.push(`await page.keyboard.press(${src(str('key'))});`);
+                return out;
+            }
+            break;
+        default:
+            break;
+    }
+    droppedNotes(step, out);
+    const isRead = step.tool === 'read' || step.tool === 'read_all';
+    if (isRead && str('what') === 'url') {
+        if (step.label)
+            out.push(`outputs[${q(`${ctx.stepId}.${step.label}`)}] = page.url();`);
+        return out;
+    }
+    // An unlabelled read published nothing — it was the agent orienting itself —
+    // so it needs no locator, and reporting one as missing would be a defect
+    // where replay simply skips: a read is an observation, never a state change.
+    if (isRead && !step.label) {
+        out.push(`// observed: ${step.tool} ${commentSafe(str('what', 'text'))} (unlabelled — it published no value)`);
+        return out;
+    }
+    // Ambiguity is the normal shape in exactly two places: a read across every
+    // match, and a loop body whose per-record locator names every record.
+    const any = step.tool === 'read_all' || first;
+    // A wait for the target to be GONE cannot go through pick(): pick demands a
+    // resolving candidate, and absence is the condition. The union of every
+    // candidate with .first() is exactly "none of these is on the page" under
+    // toBeHidden / toHaveCount(0) — the same rule replay applies (waitsForAbsence).
+    if (waitsForAbsence(step, args)) {
+        const chain = step.locators?.target ?? [];
+        noteSlots(chain, ctx);
+        const union = chainSource(chain, { slot: slotAsParam, indent: CONT_INDENT }).source;
+        if (!union) {
+            out.push(`// TODO: no locator this compiler can express for ${step.tool} — fill it in by hand.`);
+            return out;
+        }
+        out.push(waitForLine(`(${union}).first()`, args, num('timeout_ms')));
+        return out;
+    }
+    // A read resolves and reads through `readOptional`, which cannot throw: see
+    // its comment. It never goes through `actionTarget`, because a `pick` emitted
+    // as its own statement would throw before the read could catch anything.
+    if (isRead) {
+        out.push(...readLines(step, ctx, { any, first }));
+        return out;
+    }
+    // The url this step starts from, so a value it mints is read off the url it
+    // navigated TO and not off the one it left (see urlPartWhen / derivedLines).
+    const minting = derivedHere(segment, index).length > 0 || Boolean(step.mints);
+    const urlBefore = minting ? `urlBefore${++ctx.urls}` : '';
+    if (urlBefore)
+        out.push(`const ${urlBefore} = page.url();`);
+    // Everything from here to the action itself is what the already-in-effect
+    // guard wraps, so remember where it starts.
+    const actionStart = out.length;
+    const picksBefore = ctx.picks;
+    const target = actionTarget(step, 'target', ctx, out, { first, any });
+    if (!target) {
+        ctx.warnings.push(`${ctx.stepId}: step ${index} (${step.tool}) has no locator a spec can express`);
+        out.push(`// TODO: no locator this compiler can express for ${step.tool} — fill it in by hand.`);
+        return out;
+    }
+    switch (step.tool) {
+        case 'click':
+            out.push(`await click(${target});`);
+            break;
+        case 'dblclick':
+            out.push(`await click(${target}, { dbl: true });`);
+            break;
+        // Not through the tiers: tools.ts dispatches a right or modifier click as a
+        // plain, single Playwright click too (only click/dblclick reach
+        // robustClick), and a FORCED right click on the wrong layer would open
+        // someone else's context menu.
+        case 'right_click':
+            out.push(`await ${target}.click({ button: 'right' }); // plain, as replay dispatches it — robustClick's tiers are for click/dblclick only`);
+            break;
+        case 'modifier_click': {
+            const mods = Array.isArray(args.modifiers) ? args.modifiers : [];
+            out.push(`await ${target}.click({ modifiers: [${mods.map(q).join(', ')}] }); // plain, as replay dispatches it — robustClick's tiers are for click/dblclick only`);
+            break;
+        }
+        case 'fill':
+            // Through the inlined helper, never `locator.fill`: see its comment.
+            out.push(`await fill(${target}, ${src(str('value'))});`);
+            break;
+        case 'type': {
+            const delay = num('delay_ms');
+            out.push(`await ${target}.pressSequentially(${src(str('text'))}${delay === undefined ? '' : `, { delay: ${delay} }`});`);
+            break;
+        }
+        case 'press':
+            out.push(`await ${target}.press(${src(str('key'))});`);
+            break;
+        case 'select': {
+            // By label first, not value: the recording watched a human pick the
+            // option they could read, and an app is free to renumber its values.
+            // Through the inlined helper, never `locator.selectOption` alone — the
+            // recorded `optionValue` is the last resort replay itself keeps.
+            const fallback = typeof args.optionValue === 'string' && args.optionValue ? `, ${src(str('optionValue'))}` : '';
+            out.push(`await select(${target}, ${src(str('option'))}${fallback});`);
+            break;
+        }
+        case 'check':
+            out.push(`await ${target}.${args.checked === false ? 'uncheck' : 'check'}();`);
+            break;
+        case 'hover':
+            // Through the inlined helper, never `locator.hover` alone: see its comment.
+            out.push(`await hover(${target});`);
+            break;
+        case 'scroll_into_view':
+            out.push(`await ${target}.scrollIntoViewIfNeeded();`);
+            break;
+        case 'upload': {
+            const paths = Array.isArray(args.paths) ? args.paths : [];
+            out.push(`await ${target}.setInputFiles([${paths.map(q).join(', ')}]);`);
+            break;
+        }
+        case 'download': {
+            const n = ++ctx.downloads;
+            out.push(`const downloadPromise${n} = page.waitForEvent('download');`);
+            out.push(`await ${target}.click();`);
+            out.push(`const download${n} = await downloadPromise${n};`);
+            out.push(`await download${n}.saveAs(${args.save_path ? src(str('save_path')) : `\`downloads/\${download${n}.suggestedFilename()}\``});`);
+            break;
+        }
+        case 'drag': {
+            const source = actionTarget(step, 'source', ctx, out);
+            if (source)
+                out.push(`await ${source}.dragTo(${target});`);
+            else
+                out.push(`// TODO: no locator this compiler can express for the drag source.`);
+            break;
+        }
+        case 'wait_for':
+            out.push(waitForLine(target, args, num('timeout_ms')));
+            break;
+        default:
+            out.push(`// TODO: recorded tool ${step.tool} has no Tier 2 form.`);
+            ctx.warnings.push(`${ctx.stepId}: step ${index} uses tool ${step.tool}, which has no Tier 2 form`);
+            break;
+    }
+    wrapAlreadyInEffect(step, ctx, out, actionStart);
+    // A flagged step whose target resolved to a SINGLE candidate emitted no
+    // `pick`, so there is no throw to carry the note: the action is a bare
+    // locator call whose Playwright timeout says only that a selector never
+    // resolved. Rethrow with the diagnostic appended, so every way a flagged
+    // step can fail says the same thing.
+    if (ctx.note && ctx.picks === picksBefore)
+        noteRethrow(out, actionStart, ctx.note);
+    derivedLines(segment, index, ctx, out, urlBefore);
+    if (step.mints) {
+        out.push(`// This step CREATES a record (its id is url part ${q(step.mints.at)}) — clean it up in your teardown.`);
+        // Nothing else read the post-action url here, so publish the id rather than
+        // leave a teardown to re-derive it: replay keeps the same value (res.created)
+        // for exactly this reason. Read the settled way, off the url the step
+        // navigated TO — the same reason derived values cannot be read in the
+        // click's own tick.
+        if (!derivedHere(segment, index).length) {
+            out.push(`outputs[${q(`${ctx.stepId}.minted`)}] = await urlPartWhen(page, ${q(step.mints.at)}, ${urlBefore});`);
+        }
+    }
+    if (!isRead) {
+        effectLines(step, ctx, out);
+        expectationLines(step, out);
+    }
+    return out;
+}
+/**
+ * Wrap `out[from..]` in a try/catch that appends `note` to whatever it throws.
+ *
+ * The note is compile's diagnostic for this flow step, and a rethrow — not a
+ * swallow — is the point: the step still fails, it just stops lying about why.
+ */
+function noteRethrow(out, from, note) {
+    const inner = out.splice(from).map((l) => l
+        .split('\n')
+        .map((x) => (x ? `  ${x}` : x))
+        .join('\n'));
+    out.push('try {', ...inner, '} catch (err) {', `  if (err instanceof Error) err.message += ${q(`\n  ${note}`)};`, '  throw err;', '}');
+}
+function waitForLine(target, args, timeout) {
+    const only = timeout && timeout !== DEFAULT_WAIT_MS ? `{ timeout: ${timeout} }` : '';
+    const opt = only ? `, ${only}` : '';
+    switch (String(args.state)) {
+        case 'visible':
+            return `await expect(${target}).toBeVisible(${only});`;
+        case 'hidden':
+            return `await expect(${target}).toBeHidden(${only});`;
+        case 'text_equals':
+            return `await expect(${target}).toHaveText(${src(String(args.text ?? ''))}${opt});`;
+        case 'text_contains':
+            return `await expect(${target}).toContainText(${src(String(args.text ?? ''))}${opt});`;
+        case 'count':
+            return `await expect(${target}).toHaveCount(${Number(args.count ?? 0)}${opt});`;
+        default:
+            return `// TODO: recorded wait_for state ${String(args.state)} has no Tier 2 form.`;
+    }
+}
+/**
+ * A read publishes the value later steps reference by `<stepId>.<label>`; an
+ * unlabelled one never reaches here.
+ *
+ * Resolution and read go through `readOptional` TOGETHER, single candidate or
+ * many, so that neither half can fail the flow: replay skips a read it cannot
+ * resolve — and one whose read errors — and carries on, because an observation
+ * that could not be re-captured says nothing about whether the procedure ran.
+ * Emitting the single-candidate case as a bare `await loc.textContent()` would
+ * have thrown on exactly the same page where the multi-candidate case does.
+ */
+function readLines(step, ctx, opts) {
+    const what = String(step.args?.what ?? 'text');
+    const out = `outputs[${q(`${ctx.stepId}.${step.label ?? ''}`)}]`;
+    const loc = opts.first ? 'loc.first()' : 'loc';
+    let read = null;
+    if (what === 'value')
+        read = `async (loc: Locator) => await ${loc}.inputValue()`;
+    // read_all legitimately matches many elements, so textContent's strict mode
+    // would throw where replay read every match.
+    else if (what === 'text') {
+        read =
+            step.tool === 'read_all'
+                ? `async (loc: Locator) => (await ${loc}.allTextContents()).join('\\n')`
+                : `async (loc: Locator) => (await ${loc}.textContent()) ?? ''`;
+    }
+    if (!read)
+        return [`// TODO: read what=${commentSafe(what)} has no Tier 2 form (label ${commentSafe(step.label ?? '')}).`];
+    const chain = step.locators?.target ?? [];
+    noteSlots(chain, ctx);
+    const { sources } = candidateSources(chain, { slot: slotAsParam });
+    if (!sources.length) {
+        ctx.warnings.push(`${ctx.stepId}: step ${ctx.stepIndex} (${step.tool}) has no locator a spec can express`);
+        return [`// TODO: no locator this compiler can express for ${step.tool} — fill it in by hand.`];
+    }
+    const where = `${ctx.stepId} ${ctx.segmentId}/${ctx.stepIndex} target`;
+    const lines = [`${out} = await readOptional(page, [`];
+    for (const source of sources)
+        lines.push(`${CONT_INDENT}${source},`);
+    lines.push(`], ${q(where)}, ${read}${opts.any ? ', { any: true }' : ''});`);
+    return lines;
+}
+/**
+ * A folded loop: the recording did the same thing to record after record,
+ * and replay repeats the body while the guard still matches, capped at
+ * `max`. Tier 2 keeps the guard and the cap and always acts on the first
+ * match — right for a list that shrinks, and the one place a spec cannot
+ * follow replay's cursor, so it says so.
+ */
+function emitLoop(step, segment, index, ctx) {
+    const body = step.body ?? [];
+    const guardChain = step.while ?? body[0]?.locators?.target ?? [];
+    noteSlots(guardChain, ctx);
+    const guard = chainSource(guardChain, { slot: slotAsParam, indent: CONT_INDENT }).source;
+    if (!guard || !body.length) {
+        ctx.warnings.push(`${ctx.stepId}: step ${index} is a loop with no ${guard ? 'body' : 'guard a spec can express'}`);
+        return [
+            `// @step ${ctx.stepId} ${segment.id}/${index}`,
+            `// TODO: recorded loop at step ${index} has no ${guard ? 'body' : 'expressible guard'}.`,
+        ];
+    }
+    const max = step.max ?? DEFAULT_LOOP_MAX;
+    const name = `guard${++ctx.loops}`;
+    ctx.segmentId = segment.id;
+    ctx.stepIndex = index;
+    const out = [
+        `// @step ${ctx.stepId} ${segment.id}/${index}`,
+        '// The recording folded a run of identical actions into a loop. Each pass acts on the',
+        '// FIRST match: right for a list that shrinks, and all a spec can do — replay advances a',
+        '// cursor here when the list stays the same length (see runLoop).',
+        `const ${name} = ${guard};`,
+        `for (let i = 0; i < ${max} && (await ${name}.count()) > 0; i++) {`,
+    ];
+    for (const [k, bstep] of body.entries()) {
+        for (const line of emitSkillStep(bstep, segment, index, ctx, true)) {
+            out.push(...line.split('\n').map((l) => (l ? '  ' + l : l)));
+        }
+        if (k < body.length - 1)
+            out.push('');
+    }
+    out.push('}');
+    return out;
+}
+/** Whether every slot in a marker is bound by this segment's params or its derived values. */
+function markerBound(marker, segment) {
+    const slots = [...marker.matchAll(/\{\{([vd]\d+)\}\}/g)].map((m) => m[1]);
+    if (!slots.length)
+        return Boolean(marker.trim());
+    return slots.every((s) => s in segment.params || s in (segment.derived ?? {}));
+}
+/**
+ * A flow-step param value as it renders in the emitted body: a lone slot is the
+ * param itself (`p.v1`), anything else is recorded text with its slots filled.
+ */
+function valueSource(text) {
+    const only = /^\{\{([vd]\d+)\}\}$/.exec(text);
+    return only ? `p.${only[1]}` : src(text);
+}
+/**
+ * The "already satisfied" guard at the top of a step body, when the step's
+ * procedure carries one.
+ *
+ * WHY A STEP MAY BE ASKED TO DO WHAT IS ALREADY DONE. A flow is a record of
+ * what the orchestrator did, and it retries: fwod34's 06-open asked for an
+ * order to be cancelled and its recording did not land the cancel, so 08-open
+ * was recorded asking for the same cancel again. On REPLAY 06-open works —
+ * and 08-open then goes looking for a Cancel button that a cancelled order
+ * does not have. The recorded procedure is fine; it is simply being run on a
+ * record that has already reached its destination.
+ *
+ * So: identity (this is the right record) AND the goal (it is already in the
+ * state the step produces) short-circuit the step, publishing the values its
+ * read-backs would have published so the steps after it see the same shape.
+ * Emitted only where every marker is BOUND — an unbound `{{v1}}` proves
+ * nothing, and a guard that cannot be sure is not emitted at all, which
+ * simply leaves the step running exactly as it does today.
+ */
+function satisfiedGuard(step, ctx) {
+    const head = step.segments[0];
+    const last = step.segments[step.segments.length - 1];
+    const goal = last?.goal?.requireText ?? [];
+    if (!head || !goal.length)
+        return [];
+    const identity = (head.preconditions.requireText ?? []).filter((m) => markerBound(m, head));
+    if (!identity.length)
+        return [];
+    if (!goal.every((g) => markerBound(g, last)))
+        return [];
+    noteSlots([...identity, ...goal], ctx);
+    const shown = goal.map((g) => `"${g}"`).join(', ');
+    const say = `[sitelooper satisfied] ${step.id} — page shows ${shown}; nothing to do`;
+    // On the page template the goal was read on, or the words mean nothing
+    // (replay's goalSatisfied checks the same url pattern first).
+    const at = urlExpectSource(head.preconditions.urlPattern);
+    const onPage = at ? (at.startsWith('(url') ? `(${at})(new URL(page.url())) && ` : `${at}.test(page.url()) && `) : '';
+    const out = [
+        `// goal: the page already showing ${shown} for this record means the step's work is done —`,
+        '// the same check replay makes before it acts (goalSatisfied, src/skills/replay.ts).',
+        `if (${onPage}await satisfied(page, [${identity.map(src).join(', ')}], [${goal.map(src).join(', ')}])) {`,
+        `  console.log(${src(say)});`,
+    ];
+    // The read-backs never run, so the report template stands in for them: the
+    // same output keys, filled from this run's own params.
+    for (const [label, value] of Object.entries(last.report?.values ?? {})) {
+        if (!label || !value || !markerBound(value, last))
+            continue;
+        noteSlots(value, ctx);
+        out.push(`  outputs[${q(`${step.id}.${label}`)}] = ${valueSource(value)};`);
+    }
+    out.push('  return;', '}');
+    return out;
+}
+/** One segment: its preconditions, then its steps. */
+function emitSegment(segment, ctx) {
+    const out = [];
+    ctx.lastUrl = null;
+    out.push(`// ${segment.id}: ${commentSafe(segment.template)}`);
+    out.push(`// recorded on a page matching ${commentSafe(segment.preconditions.urlPattern)}`);
+    for (const marker of segment.preconditions.requireText ?? []) {
+        // Identity: the url and the page shape match every record of this
+        // template, so only the marker can say this is the RIGHT record. An
+        // unbound marker proves nothing and is skipped, exactly as replay skips it.
+        if (!markerBound(marker, segment)) {
+            out.push(`// identity marker ${commentSafe(marker)} is unbound here — nothing to check.`);
+            continue;
+        }
+        noteSlots(marker, ctx);
+        out.push(`// identity: this must be the record the flow is working on, not another of the same shape.`);
+        // Polled, not asserted once: replay reaches this gate after its own
+        // settleDom, and a spec arrives on a page that may still be rendering.
+        out.push(`await expect.poll(() => present(page, ${src(marker)}), { timeout: ${IDENTITY_WAIT_MS}, message: ${q(`identity: ${commentSafe(marker)} is not on this page`)} }).toBe(true);`);
+    }
+    for (const [i, step] of segment.steps.entries()) {
+        out.push('');
+        const lines = step.tool === 'loop' ? emitLoop(step, segment, i + 1, ctx) : emitSkillStep(step, segment, i + 1, ctx);
+        out.push(...lines);
+    }
+    return out;
+}
+/** The slots a step's `p` object carries: every param of every segment, plus what they mint. */
+function slotsOf(step, found) {
+    const names = new Set(found);
+    for (const seg of step.segments) {
+        for (const name of Object.keys(seg.params))
+            names.add(name);
+        for (const name of Object.keys(seg.derived ?? {}))
+            names.add(name);
+    }
+    return [...names].sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+}
+/**
+ * A flow-step param value as an expression: a literal, a run var, an earlier
+ * step's output, or an environment secret. Secrets stay markers everywhere
+ * until the moment they are used — see shared/secrets.ts — and that holds in
+ * a compiled spec too: the emitted file names the variable, never the value.
+ */
+function paramExpr(template, vars) {
+    const parts = [];
+    let last = 0;
+    for (const m of template.matchAll(/\{\{([\w.#:-]+)\}\}/g)) {
+        const at = m.index ?? 0;
+        if (at > last)
+            parts.push({ lit: template.slice(last, at) });
+        parts.push({ expr: refExpr(m[1], vars) });
+        last = at + m[0].length;
+    }
+    if (last < template.length)
+        parts.push({ lit: template.slice(last) });
+    if (!parts.length)
+        return q('');
+    if (parts.length === 1 && parts[0].expr)
+        return parts[0].expr;
+    if (parts.every((p) => p.lit !== undefined))
+        return q(parts.map((p) => p.lit).join(''));
+    return '`' + parts.map((p) => (p.lit !== undefined ? templateSafe(p.lit) : '${' + p.expr + '}')).join('') + '`';
+}
+function refExpr(ref, vars) {
+    const secret = /^env:([A-Za-z_][A-Za-z0-9_]*)$/.exec(ref);
+    if (secret)
+        return `process.env.${secret[1]} ?? ''`;
+    if (ref.includes('.'))
+        return `outputs[${q(ref)}] ?? ''`;
+    if (vars.has(ref))
+        return `vars.${key(ref)}`.replace(`vars.'${ref}'`, `vars[${q(ref)}]`);
+    // A reference to something the flow never declared: honest at run time
+    // rather than a compile-time guess at what the caller meant.
+    return `(vars as Record<string, string>)[${q(ref)}] ?? ''`;
+}
+/** The `{ v1: …, d1: '' }` argument one step is called with. */
+function callArgs(step, slots, vars, warnings) {
+    const derived = new Set(step.segments.flatMap((s) => Object.keys(s.derived ?? {})));
+    const fields = slots.map((slot) => {
+        // A minted value has no caller binding by construction: the body reads it
+        // off the live url after the step that creates it.
+        if (derived.has(slot))
+            return `${slot}: ''`;
+        const bound = step.params[slot];
+        if (bound !== undefined)
+            return `${slot}: ${paramExpr(bound, vars)}`;
+        const example = step.segments.map((s) => s.params[slot]?.example).find((e) => typeof e === 'string');
+        if (example === undefined)
+            return `${slot}: ''`;
+        // No flow binding: the recording's own value is the only one there is,
+        // and inlining it silently is how a replay comes to work the recorded
+        // run's record. Emitted, but the caller is told.
+        warnings.push(`${step.id}: slot ${slot} has no flow binding — the recorded value is inlined`);
+        return `${slot}: ${paramExpr(example, vars)} /* recorded value; no flow binding */`;
+    });
+    return `{ ${fields.join(', ')} }`;
+}
+/**
+ * The `{{<stepId>.url}}` / `{{<stepId>.url.<part>}}` references this flow's own
+ * params make, grouped by the step that has to publish them.
+ *
+ * WHICH REPLAY RULE THIS MIRRORS. The flow runner publishes every step's END
+ * URL as outputs — the whole url and each identifier-like part (`urlOutputs`
+ * in skills/flow.ts) — and that is how a later step's param
+ * `http://…/d/{{02-create.url.p1}}/…` gets a value. A compiled body published
+ * none of them: it binds what the step mints into its own `p.dN`, which is
+ * segment-local, while `refExpr` resolves the flow-level reference out of
+ * `outputs`. So fwgr27's 03-add did `page.goto('http://127.0.0.1:3000/d//fwgr27-…')`
+ * — the uid segment simply empty — and every locator after it missed on a page
+ * that was not the dashboard. Only the consumed refs are published: an output
+ * nothing reads is noise, and this is exactly what `consumedUrlOutputs` asks.
+ */
+function consumedUrlRefs(spec) {
+    const wanted = new Map();
+    for (const step of spec.steps) {
+        for (const value of Object.values(step.params)) {
+            for (const m of value.matchAll(/\{\{([\w-]+)\.(url(?:\.[\w.-]+)?)\}\}/g)) {
+                const set = wanted.get(m[1]) ?? new Set();
+                set.add(m[2]);
+                wanted.set(m[1], set);
+            }
+        }
+    }
+    // `url` first: it is the one output every step can publish without a read.
+    return new Map([...wanted].map(([id, outs]) => [id, [...outs].sort()]));
+}
+/** The lines that publish one step's end-url outputs, or none. */
+function urlOutputLines(stepId, outs) {
+    if (!outs?.length)
+        return [];
+    const lines = ['// Later steps refer to this step by where it left the browser, so publish its'];
+    lines.push('// end url the way the flow runner does (urlOutputs / consumedUrlOutputs in');
+    lines.push('// src/skills/flow.ts) — unpublished, `{{' + stepId + '.' + outs[0] + '}}` resolves to nothing.');
+    for (const out of outs) {
+        const key = `${stepId}.${out}`;
+        if (out === 'url')
+            lines.push(`outputs[${q(key)}] = page.url();`);
+        // No urlBefore: nothing here acted, so the wait is simply for the part to
+        // be there at all — an SPA can update its url a beat after the page itself
+        // settles, which is what consumedUrlOutputs waits out.
+        else
+            lines.push(`outputs[${q(key)}] = await urlPartWhen(page, ${q(out.slice('url.'.length))});`);
+    }
+    return lines;
+}
+export function emitFlowFile(spec, o) {
+    if (o.tier !== 'plain')
+        throw new Error(`unknown emit tier ${String(o.tier)}`);
+    const warnings = [];
+    const vars = new Set(spec.vars);
+    const urlRefs = consumedUrlRefs(spec);
+    const flagged = flaggedByStep(o.diagnostics);
+    // Bodies first: which helpers the file needs is decided by what they use.
+    const bodies = spec.steps.map((step) => {
+        const ctx = { stepId: step.id, slots: new Set(), warnings, downloads: 0, lastUrl: null, loops: 0, picks: 0, urls: 0, binds: 0, segmentId: '', stepIndex: 0, note: stepNote(flagged.get(step.id)) };
+        const lines = [];
+        if (!step.segments.length) {
+            lines.push(`// TODO: no converged procedure for ${JSON.stringify(commentSafe(step.instruction))}`);
+            lines.push(`throw new Error(${q(`step ${step.id} has no converged procedure — record it with sitelooper, then compile again`)});`);
+        }
+        else {
+            const guard = satisfiedGuard(step, ctx);
+            if (guard.length)
+                lines.push(...guard, '');
+            for (const [i, segment] of step.segments.entries()) {
+                if (i)
+                    lines.push('');
+                lines.push(...emitSegment(segment, ctx));
+            }
+            const published = urlOutputLines(step.id, urlRefs.get(step.id));
+            if (published.length)
+                lines.push('', ...published);
+        }
+        return { step, lines, slots: slotsOf(step, ctx.slots) };
+    });
+    const body = bodies.flatMap((b) => b.lines).join('\n');
+    const helpers = neededHelpers(body);
+    const out = [
+        '// @sitelooper-flow v1',
+        `// Generated by sitelooper from flow ${JSON.stringify(spec.name)} — do not edit by hand.`,
+        '// Repair drift with `sitelooper repair <this file>`; the FLOW constant below is the source of truth.',
+        `import { expect, ${helpers.some((h) => h.source.some((l) => l.includes('Locator'))) ? 'type Locator, ' : ''}type Page } from '@playwright/test';`,
+        '',
+        BEGIN_MARKER,
+        `export const FLOW = ${JSON.stringify(spec, null, 2)};`,
+        END_MARKER,
+        '',
+        `export type Vars = ${spec.vars.length ? `{ ${spec.vars.map((v) => `${key(v)}: string`).join('; ')} }` : 'Record<string, never>'};`,
+        '/** Values the steps read back, keyed "<stepId>.<output>". */',
+        'export interface Outputs {',
+        '  [key: string]: string;',
+        '}',
+        '/**',
+        ' * The wall-clock budget one run of this flow needs under a test runner: every',
+        ' * recorded step may spend a settle window, a pick, three click tiers and a 5s',
+        " * expectation, so a flow is budgeted per recorded step, never at the runner's",
+        ' * 60s default. fwod34 (odoo, 9 flow steps, ~80 recorded steps) ran ~63s to',
+        " * its 06-open before that default cut a click's retry short of the force",
+        ' * tier that replay reaches. The generated `.spec.ts` applies it with',
+        ' * `test.setTimeout(BUDGET_MS)`; your own spec can do the same or override it.',
+        ' */',
+        `export const BUDGET_MS = ${budgetMs(spec)};`,
+        '/**',
+        ' * Every `[sitelooper drift] …` line this run logged (see `pick` below):',
+        ' * a primary locator that missed and the recorded fallback that covered for',
+        ' * it. Always exported — even a flow with no multi-candidate step today may',
+        " * gain one after a repair — so a caller's assertion never has to guess",
+        ' * whether it exists. Attach it from the user spec if you want it in the',
+        " * Playwright report: `test.info().attach('sitelooper-drift', { body: DRIFT.join('\\n') })`.",
+        ' */',
+        'export const DRIFT: string[] = [];',
+    ];
+    for (const helper of helpers)
+        out.push('', ...helper.source);
+    out.push('', 'export const steps = {');
+    for (const [i, b] of bodies.entries()) {
+        if (i)
+            out.push('');
+        // Compile's verdict on this step, above the step, before its instruction:
+        // a reviewer reading the generated file sees WHY it is expected to fail
+        // and what to run, not a locator error they will read as app drift.
+        for (const d of flagged.get(b.step.id) ?? []) {
+            for (const line of formatDiagnostic(d).split('\n'))
+                out.push(`  // ${commentSafe(line)}`);
+        }
+        out.push(`  /** ${commentSafe(b.step.instruction)} */`);
+        const p = b.slots.length ? `{ ${b.slots.map((s) => `${s}: string`).join('; ')} }` : 'Record<string, string>';
+        out.push(`  async ${q(b.step.id)}(page: Page, p: ${p}, outputs: Outputs): Promise<void> {`);
+        for (const line of b.lines)
+            out.push(...line.split('\n').map((l) => (l ? '    ' + l : '')));
+        out.push('  },');
+    }
+    out.push('};');
+    out.push('', '/** Runs every step in order. */', 'export async function runFlow(page: Page, vars: Vars): Promise<Outputs> {');
+    out.push('  const outputs: Outputs = {};');
+    out.push(`  await page.goto(${q(spec.startUrl)});`);
+    for (const b of bodies) {
+        out.push(`  await steps[${q(b.step.id)}](page, ${callArgs(b.step, b.slots, vars, warnings)}, outputs);`);
+    }
+    out.push('  return outputs;', '}', '');
+    return { source: out.join('\n'), warnings };
+}
+/** An environment variable name for a run var, so the scaffold has something to pass. */
+function envName(name) {
+    return name.replace(/[^A-Za-z0-9]+/g, '_').toUpperCase();
+}
+/**
+ * The user's half. Written once and never rewritten, so it is deliberately
+ * thin: the call, and an invitation to assert whatever this suite cares
+ * about. Everything the tool regenerates lives in the `.flow.ts` beside it.
+ */
+/** Per-step budget: settle (≤2s) + pick + three 5s click tiers + a 5s expectation, with headroom. */
+const STEP_BUDGET_MS = 30_000;
+const MIN_BUDGET_MS = 120_000;
+/** The test budget for one run of the whole flow, from its recorded step count. */
+export function budgetMs(spec) {
+    const steps = spec.steps.reduce((n, st) => n + st.segments.reduce((m, seg) => m + seg.steps.length, 0), 0);
+    return Math.max(MIN_BUDGET_MS, steps * STEP_BUDGET_MS);
+}
+export function emitSpecFile(spec) {
+    const varFields = spec.vars.map((v) => `${key(v)}: process.env.${envName(v)} ?? ''`).join(', ');
+    return [
+        "import { test, expect } from '@playwright/test';",
+        `import { runFlow, steps, DRIFT, BUDGET_MS } from './${spec.name}.flow';`,
+        '',
+        `test(${q(spec.name)}, async ({ page }) => {`,
+        '  // One test runs the whole flow: budget it by its recorded steps, not the 60s default.',
+        '  test.setTimeout(BUDGET_MS);',
+        `  const outputs = await runFlow(page, ${varFields ? `{ ${varFields} }` : '{}'});`,
+        '  // Add your own assertions here; this file is yours and sitelooper never rewrites it.',
+        '  // `outputs` holds every value the flow read back, keyed "<stepId>.<output>";',
+        '  // `steps` lets you run one step on its own. `DRIFT` accumulates one line per',
+        '  // recorded locator that missed and fell through to a later candidate — attach',
+        '  // it to the report if you want it visible without reading stderr:',
+        "  //   if (DRIFT.length) await test.info().attach('sitelooper-drift', { body: DRIFT.join('\\n') });",
+        '  expect(Object.keys(outputs).length >= 0).toBe(true);',
+        '  void steps;',
+        '});',
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=emit.js.map