@reticlehq/server 2.14.0 → 3.2.0

package/dist/surface/tools/read/query-windowed.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Finding a row a windowed list has not rendered — and saying so when we have not.
+ *
+ * ── THE DEFECT ──────────────────────────────────────────────────────────────────────────────────
+ * `react-window` and friends render only the rows on screen. A query walks the DOM, so it is looking
+ * at a fraction of the list and answers "no match" for a row that exists. An agent reads that as
+ * "the element is not there" and moves on — a FALSE NEGATIVE manufactured by the tool rather than
+ * found in the app, which is the failure this product exists to refuse.
+ *
+ * The remedy already existed as `reticle_scroll_to`, and that was the other half of the problem: it
+ * is not advertised on the default surface, so the agent that needed it could not see it and had no
+ * way to learn it existed. A capability reachable only by already knowing about it is not reachable.
+ *
+ * The SCROLLING half lives in `portal/input/scroll-find.ts`, because it drives the page and this
+ * directory must not reach into `input/` — doing so completed a mutual pair, and two directories
+ * that need each other cannot be read, moved or tested apart. Shaping an answer and scrolling a list
+ * are different jobs anyway; the guard made that visible before it was a habit.
+ *
+ * ── WHY OPT-IN, NOT AUTOMATIC ───────────────────────────────────────────────────────────────────
+ * `reticle_look` promises "Reads only — nothing here changes the app". Scrolling moves the viewport
+ * and mounts rows, so folding it in silently would rescue the miss by quietly breaking the guarantee
+ * — trading a false negative for an unannounced side effect on a tool whose whole contract is that
+ * it has none. Instead: the default stays a pure read, a miss says WHAT IT SEARCHED, and the search
+ * that scrolls is one flag away on the same advertised tool.
+ *
+ * That ordering matters. The note is what removes the false negative; the flag is only what makes
+ * the note actionable.
+ */
+/**
+ * Said on a miss, and ONLY on a miss.
+ *
+ * Unconditional rather than guessing whether this page has a windowed list: deciding that would cost
+ * a round trip to measure scroll containers, and a guess dressed as a fact is what the rest of this
+ * file is about. The sentence is true of every miss — a query searched the rendered nodes — so it
+ * informs without claiming to know why nothing matched.
+ */
+export declare const RENDERED_ONLY_NOTE: string;
+/**
+ * Attach the note when a query matched nothing.
+ *
+ * Leaves an existing `note` alone: the read path already uses that field to explain a capped or
+ * truncated result, and overwriting it would replace a fact about THIS answer with a general remark.
+ */
+export declare function noteRenderedOnly(result: unknown): unknown;
+/**
+ * Everything that turns a raw query answer into this tool's answer: paginate, note a miss, cost it.
+ *
+ * One function rather than three nested calls at the call site. The order is not arbitrary — the
+ * note is attached AFTER pagination, so "nothing matched" means nothing matched on the page rather
+ * than nothing survived the page limit, and the size cost is measured last because it measures what
+ * is actually sent by the CALLER — `withSizeCost` is applied there, not here, because this directory
+ * is a pure leaf that reaches nothing, and the reach guard is right to keep it that way.
+ */
+export declare function shapeQueryResult(result: unknown, args: Record<string, unknown>): unknown;

package/dist/surface/tools/read/query-windowed.js

