@reticlehq/browser 2.1.0 → 2.2.0

package/dist/dom/auto-anchor.js

@@ -8,16 +8,16 @@
  * 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).
+ * 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

package/dist/dom/blind-spots.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Blind-spot detection, the detectable half). Cross-origin iframes are a real observation gap — the
+ * SDK cannot see inside them (same-origin policy). We COUNT them so a result can say "coverage: partial —
+ * 2 cross-origin frames unobserved" instead of implying it saw the whole page. Closed shadow roots are a
+ * blind spot too, but undetectable by design (element.shadowRoot === null), so they are not counted here.
+ */
+/** Pure: how many frames are cross-origin, given each frame's same-origin flag + whether it has a src. */
+export declare function classifyCrossOriginFrames(frames: ReadonlyArray<{
+    sameOrigin: boolean;
+    hasSrc: boolean;
+}>): number;
+/** Probe the live document: count iframes whose document is unreachable (cross-origin). */
+export declare function countCrossOriginFrames(): number;
+//# sourceMappingURL=blind-spots.d.ts.map

package/dist/dom/blind-spots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blind-spots.d.ts","sourceRoot":"","sources":["../../src/dom/blind-spots.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0GAA0G;AAC1G,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,aAAa,CAAC;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,GAC9D,MAAM,CAER;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,IAAI,MAAM,CAe/C"}

package/dist/dom/blind-spots.js

@@ -0,0 +1,30 @@
+/**
+ * Blind-spot detection, the detectable half). Cross-origin iframes are a real observation gap — the
+ * SDK cannot see inside them (same-origin policy). We COUNT them so a result can say "coverage: partial —
+ * 2 cross-origin frames unobserved" instead of implying it saw the whole page. Closed shadow roots are a
+ * blind spot too, but undetectable by design (element.shadowRoot === null), so they are not counted here.
+ */
+/** Pure: how many frames are cross-origin, given each frame's same-origin flag + whether it has a src. */
+export function classifyCrossOriginFrames(frames) {
+    return frames.filter((f) => f.hasSrc && !f.sameOrigin).length;
+}
+/** Probe the live document: count iframes whose document is unreachable (cross-origin). */
+export function countCrossOriginFrames() {
+    if (typeof document === 'undefined')
+        return 0;
+    const frames = [];
+    for (const frame of document.querySelectorAll('iframe')) {
+        const hasSrc = frame.getAttribute('src') !== null && frame.getAttribute('src') !== '';
+        let sameOrigin = true;
+        try {
+            // Reaching contentDocument throws (or yields null) for a cross-origin frame.
+            sameOrigin = frame.contentDocument !== null;
+        }
+        catch {
+            sameOrigin = false;
+        }
+        frames.push({ sameOrigin, hasSrc });
+    }
+    return classifyCrossOriginFrames(frames);
+}
+//# sourceMappingURL=blind-spots.js.map

package/dist/dom/blind-spots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blind-spots.js","sourceRoot":"","sources":["../../src/dom/blind-spots.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0GAA0G;AAC1G,MAAM,UAAU,yBAAyB,CACvC,MAA+D;IAE/D,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC;AAChE,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,sBAAsB;IACpC,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAO,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAoD,EAAE,CAAC;IACnE,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxD,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACtF,IAAI,UAAU,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC;YACH,6EAA6E;YAC7E,UAAU,GAAG,KAAK,CAAC,eAAe,KAAK,IAAI,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACP,UAAU,GAAG,KAAK,CAAC;QACrB,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,yBAAyB,CAAC,MAAM,CAAC,CAAC;AAC3C,CAAC"}

package/dist/dom/chart.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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) => {
+            data?: unknown;
+        } | undefined;
+    };
+    echarts?: {
+        getInstanceByDom?: (el: Element) => {
+            getOption?: () => unknown;
+        } | undefined;
+    };
+}): CanvasChartData | null;
+//# sourceMappingURL=chart.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chart.d.ts","sourceRoot":"","sources":["../../src/dom/chart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AASH,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,IAAI,EAAE,wBAAwB,GAAG,gBAAgB,GAAG,qBAAqB,CAAC;IAC1E,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,wGAAwG;IACxG,MAAM,EAAE,OAAO,CAAC;CACjB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAGvD;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAK7D;AAED,oGAAoG;AACpG,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CASnD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,CAwBvD;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,oGAAoG;IACpG,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE;IACP,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK;YAAE,IAAI,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG,SAAS,CAAA;KAAE,CAAC;IACvE,OAAO,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK;YAAE,SAAS,CAAC,EAAE,MAAM,OAAO,CAAA;SAAE,GAAG,SAAS,CAAA;KAAE,CAAC;CAC7F,GACA,eAAe,GAAG,IAAI,CAUxB"}

package/dist/dom/chart.js

