sitelooper 0.3.0

package/dist/daemon/recorder.js

@@ -0,0 +1,1232 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureSessionDir } from '../shared/paths.js';
+import { volatileMatcher } from '../shared/text.js';
+import { isRefTarget, refHint, resolveTarget } from './refs.js';
+import { tagComponent } from '../skills/components.js';
+/** Rebuild a candidate into a live Locator. Shared by recording and replay. */
+export function makeLocator(page, c) {
+    let loc;
+    switch (c.kind) {
+        case 'testid':
+            loc = c.attr === 'data-testid' ? page.getByTestId(c.value) : page.locator(`[${c.attr}=${JSON.stringify(c.value)}]`);
+            break;
+        case 'role':
+            // exact: Playwright's default name match is a case-insensitive substring,
+            // so a recorded 'Edit' also matches a sibling 'Exit edit' — which is how
+            // rpgr2-r2 left edit mode instead of entering it and halted the flow.
+            // A name carrying a clock or calendar token ("Due date: 12/31/2026
+            // 07:40") is matched with that token wildcarded — see volatileMatcher —
+            // so a recording's minute does not push the step onto a positional path.
+            loc = page.getByRole(c.role, { name: volatileMatcher(c.name), exact: true });
+            break;
+        case 'label':
+            loc = page.getByLabel(volatileMatcher(c.label));
+            break;
+        case 'placeholder':
+            loc = page.getByPlaceholder(volatileMatcher(c.placeholder));
+            break;
+        case 'text':
+            loc = page.getByText(volatileMatcher(c.text), { exact: true });
+            break;
+        case 'id':
+        case 'css':
+            loc = page.locator(c.selector);
+            break;
+        case 'scoped': {
+            const within = page.locator(c.container, { hasText: c.hasText });
+            loc = c.selector ? within.locator(c.selector) : within;
+            break;
+        }
+        case 'point':
+            // Resolved in two moves: markPoint() finds the element under the
+            // recorded point and tags it; this locator then names the tag.
+            loc = page.locator(`[${POINT_MARK}=${JSON.stringify(pointToken(c))}]`);
+            break;
+    }
+    return c.nth !== undefined ? loc.nth(c.nth) : loc;
+}
+/** The attribute markPoint leaves on the element it found, so a sync Locator can name it. */
+export const POINT_MARK = 'data-sitelooper-point';
+export function pointToken(c) {
+    return `${c.x},${c.y}`;
+}
+/**
+ * Find the element under a recorded point, walk up to its actionable
+ * ancestor, and tag it for makeLocator — but only when it is the KIND of
+ * thing recorded (same role, or same tag when the recording had no role).
+ * Returns what it found, or null when nothing of that kind is there. Scrolls
+ * the window so the point is on screen first; a point in an inner scroller
+ * is found only when that scroller sits where it was recorded.
+ */
+export async function markPoint(page, c) {
+    try {
+        return await page.evaluate(({ x, y, role, tag, mark, token }) => {
+            const ACTIONABLE = 'button,a[href],input,select,textarea,summary,[role],[tabindex],label';
+            const targetY = y - window.innerHeight / 2;
+            if (Math.abs(window.scrollY - targetY) > window.innerHeight / 2 || x - window.scrollX > window.innerWidth) {
+                window.scrollTo(Math.max(0, x - window.innerWidth / 2), Math.max(0, targetY));
+            }
+            const hit = document.elementFromPoint(x - window.scrollX, y - window.scrollY);
+            if (!hit)
+                return null;
+            const kindOf = (el) => {
+                const tagOf = el.tagName.toLowerCase();
+                const type = (el.getAttribute('type') || '').toLowerCase();
+                const implicit = () => {
+                    if (tagOf === 'button')
+                        return 'button';
+                    if (tagOf === 'a')
+                        return el.hasAttribute('href') ? 'link' : null;
+                    if (tagOf === 'select')
+                        return el.hasAttribute('multiple') ? 'listbox' : 'combobox';
+                    if (tagOf === 'textarea')
+                        return 'textbox';
+                    if (tagOf === 'img')
+                        return 'img';
+                    if (/^h[1-6]$/.test(tagOf))
+                        return 'heading';
+                    if (tagOf === 'input') {
+                        if (type === 'checkbox')
+                            return 'checkbox';
+                        if (type === 'radio')
+                            return 'radio';
+                        if (type === 'submit' || type === 'button' || type === 'reset')
+                            return 'button';
+                        if (type === 'search')
+                            return 'searchbox';
+                        if (type === 'number')
+                            return 'spinbutton';
+                        if (['text', 'email', 'tel', 'url', 'password', ''].includes(type))
+                            return 'textbox';
+                        return null;
+                    }
+                    return null;
+                };
+                return { role: el.getAttribute('role') || implicit(), tag: tagOf };
+            };
+            // The point lands on whatever is painted there — a heading's text
+            // span, a button's icon. Walk up a few ancestors for the recorded
+            // KIND (fwgr27: every heading point missed because the hit was the
+            // title's inner span); failing that, the nearest actionable ancestor.
+            let el = null;
+            for (let cur = hit, hops = 0; cur && hops < 6; cur = cur.parentElement, hops++) {
+                const k = kindOf(cur);
+                if (role ? k.role === role : k.tag === tag) {
+                    el = cur;
+                    break;
+                }
+            }
+            el ??= hit.closest(ACTIONABLE) ?? hit;
+            const { role: roleOf, tag: tagOf } = kindOf(el);
+            const same = role ? roleOf === role : tagOf === tag;
+            if (!same)
+                return null;
+            for (const old of Array.from(document.querySelectorAll(`[${mark}]`)))
+                old.removeAttribute(mark);
+            el.setAttribute(mark, token);
+            return { role: roleOf, tag: tagOf };
+        }, { x: c.x, y: c.y, role: c.role, tag: c.tag, mark: POINT_MARK, token: pointToken(c) });
+    }
+    catch {
+        return null;
+    }
+}
+/** Source text for a candidate, e.g. `page.getByRole('button', { name: 'Save' })`. */
+export function candidateExpr(c) {
+    let expr;
+    switch (c.kind) {
+        case 'testid':
+            expr = c.attr === 'data-testid' ? `page.getByTestId(${q(c.value)})` : `page.locator(${q(`[${c.attr}=${JSON.stringify(c.value)}]`)})`;
+            break;
+        case 'role':
+            expr = `page.getByRole(${q(c.role)}, { name: ${q(c.name)}, exact: true })`;
+            break;
+        case 'label':
+            expr = `page.getByLabel(${q(c.label)})`;
+            break;
+        case 'placeholder':
+            expr = `page.getByPlaceholder(${q(c.placeholder)})`;
+            break;
+        case 'text':
+            expr = `page.getByText(${q(c.text)}, { exact: true })`;
+            break;
+        case 'id':
+        case 'css':
+            expr = `page.locator(${q(c.selector)})`;
+            break;
+        case 'scoped':
+            expr = `page.locator(${q(c.container)}, { hasText: ${q(c.hasText)} })` + (c.selector ? `.locator(${q(c.selector)})` : '');
+            break;
+        case 'point':
+            expr = `elementAt(${c.x}, ${c.y}) /* ${c.role ?? c.tag} */`;
+            break;
+    }
+    return c.nth !== undefined ? `${expr}.nth(${c.nth})` : expr;
+}
+/**
+ * candidateExpr's judgement at the EXPRESSION level, for consumers that only
+ * have the string (drift tickets, verify-artifacts, repair triage): does this
+ * locator find its element by where it sits rather than by what it is? One
+ * function, because replay, repair triage and the artifact gate disagreeing
+ * on what "positional" means is how a repair promotes what the gate flags.
+ *
+ * An identity-scoped expression is NOT positional even when it ends in a
+ * positional cell selector: `locator('#rows tr', { hasText: 'x7' })
+ * .locator('td:nth-of-type(2)')` names the record first.
+ */
+export function positionalExpr(expr) {
+    if (/hasText:/.test(expr))
+        return false;
+    return /^elementAt\(/.test(expr) || /nth-of-type|nth-child|>>\s*nth=|\.nth\(/.test(expr) || (expr.match(/>/g) ?? []).length > 2;
+}
+/** Click tools: their target may be a table row whose durable locator is the record link inside it. */
+const CLICK_TOOLS = new Set(['click', 'dblclick', 'modifier_click', 'right_click']);
+/** Tools whose target is worth tagging with its component family (recipe compilation). */
+const COMPONENT_TOOLS = new Set(['click', 'dblclick', 'fill', 'type', 'press']);
+/** Tools that map onto Playwright script lines; everything else is agent-only scaffolding. */
+/** Args whose typed value identifies a record (see addIdentityHint). */
+const VALUE_ARG_KEYS = ['value', 'text', 'option'];
+const RECORDABLE = new Set([
+    'click', 'dblclick', 'right_click', 'modifier_click', 'fill', 'type', 'press', 'select',
+    'check', 'hover', 'scroll_into_view', 'drag', 'wait_for', 'read', 'read_all', 'eval',
+    'goto', 'back', 'upload', 'download', 'set_viewport', 'set_offline', 'screenshot',
+    'dialog_expect', 'tabs',
+]);
+/** Tools whose observed result is turned into a (commented) assertion. */
+const RESULT_TOOLS = new Set(['read', 'read_all']);
+export function isRecordable(tool) {
+    return RECORDABLE.has(tool);
+}
+/**
+ * Captures the actions an instruction takes as replayable Playwright steps.
+ *
+ * The agent drives the page through `@ref` handles, which are snapshot-scoped
+ * and meaningless in a standalone test, so every target is re-described against
+ * the live DOM *before* the action runs (afterwards the element may be gone),
+ * and the resulting expression is replayed to confirm it still resolves to that
+ * exact element. Entries are appended to `script.jsonl` in the session dir as
+ * they happen, so a recording survives a daemon restart or a hard kill.
+ */
+export class ScriptRecorder {
+    session;
+    entries = [];
+    /**
+     * How many entries were already on disk when this daemon started — a
+     * PREVIOUS take under the same session name. They are kept (a daemon that
+     * crashed mid-instruction should not lose the run's history) but they are
+     * not part of this take: fwrd16's container restarted, the runner cleared
+     * bench/results and re-recorded, and because the session dir survived, the
+     * exported flow contained the task TWICE — nine steps from the killed take
+     * followed by eight from the re-run. Both replays dutifully did the whole
+     * lifecycle twice and the verifier still scored them 6/6.
+     */
+    priorCount = 0;
+    get priorEntries() {
+        return this.priorCount;
+    }
+    constructor(session) {
+        this.session = session;
+        this.load();
+        this.priorCount = this.entries.length;
+    }
+    /** Entries recorded by THIS take — what a flow export may build from. */
+    entriesThisTake() {
+        return this.entries.slice(this.priorEntries);
+    }
+    file() {
+        return path.join(ensureSessionDir(this.session), 'script.jsonl');
+    }
+    load() {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.file(), 'utf8');
+        }
+        catch {
+            return; // nothing recorded yet for this session
+        }
+        let torn = !raw.endsWith('\n');
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                this.entries.push(JSON.parse(line));
+            }
+            catch {
+                torn = true; // a partially written last line after a kill — drop it, keep the rest
+            }
+        }
+        // Make the file canonical before the first append: appending after a
+        // torn last line glued the next entry onto the fragment, and the NEXT
+        // load lost that entry too.
+        if (torn)
+            this.rewrite();
+    }
+    append(entry) {
+        this.entries.push(entry);
+        try {
+            fs.appendFileSync(this.file(), JSON.stringify(entry) + '\n');
+        }
+        catch {
+            // recording must never break the run it is observing
+        }
+    }
+    /** Mark the start of one `do` instruction; becomes a test.step in the script. */
+    beginInstruction(text, context = {}) {
+        this.append({ k: 'instruction', text, ...context });
+    }
+    /** Close the current instruction with its outcome (learning mode; flows are built from these). */
+    endInstruction(report) {
+        this.append({ k: 'report', ...report, ...(this.pendingAsk ? { namingAsk: this.pendingAsk } : {}) });
+        this.pendingAsk = undefined;
+    }
+    /** Values the loop is holding this instruction's report to name — see RecordedReport.namingAsk. */
+    pendingAsk;
+    /** Record that the loop asked for names; call again with the outcome once the retry lands. */
+    noteNamingAsk(asked) {
+        this.pendingAsk = { asked, named: false };
+    }
+    /** Mark the held report as having come back with names. */
+    noteNamingAnswered() {
+        if (this.pendingAsk)
+            this.pendingAsk.named = true;
+    }
+    /**
+     * Pin the skill this instruction produced onto its report entry, after
+     * compilation (which happens once the report is already recorded). Rewrites
+     * the last report entry in memory and in script.jsonl so a flow exported
+     * later has the skill to replay.
+     */
+    pinSkill(skill) {
+        for (let i = this.entries.length - 1; i >= 0; i--) {
+            const e = this.entries[i];
+            if (e.k === 'report') {
+                if (!e.skill)
+                    e.skill = skill;
+                this.rewrite();
+                return;
+            }
+            if (e.k === 'instruction')
+                return; // no report for this instruction
+        }
+    }
+    /** Rewrite script.jsonl after in-place entry edits (post-session relabel). */
+    persist() {
+        this.rewrite();
+    }
+    rewrite() {
+        try {
+            fs.writeFileSync(this.file(), this.entries.map((e) => JSON.stringify(e)).join('\n') + '\n');
+        }
+        catch {
+            // recording must never break the run it observes
+        }
+    }
+    /** Append a synthetic step (a read-back captured at report time). */
+    addStep(step) {
+        this.append(step);
+    }
+    /** Values already read via a read step since the last instruction began. */
+    readResultsThisInstruction() {
+        const out = new Set();
+        for (let i = this.entries.length - 1; i >= 0; i--) {
+            const e = this.entries[i];
+            if (e.k === 'instruction')
+                break;
+            if (e.k === 'step' && (e.tool === 'read' || e.tool === 'read_all') && typeof e.result === 'string') {
+                try {
+                    const v = JSON.parse(e.result);
+                    if (typeof v === 'string')
+                        out.add(v);
+                }
+                catch {
+                    out.add(e.result);
+                }
+            }
+        }
+        return out;
+    }
+    /**
+     * The current instruction's real reads with their parsed values — target
+     * label included, read_all arrays expanded — for report-time promotion of
+     * prose-cited values into evidence.values. Synthetic read-backs excluded.
+     */
+    readsThisInstruction() {
+        const out = [];
+        for (let i = this.entries.length - 1; i >= 0; i--) {
+            const e = this.entries[i];
+            if (e.k === 'instruction')
+                break;
+            if (e.k !== 'step' || (e.tool !== 'read' && e.tool !== 'read_all') || typeof e.result !== 'string')
+                continue;
+            if (e.args.target === '(read-back)')
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(e.result);
+            }
+            catch {
+                parsed = e.result;
+            }
+            const values = (Array.isArray(parsed) ? parsed : [parsed]).filter((v) => typeof v === 'string');
+            const label = typeof e.args.label === 'string' && e.args.label.trim() ? e.args.label.trim() : undefined;
+            if (values.length)
+                out.unshift({ target: String(e.args.target ?? ''), values, ...(label ? { label } : {}) });
+        }
+        return out;
+    }
+    /** Index just past the last entry — pass to entriesSince() to read back one instruction. */
+    mark() {
+        return this.entries.length;
+    }
+    entriesSince(mark) {
+        return this.entries.slice(mark);
+    }
+    clear() {
+        this.entries.length = 0;
+        this.priorCount = 0; // a cleared recording has no previous take to skip
+        try {
+            fs.rmSync(this.file(), { force: true });
+        }
+        catch {
+            // best effort
+        }
+    }
+    /**
+     * Describe a step's targets against the live page. Called BEFORE the action,
+     * because a click can navigate or unmount the very element being described.
+     * Returns null for tools that do not map onto a script line.
+     */
+    async prepare(page, tool, args, 
+    /** Pre-resolved locators (replay): described from the element itself, not from args. */
+    resolved) {
+        if (!RECORDABLE.has(tool))
+            return null;
+        // What the agent types names what it creates: the ticket title typed here
+        // is how every later read in this instruction can be anchored to the row
+        // it belongs to rather than to a row number.
+        for (const key of VALUE_ARG_KEYS) {
+            const v = args[key];
+            if (typeof v === 'string')
+                addIdentityHint(v);
+        }
+        const locators = {};
+        for (const key of ['target', 'source']) {
+            const raw = args[key];
+            const retarget = key === 'target' && CLICK_TOOLS.has(tool);
+            if (resolved?.[key]) {
+                const rawText = typeof raw === 'string' ? raw : '';
+                locators[key] = await describeLocator(page, resolved[key], rawText, retarget).catch(() => ({
+                    expr: '',
+                    verified: false,
+                    raw: rawText,
+                }));
+                continue;
+            }
+            if (typeof raw !== 'string' || !raw.trim())
+                continue;
+            locators[key] = await describeTarget(page, raw, retarget).catch(() => ({ expr: '', verified: false, raw }));
+        }
+        // Component tagging (PLAN-component-recipes): note which recognized
+        // widget family the target sits inside, so a successful agent-driven
+        // interaction with a hard component can later compile into a recipe.
+        // Best effort like everything else here — a missing tag just means no
+        // recipe is learned from this step.
+        let component;
+        if (COMPONENT_TOOLS.has(tool) && typeof args.target === 'string' && args.target.trim()) {
+            const target = resolved?.target ?? resolveTarget(page, args.target);
+            component = (await tagComponent(target).catch(() => null)) ?? undefined;
+        }
+        return { k: 'step', tool, args, locators, ...(component ? { component } : {}) };
+    }
+    /** Commit a prepared step once the action succeeded. Failed actions are dropped. */
+    commit(step, result, extra = {}) {
+        if (!step)
+            return;
+        // A select is recorded by the option's visible LABEL whatever the caller
+        // passed: the label is the term the procedure has provenance for (it is
+        // what the instruction names, what an earlier step minted), while the
+        // value is the app's key for that option and carries none. The value the
+        // step actually selected is kept as the fallback `optionValue`.
+        let args = step.args;
+        const label = step.tool === 'select' ? /\blabel=("(?:[^"\\]|\\.)*")$/.exec(result)?.[1] : undefined;
+        if (label) {
+            const shown = JSON.parse(label);
+            if (shown && shown !== args.option)
+                args = { ...args, option: shown, optionValue: String(args.option ?? '') };
+        }
+        const entry = {
+            ...step,
+            args,
+            ...(extra.diff ? { diff: extra.diff } : {}),
+            ...(extra.via ? { via: extra.via } : {}),
+            ...(extra.fingerprintAfter ? { fingerprintAfter: extra.fingerprintAfter } : {}),
+        };
+        this.append(RESULT_TOOLS.has(step.tool) ? { ...entry, result } : entry);
+    }
+}
+/**
+ * Turn one agent-supplied target into a durable locator expression. Raw CSS
+ * selectors pass through as-is (the agent already chose something stable);
+ * `@ref` handles are re-derived from the element's own attributes, preferring
+ * test ids and roles over structural paths.
+ */
+/**
+ * How to record a raw target the agent typed. Almost everything is an opaque
+ * selector string and stays `css` — but `text="..."` is Playwright's TEXT
+ * engine, not CSS, and typing it as css cost us the whole identity guard:
+ * identityOfPrimary reads name/text/label/hasText and deliberately skips css
+ * ("a slot inside a selector is an address, not a name"), so a primary that
+ * named the record by its title advertised NO identity, and every fallback —
+ * including `tr:nth-of-type(1)` — was waved through unchecked.
+ *
+ * fwrd19l 01-open and 02-open, on every replay: the row was not painted yet
+ * (repair-desk defers its list refetch BY DESIGN), all three text-bearing
+ * candidates missed, and the positional one resolved instantly against
+ * whatever sat in row 1. It passed only because a new ticket sorts to the top.
+ *
+ * Typing it correctly re-arms the guard, which rejects the positional
+ * fallback, which makes the walk return nothing — which is what lets
+ * resolveChain's wait run at all, so the anchor wins once the row lands.
+ *
+ * Only the quoted form maps cleanly: `text="X"` is exact and whitespace
+ * -trimmed, which is what getByText(X, { exact: true }) does. Unquoted
+ * (substring, case-insensitive) and regex forms have no equivalent, so they
+ * stay css rather than being silently narrowed.
+ */
+export function primaryFor(raw) {
+    const m = /^text=(?:"([^"]*)"|'([^']*)')$/.exec(raw.trim());
+    const text = m ? (m[1] ?? m[2]) : undefined;
+    return text ? { kind: 'text', text } : { kind: 'css', selector: raw };
+}
+export async function describeTarget(page, raw, retarget = false) {
+    if (!isRefTarget(raw)) {
+        // A raw selector the agent chose: keep it as the primary, but still
+        // describe the element it hit so replay has attribute-based fallbacks.
+        const loc = page.locator(raw);
+        const count = await loc.count().catch(() => 0);
+        const primary = primaryFor(raw);
+        if (count !== 1)
+            return { expr: candidateExpr(primary), verified: false, raw, chain: [primary] };
+        const handle = await loc.elementHandle({ timeout: 2_000 }).catch(() => null);
+        if (!handle)
+            return { expr: candidateExpr(primary), verified: true, raw, chain: [primary] };
+        try {
+            const info = (await handle.evaluate(describeInPage));
+            // Dedupe: a `text="X"` primary is now the same candidate the described
+            // element yields, and carrying it twice only shortens the useful chain.
+            const rest = (await verifiedChain(page, info, handle)).chain.filter((c) => candidateExpr(c) !== candidateExpr(primary));
+            return { expr: candidateExpr(primary), verified: true, raw, chain: [primary, ...rest] };
+        }
+        finally {
+            await handle.dispose().catch(() => { });
+        }
+    }
+    const ref = raw.trim().replace(/^@/, '');
+    const handle = await page
+        .locator(`aria-ref=${ref}`)
+        .first()
+        .elementHandle({ timeout: 2_000 })
+        .catch(() => null);
+    if (!handle) {
+        // The element is already gone (re-rendered list, closed picker). The
+        // snapshot that minted the ref still says what it was, and a role+name
+        // locator beats no locator: unverified, but it can resolve on the next
+        // run where "(none recorded)" never can — fwgr20's 02-create died on
+        // exactly such a step, a data-source picker item, on every replay.
+        const hint = refHint(page, ref);
+        if (hint?.name) {
+            const c = { kind: 'role', role: hint.role, name: hint.name };
+            return { expr: candidateExpr(c), verified: false, raw, chain: [c] };
+        }
+        return { expr: '', verified: false, raw };
+    }
+    try {
+        return await describeHandle(page, handle, raw, retarget);
+    }
+    finally {
+        await handle.dispose().catch(() => { });
+    }
+}
+/**
+ * The identifying string a candidate matches on — the thing that would make it
+ * a *circular* locator if it equals the value we are trying to re-read. A price
+ * cell must not be located by "125.00"; it is located by its testid or its
+ * structural path instead.
+ */
+function candidateIdentity(c) {
+    switch (c.kind) {
+        case 'role':
+            return c.name;
+        case 'text':
+            return c.text;
+        case 'label':
+            return c.label;
+        case 'placeholder':
+            return c.placeholder;
+        case 'testid':
+            return c.value;
+        case 'scoped':
+            // Anchoring a read to the very value it reads would re-read whatever
+            // the next run happens to show there — the circularity this guards.
+            return c.hasText;
+        default:
+            return null;
+    }
+}
+/**
+ * Record-time read-back synthesis (progressive automation option (c)): given a
+ * value the agent just reported, find the live element showing it and derive a
+ * durable, NON-value locator for it, so the same value can be re-read on a
+ * later replay instead of being reported from memory. Returns a synthetic
+ * `read` step, or null when the value cannot be pinned to a single element or
+ * only a value-based (circular) locator would resolve — in which case the
+ * value stays un-threadable and the caller falls back to recovery.
+ */
+export async function captureReadBack(page, value, label) {
+    const v = value.trim();
+    if (v.length < 2 || v.length > 80)
+        return null; // too short to be distinctive, or prose
+    const loc = page.getByText(v, { exact: true });
+    const count = await loc.count().catch(() => 0);
+    // Ambiguity is acceptable for a READ-BACK only when something ELSE names the
+    // record. Within one page state, two matches of the same string do both read
+    // that string — which is what made this look safe. Across RUNS it is not:
+    // odoo keeps every run's records (no rollback, writes are runid-scoped), so
+    // by run 2 the page holds n1's customer as well as n2's and `.first()` is
+    // the wrong one. fwod9 replayed step 1 at tier A and published
+    // "fwod9-n1 Bench Customer" as run n2's observation; 1/6 objectives passed.
+    //
+    // So an ambiguous match must resolve through a row anchor, which carries the
+    // record's own identity and re-binds per run. Repairdesk never showed this
+    // because the harness resets it between runs — there was no earlier record
+    // to find.
+    if (count >= 1) {
+        const handle = await loc.first().elementHandle({ timeout: 1_000 }).catch(() => null);
+        if (handle) {
+            try {
+                const step = await readBackFromHandle(page, handle, v);
+                const winner = step?.locators.target.chain?.[0];
+                if (step && (count === 1 || winner?.kind === 'scoped'))
+                    return label ? { ...step, label } : step;
+            }
+            finally {
+                await handle.dispose().catch(() => { });
+            }
+        }
+    }
+    // Ambiguous by text, but shown in exactly one HEADING. The row-anchor rule
+    // above guards against LIST pages, where a matching string may belong to an
+    // EARLIER run's record (fwod9 republished n1's customer as n2's
+    // observation). A heading is the opposite case: it names the record THIS
+    // PAGE displays, and a replay reaches this page by its own navigation, so
+    // the heading shows the replay's own value. fwod26 is what refusing this
+    // costs: S00021 sat in both the breadcrumb and the form's <h1>, the unique-
+    // text pin bailed, the run's one record reference never became a replayable
+    // read, and five later steps fell back with `unresolved reference(s)` on
+    // BOTH replays — for a value that was on screen, correctly named, the
+    // whole time.
+    if (count > 1) {
+        const inHeading = page.locator('h1, h2, h3').getByText(v, { exact: true });
+        if ((await inHeading.count().catch(() => 0)) === 1) {
+            const handle = await inHeading.elementHandle({ timeout: 1_000 }).catch(() => null);
+            if (handle) {
+                try {
+                    const step = await readBackFromHandle(page, handle, v);
+                    if (step)
+                        return label ? { ...step, label } : step;
+                }
+                finally {
+                    await handle.dispose().catch(() => { });
+                }
+            }
+        }
+    }
+    // Not in a text node — try the form controls. An app that edits records
+    // in-place holds its values in `input.value`, which getByText cannot see:
+    // odoo reported six values from its order form and this pinned NONE of
+    // them, so every later step referencing one lost its zero-model path. The
+    // read is stored with what:'value' so the replay re-reads the control
+    // rather than its label.
+    const form = await captureFormValue(page, v);
+    return form && label ? { ...form, label } : form;
+}
+/**
+ * The single form control whose value IS this string.
+ *
+ * One round trip: comparing values element-by-element from here would be a
+ * round trip each, and a record form can hold dozens.
+ */
+async function captureFormValue(page, v) {
+    const controls = page.locator('input, textarea, select');
+    let hits;
+    try {
+        hits = await controls.evaluateAll((els, want) => els.map((el, i) => ((el.value ?? '').trim() === want ? i : -1)).filter((i) => i >= 0), v);
+    }
+    catch {
+        return null;
+    }
+    if (hits.length !== 1)
+        return null; // ambiguous or absent — a form control has no row anchor to fall back on
+    const handle = await controls.nth(hits[0]).elementHandle({ timeout: 1_000 }).catch(() => null);
+    if (!handle)
+        return null;
+    try {
+        return await readBackFromHandle(page, handle, v, 'value');
+    }
+    finally {
+        await handle.dispose().catch(() => { });
+    }
+}
+/**
+ * Read-back from a selector the MODEL supplied (the verified-fallback path,
+ * for values captureReadBack could not pin by text — e.g. a value that is not
+ * unique). The selector is trusted only after it resolves to exactly one
+ * element whose text actually IS the value; otherwise null and the value stays
+ * un-threadable.
+ */
+export async function captureReadBackAt(page, value, selector) {
+    const v = value.trim();
+    if (!selector.trim() || v.length < 2 || v.length > 80)
+        return null;
+    let loc;
+    try {
+        loc = resolveTarget(page, selector);
+    }
+    catch {
+        return null;
+    }
+    const count = await loc.count().catch(() => 0);
+    if (count !== 1)
+        return null; // must be unambiguous
+    const handle = await loc.first().elementHandle({ timeout: 1_000 }).catch(() => null);
+    if (!handle)
+        return null;
+    try {
+        const raw = await handle
+            .evaluate((el) => (el.innerText ?? el.value ?? '').trim())
+            .catch(() => '');
+        if (raw !== v && !raw.includes(v))
+            return null; // the model pointed at the wrong element
+        return await readBackFromHandle(page, handle, v);
+    }
+    finally {
+        await handle.dispose().catch(() => { });
+    }
+}
+/** Derive a durable, non-circular read step for `value` from a live element. */
+async function readBackFromHandle(page, handle, v, what = 'text') {
+    const info = (await handle.evaluate(describeInPage));
+    const chain = [];
+    let winner = null;
+    for (const candidate of candidatesFor(info)) {
+        // Skip any candidate whose identity IS the value — locating the price by
+        // "125.00" would never match a different price on the next run.
+        if (candidateIdentity(candidate.spec) === v)
+            continue;
+        // Same uniqueness rule as verifiedChain: an ambiguous anchor is not identity.
+        if (candidate.spec.kind === 'scoped' && (await candidate.make(page).count().catch(() => 0)) !== 1)
+            continue;
+        if (candidate.spec.kind === 'point') {
+            chain.push(candidate.spec);
+            continue;
+        }
+        const loc = candidate.make(page);
+        const match = await matchIndex(loc, handle);
+        if (match === null)
+            continue;
+        // Same rule as verifiedChain: an AMBIGUOUS candidate needs its index, and
+        // `match === 0` is not the same as "unique". This copy was missed when
+        // that was fixed, so a read-back pinned to an ambiguous locator could not
+        // be re-resolved.
+        const spec = match.count > 1 || match.index !== 0 ? { ...candidate.spec, nth: match.index } : candidate.spec;
+        if (!winner)
+            winner = spec;
+        chain.push(spec);
+    }
+    if (!winner)
+        return null; // only a circular locator resolved — cannot re-read stably
+    return {
+        k: 'step',
+        tool: 'read',
+        args: { target: '(read-back)', what },
+        locators: { target: { expr: candidateExpr(winner), verified: true, raw: '(read-back)', chain } },
+        result: JSON.stringify(v),
+    };
+}
+/** Describe the element a live Locator resolves to (replay path). */
+export async function describeLocator(page, locator, raw, retarget = false) {
+    const handle = await locator.elementHandle({ timeout: 2_000 }).catch(() => null);
+    if (!handle)
+        return { expr: '', verified: false, raw };
+    try {
+        return await describeHandle(page, handle, raw, retarget);
+    }
+    finally {
+        await handle.dispose().catch(() => { });
+    }
+}
+async function describeHandle(page, handle, raw, retarget = false) {
+    // A click is recorded against the element that best survives the app
+    // restyling itself — see CLICK_RETARGETS. The element the agent actually
+    // clicked keeps its structural path as the chain's last fallback.
+    if (retarget) {
+        for (const better of CLICK_RETARGETS) {
+            const el = await better(handle).catch(() => null);
+            if (!el)
+                continue;
+            try {
+                const info = (await el.evaluate(describeInPage));
+                const { winner, chain } = await verifiedChain(page, info, el);
+                if (winner) {
+                    const selfInfo = (await handle.evaluate(describeInPage));
+                    const fallback = { kind: 'css', selector: selfInfo.cssPath };
+                    return { expr: candidateExpr(winner), verified: true, raw, chain: [...chain, fallback] };
+                }
+            }
+            finally {
+                await el.dispose().catch(() => { });
+            }
+        }
+    }
+    const info = (await handle.evaluate(describeInPage));
+    const { winner, chain } = await verifiedChain(page, info, handle);
+    if (winner)
+        return { expr: candidateExpr(winner), verified: true, raw, chain };
+    // Nothing resolved back to this element — hand over the structural path and
+    // let the generated script flag it, rather than inventing something clean.
+    return { expr: `page.locator(${q(info.cssPath)})`, verified: false, raw, chain };
+}
+/**
+ * Elements a click is better recorded against than the one the agent hit, in
+ * preference order. Each returns a handle to the better target or null.
+ *
+ * 1. A click on a table ROW opening a record is more durably located by the
+ *    record's own link inside it (name = the ref, which parameterises) than
+ *    by the row (name = the whole volatile row text; a positional css
+ *    otherwise).
+ * 2. A click on an INERT element inside a control belongs to the control.
+ *    The agent clicks whatever the snapshot handed it — often a text span
+ *    inside a button — and the span's inner structure is the most volatile
+ *    DOM in the app: fwgr18 recorded grafana's time-picker as
+ *    `[testid] span > span`, the span nesting changed once a range was set,
+ *    and every replay fell to a bare structural path (4 of the sweep's 11
+ *    fallthroughs). The BUTTON has the testid and the stable identity; a
+ *    click on it lands the same.
+ */
+const CLICK_RETARGETS = [recordLinkOf, interactiveAncestorOf];
+/**
+ * If `handle` is an inert presentational element (a span, an icon) sitting
+ * inside an interactive control a few hops up, return the control — the
+ * element whose identity (testid, role, accessible name) survives the app
+ * restyling its innards. Null when the element is itself interactive or no
+ * control encloses it.
+ */
+async function interactiveAncestorOf(handle) {
+    const found = await handle.evaluateHandle((el) => {
+        const node = el;
+        // SVG-namespace elements report a lowercase tagName ("svg", "path"), so
+        // an icon click never matched the inert list until this upper-cased.
+        const tag = (n) => n.tagName.toUpperCase();
+        const interactive = (n) => {
+            if (/^(BUTTON|A|INPUT|SELECT|TEXTAREA|SUMMARY|LABEL)$/.test(tag(n)))
+                return true;
+            const role = n.getAttribute('role');
+            if (role && /^(button|link|menuitem|menuitemcheckbox|menuitemradio|tab|option|checkbox|radio|switch)$/.test(role))
+                return true;
+            return n.hasAttribute('tabindex') && n.getAttribute('tabindex') !== '-1';
+        };
+        if (!/^(SPAN|I|EM|B|STRONG|SVG|PATH|USE|IMG|SMALL|SUP|SUB)$/.test(tag(node)) || interactive(node))
+            return null;
+        for (let cur = node.parentElement, hops = 0; cur && hops < 4; cur = cur.parentElement, hops++) {
+            if (interactive(cur))
+                return cur;
+        }
+        return null;
+    });
+    const el = found.asElement();
+    if (!el) {
+        await found.dispose().catch(() => { });
+        return null;
+    }
+    return el;
+}
+/**
+ * If `handle` is a container (a table row, list item, card) that wraps exactly
+ * one hyperlink, return a handle to that link — the durable, often
+ * parameterisable target for a navigation click. Null otherwise, including
+ * when the element already IS the link or has several links (ambiguous).
+ */
+async function recordLinkOf(handle) {
+    const found = await handle.evaluateHandle((el) => {
+        const node = el;
+        if (node.tagName === 'A')
+            return null; // already a link
+        const container = /^(TR|LI|TD|TH|DIV|SECTION|ARTICLE)$/.test(node.tagName) || node.getAttribute('role') === 'row' || node.getAttribute('role') === 'listitem';
+        if (!container)
+            return null;
+        const links = Array.from(node.querySelectorAll('a[href]')).filter((a) => a.offsetParent !== null || a.getClientRects().length > 0);
+        return links.length === 1 ? links[0] : null;
+    });
+    const el = found.asElement();
+    if (!el) {
+        await found.dispose().catch(() => { });
+        return null;
+    }
+    return el;
+}
+/**
+ * All candidates for an element, the first that resolves back to it marked
+ * with its index. Later candidates are kept unindexed as replay fallbacks —
+ * checking each costs round trips, and a fallback that resolves to exactly
+ * one element needs no index anyway.
+ */
+async function verifiedChain(page, info, handle) {
+    const chain = [];
+    let winner = null;
+    for (const candidate of candidatesFor(info)) {
+        // An identity anchor that matches several elements is not identity. It
+        // would record clean (the handle is simply match 0) and then be discarded
+        // at replay, where ambiguity in the primary reads as drift — so prove it
+        // singles the record out HERE, while the page that produced it is live.
+        if (candidate.spec.kind === 'scoped' && (await candidate.make(page).count().catch(() => 0)) !== 1)
+            continue;
+        // The point is where the element IS, so it always "matches"; it is never
+        // the winner because it names no element, only a place.
+        if (winner || candidate.spec.kind === 'point') {
+            chain.push(candidate.spec);
+            continue;
+        }
+        const loc = candidate.make(page);
+        const match = await matchIndex(loc, handle);
+        if (match === null)
+            continue;
+        // Record the index whenever the locator is AMBIGUOUS, including index 0.
+        // `match === 0` used to mean "no nth needed", conflating "unique" with
+        // "first of several": every part row carries an Edit button, so the
+        // recorded getByRole('button', { name: 'Edit' }) stored no index, and at
+        // replay it matched two elements, read as drift, and fell through to
+        // `tr:nth-of-type(1) > td:nth-of-type(7)` — a structural path onto a
+        // record row, which is the shape behind every wrong-record bug this plan
+        // exists to stop. An ambiguous candidate needs its index to be
+        // reproducible, exactly as an ambiguous anchor needs to be unique.
+        winner = match.count > 1 || match.index !== 0 ? { ...candidate.spec, nth: match.index } : candidate.spec;
+        chain.push(winner);
+    }
+    return { winner, chain };
+}
+/**
+ * Index of `handle` within `locator`'s matches, or null if it is not among the
+ * first few. Identity (not text equality) is the test: two buttons can share a
+ * label, and only the one the agent actually used is the right recording.
+ */
+async function matchIndex(locator, handle) {
+    // One round trip for the index AND the match count, instead of a count
+    // plus one evaluate per candidate element (up to eleven per describe).
+    try {
+        const r = await locator.evaluateAll((els, other) => ({ index: els.indexOf(other), count: els.length }), handle);
+        return r.count === 0 || r.index < 0 || r.index >= MATCH_INDEX_LIMIT ? null : r;
+    }
+    catch {
+        return null; // detached page or malformed selector
+    }
+}
+/** How far into a locator's matches the recorded element may sit and still be indexed. */
+const MATCH_INDEX_LIMIT = 10;
+function candidatesFor(info) {
+    const out = [];
+    // Identity first, when the element sits in a record's row that shows a
+    // value the caller vouched for: that locator names the RECORD, so it is the
+    // only candidate here that survives the record moving, being renumbered, or
+    // another record sorting above it.
+    const anchor = identityAnchor(info);
+    if (anchor)
+        out.push(cand(anchor));
+    if (info.testid) {
+        const { attr, value } = info.testid;
+        out.push(cand({ kind: 'testid', attr, value }));
+    }
+    if (info.role && info.name)
+        out.push(cand({ kind: 'role', role: info.role, name: info.name }));
+    if (info.label)
+        out.push(cand({ kind: 'label', label: info.label }));
+    if (info.placeholder)
+        out.push(cand({ kind: 'placeholder', placeholder: info.placeholder }));
+    if (info.id && isStableId(info.id)) {
+        const sel = /^[A-Za-z][\w-]*$/.test(info.id) ? `#${info.id}` : `[id=${JSON.stringify(info.id)}]`;
+        out.push(cand({ kind: 'id', selector: sel }));
+    }
+    if (info.text && !info.role)
+        out.push(cand({ kind: 'text', text: info.text }));
+    // The anchored rung between the element's own semantics and the bare
+    // positional path: `[ancestor-testid] input` names a region and then the
+    // element's kind within it. The chain walker verifies it against the live
+    // element and adds `nth` only when the region holds several — which
+    // structural() then honestly reports as positional. Without this rung a
+    // testid-rich app whose input's own semantics drift falls straight to
+    // position from the document root (fwgr17-n3's panel-title fill).
+    if (info.anchor) {
+        out.push(cand({ kind: 'css', selector: `[${info.anchor.attr}=${JSON.stringify(info.anchor.value)}] ${info.tag}` }));
+    }
+    out.push(cand({ kind: 'css', selector: info.cssPath }));
+    // Where it was, last of all — see LocatorCandidate 'point'.
+    if (info.box) {
+        const { x, y, w, h } = info.box;
+        out.push(cand({ kind: 'point', x: Math.round(x + w / 2), y: Math.round(y + h / 2), w, h, role: info.role, tag: info.tag, vw: info.viewport.w, vh: info.viewport.h }));
+    }
+    return out;
+}
+/**
+ * Values that IDENTIFY the record being worked on this instruction: the
+ * caller's declared variables (a runid) plus anything typed during the
+ * instruction (the title of the thing just created). Set by the agent loop
+ * around each instruction; used only to prefer a record-anchored locator over
+ * a positional one, so a stale or empty list costs nothing but the old
+ * behaviour.
+ */
+let identityHints = [];
+export function setIdentityHints(values) {
+    identityHints = values.map((v) => String(v ?? '').trim()).filter((v) => v.length >= MIN_HINT_LEN && v.length <= 120);
+}
+export function addIdentityHint(value) {
+    const v = String(value ?? '').trim();
+    if (v.length >= MIN_HINT_LEN && v.length <= 120 && !identityHints.includes(v))
+        identityHints.push(v);
+}
+const MIN_HINT_LEN = 4;
+/** The scoped candidate for this element, when its row shows an identity hint. */
+function identityAnchor(info) {
+    const row = info.row;
+    if (!row || !identityHints.length)
+        return null;
+    // Longest match wins: a part's full name is a sharper anchor than the runid
+    // it starts with, and the runid alone would match every row of this run.
+    const hit = identityHints.filter((h) => row.text.includes(h)).sort((a, b) => b.length - a.length)[0];
+    if (!hit)
+        return null;
+    // A hint can be true of many rows at once: every part created this run is
+    // named "<runid> RD Part X", so `hasText: runid` matches them all and replay
+    // reads that ambiguity as drift (fwrd11l 03-add/04-edit/06-remove). Narrow
+    // it to the shortest CELL containing the hint — that cell names this record
+    // and still carries the hint, so compile slots the known value inside it.
+    const narrowed = row.cells.filter((c) => c.includes(hit)).sort((a, b) => a.length - b.length)[0];
+    const hasText = narrowed && narrowed.length <= 120 ? narrowed : hit;
+    return { kind: 'scoped', container: row.container, hasText, ...(row.inner ? { selector: row.inner } : {}) };
+}
+function cand(spec) {
+    return { spec, expr: candidateExpr(spec), make: (p) => makeLocator(p, spec) };
+}
+/**
+ * Framework-generated ids (React's `:r3:`, hash suffixes, bare counters) are
+ * re-minted on the next run, so they are worse than the structural path.
+ */
+export function isStableId(id) {
+    if (!id || id.length > 64)
+        return false;
+    if (/^[:\d]/.test(id))
+        return false;
+    if (/[0-9a-f]{8,}/i.test(id))
+        return false;
+    // React's useId with the colons swapped for underscores (grafana does
+    // this): `_rgl_`, `_r2u_`. Re-minted every render pass, so a primary built
+    // on one misses on every replay — fwgr18 recorded `[id="_rgl_"]` and
+    // `[id="_r2u_"]` as primaries and both were dead chains at replay time.
+    if (/^_r[0-9a-z]{1,4}_$/i.test(id))
+        return false;
+    return !/^(radix|headlessui|mui|react-aria)[-:]/i.test(id);
+}
+/** Runs in the page: everything a locator can be built from, in one round trip. */
+function describeInPage(node) {
+    const el = node;
+    const attr = (name) => el.getAttribute(name) || null;
+    // The same judgement as isStableId (which this page-side code cannot
+    // call): a framework-minted id (React's `_r8b_`, radix, a hash) anchoring
+    // the structural path or a row container is dead on the next load.
+    const stableId = (id) => Boolean(id) &&
+        id.length <= 64 &&
+        !/^[:\d]/.test(id) &&
+        !/[0-9a-f]{8,}/i.test(id) &&
+        !/^_r[0-9a-z]{1,4}_$/i.test(id) &&
+        !/^(radix|headlessui|mui|react-aria)[-:]/i.test(id);
+    const clean = (s) => {
+        const t = (s ?? '').replace(/\s+/g, ' ').trim();
+        return t && t.length <= 80 ? t : null;
+    };
+    const TESTID_ATTRS = ['data-testid', 'data-test-id', 'data-test', 'data-qa', 'data-cy'];
+    const testidAttr = TESTID_ATTRS.find((a) => el.getAttribute(a));
+    // Nearest testid-carrying ANCESTOR — see ElementInfo.anchor.
+    const anchorOf = () => {
+        for (let cur = el.parentElement, hops = 0; cur && hops < 10; cur = cur.parentElement, hops++) {
+            const a = TESTID_ATTRS.find((x) => cur.getAttribute(x));
+            if (a)
+                return { attr: a, value: cur.getAttribute(a) };
+        }
+        return null;
+    };
+    const tag = el.tagName.toLowerCase();
+    const type = (attr('type') || '').toLowerCase();
+    const implicitRole = () => {
+        if (tag === 'button')
+            return 'button';
+        if (tag === 'a')
+            return el.hasAttribute('href') ? 'link' : null;
+        if (tag === 'select')
+            return el.hasAttribute('multiple') ? 'listbox' : 'combobox';
+        if (tag === 'textarea')
+            return 'textbox';
+        if (tag === 'img')
+            return 'img';
+        if (/^h[1-6]$/.test(tag))
+            return 'heading';
+        if (tag === 'input') {
+            if (type === 'checkbox')
+                return 'checkbox';
+            if (type === 'radio')
+                return 'radio';
+            if (type === 'submit' || type === 'button' || type === 'reset')
+                return 'button';
+            if (type === 'search')
+                return 'searchbox';
+            if (type === 'number')
+                return 'spinbutton';
+            if (['text', 'email', 'tel', 'url', 'password', ''].includes(type))
+                return 'textbox';
+            return null;
+        }
+        return null;
+    };
+    const labelText = () => {
+        const labelledBy = attr('aria-labelledby');
+        if (labelledBy) {
+            const parts = labelledBy
+                .split(/\s+/)
+                .map((id) => el.ownerDocument.getElementById(id)?.textContent ?? '')
+                .join(' ');
+            const cleaned = clean(parts);
+            if (cleaned)
+                return cleaned;
+        }
+        if (el.id) {
+            const forLabel = el.ownerDocument.querySelector(`label[for="${CSS.escape(el.id)}"]`);
+            if (forLabel)
+                return clean(forLabel.textContent);
+        }
+        return clean(el.closest('label')?.textContent ?? null);
+    };
+    const cssPath = () => {
+        const parts = [];
+        let cur = el;
+        while (cur && cur.nodeType === 1 && parts.length < 6) {
+            const node = cur;
+            if (stableId(node.id)) {
+                parts.unshift(`#${CSS.escape(node.id)}`);
+                break;
+            }
+            let part = node.tagName.toLowerCase();
+            const parent = node.parentElement;
+            if (parent) {
+                const sibs = Array.from(parent.children).filter((c) => c.tagName === node.tagName);
+                if (sibs.length > 1)
+                    part += `:nth-of-type(${sibs.indexOf(node) + 1})`;
+            }
+            parts.unshift(part);
+            cur = parent;
+        }
+        return parts.join(' > ');
+    };
+    // Nearest repeated container and this element's path inside it. The
+    // container selector is deliberately GENERIC (its tag, scoped to a stable
+    // ancestor id when there is one) so it matches every record's container on
+    // a later run and `hasText` alone picks the record.
+    const rowOf = () => {
+        let box = el.closest('tr, li, [role="row"], [role="listitem"], [role="option"]');
+        // Not every list is semantic: an app that renders rows as divs is just as
+        // common. Fall back to the nearest ancestor that HAS siblings of its own
+        // shape — that repetition is what makes it a record container.
+        if (!box) {
+            for (let cur = el, hops = 0; cur && hops < 4; cur = cur.parentElement, hops++) {
+                const parent = cur.parentElement;
+                if (!parent)
+                    break;
+                const shape = (n) => `${n.tagName}.${n.getAttribute('class') ?? ''}`;
+                const sibs = Array.from(parent.children).filter((c) => shape(c) === shape(cur));
+                if (sibs.length >= 2 && cur !== el) {
+                    box = cur;
+                    break;
+                }
+            }
+        }
+        if (!box)
+            return null;
+        const text = box.innerText?.replace(/\s+/g, ' ').trim() ?? '';
+        if (!text || text.length > 400)
+            return null;
+        const cls = (box.getAttribute('class') ?? '').trim().split(/\s+/).filter(Boolean)[0];
+        const tagOf = box.tagName.toLowerCase() + (cls && /^[A-Za-z][\w-]*$/.test(cls) ? `.${cls}` : '');
+        let container = tagOf;
+        for (let p = box.parentElement, hops = 0; p && hops < 3; p = p.parentElement, hops++) {
+            if (stableId(p.id)) {
+                container = `#${CSS.escape(p.id)} ${tagOf}`;
+                break;
+            }
+        }
+        // The element's path relative to the container, same shape as cssPath.
+        const parts = [];
+        let cur = el;
+        while (cur && cur !== box && parts.length < 5) {
+            const parent = cur.parentElement;
+            let part = cur.tagName.toLowerCase();
+            if (parent) {
+                const sibs = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);
+                if (sibs.length > 1)
+                    part += `:nth-of-type(${sibs.indexOf(cur) + 1})`;
+            }
+            parts.unshift(part);
+            cur = parent;
+        }
+        // The row's own cells, so an anchor can be narrowed from "contains the
+        // runid" (true of every row this run touched) to the one cell that
+        // actually names this record.
+        const cells = Array.from(box.children)
+            .map((c) => c.innerText?.replace(/\s+/g, ' ').trim() ?? '')
+            .filter((t) => t && t.length <= 120)
+            .slice(0, 12);
+        return { container, text, inner: cur === box ? parts.join(' > ') : '', cells };
+    };
+    const label = labelText();
+    const name = clean(attr('aria-label')) ||
+        label ||
+        clean(attr('placeholder')) ||
+        clean(attr('alt')) ||
+        clean(attr('title')) ||
+        // Never an input's VALUE: it is not an accessible name (getByRole would
+        // not match it at replay), it changes every run, and on an unlabeled
+        // password field it put the typed secret into the recording.
+        clean(tag === 'input' ? '' : el.innerText);
+    return {
+        tag,
+        testid: testidAttr ? { attr: testidAttr, value: el.getAttribute(testidAttr) } : null,
+        id: el.id || null,
+        role: attr('role') || implicitRole(),
+        name,
+        label,
+        placeholder: clean(attr('placeholder')),
+        text: clean(tag === 'input' ? null : el.innerText),
+        cssPath: cssPath(),
+        row: rowOf(),
+        anchor: anchorOf(),
+        box: (() => {
+            const r = el.getBoundingClientRect();
+            if (!r.width && !r.height)
+                return null;
+            const round = (n) => Math.round(n * 10) / 10;
+            return { x: round(r.left + window.scrollX), y: round(r.top + window.scrollY), w: round(r.width), h: round(r.height) };
+        })(),
+        viewport: { w: window.innerWidth, h: window.innerHeight },
+    };
+}
+/** Single-quoted JS string literal. */
+export function q(value) {
+    return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\r/g, '').replace(/\n/g, '\\n')}'`;
+}
+//# sourceMappingURL=recorder.js.map