@reticlehq/browser 2.13.1 → 3.1.0

package/dist/presenter/tour/tour.d.ts

@@ -0,0 +1,25 @@
+import { isLastSlide } from './tour-view.js';
+export declare const TOUR_SEEN_KEY_PREFIX = "reticle.tour.seen.";
+export declare const tourSeenKey: (projectId: string) => string;
+export interface TourStorage {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+}
+export interface TourDeps {
+    readonly document: Document;
+    readonly storage: TourStorage | undefined;
+    readonly projectId: string;
+    readonly isDriving: () => boolean;
+    readonly search?: string;
+    readonly copy?: (text: string) => Promise<boolean> | boolean;
+    readonly select?: (element: Element) => void;
+}
+export interface TourHandle {
+    readonly destroy: () => void;
+    readonly isOpen: () => boolean;
+}
+export declare function openedByReticle(search: string | undefined): boolean;
+export declare function tourAlreadySeen(storage: TourStorage | undefined, projectId: string): boolean;
+export declare function mountTour(deps: TourDeps): TourHandle | undefined;
+export { isLastSlide };
+export declare function safeLocalStorage(): TourStorage | undefined;

package/dist/presenter/tour/tour.js

@@ -0,0 +1,245 @@
+import { COPIED_LABEL, COPY_FLASH_MS, COPY_LABEL, COPY_MANUAL_LABEL, TOUR_ATTR, TOUR_CSS, TOUR_PROMPT_ATTR, TOUR_TARGET_ATTR, holeRects, isInteractive, isLastSlide, nextIndex, slideHtml, tourSlides, } from './tour-view.js';
+import { TourAnchor } from '@reticlehq/core/tour';
+import { RETICLE_URL_PARAM } from '@reticlehq/core';
+export const TOUR_SEEN_KEY_PREFIX = 'reticle.tour.seen.';
+const APP_SELECTORS = ['main', '#root', '#app'];
+const HUD_PARTS = ['[data-reticle-hud]', '[data-reticle-chat-panel]'];
+function unionOfVisible(doc, selectors) {
+    let left = Number.POSITIVE_INFINITY;
+    let top = Number.POSITIVE_INFINITY;
+    let right = Number.NEGATIVE_INFINITY;
+    let bottom = Number.NEGATIVE_INFINITY;
+    for (const selector of selectors) {
+        const box = doc.querySelector(selector)?.getBoundingClientRect();
+        if (undefined === box || box.width <= 0 || box.height <= 0)
+            continue;
+        left = Math.min(left, box.left);
+        top = Math.min(top, box.top);
+        right = Math.max(right, box.left + box.width);
+        bottom = Math.max(bottom, box.top + box.height);
+    }
+    if (right === Number.NEGATIVE_INFINITY)
+        return undefined;
+    return { left, top, width: right - left, height: bottom - top };
+}
+const HUD_CONTROL_SELECTORS = {
+    [TourAnchor.HUD_CHAT]: '[data-reticle-chat-toggle]',
+    [TourAnchor.HUD_ANNOTATE]: '[data-reticle-annotate-btn]',
+    [TourAnchor.HUD_IMPACT]: '[data-reticle-report-btn]',
+    [TourAnchor.HUD_SETTINGS]: '[data-reticle-settings-btn]',
+};
+function anchorBox(doc, anchor) {
+    if (TourAnchor.HUD === anchor)
+        return unionOfVisible(doc, HUD_PARTS);
+    const control = HUD_CONTROL_SELECTORS[anchor];
+    if (undefined !== control) {
+        const box = doc.querySelector(control)?.getBoundingClientRect();
+        return undefined === box ? undefined : box;
+    }
+    if (TourAnchor.APP !== anchor)
+        return undefined;
+    for (const selector of APP_SELECTORS) {
+        const found = doc.querySelector(selector);
+        if (null === found)
+            continue;
+        const box = found.getBoundingClientRect();
+        if (box.width > 0)
+            return box;
+    }
+    return undefined;
+}
+export const tourSeenKey = (projectId) => `${TOUR_SEEN_KEY_PREFIX}${projectId}`;
+export function openedByReticle(search) {
+    if (search === undefined || '' === search)
+        return false;
+    const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
+    return (params.has(RETICLE_URL_PARAM.OPENED) ||
+        params.has(RETICLE_URL_PARAM.SESSION) ||
+        params.has(RETICLE_URL_PARAM.PROJECT));
+}
+export function tourAlreadySeen(storage, projectId) {
+    if (undefined === storage)
+        return true;
+    try {
+        return null !== storage.getItem(tourSeenKey(projectId));
+    }
+    catch {
+        return true;
+    }
+}
+function markSeen(storage, projectId) {
+    try {
+        storage?.setItem(tourSeenKey(projectId), '1');
+    }
+    catch {
+    }
+}
+export function mountTour(deps) {
+    if (deps.isDriving())
+        return undefined;
+    if (openedByReticle(deps.search))
+        return undefined;
+    if (tourAlreadySeen(deps.storage, deps.projectId))
+        return undefined;
+    const doc = deps.document;
+    const style = doc.createElement('style');
+    style.setAttribute(TOUR_ATTR, '');
+    style.textContent = TOUR_CSS;
+    doc.head.appendChild(style);
+    const root = doc.createElement('div');
+    root.setAttribute(TOUR_ATTR, '');
+    const slides = tourSlides();
+    let index = 0;
+    let open = true;
+    let detachKeys = () => undefined;
+    const close = () => {
+        if (!open)
+            return;
+        open = false;
+        detachKeys();
+        markSeen(deps.storage, deps.projectId);
+        root.remove();
+        style.remove();
+    };
+    const draw = () => {
+        const slide = slides[index];
+        if (undefined === slide)
+            return;
+        root.innerHTML = `<div class="reticle-tour-scrim"></div>${slideHtml(slide)}`;
+        if (TourAnchor.NONE !== slide.anchor) {
+            const box = anchorBox(doc, slide.anchor);
+            if (undefined !== box && box.width > 0) {
+                const region = TourAnchor.APP === slide.anchor;
+                const ring = doc.createElement('div');
+                ring.className = region ? 'reticle-tour-ring is-region' : 'reticle-tour-ring';
+                const pad = region ? -2 : 6;
+                ring.style.left = `${String(Math.round(box.left - pad))}px`;
+                ring.style.top = `${String(Math.round(box.top - pad))}px`;
+                ring.style.width = `${String(Math.round(box.width + pad * 2))}px`;
+                ring.style.height = `${String(Math.round(box.height + pad * 2))}px`;
+                root.appendChild(ring);
+                if (!region)
+                    root.querySelector('.reticle-tour-scrim')?.classList.add('is-clear');
+                if (isInteractive(slide)) {
+                    ring.classList.add('is-live');
+                    root.querySelector('.reticle-tour-scrim')?.remove();
+                    const view = doc.defaultView;
+                    for (const rect of holeRects({
+                        left: box.left - pad,
+                        top: box.top - pad,
+                        width: box.width + pad * 2,
+                        height: box.height + pad * 2,
+                    }, view?.innerWidth ?? doc.documentElement.clientWidth, view?.innerHeight ?? doc.documentElement.clientHeight)) {
+                        const blocker = doc.createElement('div');
+                        blocker.className = 'reticle-tour-blocker';
+                        blocker.style.left = `${String(Math.round(rect.left))}px`;
+                        blocker.style.top = `${String(Math.round(rect.top))}px`;
+                        blocker.style.width = `${String(Math.round(rect.width))}px`;
+                        blocker.style.height = `${String(Math.round(rect.height))}px`;
+                        root.appendChild(blocker);
+                    }
+                }
+            }
+        }
+    };
+    const copyPrompt = (button) => {
+        const slide = slides[index];
+        const which = Number(button.getAttribute(TOUR_PROMPT_ATTR));
+        const prompt = slide?.prompts?.[which];
+        if (undefined === prompt)
+            return;
+        const flash = (label, mark) => {
+            button.textContent = label;
+            button.classList.add(mark);
+            doc.defaultView?.setTimeout(() => {
+                button.textContent = COPY_LABEL;
+                button.classList.remove(mark);
+            }, COPY_FLASH_MS);
+        };
+        const settle = (copied) => {
+            if (copied) {
+                flash(COPIED_LABEL, 'is-done');
+                return;
+            }
+            const text = root.querySelector(`.reticle-tour-prompt[${TOUR_PROMPT_ATTR}="${String(which)}"] .reticle-tour-prompt-text`);
+            if (null !== text)
+                deps.select?.(text);
+            flash(COPY_MANUAL_LABEL, 'is-manual');
+        };
+        const result = deps.copy?.(prompt.text);
+        if (undefined === result) {
+            settle(false);
+            return;
+        }
+        if ('boolean' === typeof result) {
+            settle(result);
+            return;
+        }
+        void result.then(settle).catch(() => {
+            settle(false);
+        });
+    };
+    root.addEventListener('click', (event) => {
+        const target = event.target;
+        if (!(target instanceof Element))
+            return;
+        const hit = target.closest(`[${TOUR_TARGET_ATTR}]`);
+        if (null === hit)
+            return;
+        const what = hit.getAttribute(TOUR_TARGET_ATTR);
+        if (null === what)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        if ('skip' === what || 'done' === what) {
+            close();
+            return;
+        }
+        if ('copy' === what) {
+            copyPrompt(hit);
+            return;
+        }
+        const moved = nextIndex(index, 'back' === what ? -1 : 1);
+        if (moved === index)
+            return;
+        index = moved;
+        draw();
+    });
+    const onKey = (event) => {
+        if (!open)
+            return;
+        const step = 'ArrowRight' === event.key ? 1 : 'ArrowLeft' === event.key ? -1 : 0;
+        if ('Escape' === event.key) {
+            event.preventDefault();
+            close();
+            return;
+        }
+        if (0 === step)
+            return;
+        const moved = nextIndex(index, step);
+        if (moved === index)
+            return;
+        event.preventDefault();
+        index = moved;
+        draw();
+    };
+    doc.addEventListener('keydown', onKey);
+    detachKeys = () => {
+        doc.removeEventListener('keydown', onKey);
+    };
+    draw();
+    doc.body.appendChild(root);
+    return {
+        destroy: close,
+        isOpen: () => open,
+    };
+}
+export { isLastSlide };
+export function safeLocalStorage() {
+    try {
+        return window.localStorage;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/recorder/recorder-styles.d.ts

@@ -1,9 +1,3 @@
-/**
- * Inline style strings for the floating recorder toolbar. Browser-local UI
- * text (never crosses the wire), split out of recorder.ts to keep that file under the 500-line cap
- * (mirrors how presenter.ts extracts presenter-log.ts). All toolbar nodes also carry
- * data-reticle-overlay, so they are snapshot-excluded via dom-ignore.ts regardless of these styles.
- */
 export declare const TOOLBAR_CSS: string;
 export declare const BTN_CSS: string;
 export declare const NAME_CSS: string;

package/dist/recorder/recorder-styles.js

@@ -1,9 +1,3 @@
-/**
- * Inline style strings for the floating recorder toolbar. Browser-local UI
- * text (never crosses the wire), split out of recorder.ts to keep that file under the 500-line cap
- * (mirrors how presenter.ts extracts presenter-log.ts). All toolbar nodes also carry
- * data-reticle-overlay, so they are snapshot-excluded via dom-ignore.ts regardless of these styles.
- */
 export const TOOLBAR_CSS = [
     'position:fixed',
     'top:8px',

package/dist/recorder/recorder.d.ts

@@ -1,59 +1,25 @@
 import { AnnotationKind, EventType, RecorderPhase, type FlowAnchor, type FlowFile, type FlowStep } from '@reticlehq/core';
-/**
- * The human recorder. A floating toolbar (Record / Stop / Annotate) lets a
- * human click the golden path; capture-phase listeners map each real interaction to a SEMANTIC
- * anchor (testid → role+name → degraded placeholder, NEVER a volatile ref — invariant #1) and
- * append a FlowStep. Stop compiles a FlowFile in-page and emits ONE EventType.FLOW_RECORDED event
- * the server persists. Four structured annotation kinds compile into expect/dynamic/success.
- *
- * FIRST CUT scope: structured annotations only (the 4 AnnotationKind values via a menu + a signal
- * <select> drawn from registered capabilities). Explicitly FUTURE, not faked here:
- * - NL annotation → predicate compiler (CO-OWNED-FLOWS invariant #2 best-UX path).
- * - fixtures/preconditions (FlowFile.fixture stays a schema slot, never written).
- * - wait-for / ignore-region annotation kinds (only the 4 requested ship).
- */
-/** Browser-local UI text — never crosses the wire, mirrors presenter.ts CHIP_LABEL precedent. */
 export declare const RECORDER_EMPTY_MSG = "recorded 0 steps";
 interface RecorderDeps {
-    /** Emit a wire event (Reticle.#emit bound). */
     emit: (type: EventType, data: Record<string, unknown>) => void;
-    /** Injected clock for FlowFile.createdAt — never Date.now in pure logic (rule 7). */
     now: () => number;
-    /** Default flow name when the toolbar field is blank. */
     defaultName?: string;
 }
 export interface RecorderHandle {
     mount(): void;
     destroy(): void;
-    /** Test seam: current phase. */
     phase(): RecorderPhase;
-    /** Test seam: steps captured so far in the active span. */
     steps(): FlowStep[];
 }
-/** A structured annotation captured while recording (compiled into flow fields at Stop). */
 export interface Annotation {
     kind: AnnotationKind;
     anchor: FlowAnchor;
-    /** Required for ASSERT_SIGNAL / SUCCESS_STATE; the chosen capability signal name. */
     signal?: string;
 }
-/**
- * Pure: map a clicked/typed element → semantic FlowAnchor. testid wins; else role+accessible-name;
- * else the DEGRADED_ANCHOR_ROLE placeholder + degraded:true (never a ref — invariant #1).
- */
 export declare function anchorFor(el: Element): {
     anchor: FlowAnchor;
     degraded: boolean;
 };
-/**
- * Pure: assemble the in-page FlowFile from captured steps + annotations.
- * - ASSERT_SIGNAL → the most-recent step's expect.signal.
- * - ASSERT_VISIBLE → the most-recent step's expect.element (from the annotation anchor).
- * - MARK_DYNAMIC → push the anchor into flow.dynamic[].
- * - SUCCESS_STATE → flow.success = { signal }.
- * (FUTURE: per-step annotation targeting beyond the most-recent step.)
- */
 export declare function compileRecording(name: string, steps: FlowStep[], annotations: Annotation[], createdAt: number, startPath?: string): FlowFile;
-/** Install the floating recorder toolbar. Default off; gated by the host (reticle.ts recorder flag). */
 export declare function installRecorder(deps: RecorderDeps): RecorderHandle;
 export {};

package/dist/recorder/recorder.js

@@ -1,23 +1,10 @@
 import { ActionType, AnchorKind, AnnotationKind, DEGRADED_ANCHOR_ROLE, EventType, FLOW_FILE_VERSION, FlowStepTool, RecorderPhase, } from '@reticlehq/core';
 import { REDACTED_VALUE } from '@reticlehq/core';
+import { sourceFromDom } from '../dom/addressing/source.js';
 import { getAccessibleName, getRole, isSensitiveField } from '../dom/a11y.js';
 import { isReticleOverlay } from '../dom/dom-ignore.js';
 import { getCapabilities } from '../registry/capabilities.js';
 import { TOOLBAR_CSS, BTN_CSS, NAME_CSS, STATUS_CSS, MENU_CSS } from './recorder-styles.js';
-/**
- * The human recorder. A floating toolbar (Record / Stop / Annotate) lets a
- * human click the golden path; capture-phase listeners map each real interaction to a SEMANTIC
- * anchor (testid → role+name → degraded placeholder, NEVER a volatile ref — invariant #1) and
- * append a FlowStep. Stop compiles a FlowFile in-page and emits ONE EventType.FLOW_RECORDED event
- * the server persists. Four structured annotation kinds compile into expect/dynamic/success.
- *
- * FIRST CUT scope: structured annotations only (the 4 AnnotationKind values via a menu + a signal
- * <select> drawn from registered capabilities). Explicitly FUTURE, not faked here:
- * - NL annotation → predicate compiler (CO-OWNED-FLOWS invariant #2 best-UX path).
- * - fixtures/preconditions (FlowFile.fixture stays a schema slot, never written).
- * - wait-for / ignore-region annotation kinds (only the 4 requested ship).
- */
-/** Browser-local UI text — never crosses the wire, mirrors presenter.ts CHIP_LABEL precedent. */
 export const RECORDER_EMPTY_MSG = 'recorded 0 steps';
 const STATUS_RECORDING = 'recording…';
 const STATUS_IDLE = 'ready';
@@ -38,16 +25,11 @@ const ANNOTATION_LABEL = {
     [AnnotationKind.SUCCESS_STATE]: 'success state',
     [AnnotationKind.INTENT]: 'intent',
 };
-/** Annotation kinds whose compilation needs a signal name (from the capabilities <select>). */
 const NEEDS_SIGNAL = new Set([
     AnnotationKind.ASSERT_SIGNAL,
     AnnotationKind.SUCCESS_STATE,
 ]);
 const DEFAULT_NAME = 'recorded-flow';
-/**
- * Pure: map a clicked/typed element → semantic FlowAnchor. testid wins; else role+accessible-name;
- * else the DEGRADED_ANCHOR_ROLE placeholder + degraded:true (never a ref — invariant #1).
- */
 export function anchorFor(el) {
     const testid = el.getAttribute(TESTID_ATTR);
     if (testid !== null && testid.length > 0) {
@@ -59,7 +41,6 @@ export function anchorFor(el) {
         const anchor = name.length > 0 ? { kind: AnchorKind.ROLE, role, name } : { kind: AnchorKind.ROLE, role };
         return { anchor, degraded: false };
     }
-    // No resolvable testid/role/name — keep the step with a legible placeholder, never a ref.
     return { anchor: { kind: AnchorKind.ROLE, role: DEGRADED_ANCHOR_ROLE }, degraded: true };
 }
 function isTextbox(el) {
@@ -84,16 +65,13 @@ function buildStep(el, action, args) {
         step.args = args;
     if (degraded)
         step.degraded = true;
+    const source = sourceFromDom(el);
+    if (source !== undefined) {
+        step.source =
+            source.line === undefined ? { file: source.file } : { file: source.file, line: source.line };
+    }
     return step;
 }
-/**
- * Pure: assemble the in-page FlowFile from captured steps + annotations.
- * - ASSERT_SIGNAL → the most-recent step's expect.signal.
- * - ASSERT_VISIBLE → the most-recent step's expect.element (from the annotation anchor).
- * - MARK_DYNAMIC → push the anchor into flow.dynamic[].
- * - SUCCESS_STATE → flow.success = { signal }.
- * (FUTURE: per-step annotation targeting beyond the most-recent step.)
- */
 export function compileRecording(name, steps, annotations, createdAt, startPath) {
     const out = steps.map((s) => ({ ...s }));
     const dynamic = [];
@@ -137,12 +115,10 @@ function anchorToElement(anchor) {
     }
     return {};
 }
-/** Live recorder instance: holds the capture buffer, toolbar DOM, and the phase machine. */
 class Recorder {
     #deps;
     #phase = RecorderPhase.IDLE;
     #steps = [];
-    /** The pathname the recording began on, so replay can navigate here before step 1. */
     #startPath;
     #annotations = [];
     #pendingFill;
@@ -150,7 +126,6 @@ class Recorder {
     #root;
     #statusEl;
     #menuEl;
-    /** The annotation being assembled in ANNOTATING phase. */
     #draft;
     constructor(deps) {
         this.#deps = deps;
@@ -183,7 +158,6 @@ class Recorder {
         this.#draft = undefined;
         this.#pendingFill = undefined;
     }
-    // ---- capture ----
     #installCapture() {
         const onClick = (ev) => this.#onClick(ev);
         const onInput = (ev) => this.#onInput(ev);
@@ -200,7 +174,6 @@ class Recorder {
             document.removeEventListener('submit', onSubmit, true);
         });
     }
-    /** True if the event should be ignored (toolbar self-click or non-element target). */
     #ignore(ev) {
         const target = ev.target;
         if (!(target instanceof Element))
@@ -219,9 +192,6 @@ class Recorder {
         }
         if (this.#phase !== RecorderPhase.RECORDING)
             return;
-        // Controls that emit `change` (checkbox, radio, select) are recorded by #onChange as their
-        // semantic step (CHECK/UNCHECK/SELECT). Recording a CLICK here too would replay any onChange
-        // side effect twice (analytics, dependent-field resets), so skip the duplicate.
         if ((target instanceof HTMLInputElement &&
             ('checkbox' === inputRole(target) || 'radio' === inputRole(target))) ||
             target instanceof HTMLSelectElement) {
@@ -236,7 +206,6 @@ class Recorder {
         const target = this.#ignore(ev);
         if (target === undefined || !isTextbox(target))
             return;
-        // Debounce per-keystroke input: keep the latest value, flush on change/blur/next-act.
         this.#pendingFill = { el: target, value: target.value };
     }
     #onChange(ev) {
@@ -279,12 +248,9 @@ class Recorder {
         if (pending === undefined)
             return;
         this.#pendingFill = undefined;
-        // Never persist a typed secret into a git-checked flow file: password/OTP/cc/sensitive-keyed
-        // fields record REDACTED_VALUE, the same redaction live snapshots apply (dom/a11y.ts getValue).
         const value = isSensitiveField(pending.el) ? REDACTED_VALUE : pending.value;
         this.#steps.push(buildStep(pending.el, ActionType.FILL, { value }));
     }
-    // ---- annotation ----
     #captureAnnotationTarget(target) {
         const draft = this.#draft;
         if (draft === undefined)
@@ -299,7 +265,6 @@ class Recorder {
         this.#setPhase(RecorderPhase.RECORDING);
         this.#closeMenu();
     }
-    /** Annotate-on-prior: confirm the most-recent step as the target (no extra click needed). */
     #confirmAnnotationOnPrior() {
         const draft = this.#draft;
         if (draft === undefined)
@@ -325,9 +290,7 @@ class Recorder {
         const value = select?.value ?? '';
         return value.length > 0 ? value : undefined;
     }
-    // ---- toolbar lifecycle actions ----
     #start() {
-        // A fresh span — no leakage from a previous Record→Stop cycle.
         this.#steps = [];
         this.#startPath = 'undefined' === typeof location ? undefined : location.pathname;
         this.#annotations = [];
@@ -355,7 +318,6 @@ class Recorder {
     #setPhase(phase) {
         this.#phase = phase;
     }
-    // ---- toolbar DOM (all nodes data-reticle-overlay → snapshot-excluded via dom-ignore.ts) ----
     #buildToolbar() {
         const root = document.createElement('div');
         root.setAttribute('data-reticle-overlay', '');
@@ -396,9 +358,6 @@ class Recorder {
             return;
         menu.textContent = '';
         for (const kind of Object.values(AnnotationKind)) {
-            // INTENT is free-text (the business goal), not a signal/testid pick — authored via
-            // reticle_annotate { kind:'intent', text }. The human toolbar's name field is signal/testid only,
-            // so intent is omitted from this menu rather than shipped as a control that can't capture text.
             if (kind === AnnotationKind.INTENT)
                 continue;
             const item = document.createElement('button');
@@ -426,7 +385,6 @@ class Recorder {
             }
             menu.appendChild(select);
         }
-        // "Confirm on prior step" path (annotate-on-prior); or the next click selects the target.
         const confirm = document.createElement('button');
         confirm.setAttribute('data-reticle-action', 'annotate-confirm');
         confirm.textContent = 'on prior step';
@@ -448,7 +406,6 @@ class Recorder {
         return value.length > 0 ? value : undefined;
     }
 }
-/** Install the floating recorder toolbar. Default off; gated by the host (reticle.ts recorder flag). */
 export function installRecorder(deps) {
     return new Recorder(deps);
 }

package/dist/registry/auto-testids.d.ts

@@ -1,21 +1,2 @@
-/**
- * The testids the page is actually showing, read from the live DOM.
- *
- * `registerCapabilities({ testids: [...] })` used to be the only source, and `init` filled it by
- * grepping the source at install time. That list is a snapshot of the codebase on the day `init` ran:
- * it goes stale on the next commit that renames an element, it is empty for every app whose testids
- * arrive with a lazy route, and finishing it was homework handed to whoever ran the install.
- *
- * The attribute in the DOM is the same declaration, read fresh, so nothing has to be copied into a
- * config file to be true. Reticle's own presenter markup is excluded — advertising our own controls
- * as the app's testable surface would be the tool describing itself.
- */
-/**
- * Ceiling on the reported list.
- *
- * A virtualized 500-row grid stamps a testid per cell, and the capabilities payload rides in every
- * announce — an uncapped read turns one long table into a permanently expensive message. The cap is
- * on the REPORT, not on what can be driven: a testid past it is still findable by query.
- */
 export declare const MAX_AUTO_TESTIDS = 200;
 export declare function domTestids(doc: Document): string[];

package/dist/registry/auto-testids.js

@@ -1,26 +1,6 @@
-/**
- * The testids the page is actually showing, read from the live DOM.
- *
- * `registerCapabilities({ testids: [...] })` used to be the only source, and `init` filled it by
- * grepping the source at install time. That list is a snapshot of the codebase on the day `init` ran:
- * it goes stale on the next commit that renames an element, it is empty for every app whose testids
- * arrive with a lazy route, and finishing it was homework handed to whoever ran the install.
- *
- * The attribute in the DOM is the same declaration, read fresh, so nothing has to be copied into a
- * config file to be true. Reticle's own presenter markup is excluded — advertising our own controls
- * as the app's testable surface would be the tool describing itself.
- */
 const TESTID_ATTR = 'data-testid';
 const TESTID_SELECTOR = `[${TESTID_ATTR}]`;
-/**
- * Ceiling on the reported list.
- *
- * A virtualized 500-row grid stamps a testid per cell, and the capabilities payload rides in every
- * announce — an uncapped read turns one long table into a permanently expensive message. The cap is
- * on the REPORT, not on what can be driven: a testid past it is still findable by query.
- */
 export const MAX_AUTO_TESTIDS = 200;
-/** Reticle's own UI carries testids; they are not the host app's surface. */
 const RETICLE_OWN_PREFIX = 'reticle-';
 export function domTestids(doc) {
     const out = [];
@@ -30,7 +10,7 @@ export function domTestids(doc) {
         nodes = doc.querySelectorAll(TESTID_SELECTOR);
     }
     catch {
-        return out; // a document that cannot be queried (detached, hostile) simply advertises nothing
+        return out;
     }
     for (let i = 0; i < nodes.length && out.length < MAX_AUTO_TESTIDS; i += 1) {
         const value = nodes[i]?.getAttribute(TESTID_ATTR);

package/dist/registry/capabilities.d.ts

@@ -1,4 +1,3 @@
-/** Self-describing capability registry — the testable surface the app advertises. */
 export interface CapabilityFlow {
     name: string;
     steps: string[];
@@ -8,46 +7,16 @@ export interface Capabilities {
     signals: string[];
     stores: string[];
     flows: CapabilityFlow[];
-    /**
-     * True when Reticle's OWN presenter is visible to snapshots and queries.
-     *
-     * Present only when the hatch is open, and reported here rather than left implicit, because a
-     * verdict drawn against Reticle's own interface is not an ordinary verdict: an agent that can see
-     * the impact panel can also assert against it. Anybody reading a result should be able to tell
-     * which kind they are holding without going to look at a build config.
-     */
     presenterExposed?: boolean;
 }
-/** What the host app passes to reticle.describe; all fields optional. */
 export interface CapabilitiesInput {
     testids?: string[];
     signals?: string[];
     stores?: string[];
     flows?: CapabilityFlow[];
 }
-/** Set by the SDK at connect. Idempotent; the last connect wins. */
 export declare function setCapabilitiesListener(cb: (() => void) | undefined): void;
-/** Called by the host app via reticle.describe. Merges (idempotent), never replaces wholesale. */
 export declare function registerCapabilities(input: CapabilitiesInput): void;
-/** Snapshot copy of the registered capabilities (defensive — never hand out the live arrays). */
 export declare function getCapabilities(): Capabilities;
-/**
- * Testids the app DECLARED, without the ones merely observed in the DOM.
- *
- * The difference carries meaning the merged list cannot. `knownEmptyState` asks "did the app NAME
- * this element as part of its testable surface?", which is how a zero-match query against
- * `cart-empty-region` is told apart from a broken selector. Every testid on the page is observed, so
- * answering that over the merged list makes it true whenever the page has any testid at all — the
- * same as not asking.
- */
 export declare function declaredTestids(): string[];
-/**
- * Whether the app has a testable surface at all (used in the HELLO flag).
- *
- * Answered over the OBSERVED surface as well as the declared one. It used to be answerable only by
- * declaration, so an app with two hundred testids in its DOM and a live Redux store reported
- * `hasCapabilities: false` until somebody typed those facts into a config file — and the agent
- * reading that flag concluded, correctly by the flag and wrongly in fact, that there was nothing to
- * drive.
- */
 export declare function hasCapabilities(): boolean;