@reticlehq/browser 2.11.0 → 2.13.0

package/dist/dom/snapshot.js

@@ -3,7 +3,7 @@ import { capturedRootOf } from './shadow-registry.js';
 import { isFrame } from './realm.js';
 import { getAccessibleName, getRole, getStates, getValue, isVisible } from './a11y.js';
 import { refs } from './refs.js';
-import { isIgnored } from './dom-ignore.js';
+import { isIgnored, isReticleOverlay } from './dom-ignore.js';
 const INTERACTIVE = new Set([
     'button',
     'link',
@@ -55,6 +55,16 @@ function directText(el) {
     const collapsed = out.replace(/\s+/g, ' ').trim();
     return collapsed.length > TEXT_MAX ? `${collapsed.slice(0, TEXT_MAX)}…` : collapsed;
 }
+/**
+ * Cap on how many cut branches one snapshot names.
+ *
+ * A hostile or merely huge DOM can cut thousands of siblings at once (a non-virtualized grid does it
+ * routinely), and a frontier that large is neither affordable to send nor useful to re-read one at a
+ * time. Fifty is well above what a real page's cut produces — the frontier is the branches at the
+ * node cap, not the nodes themselves — and small enough that the list stays a hint rather than a
+ * second snapshot. Past it the read declares `unreadOverflow` instead of quietly sending fewer.
+ */
+export const MAX_UNREAD_BRANCHES = 50;
 /** Cheap skips that need no computed style (tags, overlays, aria-hidden, [hidden]). */
 function skipEarly(el) {
     if (SKIP_TAGS.has(el.tagName.toLowerCase()))
@@ -77,8 +87,12 @@ function stateSuffix(el) {
 function formatLine(el, depth, role, name, layout) {
     const indent = '  '.repeat(depth);
     const value = getValue(el);
-    const namePart = name.length > 0 ? ` "${name}"` : '';
-    const refPart = INTERACTIVE.has(role) || name.length > 0 ? ` (ref=${refs.refFor(el)})` : '';
+    // A testid stands in for the accessible name when there is none. Including a role-less control and
+    // then printing it as a bare `- generic` is worse than leaving it out: it is visible and it cannot
+    // be addressed. This is the name its author gave it.
+    const label = name;
+    const namePart = label.length > 0 ? ` "${label}"` : '';
+    const refPart = INTERACTIVE.has(role) || label.length > 0 ? ` (ref=${refs.refFor(el)})` : '';
     const valuePart = value !== undefined && value.length > 0 ? ` [value="${value}"]` : '';
     const layoutPart = layout.length > 0 ? ` [${layout}]` : '';
     return `${indent}- ${role}${namePart}${refPart}${valuePart}${layoutPart}${stateSuffix(el)}`;
@@ -105,6 +119,16 @@ function layoutSignature(style) {
     }
     return '';
 }
+/** Record a cut branch on the frontier, declaring an overflow rather than shortening it silently. */
+function recordUnread(branches, ctx) {
+    for (const branch of branches) {
+        if (ctx.unread.length >= MAX_UNREAD_BRANCHES) {
+            ctx.unreadOverflow = true;
+            return;
+        }
+        ctx.unread.push(refs.refFor(branch));
+    }
+}
 /**
  * The children to walk under `parent`, piercing boundaries a plain `.children` misses: an OPEN shadow
  * root renders as part of the element (web components / design systems), and a SAME-ORIGIN iframe's
@@ -134,52 +158,118 @@ function pierceChildren(parent) {
     }
     return out;
 }
+/** Emit one element (if it earns a line) and descend into it. Split out of `walk` so the completion
+ * re-read can start AT a branch root — the node the truncated walk stopped just before emitting. */
+function visit(child, depth, ctx, inLive) {
+    if (skipEarly(child))
+        return;
+    // Resolve computed style ONCE per node (the dominant snapshot cost) and thread it into both the
+    // display-none skip and the layout signature — was two forced style resolutions per node.
+    const view = child.ownerDocument.defaultView;
+    const style = view !== null ? view.getComputedStyle(child) : null;
+    if (style !== null && 'none' === style.display)
+        return;
+    const role = getRole(child);
+    const name = getAccessibleName(child);
+    const interactive = INTERACTIVE.has(role);
+    // Announcements are exempt from leanness, and so is everything inside one: a live region whose
+    // message sits in a child element would otherwise be included as a contentless `- generic`.
+    const announce = inLive || announces(child, role);
+    const lean = ctx.mode === SnapshotMode.INTERACTIVE && !announce;
+    // A generic, unnamed container's own text content — only consulted outside INTERACTIVE mode,
+    // so the actionable-only view stays lean while FULL/meaningful views see content regressions.
+    const text = !lean && 'generic' === role && 0 === name.length ? directText(child) : '';
+    // Layout signature for grid/flex containers — makes CLS/layout regressions visible.
+    const layout = lean ? '' : layoutSignature(style);
+    // Actionable WITHOUT an interactive role, which is most of the real web.
+    //
+    // `interactive` is a role test, and a large share of production UI carries no roles at all.
+    // Measured on MarkText, a production Electron editor: `mode:"interactive"` returned an EMPTY tree
+    // where `mode:"full"` found 47 nodes, because its whole block picker is `<div>`s. An empty tree is
+    // indistinguishable from an empty page, and the tool description recommends this mode as the
+    // default — so the cheaper view told an agent there was nothing to drive.
+    //
+    // A `data-testid` ONLY. It is a handle its author put there to be driven, and it marks one element
+    // rather than a subtree.
+    //
+    // `cursor: pointer` was tried here as a second signal — it is how an app tells a HUMAN that a
+    // thing is clickable — and measured on MarkText it was a disaster: interactive went from 0 nodes
+    // and 72 tokens to 180 nodes and 870, against a FULL snapshot of 47 nodes and 424. The pointer
+    // cursor is inherited, so every wrapper div inside a clickable row matched, and the lean mode
+    // became twice the size of the complete one while adding nothing but nameless `- generic` lines.
+    // The mode's whole claim is that it is smaller; a signal that cannot tell a control from its
+    // ancestors cannot be used to decide what a control is.
+    // `data-testid` was tried here as a second signal, on the premise that it is a handle its author
+    // put there to be driven. Measured against our own instrumented bench app, the premise is false:
+    // the lean tree on its dashboard came to 16 nodes and 175 tokens, and EIGHT were display elements
+    // — kpi-deploys, kpi-success, kpi-p95, kpi-services, area-chart, activity-feed, brand. Half the
+    // "actionable" view was things nothing can act on, and the mode roughly doubled to carry them; the
+    // benchmark read it as a 4% verification-efficiency regression. A testid marks what a TEST cares
+    // about, which is a superset of what a driver can use.
+    //
+    // It did not even help the case it shipped for: MarkText's controls carry no testid. `leanSkipped`
+    // is what fixed that — an empty tree that says how many it passed over is no longer an empty page.
+    //
+    // `cursor: pointer` was tried too and was worse: interactive went from 0 nodes and 72 tokens to
+    // 180 and 870 against a FULL snapshot of 47/424, because the pointer cursor is inherited and every
+    // wrapper div inside a clickable row matched. A signal that cannot tell a control from its
+    // ancestors cannot decide what a control is.
+    const actionable = interactive;
+    // A testid still makes an element MEANINGFUL, so `full` keeps it and can name and address it. It
+    // just is not evidence that the element is ACTIONABLE, which is the only question lean mode asks.
+    const meaningful = actionable || role !== 'generic' || name.length > 0 || text.length > 0 || layout.length > 0;
+    const include = lean ? actionable : meaningful;
+    // Counted, not just skipped. An empty INTERACTIVE tree is indistinguishable from an empty page,
+    // and on a real app the difference is everything: MarkText's block picker is 20+ live controls
+    // that carry no role, no testid and no pointer cursor, so the lean view is empty while the app is
+    // full of things to drive. Knowing how many were passed over is what turns "" into "look again in
+    // full mode" — see the note the snapshot tool builds from this.
+    if (lean && !include && meaningful)
+        ctx.leanSkipped += 1;
+    if (include) {
+        ctx.nodes += 1;
+        ctx.lines.push(text.length > 0 && 0 === name.length && 0 === layout.length
+            ? formatTextLine(depth, text)
+            : formatLine(child, depth, role, name, layout));
+        walk(child, depth + 1, ctx, announce);
+    }
+    else {
+        walk(child, depth, ctx, announce);
+    }
+}
 function walk(parent, depth, ctx, inLive = false) {
     if (depth > ctx.maxDepth)
         return;
-    for (const child of pierceChildren(parent)) {
+    const children = pierceChildren(parent);
+    for (let index = 0; index < children.length; index += 1) {
         if (ctx.nodes >= ctx.maxNodes) {
             ctx.truncated = true;
+            // Everything from here on is unread, not absent. Naming the frontier is what makes the cut
+            // recoverable — see `unread` on SnapshotResult.
+            recordUnread(children.slice(index), ctx);
             return;
         }
-        if (skipEarly(child))
-            continue;
-        // Resolve computed style ONCE per node (the dominant snapshot cost) and thread it into both the
-        // display-none skip and the layout signature — was two forced style resolutions per node.
-        const view = child.ownerDocument.defaultView;
-        const style = view !== null ? view.getComputedStyle(child) : null;
-        if (style !== null && 'none' === style.display)
-            continue;
-        const role = getRole(child);
-        const name = getAccessibleName(child);
-        const interactive = INTERACTIVE.has(role);
-        // Announcements are exempt from leanness, and so is everything inside one: a live region whose
-        // message sits in a child element would otherwise be included as a contentless `- generic`.
-        const announce = inLive || announces(child, role);
-        const lean = ctx.mode === SnapshotMode.INTERACTIVE && !announce;
-        // A generic, unnamed container's own text content — only consulted outside INTERACTIVE mode,
-        // so the actionable-only view stays lean while FULL/meaningful views see content regressions.
-        const text = !lean && 'generic' === role && 0 === name.length ? directText(child) : '';
-        // Layout signature for grid/flex containers — makes CLS/layout regressions visible.
-        const layout = lean ? '' : layoutSignature(style);
-        const meaningful = interactive || role !== 'generic' || name.length > 0 || text.length > 0 || layout.length > 0;
-        const include = lean ? interactive : meaningful;
-        if (include) {
-            ctx.nodes += 1;
-            ctx.lines.push(text.length > 0 && 0 === name.length && 0 === layout.length
-                ? formatTextLine(depth, text)
-                : formatLine(child, depth, role, name, layout));
-            walk(child, depth + 1, ctx, announce);
-        }
-        else {
-            walk(child, depth, ctx, announce);
-        }
+        const child = children[index];
+        if (child !== undefined)
+            visit(child, depth, ctx, inLive);
     }
 }
+/**
+ * The APP's open dialogs. Reticle's own panels are excluded, always.
+ *
+ * The HUD's chat and report panels carry `role="dialog"` because that is the correct role for what
+ * they are — but they are OUR surface, not the application's. Once the presenter became visible to
+ * the tool surface (so that Reticle can be used to check its own HUD), every snapshot of every page
+ * started reporting `visibleDialogs: ["Reticle agent chat"]`, telling the agent a modal was up when
+ * the app had none. An agent that believes a dialog is open dismisses it before doing anything else,
+ * which is a wasted action at best and a dismissed REAL dialog at worst.
+ */
 function collectDialogs(root) {
     const nodes = root.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]');
     const names = [];
     for (const node of nodes) {
+        if (isReticleOverlay(node))
+            continue;
         if (isVisible(node))
             names.push(getAccessibleName(node) || '(unnamed dialog)');
     }
@@ -209,6 +299,11 @@ function overlayHidingPage(root) {
     const dialogs = document.body.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]');
     let modal;
     for (const d of dialogs) {
+        // Never OUR overlay. Reticle's HUD must not be able to explain the app's absence with itself:
+        // that turns "the page did not render" into "an overlay is covering it", which sends the reader
+        // to dismiss a panel that was never the problem.
+        if (isReticleOverlay(d))
+            continue;
         if (isVisible(d)) {
             modal = d;
             break;
@@ -255,16 +350,25 @@ export function buildSnapshot(options = {}) {
     const ctx = {
         lines: [],
         nodes: 0,
+        leanSkipped: 0,
         truncated: false,
         mode,
         maxNodes: options.maxNodes ?? 400,
         maxDepth: options.maxDepth ?? 20,
+        unread: [],
+        unreadOverflow: false,
     };
-    walk(root, 0, ctx);
+    if (true === options.includeRoot)
+        visit(root, 0, ctx, false);
+    else
+        walk(root, 0, ctx);
     return {
         tree: ctx.lines.join('\n'),
         status,
         nodes: ctx.nodes,
         truncated: ctx.truncated,
+        ...(ctx.leanSkipped > 0 ? { leanSkipped: ctx.leanSkipped } : {}),
+        ...(ctx.unread.length > 0 ? { unread: ctx.unread } : {}),
+        ...(ctx.unreadOverflow ? { unreadOverflow: true } : {}),
     };
 }

package/dist/edit-epoch.d.ts

@@ -0,0 +1,32 @@
+import { type RefRegistry } from './dom/refs.js';
+export declare class EditEpoch {
+    #private;
+    /** The registry is injected for the same reason the clock is: the interesting property is the
+     *  RELATION between when a ref was minted and when an edit landed, and a global has no seam. */
+    constructor(registry: RefRegistry);
+    /**
+     * How many hot updates this document has applied.
+     *
+     * `NO_EDITS_OBSERVED` means exactly that and never "none happened": most pages Reticle instruments
+     * have no channel that could report one, so absence here is UNKNOWN.
+     */
+    get current(): number;
+    /** Subscribe to a hot-update channel if one was handed in. Anything else is silently ignored —
+     *  no channel is the normal case, not an error. */
+    observe(hot: unknown): void;
+    /** Record that an update was applied, naming the files it changed (which may be none). */
+    applied(files: readonly string[]): void;
+    /**
+     * The refusal for a ref that no longer resolves — saying WHY when the page can tell us.
+     *
+     * The generic wording is untouched and stays at the front: it is already tuned, and the server's
+     * recovery table matches on it. When the ref predates the last hot update the diagnosis is
+     * appended, because "you edited TripCard.tsx and it re-rendered" is a next step and "that ref is
+     * stale" is a dead end. A ref minted AFTER the last update gets the generic message unchanged —
+     * blaming an edit for an ordinary post-click stale ref would be a confident wrong answer, which is
+     * worse than the vague right one.
+     */
+    staleRefMessage(ref: string): string;
+}
+/** The epoch of the page, paired with the process-wide ref registry it has to reason against. */
+export declare const editEpoch: EditEpoch;

package/dist/edit-epoch.js

@@ -0,0 +1,108 @@
+import { NO_EDITS_OBSERVED } from '@reticlehq/core';
+import { echoRef, refs } from './dom/refs.js';
+/**
+ * What the page can tell us about its own source being edited underneath it.
+ *
+ * The agent driving Reticle edits source and re-verifies in a loop. When an edit lands, the dev
+ * server hot-updates the module and the framework re-renders: DOM nodes are REPLACED, every ref the
+ * agent holds points at a detached node — and there was no navigation, so the document is the same
+ * one and `documentId` never moves. The agent got a generic "that ref is stale" and could not tell
+ * its own edit landing from a bug in the app it was verifying.
+ *
+ * DELIBERATELY NOT A BUILD INTEGRATION. Nothing here watches files, reads the user's repo or knows
+ * what a module graph is. The page is told by its own dev server that it hot-updated; this records
+ * that it happened and what it named, and that is the whole feature.
+ */
+/**
+ * Vite's "the update has been applied" event, on a hot context.
+ *
+ * `vite:afterUpdate` rather than `vite:beforeUpdate`: the point of the epoch is that the DOM has
+ * been replaced, and before the update it has not been yet.
+ *
+ * The SDK does NOT depend on Vite — it ships to Next, Electron, Tauri and plain pages, and it cannot
+ * read `import.meta.hot` of its own module in any of them (a dependency is pre-bundled by Vite's
+ * optimizer and gets no hot context at all). The channel is handed IN by whoever has one, and this
+ * name is the only Vite-shaped thing in the SDK.
+ */
+const HOT_UPDATE_APPLIED = 'vite:afterUpdate';
+/** How many changed files a refusal names before it stops being a diagnosis and starts being a list. */
+const MAX_NAMED_FILES = 3;
+/** The exact substring the server's recovery table keys off. Changing it silently unclassifies. */
+const STALE_REF_REFUSAL = 'no longer resolves to an element';
+/** The clause that turns a dead end into a diagnosis, and the one the server's table matches on. */
+const CODE_CHANGED = 'the code changed underneath it';
+/** Anything object-shaped, as a bag of unknowns. The payload comes from the page, so nothing about
+ *  its shape is guaranteed and every field has to be checked before it is read. */
+function fields(value) {
+    return null !== value && 'object' === typeof value
+        ? value
+        : undefined;
+}
+function isHotLike(value) {
+    return 'function' === typeof fields(value)?.['on'];
+}
+/** The file paths a hot-update payload named, narrowed from `unknown`. */
+function updatedPaths(payload) {
+    const updates = fields(payload)?.['updates'];
+    if (!Array.isArray(updates))
+        return [];
+    const paths = [];
+    for (const update of updates) {
+        const path = fields(update)?.['path'];
+        if ('string' === typeof path && path.length > 0 && !paths.includes(path))
+            paths.push(path);
+    }
+    return paths;
+}
+export class EditEpoch {
+    #epoch = NO_EDITS_OBSERVED;
+    #files = [];
+    #refs;
+    /** The registry is injected for the same reason the clock is: the interesting property is the
+     *  RELATION between when a ref was minted and when an edit landed, and a global has no seam. */
+    constructor(registry) {
+        this.#refs = registry;
+    }
+    /**
+     * How many hot updates this document has applied.
+     *
+     * `NO_EDITS_OBSERVED` means exactly that and never "none happened": most pages Reticle instruments
+     * have no channel that could report one, so absence here is UNKNOWN.
+     */
+    get current() {
+        return this.#epoch;
+    }
+    /** Subscribe to a hot-update channel if one was handed in. Anything else is silently ignored —
+     *  no channel is the normal case, not an error. */
+    observe(hot) {
+        if (!isHotLike(hot))
+            return;
+        hot.on(HOT_UPDATE_APPLIED, (payload) => this.applied(updatedPaths(payload)));
+    }
+    /** Record that an update was applied, naming the files it changed (which may be none). */
+    applied(files) {
+        this.#epoch += 1;
+        this.#files = files.slice(0, MAX_NAMED_FILES);
+        this.#refs.markEdited();
+    }
+    /**
+     * The refusal for a ref that no longer resolves — saying WHY when the page can tell us.
+     *
+     * The generic wording is untouched and stays at the front: it is already tuned, and the server's
+     * recovery table matches on it. When the ref predates the last hot update the diagnosis is
+     * appended, because "you edited TripCard.tsx and it re-rendered" is a next step and "that ref is
+     * stale" is a dead end. A ref minted AFTER the last update gets the generic message unchanged —
+     * blaming an edit for an ordinary post-click stale ref would be a confident wrong answer, which is
+     * worse than the vague right one.
+     */
+    staleRefMessage(ref) {
+        const generic = `ref '${echoRef(ref)}' ${STALE_REF_REFUSAL}`;
+        if (!this.#refs.mintedBeforeLastEdit(ref))
+            return generic;
+        const named = 0 === this.#files.length ? 'the page hot-updated' : `${this.#files.join(', ')} hot-updated`;
+        return (`${generic} — ${named} after this ref was taken, so ${CODE_CHANGED} and the framework ` +
+            'replaced the node. Query again for a fresh ref: this is your own edit landing, not the app failing.');
+    }
+}
+/** The epoch of the page, paired with the process-wide ref registry it has to reason against. */
+export const editEpoch = new EditEpoch(refs);

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { SESSION_AUTO } from '@reticlehq/core';
 export { setIgnoreSelectors } from './dom/dom-ignore.js';
 export { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/adapters.js';
 export type { ReticleAdapter, ComponentInfo, ComponentSource } from './registry/adapters.js';
-export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, } from './registry/stores.js';
+export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, sourceOwner, markAdapterSource, } from './registry/stores.js';
 export type { StoreGetter, StoreLike, StoreSubscribe } from './registry/stores.js';
 export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, recoilStore, svelteStore, piniaStore, pushStore, } from './registry/store-adapters.js';
 export type { QuerySnapshot, RecoilAtomSnapshot } from './registry/store-adapters.js';

package/dist/index.js

@@ -14,7 +14,11 @@ export { setIgnoreSelectors } from './dom/dom-ignore.js';
 // Adapter API (used by @reticlehq/react and other framework adapters).
 export { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/adapters.js';
 // Store registry: pull live framework/store state on demand.
-export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, } from './registry/stores.js';
+export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, 
+// Which name a store SOURCE is registered under. The React adapter discovers stores from the fiber
+// tree and needs this to tell "the app already wired this exact store" from "this is another one" —
+// a question neither the name nor the read value can answer.
+sourceOwner, markAdapterSource, } from './registry/stores.js';
 // Adapters for state libraries that do not natively expose `{getState, subscribe}`. zustand and Redux
 // need none of these; TanStack Query is the one that matters most, because a stale-cache bug fires no
 // request and renders a plausible value, so the cache is the only witness.

package/dist/observers/animation.js

@@ -3,6 +3,8 @@ import { refs } from '../dom/refs.js';
 import { isReticleOverlay } from '../dom/dom-ignore.js';
 /** Observe CSS animations + transitions and emit anim.start / anim.end. */
 export function installAnimation(emit) {
+    const ac = new AbortController();
+    const { signal } = ac;
     const onStart = (event) => {
         const target = event.target;
         // Skip Reticle's own HUD keyframes (reticle-pulse/reticle-shimmer/…) so observe/record never
@@ -23,12 +25,8 @@ export function installAnimation(emit) {
             emit(EventType.ANIM_END, { name: event.propertyName, kind: 'transition' }, refs.refFor(target));
         }
     };
-    document.addEventListener('animationstart', onStart, true);
-    document.addEventListener('animationend', onEnd, true);
-    document.addEventListener('transitionend', onTransitionEnd, true);
-    return () => {
-        document.removeEventListener('animationstart', onStart, true);
-        document.removeEventListener('animationend', onEnd, true);
-        document.removeEventListener('transitionend', onTransitionEnd, true);
-    };
+    document.addEventListener('animationstart', onStart, { capture: true, signal });
+    document.addEventListener('animationend', onEnd, { capture: true, signal });
+    document.addEventListener('transitionend', onTransitionEnd, { capture: true, signal });
+    return () => ac.abort();
 }

package/dist/observers/context-open.d.ts

@@ -0,0 +1,12 @@
+import type { Emit, Teardown } from './types.js';
+/**
+ * The page asked for ANOTHER browsing context — `window.open` — so the consequence of whatever was
+ * just clicked may live where this document's SDK cannot follow. An OAuth sign-in is the archetype:
+ * the POST succeeds, the popup carries the whole flow, and the original tab legitimately never
+ * changes (#508). Without this event the contradiction layer reads that shape as response-ignored,
+ * accusing the client of ignoring a response it handed to a window nobody can see.
+ *
+ * The wrap preserves the call exactly: same arguments, same return value, and a null/undefined
+ * first argument (the "open a blank tab" form) still emits, since a blank tab can navigate anywhere.
+ */
+export declare function installContextOpen(emit: Emit): Teardown;

package/dist/observers/context-open.js

@@ -0,0 +1,25 @@
+import { EventType } from '@reticlehq/core';
+import { captureMethod } from '../patching/capture-method.js';
+/**
+ * The page asked for ANOTHER browsing context — `window.open` — so the consequence of whatever was
+ * just clicked may live where this document's SDK cannot follow. An OAuth sign-in is the archetype:
+ * the POST succeeds, the popup carries the whole flow, and the original tab legitimately never
+ * changes (#508). Without this event the contradiction layer reads that shape as response-ignored,
+ * accusing the client of ignoring a response it handed to a window nobody can see.
+ *
+ * The wrap preserves the call exactly: same arguments, same return value, and a null/undefined
+ * first argument (the "open a blank tab" form) still emits, since a blank tab can navigate anywhere.
+ */
+export function installContextOpen(emit) {
+    const originalOpen = captureMethod(window, 'open');
+    if (originalOpen === undefined)
+        return () => { };
+    const openPatch = function (href, target, features) {
+        emit(EventType.CONTEXT_OPENED, { ...(href === undefined ? {} : { href }) });
+        return originalOpen.call(this, href, target, features);
+    };
+    window.open = openPatch;
+    return () => {
+        window.open = originalOpen;
+    };
+}

package/dist/observers/focus.js

@@ -17,6 +17,8 @@ function toBody(el) {
  * FOCUS_CHANGE {to, from, toBody}. Reversible.
  */
 export function installFocus(emit) {
+    const ac = new AbortController();
+    const { signal } = ac;
     let last = null;
     const onFocusIn = (event) => {
         const to = event.target;
@@ -39,10 +41,7 @@ export function installFocus(emit) {
             toBody: true,
         });
     };
-    document.addEventListener('focusin', onFocusIn);
-    document.addEventListener('focusout', onFocusOut);
-    return () => {
-        document.removeEventListener('focusin', onFocusIn);
-        document.removeEventListener('focusout', onFocusOut);
-    };
+    document.addEventListener('focusin', onFocusIn, { signal });
+    document.addEventListener('focusout', onFocusOut, { signal });
+    return () => ac.abort();
 }

package/dist/observers/health.js

@@ -109,21 +109,18 @@ function snapshotHealth() {
  * tab blind. Uses a native (pre-bound) timer so a frozen app clock (reticle_clock) never stalls it.
  */
 export function installHealth(emit) {
+    const ac = new AbortController();
+    const { signal } = ac;
     const report = (reason) => {
         emit(EventType.PAGE_HEALTH, { ...snapshotHealth(), reason });
     };
-    const onVisibility = () => report(HealthReason.VISIBILITY);
-    const onFocus = () => report(HealthReason.FOCUS);
-    const onBlur = () => report(HealthReason.BLUR);
-    document.addEventListener('visibilitychange', onVisibility);
-    window.addEventListener('focus', onFocus);
-    window.addEventListener('blur', onBlur);
+    document.addEventListener('visibilitychange', () => report(HealthReason.VISIBILITY), { signal });
+    window.addEventListener('focus', () => report(HealthReason.FOCUS), { signal });
+    window.addEventListener('blur', () => report(HealthReason.BLUR), { signal });
     report(HealthReason.INITIAL); // baseline so the server knows state before the first change
     const stopHeartbeat = nativeSetInterval(() => report(HealthReason.HEARTBEAT), SESSION_HEALTH.HEARTBEAT_MS);
     return () => {
         stopHeartbeat();
-        document.removeEventListener('visibilitychange', onVisibility);
-        window.removeEventListener('focus', onFocus);
-        window.removeEventListener('blur', onBlur);
+        ac.abort();
     };
 }

package/dist/observers/install-all.js

@@ -17,6 +17,7 @@ import { installStoreState } from './state.js';
 import { installFocus } from './focus.js';
 import { installBlindSpots } from './blind-spots.js';
 import { installDownload } from './download.js';
+import { installContextOpen } from './context-open.js';
 import { installNetwork } from './network.js';
 import { installIpc, ipcNetOverrides, isReticleOwnIpc } from './ipc.js';
 import { installPerf } from './perf.js';
@@ -62,5 +63,6 @@ export function installAllObservers(emit, options) {
         guard(emit, SdkSite.NETWORK_OBSERVER, () => installDownload(emit, { capturePreview: options.captureBodies })),
         guard(emit, SdkSite.DOM_OBSERVER, () => installBlindSpots(emit)), // cross-origin iframes the SDK can't see → BLIND_SPOT (coverage: partial)
         guard(emit, SdkSite.HEALTH_OBSERVER, () => installHealth(emit)), // page visibility/focus health + heartbeat
+        guard(emit, SdkSite.DOM_OBSERVER, () => installContextOpen(emit)), // window.open → CONTEXT_OPENED (the consequence may live in another context)
     ];
 }

package/dist/observers/network-redact.d.ts

@@ -5,3 +5,16 @@
  * The hash is preserved and the URL is returned byte-for-byte when nothing matched.
  */
 export declare function redactUrl(raw: string): string;
+/**
+ * Displayed URL plus, when redaction rewrote it, the raw request for graders.
+ *
+ * `url` is what the agent reads. `urlRaw` exists only so `urlContains` can still match a public
+ * path segment that the heuristic rewrote (`/auth/token/refresh-context`). Omitted when nothing
+ * changed, so an ordinary request pays nothing.
+ */
+export declare function netUrlFields(raw: string): {
+    url: string;
+} | {
+    url: string;
+    urlRaw: string;
+};

package/dist/observers/network-redact.js

@@ -1,4 +1,4 @@
-import { REDACTED_VALUE } from '@reticlehq/core';
+import { REDACTED_VALUE, URL_RAW } from '@reticlehq/core';
 import { isSensitiveKey } from '../security/serialization.js';
 /** A path segment name that is typically followed by a single-use secret token in the NEXT segment. */
 const SENSITIVE_PATH_SEGMENT = /^(reset|verify|verification|confirm|activate|invite|magic|magiclink|token|key|oauth|unsubscribe|password)$/i;
@@ -67,3 +67,14 @@ export function redactUrl(raw) {
     const queryOut = -1 === queryStart ? '' : `?${newQuery}`;
     return `${segments.join('/')}${queryOut}${newHash}`;
 }
+/**
+ * Displayed URL plus, when redaction rewrote it, the raw request for graders.
+ *
+ * `url` is what the agent reads. `urlRaw` exists only so `urlContains` can still match a public
+ * path segment that the heuristic rewrote (`/auth/token/refresh-context`). Omitted when nothing
+ * changed, so an ordinary request pays nothing.
+ */
+export function netUrlFields(raw) {
+    const url = redactUrl(raw);
+    return url === raw ? { url } : { url, [URL_RAW]: raw };
+}

package/dist/observers/network.d.ts

@@ -1,6 +1,6 @@
 import type { Emit, Teardown } from './types.js';
-import { redactUrl } from './network-redact.js';
-export { redactUrl };
+import { redactUrl, netUrlFields } from './network-redact.js';
+export { redactUrl, netUrlFields };
 /** Config for the network observer. Body capture is OFF by default and dev-only opt-in. */
 /**
  * Reinterpret a completed request's fields from its response.