@reticlehq/browser 2.0.0

package/dist/dom/auto-anchor.js

@@ -0,0 +1,75 @@
+/**
+ * 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 const AnchorStrategy = {
+    TESTID: 'testid',
+    COMPONENT: 'component',
+    ROLE: 'role',
+    POSITION: 'position',
+};
+function nonEmpty(s) {
+    return typeof s === 'string' && s.length > 0;
+}
+/** Source as a compact `file:line` suffix; basename only to stay terse and path-independent. */
+function sourceTag(source) {
+    const base = source.file.split('/').pop() ?? source.file;
+    return `${base}:${source.line}`;
+}
+/**
+ * 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 function synthesizeAnchor(input) {
+    if (nonEmpty(input.testid)) {
+        return { strategy: AnchorStrategy.TESTID, value: input.testid, stable: true };
+    }
+    if (nonEmpty(input.component) && input.source !== undefined) {
+        return {
+            strategy: AnchorStrategy.COMPONENT,
+            value: `${input.component}@${sourceTag(input.source)}`,
+            stable: true,
+        };
+    }
+    if (nonEmpty(input.component) && (nonEmpty(input.role) || nonEmpty(input.name))) {
+        const qualifier = nonEmpty(input.name) ? input.name : input.role;
+        return {
+            strategy: AnchorStrategy.COMPONENT,
+            value: `${input.component}[${qualifier ?? ''}]`,
+            stable: true,
+        };
+    }
+    if (nonEmpty(input.role) && nonEmpty(input.name)) {
+        return { strategy: AnchorStrategy.ROLE, value: `${input.role}:${input.name}`, stable: false };
+    }
+    if (nonEmpty(input.role)) {
+        const suffix = input.nth !== undefined ? `#${input.nth}` : '';
+        return { strategy: AnchorStrategy.ROLE, value: `${input.role}${suffix}`, stable: false };
+    }
+    // Last resort: position only — addressable but never trusted.
+    return { strategy: AnchorStrategy.POSITION, value: `el#${input.nth ?? 0}`, stable: false };
+}
+//# sourceMappingURL=auto-anchor.js.map

package/dist/dom/auto-anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-anchor.js","sourceRoot":"","sources":["../../src/dom/auto-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;CACZ,CAAC;AA2BX,SAAS,QAAQ,CAAC,CAAqB;IACrC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED,gGAAgG;AAChG,SAAS,SAAS,CAAC,MAAsC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC;IACzD,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,QAAQ,EAAE,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAChF,CAAC;IACD,IAAI,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC5D,OAAO;YACL,QAAQ,EAAE,cAAc,CAAC,SAAS;YAClC,KAAK,EAAE,GAAG,KAAK,CAAC,SAAS,IAAI,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE;YACtD,MAAM,EAAE,IAAI;SACb,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAChF,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;QACjE,OAAO;YACL,QAAQ,EAAE,cAAc,CAAC,SAAS;YAClC,KAAK,EAAE,GAAG,KAAK,CAAC,SAAS,IAAI,SAAS,IAAI,EAAE,GAAG;YAC/C,MAAM,EAAE,IAAI;SACb,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,OAAO,EAAE,QAAQ,EAAE,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAChG,CAAC;IACD,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,OAAO,EAAE,QAAQ,EAAE,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,IAAI,GAAG,MAAM,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC3F,CAAC;IACD,8DAA8D;IAC9D,OAAO,EAAE,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC7F,CAAC"}

package/dist/dom/dom-ignore.d.ts

@@ -0,0 +1,7 @@
+/** Let the host app add selectors to exclude from snapshots (e.g. its own dev widgets). */
+export declare function setIgnoreSelectors(selectors: string[]): void;
+/** True if the element is part of Reticle's own presenter overlay. */
+export declare function isReticleOverlay(el: Element): boolean;
+/** True if the element should be excluded from snapshots/queries (Reticle overlay or dev overlay). */
+export declare function isIgnored(el: Element): boolean;
+//# sourceMappingURL=dom-ignore.d.ts.map

