@reticlehq/browser 2.14.0 → 3.1.0

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

@@ -16,4 +16,12 @@ export declare function clickGeometry(el: HTMLElement): ClickGeometry;
 export declare function firePointer(el: Element, type: string, relatedTarget?: EventTarget | null): void;
 export declare function firePointerNonBubbling(el: Element, type: string, relatedTarget?: EventTarget | null): void;
 export declare function dragElement(source: HTMLElement, target: HTMLElement | null, data: unknown): Promise<boolean>;
+export declare function fireTapSequence(el: HTMLElement, hold: {
+    ms: number;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+} | undefined): Promise<{
+    prevented: boolean;
+    heldMs: number;
+}>;
 export {};

package/dist/actions/actions-dom.js

@@ -1,7 +1,7 @@
-import { refs } from '../dom/refs.js';
+import { refs } from '../dom/addressing/refs.js';
 import { hitTestOccluder } from '../dom/occlusion.js';
-import { nativeFrame } from '../timers/native-timers.js';
-import { asSyntheticInput } from './synthetic-input.js';
+import { nativeFrame } from '../timers/native/native-timers.js';
+import { asSyntheticInput } from './synthetic/synthetic-input.js';
 export const NO_GEOMETRY = {
     occluded: false,
     occludedBy: null,
@@ -176,3 +176,70 @@ export async function dragElement(source, target, data) {
     }
     return dropPrevented;
 }
+export async function fireTapSequence(el, hold) {
+    const touches = touchListFor(el);
+    firePointerTouch(el, 'pointerdown');
+    asSyntheticInput(() => el.dispatchEvent(makeTouchEvent('touchstart', touches)));
+    if (el.tabIndex >= 0 && 'function' === typeof el.focus)
+        el.focus();
+    let heldMs = 0;
+    if (hold !== undefined && hold.ms > 0) {
+        const started = hold.now();
+        await hold.sleep(hold.ms);
+        heldMs = hold.now() - started;
+    }
+    asSyntheticInput(() => el.dispatchEvent(makeTouchEvent('touchend', [])));
+    firePointerTouch(el, 'pointerup');
+    const clicked = asSyntheticInput(() => el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true })));
+    return { prevented: !clicked, heldMs };
+}
+function firePointerTouch(el, type) {
+    asSyntheticInput(() => {
+        if ('function' === typeof PointerEvent) {
+            el.dispatchEvent(new PointerEvent(type, {
+                bubbles: true,
+                cancelable: true,
+                pointerType: 'touch',
+                isPrimary: true,
+                width: 23,
+                height: 23,
+            }));
+            return;
+        }
+        el.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true }));
+    });
+}
+function touchListFor(el) {
+    if ('function' !== typeof Touch || 'function' !== typeof el.getBoundingClientRect)
+        return [];
+    const rect = el.getBoundingClientRect();
+    try {
+        return [
+            new Touch({
+                identifier: 0,
+                target: el,
+                clientX: rect.left + rect.width / 2,
+                clientY: rect.top + rect.height / 2,
+            }),
+        ];
+    }
+    catch {
+        return [];
+    }
+}
+function makeTouchEvent(type, touches) {
+    if ('function' === typeof TouchEvent) {
+        try {
+            return new TouchEvent(type, {
+                bubbles: true,
+                cancelable: true,
+                touches,
+                targetTouches: touches,
+                changedTouches: touches,
+            });
+        }
+        catch {
+        }
+    }
+    return new Event(type, { bubbles: true, cancelable: true });
+}

package/dist/actions/actions-press.d.ts

