@reticlehq/browser 2.0.0

package/dist/commands/commands.js

@@ -0,0 +1,246 @@
+import { ActionType, ComponentStateReason, DANGEROUS_ACTION_CONFIRM_ARG, ElementQuerySchema, ReticleCommand, SnapshotMode, TRANSPORT_LIMITS, selectPath, capDepth, } from '@reticlehq/core';
+import { buildSnapshot } from '../dom/snapshot.js';
+import { matchQuery, runQuery } from '../dom/query.js';
+import { executeAction, executeSequence, dispatchWebMcp, } from '../actions/actions.js';
+import { describe } from '../dom/a11y.js';
+import { themeReport } from '../dom/theme.js';
+import { refs } from '../dom/refs.js';
+import { identifyComponent, readComponentState } from '../registry/adapters.js';
+import { readStores, storeNames } from '../registry/stores.js';
+import { getCapabilities } from '../registry/capabilities.js';
+import { freezeClock, advanceClock, resetClock, isClockFrozen } from '../timers/clock.js';
+import { scrollContainer } from '../actions/scroll.js';
+/** Query param appended on a hard reload to bypass the browser cache. */
+const RELOAD_CACHE_BUST_PARAM = '_reticle_reload';
+function str(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function num(value) {
+    return typeof value === 'number' ? value : undefined;
+}
+function record(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+function queryFromArgs(args) {
+    return {
+        by: str(args['by']),
+        value: str(args['value']),
+        role: str(args['role']),
+        name: str(args['name']),
+        text: str(args['text']),
+        label: str(args['label']),
+        placeholder: str(args['placeholder']),
+        testid: str(args['testid']),
+        alt: str(args['alt']),
+        scope: str(args['scope']),
+    };
+}
+function inspect(ref) {
+    const el = refs.resolve(ref);
+    if (el === null)
+        return { error: `ref '${ref}' no longer resolves` };
+    const rect = el.getBoundingClientRect();
+    const component = identifyComponent(el);
+    const view = el.ownerDocument.defaultView;
+    const cs = view !== null ? view.getComputedStyle(el) : null;
+    // Computed style the a11y tree is blind to — `cursor` (does it look interactive?), display/
+    // visibility, and color/opacity — so a UI bug that leaves the element "present but unusable"
+    // (dead cursor, invisible, recolored) is observable in one inspect call.
+    const styles = cs !== null
+        ? {
+            color: cs.color,
+            backgroundColor: cs.backgroundColor,
+            opacity: cs.opacity,
+            cursor: cs.cursor,
+            display: cs.display,
+            visibility: cs.visibility,
+        }
+        : null;
+    return {
+        ...describe(el),
+        tag: el.tagName.toLowerCase(),
+        href: el.getAttribute('href') ?? undefined,
+        formAction: el instanceof HTMLButtonElement || el instanceof HTMLInputElement
+            ? (el.form?.getAttribute('action') ?? undefined)
+            : undefined,
+        formText: el instanceof HTMLButtonElement || el instanceof HTMLInputElement
+            ? (el.form?.textContent ?? undefined)
+            : undefined,
+        box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+        // True when another element sits over this one's center point — the click would hit the overlay,
+        // not this control (a z-index/overlay bug the DOM tree cannot show).
+        occluded: isOccluded(el, rect),
+        styles,
+        // Theme compliance vs the app's design tokens (off-theme colors a DOM tool can't judge).
+        theme: cs !== null ? themeReport(cs) : null,
+        component,
+    };
+}
+/** True if the node (or an ancestor) is part of Reticle's own injected UI (HUD, glow, cursor, flag
+ * button, …). Reticle's overlay must never count as occluding the app — a control sitting under the
+ * HUD is a false "occluded" reading, since the HUD is not part of the app the user actually sees. */
+function isReticleUi(node) {
+    for (let n = node; n !== null; n = n.parentElement) {
+        for (const attr of Array.from(n.attributes)) {
+            if (attr.name.startsWith('data-reticle'))
+                return true;
+        }
+    }
+    return false;
+}
+/** Whether a NON-Reticle element covers this one's center point (a transparent overlay / z-index bug). */
+function isOccluded(el, rect) {
+    if (rect.width === 0 || rect.height === 0)
+        return false; // a 0×0 box is a different bug (size)
+    const doc = el.ownerDocument;
+    if (typeof doc.elementFromPoint !== 'function')
+        return false;
+    const top = doc.elementFromPoint(rect.x + rect.width / 2, rect.y + rect.height / 2);
+    // Reticle's own HUD sits at a high z-index and must never read as occluding the app.
+    if (top === null || isReticleUi(top))
+        return false;
+    return top !== el && !el.contains(top);
+}
+/** Narrowing guard: an adapter returned a ComponentStateResult (has a boolean `ok`). */
+function isComponentStateResult(value) {
+    return (typeof value === 'object' && value !== null && 'ok' in value && typeof value.ok === 'boolean');
+}
+const COMPONENT_UNAVAILABLE = {
+    ok: false,
+    reason: ComponentStateReason.UNAVAILABLE,
+};
+/**
+ * Stores are the reliable path. The `ref` component read is bounded: a stale ref, no
+ * adapter, or an adapter returning a non-conforming value all collapse to a structured
+ * `{ ok: false, reason }` — never a raw (possibly circular) object that could hang serialization.
+ *
+ * `path`/`depth` are applied HERE, in the page, BEFORE the value crosses the transport — so a scoped
+ * read of a huge store (e.g. `deployments.0.status` on a 500-row store) returns only the small
+ * sub-tree and is never truncated. (Previously selection ran server-side, AFTER the whole store had
+ * already been size-capped in transit, which silently lost any field after a large array.)
+ */
+function readState(ref, store, path, depth) {
+    const stores = readStores(store);
+    const names = storeNames();
+    // Scoped read: walk `path` into the named store (or the whole {stores} when no store is given) and
+    // cap depth — entirely in-page, so only the result crosses the wire.
+    if (path !== undefined || depth !== undefined) {
+        const base = store !== undefined ? stores[store] : { stores, storeNames: names };
+        const selection = path !== undefined ? selectPath(base, path) : { found: true, value: base };
+        const value = selection.found && depth !== undefined ? capDepth(selection.value, depth) : selection.value;
+        return {
+            store,
+            path,
+            found: selection.found,
+            value,
+            ...('availableKeys' in selection ? { availableKeys: selection.availableKeys } : {}),
+            storeNames: names,
+        };
+    }
+    const result = {
+        stores,
+        storeNames: names,
+    };
+    if (ref !== undefined && ref.length > 0) {
+        const el = refs.resolve(ref);
+        if (el === null) {
+            result.component = COMPONENT_UNAVAILABLE;
+        }
+        else {
+            const state = readComponentState(el);
+            result.component = isComponentStateResult(state) ? state : COMPONENT_UNAVAILABLE;
+        }
+    }
+    return result;
+}
+function listAnimations() {
+    const doc = document;
+    if (typeof doc.getAnimations !== 'function')
+        return { animations: [] };
+    const animations = doc.getAnimations().map((a) => {
+        const effect = a.effect;
+        const timing = effect?.getTiming();
+        return {
+            playState: a.playState,
+            currentTime: a.currentTime,
+            duration: timing?.duration,
+        };
+    });
+    return { animations };
+}
+export function resolveNavigationUrl(rawUrl, baseUrl) {
+    if (rawUrl.length === 0 || rawUrl.length > TRANSPORT_LIMITS.MAX_URL_LENGTH)
+        return null;
+    try {
+        const url = new URL(rawUrl, baseUrl);
+        return url.protocol === 'http:' || url.protocol === 'https:' ? url.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Map browser command names to handlers. Used by the transport on each COMMAND. */
+export function createCommandRegistry() {
+    const reg = new Map();
+    reg.set(ReticleCommand.SNAPSHOT, (args) => buildSnapshot({
+        scope: str(args['scope']),
+        mode: str(args['mode']) ?? SnapshotMode.FULL,
+    }));
+    reg.set(ReticleCommand.QUERY, (args) => runQuery(queryFromArgs(args)));
+    reg.set(ReticleCommand.MATCH, (args) => matchQuery(ElementQuerySchema.parse(record(args['query'])), str(args['state'])));
+    reg.set(ReticleCommand.ACT, (args) => {
+        const action = str(args['action']) ?? '';
+        if (action === ActionType.WEBMCP) {
+            const inner = record(args['args']);
+            return dispatchWebMcp(str(inner['tool']) ?? '', record(inner['params']), inner[DANGEROUS_ACTION_CONFIRM_ARG] === true);
+        }
+        return executeAction(str(args['ref']) ?? '', action, record(args['args']));
+    });
+    reg.set(ReticleCommand.ACT_SEQUENCE, (args) => executeSequence((Array.isArray(args['steps']) ? args['steps'] : [])));
+    reg.set(ReticleCommand.INSPECT, (args) => inspect(str(args['ref']) ?? ''));
+    reg.set(ReticleCommand.ANIMATIONS, () => listAnimations());
+    reg.set(ReticleCommand.CLOCK, (args) => {
+        if (args['reset'] === true) {
+            resetClock();
+        }
+        else {
+            if (args['freeze'] === true)
+                freezeClock();
+            const adv = args['advanceMs'];
+            if (typeof adv === 'number')
+                advanceClock(adv);
+        }
+        return { frozen: isClockFrozen() };
+    });
+    reg.set(ReticleCommand.STATE_READ, (args) => readState(str(args['ref']), str(args['store']), str(args['path']), num(args['depth'])));
+    reg.set(ReticleCommand.CAPABILITIES, () => getCapabilities());
+    reg.set(ReticleCommand.SCROLL, (args) => {
+        const dy = args['dy'];
+        const fraction = args['fraction'];
+        return scrollContainer(str(args['ref']), typeof dy === 'number' ? dy : undefined, typeof fraction === 'number' ? fraction : undefined);
+    });
+    reg.set(ReticleCommand.NAVIGATE, (args) => {
+        const rawUrl = str(args['url']);
+        if (rawUrl === undefined || rawUrl.length === 0)
+            return { ok: false, reason: 'url required' };
+        const url = resolveNavigationUrl(rawUrl, window.location.href);
+        if (url === null)
+            return { ok: false, reason: 'only http(s) navigation is allowed' };
+        window.location.assign(url);
+        return { ok: true, url };
+    });
+    reg.set(ReticleCommand.REFRESH, (args) => {
+        if (args['hard'] === true) {
+            // Hard reload: navigate to self with a cache-busting param then replace history.
+            const url = new URL(window.location.href);
+            url.searchParams.set(RELOAD_CACHE_BUST_PARAM, String(Date.now()));
+            window.location.replace(url.toString());
+        }
+        else {
+            window.location.reload();
+        }
+        return { ok: true };
+    });
+    return reg;
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/commands/commands.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,4BAA4B,EAC5B,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,QAAQ,GAIT,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EACL,aAAa,EACb,eAAe,EACf,cAAc,GAEf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAIvD,yEAAyE;AACzE,MAAM,uBAAuB,GAAG,iBAAiB,CAAC;AAElD,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,SAAS,GAAG,CAAC,KAAc;IACzB,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAE,KAAiC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/F,CAAC;AAED,SAAS,aAAa,CAAC,IAA6B;IAClD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAuB;QACzC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACrC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3B,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;KAC1B,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,GAAW;IAC1B,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,sBAAsB,EAAE,CAAC;IACrE,MAAM,IAAI,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;IACxC,MAAM,SAAS,GAAG,iBAAiB,CAAC,EAAE,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,EAAE,CAAC,aAAa,CAAC,WAAW,CAAC;IAC1C,MAAM,EAAE,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5D,4FAA4F;IAC5F,6FAA6F;IAC7F,yEAAyE;IACzE,MAAM,MAAM,GACV,EAAE,KAAK,IAAI;QACT,CAAC,CAAC;YACE,KAAK,EAAE,EAAE,CAAC,KAAK;YACf,eAAe,EAAE,EAAE,CAAC,eAAe;YACnC,OAAO,EAAE,EAAE,CAAC,OAAO;YACnB,MAAM,EAAE,EAAE,CAAC,MAAM;YACjB,OAAO,EAAE,EAAE,CAAC,OAAO;YACnB,UAAU,EAAE,EAAE,CAAC,UAAU;SAC1B;QACH,CAAC,CAAC,IAAI,CAAC;IACX,OAAO;QACL,GAAG,QAAQ,CAAC,EAAE,CAAC;QACf,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE;QAC7B,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,SAAS;QAC1C,UAAU,EACR,EAAE,YAAY,iBAAiB,IAAI,EAAE,YAAY,gBAAgB;YAC/D,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC;YAChD,CAAC,CAAC,SAAS;QACf,QAAQ,EACN,EAAE,YAAY,iBAAiB,IAAI,EAAE,YAAY,gBAAgB;YAC/D,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,IAAI,SAAS,CAAC;YACrC,CAAC,CAAC,SAAS;QACf,GAAG,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;QACrE,iGAAiG;QACjG,qEAAqE;QACrE,QAAQ,EAAE,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC;QAC9B,MAAM;QACN,yFAAyF;QACzF,KAAK,EAAE,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI;QAC3C,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;qGAEqG;AACrG,SAAS,WAAW,CAAC,IAAoB;IACvC,KAAK,IAAI,CAAC,GAAmB,IAAI,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,CAAC;QACnE,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC;gBAAE,OAAO,IAAI,CAAC;QACxD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,0GAA0G;AAC1G,SAAS,UAAU,CAAC,EAAW,EAAE,IAAa;IAC5C,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,sCAAsC;IAC/F,MAAM,GAAG,GAAG,EAAE,CAAC,aAAa,CAAC;IAC7B,IAAI,OAAO,GAAG,CAAC,gBAAgB,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC7D,MAAM,GAAG,GAAG,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACpF,qFAAqF;IACrF,IAAI,GAAG,KAAK,IAAI,IAAI,WAAW,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACnD,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,wFAAwF;AACxF,SAAS,sBAAsB,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,EAAE,KAAK,SAAS,CAC9F,CAAC;AACJ,CAAC;AAED,MAAM,qBAAqB,GAAyB;IAClD,EAAE,EAAE,KAAK;IACT,MAAM,EAAE,oBAAoB,CAAC,WAAW;CACzC,CAAC;AAEF;;;;;;;;;GASG;AACH,SAAS,SAAS,CAChB,GAAuB,EACvB,KAAyB,EACzB,IAAwB,EACxB,KAAyB;IAEzB,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;IAE3B,mGAAmG;IACnG,qEAAqE;IACrE,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;QACjF,MAAM,SAAS,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC7F,MAAM,KAAK,GACT,SAAS,CAAC,KAAK,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC;QAC9F,OAAO;YACL,KAAK;YACL,IAAI;YACJ,KAAK,EAAE,SAAS,CAAC,KAAK;YACtB,KAAK;YACL,GAAG,CAAC,eAAe,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,SAAS,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnF,UAAU,EAAE,KAAK;SAClB,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAIR;QACF,MAAM;QACN,UAAU,EAAE,KAAK;KAClB,CAAC;IACF,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,MAAM,CAAC,SAAS,GAAG,qBAAqB,CAAC;QAC3C,CAAC;aAAM,CAAC;YACN,MAAM,KAAK,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAC;YACrC,MAAM,CAAC,SAAS,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,qBAAqB,CAAC;QACnF,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,cAAc;IACrB,MAAM,GAAG,GAAG,QAA4D,CAAC;IACzE,IAAI,OAAO,GAAG,CAAC,aAAa,KAAK,UAAU;QAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IACvE,MAAM,UAAU,GAAG,GAAG,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC/C,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;QACxB,MAAM,MAAM,GAAG,MAAM,EAAE,SAAS,EAAE,CAAC;QACnC,OAAO;YACL,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,QAAQ,EAAE,MAAM,EAAE,QAAQ;SAC3B,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,UAAU,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,OAAe;IAClE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,gBAAgB,CAAC,cAAc;QAAE,OAAO,IAAI,CAAC;IACxF,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACvF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,qBAAqB;IACnC,MAAM,GAAG,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC9C,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CACxC,aAAa,CAAC;QACZ,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,IAAI,EAAG,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAA8B,IAAI,YAAY,CAAC,IAAI;KAC3E,CAAC,CACH,CAAC;IACF,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACvE,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CACrC,UAAU,CACR,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAC/C,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAA6B,CAC/C,CACF,CAAC;IACF,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE;QACnC,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACzC,IAAI,MAAM,KAAK,UAAU,CAAC,MAAM,EAAE,CAAC;YACjC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YACnC,OAAO,cAAc,CACnB,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EACxB,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EACvB,KAAK,CAAC,4BAA4B,CAAC,KAAK,IAAI,CAC7C,CAAC;QACJ,CAAC;QACD,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE,CAC5C,eAAe,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAiB,CAAC,CACrF,CAAC;IACF,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC3E,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,cAAc,EAAE,CAAC,CAAC;IAC3D,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE;QACrC,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;YAC3B,UAAU,EAAE,CAAC;QACf,CAAC;aAAM,CAAC;YACN,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI;gBAAE,WAAW,EAAE,CAAC;YAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;YAC9B,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,YAAY,CAAC,GAAG,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,CAAC;IACrC,CAAC,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CAC1C,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CACvF,CAAC;IACF,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;IAC9D,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACtC,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QAClC,OAAO,eAAe,CACpB,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAChB,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,EACvC,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CACpD,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;QACxC,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QAC9F,MAAM,GAAG,GAAG,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC/D,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,EAAE,CAAC;QACrF,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IAC3B,CAAC,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;QACvC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;YAC1B,iFAAiF;YACjF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC1C,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,uBAAuB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAClE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC3B,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/dom/a11y.d.ts

@@ -0,0 +1,20 @@
+import { ElementState, type ElementDescriptor } from '@reticlehq/core';
+/** Compute the ARIA role (explicit wins, else implicit from the tag). */
+export declare function getRole(el: Element): string;
+/** Accessible name via a practical subset of the accname algorithm. */
+export declare function getAccessibleName(el: Element): string;
+/** The set of states relevant to assertions (plan/06). */
+export declare function getStates(el: Element): ElementState[];
+/**
+ * True when a form field holds a secret the SDK must never capture verbatim — a password input, a
+ * sensitive `autocomplete` (cc-number, one-time-code, …), or a name/id/testid/aria-label that trips
+ * `isSensitiveKey`. The single source of truth for both live-snapshot redaction (`getValue`) and the
+ * flow recorder's fill-value redaction, so recorded flows never persist typed passwords/OTPs/keys.
+ */
+export declare function isSensitiveField(el: Element): boolean;
+export declare function getValue(el: Element): string | undefined;
+/** Whether the element is actually visible (not display:none/hidden/aria-hidden/opacity:0). */
+export declare function isVisible(el: Element): boolean;
+/** Build the compact descriptor surfaced to the agent. */
+export declare function describe(el: Element): ElementDescriptor;
+//# sourceMappingURL=a11y.d.ts.map

package/dist/dom/a11y.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.d.ts","sourceRoot":"","sources":["../../src/dom/a11y.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAkB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAsCvF,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAkD3C;AAkBD,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAwCrD;AAQD,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,YAAY,EAAE,CAqBrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAsBrD;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAWxD;AAED,+FAA+F;AAC/F,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAqB9C;AASD,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,iBAAiB,CAcvD"}

package/dist/dom/a11y.js

@@ -0,0 +1,263 @@
+import { ElementState, REDACTED_VALUE } from '@reticlehq/core';
+import { refs } from './refs.js';
+import { isSensitiveKey } from '../security/serialization.js';
+/** Roles whose accessible name comes from their text content. */
+const NAME_FROM_CONTENT = new Set([
+    'button',
+    'link',
+    'heading',
+    'option',
+    'listitem',
+    'cell',
+    'columnheader',
+    'rowheader',
+    'tab',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'treeitem',
+    'gridcell',
+    'switch',
+    'status',
+    'alert',
+]);
+const INPUT_TEXT_TYPES = new Set(['text', 'email', 'tel', 'url', 'search', 'password', '']);
+function inputRole(input) {
+    const type = input.type.toLowerCase();
+    if (INPUT_TEXT_TYPES.has(type))
+        return 'textbox';
+    if (type === 'checkbox')
+        return 'checkbox';
+    if (type === 'radio')
+        return 'radio';
+    if (type === 'range')
+        return 'slider';
+    if (type === 'number')
+        return 'spinbutton';
+    if (type === 'submit' || type === 'button' || type === 'reset')
+        return 'button';
+    return 'textbox';
+}
+/** Compute the ARIA role (explicit wins, else implicit from the tag). */
+export function getRole(el) {
+    const explicit = el.getAttribute('role');
+    if (explicit !== null && explicit.trim().length > 0)
+        return explicit.trim();
+    const tag = el.tagName.toLowerCase();
+    switch (tag) {
+        case 'a':
+            return el.hasAttribute('href') ? 'link' : 'generic';
+        case 'button':
+            return 'button';
+        case 'input':
+            return inputRole(el);
+        case 'textarea':
+            return 'textbox';
+        case 'select':
+            return el.multiple ? 'listbox' : 'combobox';
+        case 'h1':
+        case 'h2':
+        case 'h3':
+        case 'h4':
+        case 'h5':
+        case 'h6':
+            return 'heading';
+        case 'ul':
+        case 'ol':
+            return 'list';
+        case 'li':
+            return 'listitem';
+        case 'nav':
+            return 'navigation';
+        case 'main':
+            return 'main';
+        case 'aside':
+            return 'complementary';
+        case 'dialog':
+            return 'dialog';
+        case 'img':
+            return 'img';
+        case 'table':
+            return 'table';
+        case 'form':
+            return 'form';
+        case 'p':
+            return 'paragraph';
+        case 'header':
+            return 'banner';
+        case 'footer':
+            return 'contentinfo';
+        default:
+            return 'generic';
+    }
+}
+function collapse(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function labelledByText(el) {
+    const ids = el.getAttribute('aria-labelledby');
+    if (ids === null)
+        return null;
+    const parts = [];
+    for (const id of ids.split(/\s+/)) {
+        const ref = el.ownerDocument.getElementById(id);
+        if (ref !== null)
+            parts.push(collapse(ref.textContent ?? ''));
+    }
+    const joined = parts.join(' ').trim();
+    return joined.length > 0 ? joined : null;
+}
+/** Accessible name via a practical subset of the accname algorithm. */
+export function getAccessibleName(el) {
+    const labelled = labelledByText(el);
+    if (labelled !== null)
+        return labelled;
+    const ariaLabel = el.getAttribute('aria-label');
+    if (ariaLabel !== null && ariaLabel.trim().length > 0)
+        return ariaLabel.trim();
+    if (el instanceof HTMLImageElement) {
+        const alt = el.getAttribute('alt');
+        if (alt !== null)
+            return alt.trim();
+    }
+    if (el instanceof HTMLInputElement ||
+        el instanceof HTMLTextAreaElement ||
+        el instanceof HTMLSelectElement) {
+        const labels = el.labels;
+        if (labels !== null && labels.length > 0) {
+            const text = [...labels]
+                .map((l) => collapse(l.textContent ?? ''))
+                .join(' ')
+                .trim();
+            if (text.length > 0)
+                return text;
+        }
+        if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+            const placeholder = el.getAttribute('placeholder');
+            if (placeholder !== null && placeholder.trim().length > 0)
+                return placeholder.trim();
+        }
+    }
+    if (NAME_FROM_CONTENT.has(getRole(el))) {
+        const text = collapse(el.textContent ?? '');
+        if (text.length > 0)
+            return text;
+    }
+    const title = el.getAttribute('title');
+    if (title !== null && title.trim().length > 0)
+        return title.trim();
+    return '';
+}
+function ariaBool(el, attr) {
+    const value = el.getAttribute(attr);
+    if (value === null)
+        return undefined;
+    return value === 'true';
+}
+/** The set of states relevant to assertions (plan/06). */
+export function getStates(el) {
+    const states = [ElementState.PRESENT];
+    if (isVisible(el))
+        states.push(ElementState.VISIBLE);
+    else
+        states.push(ElementState.HIDDEN);
+    const disabledProp = (el instanceof HTMLButtonElement ||
+        el instanceof HTMLInputElement ||
+        el instanceof HTMLSelectElement ||
+        el instanceof HTMLTextAreaElement) &&
+        el.disabled;
+    const disabled = disabledProp || ariaBool(el, 'aria-disabled') === true;
+    states.push(disabled ? ElementState.DISABLED : ElementState.ENABLED);
+    const checkedProp = el instanceof HTMLInputElement && (el.type === 'checkbox' || el.type === 'radio') && el.checked;
+    if (checkedProp || ariaBool(el, 'aria-checked') === true)
+        states.push(ElementState.CHECKED);
+    if (ariaBool(el, 'aria-expanded') === true)
+        states.push(ElementState.EXPANDED);
+    if (el.ownerDocument.activeElement === el)
+        states.push(ElementState.FOCUSED);
+    return states;
+}
+/**
+ * True when a form field holds a secret the SDK must never capture verbatim — a password input, a
+ * sensitive `autocomplete` (cc-number, one-time-code, …), or a name/id/testid/aria-label that trips
+ * `isSensitiveKey`. The single source of truth for both live-snapshot redaction (`getValue`) and the
+ * flow recorder's fill-value redaction, so recorded flows never persist typed passwords/OTPs/keys.
+ */
+export function isSensitiveField(el) {
+    if (!(el instanceof HTMLInputElement) &&
+        !(el instanceof HTMLTextAreaElement) &&
+        !(el instanceof HTMLSelectElement)) {
+        return false;
+    }
+    const autocomplete = el.getAttribute('autocomplete') ?? '';
+    const identifiers = [
+        el.getAttribute('name') ?? '',
+        el.id,
+        el.getAttribute('data-testid') ?? '',
+        el.getAttribute('aria-label') ?? '',
+    ];
+    const sensitiveAutocomplete = /current-password|new-password|cc-number|cc-csc|one-time-code/i.test(autocomplete);
+    return ((el instanceof HTMLInputElement && el.type.toLowerCase() === 'password') ||
+        sensitiveAutocomplete ||
+        identifiers.some(isSensitiveKey));
+}
+export function getValue(el) {
+    if (el instanceof HTMLInputElement ||
+        el instanceof HTMLTextAreaElement ||
+        el instanceof HTMLSelectElement) {
+        if (isSensitiveField(el))
+            return REDACTED_VALUE;
+        return el.value;
+    }
+    const valueNow = el.getAttribute('aria-valuenow');
+    return valueNow ?? undefined;
+}
+/** Whether the element is actually visible (not display:none/hidden/aria-hidden/opacity:0). */
+export function isVisible(el) {
+    if (!el.isConnected)
+        return false;
+    let node = el;
+    while (node !== null) {
+        if (node.getAttribute('aria-hidden') === 'true')
+            return false;
+        if (node instanceof HTMLElement && node.hidden)
+            return false;
+        const view = node.ownerDocument.defaultView;
+        if (view !== null) {
+            const style = view.getComputedStyle(node);
+            if (style.display === 'none' ||
+                style.visibility === 'hidden' ||
+                style.visibility === 'collapse') {
+                return false;
+            }
+            if (Number.parseFloat(style.opacity || '1') === 0)
+                return false;
+        }
+        node = node.parentElement;
+    }
+    return true;
+}
+const MAX_TEXT = 80;
+function getVisibleText(el) {
+    const text = collapse(el.textContent ?? '');
+    return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}…` : text;
+}
+/** Build the compact descriptor surfaced to the agent. */
+export function describe(el) {
+    const value = getValue(el);
+    const text = getVisibleText(el);
+    const name = getAccessibleName(el);
+    const base = {
+        ref: refs.refFor(el),
+        role: getRole(el),
+        name,
+        states: getStates(el),
+        visible: isVisible(el),
+    };
+    if (value !== undefined && value.length > 0)
+        base.value = value;
+    if (text.length > 0 && text !== name)
+        base.text = text;
+    return base;
+}
+//# sourceMappingURL=a11y.js.map

package/dist/dom/a11y.js.map

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

package/dist/dom/auto-anchor.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Auto-anchor synthesis — derive a STABLE way to address any element WITHOUT a hand-added
+ * data-testid. This is the brain of zero-config integration: given what the framework already knows
+ * about an element (its component name + source location from the fiber, its role + accessible name,
+ * its position), pick the most durable anchor so a flow can re-find the element across refactors.
+ *
+ * Pure and framework-agnostic: it takes a plain descriptor (the React adapter, or a future Vue/Svelte
+ * adapter, fills it in) and returns the chosen anchor + whether it is stable. No DOM, no fiber here.
+ *
+ * Priority (most → least durable). Each tier is only used when the one above is unavailable:
+ *   1. testid           — explicit, author-chosen, the gold standard. Stable.
+ *   2. component@source  — component display name + source file:line. Survives text/markup/style
+ *                          changes; uniquely identifies WHERE in the source the element comes from.
+ *                          Stable (a move that changes the source line is a real change worth re-pinning).
+ *   3. component+role/name — component name plus role/accessible-name when no source is available.
+ *                          Stable enough: the component identity anchors it, role/name disambiguate.
+ *   4. role+name         — semantic but content-dependent: an accessible name can change with copy.
+ *                          NOT marked stable (a healed locator could drift to a renamed element).
+ *   5. role / position   — last resort. NOT stable; surfaced so the element is still addressable, but
+ *                          a flow built on it should be flagged (the recorder marks the step degraded).
+ *
+ * The point: tiers 1–3 are "stable" (a flow anchored on them can be trusted to re-resolve to the
+ * same element); tiers 4–5 are best-effort. Today most elements without a testid fall to role/text
+ * (degraded). With component+source, the SAME elements become tier-2 stable anchors — that is how
+ * integration becomes universal without the app author adding a single testid.
+ */
+/** Which signal produced the anchor — also its durability tier. */
+export declare const AnchorStrategy: {
+    readonly TESTID: "testid";
+    readonly COMPONENT: "component";
+    readonly ROLE: "role";
+    readonly POSITION: "position";
+};
+export type AnchorStrategy = (typeof AnchorStrategy)[keyof typeof AnchorStrategy];
+/** What an adapter knows about an element — any subset; richer input yields a more durable anchor. */
+export interface AnchorInput {
+    /** Explicit data-testid, if the author added one. */
+    testid?: string;
+    /** Nearest component display name (React fiber / Vue instance / …). */
+    component?: string;
+    /** Source location stamped by the framework's compiler/plugin. */
+    source?: {
+        file: string;
+        line: number;
+    };
+    /** ARIA role. */
+    role?: string;
+    /** Accessible name (label / text). */
+    name?: string;
+    /** Index among same-component-or-role siblings — a positional tiebreaker. */
+    nth?: number;
+}
+interface SynthesizedAnchor {
+    strategy: AnchorStrategy;
+    /** A compact, human-legible, re-resolvable anchor string. */
+    value: string;
+    /** True when a flow can trust this anchor to re-resolve to the same element (tiers 1–3). */
+    stable: boolean;
+}
+/**
+ * Choose the most durable anchor for an element from whatever the adapter could observe. Always
+ * returns something addressable (falls through to position), with `stable` marking tiers 1–3.
+ */
+export declare function synthesizeAnchor(input: AnchorInput): SynthesizedAnchor;
+export {};
+//# sourceMappingURL=auto-anchor.d.ts.map

package/dist/dom/auto-anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-anchor.d.ts","sourceRoot":"","sources":["../../src/dom/auto-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,mEAAmE;AACnE,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAElF,sGAAsG;AACtG,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,iBAAiB;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,UAAU,iBAAiB;IACzB,QAAQ,EAAE,cAAc,CAAC;IACzB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,MAAM,EAAE,OAAO,CAAC;CACjB;AAYD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,iBAAiB,CA4BtE"}