@reticlehq/browser 2.13.1 → 3.1.0

package/dist/connect-options.d.ts

@@ -1,120 +1,26 @@
 import type { RedactionConfig } from '@reticlehq/core';
-/**
- * What `reticle.connect()` accepts.
- *
- * Split out of reticle.ts when that file crossed the 600-line cap - the same move `session-info.ts`
- * made for the server's Session. A pure description of the SDK's public entry contract has no reason
- * to live inside the class that happens to consume it, and separating them keeps the surface every
- * integrating app actually reads reviewable on its own.
- */
 export interface ReticleConnectOptions {
-    /** WS endpoint of the local bridge. Defaults to ws://localhost:<port><path>. */
     url?: string;
-    /** Human-friendly session label so the agent can target the right tab. */
     session?: string;
-    /**
-     * Stable project identity, normally stamped by the build plugin (e.g. "acme-web-9f3c1d"). Lets the
-     * agent scope to the right app even when its dev server boots on an unexpected port. Optional.
-     */
     projectId?: string;
-    /**
-     * Browser/bridge pairing token. Required whenever the daemon has one, which is the ordinary case:
-     * it auto-provisions `~/.reticle/pairing-token` on first start and then refuses a hello without it,
-     * including on localhost. Non-localhost additionally needs `allowNonLocalhost`.
-     */
     token?: string;
-    /** Explicitly allow Reticle on a non-localhost page or bridge. Requires token. */
     allowNonLocalhost?: boolean;
-    /**
-     * Escape hatch for the production backstop. Reticle is dev-only and refuses to connect when the
-     * build reports NODE_ENV=production (an SSR healthcheck or a prod bundle opened locally would
-     * otherwise activate). The real fix is to gate the import behind `import.meta.env.DEV` so it's
-     * tree-shaken out; this flag only exists for the rare intentional prod diagnostic.
-     */
     allowInProduction?: boolean;
-    /** Show a small in-page status chip (connection + event count). */
     overlay?: boolean;
-    /**
-     * Capture request/response bodies on net.request events (dev-only; text-like content only,
-     * sensitive keys redacted, per-body capped). Off by default - bodies cost tokens and can carry PII.
-     */
     captureNetworkBodies?: boolean;
-    /**
-     * Make Reticle's OWN presenter visible to snapshots and queries. CONTRIBUTORS ONLY.
-     *
-     * The presenter is hidden from every tool by design, for a good reason: an agent that can drive
-     * Reticle's own interface can fabricate its own impact report, and Reticle chrome in a snapshot is
-     * noise in every other app on earth.
-     *
-     * The cost of that rule is that a HUD change is the only kind of change Reticle cannot be used to
-     * check — the panel rendering it is invisible to everything that could look at it. This hatch
-     * exists for exactly that case: the app under test IS Reticle. It reports itself in the app's
-     * capabilities, so a verdict drawn with it open can never be mistaken for an ordinary one.
-     */
+    sourceMapping?: boolean;
+    captureErrorBodies?: boolean;
     exposePresenter?: boolean;
-    /**
-     * The project root, so source paths report repo-relative instead of absolute.
-     *
-     * React's `_debugSource.fileName` is absolute; the babel stamp is repo-relative. Build plugins that
-     * can `define` a global set it themselves; frameworks that cannot (Next passes it through env,
-     * Astro through its own config) hand it here instead. Taking it as a connect OPTION is what keeps
-     * the generated app-side code plain JavaScript - the previous shape made the caller assign a global,
-     * and the TypeScript cast that needed shipped into a `.jsx` file and broke the build.
-     */
     root?: string;
-    /**
-     * The SDK's own package version, so a version-skewed pair against the daemon can name itself
-     * rather than surfacing as a bare `-32000`. Build plugins supply it automatically; pass it here
-     * only for a hand-wired connect that has no plugin.
-     */
     sdkVersion?: string;
-    /** Presenter mode: glow border, animated cursor, click/hover effects, narration HUD. */
     present?: boolean;
-    /** Per-action pacing (ms) in presenter mode so a human can follow. Default 450. */
     pace?: number;
-    /** Min ms each narration line stays visible before the next replaces it (presenter). Default 3000. */
     narrationDwellMs?: number;
-    /**
-     * Border behavior in presenter mode: 'session' (default) persists the border for the whole
-     * session; 'busy' restores the fade-after-idle behavior.
-     */
     border?: 'session' | 'busy';
-    /** Max accumulated activity-log rows before the oldest are pruned (presenter). Default 50. */
     logMax?: number;
-    /**
-     * Mount the floating human-recorder toolbar (Record/Stop/Annotate).
-     * Default off - purely additive, dev-only.
-     */
     recorder?: boolean;
-    /**
-     * Mount the page annotator: expanding the HUD enters click-to-annotate mode, and Reticle emits
-     * a HUMAN_MARK the agent drains via reticle_review. Defaults to ON with the presenter; pass
-     * `annotate: false` to suppress.
-     */
     annotate?: boolean;
-    /** Live-control: overridable ended-border fade delay (native timer). Default 4000. */
     endedFadeMs?: number;
-    /** Session auto-end after this much agent idle (presenter). Default 5min; agent-tunable via reticle_session. */
     idleEndMs?: number;
-    /**
-     * Extend the redaction rules with your app's own vocabulary.
-     *
-     * ```ts
-     * reticle.connect({
-     *   redact: {
-     *     keys: ['deviceSecretRef', /^partner[-_]?code$/i],  // also redact these
-     *     allow: ['designToken'],                            // stop redacting this false positive
-     *   },
-     * });
-     * ```
-     *
-     * Additive only - there is no way to replace the built-in rule, because a config that could would
-     * eventually ship an app that leaks. `keys` strings match a key name exactly (case-insensitively);
-     * a RegExp is tested against it. `allow` exempts a key from the DEFAULT rule and loses to `keys`.
-     *
-     * Literal `keys` strings also cross the bridge, so the daemon redacts them on the driven path,
-     * where request bodies are captured raw from the network stack and never pass through this SDK.
-     * RegExp entries and `allow` do NOT cross - see docs/usage.md ("Extending the redaction rules") for why, and what that means.
-     */
     redact?: RedactionConfig;
 }

