@reticlehq/browser 2.13.1 → 3.1.0

package/dist/dom/chart.d.ts

@@ -1,83 +1,22 @@
-/**
- * Chart inspection — the one dashboard surface Reticle could not previously see.
- *
- * A chart is where the store and the screen diverge most easily and most silently. Everything else on
- * a dashboard is text: a KPI card renders a number you can read, a table renders rows you can count,
- * and if the store disagrees with either, a state-vs-DOM comparison catches it. A chart renders
- * GEOMETRY — the data has been through a scale function into `points`/`d` coordinates — and geometry
- * is not text. `series` can be perfectly correct in the store while the polyline is blank, flat, or
- * full of NaN, and no reader of either side would notice.
- *
- * Two failure classes are worth detecting, and they are chosen because they are DECIDABLE from the
- * element alone — no baseline image, no per-library scale inversion, no false positives from a chart
- * that is merely ugly:
- *
- *  1. **Non-finite coordinates.** `NaN`/`Infinity` in a path reaches the DOM whenever the scale math
- *     divides by a zero range — an empty series, a single-point series, or min === max. The browser
- *     silently renders nothing. This is a genuine bug every time; there is no chart for which NaN
- *     coordinates are correct.
- *  2. **Degenerate geometry.** A chart element that exists but encloses no area: no points at all, or
- *     every point identical. Distinguishes "the chart is missing" (already catchable — the element is
- *     absent) from "the chart is present and empty", which looks healthy to a presence check and to a
- *     screenshot diff against a baseline that was also empty.
- *
- * Deliberately NOT attempted: comparing plotted geometry against the source data. That needs the
- * chart's scale functions inverted per library, is a large surface to get wrong, and `chartInstance`
- * below obsoletes it for the libraries people actually use — Chart.js and ECharts both hang their
- * instance off the canvas element, so their data can be read directly rather than reverse-engineered
- * from pixels.
- */
 export interface ChartFinding {
-    /** What is wrong, as a stable machine-readable kind. */
     kind: 'non-finite-coordinates' | 'empty-geometry' | 'degenerate-geometry';
-    /** The offending element's tag, so the agent can find it. */
     tag: string;
-    /** Which attribute carried the fault. */
     attr: string;
-    /** A short excerpt of the offending value — bounded; the full path can be thousands of chars. */
     sample: string;
 }
 export interface ChartReport {
-    /** How many data-bearing geometry elements were examined. */
     examined: number;
     findings: ChartFinding[];
-    /** True when a canvas is present, i.e. the geometry is NOT in the DOM and this report cannot see it. */
     canvas: boolean;
 }
-/**
- * Every number embedded in a geometry attribute. Path data interleaves single-letter drawing
- * commands with coordinate pairs, so this extracts numeric-looking tokens rather than parsing the
- * path grammar — the question here is only "is any coordinate non-finite", which does not need a
- * full parser.
- */
 export declare function geometryNumbers(value: string): number[];
-/** True when the attribute contains a coordinate the browser cannot render. */
 export declare function hasNonFiniteCoordinate(value: string): boolean;
-/** True when the geometry encloses no area — no coordinates, or every coordinate pair identical. */
 export declare function isDegenerate(value: string): boolean;
-/**
- * Inspect a subtree for chart geometry faults. Pure over the element — no events, no globals — so it
- * can back a tool call, an assertion, or a snapshot annotation without any of them owning it.
- */
 export declare function inspectChart(root: Element): ChartReport;
-/** The shape a canvas charting library hangs off its canvas element, once located. */
 export interface CanvasChartData {
     library: 'chartjs' | 'echarts';
-    /** The library's own data structure — series/datasets — read directly, not inferred from pixels. */
     data: unknown;
 }
