fast-replay 0.1.0

package/dist/recorder/agent/reveal-tracker.d.ts

@@ -0,0 +1,26 @@
+import type { AgentConfig } from './config.js';
+/**
+ * Decides when a hover deserves to become a step of its own.
+ *
+ * Almost every hover is incidental mouse travel and must be dropped, or the IR
+ * would be unreadable. The exception is the hover-to-open menu: if hovering
+ * revealed the content we then acted on, replay must reproduce that hover or it
+ * will click an element that is not there yet.
+ *
+ * This owns the three pieces of state that decision needs, which is why it is a
+ * unit rather than loose variables shared between the observer and the capture
+ * listeners.
+ */
+export interface RevealTracker {
+    noteHover(el: Element): void;
+    /** Called for every emitted action, to date the reveal cooldown. */
+    noteAction(at: number): void;
+    /** Called by the DOM observer with nodes that just became visible. */
+    noteRevealed(nodes: Element[], at: number): void;
+    /**
+     * Consumes the pending reveal. Returns the hovered element only if it
+     * revealed the thing being acted on now; null otherwise.
+     */
+    takeLoadBearingHover(actionTarget: Element | null): Element | null;
+}
+export declare function createRevealTracker(config: AgentConfig): RevealTracker;

package/dist/recorder/agent/reveal-tracker.js

@@ -0,0 +1,41 @@
+/**
+ * DOM landing right after an action is that action's consequence, not a
+ * hover's. Without this, clicking "Add" and then clicking inside the new row
+ * would invent a bogus hover step on the Add button.
+ */
+const ACTION_COOLDOWN_MS = 600;
+export function createRevealTracker(config) {
+    let pending = null;
+    let lastHovered = null;
+    let lastActionAt = 0;
+    return {
+        noteHover(el) {
+            lastHovered = el;
+        },
+        noteAction(at) {
+            lastActionAt = at;
+        },
+        noteRevealed(nodes, at) {
+            if (!nodes.length || !lastHovered)
+                return;
+            if (at - lastActionAt <= ACTION_COOLDOWN_MS)
+                return;
+            pending = { el: lastHovered, nodes, at };
+        },
+        takeLoadBearingHover(actionTarget) {
+            const reveal = pending;
+            pending = null;
+            if (!reveal || !actionTarget)
+                return null;
+            if (Date.now() - reveal.at > config.hoverRevealWindowMs)
+                return null;
+            if (!reveal.el.isConnected)
+                return null;
+            // Load-bearing means: the thing we are about to act on lives inside what
+            // the hover revealed.
+            const inside = reveal.nodes.some((n) => n === actionTarget || n.contains(actionTarget));
+            return inside ? reveal.el : null;
+        },
+    };
+}
+//# sourceMappingURL=reveal-tracker.js.map

package/dist/recorder/agent/reveal-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reveal-tracker.js","sourceRoot":"","sources":["../../../src/recorder/agent/reveal-tracker.ts"],"names":[],"mappings":"AA2BA;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,MAAM,UAAU,mBAAmB,CAAC,MAAmB;IACrD,IAAI,OAAO,GAAyD,IAAI,CAAC;IACzE,IAAI,WAAW,GAAmB,IAAI,CAAC;IACvC,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,OAAO;QACL,SAAS,CAAC,EAAE;YACV,WAAW,GAAG,EAAE,CAAC;QACnB,CAAC;QAED,UAAU,CAAC,EAAE;YACX,YAAY,GAAG,EAAE,CAAC;QACpB,CAAC;QAED,YAAY,CAAC,KAAK,EAAE,EAAE;YACpB,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,WAAW;gBAAE,OAAO;YAC1C,IAAI,EAAE,GAAG,YAAY,IAAI,kBAAkB;gBAAE,OAAO;YACpD,OAAO,GAAG,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAC3C,CAAC;QAED,oBAAoB,CAAC,YAAY;YAC/B,MAAM,MAAM,GAAG,OAAO,CAAC;YACvB,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,CAAC,MAAM,IAAI,CAAC,YAAY;gBAAE,OAAO,IAAI,CAAC;YAC1C,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,mBAAmB;gBAAE,OAAO,IAAI,CAAC;YACrE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,WAAW;gBAAE,OAAO,IAAI,CAAC;YACxC,yEAAyE;YACzE,sBAAsB;YACtB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,YAAY,IAAI,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;YACxF,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACnC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/recorder/agent/roles.d.ts

