@reticlehq/browser 2.13.1 → 3.1.0

package/dist/util/captured-method.d.ts

@@ -1,37 +1,2 @@
-/**
- * Read a host object's method as a STORED VALUE, for code that has to put it back.
- *
- * Every observer here patches a global and must be able to undo it: `console.error`, `window.fetch`,
- * `window.setTimeout`, `Date.now`. Undoing means holding the true original — the same function
- * object, so teardown restores exactly what was there and a later install can recognise it by
- * identity — and calling through a separately bound copy, because a host method invoked with the
- * wrong receiver throws (`fetch` gives "Illegal invocation").
- *
- * Written as `const original = window.fetch`, that is a bare unbound method reference, and
- * `@typescript-eslint/unbound-method` is right to flag the SHAPE even though this use is deliberate:
- * the rule cannot see that the next line binds it, nor that the raw value only ever goes back into
- * the slot it came from.
- *
- * The two obvious ways out are both wrong here. An `eslint-disable` is against this repo's standing
- * rule and hides the shape from every future reader. Annotating `this: void` asserts the function
- * does not use its receiver — which for a console method or `fetch` is simply false, and is the very
- * reason the binding exists.
- *
- * So the intent is expressed instead of suppressed. A property descriptor's `value` is a stored
- * value, not a method being detached from its object, which is exactly the distinction the rule is
- * drawing and exactly what this code wants. It is also strictly more accurate for the restore case:
- * it reads what the slot HOLDS rather than what calling the property would do, so an accessor
- * defined on the object cannot be silently flattened into its result.
- *
- * Returns undefined when the property is absent or inherited rather than own — a caller that needs a
- * fallback to the prototype chain should say so at its own call site rather than have it hidden here.
- */
 export declare function capturedMethod<T>(target: object, key: PropertyKey): T | undefined;
-/**
- * The same, for a property this code knows is present — the globals every observer patches.
- *
- * Throws rather than returning a broken teardown. A missing `window.fetch` is not a condition any
- * caller here can recover from, and silently installing a patch that cannot be undone is worse than
- * refusing: the page keeps the wrapper for the rest of its life with nothing able to remove it.
- */
 export declare function requireCapturedMethod<T>(target: object, key: PropertyKey): T;

package/dist/util/captured-method.js

@@ -1,41 +1,6 @@
-/**
- * Read a host object's method as a STORED VALUE, for code that has to put it back.
- *
- * Every observer here patches a global and must be able to undo it: `console.error`, `window.fetch`,
- * `window.setTimeout`, `Date.now`. Undoing means holding the true original — the same function
- * object, so teardown restores exactly what was there and a later install can recognise it by
- * identity — and calling through a separately bound copy, because a host method invoked with the
- * wrong receiver throws (`fetch` gives "Illegal invocation").
- *
- * Written as `const original = window.fetch`, that is a bare unbound method reference, and
- * `@typescript-eslint/unbound-method` is right to flag the SHAPE even though this use is deliberate:
- * the rule cannot see that the next line binds it, nor that the raw value only ever goes back into
- * the slot it came from.
- *
- * The two obvious ways out are both wrong here. An `eslint-disable` is against this repo's standing
- * rule and hides the shape from every future reader. Annotating `this: void` asserts the function
- * does not use its receiver — which for a console method or `fetch` is simply false, and is the very
- * reason the binding exists.
- *
- * So the intent is expressed instead of suppressed. A property descriptor's `value` is a stored
- * value, not a method being detached from its object, which is exactly the distinction the rule is
- * drawing and exactly what this code wants. It is also strictly more accurate for the restore case:
- * it reads what the slot HOLDS rather than what calling the property would do, so an accessor
- * defined on the object cannot be silently flattened into its result.
- *
- * Returns undefined when the property is absent or inherited rather than own — a caller that needs a
- * fallback to the prototype chain should say so at its own call site rather than have it hidden here.
- */
 export function capturedMethod(target, key) {
     return Object.getOwnPropertyDescriptor(target, key)?.value;
 }
