@reticlehq/server 2.14.0 → 3.2.0

package/dist/events/reaction.d.ts

@@ -1,33 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-interface ReactionSummary {
-    total: number;
-    network: number;
-    domAdded: number;
-    domRemoved: number;
-    domChanged: number;
-    routeChanges: number;
-    consoleErrors: number;
-    animations: number;
-    signals: number;
-}
-interface ReactionReport {
-    window_ms: number;
-    events: ReticleEvent[];
-    summary: ReactionSummary;
-}
-/** Turn a slice of the event buffer into the structured "what the app did" report (plan/05). */
-export declare function buildReactionReport(events: ReticleEvent[], windowMs: number): ReactionReport;
-/** The lean form of a reaction report: window + counts, WITHOUT the heavy per-event timeline. */
-interface ReactionDigest {
-    window_ms: number;
-    summary: ReactionSummary;
-}
-/**
- * Drop the per-event `events` array, keeping the window and counts. The counts already answer "what
- * did the app do?" (DOM added/removed/changed, network, signals…), and a predicate verdict carries
- * the matching evidence — so a tool returning this digest stays cheap while the full timeline is one
- * `reticle_observe { since }` away when the agent needs it. On a large DOM the events array dominates
- * the cost (hundreds of tokens of mutations); the digest is a handful.
- */
-export declare function summarizeReaction(report: ReactionReport): ReactionDigest;
-export {};

package/dist/events/reaction.js

@@ -1,59 +0,0 @@
-import { EventType } from '@reticlehq/core';
-/** Turn a slice of the event buffer into the structured "what the app did" report (plan/05). */
-export function buildReactionReport(events, windowMs) {
-    const summary = {
-        total: events.length,
-        network: 0,
-        domAdded: 0,
-        domRemoved: 0,
-        domChanged: 0,
-        routeChanges: 0,
-        consoleErrors: 0,
-        animations: 0,
-        signals: 0,
-    };
-    for (const e of events) {
-        switch (e.type) {
-            case EventType.NET_REQUEST:
-                summary.network += 1;
-                break;
-            case EventType.DOM_ADDED:
-                summary.domAdded += 1;
-                break;
-            case EventType.DOM_REMOVED:
-                summary.domRemoved += 1;
-                break;
-            case EventType.DOM_ATTR:
-            case EventType.DOM_TEXT:
-                summary.domChanged += 1;
-                break;
-            case EventType.ROUTE_CHANGE:
-                summary.routeChanges += 1;
-                break;
-            case EventType.CONSOLE_ERROR:
-            case EventType.ERROR_UNCAUGHT:
-                summary.consoleErrors += 1;
-                break;
-            case EventType.ANIM_START:
-            case EventType.ANIM_END:
-                summary.animations += 1;
-                break;
-            case EventType.SIGNAL:
-                summary.signals += 1;
-                break;
-            default:
-                break;
-        }
-    }
-    return { window_ms: windowMs, events, summary };
-}
-/**
- * Drop the per-event `events` array, keeping the window and counts. The counts already answer "what
- * did the app do?" (DOM added/removed/changed, network, signals…), and a predicate verdict carries
- * the matching evidence — so a tool returning this digest stays cheap while the full timeline is one
- * `reticle_observe { since }` away when the agent needs it. On a large DOM the events array dominates
- * the cost (hundreds of tokens of mutations); the digest is a handful.
- */
-export function summarizeReaction(report) {
-    return { window_ms: report.window_ms, summary: report.summary };
-}

package/dist/events/reconcile.d.ts