package/dist/dom/dom-ignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-ignore.d.ts","sourceRoot":"","sources":["../../src/dom/dom-ignore.ts"],"names":[],"mappings":"AAUA,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAE5D;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAErD;AAED,sGAAsG;AACtG,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAM9C"}

package/dist/dom/dom-ignore.js

@@ -0,0 +1,21 @@
+/** Selectors for Reticle's own presenter overlay (cursor, HUD, glow) — never observed/snapshotted. */
+const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow]';
+/** Known third-party dev overlays to keep out of snapshots (Agentation, Next dev UI). */
+const DEV_OVERLAYS = '[data-agentation],#__next-build-watcher,nextjs-portal,[data-nextjs-dialog],[data-nextjs-toast]';
+let extraIgnore = '';
+/** Let the host app add selectors to exclude from snapshots (e.g. its own dev widgets). */
+export function setIgnoreSelectors(selectors) {
+    extraIgnore = selectors.join(',');
+}
+/** True if the element is part of Reticle's own presenter overlay. */
+export function isReticleOverlay(el) {
+    return el.closest(RETICLE_OVERLAY) !== null;
+}
+/** True if the element should be excluded from snapshots/queries (Reticle overlay or dev overlay). */
+export function isIgnored(el) {
+    const sel = extraIgnore.length > 0
+        ? `${RETICLE_OVERLAY},${DEV_OVERLAYS},${extraIgnore}`
+        : `${RETICLE_OVERLAY},${DEV_OVERLAYS}`;
+    return el.closest(sel) !== null;
+}
+//# sourceMappingURL=dom-ignore.js.map

package/dist/dom/dom-ignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-ignore.js","sourceRoot":"","sources":["../../src/dom/dom-ignore.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,MAAM,eAAe,GACnB,qFAAqF,CAAC;AAExF,yFAAyF;AACzF,MAAM,YAAY,GAChB,gGAAgG,CAAC;AAEnG,IAAI,WAAW,GAAG,EAAE,CAAC;AAErB,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CAAC,SAAmB;IACpD,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,EAAW;IAC1C,OAAO,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC,KAAK,IAAI,CAAC;AAC9C,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,SAAS,CAAC,EAAW;IACnC,MAAM,GAAG,GACP,WAAW,CAAC,MAAM,GAAG,CAAC;QACpB,CAAC,CAAC,GAAG,eAAe,IAAI,YAAY,IAAI,WAAW,EAAE;QACrD,CAAC,CAAC,GAAG,eAAe,IAAI,YAAY,EAAE,CAAC;IAC3C,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;AAClC,CAAC"}

package/dist/dom/query.d.ts

@@ -0,0 +1,6 @@
+import { ElementState, type ElementQuery, type MatchResult, type QueryResult } from '@reticlehq/core';
+/** Match an element predicate against the live DOM (plan/06). */
+export declare function matchQuery(query: ElementQuery, state?: ElementState): MatchResult;
+/** Resolve a query to descriptors for the `query` MCP tool. */
+export declare function runQuery(query: ElementQuery): QueryResult;
+//# sourceMappingURL=query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/dom/query.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,YAAY,EAGZ,KAAK,YAAY,EACjB,KAAK,WAAW,EAGhB,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AA8IzB,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,WAAW,CAUjF;AAmFD,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAMzD"}

package/dist/dom/query.js