-/**
- * The same, for a property this code knows is present — the globals every observer patches.
- *
- * Throws rather than returning a broken teardown. A missing `window.fetch` is not a condition any
- * caller here can recover from, and silently installing a patch that cannot be undone is worse than
- * refusing: the page keeps the wrapper for the rest of its life with nothing able to remove it.
- */
 export function requireCapturedMethod(target, key) {
     const value = capturedMethod(target, key);
     if (value === undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "2.13.1",
+  "version": "3.1.0",
   "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,12 +13,13 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@reticlehq/core": "2.13.1"
+    "@reticlehq/core": "3.1.0"
   },
   "devDependencies": {
     "@iconify-json/heroicons-outline": "^1.2.1",
     "@iconify-json/heroicons-solid": "^1.2.1",
     "@tanstack/query-core": "^5.101.4",
+    "esbuild": "^0.28.2",
     "jotai": "^2.20.2",
     "jsdom": "^30.0.1",
     "mobx": "^7.0.3",
@@ -35,7 +36,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reticlehq/reticle.git",
-    "directory": "packages/browser"
+    "directory": "adapters/realm/browser"
   },
   "homepage": "https://github.com/reticlehq/reticle#readme",
   "bugs": "https://github.com/reticlehq/reticle/issues",
@@ -59,7 +60,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "node scripts/embed-heroicons.mjs && tsc -b",
+    "build": "node scripts/embed-heroicons.mjs && tsc -b && node ../../../scripts/alias-dist.mjs",
     "typecheck": "tsc -b",
     "lint": "eslint src",
     "test:unit": "vitest run src --passWithNoTests",

package/dist/actions/synthetic-input.d.ts

@@ -1,9 +0,0 @@
-/** True while a Reticle-dispatched input event is being delivered. */
-export declare function isSyntheticInput(): boolean;
-/**
- * Run `dispatch` marked as Reticle's own.
- *
- * `finally` rather than a trailing decrement: a listener that throws must not leave the flag stuck
- * on, which would silently disable annotation for the rest of the page's life.
- */
-export declare function asSyntheticInput<T>(dispatch: () => T): T;

package/dist/actions/synthetic-input.js

@@ -1,40 +0,0 @@
-/**
- * Is the input event currently being dispatched one that RETICLE made?
- *
- * The annotator listens for clicks in the capture phase and cancels them, because a click in
- * annotate mode is a request to place a mark rather than a request to press a button. That is right
- * for a person and wrong for the agent: `reticle_act` dispatches its clicks into the same document,
- * so with the HUD expanded every agent click was swallowed while the action still reported
- * `dispatched: true`. Measured on this repo's own fixture — the same click that produced
- * `POST /api/login -> 200` with annotate off produced no network at all with it on.
- *
- * `isTrusted` looks like the answer and is not usable: it is false for everything `dispatchEvent`
- * creates, which is also how every test in this package drives the annotator, so gating on it would
- * make annotation untestable and would still not distinguish Reticle's clicks from the page's own
- * synthetic ones.
- *
- * So Reticle marks its own. Dispatch is synchronous, so a plain depth counter held across the call
- * is exact: any listener running inside it — capture phase included — is running because of us.
- * Nested actions are counted rather than flagged, so an inner action finishing does not clear the
- * mark for the outer one still in flight.
- */
-let depth = 0;
-/** True while a Reticle-dispatched input event is being delivered. */
-export function isSyntheticInput() {
-    return depth > 0;
-}
-/**
- * Run `dispatch` marked as Reticle's own.
- *
- * `finally` rather than a trailing decrement: a listener that throws must not leave the flag stuck
- * on, which would silently disable annotation for the rest of the page's life.
- */
-export function asSyntheticInput(dispatch) {
-    depth += 1;
-    try {
-        return dispatch();
-    }
-    finally {
-        depth -= 1;
-    }
-}

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

@@ -1,65 +0,0 @@
-/**
- * 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 {};

package/dist/dom/auto-anchor.js

@@ -1,74 +0,0 @@
-/**
- * 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 'string' === typeof s && 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 };
-}

package/dist/dom/refs.d.ts

@@ -1,90 +0,0 @@
-import { type Ref } from '@reticlehq/core';
-/**
- * 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.
- */
-/**
- * How many ref -> element entries are retained.
- *
- * The forward map is weak, so elements are always collectable; this bounds the BOOKKEEPING, which was
- * not. Refs are minted far more often than an agent asks about them — every meaningful DOM addition,
- * every transitionend, every scroll reveal — and the only eviction used to be "the agent happened to
- * resolve this exact dead ref". A busy app over a long session therefore accumulated entries for
- * elements that had been garbage for hours.
- *
- * Sized generously because eviction is not free of consequence (see refFor): the useful lifetime of a
- * ref is one agent turn, and this is far more than any one turn produces.
- */
-export declare const MAX_TRACKED_REFS = 10000;
-/**
- * A ref, made safe to interpolate into an error message.
- *
- * A ref Reticle mints is `e7` — three characters. A ref a CALLER passes is whatever they typed, and
- * an agent guessing at the schema can pass 100KB of it. Every stale-ref message interpolates that
- * value directly, so the caller's own bad argument came back as a 100KB error.
- *
- * The server caps error messages centrally, but it cannot help here: the browser's transport
- * serializer truncates from the TAIL first, which severs "… no longer resolves to an element" — the
- * exact substring the server's recovery table matches on. A stale ref then arrives classified as a
- * possible Reticle defect. So the echo is bounded at the source, where the untrusted value enters
- * the message.
- */
-export declare function echoRef(ref: string): string;
-/**
- * How many numbers a document claims at once.
- *
- * The reservation is a synchronous storage write, so it cannot happen per mint — mints are frequent
- * (every meaningful DOM addition, every transitionend, every scroll reveal). One write per this many
- * mints is free.
- *
- * Sized to keep refs SHORT, and the first attempt at that reasoned about the wrong axis. It bounded
- * how many navigations it took to reach seven digits and concluded "a hundred" — but the cost is not
- * paid at seven digits, it is paid at every digit, on every ref, in every snapshot and every error
- * message, on every turn. At 10,000 the SECOND document already mints five-digit refs.
- *
- * Measured on one unchanged three-element page across a session: 61 tokens on the first document,
- * 64 after a reload, 65 later — +6.5% for the same page, entirely in ref width. The benchmark saw the
- * same thing as a ~4% rise in average observation cost, which is what a benchmark is for.
- *
- * So the block is small. A document claims another one when it outmints this, which costs one more
- * storage write and is exactly proportional: a page with thousands of elements has a long snapshot
- * anyway, and a small page — the common case, and the one an agent drives repeatedly — keeps
- * three-digit refs across dozens of navigations.
- */
-export declare const REF_BLOCK = 100;
-export declare class RefRegistry {
-    #private;
-    /**
-     * Storage is injected rather than read from the global for the same reason the clock is: it is an
-     * ambient dependency that decides behaviour, and the cross-document property is untestable if the
-     * only way to get a second document is to actually navigate.
-     */
-    constructor(storage?: () => Storage | undefined);
-    /** How many reverse entries are currently retained. Exposed so the bound can be asserted. */
-    get size(): number;
-    /**
-     * A hot update just replaced modules in this document: every ref handed out so far was minted
-     * against the DOM the previous version of that code produced.
-     *
-     * Only the boundary is recorded. Nothing is evicted — a hot update is not a navigation, and most
-     * of the page survives one, so refs minted before it very often still resolve. This exists so the
-     * ones that DON'T can say why.
-     */
-    markEdited(): void;
-    /** Was this ref handed out before the last hot update? False while no update has been observed. */
-    mintedBeforeLastEdit(ref: string): boolean;
-    /** Get the existing ref for an element, or mint a new one. */
-    refFor(el: Element): Ref;
-    /**
-     * Resolve a ref back to its element, or null if it's gone/detached.
-     *
-     * Takes a plain `string` ON PURPOSE: this is the untrusted-input path — the ref comes from the agent
-     * over the wire, and a miss is answered with null rather than an error. Requiring a branded Ref here
-     * would force a meaningless cast at every wire boundary and buy nothing; the brand's value is on the
-     * MINT (refFor) so our own code cannot pass, say, a sessionId where a handle is expected.
-     */
-    resolve(ref: string): Element | null;
-}
-/** Process-wide registry shared by snapshot, query, and the action executor. */
-export declare const refs: RefRegistry;

package/dist/dom/refs.js

@@ -1,245 +0,0 @@
-import { TRANSPORT_LIMITS, asRef } from '@reticlehq/core';
-/**
- * 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.
- */
-/**
- * How many ref -> element entries are retained.
- *
- * The forward map is weak, so elements are always collectable; this bounds the BOOKKEEPING, which was
- * not. Refs are minted far more often than an agent asks about them — every meaningful DOM addition,
- * every transitionend, every scroll reveal — and the only eviction used to be "the agent happened to
- * resolve this exact dead ref". A busy app over a long session therefore accumulated entries for
- * elements that had been garbage for hours.
- *
- * Sized generously because eviction is not free of consequence (see refFor): the useful lifetime of a
- * ref is one agent turn, and this is far more than any one turn produces.
- */
-export const MAX_TRACKED_REFS = 10000;
-/** Marks a ref that was too long to echo in full. */
-const REF_ELISION = '…';
-/** Every ref Reticle mints is this letter followed by its sequence number. */
-const REF_PREFIX = 'e';
-/**
- * A ref, made safe to interpolate into an error message.
- *
- * A ref Reticle mints is `e7` — three characters. A ref a CALLER passes is whatever they typed, and
- * an agent guessing at the schema can pass 100KB of it. Every stale-ref message interpolates that
- * value directly, so the caller's own bad argument came back as a 100KB error.
- *
- * The server caps error messages centrally, but it cannot help here: the browser's transport
- * serializer truncates from the TAIL first, which severs "… no longer resolves to an element" — the
- * exact substring the server's recovery table matches on. A stale ref then arrives classified as a
- * possible Reticle defect. So the echo is bounded at the source, where the untrusted value enters
- * the message.
- */
-export function echoRef(ref) {
-    const max = TRANSPORT_LIMITS.MAX_REF_LENGTH;
-    return max >= ref.length ? ref : `${ref.slice(0, max)}${REF_ELISION}`;
-}
-/**
- * Full-sweep cadence. The deref-sweep is O(retained), and a page legitimately holding ≥ MAX_TRACKED_REFS
- * live elements (a 10k-node dashboard) can never get under the cap that way, so running it on EVERY mint
- * over the cap turned each mint into a 10k-entry scan — measured 264µs vs 0.20µs (1,300x) on the app's
- * main thread, ~2.6% of it forever on a churning page. The cap is instead held by an O(1) oldest-drop per
- * over-cap mint, and the expensive dead-entry sweep runs once per this many mints (amortized O(1)).
- */
-const SWEEP_EVERY_MINTS = 1000;
-/**
- * Where a document records the ref numbers it has claimed, so the next one starts past them.
- *
- * Refs are per-DOCUMENT: a reload or a cross-page link tears this module down and the next document
- * used to start minting from `e1` again. So `e7` from page A was a valid, resolvable, DIFFERENT
- * element on page B — nothing refused, the wrong element was acted on, and the result came back `ok`.
- * The SPA case was always safe (WeakRef liveness + isConnected); this was the other half, and the
- * more dangerous one, because it produced a false green instead of an error.
- *
- * Deliberately NOT a change to the ref grammar. Stamping refs `e7@3` would have worked too, but every
- * agent passes refs back verbatim and every saved flow on disk already holds bare ones, so it buys a
- * wire-format migration for a property the sequence itself can carry. A number that never restarts
- * means a stale ref simply misses the map, and the refusal that already exists — already worded for
- * exactly this case — fires unchanged.
- *
- * Namespaced like the session key it sits beside; `sessionStorage` is the right scope for the same
- * reason session continuity uses it (survives reloads and same-tab navigations, not shared with
- * another tab, which is a different session with its own registry anyway).
- */
-const REF_BASE_KEY = '__reticle_ref_base';
-/**
- * How many numbers a document claims at once.
- *
- * The reservation is a synchronous storage write, so it cannot happen per mint — mints are frequent
- * (every meaningful DOM addition, every transitionend, every scroll reveal). One write per this many
- * mints is free.
- *
- * Sized to keep refs SHORT, and the first attempt at that reasoned about the wrong axis. It bounded
- * how many navigations it took to reach seven digits and concluded "a hundred" — but the cost is not
- * paid at seven digits, it is paid at every digit, on every ref, in every snapshot and every error
- * message, on every turn. At 10,000 the SECOND document already mints five-digit refs.
- *
- * Measured on one unchanged three-element page across a session: 61 tokens on the first document,
- * 64 after a reload, 65 later — +6.5% for the same page, entirely in ref width. The benchmark saw the
- * same thing as a ~4% rise in average observation cost, which is what a benchmark is for.
- *
- * So the block is small. A document claims another one when it outmints this, which costs one more
- * storage write and is exactly proportional: a page with thousands of elements has a long snapshot
- * anyway, and a small page — the common case, and the one an agent drives repeatedly — keeps
- * three-digit refs across dozens of navigations.
- */
-export const REF_BLOCK = 100;
-/** The reserved-block high-water mark, or 0 when storage is unavailable or its value is junk. */
-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; // a sandboxed iframe throws on access; a session must still start
-    }
-}
-export class RefRegistry {
-    #toRef = new WeakMap();
-    #fromRef = new Map();
-    #storage;
-    #seq = 0;
-    /** The end of the block currently reserved. Minting past it claims the next one. */
-    #reserved = 0;
-    #mintsSinceSweep = 0;
-    /**
-     * The highest number handed out before the last hot update was applied, or 0 while none has been.
-     *
-     * A watermark rather than a per-ref stamp: the sequence never restarts within a document, so one
-     * number separates "minted before the code changed" from "minted after it" for every ref at once.
-     * The alternative — an epoch on every map entry — is bookkeeping paid on every mint for an answer
-     * needed only on the rare refusal.
-     */
-    #editedAtSeq = 0;
-    /**
-     * Storage is injected rather than read from the global for the same reason the clock is: it is an
-     * ambient dependency that decides behaviour, and the cross-document property is untestable if the
-     * only way to get a second document is to actually navigate.
-     */
-    constructor(storage = () => globalThis.sessionStorage) {
-        this.#storage = storage;
-    }
-    /** Read the tab's high-water mark and claim the next block, BEFORE any of it is handed out. */
-    #reserve() {
-        let store;
-        try {
-            store = this.#storage();
-        }
-        catch {
-            store = undefined; // hostile storage: no cross-document guarantee, but the session still starts
-        }
-        const base = Math.max(readBase(store), this.#seq);
-        this.#reserved = base + REF_BLOCK;
-        try {
-            store?.setItem(REF_BASE_KEY, String(this.#reserved));
-        }
-        catch {
-            /* same: never block a mint on storage */
-        }
-        // Claimed on the FIRST mint, not at unload — a page that crashes, is killed, or navigates away
-        // without firing unload has still permanently spent its numbers.
-        this.#seq = base;
-    }
-    /** How many reverse entries are currently retained. Exposed so the bound can be asserted. */
-    get size() {
-        return this.#fromRef.size;
-    }
-    /** O(1): drop the least-recently-minted reverse entry. Map iterates in insertion order, so the front
-     *  is the oldest. A still-live element whose entry is dropped re-registers on its next refFor. */
-    #evictOldest() {
-        const oldest = this.#fromRef.keys().next();
-        if (oldest.done !== true)
-            this.#fromRef.delete(oldest.value);
-    }
-    /** Full pass: drop every entry whose element has been collected or detached (frees genuinely dead
-     *  bookkeeping), then any remaining excess by age. Amortized — called once per SWEEP_EVERY_MINTS. */
-    #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();
-    }
-    /**
-     * A hot update just replaced modules in this document: every ref handed out so far was minted
-     * against the DOM the previous version of that code produced.
-     *
-     * Only the boundary is recorded. Nothing is evicted — a hot update is not a navigation, and most
-     * of the page survives one, so refs minted before it very often still resolve. This exists so the
-     * ones that DON'T can say why.
-     */
-    markEdited() {
-        this.#editedAtSeq = this.#seq;
-    }
-    /** Was this ref handed out before the last hot update? False while no update has been observed. */
-    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;
-    }
-    /** Get the existing ref for an element, or mint a new one. */
-    refFor(el) {
-        const existing = this.#toRef.get(el);
-        if (existing !== undefined) {
-            // Re-register if this element's entry was evicted while it was off the agent's radar. Without
-            // this, an element that is still on the page could hold a ref that no longer resolves — the
-            // eviction would surface as "element not found", which is a wrong answer rather than a slow one.
-            // Either way, TOUCH it to the recent end (LRU): an element being surfaced right now must not be
-            // the oldest-drop victim of a mint storm before the agent gets to act on it.
-            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));
-        // Keep bounded cheaply on every mint; run the full dead-entry sweep only periodically.
-        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 a ref back to its element, or null if it's gone/detached.
-     *
-     * Takes a plain `string` ON PURPOSE: this is the untrusted-input path — the ref comes from the agent
-     * over the wire, and a miss is answered with null rather than an error. Requiring a branded Ref here
-     * would force a meaningless cast at every wire boundary and buy nothing; the brand's value is on the
-     * MINT (refFor) so our own code cannot pass, say, a sessionId where a handle is expected.
-     */
-    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;
-        }
-        // LRU touch: a ref the agent just resolved is in ACTIVE use — move it to the most-recent end so an
-        // oldest-drop eviction between this resolve and the follow-up act can't reclaim it and turn a live
-        // element into a false "ref no longer resolves". O(1) — Map preserves insertion order.
-        this.#fromRef.delete(ref);
-        this.#fromRef.set(ref, weak);
-        return el;
-    }
-}
-/** Process-wide registry shared by snapshot, query, and the action executor. */
-export const refs = new RefRegistry();