@@ -0,0 +1,75 @@
+/**
+ * Finding a row a windowed list has not rendered — and saying so when we have not.
+ *
+ * ── THE DEFECT ──────────────────────────────────────────────────────────────────────────────────
+ * `react-window` and friends render only the rows on screen. A query walks the DOM, so it is looking
+ * at a fraction of the list and answers "no match" for a row that exists. An agent reads that as
+ * "the element is not there" and moves on — a FALSE NEGATIVE manufactured by the tool rather than
+ * found in the app, which is the failure this product exists to refuse.
+ *
+ * The remedy already existed as `reticle_scroll_to`, and that was the other half of the problem: it
+ * is not advertised on the default surface, so the agent that needed it could not see it and had no
+ * way to learn it existed. A capability reachable only by already knowing about it is not reachable.
+ *
+ * The SCROLLING half lives in `portal/input/scroll-find.ts`, because it drives the page and this
+ * directory must not reach into `input/` — doing so completed a mutual pair, and two directories
+ * that need each other cannot be read, moved or tested apart. Shaping an answer and scrolling a list
+ * are different jobs anyway; the guard made that visible before it was a habit.
+ *
+ * ── WHY OPT-IN, NOT AUTOMATIC ───────────────────────────────────────────────────────────────────
+ * `reticle_look` promises "Reads only — nothing here changes the app". Scrolling moves the viewport
+ * and mounts rows, so folding it in silently would rescue the miss by quietly breaking the guarantee
+ * — trading a false negative for an unannounced side effect on a tool whose whole contract is that
+ * it has none. Instead: the default stays a pure read, a miss says WHAT IT SEARCHED, and the search
+ * that scrolls is one flag away on the same advertised tool.
+ *
+ * That ordering matters. The note is what removes the false negative; the flag is only what makes
+ * the note actionable.
+ */
+import { asNumber } from '@reticlehq/core';
+import { paginateQueryResult } from './query-paginate.js';
+/**
+ * Said on a miss, and ONLY on a miss.
+ *
+ * Unconditional rather than guessing whether this page has a windowed list: deciding that would cost
+ * a round trip to measure scroll containers, and a guess dressed as a fact is what the rest of this
+ * file is about. The sentence is true of every miss — a query searched the rendered nodes — so it
+ * informs without claiming to know why nothing matched.
+ */
+export const RENDERED_ONLY_NOTE = 'Searched the RENDERED nodes only. A windowed list (react-window and similar) mounts just the rows ' +
+    'on screen, so a row that exists off-screen does not match. Scroll the list with ' +
+    'reticle_act { action: "scroll" } and search again.';
+/**
+ * Attach the note when a query matched nothing.
+ *
+ * Leaves an existing `note` alone: the read path already uses that field to explain a capped or
+ * truncated result, and overwriting it would replace a fact about THIS answer with a general remark.
+ */
+export function noteRenderedOnly(result) {
+    if (typeof result !== 'object' || null === result)
+        return result;
+    const shaped = result;
+    const matched = Array.isArray(shaped.elements)
+        ? shaped.elements.length
+        : 'number' === typeof shaped.count
+            ? shaped.count
+            : undefined;
+    if (0 !== matched)
+        return result;
+    if ('string' === typeof shaped.note && shaped.note.length > 0)
+        return result;
+    return { ...result, note: RENDERED_ONLY_NOTE };
+}
+/**
+ * Everything that turns a raw query answer into this tool's answer: paginate, note a miss, cost it.
+ *
+ * One function rather than three nested calls at the call site. The order is not arbitrary — the
+ * note is attached AFTER pagination, so "nothing matched" means nothing matched on the page rather
+ * than nothing survived the page limit, and the size cost is measured last because it measures what
+ * is actually sent by the CALLER — `withSizeCost` is applied there, not here, because this directory
+ * is a pure leaf that reaches nothing, and the reach guard is right to keep it that way.
+ */
+export function shapeQueryResult(result, args) {
+    const paginated = paginateQueryResult(result, asNumber(args['limit']), true === args['count_only']);
+    return noteRenderedOnly(paginated);
+}