@@ -0,0 +1,236 @@
+import { queryAllByRole, queryAllByText, queryAllByLabelText, queryAllByPlaceholderText, queryAllByTestId, queryAllByAltText, } from '@testing-library/dom';
+import { ElementState, QueryBy, } from '@reticlehq/core';
+import { describe, getStates } from './a11y.js';
+import { getCapabilities } from '../registry/capabilities.js';
+import { identifyComponent } from '../registry/adapters.js';
+import { refs } from './refs.js';
+const TESTID_ATTR = 'data-testid';
+const SOURCE_ATTR = 'data-reticle-source';
+const MAX_PRESENT_TESTIDS = 12;
+/** Bound the fiber-walk fallback so a component-name query can't scan an unbounded DOM. */
+const MAX_COMPONENT_CANDIDATES = 2000;
+/** Likely-actionable elements considered when resolving a component anchor without a source stamp. */
+const COMPONENT_CANDIDATE_SELECTOR = '[data-reticle-source], [data-testid], button, a, input, select, textarea, [role]';
+function resolveContainer(scope) {
+    const body = document.body;
+    if (scope === undefined)
+        return body;
+    const byRef = refs.resolve(scope);
+    if (byRef instanceof HTMLElement)
+        return byRef;
+    try {
+        const found = document.querySelector(scope);
+        if (found instanceof HTMLElement)
+            return found;
+    }
+    catch {
+        // invalid selector — fall through to body
+    }
+    return body;
+}
+/**
+ * Resolve an element by its SOURCE location — the precise, granular auto-anchor. The babel plugin
+ * stamps `data-reticle-source="file:line:column"` on host elements, so a line-level starts-with match
+ * pins the exact JSX element with a single fast attribute selector (no fiber walk). Column is
+ * ignored so a small column drift doesn't unbind the anchor.
+ */
+function findBySource(container, source) {
+    const prefix = `${source.file}:${source.line}:`.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    try {
+        return Array.from(container.querySelectorAll(`[${SOURCE_ATTR}^="${prefix}"]`));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolve by component display name when no source stamp is available: scan a bounded set of
+ * likely-actionable elements and keep those whose NEAREST enclosing component (via the registered
+ * framework adapter) matches. Coarser than source (one component renders many hosts) — used as a
+ * fallback / for frameworks without a source plugin.
+ */
+function findByComponentName(container, component) {
+    const out = [];
+    let scanned = 0;
+    for (const el of Array.from(container.querySelectorAll(COMPONENT_CANDIDATE_SELECTOR))) {
+        if (scanned >= MAX_COMPONENT_CANDIDATES)
+            break;
+        scanned += 1;
+        const info = identifyComponent(el);
+        if (info !== null && info.componentStack[0] === component)
+            out.push(el);
+    }
+    return out;
+}
+/** Auto-anchor resolution: source (precise) first, then component name (coarse fallback). */
+function findByComponent(container, query) {
+    if (query.source !== undefined) {
+        const bySource = findBySource(container, query.source);
+        if (bySource.length > 0)
+            return bySource;
+    }
+    if (query.component !== undefined && query.component.length > 0) {
+        return findByComponentName(container, query.component);
+    }
+    return [];
+}
+/** Run the appropriate Testing-Library query for the given ElementQuery. */
+function findCandidates(query) {
+    const container = resolveContainer(query.scope);
+    const by = query.by;
+    const value = query.value;
+    // Explicit `by`+`value` form.
+    if (by !== undefined && value !== undefined) {
+        switch (by) {
+            case QueryBy.ROLE:
+                return queryAllByRole(container, value, query.name !== undefined ? { hidden: true, name: query.name } : { hidden: true });
+            case QueryBy.TEXT:
+                return queryAllByText(container, value, { exact: false });
+            case QueryBy.LABEL:
+                return queryAllByLabelText(container, value, { exact: false });
+            case QueryBy.PLACEHOLDER:
+                return queryAllByPlaceholderText(container, value, { exact: false });
+            case QueryBy.TESTID:
+                return queryAllByTestId(container, value, { exact: true });
+            case QueryBy.ALT:
+                return queryAllByAltText(container, value, { exact: false });
+            case QueryBy.COMPONENT:
+                // value is the component name; .source (if present) still takes precedence inside.
+                return findByComponent(container, { ...query, component: query.component ?? value });
+            default:
+                return [];
+        }
+    }
+    // Auto-anchor (component / source) — checked before the role/text fields so a query carrying
+    // both a component anchor and an incidental role resolves by the more durable anchor.
+    if (query.component !== undefined || query.source !== undefined) {
+        return findByComponent(container, query);
+    }
+    // Structured form (role+name, or any single field).
+    if (query.role !== undefined) {
+        const options = query.name !== undefined
+            ? { hidden: true, name: query.name }
+            : { hidden: true };
+        return queryAllByRole(container, query.role, options);
+    }
+    if (query.text !== undefined)
+        return queryAllByText(container, query.text, { exact: false });
+    if (query.label !== undefined) {
+        return queryAllByLabelText(container, query.label, { exact: false });
+    }
+    if (query.placeholder !== undefined) {
+        return queryAllByPlaceholderText(container, query.placeholder, { exact: false });
+    }
+    if (query.testid !== undefined)
+        return queryAllByTestId(container, query.testid, { exact: true });
+    if (query.alt !== undefined)
+        return queryAllByAltText(container, query.alt, { exact: false });
+    return [];
+}
+function inState(el, state) {
+    return getStates(el).includes(state);
+}
+/** Match an element predicate against the live DOM (plan/06). */
+export function matchQuery(query, state) {
+    let elements;
+    try {
+        elements = findCandidates(query);
+    }
+    catch {
+        elements = [];
+    }
+    const filtered = state === undefined ? elements : elements.filter((el) => inState(el, state));
+    const descriptors = filtered.map((el) => describe(el));
+    return { matched: descriptors.length > 0, count: descriptors.length, elements: descriptors };
+}
+/** Structural clusters of the page — the successor to the raw testid list in zero-match hints. */
+function buildPresentRegions(query) {
+    const container = resolveContainer(query.scope);
+    const regions = [];
+    const CONTAINER_ROLES = [
+        'list',
+        'listbox',
+        'grid',
+        'table',
+        'tree',
+        'treegrid',
+        'dialog',
+        'alertdialog',
+        'navigation',
+        'main',
+        'banner',
+        'form',
+        'search',
+        'menu',
+        'menubar',
+        'tablist',
+    ];
+    for (const role of CONTAINER_ROLES) {
+        let containers;
+        try {
+            containers = queryAllByRole(container, role, { hidden: true });
+        }
+        catch {
+            continue;
+        }
+        for (const el of containers) {
+            const name = el.getAttribute('aria-label') ??
+                el.getAttribute('aria-labelledby') ??
+                el.getAttribute('data-testid') ??
+                undefined;
+            const children = el.querySelectorAll('[role]');
+            const sample = [];
+            for (const child of Array.from(children)) {
+                if (sample.length >= 3)
+                    break;
+                const childRole = child.getAttribute('role');
+                const childName = child.getAttribute('aria-label') ??
+                    child.getAttribute('data-testid') ??
+                    child.textContent?.trim().slice(0, 40) ??
+                    '';
+                if (childRole !== null && childName.length > 0) {
+                    sample.push(`${childRole}[${childName}]`);
+                }
+            }
+            const region = { role, childCount: children.length, sample };
+            if (name !== undefined && name.length > 0)
+                region.name = name;
+            regions.push(region);
+            if (regions.length >= 10)
+                return regions;
+        }
+    }
+    return regions;
+}
+/** Diagnostic hint for a zero-match query: what testids ARE present in the searched scope. */
+function buildEmptyHint(query) {
+    const container = resolveContainer(query.scope);
+    const all = container.querySelectorAll(`[${TESTID_ATTR}]`);
+    const present = [];
+    for (const el of Array.from(all)) {
+        const id = el.getAttribute(TESTID_ATTR);
+        if (id !== null && id.length > 0 && !present.includes(id)) {
+            present.push(id);
+            if (present.length >= MAX_PRESENT_TESTIDS)
+                break;
+        }
+    }
+    const registered = getCapabilities().testids;
+    const knownEmptyState = present.some((id) => registered.includes(id));
+    const route = `${location.pathname}${location.search}`;
+    return {
+        route,
+        presentTestids: present,
+        presentRegions: buildPresentRegions(query),
+        knownEmptyState,
+    };
+}
+/** Resolve a query to descriptors for the `query` MCP tool. */
+export function runQuery(query) {
+    const result = matchQuery(query);
+    if (result.elements.length === 0) {
+        return { elements: result.elements, hint: buildEmptyHint(query) };
+    }
+    return { elements: result.elements };
+}
+//# sourceMappingURL=query.js.map

package/dist/dom/query.js.map

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

package/dist/dom/refs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Stable, human-meaningful element handles. Each element gets a ref like `e7`; the same
+ * element keeps its ref across snapshots, and a ref re-resolves to its element as long as
+ * the element is still in the document. See plan/03 (Refs).
+ */
+export declare class RefRegistry {
+    #private;
+    /** Get the existing ref for an element, or mint a new one. */
+    refFor(el: Element): string;
+    /** Resolve a ref back to its element, or null if it's gone/detached. */
+    resolve(ref: string): Element | null;
+}
+/** Process-wide registry shared by snapshot, query, and the action executor. */
+export declare const refs: RefRegistry;
+//# sourceMappingURL=refs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/dom/refs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,WAAW;;IAKtB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM;IAU3B,wEAAwE;IACxE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;CAUrC;AAED,gFAAgF;AAChF,eAAO,MAAM,IAAI,aAAoB,CAAC"}

package/dist/dom/refs.js

@@ -0,0 +1,36 @@
+/**
+ * Stable, human-meaningful element handles. Each element gets a ref like `e7`; the same
+ * element keeps its ref across snapshots, and a ref re-resolves to its element as long as
+ * the element is still in the document. See plan/03 (Refs).
+ */
+export class RefRegistry {
+    #toRef = new WeakMap();
+    #fromRef = new Map();
+    #seq = 0;
+    /** Get the existing ref for an element, or mint a new one. */
+    refFor(el) {
+        const existing = this.#toRef.get(el);
+        if (existing !== undefined)
+            return existing;
+        this.#seq += 1;
+        const ref = `e${String(this.#seq)}`;
+        this.#toRef.set(el, ref);
+        this.#fromRef.set(ref, new WeakRef(el));
+        return ref;
+    }
+    /** Resolve a ref back to its element, or null if it's gone/detached. */
+    resolve(ref) {
+        const weak = this.#fromRef.get(ref);
+        if (weak === undefined)
+            return null;
+        const el = weak.deref();
+        if (el === undefined || !el.isConnected) {
+            this.#fromRef.delete(ref);
+            return null;
+        }
+        return el;
+    }
+}
+/** Process-wide registry shared by snapshot, query, and the action executor. */
+export const refs = new RefRegistry();
+//# sourceMappingURL=refs.js.map

package/dist/dom/refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../../src/dom/refs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,WAAW;IACb,MAAM,GAAG,IAAI,OAAO,EAAmB,CAAC;IACxC,QAAQ,GAAG,IAAI,GAAG,EAA4B,CAAC;IACxD,IAAI,GAAG,CAAC,CAAC;IAET,8DAA8D;IAC9D,MAAM,CAAC,EAAW;QAChB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAC;QAC5C,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;QACf,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QACxC,OAAO,GAAG,CAAC;IACb,CAAC;IAED,wEAAwE;IACxE,OAAO,CAAC,GAAW;QACjB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACpC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,EAAE,KAAK,SAAS,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC;YACxC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC"}

package/dist/dom/snapshot.d.ts

@@ -0,0 +1,22 @@
+import { SnapshotMode } from '@reticlehq/core';
+interface SnapshotStatus {
+    route: string;
+    title: string;
+    visibleDialogs: string[];
+}
+export interface SnapshotResult {
+    tree: string;
+    status: SnapshotStatus;
+    nodes: number;
+    truncated: boolean;
+}
+interface SnapshotOptions {
+    scope?: string | undefined;
+    mode?: SnapshotMode | undefined;
+    maxNodes?: number | undefined;
+    maxDepth?: number | undefined;
+}
+/** Build the semantic accessibility snapshot of the page or a subtree (plan/04). */
+export declare function buildSnapshot(options?: SnapshotOptions): SnapshotResult;
+export {};
+//# sourceMappingURL=snapshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/dom/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAyC7D,UAAU,cAAc;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,eAAe;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AA+HD,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,CA4B3E"}

package/dist/dom/snapshot.js

@@ -0,0 +1,171 @@
+import { ElementState, SnapshotMode } from '@reticlehq/core';
+import { getAccessibleName, getRole, getStates, getValue, isVisible } from './a11y.js';
+import { refs } from './refs.js';
+import { isIgnored } from './dom-ignore.js';
+const INTERACTIVE = new Set([
+    'button',
+    'link',
+    'textbox',
+    'checkbox',
+    'radio',
+    'combobox',
+    'listbox',
+    'slider',
+    'spinbutton',
+    'switch',
+    'tab',
+    'menuitem',
+    'option',
+]);
+const SKIP_TAGS = new Set(['script', 'style', 'noscript', 'template', 'head', 'meta', 'link']);
+/** Cap on inlined text content so a verbose node can't blow up the snapshot. */
+const TEXT_MAX = 80;
+/**
+ * Concatenated DIRECT text of an element (its own text nodes, not descendants' — those are
+ * captured when their own element is walked, so no duplication). Collapsed + truncated.
+ * This is what makes a silent removal of non-interactive content (e.g. a KPI card) visible:
+ * the accessibility role tree alone omits generic containers' text.
+ */
+function directText(el) {
+    let out = '';
+    for (const node of el.childNodes) {
+        if (node.nodeType === 3 /* Node.TEXT_NODE */)
+            out += node.textContent ?? '';
+    }
+    const collapsed = out.replace(/\s+/g, ' ').trim();
+    return collapsed.length > TEXT_MAX ? `${collapsed.slice(0, TEXT_MAX)}…` : collapsed;
+}
+function skip(el) {
+    if (SKIP_TAGS.has(el.tagName.toLowerCase()))
+        return true;
+    if (isIgnored(el))
+        return true; // Reticle overlay + known dev overlays
+    if (el.getAttribute('aria-hidden') === 'true')
+        return true;
+    if (el instanceof HTMLElement && el.hidden)
+        return true;
+    const view = el.ownerDocument.defaultView;
+    if (view !== null) {
+        const style = view.getComputedStyle(el);
+        if (style.display === 'none')
+            return true;
+    }
+    return false;
+}
+function stateSuffix(el) {
+    const states = getStates(el).filter((s) => s === ElementState.DISABLED ||
+        s === ElementState.CHECKED ||
+        s === ElementState.EXPANDED ||
+        s === ElementState.FOCUSED);
+    return states.length > 0 ? ` [${states.join(',')}]` : '';
+}
+function formatLine(el, depth, role, name, layout) {
+    const indent = '  '.repeat(depth);
+    const value = getValue(el);
+    const namePart = name.length > 0 ? ` "${name}"` : '';
+    const refPart = INTERACTIVE.has(role) || name.length > 0 ? ` (ref=${refs.refFor(el)})` : '';
+    const valuePart = value !== undefined && value.length > 0 ? ` [value="${value}"]` : '';
+    const layoutPart = layout.length > 0 ? ` [${layout}]` : '';
+    return `${indent}- ${role}${namePart}${refPart}${valuePart}${layoutPart}${stateSuffix(el)}`;
+}
+/** A generic container's own text content, with no ref (kept lean — text isn't actionable). */
+function formatTextLine(depth, text) {
+    return `${'  '.repeat(depth)}- text "${text}"`;
+}
+/**
+ * Compact signature of an element's own layout when it is a grid/flex container. A layout
+ * regression (e.g. grid columns 2 -> 3) leaves the role+text tree identical, so a role-only
+ * snapshot is blind to it; this line makes it visible. Empty for non-container elements.
+ */
+function layoutSignature(el) {
+    const view = el.ownerDocument.defaultView;
+    if (view === null)
+        return '';
+    const style = view.getComputedStyle(el);
+    const display = style.display;
+    // Grid track templates are the high-signal CLS case (column/row count + sizing) and there are
+    // few grid containers per page. Flex is intentionally excluded: nearly every row is a flex
+    // box, so signing them all floods the snapshot for little regression value.
+    if (display === 'grid' || display === 'inline-grid') {
+        const cols = style.gridTemplateColumns;
+        return cols !== '' && cols !== 'none' ? `grid-cols:${cols}` : 'grid';
+    }
+    return '';
+}
+function walk(parent, depth, ctx) {
+    if (depth > ctx.maxDepth)
+        return;
+    for (const child of parent.children) {
+        if (ctx.nodes >= ctx.maxNodes) {
+            ctx.truncated = true;
+            return;
+        }
+        if (skip(child))
+            continue;
+        const role = getRole(child);
+        const name = getAccessibleName(child);
+        const interactive = INTERACTIVE.has(role);
+        // A generic, unnamed container's own text content — only consulted outside INTERACTIVE mode,
+        // so the actionable-only view stays lean while FULL/meaningful views see content regressions.
+        const lean = ctx.mode === SnapshotMode.INTERACTIVE;
+        const text = !lean && role === 'generic' && name.length === 0 ? directText(child) : '';
+        // Layout signature for grid/flex containers — makes CLS/layout regressions visible.
+        const layout = lean ? '' : layoutSignature(child);
+        const meaningful = interactive || role !== 'generic' || name.length > 0 || text.length > 0 || layout.length > 0;
+        const include = lean ? interactive : meaningful;
+        if (include) {
+            ctx.nodes += 1;
+            ctx.lines.push(text.length > 0 && name.length === 0 && layout.length === 0
+                ? formatTextLine(depth, text)
+                : formatLine(child, depth, role, name, layout));
+            walk(child, depth + 1, ctx);
+        }
+        else {
+            walk(child, depth, ctx);
+        }
+    }
+}
+function collectDialogs(root) {
+    const nodes = root.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]');
+    const names = [];
+    for (const node of nodes) {
+        if (isVisible(node))
+            names.push(getAccessibleName(node) || '(unnamed dialog)');
+    }
+    return names;
+}
+function buildStatus(root) {
+    return {
+        route: `${location.pathname}${location.search}${location.hash}`,
+        title: document.title,
+        visibleDialogs: collectDialogs(root),
+    };
+}
+/** Build the semantic accessibility snapshot of the page or a subtree (plan/04). */
+export function buildSnapshot(options = {}) {
+    const mode = options.mode ?? SnapshotMode.FULL;
+    const scopeEl = options.scope !== undefined
+        ? (refs.resolve(options.scope) ?? document.querySelector(options.scope))
+        : document.body;
+    const root = scopeEl ?? document.body;
+    const status = buildStatus(root);
+    if (mode === SnapshotMode.STATUS) {
+        return { tree: '', status, nodes: 0, truncated: false };
+    }
+    const ctx = {
+        lines: [],
+        nodes: 0,
+        truncated: false,
+        mode,
+        maxNodes: options.maxNodes ?? 400,
+        maxDepth: options.maxDepth ?? 20,
+    };
+    walk(root, 0, ctx);
+    return {
+        tree: ctx.lines.join('\n'),
+        status,
+        nodes: ctx.nodes,
+        truncated: ctx.truncated,
+    };
+}
+//# sourceMappingURL=snapshot.js.map