@@ -8,3 +8,7 @@ export declare function pressModifiers(args: Record<string, unknown>): {
 export declare function pressCode(args: Record<string, unknown>, key: string): string;
 export declare function focusedOrDocument(): HTMLElement;
 export declare function isReflessDocumentPress(ref: string, action: string, args: Record<string, unknown>): boolean;
+export declare function pressKeys(args: Record<string, unknown>): string[];
+export declare function holdKey(el: HTMLElement, key: string, code: string, mods: Record<string, boolean>, ms: number): Promise<void>;
+export declare function pressCombo(el: HTMLElement, keys: readonly string[], mods: Record<string, boolean>, holdMs: number): Promise<boolean>;
+export declare const ZOOM_NEEDS_REAL_BROWSER_MSG: string;

package/dist/actions/actions-press.js

@@ -1,4 +1,7 @@
 import { ActionType, isGlobalPress, pressKeyFromArgs } from '@reticlehq/core';
+import { asSyntheticInput } from './synthetic/synthetic-input.js';
+import { nativeSetTimeout } from '../timers/native/native-timers.js';
+const sleep = (ms) => new Promise((r) => nativeSetTimeout(r, ms));
 import { isHtmlElement } from '../dom/realm.js';
 function asString(value, fallback = '') {
     return 'string' === typeof value ? value : fallback;
@@ -75,3 +78,46 @@ export function focusedOrDocument() {
 export function isReflessDocumentPress(ref, action, args) {
     return 0 === ref.length && isGlobalPress(args) && ActionType.PRESS === action;
 }
+export function pressKeys(args) {
+    const raw = args['keys'];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((k) => asString(k)).filter((k) => k.length > 0);
+}
+const KEY_REPEAT_MS = 33;
+const KEY_REPEAT_DELAY_MS = 500;
+export async function holdKey(el, key, code, mods, ms) {
+    const started = Date.now();
+    if (ms > KEY_REPEAT_DELAY_MS)
+        await sleep(KEY_REPEAT_DELAY_MS);
+    while (Date.now() - started < ms) {
+        asSyntheticInput(() => el.dispatchEvent(new KeyboardEvent('keydown', {
+            key,
+            code,
+            bubbles: true,
+            cancelable: true,
+            repeat: true,
+            ...mods,
+        })));
+        await sleep(Math.min(KEY_REPEAT_MS, Math.max(0, ms - (Date.now() - started))));
+    }
+}
+export async function pressCombo(el, keys, mods, holdMs) {
+    let prevented = false;
+    for (const key of keys) {
+        const code = pressCode({}, key);
+        const ok = asSyntheticInput(() => el.dispatchEvent(new KeyboardEvent('keydown', { key, code, bubbles: true, cancelable: true, ...mods })));
+        if (!ok)
+            prevented = true;
+    }
+    if (holdMs > 0)
+        await sleep(holdMs);
+    for (const key of [...keys].reverse()) {
+        const code = pressCode({}, key);
+        asSyntheticInput(() => el.dispatchEvent(new KeyboardEvent('keyup', { key, code, bubbles: true, ...mods })));
+    }
+    return prevented;
+}
+export const ZOOM_NEEDS_REAL_BROWSER_MSG = 'cannot zoom from inside the page — CSS zoom changes how it LOOKS without changing the layout ' +
+    'viewport, visualViewport or media queries, so a layout that breaks at 200% would be reported as ' +
+    'checked and passing. Drive a real browser (reticle drive <url>, or reticle_lease) and zoom there.';

package/dist/actions/actions.d.ts

@@ -35,6 +35,7 @@ interface ActionResult {
     warning?: string;
 }
 export declare const MAX_HOLD_MS = 30000;
+export declare const ZOOM_NEEDS_REAL_BROWSER_MSG: string;
 export declare function executeAction(ref: string, action: string, args?: Record<string, unknown>): Promise<ActionResult>;
 export declare function dispatchWebMcp(tool: string, params: Record<string, unknown>, confirmDangerous?: boolean): Promise<unknown>;
 export interface ActionStep {

package/dist/actions/actions.js

@@ -1,14 +1,14 @@
 import { ActionType, ActionWarning, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, NATIVE_INPUT_ARG, SettleReason, } from '@reticlehq/core';
-import { asSyntheticInput } from './synthetic-input.js';
-import { echoRef, refs } from '../dom/refs.js';
+import { asSyntheticInput } from './synthetic/synthetic-input.js';
+import { echoRef, refs } from '../dom/addressing/refs.js';
 import { dangerousActionContext, requiresDangerousConfirmation, submitControlFor, } from './danger-context.js';
 import { assertEditable, assertNotRichText, setNativeValue } from './value-input.js';
 import { getAccessibleName, getRole, isVisible, getStates } from '../dom/a11y.js';
-import { elementHasHoverHandlers, identifyComponent } from '../registry/adapters.js';
+import { elementHasHoverHandlers, identifyComponent } from '../registry/stores/adapters.js';
 import { isForm, isHtmlElement, isInput, isSelect, isTextArea } from '../dom/realm.js';
-import { nativeSetTimeout, settle } from '../timers/native-timers.js';
+import { nativeSetTimeout, settle } from '../timers/native/native-timers.js';
 import { AppearedText } from './appeared-text.js';
-import { focusedOrDocument, isReflessDocumentPress, pressCode, pressKey, pressModifiers, } from './actions-press.js';
+import { focusedOrDocument, isReflessDocumentPress, pressCode, pressKey, pressModifiers, pressKeys, holdKey, pressCombo, } from './actions-press.js';
 function asString(value, fallback = '') {
     return 'string' === typeof value ? value : fallback;
 }
@@ -124,7 +124,8 @@ function assertActionAllowed(el, action, args) {
         throw new Error(`potentially destructive action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
     }
 }
-import { NO_GEOMETRY, fireClickSequence, clickGeometry, firePointer, firePointerNonBubbling, dragElement, } from './actions-dom.js';
+import { NO_GEOMETRY, fireClickSequence, fireTapSequence, clickGeometry, firePointer, firePointerNonBubbling, dragElement, } from './actions-dom.js';
+import { scrollFrom } from './scroll.js';
 function enabledOf(el) {
     return !getStates(el).includes(ElementState.DISABLED);
 }
@@ -151,8 +152,18 @@ async function dispatchFor(el, action, args) {
         const hold = clampHold(args['holdMs']);
         return await fireClickSequence(el, 0 === hold ? undefined : { ms: hold, sleep, now: () => Date.now() });
     }
+    if (ActionType.TAP === action) {
+        const hold = clampHold(args['holdMs']);
+        return await fireTapSequence(el, 0 === hold ? undefined : { ms: hold, sleep, now: () => Date.now() });
+    }
     return { prevented: await dispatchOther(el, action, args), heldMs: 0 };
 }
+export const ZOOM_NEEDS_REAL_BROWSER_MSG = 'cannot zoom from inside the page — CSS zoom changes how it LOOKS without changing the layout ' +
+    'viewport, visualViewport or media queries, so a layout that breaks at 200% would be reported as ' +
+    'checked and passing. Drive a real browser (reticle drive <url>, or reticle_lease) and zoom there.';
+function asFiniteNumber(raw) {
+    return 'number' === typeof raw && Number.isFinite(raw) ? raw : undefined;
+}
 async function dispatchOther(el, action, args) {
     switch (action) {
         case ActionType.DBLCLICK:
@@ -253,16 +264,31 @@ async function dispatchOther(el, action, args) {
             return false;
         }
         case ActionType.PRESS: {
+            const mods = pressModifiers(args);
+            const combo = pressKeys(args);
+            if (combo.length > 0)
+                return await pressCombo(el, combo, mods, clampHold(args['holdMs']));
             const key = pressKey(args);
             const code = pressCode(args, key);
-            const mods = pressModifiers(args);
             const down = asSyntheticInput(() => el.dispatchEvent(new KeyboardEvent('keydown', { key, code, bubbles: true, cancelable: true, ...mods })));
+            const hold = clampHold(args['holdMs']);
+            if (hold > 0)
+                await holdKey(el, key, code, mods, hold);
             asSyntheticInput(() => el.dispatchEvent(new KeyboardEvent('keyup', { key, code, bubbles: true, ...mods })));
             return !down;
         }
         case ActionType.SCROLL_INTO_VIEW:
             el.scrollIntoView();
             return false;
+        case ActionType.ZOOM:
+            throw new Error(ZOOM_NEEDS_REAL_BROWSER_MSG);
+        case ActionType.SCROLL: {
+            const dy = asFiniteNumber(args['dy']);
+            const dx = asFiniteNumber(args['dx']);
+            const fraction = asFiniteNumber(args['fraction']);
+            scrollFrom(el, dy, fraction, dx);
+            return false;
+        }
         case ActionType.UPLOAD: {
             if (!isInput(el) || el.type !== 'file') {
                 throw new Error('upload target must be a <input type="file">');
@@ -302,6 +328,12 @@ async function dispatchOther(el, action, args) {
             throw new Error(`unknown action '${action}'`);
     }
 }
+function asSettleBudget(raw) {
+    if ('number' !== typeof raw || !Number.isFinite(raw))
+        return undefined;
+    return Math.max(0, Math.min(raw, FRAME_BUDGET_MS_CEILING));
+}
+const FRAME_BUDGET_MS_CEILING = 200;
 export async function executeAction(ref, action, args = {}) {
     const named = 0 < ref.length;
     const el = isReflessDocumentPress(ref, action, args) ? focusedOrDocument() : requireElement(ref);
@@ -336,7 +368,8 @@ export async function executeAction(ref, action, args = {}) {
         heldMs = outcome.heldMs;
     }
     finally {
-        const outcome = await settle();
+        const budget = asSettleBudget(args['settleMs']);
+        const outcome = await settle(budget);
         settled = outcome.settled;
         settleReason = outcome.settled ? null : SettleReason.TIMEOUT;
         obs.disconnect();

package/dist/actions/appeared-text.js

@@ -6,6 +6,10 @@ const HAS_LETTER = /\p{L}/u;
 function saysSomething(text) {
     return HAS_LETTER.test(text);
 }
+const MAX_MESSAGE_ELEMENTS = 3;
+function isRenderedView(node) {
+    return node instanceof Element && node.querySelectorAll('*').length > MAX_MESSAGE_ELEMENTS;
+}
 export class AppearedText {
     #seen = new Set();
     #length = 0;
@@ -20,6 +24,8 @@ export class AppearedText {
             for (const node of record.addedNodes) {
                 if (this.#full())
                     return;
+                if (isRenderedView(node))
+                    continue;
                 const owner = TEXT_NODE === node.nodeType ? node.parentElement : elementOf(node);
                 this.#add(node.textContent, owner);
             }

package/dist/actions/scroll.d.ts

@@ -4,6 +4,13 @@ interface ScrollResult {
     scrollHeight: number;
     clientHeight: number;
     atEnd: boolean;
+    atStart: boolean;
+    scrollLeft: number;
+    scrollWidth: number;
+    clientWidth: number;
+    atLeftEnd: boolean;
+    atRightEnd: boolean;
 }
-export declare function scrollContainer(ref: string | undefined, dy: number | undefined, fraction?: number): ScrollResult;
+export declare function scrollContainer(ref: string | undefined, dy: number | undefined, fraction?: number, dx?: number): ScrollResult;
+export declare function scrollFrom(base: Element | undefined, dy: number | undefined, fraction?: number, dx?: number): ScrollResult;
 export {};

package/dist/actions/scroll.js

@@ -1,36 +1,54 @@
-import { refs } from '../dom/refs.js';
+import { refs } from '../dom/addressing/refs.js';
 const FALLBACK_STEP_PX = 400;
 const VIEWPORT_FRACTION = 0.8;
-function nearestScrollable(el) {
+function nearestScrollable(el, axis) {
     let cur = el;
     while (cur !== null && cur !== document.body) {
-        const oy = getComputedStyle(cur).overflowY;
-        if (('auto' === oy || 'scroll' === oy) && cur.scrollHeight > cur.clientHeight)
+        const style = getComputedStyle(cur);
+        const overflow = 'x' === axis ? style.overflowX : style.overflowY;
+        const scrollable = 'x' === axis ? cur.scrollWidth > cur.clientWidth : cur.scrollHeight > cur.clientHeight;
+        if (('auto' === overflow || 'scroll' === overflow) && scrollable)
             return cur;
         cur = cur.parentElement;
     }
     return document.scrollingElement ?? document.documentElement;
 }
-export function scrollContainer(ref, dy, fraction) {
+export function scrollContainer(ref, dy, fraction, dx) {
     const base = ref !== undefined ? refs.resolve(ref) : null;
-    const target = base instanceof Element
-        ? nearestScrollable(base)
+    return scrollFrom(base instanceof Element ? base : undefined, dy, fraction, dx);
+}
+export function scrollFrom(base, dy, fraction, dx) {
+    const axis = dx !== undefined && dx !== 0 && (dy === undefined || 0 === dy) ? 'x' : 'y';
+    const target = base !== undefined
+        ? nearestScrollable(base, axis)
         : (document.scrollingElement ?? document.documentElement);
     const before = target.scrollTop;
+    const beforeLeft = target.scrollLeft;
     if (fraction !== undefined && fraction >= 0 && fraction <= 1) {
         target.scrollTop = Math.round(target.scrollHeight * fraction);
     }
     else {
-        const step = dy ?? (Math.round(target.clientHeight * VIEWPORT_FRACTION) || FALLBACK_STEP_PX);
-        target.scrollTop = before + step;
+        if (dx !== undefined && dx !== 0)
+            target.scrollLeft = beforeLeft + dx;
+        if (dx === undefined || (dy !== undefined && 0 !== dy)) {
+            const step = dy ?? (Math.round(target.clientHeight * VIEWPORT_FRACTION) || FALLBACK_STEP_PX);
+            target.scrollTop = before + step;
+        }
     }
     target.dispatchEvent(new Event('scroll', { bubbles: false }));
     const after = target.scrollTop;
+    const afterLeft = target.scrollLeft;
     return {
-        scrolled: after !== before,
+        scrolled: after !== before || afterLeft !== beforeLeft,
         scrollTop: after,
         scrollHeight: target.scrollHeight,
         clientHeight: target.clientHeight,
         atEnd: after + target.clientHeight >= target.scrollHeight - 1,
+        atStart: after <= 1,
+        scrollLeft: afterLeft,
+        scrollWidth: target.scrollWidth,
+        clientWidth: target.clientWidth,
+        atLeftEnd: afterLeft <= 1,
+        atRightEnd: afterLeft + target.clientWidth >= target.scrollWidth - 1,
     };
 }

package/dist/commands/commands.js

@@ -1,17 +1,18 @@
 import { ActionType, ComponentStateReason, DANGEROUS_ACTION_CONFIRM_ARG, ElementQuerySchema, ReticleCommand, SnapshotMode, TRANSPORT_LIMITS, selectPath, capDepth, } from '@reticlehq/core';
 import { buildSnapshot } from '../dom/snapshot.js';
+import { paintContextOf } from '../dom/paint-context.js';
 import { matchQuery, runQuery } from '../dom/query.js';
 import { executeAction, executeSequence, dispatchWebMcp, } from '../actions/actions.js';
 import { describe } from '../dom/a11y.js';
-import { documentHasSourceStamps, sourceFor, formatSource } from '../dom/source.js';
+import { documentHasSourceStamps, sourceFor, formatSource } from '../dom/addressing/source.js';
 import { themeReport } from '../dom/theme.js';
-import { refs } from '../dom/refs.js';
+import { refs } from '../dom/addressing/refs.js';
 import { editEpoch } from '../edit-epoch.js';
 import { isButton, isInput } from '../dom/realm.js';
 import { hitTestOccluder } from '../dom/occlusion.js';
 import { readStorage } from '../observers/storage.js';
 import { captureDesktopWindow } from '../dom/desktop-capture.js';
-import { identifyComponent, readComponentState } from '../registry/adapters.js';
+import { identifyComponent, readComponentState } from '../registry/stores/adapters.js';
 import { readStoresWithTruncation, readStoresRaw, storeNames } from '../registry/stores.js';
 import { sanitizeWithReport } from '../security/serialization.js';
 import { getCapabilities } from '../registry/capabilities.js';
@@ -84,10 +85,16 @@ function inspect(ref) {
         scrollHeight: el.scrollHeight,
         clientHeight: el.clientHeight,
         overflowY: cs?.overflowY ?? 'visible',
+        scrollLeft: el.scrollLeft,
+        scrollWidth: el.scrollWidth,
+        clientWidth: el.clientWidth,
+        overflowX: cs?.overflowX ?? 'visible',
     };
+    const paintContext = paintContextOf(el);
     return {
         ...describe(el),
         ...(source !== undefined ? { source } : {}),
+        ...(paintContext.length > 0 ? { paintContext } : {}),
         ...(sourceUnavailable !== undefined ? { sourceUnavailable } : {}),
         tag: el.tagName.toLowerCase(),
         href: el.getAttribute('href') ?? undefined,

package/dist/dom/a11y.js

@@ -1,9 +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';
+import { formatSource, sourceFromDom } from './addressing/source.js';
 const NAME_FROM_CONTENT = new Set([
     'button',
     'link',

package/dist/dom/desktop-capture.js

@@ -1,5 +1,5 @@
 import { RETICLE_IPC_GLOBAL, RETICLE_TAURI_CAPTURE_COMMAND, VisualReason } from '@reticlehq/core';
-import { nativeFrame } from '../timers/native-timers.js';
+import { nativeFrame } from '../timers/native/native-timers.js';
 import { RETICLE_OVERLAY } from './dom-ignore.js';
 const FULL_PAGE_UNSUPPORTED_MARKER = VisualReason.FULL_PAGE_UNSUPPORTED;
 const RECOGNISED_MARKERS = [

package/dist/dom/dom-ignore.js

@@ -1,4 +1,4 @@
-export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark],[data-reticle-blocker]';
+export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark],[data-reticle-blocker],[data-reticle-tour]';
 const DEV_OVERLAYS = '[data-agentation],#__next-build-watcher,nextjs-portal,[data-nextjs-dialog],[data-nextjs-toast]';
 let extraIgnore = '';
 let presenterVisible = false;

package/dist/dom/occlusion.js

@@ -1,13 +1,39 @@
 import { isReticleUi } from './dom-ignore.js';
+const SAMPLE_POINTS = [
+    [0.5, 0.5],
+    [0.25, 0.25],
+    [0.75, 0.25],
+    [0.25, 0.75],
+    [0.75, 0.75],
+];
+const BLOCKED_MAJORITY = 3;
 export function hitTestOccluder(el, rect) {
     if (0 === rect.width || 0 === rect.height)
         return null;
     const doc = el.ownerDocument;
     if (typeof doc.elementFromPoint !== 'function')
         return null;
-    const top = doc.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
-    if (null === top || isReticleUi(top))
-        return null;
-    const lands = top === el || el.contains(top) || top.contains(el);
-    return lands ? null : top;
+    const withStack = doc;
+    const topAt = (x, y) => {
+        const found = withStack.elementsFromPoint?.(x, y) ?? [doc.elementFromPoint(x, y)];
+        return found.find((c) => null !== c && !isReticleUi(c)) ?? null;
+    };
+    const blockers = new Map();
+    for (const [fx, fy] of SAMPLE_POINTS) {
+        const top = topAt(rect.left + rect.width * fx, rect.top + rect.height * fy);
+        if (null === top)
+            continue;
+        if (top === el || el.contains(top) || top.contains(el))
+            continue;
+        blockers.set(top, (blockers.get(top) ?? 0) + 1);
+    }
+    let worst = null;
+    let worstCount = 0;
+    for (const [element, count] of blockers) {
+        if (count > worstCount) {
+            worst = element;
+            worstCount = count;
+        }
+    }
+    return worstCount >= BLOCKED_MAJORITY ? worst : null;
 }

package/dist/dom/paint-context.d.ts

@@ -0,0 +1,6 @@
+export interface PaintContextEntry {
+    readonly on: string;
+    readonly property: string;
+    readonly value: string;
+}
+export declare function paintContextOf(el: Element): PaintContextEntry[];

package/dist/dom/paint-context.js

@@ -0,0 +1,38 @@
+const PAINT_PROPERTIES = [
+    'filter',
+    'opacity',
+    'transform',
+    'mix-blend-mode',
+    'backdrop-filter',
+];
+const INERT = {
+    filter: 'none',
+    opacity: '1',
+    transform: 'none',
+    'mix-blend-mode': 'normal',
+    'backdrop-filter': 'none',
+};
+function describeElement(el) {
+    if (el.id.length > 0)
+        return `#${el.id}`;
+    const cls = el.getAttribute('class');
+    if (cls !== null && cls.trim().length > 0)
+        return `.${cls.trim().split(/\s+/).join('.')}`;
+    return el.tagName.toLowerCase();
+}
+export function paintContextOf(el) {
+    const view = el.ownerDocument.defaultView;
+    if (null === view)
+        return [];
+    const found = [];
+    for (let node = el; node !== null && node !== el.ownerDocument.documentElement; node = node.parentElement) {
+        const style = view.getComputedStyle(node);
+        for (const property of PAINT_PROPERTIES) {
+            const value = style.getPropertyValue(property);
+            if (value.length > 0 && value !== INERT[property]) {
+                found.push({ on: describeElement(node), property, value });
+            }
+        }
+    }
+    return found;
+}

package/dist/dom/query.js

@@ -5,8 +5,8 @@ import { getAccessibleName, getRole, describe, getStates, isInViewport, isVisibl
 import { isIgnored, isReticleOverlay } from './dom-ignore.js';
 import { isSensitiveKey } from '../security/serialization.js';
 import { declaredTestids } from '../registry/capabilities.js';
-import { identifyComponent } from '../registry/adapters.js';
-import { refs } from './refs.js';
+import { identifyComponent } from '../registry/stores/adapters.js';
+import { refs } from './addressing/refs.js';
 const TESTID_ATTR = 'data-testid';
 const SOURCE_ATTR = DATA_RETICLE_SOURCE_ATTR;
 const MAX_PRESENT_TESTIDS = 12;

package/dist/dom/snapshot.js

@@ -2,7 +2,7 @@ import { ElementState, SnapshotMode } from '@reticlehq/core';
 import { capturedRootOf } from './shadow-registry.js';
 import { isFrame } from './realm.js';
 import { getAccessibleName, getRole, getStates, getValue, isVisible } from './a11y.js';
-import { refs } from './refs.js';
+import { refs } from './addressing/refs.js';
 import { isIgnored, isReticleOverlay } from './dom-ignore.js';
 const INTERACTIVE = new Set([
     'button',

package/dist/edit-epoch.d.ts

@@ -1,4 +1,4 @@
-import { type RefRegistry } from './dom/refs.js';
+import { type RefRegistry } from './dom/addressing/refs.js';
 export declare class EditEpoch {
     #private;
     constructor(registry: RefRegistry);

package/dist/edit-epoch.js

@@ -1,5 +1,5 @@
 import { NO_EDITS_OBSERVED } from '@reticlehq/core';
-import { echoRef, refs } from './dom/refs.js';
+import { echoRef, refs } from './dom/addressing/refs.js';
 const HOT_UPDATE_APPLIED = 'vite:afterUpdate';
 const MAX_NAMED_FILES = 3;
 const STALE_REF_REFUSAL = 'no longer resolves to an element';

package/dist/index.d.ts

@@ -1,11 +1,10 @@
-import { Reticle } from './reticle.js';
-export declare const reticle: Reticle;
+export { reticle } from './reticle-singleton.js';
 export { Reticle } from './reticle.js';
 export type { ReticleConnectOptions } from './reticle.js';
 export { SESSION_AUTO } from '@reticlehq/core';
 export { setIgnoreSelectors } from './dom/dom-ignore.js';
-export { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/adapters.js';
-export type { ReticleAdapter, ComponentInfo, ComponentSource } from './registry/adapters.js';
+export { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/stores/adapters.js';
+export type { ReticleAdapter, ComponentInfo, ComponentSource } from './registry/stores/adapters.js';
 export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, sourceOwner, markAdapterSource, } from './registry/stores.js';
 export type { StoreGetter, StoreLike, StoreSubscribe } from './registry/stores.js';
 export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, recoilStore, svelteStore, piniaStore, pushStore, } from './registry/store-adapters.js';
@@ -23,6 +22,6 @@ export type { ChartReport, ChartFinding, CanvasChartData } from './dom/chart.js'
 export { matchQuery, runQuery } from './dom/query.js';
 export { executeAction, executeSequence } from './actions/actions.js';
 export { describe, getRole, getAccessibleName, getStates, isVisible } from './dom/a11y.js';
-export { refs, RefRegistry } from './dom/refs.js';
+export { refs, RefRegistry } from './dom/addressing/refs.js';
 export { Annotator, installAnnotator, type AnnotatorDeps } from './review/annotator.js';
 export { resolveMarkAnchor, type MarkAnchor } from './review/mark-anchor.js';

package/dist/index.js

@@ -1,10 +1,8 @@
-import { Reticle } from './reticle.js';
-const globalStore = globalThis;
-export const reticle = (globalStore.__reticleInstance ??= new Reticle());
+export { reticle } from './reticle-singleton.js';
 export { Reticle } from './reticle.js';
 export { SESSION_AUTO } from '@reticlehq/core';
 export { setIgnoreSelectors } from './dom/dom-ignore.js';
-export { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/adapters.js';
+export { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/stores/adapters.js';
 export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, sourceOwner, markAdapterSource, } from './registry/stores.js';
 export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, recoilStore, svelteStore, piniaStore, pushStore, } from './registry/store-adapters.js';
 export { registerCapabilities, getCapabilities, hasCapabilities, setCapabilitiesListener, } from './registry/capabilities.js';
@@ -16,6 +14,6 @@ export { inspectChart, canvasChartData } from './dom/chart.js';
 export { matchQuery, runQuery } from './dom/query.js';
 export { executeAction, executeSequence } from './actions/actions.js';
 export { describe, getRole, getAccessibleName, getStates, isVisible } from './dom/a11y.js';
-export { refs, RefRegistry } from './dom/refs.js';
+export { refs, RefRegistry } from './dom/addressing/refs.js';
 export { Annotator, installAnnotator } from './review/annotator.js';
 export { resolveMarkAnchor } from './review/mark-anchor.js';

package/dist/observers/animation.js

@@ -1,5 +1,5 @@
 import { EventType } from '@reticlehq/core';
-import { refs } from '../dom/refs.js';
+import { refs } from '../dom/addressing/refs.js';
 import { isReticleOverlay } from '../dom/dom-ignore.js';
 export function installAnimation(emit) {
     const ac = new AbortController();

package/dist/observers/blind-spots.js

@@ -2,7 +2,7 @@ import { EventType, BlindSpotKind } from '@reticlehq/core';
 import { countUnmountedRows } from '../dom/virtualized.js';
 import { isCaptured } from '../dom/shadow-registry.js';
 import { sameOriginFrameBodies } from './frames.js';
-import { nativeClearTimeout, nativeSetTimeout } from '../timers/native-timers.js';
+import { nativeClearTimeout, nativeSetTimeout } from '../timers/native/native-timers.js';
 export function countClosedShadowRoots() {
     let count = 0;
     for (const el of document.querySelectorAll('*')) {