@@ -1,39 +0,0 @@
-/**
- * Compare what the API SAID against what the page SHOWS.
- *
- * Every other check in Reticle reads one side. This reads both, which is the one comparison only
- * something living inside the app can make: the response body and the rendered text are in the same
- * process, and nothing else holds them at the same time. A screenshot has the render and not the
- * data; a network log has the data and not the render; a human reading either one sees a number that
- * looks right.
- *
- * Two findings, both measured on a real payments dashboard:
- *
- *  - **the wrong currency.** `GET /payments` returns `{amount: 7997, currency: "USD"}` and the row
- *    renders "₹79.97". The number is correct, the unit is not — a dollar amount presented as rupees.
- *    Every channel agrees: 200, the digits match the data, the page settles.
- *  - **a status that is never shown.** `GET /settlements` returns `status: "on_hold"` with
- *    `hold_reason: "kyc_documents_expired"`, and the badge reads "pending". A merchant reads
- *    "pending" and waits, while the payout is blocked on expired documents.
- *
- * Pure: response bodies and page text in, findings out. No session, no DOM, no clock.
- */
-/** A finding: one field of one entity whose rendering disagrees with the data. */
-export interface Mismatch {
-    entity: string;
-    field: string;
-    /** What the API returned. */
-    api: string;
-    /** What the page shows instead — absent when the value simply never appears. */
-    rendered?: string;
-    why: string;
-}
-/** Every object carrying an `id`, at any depth. These are the things a UI renders as rows. */
-export declare function entitiesIn(node: unknown, out?: Record<string, unknown>[]): Record<string, unknown>[];
-/**
- * Compare entities against the page's rendered text.
- *
- * `pageText` is the visible text of the page — the snapshot's own tree is exactly this, so no new
- * capability is needed to obtain it.
- */
-export declare function reconcile(bodies: readonly unknown[], pageText: string): Mismatch[];

package/dist/events/reconcile.js