package/dist/surface/tools/read/snapshot-delta.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Server-side snapshot delta — return only what CHANGED since the agent's last look.
+ *
+ * An agent that re-reads a full accessibility tree every look accumulates tens of thousands of
+ * tokens of STALE structure over a session, and then starts naming selectors that no longer exist.
+ * The agent-facing cost is the MCP result it reads, not the internal WS payload, so computing the
+ * delta here and returning only added/removed lines cuts the tokens the model spends AND removes the
+ * stale full tree. Reuses the same normalize+diff as the baseline layer, so "what changed" means the
+ * same thing everywhere.
+ *
+ * Pure decision (`snapshotDelta`) + a small route-invalidated cache (`SnapshotCache`). A route change
+ * invalidates the prior snapshot (a diff across pages would be meaningless), so the next snapshot
+ * returns full — never a misleading cross-page delta.
+ */
+/**
+ * Pure: was the prior snapshot of this scope both RECENT and SMALLER than this one? If so, the
+ * earlier reading was very likely taken mid-load — content arrived in the gap between the two calls
+ * — and any presence-grade conclusion drawn from that earlier snapshot ("this route renders
+ * nothing") is suspect. Silent otherwise: a stale prior or a page that shrank (or stayed the same
+ * size) is not this trap.
+ */
+export declare function snapshotGrowthNote(prior: {
+    tree: string;
+    atMs: number;
+} | undefined, nextTree: string, nowMs: number, windowMs?: number): string | undefined;
+export declare const SnapshotDeltaMode: {
+    readonly FULL: "full";
+    readonly DELTA: "delta";
+    readonly UNCHANGED: "unchanged";
+};
+export type SnapshotDeltaMode = (typeof SnapshotDeltaMode)[keyof typeof SnapshotDeltaMode];
+interface SnapshotDelta {
+    added: string[];
+    removed: string[];
+    changed: string[];
+    addedCount: number;
+    removedCount: number;
+}
+/** Where focus moved, when it moved. Absent fields mean nothing held focus on that side. */
+interface FocusChange {
+    from?: string;
+    to?: string;
+}
+type DeltaDecision = {
+    mode: typeof SnapshotDeltaMode.FULL;
+} | {
+    mode: typeof SnapshotDeltaMode.UNCHANGED;
+    focusChanged?: FocusChange;
+} | {
+    mode: typeof SnapshotDeltaMode.DELTA;
+    delta: SnapshotDelta;
+    focusChanged?: FocusChange;
+};
+/** Pure: decide full vs delta vs unchanged given the previous tree (same route) and the next tree. */
+export declare function snapshotDelta(prevTree: string | undefined, nextTree: string): DeltaDecision;
+/** Per-(session,scope,mode) last-snapshot cache. Route-aware: a route change invalidates the entry. */
+export declare class SnapshotCache {
+    #private;
+    constructor(max?: number, now?: () => number);
+    /** True when an entry exists for this key (regardless of route match). */
+    has(key: string): boolean;
+    /** The clock this cache was constructed with — callers compare against it so `remember`'s
+     * timestamp and a caller's "now" can never drift onto two different clocks. */
+    now(): number;
+    /** Last tree for this key IF the route still matches; undefined when absent or route changed. */
+    recall(key: string, route: string): string | undefined;
+    /**
+     * The last remembered tree for this key AND when it was remembered, IF the route still matches.
+     * Same route-gating as `recall` — a route change makes the prior entry meaningless for comparison,
+     * not just for diffing.
+     */
+    priorEntry(key: string, route: string): {
+        tree: string;
+        atMs: number;
+    } | undefined;
+    remember(key: string, route: string, tree: string): void;
+}
+export declare function snapshotCacheKey(sessionId: string, scope: string, mode: string): string;
+interface SnapshotDeltaOpts {
+    sessionId: string;
+    scope: string;
+    mode: string;
+    diff: boolean;
+}
+/**
+ * Shape a raw snapshot result for the agent: when `diff` is requested and a same-route prior
+ * snapshot exists, return only the delta (or `unchanged`) instead of the full tree. Always updates
+ * the cache. Non-object/errorless results pass through. The cache is the only state; the decision is
+ * the pure `snapshotDelta`.
+ */
+export declare function applySnapshotDelta(raw: unknown, opts: SnapshotDeltaOpts, cache: SnapshotCache): unknown;
+export {};

package/dist/surface/tools/read/snapshot-delta.js