package/dist/dom/a11y.d.ts

@@ -1,38 +1,9 @@
 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;
 export declare function getAccessibleName(el: Element): string;
-/**
- * The set of states relevant to assertions. `visible` is an O(depth) forced-style walk; callers that
- * already computed it (describe) pass it in so it isn't resolved twice per element.
- */
 export declare function getStates(el: Element, visible?: boolean): 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), walking to
- * root. This is an O(depth) forced-style walk PER node; `memo` (optional, scoped to ONE synchronous
- * query pass) caches the full inherited result per element so a broad state-filtered query stops
- * re-resolving getComputedStyle up the same ancestor chain for every sibling. Sound because the DOM is
- * static for the pass's duration — the cache MUST be a per-call Map, never module-level (that would go
- * stale the instant the app mutates, the same trap the shadow-root note in query.ts documents).
- */
-/**
- * True when the element is inside the viewport right now: visible AND its bounding box intersects
- * the window. This is what makes a scroll assertable (#398) — content below the fold of a scrolling
- * container is `visible`/`present` before any scroll, so only a viewport-intersection check can tell
- * "scrolled into view" from "was always in the DOM". Uses getBoundingClientRect (viewport-relative,
- * already accounts for scroll position), not an IntersectionObserver, so it stays synchronous inside
- * the predicate pass.
- */
 export declare function isInViewport(el: Element, memo?: Map<Element, boolean>): boolean;
 export declare function isVisible(el: Element, memo?: Map<Element, boolean>): boolean;
-/** Build the compact descriptor surfaced to the agent. `memo` (optional) shares the per-call
- * visibility cache with the query's state filter so ancestors aren't re-walked per element. */
 export declare function describe(el: Element, memo?: Map<Element, boolean>): ElementDescriptor;

package/dist/dom/a11y.js

@@ -1,22 +1,9 @@
 import { ElementState, REDACTED_VALUE } from '@reticlehq/core';
 import { isButton, isHtmlElement, isImage, isInput, isSelect, isTextArea } from './realm.js';