@@ -1,211 +0,0 @@
-/**
- * Compare what the API SAID against what the page SHOWS.
- *
- * Every other check in Reticle reads one side. This reads both, which is the one comparison only
- * something living inside the app can make: the response body and the rendered text are in the same
- * process, and nothing else holds them at the same time. A screenshot has the render and not the
- * data; a network log has the data and not the render; a human reading either one sees a number that
- * looks right.
- *
- * Two findings, both measured on a real payments dashboard:
- *
- *  - **the wrong currency.** `GET /payments` returns `{amount: 7997, currency: "USD"}` and the row
- *    renders "₹79.97". The number is correct, the unit is not — a dollar amount presented as rupees.
- *    Every channel agrees: 200, the digits match the data, the page settles.
- *  - **a status that is never shown.** `GET /settlements` returns `status: "on_hold"` with
- *    `hold_reason: "kyc_documents_expired"`, and the badge reads "pending". A merchant reads
- *    "pending" and waits, while the payout is blocked on expired documents.
- *
- * Pure: response bodies and page text in, findings out. No session, no DOM, no clock.
- */
-/**
- * Currency markers, symbol and code. Deliberately a closed list: currency is one of the few things an
- * app renders that has a fixed, publicly agreed vocabulary, which is what makes this checkable
- * without knowing anything about the app.
- */
-const CURRENCY_MARKS = {
-    INR: ['₹', 'INR', 'Rs.', 'Rs '],
-    USD: ['$', 'USD', 'US$'],
-    EUR: ['€', 'EUR'],
-    GBP: ['£', 'GBP'],
-    JPY: ['¥', 'JPY'],
-    AED: ['AED', 'د.إ'],
-    SGD: ['SGD', 'S$'],
-    AUD: ['AUD', 'A$'],
-};
-/** Currencies whose minor unit is not 1/100. Rendering these needs a different divisor. */
-const ZERO_DECIMAL = new Set(['JPY', 'KRW', 'VND']);
-/** Fields that name a state — the ones a badge renders and a user acts on. */
-const STATE_FIELDS = new Set(['status', 'state']);
-const ITEM_KEYS = ['items', 'results', 'data', 'records', 'rows', 'entries'];
-function isRecord(value) {
-    return 'object' === typeof value && value !== null && !Array.isArray(value);
-}
-/** Every object carrying an `id`, at any depth. These are the things a UI renders as rows. */
-export function entitiesIn(node, out = []) {
-    if (Array.isArray(node)) {
-        for (const item of node)
-            entitiesIn(item, out);
-        return out;
-    }
-    if (!isRecord(node))
-        return out;
-    if (node['id'] !== undefined)
-        out.push(node);
-    for (const key of ITEM_KEYS) {
-        if (node[key] !== undefined)
-            entitiesIn(node[key], out);
-    }
-    return out;
-}
-/**
- * Every way a UI might print a minor-unit integer as a major-unit amount.
- *
- * Real interfaces group digits, and they do not agree on how: "44,573.44" in most of the world,
- * "44.573,44" across much of Europe, and "1,22,464.06" under the Indian lakh convention. Matching only
- * the ungrouped form finds nothing on any app that formats its money, which is all of them — measured
- * on a logistics console whose cells read "₹44,573.44" while the check searched for "44573.44".
- */
-function majorForms(minor, currency) {
-    if (ZERO_DECIMAL.has(currency))
-        return [String(minor), group(String(minor)), indian(String(minor))];
-    const plain = (minor / 100).toFixed(2);
-    const [whole = '', fraction = ''] = plain.split('.');
-    return [
-        plain,
-        `${group(whole)}.${fraction}`,
-        `${indian(whole)}.${fraction}`,
-        // European: dots group, comma is the decimal separator.
-        `${group(whole).replace(/,/g, '.')},${fraction}`,
-    ];
-}
-/** Western grouping: every three digits from the right. */
-function group(whole) {
-    return whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
-}
-/** Indian grouping: the last three digits, then pairs — 1,22,464. */
-function indian(whole) {
-    if (whole.length <= 3)
-        return whole;
-    const last = whole.slice(-3);
-    const rest = whole.slice(0, -3);
-    return `${rest.replace(/\B(?=(\d{2})+(?!\d))/g, ',')},${last}`;
-}
-/** Does the text show this amount marked as some OTHER currency? Returns that marker. */
-function wrongCurrencyMark(text, amounts, expected) {
-    for (const amount of amounts) {
-        const mark = markBefore(text, amount, expected);
-        if (mark !== undefined)
-            return mark;
-    }
-    return undefined;
-}
-function markBefore(text, amount, expected) {
-    const at = text.indexOf(amount);
-    if (-1 === at)
-        return undefined; // this rendering is not on screen — try the next
-    // Look just before the number, where a symbol or code sits. A window, not the whole page: the
-    // point is what is attached to THIS amount.
-    const before = text.slice(Math.max(0, at - 12), at);
-    const expectedMarks = CURRENCY_MARKS[expected] ?? [expected];
-    if (expectedMarks.some((mark) => before.includes(mark)))
-        return undefined;
-    for (const [code, marks] of Object.entries(CURRENCY_MARKS)) {
-        if (code === expected)
-            continue;
-        for (const mark of marks) {
-            if (before.includes(mark))
-                return mark;
-        }
-    }
-    return undefined;
-}
-/** Every form a state value might legitimately be rendered as: `on_hold`, `on hold`, `On Hold`. */
-function renderedForms(value) {
-    const spaced = value.replace(/[_-]+/g, ' ');
-    return [value, spaced, spaced.replace(/\s+/g, '')];
-}
-function shows(text, value) {
-    const haystack = text.toLowerCase();
-    return renderedForms(value).some((form) => haystack.includes(form.toLowerCase()));
-}
-/**
- * Compare entities against the page's rendered text.
- *
- * `pageText` is the visible text of the page — the snapshot's own tree is exactly this, so no new
- * capability is needed to obtain it.
- */
-export function reconcile(bodies, pageText) {
-    const entities = bodies.flatMap((body) => entitiesIn(body));
-    const found = [];
-    const seen = new Set();
-    // Every value each state field took across the response set — used to tell "this value is simply
-    // not rendered anywhere" (uninteresting) from "a DIFFERENT value of this same field is rendered"
-    // (a mapping bug). Without that distinction the check would flag any field a UI chooses not to show.
-    const vocabulary = new Map();
-    for (const entity of entities) {
-        for (const [field, value] of Object.entries(entity)) {
-            if (!STATE_FIELDS.has(field) || typeof value !== 'string')
-                continue;
-            const values = vocabulary.get(field) ?? new Set();
-            values.add(value);
-            vocabulary.set(field, values);
-        }
-    }
-    for (const entity of entities) {
-        // An id is a string or a number in every API worth reconciling; anything else is not an identity
-        // this can report against, so the record is skipped rather than stringified into nonsense.
-        const raw = entity['id'];
-        if (typeof raw !== 'string' && typeof raw !== 'number')
-            continue;
-        const id = String(raw);
-        // Any numeric field on an entity that declares a currency is money in THAT currency. Checking a
-        // fixed field name instead would only ever work on APIs that happen to call it `amount` — the
-        // three real ones measured here use `amount`, `declaredValueMinor` and `total`.
-        //
-        // The check is still tight, because a value only counts when the page renders it AS money: the
-        // number must appear with a currency marker attached. A non-money number that happens to share a
-        // decimal form (a weight, a count) is rendered bare and never reaches the comparison.
-        const currency = entity['currency'];
-        if ('string' === typeof currency) {
-            for (const [field, value] of Object.entries(entity)) {
-                if (typeof value !== 'number' || 'currency' === field)
-                    continue;
-                const printed = majorForms(value, currency);
-                const wrong = wrongCurrencyMark(pageText, printed, currency);
-                const key = `${id}:currency`;
-                if (wrong === undefined || seen.has(key))
-                    continue;
-                seen.add(key);
-                found.push({
-                    entity: id,
-                    field: 'currency',
-                    api: currency,
-                    rendered: wrong,
-                    why: `the API reports ${currency} ${String(value)} (minor units, field "${field}") and the page shows it marked "${wrong}" — the number is right and the currency is not, so the amount reads as a different one entirely`,
-                });
-            }
-        }
-        for (const [field, value] of Object.entries(entity)) {
-            if (!STATE_FIELDS.has(field) || typeof value !== 'string')
-                continue;
-            if (shows(pageText, value))
-                continue;
-            // Only interesting if the page renders SOME value of this field — otherwise the UI just does
-            // not display it, which is a design choice and not a defect.
-            const others = [...(vocabulary.get(field) ?? [])].filter((v) => v !== value);
-            const shown = others.filter((v) => shows(pageText, v));
-            const key = `${id}:${field}`;
-            if (0 === shown.length || seen.has(key))
-                continue;
-            seen.add(key);
-            found.push({
-                entity: id,
-                field,
-                api: value,
-                why: `the API reports ${field}="${value}" for ${id}, and no rendering of that value appears on the page — while other values of the same field are shown (${shown.join(', ')}), so this record is being displayed as something it is not`,
-            });
-        }
-    }
-    return found;
-}