@@ -0,0 +1,11 @@
+export declare function getRole(el: Element): string | null;
+/** Elements whose value is typed rather than toggled — the `fill` targets. */
+export declare function isEditable(el: Element | null): el is HTMLElement;
+/**
+ * A pragmatic subset of the accname algorithm — enough to make role+name
+ * selectors useful, without shipping the full 600-line spec. Order follows
+ * accname's precedence for the sources we do implement.
+ */
+export declare function accessibleName(el: Element): string;
+/** Text of the element itself, used for the `text=` selector candidate. */
+export declare function ownText(el: Element): string;

package/dist/recorder/agent/roles.js

@@ -0,0 +1,148 @@
+import { clean, escAttr } from './text.js';
+/** ARIA roles and accessible names, computed from a live element. */
+const TAG_ROLES = {
+    button: 'button',
+    select: 'combobox',
+    textarea: 'textbox',
+    nav: 'navigation',
+    main: 'main',
+    header: 'banner',
+    footer: 'contentinfo',
+    aside: 'complementary',
+    form: 'form',
+    table: 'table',
+    tr: 'row',
+    td: 'cell',
+    th: 'columnheader',
+    ul: 'list',
+    ol: 'list',
+    li: 'listitem',
+    dialog: 'dialog',
+    option: 'option',
+    h1: 'heading',
+    h2: 'heading',
+    h3: 'heading',
+    h4: 'heading',
+    h5: 'heading',
+    h6: 'heading',
+};
+const INPUT_ROLES = {
+    button: 'button',
+    submit: 'button',
+    reset: 'button',
+    image: 'button',
+    checkbox: 'checkbox',
+    radio: 'radio',
+    range: 'slider',
+    number: 'spinbutton',
+    search: 'searchbox',
+    email: 'textbox',
+    tel: 'textbox',
+    text: 'textbox',
+    url: 'textbox',
+};
+/** Roles whose accessible name comes from their own text content. */
+const NAME_FROM_CONTENT = [
+    'button',
+    'link',
+    'heading',
+    'cell',
+    'columnheader',
+    'rowheader',
+    'listitem',
+    'option',
+    'tab',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'treeitem',
+    'switch',
+    'checkbox',
+    'radio',
+];
+const NON_EDITABLE_INPUTS = ['checkbox', 'radio', 'button', 'submit', 'reset', 'file', 'image'];
+export function getRole(el) {
+    const explicit = el.getAttribute('role');
+    if (explicit)
+        return explicit.trim().split(/\s+/)[0] || null;
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'a')
+        return el.hasAttribute('href') ? 'link' : null;
+    if (tag === 'img')
+        return el.getAttribute('alt') === '' ? null : 'img';
+    if (tag === 'input') {
+        const type = (el.getAttribute('type') || 'text').toLowerCase();
+        return INPUT_ROLES[type] ?? null;
+    }
+    return TAG_ROLES[tag] ?? null;
+}
+/** Elements whose value is typed rather than toggled — the `fill` targets. */
+export function isEditable(el) {
+    if (!el || el.nodeType !== 1)
+        return false;
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'textarea')
+        return true;
+    if (el.isContentEditable)
+        return true;
+    if (tag !== 'input')
+        return false;
+    const type = (el.getAttribute('type') || 'text').toLowerCase();
+    return !NON_EDITABLE_INPUTS.includes(type);
+}
+/**
+ * A pragmatic subset of the accname algorithm — enough to make role+name
+ * selectors useful, without shipping the full 600-line spec. Order follows
+ * accname's precedence for the sources we do implement.
+ */
+export function accessibleName(el) {
+    const aria = el.getAttribute('aria-label');
+    if (aria && aria.trim())
+        return clean(aria);
+    const labelledby = el.getAttribute('aria-labelledby');
+    if (labelledby) {
+        const parts = labelledby
+            .split(/\s+/)
+            .map((id) => document.getElementById(id))
+            .filter((n) => !!n)
+            .map((n) => clean(n.textContent));
+        const joined = clean(parts.filter(Boolean).join(' '));
+        if (joined)
+            return joined;
+    }
+    const tag = el.tagName.toLowerCase();
+    if (['input', 'select', 'textarea'].includes(tag)) {
+        const id = el.getAttribute('id');
+        if (id) {
+            const forLabel = document.querySelector(`label[for="${escAttr(id)}"]`);
+            if (forLabel) {
+                const t = clean(forLabel.textContent);
+                if (t)
+                    return t;
+            }
+        }
+        const wrapping = el.closest('label');
+        if (wrapping) {
+            const t = clean(wrapping.textContent);
+            if (t)
+                return t;
+        }
+    }
+    for (const attr of ['alt', 'title', 'placeholder']) {
+        const v = el.getAttribute(attr);
+        if (v && v.trim())
+            return clean(v);
+    }
+    const role = getRole(el);
+    if (role && NAME_FROM_CONTENT.includes(role)) {
+        const t = clean(el.textContent);
+        if (t)
+            return t;
+    }
+    return '';
+}
+/** Text of the element itself, used for the `text=` selector candidate. */
+export function ownText(el) {
+    return clean(el.textContent, 60);
+}
+//# sourceMappingURL=roles.js.map