@@ -0,0 +1,356 @@
+/**
+ * Server-side snapshot delta — return only what CHANGED since the agent's last look.
+ *
+ * An agent that re-reads a full accessibility tree every look accumulates tens of thousands of
+ * tokens of STALE structure over a session, and then starts naming selectors that no longer exist.
+ * The agent-facing cost is the MCP result it reads, not the internal WS payload, so computing the
+ * delta here and returning only added/removed lines cuts the tokens the model spends AND removes the
+ * stale full tree. Reuses the same normalize+diff as the baseline layer, so "what changed" means the
+ * same thing everywhere.
+ *
+ * Pure decision (`snapshotDelta`) + a small route-invalidated cache (`SnapshotCache`). A route change
+ * invalidates the prior snapshot (a diff across pages would be meaningless), so the next snapshot
+ * returns full — never a misleading cross-page delta.
+ */
+/**
+ * Identity for comparison, ref for action.
+ *
+ * The delta path used `normalizeLines` from the baseline layer, which strips the ref marker on
+ * purpose — a ref stored in a baseline would make every later diff noisy. Correct there, wrong here:
+ * every delta line came back as `- button "Row actions"` with no ref, and acting needs a ref, so the
+ * full snapshot had to be taken anyway. The diff call cost tokens and bought nothing. One helper, two
+ * callers, opposite requirements — so this path keeps the ref-stripped line as the KEY and emits the
+ * ORIGINAL line with its ref.
+ *
+ * Focus is stripped from the key too. It rides in the line as `[focused]`, alone or comma-joined with
+ * other states, so a focus move used to surface as one line removed and its twin added — structural
+ * change reported where nothing had been added at all. Focus is a property OF a line, so it gets its
+ * own field. Only focus is exempt: `disabled` moving is a real change and must still show.
+ */
+/** The ref marker, as `formatLine` writes it. Bounded quantifier: `\s*` backtracks polynomially. */
+const REF_MARKER = /\s?\(ref=e\d+\)/;
+/** The state bracket — ` [disabled,checked,expanded,focused]` — and the one state that is not structural. */
+const STATE_BRACKET = /\s\[([a-z,]+)\]$/;
+const FOCUSED_STATE = 'focused';
+/** True when this line carries focus. */
+function isFocused(line) {
+    return true === STATE_BRACKET.exec(line)?.[1]?.split(',').includes(FOCUSED_STATE);
+}
+/** The same line with focus removed — and the bracket dropped when focus was all it held. */
+function withoutFocus(line) {
+    const match = STATE_BRACKET.exec(line);
+    const states = match?.[1];
+    if (null === match || undefined === match || undefined === states)
+        return line;
+    const rest = states.split(',').filter((s) => s !== FOCUSED_STATE);
+    const head = line.slice(0, match.index);
+    return 0 === rest.length ? head : `${head} [${rest.join(',')}]`;
+}
+/** What makes two lines "the same element" for diffing: no ref, no focus, no surrounding space. */
+function deltaKey(line) {
+    return withoutFocus(line.replace(REF_MARKER, '')).trim();
+}
+function deltaLines(tree) {
+    return tree
+        .split('\n')
+        .map((line) => ({ key: deltaKey(line), text: withoutFocus(line).trim() }))
+        .filter((line) => line.key.length > 0);
+}
+/**
+ * Multiset diff on the key, emitting the original text.
+ *
+ * Multiset rather than set because duplicate labels are the norm — twelve identical `Row actions`
+ * buttons — and the count is the only thing that says how many left. Emitting the ORIGINAL text is
+ * what finally tells them apart: with refs, "which twelve" has an answer.
+ */
+/** Extract the ref marker value from a text line, or undefined if absent. */
+function refOf(text) {
+    return REF_MARKER.exec(text)?.[0]?.trim();
+}
+/** Extract the role (first word after the bullet) from a snapshot line — the structural type that must match. */
+function roleOf(text) {
+    return (text
+        .trimStart()
+        .replace(/^-\s*/, '')
+        .split(/[\s"(]/)[0] ?? '');
+}
+function diffKeyed(prev, next) {
+    const bucket = (lines) => {
+        const map = new Map();
+        for (const line of lines) {
+            const existing = map.get(line.key);
+            if (existing === undefined)
+                map.set(line.key, [line.text]);
+            else
+                existing.push(line.text);
+        }
+        return map;
+    };
+    const before = bucket(prev);
+    const after = bucket(next);
+    const removed = [];
+    const added = [];
+    for (const key of new Set([...before.keys(), ...after.keys()])) {
+        const was = before.get(key) ?? [];
+        const now = after.get(key) ?? [];
+        // Pair the SAME REF first. Twelve identical `Row actions` buttons are one key, and the ref is the
+        // only thing that says which of them left — an end-of-list surplus would name an arbitrary one.
+        const survived = new Set(now);
+        const wentOrChanged = was.filter((text) => !survived.has(text));
+        const arrivedOrChanged = now.filter((text) => !new Set(was).has(text));
+        // Whatever is left over on both sides is the SAME element with a re-minted ref (a re-render, or a
+        // navigation that restarts the sequence). Pairing those off is what stops a ref change reading as
+        // a removal plus an addition; only the count difference is a real structural change.
+        const paired = Math.min(wentOrChanged.length, arrivedOrChanged.length);
+        removed.push(...wentOrChanged.slice(paired));
+        added.push(...arrivedOrChanged.slice(paired));
+    }
+    return { removed, added };
+}
+/**
+ * Same ref AND same role in both added and removed = value change, not a structural
+ * arrival/departure. Refs alone are not stable identities — they are re-minted on re-render — so a
+ * removed button and an added textbox sharing a ref must stay in their respective lists.
+ */
+function extractChanged(added, removed) {
+    const addedByRef = new Map();
+    for (const [i, text] of added.entries()) {
+        const ref = refOf(text);
+        if (ref !== undefined)
+            addedByRef.set(ref, { idx: i, text, role: roleOf(text) });
+    }
+    const changedIndicesInAdded = new Set();
+    const changedIndicesInRemoved = new Set();
+    const changed = [];
+    for (const [i, text] of removed.entries()) {
+        const ref = refOf(text);
+        if (ref === undefined)
+            continue;
+        const match = addedByRef.get(ref);
+        if (match !== undefined && match.role === roleOf(text)) {
+            changed.push(match.text);
+            changedIndicesInAdded.add(match.idx);
+            changedIndicesInRemoved.add(i);
+            addedByRef.delete(ref);
+        }
+    }
+    return {
+        added: added.filter((_, i) => !changedIndicesInAdded.has(i)),
+        removed: removed.filter((_, i) => !changedIndicesInRemoved.has(i)),
+        changed,
+    };
+}
+/**
+ * Where focus sits now: the line to show, plus the identity to compare it BY.
+ *
+ * These have to be two different things. Comparing the rendered lines said focus had moved whenever
+ * the focused element merely changed — typing into a focused textbox rewrites its `[value=...]`, so
+ * `from` and `to` came back naming the same element with different text. Focus identity is the
+ * ELEMENT, so the comparison is on the ref, and the line is only what gets displayed. Where there is
+ * no ref to compare (a non-interactive line), the ref-stripped key stands in.
+ *
+ * Read from the raw tree so a line the diff filters out cannot silently swallow the focus report.
+ */
+function focusedLine(tree) {
+    const focused = tree.split('\n').find((line) => isFocused(line));
+    if (focused === undefined)
+        return undefined;
+    const text = withoutFocus(focused).trim();
+    return { id: REF_MARKER.exec(focused)?.[0]?.trim() ?? deltaKey(focused), text };
+}
+/**
+ * How recent a smaller prior snapshot has to be for its growth to be worth flagging (#787) — long
+ * enough to catch the "route committed, then hydrated" window the bug report describes (hundreds of
+ * ms up to a couple of seconds), short enough that an unrelated LATER snapshot of a page that simply
+ * grew through normal use (an infinite-scroll load, a live feed) doesn't get blamed on load timing.
+ */
+const GROWTH_NOTE_WINDOW_MS = 5000;
+/** Non-empty lines only — a blank line in the tree text is formatting, not a node. */
+function nodeCount(tree) {
+    return tree.split('\n').filter((line) => '' !== line.trim()).length;
+}
+/**
+ * Pure: was the prior snapshot of this scope both RECENT and SMALLER than this one? If so, the
+ * earlier reading was very likely taken mid-load — content arrived in the gap between the two calls
+ * — and any presence-grade conclusion drawn from that earlier snapshot ("this route renders
+ * nothing") is suspect. Silent otherwise: a stale prior or a page that shrank (or stayed the same
+ * size) is not this trap.
+ */
+export function snapshotGrowthNote(prior, nextTree, nowMs, windowMs = GROWTH_NOTE_WINDOW_MS) {
+    if (prior === undefined)
+        return undefined;
+    const elapsedMs = nowMs - prior.atMs;
+    if (elapsedMs < 0 || elapsedMs > windowMs)
+        return undefined;
+    const priorCount = nodeCount(prior.tree);
+    const nextCount = nodeCount(nextTree);
+    if (nextCount <= priorCount)
+        return undefined;
+    return (`this scope had ${String(priorCount)} nodes ${String(elapsedMs)}ms ago and has ${String(nextCount)} now — ` +
+        'content likely arrived after your last look; a presence conclusion drawn from that earlier snapshot may have been taken mid-load');
+}
+export const SnapshotDeltaMode = {
+    FULL: 'full',
+    DELTA: 'delta',
+    UNCHANGED: 'unchanged',
+};
+/** Pure: decide full vs delta vs unchanged given the previous tree (same route) and the next tree. */
+export function snapshotDelta(prevTree, nextTree) {
+    if (prevTree === undefined)
+        return { mode: SnapshotDeltaMode.FULL };
+    const raw = diffKeyed(deltaLines(prevTree), deltaLines(nextTree));
+    const { added, removed, changed } = extractChanged(raw.added, raw.removed);
+    const before = focusedLine(prevTree);
+    const now = focusedLine(nextTree);
+    // Reported only on a MOVE. Repeating "focus is still here" every turn is the noise the delta exists
+    // to remove, and an absent field is how the agent knows nothing happened.
+    const focusChanged = before?.id === now?.id
+        ? undefined
+        : {
+            ...(before === undefined ? {} : { from: before.text }),
+            ...(now === undefined ? {} : { to: now.text }),
+        };
+    const moved = focusChanged === undefined ? {} : { focusChanged };
+    if (0 === added.length && 0 === removed.length && 0 === changed.length) {
+        return { mode: SnapshotDeltaMode.UNCHANGED, ...moved };
+    }
+    return {
+        mode: SnapshotDeltaMode.DELTA,
+        delta: {
+            added,
+            removed,
+            changed,
+            addedCount: added.length,
+            removedCount: removed.length,
+        },
+        ...moved,
+    };
+}
+const DEFAULT_MAX_ENTRIES = 50;
+/** Per-(session,scope,mode) last-snapshot cache. Route-aware: a route change invalidates the entry. */
+export class SnapshotCache {
+    #map = new Map();
+    #max;
+    #now;
+    constructor(max = DEFAULT_MAX_ENTRIES, now = Date.now) {
+        this.#max = max;
+        this.#now = now;
+    }
+    /** True when an entry exists for this key (regardless of route match). */
+    has(key) {
+        return this.#map.has(key);
+    }
+    /** The clock this cache was constructed with — callers compare against it so `remember`'s
+     * timestamp and a caller's "now" can never drift onto two different clocks. */
+    now() {
+        return this.#now();
+    }
+    /** Last tree for this key IF the route still matches; undefined when absent or route changed. */
+    recall(key, route) {
+        return this.priorEntry(key, route)?.tree;
+    }
+    /**
+     * The last remembered tree for this key AND when it was remembered, IF the route still matches.
+     * Same route-gating as `recall` — a route change makes the prior entry meaningless for comparison,
+     * not just for diffing.
+     */
+    priorEntry(key, route) {
+        const entry = this.#map.get(key);
+        if (entry === undefined || entry.route !== route)
+            return undefined;
+        // LRU touch: re-insert so a HOT key isn't evicted while colder, more-recently-added keys survive
+        // (Map preserves insertion order; delete+set moves it to the most-recently-used end).
+        this.#map.delete(key);
+        this.#map.set(key, entry);
+        return { tree: entry.tree, atMs: entry.atMs };
+    }
+    remember(key, route, tree) {
+        // Re-insert to move the key to the most-recently-used end (a plain set keeps its old position).
+        this.#map.delete(key);
+        if (this.#map.size >= this.#max) {
+            const oldest = this.#map.keys().next().value;
+            if (oldest !== undefined)
+                this.#map.delete(oldest);
+        }
+        this.#map.set(key, { route, tree, atMs: this.#now() });
+    }
+}
+/**
+ * Joins the cache-key parts. NUL because `scope` is a caller-supplied selector that may contain any
+ * printable character — a printable separator could be forged into a colliding key. Written as an
+ * ESCAPE, never as a literal NUL byte: a raw one makes this file read as binary to grep/diff tooling,
+ * which silently hid every symbol in it from repo-wide searches.
+ */
+const CACHE_KEY_SEPARATOR = '\u0000';
+export function snapshotCacheKey(sessionId, scope, mode) {
+    return `${sessionId}${CACHE_KEY_SEPARATOR}${scope}${CACHE_KEY_SEPARATOR}${mode}`;
+}
+/** Said out loud when a diff was computed over a capped tree, so "unchanged" cannot mean "nothing happened". */
+const CAPPED_DIFF_NOTE = 'this diff covers only the first N nodes of the page (the snapshot hit its cap), so "unchanged" means "unchanged in the part that was captured" — narrow with `scope` to see the rest';
+/**
+ * Shape a raw snapshot result for the agent: when `diff` is requested and a same-route prior
+ * snapshot exists, return only the delta (or `unchanged`) instead of the full tree. Always updates
+ * the cache. Non-object/errorless results pass through. The cache is the only state; the decision is
+ * the pure `snapshotDelta`.
+ */
+export function applySnapshotDelta(raw, opts, cache) {
+    if (typeof raw !== 'object' || null === raw)
+        return raw;
+    const r = raw;
+    // Only shape genuine snapshots (have a string tree). An error envelope passes through untouched.
+    if (typeof r['tree'] !== 'string')
+        return raw;
+    const tree = r['tree'];
+    const status = 'object' === typeof r['status'] && r['status'] !== null
+        ? r['status']
+        : {};
+    const route = 'string' === typeof status['route'] ? status['route'] : '';
+    const key = snapshotCacheKey(opts.sessionId, opts.scope, opts.mode);
+    // Read the growth signal BEFORE remember() overwrites the entry it compares against — needed on
+    // both branches below (#787), not only the diff:true path, since the reporter's own repro used a
+    // plain snapshot the second time.
+    const priorEntry = cache.priorEntry(key, route);
+    const growthNote = snapshotGrowthNote(priorEntry, tree, cache.now());
+    const growth = growthNote === undefined ? {} : { growthWarning: growthNote };
+    if (!opts.diff) {
+        cache.remember(key, route, tree);
+        return { ...r, ...growth };
+    }
+    const prev = priorEntry?.tree;
+    const hadEntry = cache.has(key);
+    cache.remember(key, route, tree);
+    const decision = snapshotDelta(prev, tree);
+    if (decision.mode === SnapshotDeltaMode.FULL) {
+        const reason = hadEntry ? 'route changed' : 'first snapshot for this route';
+        return { ...r, mode: SnapshotDeltaMode.FULL, reason, ...growth };
+    }
+    // The walk stops at a node cap and returns a DOCUMENT-ORDER PREFIX, so two capped snapshots of a
+    // large page are identical whenever the change happened past the cap — and "unchanged" is then a
+    // statement about the cap, not about the page. Carried through on both branches: a delta computed
+    // over a prefix is real but not exhaustive either.
+    const capped = true === r['truncated'] ? { truncated: true, note: CAPPED_DIFF_NOTE } : {};
+    // Spread onto BOTH branches. A value computed correctly and declared nowhere on the way out is the
+    // defect shape that hit this release five separate times: nothing throws, no test reddens, the
+    // field is simply absent forever.
+    const moved = decision.focusChanged === undefined ? {} : { focusChanged: decision.focusChanged };
+    if (decision.mode === SnapshotDeltaMode.UNCHANGED) {
+        return {
+            mode: SnapshotDeltaMode.UNCHANGED,
+            status: r['status'],
+            ...moved,
+            ...capped,
+            ...growth,
+        };
+    }
+    const { changed, ...structuralDelta } = decision.delta;
+    const changedField = changed.length > 0 ? { changed, changedCount: changed.length } : {};
+    return {
+        mode: SnapshotDeltaMode.DELTA,
+        delta: structuralDelta,
+        ...changedField,
+        status: r['status'],
+        ...moved,
+        ...capped,
+        ...growth,
+    };
+}