package/dist/events/ring-buffer.d.ts

@@ -1,41 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-interface RingBufferOptions {
-    maxEvents?: number;
-    maxAgeMs?: number;
-    maxBytes?: number;
-}
-/**
- * Bounded, time-aware event store per session. The single data structure that powers
- * observe/wait_for/assert — it lets us look both backward (recent buffer) and
- * forward (await new events).
- *
- * Eviction advances a HEAD index instead of shift/splice — O(1) per dropped event (was O(n) per
- * shift, i.e. O(n) per push at steady state under the DOM/animation floods). The dead prefix is
- * compacted away once it dominates, so the backing arrays stay bounded (amortized O(1)).
- *
- * `now` is injected so the buffer is deterministically testable (inject the clock, never call
- * Date.now inside logic).
- */
-export declare class RingBuffer {
-    #private;
-    constructor(options?: RingBufferOptions);
-    push(event: ReticleEvent, now: number, byteSize?: number): void;
-    /** Events at or after a given timestamp cursor. */
-    since(cursor: number): ReticleEvent[];
-    /** Events within the last `windowMs`, relative to `now`. */
-    window(windowMs: number, now: number): ReticleEvent[];
-    /**
-     * Did this buffer evict scarce evidence that belonged to a window opened at `cursor`?
-     *
-     * The one honest input to "was the capture clean". A `false` here means every non-churn event in
-     * the window is still held, whatever the drop counter says — and the drop counter says a great
-     * deal, because age eviction runs on every push.
-     */
-    lostSince(cursor: number): boolean;
-    /** Snapshot of buffer health for the agent — live events held and cumulative drops since connect. */
-    bufferHealth(): {
-        total: number;
-        dropped: number;
-    };
-}
-export {};