package/dist/recorder/agent/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../../../src/recorder/agent/roles.ts"],"names":[],"mappings":"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"}

package/dist/recorder/agent/selectors.d.ts

@@ -0,0 +1,26 @@
+import type { CapturedTarget } from '../types.js';
+export declare function testIdSelector(el: Element): string | null;
+export declare function idSelector(el: Element): string | null;
+export declare function roleNameSelector(el: Element): string | null;
+/**
+ * Selectors durable enough to wait on. `appeared` tolerates role+name because
+ * waiting for *a* matching element is the right semantic; `gone` does not,
+ * because a wait for count===0 would never settle while siblings remain.
+ */
+export declare function appearedSelector(el: Element): string | null;
+export declare function goneSelector(el: Element): string | null;
+export declare function buildCssPath(el: Element): string | null;
+/**
+ * Candidates in priority order:
+ *   test id / stable id → name attribute → role + accessible name
+ *   → stable CSS path → text anchor
+ */
+export declare function buildCandidates(el: Element): string[];
+/**
+ * Plain-language description of an element, from role + accessible name +
+ * nearest row/section label. Rule-based, no LLM. Surfaces in failure messages
+ * and is the re-grounding prompt for Phase 1 self-heal.
+ */
+export declare function semanticOf(el: Element): string;
+/** Null when the element has no addressable selector at all. */
+export declare function describe(el: Element): CapturedTarget | null;

package/dist/recorder/agent/selectors.js