-import { refs } from './refs.js';
+import { refs } from './addressing/refs.js';
 import { inspectChart } from './chart.js';
 import { isSensitiveKey } from '../security/serialization.js';
-import { formatSource, sourceFromDom } from './source.js';
-/**
- * Roles whose accessible name comes from their text content (ARIA's `nameFrom: author content`).
- *
- * `radio`, `checkbox`, `row` and `tooltip` were missing, and the gap is not cosmetic: a segmented
- * filter written as `<button role="radio">held</button>` — an extremely ordinary design-system
- * control — reported as a nameless `radio`, so `by: role` + name could not address it at all and an
- * agent had to fall back to a testid the app has no reason to carry. Measured on a shipments console:
- * six filters, six nameless radios, none reachable by name.
- *
- * `listitem`, `status` and `alert` are NOT in the spec's list. They are kept as a deliberate
- * over-approximation — a name computed from content is more useful than no name — and removing them
- * has no measured symptom to justify the risk.
- */
+import { formatSource, sourceFromDom } from './addressing/source.js';
 const NAME_FROM_CONTENT = new Set([
     'button',
     'link',
@@ -57,16 +44,6 @@ function inputRole(input) {
         return 'button';
     return 'textbox';
 }
-/**
- * Cheap author-supplied-naming probe: an explicit `aria-label`, any `aria-labelledby`, or a
- * `title`. Attribute reads only - no name computation - so `getRole` can consult it without
- * recursion into `getAccessibleName`.
- *
- * This decides `section` -> `region`, which the implicit-role table makes CONDITIONAL: an unnamed
- * `<section>` is a plain `generic` container, while one carrying an accessible name is exposed as
- * `region`. Getting that backwards either floods every page with phantom regions or hides real
- * ones, so both halves are pinned by tests.
- */
 function hasAuthorNaming(el) {
     const label = el.getAttribute('aria-label');
     if (label !== null && label.trim().length > 0)
@@ -77,7 +54,6 @@ function hasAuthorNaming(el) {
     const title = el.getAttribute('title');
     return title !== null && title.trim().length > 0;
 }
-/** 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)
@@ -124,10 +100,6 @@ export function getRole(el) {
         case 'thead':
         case 'tfoot':
             return 'rowgroup';
-        // A cell's role follows its grid context: plain tables expose `cell`/`columnheader`,
-        // while inside an explicit `role="grid"`/`role="treegrid"` the same markup is exposed as
-        // `gridcell` - the pair data-grid queries actually reach for (`{ role: "cell" }` against a
-        // CSS grid pretending to be a table would otherwise answer zero).
         case 'td':
             return el.closest('[role~="grid"], [role~="treegrid"]') !== null ? 'gridcell' : 'cell';
         case 'th': {
@@ -186,22 +158,6 @@ function labelledByText(el) {
     const joined = parts.join(' ').trim();
     return joined.length > 0 ? joined : null;
 }
-/** Accessible name via a practical subset of the accname algorithm. */
-/** Accessible name via a practical subset of the accname algorithm. */
-/**
- * Text content with `aria-hidden` subtrees removed.
- *
- * The accessible-name spec excludes them, and so does the matcher, because THIS function is what
- * `by: role` + name matches through. Reading raw `textContent` here made the name we REPORT differ
- * from the name that can be SELECTED: Material UI renders its required-field marker as
- * `<span aria-hidden="true"> *</span>`, so a login field was reported as `"Username *"` and
- * addressable only as `"Username"`. Reporting a name the agent cannot use defeats the purpose of
- * reporting it at all, so both come from the same rule.
- *
- * An `<img alt>` contributes its alt text the way the spec's subtree step treats embedded
- * alternatives: `<button><img alt="Close"></button>` is named "Close", not nameless. Pieces are
- * joined with spaces so an icon followed by a word never fuses into one unmatchable token.
- */
 function textWithoutHidden(node) {
     if (node.nodeType === Node.TEXT_NODE)
         return node.textContent ?? '';
@@ -244,10 +200,6 @@ export function getAccessibleName(el) {
             if (text.length > 0)
                 return text;
         }
-        // Submit-like inputs carry their name on `value`, exactly where the visible caption comes
-        // from: `<input type="submit" value="Send">` renders a button reading Send. Without this the
-        // descriptor printed `button ""` while `by: text` found the very same input by "Send", so the
-        // two locators disagreed about one element - the disagreement this engine exists to prevent.
         if (isInput(el)) {
             const type = el.type.toLowerCase();
             if ('submit' === type || 'button' === type || 'reset' === type) {
@@ -278,10 +230,6 @@ function ariaBool(el, attr) {
         return undefined;
     return 'true' === value;
 }
-/**
- * The set of states relevant to assertions. `visible` is an O(depth) forced-style walk; callers that
- * already computed it (describe) pass it in so it isn't resolved twice per element.
- */
 export function getStates(el, visible = isVisible(el)) {
     const states = [ElementState.PRESENT];
     states.push(visible ? ElementState.VISIBLE : ElementState.HIDDEN);
@@ -297,12 +245,6 @@ export function getStates(el, visible = isVisible(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 (!isInput(el) && !isTextArea(el) && !isSelect(el)) {
         return false;
@@ -328,7 +270,6 @@ export function getValue(el) {
     const valueNow = el.getAttribute('aria-valuenow');
     return valueNow ?? undefined;
 }
-/** Whether the element's OWN box hides it — one forced-style resolution, no ancestor walk. */
 function selfHidden(el) {
     if ('true' === el.getAttribute('aria-hidden'))
         return true;
@@ -347,22 +288,6 @@ function selfHidden(el) {
     }
     return false;
 }
-/**
- * Whether the element is actually visible (not display:none/hidden/aria-hidden/opacity:0), walking to
- * root. This is an O(depth) forced-style walk PER node; `memo` (optional, scoped to ONE synchronous
- * query pass) caches the full inherited result per element so a broad state-filtered query stops
- * re-resolving getComputedStyle up the same ancestor chain for every sibling. Sound because the DOM is
- * static for the pass's duration — the cache MUST be a per-call Map, never module-level (that would go
- * stale the instant the app mutates, the same trap the shadow-root note in query.ts documents).
- */
-/**
- * True when the element is inside the viewport right now: visible AND its bounding box intersects
- * the window. This is what makes a scroll assertable (#398) — content below the fold of a scrolling
- * container is `visible`/`present` before any scroll, so only a viewport-intersection check can tell
- * "scrolled into view" from "was always in the DOM". Uses getBoundingClientRect (viewport-relative,
- * already accounts for scroll position), not an IntersectionObserver, so it stays synchronous inside
- * the predicate pass.
- */
 export function isInViewport(el, memo) {
     if (!isVisible(el, memo))
         return false;
@@ -381,9 +306,6 @@ export function isVisible(el, memo) {
     if (cached !== undefined)
         return cached;
     const parent = el.parentElement;
-    // Each cached boolean already folds in that node's own aria-hidden/[hidden]/display/visibility/opacity,
-    // so inherited visibility composes by AND up the chain and a sibling short-circuits at the first
-    // cached ancestor.
     const result = !selfHidden(el) && (null === parent || isVisible(parent, memo));
     if (memo !== undefined)
         memo.set(el, result);
@@ -394,13 +316,11 @@ 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. `memo` (optional) shares the per-call
- * visibility cache with the query's state filter so ancestors aren't re-walked per element. */
 export function describe(el, memo) {
     const value = getValue(el);
     const text = getVisibleText(el);
     const name = getAccessibleName(el);
-    const visible = isVisible(el, memo); // O(depth) style walk — computed ONCE and reused by getStates
+    const visible = isVisible(el, memo);
     const base = {
         ref: refs.refFor(el),
         role: getRole(el),
@@ -412,16 +332,9 @@ export function describe(el, memo) {
         base.value = value;
     if (text.length > 0 && text !== name)
         base.text = text;
-    // DOM-only lookup on purpose: describe() runs once per matched element, so the adapter's fiber walk
-    // would turn a broad query into thousands of tree traversals. The stamped attribute answers the
-    // same question for a fraction of the cost, and single-element paths that can afford the better
-    // answer (inspect, act, review) use sourceFor() instead.
     const source = formatSource(sourceFromDom(el));
     if (source !== undefined)
         base.source = source;
-    // Chart faults, only when there are any. Gated on the element actually containing plot geometry so
-    // the common case — every non-chart element on the page — pays one querySelector miss and nothing
-    // else, and a HEALTHY chart adds no bytes to the wire either.
     if (el.querySelector('path, polyline, polygon') !== null) {
         const faults = inspectChart(el).findings;
         if (faults.length > 0)

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

@@ -0,0 +1,25 @@
+export declare const AnchorStrategy: {
+    readonly TESTID: "testid";
+    readonly COMPONENT: "component";
+    readonly ROLE: "role";
+    readonly POSITION: "position";
+};
+export type AnchorStrategy = (typeof AnchorStrategy)[keyof typeof AnchorStrategy];
+export interface AnchorInput {
+    testid?: string;
+    component?: string;
+    source?: {
+        file: string;
+        line: number;
+    };
+    role?: string;
+    name?: string;
+    nth?: number;
+}
+interface SynthesizedAnchor {
+    strategy: AnchorStrategy;
+    value: string;
+    stable: boolean;
+}
+export declare function synthesizeAnchor(input: AnchorInput): SynthesizedAnchor;
+export {};

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

@@ -0,0 +1,41 @@
+export const AnchorStrategy = {
+    TESTID: 'testid',
+    COMPONENT: 'component',
+    ROLE: 'role',
+    POSITION: 'position',
+};
+function nonEmpty(s) {
+    return 'string' === typeof s && s.length > 0;
+}
+function sourceTag(source) {
+    const base = source.file.split('/').pop() ?? source.file;
+    return `${base}:${source.line}`;
+}
+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 };
+    }
+    return { strategy: AnchorStrategy.POSITION, value: `el#${input.nth ?? 0}`, stable: false };
+}

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

@@ -0,0 +1,14 @@
+import { type Ref } from '@reticlehq/core';
+export declare const MAX_TRACKED_REFS = 10000;
+export declare function echoRef(ref: string): string;
+export declare const REF_BLOCK = 100;
+export declare class RefRegistry {
+    #private;
+    constructor(storage?: () => Storage | undefined);
+    get size(): number;
+    markEdited(): void;
+    mintedBeforeLastEdit(ref: string): boolean;
+    refFor(el: Element): Ref;
+    resolve(ref: string): Element | null;
+}
+export declare const refs: RefRegistry;

package/dist/dom/addressing/refs.js

@@ -0,0 +1,114 @@
+import { TRANSPORT_LIMITS, asRef } from '@reticlehq/core';
+export const MAX_TRACKED_REFS = 10000;
+const REF_ELISION = '…';
+const REF_PREFIX = 'e';
+export function echoRef(ref) {
+    const max = TRANSPORT_LIMITS.MAX_REF_LENGTH;
+    return max >= ref.length ? ref : `${ref.slice(0, max)}${REF_ELISION}`;
+}
+const SWEEP_EVERY_MINTS = 1000;
+const REF_BASE_KEY = '__reticle_ref_base';
+export const REF_BLOCK = 100;
+function readBase(store) {
+    try {
+        const raw = store?.getItem(REF_BASE_KEY);
+        const value = null === raw || undefined === raw ? Number.NaN : Number(raw);
+        return Number.isSafeInteger(value) && value > 0 ? value : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export class RefRegistry {
+    #toRef = new WeakMap();
+    #fromRef = new Map();
+    #storage;
+    #seq = 0;
+    #reserved = 0;
+    #mintsSinceSweep = 0;
+    #editedAtSeq = 0;
+    constructor(storage = () => globalThis.sessionStorage) {
+        this.#storage = storage;
+    }
+    #reserve() {
+        let store;
+        try {
+            store = this.#storage();
+        }
+        catch {
+            store = undefined;
+        }
+        const base = Math.max(readBase(store), this.#seq);
+        this.#reserved = base + REF_BLOCK;
+        try {
+            store?.setItem(REF_BASE_KEY, String(this.#reserved));
+        }
+        catch {
+        }
+        this.#seq = base;
+    }
+    get size() {
+        return this.#fromRef.size;
+    }
+    #evictOldest() {
+        const oldest = this.#fromRef.keys().next();
+        if (oldest.done !== true)
+            this.#fromRef.delete(oldest.value);
+    }
+    #sweep() {
+        for (const [ref, weak] of this.#fromRef) {
+            const el = weak.deref();
+            if (el === undefined || !el.isConnected)
+                this.#fromRef.delete(ref);
+        }
+        while (this.#fromRef.size > MAX_TRACKED_REFS)
+            this.#evictOldest();
+    }
+    markEdited() {
+        this.#editedAtSeq = this.#seq;
+    }
+    mintedBeforeLastEdit(ref) {
+        if (0 === this.#editedAtSeq || !ref.startsWith(REF_PREFIX))
+            return false;
+        const n = Number(ref.slice(REF_PREFIX.length));
+        return Number.isSafeInteger(n) && n > 0 && n <= this.#editedAtSeq;
+    }
+    refFor(el) {
+        const existing = this.#toRef.get(el);
+        if (existing !== undefined) {
+            const weak = this.#fromRef.get(existing);
+            this.#fromRef.delete(existing);
+            this.#fromRef.set(existing, weak ?? new WeakRef(el));
+            return existing;
+        }
+        if (this.#seq >= this.#reserved)
+            this.#reserve();
+        this.#seq += 1;
+        const ref = asRef(`${REF_PREFIX}${String(this.#seq)}`);
+        this.#toRef.set(el, ref);
+        this.#fromRef.set(ref, new WeakRef(el));
+        this.#mintsSinceSweep += 1;
+        if (this.#mintsSinceSweep >= SWEEP_EVERY_MINTS) {
+            this.#mintsSinceSweep = 0;
+            this.#sweep();
+        }
+        else if (this.#fromRef.size > MAX_TRACKED_REFS) {
+            this.#evictOldest();
+        }
+        return ref;
+    }
+    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;
+        }
+        this.#fromRef.delete(ref);
+        this.#fromRef.set(ref, weak);
+        return el;
+    }
+}
+export const refs = new RefRegistry();

package/dist/dom/addressing/source.d.ts

@@ -0,0 +1,9 @@
+export interface SourceLocation {
+    file: string;
+    line: number;
+}
+export declare function parseSourceAttr(value: string | null): SourceLocation | undefined;
+export declare function sourceFromDom(el: Element): SourceLocation | undefined;
+export declare function sourceFor(el: Element, adapterSource: SourceLocation | undefined): SourceLocation | undefined;
+export declare function documentHasSourceStamps(doc: Document): boolean;
+export declare function formatSource(source: SourceLocation | undefined): string | undefined;

package/dist/dom/addressing/source.js

@@ -0,0 +1,29 @@
+import { DATA_RETICLE_SOURCE_ATTR } from '@reticlehq/core';
+const SOURCE_ATTR = DATA_RETICLE_SOURCE_ATTR;
+export function parseSourceAttr(value) {
+    if (null === value)
+        return undefined;
+    const m = /^(.*):(\d+):(\d+)$/.exec(value);
+    if (null === m)
+        return undefined;
+    const file = m[1];
+    const line = Number(m[2]);
+    if (file === undefined || 0 === file.length || !Number.isFinite(line))
+        return undefined;
+    return { file, line };
+}
+export function sourceFromDom(el) {
+    const host = el.closest(`[${SOURCE_ATTR}]`);
+    return host !== null ? parseSourceAttr(host.getAttribute(SOURCE_ATTR)) : undefined;
+}
+export function sourceFor(el, adapterSource) {
+    if (adapterSource !== undefined)
+        return { file: adapterSource.file, line: adapterSource.line };
+    return sourceFromDom(el);
+}
+export function documentHasSourceStamps(doc) {
+    return doc.querySelector(`[${SOURCE_ATTR}]`) !== null;
+}
+export function formatSource(source) {
+    return source === undefined ? undefined : `${source.file}:${String(source.line)}`;
+}