@reticlehq/browser 2.13.1 → 2.14.0

package/dist/dom/a11y.js

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

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

@@ -1,30 +1,3 @@
-/**
- * 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";
@@ -32,34 +5,21 @@ export declare const AnchorStrategy: {
     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,30 +1,3 @@
-/**
- * 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',
@@ -34,15 +7,10 @@ export const AnchorStrategy = {
 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 };
@@ -69,6 +37,5 @@ export function synthesizeAnchor(input) {
         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/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 { 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;