-/**
- * Read the data behind a CANVAS chart.
- *
- * Canvas is the one place where "instrument from inside the app" is not merely cheaper than pixels but
- * is the only option at all: the chart is a bitmap, so the DOM shows an empty `<canvas>` and a
- * screenshot shows colours no assertion can interpret. Both major canvas libraries keep their live
- * instance reachable from the element — Chart.js via its registry, ECharts via a per-DOM lookup — so
- * the series data is READABLE rather than reverse-engineerable.
- *
- * Takes the globals as arguments rather than reaching for `window`, so this stays pure and testable
- * and the SDK never depends on either library being present.
- */
 export declare function canvasChartData(canvas: Element, globals: {
     Chart?: {
         getChart?: (el: Element) => {

package/dist/dom/chart.js

@@ -1,72 +1,24 @@
-/**
- * Chart inspection — the one dashboard surface Reticle could not previously see.
- *
- * A chart is where the store and the screen diverge most easily and most silently. Everything else on
- * a dashboard is text: a KPI card renders a number you can read, a table renders rows you can count,
- * and if the store disagrees with either, a state-vs-DOM comparison catches it. A chart renders
- * GEOMETRY — the data has been through a scale function into `points`/`d` coordinates — and geometry
- * is not text. `series` can be perfectly correct in the store while the polyline is blank, flat, or
- * full of NaN, and no reader of either side would notice.
- *
- * Two failure classes are worth detecting, and they are chosen because they are DECIDABLE from the
- * element alone — no baseline image, no per-library scale inversion, no false positives from a chart
- * that is merely ugly:
- *
- *  1. **Non-finite coordinates.** `NaN`/`Infinity` in a path reaches the DOM whenever the scale math
- *     divides by a zero range — an empty series, a single-point series, or min === max. The browser
- *     silently renders nothing. This is a genuine bug every time; there is no chart for which NaN
- *     coordinates are correct.
- *  2. **Degenerate geometry.** A chart element that exists but encloses no area: no points at all, or
- *     every point identical. Distinguishes "the chart is missing" (already catchable — the element is
- *     absent) from "the chart is present and empty", which looks healthy to a presence check and to a
- *     screenshot diff against a baseline that was also empty.
- *
- * Deliberately NOT attempted: comparing plotted geometry against the source data. That needs the
- * chart's scale functions inverted per library, is a large surface to get wrong, and `chartInstance`
- * below obsoletes it for the libraries people actually use — Chart.js and ECharts both hang their
- * instance off the canvas element, so their data can be read directly rather than reverse-engineered
- * from pixels.
- */
-/** Elements whose geometry encodes data. `line`/`circle`/`rect` are excluded: they are used for axes,
- *  gridlines and backgrounds, where a zero-extent element is normal rather than a fault. */
 const GEOMETRY_TAGS = ['path', 'polyline', 'polygon'];
-/** Attributes carrying that geometry, per tag. */
 const GEOMETRY_ATTRS = ['d', 'points'];
 const SAMPLE_MAX = 120;
-/**
- * Every number embedded in a geometry attribute. Path data interleaves single-letter drawing
- * commands with coordinate pairs, so this extracts numeric-looking tokens rather than parsing the
- * path grammar — the question here is only "is any coordinate non-finite", which does not need a
- * full parser.
- */
 export function geometryNumbers(value) {
     const tokens = value.match(/-?\d*\.?\d+(?:e[-+]?\d+)?|NaN|Infinity|-Infinity/gi) ?? [];
     return tokens.map((t) => Number(t));
 }
-/** True when the attribute contains a coordinate the browser cannot render. */
 export function hasNonFiniteCoordinate(value) {
-    // Checked textually first: `NaN` and `Infinity` survive into the attribute as literal words, and a
-    // string scan catches them without depending on how the number extractor tokenises.
     if (/NaN|Infinity/i.test(value))
         return true;
     return geometryNumbers(value).some((n) => !Number.isFinite(n));
 }
-/** True when the geometry encloses no area — no coordinates, or every coordinate pair identical. */
 export function isDegenerate(value) {
     const nums = geometryNumbers(value).filter((n) => Number.isFinite(n));
     if (0 === nums.length)
         return true;
-    // A polyline of one repeated point draws nothing. Compare pairs, not raw numbers, so a legitimately
-    // flat line (varying x, constant y) is NOT flagged — that is a real chart of constant data.
     const xs = nums.filter((_, i) => 0 === i % 2);
     const ys = nums.filter((_, i) => 1 === i % 2);
     const allSame = (arr) => arr.every((v) => v === arr[0]);
     return xs.length > 1 && allSame(xs) && allSame(ys);
 }
-/**
- * Inspect a subtree for chart geometry faults. Pure over the element — no events, no globals — so it
- * can back a tool call, an assertion, or a snapshot annotation without any of them owning it.
- */
 export function inspectChart(root) {
     const findings = [];
     let examined = 0;
@@ -93,18 +45,6 @@ export function inspectChart(root) {
     const canvas = root.querySelectorAll('canvas').length > 0;
     return { examined, findings, canvas };
 }
-/**
- * Read the data behind a CANVAS chart.
- *
- * Canvas is the one place where "instrument from inside the app" is not merely cheaper than pixels but
- * is the only option at all: the chart is a bitmap, so the DOM shows an empty `<canvas>` and a
- * screenshot shows colours no assertion can interpret. Both major canvas libraries keep their live
- * instance reachable from the element — Chart.js via its registry, ECharts via a per-DOM lookup — so
- * the series data is READABLE rather than reverse-engineerable.
- *
- * Takes the globals as arguments rather than reaching for `window`, so this stays pure and testable
- * and the SDK never depends on either library being present.
- */
 export function canvasChartData(canvas, globals) {
     const chartjs = globals.Chart?.getChart?.(canvas);
     if (chartjs !== undefined && chartjs !== null) {

package/dist/dom/desktop-capture.d.ts

@@ -1,35 +1,5 @@
-/**
- * Desktop screenshots, asked of the runtime that owns the window.
- *
- * A browser tab is captured through CDP. A desktop webview has no CDP endpoint, so the pixels have
- * to come from the shell — and the shell is the only party that can produce them CORRECTLY.
- *
- * Capturing a screen *region* instead was tried and rejected: it photographs the glass, so an app
- * window sitting behind the editor yields a picture of the editor, saved as a visual baseline that a
- * later diff would trust. A screenshot tool that can silently return another window's pixels is
- * worse than one that returns nothing — it manufactures exactly the false green Reticle exists to
- * eliminate. Electron's `webContents.capturePage()` reads the window's own backing store instead:
- * correct while occluded, correct while backgrounded, and needing no screen-recording permission.
- *
- * Both desktop runtimes can do this, each through its own shell API — `webContents.capturePage()` on
- * Electron, and on Tauri the platform's own webview snapshot (`WKWebView.takeSnapshot`, WebView2
- * `CapturePreview`, or WebKitGTK's snapshot). None of them reads the screen, so all stay correct with
- * the window occluded, hidden, or running headless with nothing on screen at all.
- *
- * The app opts in with one line in its main process (`@reticlehq/electron/main`) or one Rust command
- * (`reticle-tauri`). Absent that, this returns `{ ok: false }` and the tool reports no-provider
- * rather than guessing.
- */
 interface CaptureResult {
     ok: boolean;
-    /**
-     * Filesystem path of the captured PNG, written by the desktop shell.
-     *
-     * A path, not the image bytes: the SDK's transport sanitizer caps every string at 64KB, so a
-     * base64 PNG came back SILENTLY TRUNCATED and was saved as a "successful" screenshot that no
-     * decoder could read. The daemon and the app always share a machine here (the bridge is loopback),
-     * so handing over a path keeps the image off the event wire entirely.
-     */
     path?: string;
     reason?: string;
 }

package/dist/dom/desktop-capture.js

@@ -1,59 +1,12 @@
-/**
- * Desktop screenshots, asked of the runtime that owns the window.
- *
- * A browser tab is captured through CDP. A desktop webview has no CDP endpoint, so the pixels have
- * to come from the shell — and the shell is the only party that can produce them CORRECTLY.
- *
- * Capturing a screen *region* instead was tried and rejected: it photographs the glass, so an app
- * window sitting behind the editor yields a picture of the editor, saved as a visual baseline that a
- * later diff would trust. A screenshot tool that can silently return another window's pixels is
- * worse than one that returns nothing — it manufactures exactly the false green Reticle exists to
- * eliminate. Electron's `webContents.capturePage()` reads the window's own backing store instead:
- * correct while occluded, correct while backgrounded, and needing no screen-recording permission.
- *
- * Both desktop runtimes can do this, each through its own shell API — `webContents.capturePage()` on
- * Electron, and on Tauri the platform's own webview snapshot (`WKWebView.takeSnapshot`, WebView2
- * `CapturePreview`, or WebKitGTK's snapshot). None of them reads the screen, so all stay correct with
- * the window occluded, hidden, or running headless with nothing on screen at all.
- *
- * The app opts in with one line in its main process (`@reticlehq/electron/main`) or one Rust command
- * (`reticle-tauri`). Absent that, this returns `{ ok: false }` and the tool reports no-provider
- * rather than guessing.
- */
 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';
-/**
- * What a shell returns when it can photograph the viewport but not the whole scroll height.
- *
- * Only WebKitGTK can render a full document offscreen; `capturePage()` and `takeSnapshot` both give
- * what is composited. Downgrading silently would be the worst option available: the caller asked for
- * the content below the fold, would get an image without it, and would bank it as a baseline that a
- * later diff reports as matching. So the shells say so, and the tool reports the reason.
- */
 const FULL_PAGE_UNSUPPORTED_MARKER = VisualReason.FULL_PAGE_UNSUPPORTED;
-/**
- * Reasons a shell can name, in the order they are matched.
- *
- * The shell throws one of these rather than answering a bare null, because "nothing came back" was
- * covering three different problems at once: a window with no composited frame yet, a webContents
- * that had gone away, and any error at all. They need different responses from the reader, and the
- * tool reported them identically.
- */
 const RECOGNISED_MARKERS = [
     FULL_PAGE_UNSUPPORTED_MARKER,
     VisualReason.NOT_COMPOSITED,
 ];
 const TAURI_INTERNALS_GLOBAL = '__TAURI_INTERNALS__';
-/**
- * Tauri's capture path, used when no preload-installed channel exists.
- *
- * Electron can install `RETICLE_IPC_GLOBAL` from its preload, which runs before app code. Tauri has
- * no preload stage at all, so requiring the same global would mean every Tauri app hand-writing a
- * frontend shim — a setup step that silently yields "no screenshots" when forgotten. Invoking the
- * command directly removes the JavaScript side entirely: the app registers one Rust command and the
- * SDK finds it. Absent that command the invoke rejects, and this reports no-provider like any other.
- */
 function tauriCapture() {
     const internals = window[TAURI_INTERNALS_GLOBAL];
     if (typeof internals?.invoke !== 'function')
@@ -64,31 +17,9 @@ function tauriCapture() {
         return 'string' === typeof path ? path : null;
     };
 }
-/**
- * Take Reticle's own UI out of the shot, then put it back.
- *
- * The shell photographs the composited window, so anything Reticle mounted is IN the picture — and
- * the presenter panel is the worst possible thing to bank into a visual baseline, because it renders
- * live session state: an event tally, a log tail, a run badge. A baseline captured with it is a
- * baseline of Reticle's own UI as much as the app's, and the next `reticle_visual_diff` reports a
- * change that belongs entirely to the observer. That is measuring the instrument.
- *
- * Two frames, not one: the first lets the style change apply, the second lets the compositor present
- * it — capture before that and the shell photographs the pre-hide window anyway. Both are BOUNDED
- * frames, which is load-bearing rather than defensive: a headless Tauri window is hidden, and a
- * hidden webview never fires `requestAnimationFrame` at all, so a raw double-rAF here deadlocked
- * every capture until the command timed out at 8s. Restoration runs in a `finally`, so a capture
- * that throws still leaves the panel on screen for the human watching.
- */
 async function withReticleUiHidden(capture) {
-    // The SAME selector the snapshot layer already uses to keep Reticle's own DOM out of what the
-    // agent reads — the presenter panel, the cursor, the glow, and the annotator's "flag a bug"
-    // button. One definition: a root that leaked into snapshots once would otherwise leak into
-    // baselines the second time someone added one.
     const roots = [...document.querySelectorAll(RETICLE_OVERLAY)];
     const previous = roots.map((el) => el.style.visibility);
-    // `visibility`, not `display`: it keeps the element's box, so hiding cannot reflow the app
-    // underneath and change the very layout the screenshot is meant to record.
     for (const el of roots)
         el.style.visibility = 'hidden';
     try {
@@ -118,9 +49,6 @@ export async function captureDesktopWindow(fullPage = false) {
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
-        // Recognised markers are reported as the reason ITSELF, so the tool can branch on a closed
-        // vocabulary rather than on prose. Everything else keeps its own message: dressing an unknown
-        // failure up as a known one would send the reader to the wrong place entirely.
         for (const marker of RECOGNISED_MARKERS) {
             if (reason.includes(marker))
                 return { ok: false, reason: marker };

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

@@ -1,37 +1,7 @@
-/**
- * Selectors for Reticle's own presenter overlay (cursor, HUD, glow) + the annotator's
- * UI (`data-reticle-mark`) - never observed/snapshotted. The annotator mounts by DEFAULT with the
- * presenter, so omitting its selector here leaked annotation chrome into every snapshot.
- */
 export declare const RETICLE_OVERLAY: string;
-/**
- * Make Reticle's own presenter visible to snapshots and queries. Contributors only.
- *
- * Deliberately a function rather than a field on the ignore set, so the one place that decides
- * "is this ours" also decides "may it be seen", and no caller can half-apply it.
- */
 export declare function setPresenterVisible(visible: boolean): void;
-/** Whether the hatch is open — reported in the app's capabilities so a verdict is never mistaken. */
 export declare function isPresenterVisible(): boolean;
-/** Let the host app add selectors to exclude from snapshots (e.g. its own dev widgets). */
 export declare function setIgnoreSelectors(selectors: string[]): void;
-/** True if the element is part of Reticle's own presenter overlay. */
 export declare function isReticleOverlay(el: Element): boolean;
-/**
- * True iff the element is part of Reticle's OWN UI - the presenter overlay, the HUD, the synthetic
- * cursor, the glow, or the annotator's marks - or lives inside one of them.
- *
- * The rule used to be "any ancestor carries a data-reticle* attribute", which is wrong twice over.
- * `data-reticle-mark-active` sits on <html> while annotate mode is live, so the whole document
- * answered yes; and `data-reticle-source` is stamped by the Vite/Babel plugins on every element the
- * APP renders, so in an instrumented app - which is the only kind there is - most of the page
- * answered yes too. Those attributes describe page content; they do not make it ours.
- *
- * Two things read this and both failed silently. `pageElementAt` (annotator) skipped every stamped
- * element and anchored the note to the outermost unstamped ancestor, i.e. the app shell instead of
- * the control under the cursor. `occlusion.ts` reads a yes as "nothing to report", so occlusion
- * detection - a bug class Reticle advertises catching - came back clean wherever the stamp reached.
- */
 export declare function isReticleUi(node: Element | null): boolean;
-/** True if the element should be excluded from snapshots/queries (Reticle overlay or dev overlay). */
 export declare function isIgnored(el: Element): boolean;

package/dist/dom/dom-ignore.js

@@ -1,70 +1,23 @@
-/**
- * Selectors for Reticle's own presenter overlay (cursor, HUD, glow) + the annotator's
- * UI (`data-reticle-mark`) - never observed/snapshotted. The annotator mounts by DEFAULT with the
- * presenter, so omitting its selector here leaked annotation chrome into every snapshot.
- */
-export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark],[data-reticle-blocker]';
-/** Known third-party dev overlays to keep out of snapshots (Agentation, Next dev UI). */
+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 = '';
-/**
- * Whether Reticle's OWN UI is visible to snapshots and queries.
- *
- * Off, always, unless an app opts in — and the opt-in exists for exactly one situation: the app
- * under test IS Reticle. A HUD change is otherwise the only kind of change Reticle cannot be used to
- * check, because the panel that renders it is invisible to every tool that could look at it.
- *
- * It stays off by default because the reason for hiding it is sound: an agent that can drive
- * Reticle's own interface can fabricate its own impact report, and a snapshot full of Reticle chrome
- * is noise in every other app on earth. This is a hatch for contributors, not a setting.
- *
- * Third-party dev overlays stay ignored either way — they are somebody else's furniture and were
- * never the thing being verified.
- */
 let presenterVisible = false;
-/**
- * Make Reticle's own presenter visible to snapshots and queries. Contributors only.
- *
- * Deliberately a function rather than a field on the ignore set, so the one place that decides
- * "is this ours" also decides "may it be seen", and no caller can half-apply it.
- */
 export function setPresenterVisible(visible) {
     presenterVisible = visible;
 }
-/** Whether the hatch is open — reported in the app's capabilities so a verdict is never mistaken. */
 export function isPresenterVisible() {
     return presenterVisible;
 }
-/** Let the host app add selectors to exclude from snapshots (e.g. its own dev widgets). */
 export function setIgnoreSelectors(selectors) {
     extraIgnore = selectors.join(',');
 }
-/** True if the element is part of Reticle's own presenter overlay. */
 export function isReticleOverlay(el) {
     return el.closest(RETICLE_OVERLAY) !== null;
 }
-/**
- * True iff the element is part of Reticle's OWN UI - the presenter overlay, the HUD, the synthetic
- * cursor, the glow, or the annotator's marks - or lives inside one of them.
- *
- * The rule used to be "any ancestor carries a data-reticle* attribute", which is wrong twice over.
- * `data-reticle-mark-active` sits on <html> while annotate mode is live, so the whole document
- * answered yes; and `data-reticle-source` is stamped by the Vite/Babel plugins on every element the
- * APP renders, so in an instrumented app - which is the only kind there is - most of the page
- * answered yes too. Those attributes describe page content; they do not make it ours.
- *
- * Two things read this and both failed silently. `pageElementAt` (annotator) skipped every stamped
- * element and anchored the note to the outermost unstamped ancestor, i.e. the app shell instead of
- * the control under the cursor. `occlusion.ts` reads a yes as "nothing to report", so occlusion
- * detection - a bug class Reticle advertises catching - came back clean wherever the stamp reached.
- */
 export function isReticleUi(node) {
     return node !== null && node.closest(RETICLE_OVERLAY) !== null;
 }
-/** True if the element should be excluded from snapshots/queries (Reticle overlay or dev overlay). */
 export function isIgnored(el) {
-    // With the hatch open, Reticle's own overlay drops out of the ignore set — but the third-party
-    // dev overlays do not. They are somebody else's furniture and were never the thing being verified.
     const ours = presenterVisible ? '' : RETICLE_OVERLAY;
     const sel = [ours, DEV_OVERLAYS, extraIgnore].filter((part) => part.length > 0).join(',');
     return el.closest(sel) !== null;

package/dist/dom/occlusion.d.ts

@@ -1,8 +1 @@
-/**
- * Center-point hit-test, shared by click-geometry (actions) and occlusion detection (commands) so the
- * two can't drift. Returns the top NON-Reticle element covering `el`'s center, or null when nothing
- * foreign is on top — i.e. `el` itself, an ancestor wrapping it, or a descendant is on top (all "not
- * occluded"). A zero-area or unlayouted box (jsdom / detached node) returns null: we cannot tell, so
- * we never false-positive an occlusion. Reticle's own HUD is never treated as an occluder.
- */
 export declare function hitTestOccluder(el: Element, rect: DOMRect): Element | null;

package/dist/dom/occlusion.js

@@ -1,20 +1,39 @@
 import { isReticleUi } from './dom-ignore.js';
-/**
- * Center-point hit-test, shared by click-geometry (actions) and occlusion detection (commands) so the
- * two can't drift. Returns the top NON-Reticle element covering `el`'s center, or null when nothing
- * foreign is on top — i.e. `el` itself, an ancestor wrapping it, or a descendant is on top (all "not
- * occluded"). A zero-area or unlayouted box (jsdom / detached node) returns null: we cannot tell, so
- * we never false-positive an occlusion. Reticle's own HUD is never treated as an occluder.
- */
+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.d.ts

@@ -1,18 +1,4 @@
 import { ElementState, type ElementQuery, type MatchResult, type QueryResult } from '@reticlehq/core';
-/** Longest attribute value returned; one enormous href must not blow the response budget. */
 export declare const ATTR_VALUE_MAX = 512;
-/**
- * Match an element predicate against the live DOM.
- *
- * `count` is every match; `elements` is the described prefix. Keeping those separate is what lets
- * "how many?" stay exact while the answer stays affordable.
- */
 export declare function matchQuery(query: ElementQuery, state?: ElementState, limit?: number): MatchResult;
-/**
- * Resolve a query to descriptors for the `query` MCP tool.
- *
- * `count` is carried through deliberately: the server reports match totals from it rather than from
- * the array, because the array is capped in transit. Dropping it here - which this function used to
- * do - silently put the server back to counting survivors and calling that the answer.
- */
 export declare function runQuery(query: ElementQuery, limit?: number): QueryResult;