@@ -0,0 +1,119 @@
+/**
+ * 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 (nums.length === 0)
+        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) => i % 2 === 0);
+    const ys = nums.filter((_, i) => i % 2 === 1);
+    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;
+    for (const tag of GEOMETRY_TAGS) {
+        for (const el of Array.from(root.querySelectorAll(tag))) {
+            for (const attr of GEOMETRY_ATTRS) {
+                const value = el.getAttribute(attr);
+                if (value === null)
+                    continue;
+                examined += 1;
+                const sample = value.length > SAMPLE_MAX ? `${value.slice(0, SAMPLE_MAX)}…` : value;
+                if (hasNonFiniteCoordinate(value)) {
+                    findings.push({ kind: 'non-finite-coordinates', tag, attr, sample });
+                }
+                else if (value.trim().length === 0) {
+                    findings.push({ kind: 'empty-geometry', tag, attr, sample });
+                }
+                else if (isDegenerate(value)) {
+                    findings.push({ kind: 'degenerate-geometry', tag, attr, sample });
+                }
+            }
+        }
+    }
+    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) {
+        return { library: 'chartjs', data: chartjs.data ?? null };
+    }
+    const echart = globals.echarts?.getInstanceByDom?.(canvas);
+    if (echart !== undefined && echart !== null) {
+        return { library: 'echarts', data: echart.getOption?.() ?? null };
+    }
+    return null;
+}
+//# sourceMappingURL=chart.js.map

package/dist/dom/chart.js.map

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

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

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

package/dist/dom/dom-ignore.js

@@ -1,5 +1,10 @@
-/** Selectors for Reticle's own presenter overlay (cursor, HUD, glow) — never observed/snapshotted. */
-const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow]';
+/**
+ * Selectors for Reticle's own presenter overlay (cursor, HUD, glow) + the annotator's "flag a bug"
+ * UI (`data-reticle-mark`) — never observed/snapshotted. The annotator mounts by DEFAULT with the
+ * presenter, so omitting its selector here leaked a phantom `<button>Flag a bug</button>` into every
+ * snapshot and streamed its highlight-box mutations/transitions as if the APP had rendered them.
+ */
+const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark]';
 /** Known third-party dev overlays to keep out of snapshots (Agentation, Next dev UI). */
 const DEV_OVERLAYS = '[data-agentation],#__next-build-watcher,nextjs-portal,[data-nextjs-dialog],[data-nextjs-toast]';
 let extraIgnore = '';

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

@@ -1 +1 @@
-{"version":3,"file":"dom-ignore.js","sourceRoot":"","sources":["../../src/dom/dom-ignore.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,MAAM,eAAe,GACnB,qFAAqF,CAAC;AAExF,yFAAyF;AACzF,MAAM,YAAY,GAChB,gGAAgG,CAAC;AAEnG,IAAI,WAAW,GAAG,EAAE,CAAC;AAErB,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CAAC,SAAmB;IACpD,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,EAAW;IAC1C,OAAO,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC,KAAK,IAAI,CAAC;AAC9C,CAAC;AAED,8GAA8G;AAC9G,MAAM,UAAU,WAAW,CAAC,IAAoB;IAC9C,KAAK,IAAI,CAAC,GAAmB,IAAI,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,CAAC;QACnE,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC;gBAAE,OAAO,IAAI,CAAC;QACxD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,SAAS,CAAC,EAAW;IACnC,MAAM,GAAG,GACP,WAAW,CAAC,MAAM,GAAG,CAAC;QACpB,CAAC,CAAC,GAAG,eAAe,IAAI,YAAY,IAAI,WAAW,EAAE;QACrD,CAAC,CAAC,GAAG,eAAe,IAAI,YAAY,EAAE,CAAC;IAC3C,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;AAClC,CAAC"}
+{"version":3,"file":"dom-ignore.js","sourceRoot":"","sources":["../../src/dom/dom-ignore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,eAAe,GACnB,yGAAyG,CAAC;AAE5G,yFAAyF;AACzF,MAAM,YAAY,GAChB,gGAAgG,CAAC;AAEnG,IAAI,WAAW,GAAG,EAAE,CAAC;AAErB,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CAAC,SAAmB;IACpD,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,EAAW;IAC1C,OAAO,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC,KAAK,IAAI,CAAC;AAC9C,CAAC;AAED,8GAA8G;AAC9G,MAAM,UAAU,WAAW,CAAC,IAAoB;IAC9C,KAAK,IAAI,CAAC,GAAmB,IAAI,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,CAAC;QACnE,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC;gBAAE,OAAO,IAAI,CAAC;QACxD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,SAAS,CAAC,EAAW;IACnC,MAAM,GAAG,GACP,WAAW,CAAC,MAAM,GAAG,CAAC;QACpB,CAAC,CAAC,GAAG,eAAe,IAAI,YAAY,IAAI,WAAW,EAAE;QACrD,CAAC,CAAC,GAAG,eAAe,IAAI,YAAY,EAAE,CAAC;IAC3C,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;AAClC,CAAC"}

package/dist/dom/query.d.ts

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

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

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/dom/query.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,YAAY,EAGZ,KAAK,YAAY,EACjB,KAAK,WAAW,EAGhB,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AA8IzB,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,WAAW,CAUjF;AAmFD,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAMzD"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/dom/query.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,YAAY,EAIZ,KAAK,YAAY,EACjB,KAAK,WAAW,EAGhB,KAAK,WAAW,EAEjB,MAAM,iBAAiB,CAAC;AAkNzB,6FAA6F;AAC7F,eAAO,MAAM,cAAc,MAAM,CAAC;AAqClC;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EACnB,KAAK,CAAC,EAAE,YAAY,EACpB,KAAK,GAAE,MAAsB,GAC5B,WAAW,CA+Bb;AAoGD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAYzE"}