package/dist/events/ring-buffer.js

@@ -1,151 +0,0 @@
-import { CHURN_TYPES, RING_BUFFER_DEFAULTS } from '@reticlehq/core';
-/** How far forward to look for a churn event to sacrifice before falling back to plain FIFO. */
-const CHURN_SCAN_LIMIT = 256;
-/**
- * Bounded, time-aware event store per session. The single data structure that powers
- * observe/wait_for/assert — it lets us look both backward (recent buffer) and
- * forward (await new events).
- *
- * Eviction advances a HEAD index instead of shift/splice — O(1) per dropped event (was O(n) per
- * shift, i.e. O(n) per push at steady state under the DOM/animation floods). The dead prefix is
- * compacted away once it dominates, so the backing arrays stay bounded (amortized O(1)).
- *
- * `now` is injected so the buffer is deterministically testable (inject the clock, never call
- * Date.now inside logic).
- */
-export class RingBuffer {
-    #maxEvents;
-    #maxAgeMs;
-    #maxBytes;
-    #events = [];
-    #eventBytes = [];
-    /** Index of the first LIVE event; [0, #head) are evicted but not yet compacted out of the arrays. */
-    #head = 0;
-    #totalBytes = 0;
-    #droppedCount = 0;
-    /**
-     * The timestamp of the newest NON-CHURN event this buffer has ever evicted, or `undefined` if it
-     * has never lost one. This — not the drop counter — is what impeaches an observation window.
-     *
-     * The counter cannot answer the question. It moves for age eviction (everything past 60s, on every
-     * push) and for churn eviction (the low-signal floor, sacrificed on purpose so scarce evidence
-     * survives), neither of which is evidence lost from the window an agent just observed. See
-     * `lostSince` and `ring-buffer-window-loss.test.ts`.
-     */
-    #lastScarceLossT;
-    constructor(options = {}) {
-        this.#maxEvents = options.maxEvents ?? RING_BUFFER_DEFAULTS.MAX_EVENTS;
-        this.#maxAgeMs = options.maxAgeMs ?? RING_BUFFER_DEFAULTS.MAX_AGE_MS;
-        this.#maxBytes = options.maxBytes ?? RING_BUFFER_DEFAULTS.MAX_BYTES;
-    }
-    #liveCount() {
-        return this.#events.length - this.#head;
-    }
-    push(event, now, byteSize) {
-        this.#events.push(event);
-        // Prefer the size measured at the parse boundary (the raw wire frame the bridge already has) over
-        // re-serializing here — a JSON.stringify per pushed event was the buffer's highest constant cost.
-        const bytes = byteSize ?? Buffer.byteLength(JSON.stringify(event), 'utf8');
-        this.#eventBytes.push(bytes);
-        this.#totalBytes += bytes;
-        this.#evict(now);
-    }
-    /** Events at or after a given timestamp cursor. */
-    since(cursor) {
-        return this.#events.slice(this.#lowerBound(cursor));
-    }
-    /** Events within the last `windowMs`, relative to `now`. */
-    window(windowMs, now) {
-        return this.#events.slice(this.#lowerBound(now - windowMs));
-    }
-    /** Binary search over the LIVE window [#head, length) for the first event at/after `target`. */
-    #lowerBound(target) {
-        let lo = this.#head;
-        let hi = this.#events.length;
-        while (lo < hi) {
-            const mid = (lo + hi) >>> 1;
-            if ((this.#events[mid]?.t ?? 0) < target)
-                lo = mid + 1;
-            else
-                hi = mid;
-        }
-        return lo;
-    }
-    #evict(now) {
-        const cutoff = now - this.#maxAgeMs;
-        const before = this.#liveCount();
-        // Cap/byte pressure: sacrifice the CHURN floor before scarce evidence. The head is usually churn on
-        // a busy page, so this stays the O(1) head-advance; only when the oldest event is worth keeping do we
-        // look forward (bounded) for a churn event to drop instead.
-        // Byte pressure keeps at least ONE event: a single event larger than the whole byte budget would
-        // otherwise be pushed and then immediately self-evicted, so a waiter for it never saw it and only
-        // `dropped` moved. Bytes is a soft cap and per-value serialization already bounds any one event, so
-        // keeping the sole survivor over the budget is the correct trade. The count cap (maxEvents, ~2000)
-        // is a hard bound and stays `> maxEvents`.
-        while (this.#liveCount() > this.#maxEvents ||
-            (this.#totalBytes > this.#maxBytes && this.#liveCount() > 1)) {
-            if (CHURN_TYPES.has(this.#events[this.#head]?.type ?? '')) {
-                this.#totalBytes -= this.#eventBytes[this.#head] ?? 0;
-                this.#head += 1;
-                continue;
-            }
-            const victim = this.#findChurnAfterHead();
-            if (-1 === victim) {
-                // Buffer genuinely full of high-signal events — fall back to FIFO so it stays bounded. This
-                // is the one eviction path that destroys scarce evidence, and the only one that should ever
-                // make a verdict say it could not see.
-                this.#noteScarceLoss(this.#head);
-                this.#totalBytes -= this.#eventBytes[this.#head] ?? 0;
-                this.#head += 1;
-                continue;
-            }
-            this.#totalBytes -= this.#eventBytes[victim] ?? 0;
-            this.#events.splice(victim, 1); // order preserved; victim > #head so the head stays valid
-            this.#eventBytes.splice(victim, 1);
-        }
-        while (this.#liveCount() > 0 && (this.#events[this.#head]?.t ?? cutoff) < cutoff) {
-            this.#noteScarceLoss(this.#head);
-            this.#totalBytes -= this.#eventBytes[this.#head] ?? 0;
-            this.#head += 1;
-        }
-        this.#droppedCount += before - this.#liveCount();
-        // Reclaim the dead prefix once it dominates the backing arrays (amortized O(1) compaction).
-        if (this.#head > 1024 && this.#head * 2 >= this.#events.length) {
-            this.#events = this.#events.slice(this.#head);
-            this.#eventBytes = this.#eventBytes.slice(this.#head);
-            this.#head = 0;
-        }
-    }
-    /** Record an eviction at `index` as scarce loss, unless it was the churn floor being sacrificed. */
-    #noteScarceLoss(index) {
-        const victim = this.#events[index];
-        if (victim === undefined || CHURN_TYPES.has(victim.type))
-            return;
-        if (this.#lastScarceLossT === undefined || victim.t > this.#lastScarceLossT) {
-            this.#lastScarceLossT = victim.t;
-        }
-    }
-    /**
-     * Did this buffer evict scarce evidence that belonged to a window opened at `cursor`?
-     *
-     * The one honest input to "was the capture clean". A `false` here means every non-churn event in
-     * the window is still held, whatever the drop counter says — and the drop counter says a great
-     * deal, because age eviction runs on every push.
-     */
-    lostSince(cursor) {
-        return this.#lastScarceLossT !== undefined && this.#lastScarceLossT >= cursor;
-    }
-    /** First churn event after the head, or -1 if none within the bounded scan (keeps eviction cheap). */
-    #findChurnAfterHead() {
-        const end = Math.min(this.#events.length, this.#head + CHURN_SCAN_LIMIT);
-        for (let i = this.#head + 1; i < end; i++) {
-            if (CHURN_TYPES.has(this.#events[i]?.type ?? ''))
-                return i;
-        }
-        return -1;
-    }
-    /** Snapshot of buffer health for the agent — live events held and cumulative drops since connect. */
-    bufferHealth() {
-        return { total: this.#liveCount(), dropped: this.#droppedCount };
-    }
-}

package/dist/events/split-text-miss.d.ts

@@ -1,32 +0,0 @@
-/**
- * Turning "no element matched {text: …}" into something an agent can act on, when the string IS here.
- *
- * `by: text` matches an element's own text nodes. A label rendered across several children —
- * `v-html`, one `<span>` per word, a highlighted substring — is on the page and matches nothing, and
- * the verdict is byte-identical to the one for an element that never rendered.
- *
- * That equivalence is the expensive part. Reported from the field: `act_and_wait` returned
- * `effect.appeared` containing `"Move to Reticle Repro Folder"`, the `until` predicate in the SAME
- * call searched for that string and failed, and the drive ended in a bug report against an app that
- * had rendered correctly. `appeared` concatenates an added subtree while `text` reads direct text
- * only, so the channel an agent is most likely to copy from produces the one locator this query
- * cannot resolve.
- *
- * Naming the container ends it in one step: `ref` is a locator, and a scoped text predicate with
- * `self: true` checks the container's combined subtree text. The recovery is a predicate the agent
- * can paste rather than another guess, and it is serialized as JSON so the schema test can parse it.
- */
-/** The container descriptor the browser attaches to a missed text query. */
-interface SplitTextOwner {
-    ref?: string;
-    role?: string;
-    name?: string;
-}
-/**
- * The "…but it IS here, split across children" clause, or undefined when there is nothing to say.
- *
- * Undefined — not a vaguer sentence — when the browser found no container: an ordinary miss keeps the
- * short message it already had. A clause that fires on every failure stops carrying information.
- */
-export declare function describeSplitTextMiss(owner: SplitTextOwner | undefined, searchedText?: string): string | undefined;
-export {};

package/dist/events/split-text-miss.js

@@ -1,51 +0,0 @@
-/**
- * Turning "no element matched {text: …}" into something an agent can act on, when the string IS here.
- *
- * `by: text` matches an element's own text nodes. A label rendered across several children —
- * `v-html`, one `<span>` per word, a highlighted substring — is on the page and matches nothing, and
- * the verdict is byte-identical to the one for an element that never rendered.
- *
- * That equivalence is the expensive part. Reported from the field: `act_and_wait` returned
- * `effect.appeared` containing `"Move to Reticle Repro Folder"`, the `until` predicate in the SAME
- * call searched for that string and failed, and the drive ended in a bug report against an app that
- * had rendered correctly. `appeared` concatenates an added subtree while `text` reads direct text
- * only, so the channel an agent is most likely to copy from produces the one locator this query
- * cannot resolve.
- *
- * Naming the container ends it in one step: `ref` is a locator, and a scoped text predicate with
- * `self: true` checks the container's combined subtree text. The recovery is a predicate the agent
- * can paste rather than another guess, and it is serialized as JSON so the schema test can parse it.
- */
-import { PredicateKind } from '@reticlehq/core';
-/** Enough of the label to recognise it; the message is read in a tool result, not a log. */
-const MAX_TEXT = 60;
-/** What the container is, in the fewest words that still identify it on the page. */
-function nameOf(owner) {
-    const name = owner.name !== undefined && owner.name.length > 0 ? owner.name : undefined;
-    const role = owner.role !== undefined && owner.role.length > 0 ? owner.role : 'element';
-    return name === undefined ? role : `${role} '${truncate(name)}'`;
-}
-function truncate(value) {
-    return value.length > MAX_TEXT ? `${value.slice(0, MAX_TEXT)}…` : value;
-}
-/**
- * The "…but it IS here, split across children" clause, or undefined when there is nothing to say.
- *
- * Undefined — not a vaguer sentence — when the browser found no container: an ordinary miss keeps the
- * short message it already had. A clause that fires on every failure stops carrying information.
- */
-export function describeSplitTextMiss(owner, searchedText) {
-    if (owner === undefined)
-        return undefined;
-    const where = nameOf(owner);
-    const scope = owner.ref !== undefined && owner.ref.length > 0 ? owner.ref : undefined;
-    const recovery = scope === undefined || searchedText === undefined
-        ? 'scope to that container and match it as a whole'
-        : `retry as ${JSON.stringify({
-            kind: PredicateKind.TEXT,
-            contains: searchedText,
-            scope,
-            self: true,
-        })}`;
-    return `that text IS on the page, split across the children of ${where} — no single element's own text carries it, so no text query can match it; ${recovery}`;
-}

package/dist/events/stale-response.d.ts

@@ -1,3 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-import type { OwnContradiction } from './contradictions.js';
-export declare function findStaleResponses(events: readonly ReticleEvent[]): OwnContradiction[];