@@ -0,0 +1,256 @@
+import { accessibleName, getRole, ownText } from './roles.js';
+import { clean, escAttr, escId, isStableClass, isStableToken, renderedText } from './text.js';
+/**
+ * Selector-candidate generation.
+ *
+ * Everything here runs while the element is still live and attached, which is
+ * the only moment these can be computed reliably — and the only way `domGone`
+ * can name a node that is already detached by the time we report it.
+ */
+/**
+ * Attributes an app deliberately puts on an element to identify it. Ordered by
+ * how conventional they are.
+ *
+ * `data-sentry-label` is here because real apps label elements for telemetry
+ * far more consistently than they add test ids — Expensify labels nearly every
+ * interactive element that way, and those labels are as stable as a test id.
+ */
+const TEST_ID_ATTRS = [
+    'data-testid',
+    'data-test',
+    'data-test-id',
+    'data-cy',
+    'data-sentry-label',
+    'data-testid-label',
+];
+const MAX_CANDIDATES = 5;
+const MAX_CSS_PATH_DEPTH = 6;
+export function testIdSelector(el) {
+    for (const attr of TEST_ID_ATTRS) {
+        const v = el.getAttribute(attr);
+        if (v)
+            return `[${attr}="${escAttr(v)}"]`;
+    }
+    return null;
+}
+export function idSelector(el) {
+    const id = el.getAttribute('id');
+    return id && isStableToken(id) ? `#${escId(id)}` : null;
+}
+export function roleNameSelector(el) {
+    const role = getRole(el);
+    if (!role)
+        return null;
+    const name = accessibleName(el);
+    if (!name)
+        return null;
+    return `role=${role}[name="${escAttr(name)}"]`;
+}
+/**
+ * Selectors durable enough to wait on. `appeared` tolerates role+name because
+ * waiting for *a* matching element is the right semantic; `gone` does not,
+ * because a wait for count===0 would never settle while siblings remain.
+ */
+export function appearedSelector(el) {
+    return testIdSelector(el) ?? idSelector(el) ?? roleNameSelector(el);
+}
+export function goneSelector(el) {
+    return testIdSelector(el) ?? idSelector(el);
+}
+function allElements() {
+    return Array.from(document.querySelectorAll('*'));
+}
+/** Append `>> nth=N` only when the base selector is genuinely ambiguous. */
+function withNth(base, el, matches) {
+    if (matches.length <= 1)
+        return base;
+    const idx = matches.indexOf(el);
+    return idx < 0 ? base : `${base} >> nth=${idx}`;
+}
+export function buildCssPath(el) {
+    const segs = [];
+    let cur = el;
+    let depth = 0;
+    while (cur && cur.nodeType === 1 && cur !== document.documentElement && depth < MAX_CSS_PATH_DEPTH) {
+        const node = cur;
+        // Anchoring on a testid/id ancestor beats a long fragile tag chain.
+        if (depth > 0) {
+            const anchor = testIdSelector(node) ?? idSelector(node);
+            if (anchor) {
+                segs.unshift(anchor);
+                break;
+            }
+        }
+        let seg = node.tagName.toLowerCase();
+        const classes = Array.from(node.classList).filter(isStableClass).slice(0, 2);
+        if (classes.length)
+            seg += `.${classes.map(escId).join('.')}`;
+        const parent = node.parentElement;
+        if (parent) {
+            const sameTag = Array.from(parent.children).filter((c) => c.tagName === node.tagName);
+            if (sameTag.length > 1)
+                seg += `:nth-of-type(${sameTag.indexOf(node) + 1})`;
+        }
+        segs.unshift(seg);
+        const partial = segs.join(' > ');
+        try {
+            if (document.querySelectorAll(partial).length === 1)
+                return partial;
+        }
+        catch {
+            return null;
+        }
+        cur = parent;
+        depth++;
+    }
+    if (!segs.length)
+        return null;
+    const sel = segs.join(' > ');
+    try {
+        return document.querySelectorAll(sel).length ? sel : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Candidates in priority order:
+ *   test id / stable id → name attribute → role + accessible name
+ *   → stable CSS path → text anchor
+ */
+export function buildCandidates(el) {
+    const out = [];
+    const push = (s) => {
+        if (s && out.indexOf(s) === -1)
+            out.push(s);
+    };
+    push(testIdSelector(el));
+    push(idSelector(el));
+    const nameAttr = el.getAttribute('name');
+    if (nameAttr && isStableToken(nameAttr)) {
+        push(`${el.tagName.toLowerCase()}[name="${escAttr(nameAttr)}"]`);
+    }
+    const roleName = roleNameSelector(el);
+    if (roleName) {
+        const role = getRole(el);
+        const name = accessibleName(el);
+        const matches = allElements().filter((c) => getRole(c) === role && accessibleName(c) === name);
+        push(withNth(roleName, el, matches));
+    }
+    // Ranked above the CSS path on purpose: when a click lands on an inner node
+    // of a labelled control, `[data-testid="x"]` is strictly more durable than
+    // `[data-testid="x"] > span` or a chain of :nth-of-type positions.
+    push(labelledAncestorSelector(el));
+    const cssPath = buildCssPath(el);
+    const text = ownText(el);
+    const textSelector = text && isSmallestWithText(el, text)
+        ? withNth(`text="${escAttr(text)}"`, el, allElements().filter((c) => isSmallestWithText(c, text)))
+        : null;
+    // A path that is unique only by sibling position breaks the moment anything
+    // is inserted, reordered or conditionally rendered above it — which on a list
+    // or a nav is routine. Visible text is not durable either, but it survives a
+    // reshuffle, so it goes first when the path has nothing but position to
+    // offer. A path anchored on an attribute or a stable class still wins.
+    if (isPositionalOnly(cssPath)) {
+        push(textSelector);
+        push(cssPath);
+    }
+    else {
+        push(cssPath);
+        push(textSelector);
+    }
+    return out.slice(0, MAX_CANDIDATES);
+}
+/** True when the selector's uniqueness rests entirely on :nth-of-type. */
+function isPositionalOnly(selector) {
+    if (!selector)
+        return false;
+    if (!selector.includes(':nth-of-type('))
+        return false;
+    // An attribute anchor or a surviving class name carries real identity.
+    return !selector.includes('[') && !selector.includes('.');
+}
+/**
+ * The nearest identifiable ancestor, offered as a late fallback.
+ *
+ * When a click lands on an inner node of a labelled control, the CSS path
+ * descends from the label into style hashes and there is nothing else to fall
+ * back to. The labelled ancestor is usually clickable and always more durable,
+ * so it is worth having behind the more precise candidates.
+ *
+ * Only offered when the element has no identity of its own, and only for
+ * ancestors close enough to be the same control.
+ */
+function labelledAncestorSelector(el) {
+    if (testIdSelector(el) ?? idSelector(el))
+        return null;
+    let cur = el.parentElement;
+    for (let depth = 0; cur && depth < 3; depth++) {
+        const anchor = testIdSelector(cur);
+        if (anchor) {
+            try {
+                // Ambiguous ancestors are worse than no fallback at all.
+                return document.querySelectorAll(anchor).length === 1 ? anchor : null;
+            }
+            catch {
+                return null;
+            }
+        }
+        cur = cur.parentElement;
+    }
+    return null;
+}
+/**
+ * Playwright's `text=` engine matches the *smallest* element containing the
+ * text, so an ancestor whose only content is that text does not match.
+ *
+ * Counting ancestors here would shift every index: a lone `<ul><li><button>Go`
+ * would record `text="Go" >> nth=2` when replay sees exactly one match, and the
+ * selector would resolve to nothing.
+ */
+function isSmallestWithText(el, text) {
+    if (ownText(el) !== text)
+        return false;
+    return !Array.from(el.children).some((child) => ownText(child) === text);
+}
+function contextLabel(el) {
+    const row = el.closest('tr, [role="row"], li, [role="listitem"], [data-testid*="row"]');
+    if (row && row !== el) {
+        // Strip the element's own label so the context names its surroundings,
+        // not the thing we already named: "the row containing Sensor 2", not
+        // "the row containing Sensor 2 Delete".
+        const own = renderedText(el, 60);
+        const full = renderedText(row, 120);
+        const t = clean(own ? full.split(own).join(' ') : full, 60);
+        if (t)
+            return ` in the row containing "${t}"`;
+    }
+    const section = el.closest('form, section, dialog, [role="dialog"], nav, main, aside');
+    if (section && section !== el) {
+        const label = section.getAttribute('aria-label') ||
+            clean(section.querySelector('h1, h2, h3, h4, legend')?.textContent) ||
+            '';
+        if (label)
+            return ` in the ${section.tagName.toLowerCase()} labelled "${clean(label, 40)}"`;
+    }
+    return '';
+}
+/**
+ * Plain-language description of an element, from role + accessible name +
+ * nearest row/section label. Rule-based, no LLM. Surfaces in failure messages
+ * and is the re-grounding prompt for Phase 1 self-heal.
+ */
+export function semanticOf(el) {
+    const role = getRole(el) || el.tagName.toLowerCase();
+    const name = accessibleName(el) || ownText(el);
+    const head = name ? `${name} ${role}` : role;
+    return head + contextLabel(el);
+}
+/** Null when the element has no addressable selector at all. */
+export function describe(el) {
+    const candidates = buildCandidates(el);
+    if (!candidates.length)
+        return null;
+    return { candidates, semantic: semanticOf(el) };
+}
+//# sourceMappingURL=selectors.js.map

package/dist/recorder/agent/selectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.js","sourceRoot":"","sources":["../../../src/recorder/agent/selectors.ts"],"names":[],"mappings":"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"}

package/dist/recorder/agent/text.d.ts

@@ -0,0 +1,19 @@
+/** String and token helpers shared across the in-page agent. */
+/** Collapse whitespace, trim, and cap length with an ellipsis. */
+export declare function clean(s: string | null | undefined, max?: number): string;
+/** Escape a value for use inside a double-quoted selector attribute. */
+export declare function escAttr(v: string): string;
+/** Escape an identifier for use in a CSS selector. */
+export declare function escId(v: string): string;
+/**
+ * Reject build-generated tokens. The goal is stability across rebuilds, so
+ * anything carrying a content hash or a CSS-in-JS prefix is out.
+ */
+export declare function isStableToken(t: string): boolean;
+export declare function isStableClass(c: string): boolean;
+/**
+ * Text as rendered. `textContent` concatenates across element boundaries —
+ * a row reads "Sensor 2Delete" — whereas `innerText` respects layout and
+ * separates them.
+ */
+export declare function renderedText(el: Element, max?: number): string;

package/dist/recorder/agent/text.js

@@ -0,0 +1,82 @@
+/** String and token helpers shared across the in-page agent. */
+/** Collapse whitespace, trim, and cap length with an ellipsis. */
+export function clean(s, max = 80) {
+    if (!s)
+        return '';
+    const t = s.replace(/\s+/g, ' ').trim();
+    return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+/** Escape a value for use inside a double-quoted selector attribute. */
+export function escAttr(v) {
+    return v.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/** Escape an identifier for use in a CSS selector. */
+export function escId(v) {
+    return typeof window.CSS?.escape === 'function'
+        ? window.CSS.escape(v)
+        : v.replace(/([^\w-])/g, '\\$1');
+}
+/**
+ * Reject build-generated tokens. The goal is stability across rebuilds, so
+ * anything carrying a content hash or a CSS-in-JS prefix is out.
+ */
+export function isStableToken(t) {
+    if (!t || t.length > 40)
+        return false;
+    if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(t))
+        return false;
+    if (/^(css|sc|emotion|styled|jsx|glamor|makeStyles)-/i.test(t))
+        return false;
+    if (/[0-9a-f]{6,}/i.test(t))
+        return false; // embedded hash
+    if ((t.match(/\d/g) || []).length >= 3)
+        return false; // numeric noise
+    if (/[A-Z]/.test(t) && /\d/.test(t))
+        return false; // e.g. Button_root__2Xy4z
+    // Atomic-CSS hashes: a 1-2 char namespace then an opaque blob. React Native
+    // Web emits these (r-1awozwy, r-1mdbw0j) and they change whenever styling
+    // does, so a CSS path built from them breaks on the next restyle.
+    if (/^[a-z]{1,2}-[a-z0-9]{5,}$/i.test(t) && /\d/.test(t))
+        return false;
+    // Per-session ids from a11y announcers and portal libraries (#zb5bjyh-aria).
+    // They are regenerated on every page load, so they can never match on a
+    // later run — a wait on one is guaranteed to time out.
+    if (t.split(/[-_]/).some(looksGenerated))
+        return false;
+    // Live-region announcers (react-aria and friends) mint ids per page load and
+    // suffix them by role: `fvbiask-aria`, `rouspeg-diff`. The prefix is random
+    // but not always vowel-starved, so the suffix is the reliable tell.
+    if (/-(aria|diff|live|announcer|portal)$/i.test(t))
+        return false;
+    return true;
+}
+/**
+ * A token that reads like a nanoid rather than a word: long enough to be
+ * opaque and starved of vowels.
+ *
+ * Two shapes. With a digit, one vowel is already suspicious (`zb5bjyh`).
+ * Without one, it takes a total absence of vowels — which is what catches
+ * React Native Web's digit-free atomic hashes (`dnmrzs` in `div.r-dnmrzs`).
+ * `y` counts as a vowel so ordinary words like `rhythm` survive.
+ */
+function looksGenerated(segment) {
+    if (segment.length < 6)
+        return false;
+    if (!/^[a-z0-9]+$/i.test(segment))
+        return false;
+    const vowels = (segment.match(/[aeiouy]/gi) || []).length;
+    return /\d/.test(segment) ? vowels <= 1 : vowels === 0;
+}
+export function isStableClass(c) {
+    return isStableToken(c) && !/^_/.test(c);
+}
+/**
+ * Text as rendered. `textContent` concatenates across element boundaries —
+ * a row reads "Sensor 2Delete" — whereas `innerText` respects layout and
+ * separates them.
+ */
+export function renderedText(el, max = 80) {
+    const inner = el.innerText;
+    return clean(typeof inner === 'string' ? inner : el.textContent, max);
+}
+//# sourceMappingURL=text.js.map

package/dist/recorder/agent/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../../src/recorder/agent/text.ts"],"names":[],"mappings":"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"}

package/dist/recorder/agent/transport.d.ts

@@ -0,0 +1,14 @@
+import type { PageEvent } from '../types.js';
+import type { AgentConfig } from './config.js';
+export interface Transport {
+    emit(ev: PageEvent): void;
+    /** Look up a Playwright-exposed binding, or null if it is not installed yet. */
+    binding(name: string): ((arg: unknown) => unknown) | null;
+}
+/**
+ * Carries events from the page to Node over a Playwright exposed binding.
+ *
+ * Bindings are not guaranteed to exist when the first events fire, so events
+ * queue until one appears rather than being dropped on the floor.
+ */
+export declare function createTransport(config: AgentConfig): Transport;