@reticlehq/browser 2.2.1 → 2.4.0

package/dist/observers/dom.js

@@ -8,13 +8,16 @@ import { refs } from '../dom/refs.js';
  * container persists across ticks, so its testid (or ref) is the identity that does accumulate.
  */
 function regionKeyOf(target) {
-    const el = target instanceof Element ? target : null;
+    const el = isElement(target) ? target : null;
     if (el === null)
         return undefined;
     const labelled = el.closest('[data-testid]');
     return labelled?.getAttribute('data-testid') ?? refs.refFor(el);
 }
 import { isReticleOverlay } from '../dom/dom-ignore.js';
+import { capturedRoots, installShadowRegistry, onShadowRoot } from '../dom/shadow-registry.js';
+import { isElement } from '../dom/realm.js';
+import { observeSameOriginFrames } from './frames.js';
 const WATCHED_ATTRS = [
     'class',
     'hidden',
@@ -46,7 +49,30 @@ function isMeaningful(role, name) {
     return role !== 'generic' || name.length > 0;
 }
 /** Observe DOM mutations and emit semantic (not raw) events. */
+/**
+ * The trimmed text carried by a node list, or undefined when it carries none.
+ *
+ * Whitespace-only nodes are ignored deliberately: a re-render that reshuffles indentation would
+ * otherwise emit a text change on every layout node, which is noise the timeline cannot afford.
+ */
+const TEXT_NODE = 3;
+function textOf(nodes) {
+    let out = '';
+    for (const node of nodes) {
+        // The numeric nodeType, not `Node.TEXT_NODE`: the global `Node` constructor is not guaranteed to
+        // exist wherever this runs, and referencing it threw a ReferenceError rather than degrading.
+        if (node.nodeType !== TEXT_NODE)
+            continue;
+        out += node.nodeValue ?? '';
+    }
+    const trimmed = out.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
 export function installDom(emit) {
+    // Installed here rather than in the bootstrap list because this observer is the registry's reason
+    // for existing, and the ordering matters: a root attached between the two would be missed by both.
+    // It is also the only chance to capture a CLOSED root, which attachShadow returns exactly once.
+    const stopRegistry = installShadowRegistry();
     const observer = new MutationObserver((records) => {
         let added = 0;
         let removed = 0;
@@ -58,9 +84,7 @@ export function installDom(emit) {
         for (const record of records) {
             if (record.type === 'attributes') {
                 const target = record.target;
-                if (target instanceof Element &&
-                    record.attributeName !== null &&
-                    !isReticleOverlay(target)) {
+                if (isElement(target) && record.attributeName !== null && !isReticleOverlay(target)) {
                     if (changed >= MAX_PER_BATCH) {
                         dropped += 1;
                         continue;
@@ -93,8 +117,31 @@ export function installDom(emit) {
                 }
                 continue;
             }
+            // A TEXT node arriving or leaving is a text change, and it is the ordinary one. `characterData`
+            // fires only when an EXISTING text node's `data` is edited in place; `el.textContent = x`,
+            // `innerText`, and React replacing a child all REPLACE the node instead — a childList mutation
+            // carrying a Text node, which the Element-only loops below skip. Measured on a live page:
+            // `firstChild.data = x` emitted `dom.text`, while `textContent`, `innerText` and
+            // `appendChild(createTextNode())` emitted NOTHING. So the most common visible change an app
+            // makes — updating text — produced no event at all, `reticle_observe` reported "nothing
+            // happened" over a screen that had visibly changed, and `settled` went quiet immediately.
+            if (textOf(record.addedNodes) !== undefined || textOf(record.removedNodes) !== undefined) {
+                const parent = isElement(record.target) ? record.target : null;
+                if (parent !== null && !isReticleOverlay(parent)) {
+                    if (changed >= MAX_PER_BATCH)
+                        dropped += 1;
+                    else {
+                        changed += 1;
+                        // The element's text AFTER the mutation, so a cleared node reports '' rather than the
+                        // text that just left — the reader wants what is on screen now.
+                        const text = (parent.textContent ?? '').trim().slice(0, 80);
+                        const old = capValue(textOf(record.removedNodes) ?? null);
+                        emit(EventType.DOM_TEXT, { text, ...(old === undefined ? {} : { old }) }, refs.refFor(parent));
+                    }
+                }
+            }
             for (const node of record.addedNodes) {
-                if (!(node instanceof Element))
+                if (!isElement(node))
                     continue;
                 if (added >= MAX_PER_BATCH) {
                     dropped += 1;
@@ -117,7 +164,7 @@ export function installDom(emit) {
                 }
             }
             for (const node of record.removedNodes) {
-                if (!(node instanceof Element))
+                if (!isElement(node))
                     continue;
                 if (removed >= MAX_PER_BATCH) {
                     dropped += 1;
@@ -139,7 +186,7 @@ export function installDom(emit) {
         if (dropped > 0)
             emit(EventType.TRUNCATED, { channel: TruncationChannel.DOM, dropped });
     });
-    observer.observe(document.documentElement, {
+    const options = {
         subtree: true,
         childList: true,
         attributes: true,
@@ -147,9 +194,20 @@ export function installDom(emit) {
         attributeOldValue: true,
         characterData: true,
         characterDataOldValue: true,
-    });
+    };
+    observer.observe(document.documentElement, options);
+    // A MutationObserver does NOT cross a shadow boundary, so every root needs its own observation.
+    // Without this, a click that changed text inside a web component produced an empty observe window —
+    // the same shape as an app that ignored the click entirely.
+    for (const root of capturedRoots())
+        observer.observe(root, options);
+    const unsubscribe = onShadowRoot((root) => observer.observe(root, options));
+    // Same-origin frame documents are separate node trees for the same reason, with the same symptom.
+    const stopFrames = observeSameOriginFrames((body) => observer.observe(body, options));
     return () => {
+        stopFrames();
+        unsubscribe();
+        stopRegistry();
         observer.disconnect();
     };
 }
-//# sourceMappingURL=dom.js.map

package/dist/observers/download.d.ts

@@ -0,0 +1,6 @@
+import type { Emit, Teardown } from './types.js';
+export interface DownloadOptions {
+    /** Include a content preview. Gated for the same reason request bodies are: exports hold PII. */
+    capturePreview?: boolean;
+}
+export declare function installDownload(emit: Emit, opts?: DownloadOptions): Teardown;

package/dist/observers/download.js

@@ -0,0 +1,103 @@
+import { EventType } from '@reticlehq/core';
+import { captureMethod } from '../patching/capture-method.js';
+import { projectBody } from './network-body.js';
+/**
+ * Files the app PRODUCES — the one artifact class an outside-the-browser tool cannot inspect.
+ *
+ * A generated export never crosses the network: the app builds a Blob, hands it to
+ * `URL.createObjectURL`, and clicks an anchor. There is no request to intercept, and Playwright MCP
+ * has no tool that returns a downloaded file at all. Reticle runs inside the page, where the Blob is
+ * constructed, so the export is observable before it reaches the disk.
+ *
+ * Measured on a real merchant dashboard: one Export click produced a CSV wrong three ways at once —
+ * 25 data rows in a file named `transactions-128-rows.csv`, an unquoted `3 Aug, 10:00 pm` that
+ * shifts every column after it, and an `amount_inr` header over rows denominated in USD — while the
+ * click itself reported a clean success and every other channel agreed. The benchmark's ground truth
+ * records those three as missed by BOTH toolchains, for the same reason: nobody opened the file.
+ */
+/** Text-like types worth counting lines in and previewing. Anything else reports type + size only. */
+const TEXTUAL = /text\/|json|csv|xml|ndjson|javascript/i;
+/** Lines are reported for text files; the preview is capped and redacted by projectBody. */
+const PREVIEW_CHARS = 2000;
+export function installDownload(emit, opts = {}) {
+    // jsdom does not implement `createObjectURL`, and plenty of users run this SDK under jsdom in their
+    // own test suite. Reaching for `.bind` on an absent function threw during `connect()` — an
+    // observability layer taking the host app down with it, which is the one failure mode it may never
+    // have. No object URLs means no generated files to observe, so this simply stands down.
+    if (typeof URL.createObjectURL !== 'function')
+        return () => undefined;
+    const objectUrl = URL.createObjectURL.bind(URL);
+    const known = new Map();
+    /**
+     * `createObjectURL` is where the file becomes real. The filename is NOT here — it lives on the
+     * anchor that gets clicked — so the blob is remembered against its URL and reported when either
+     * the anchor fires or, failing that, on a microtask so a download that is never clicked (a
+     * generated preview, an <img> src) is still visible.
+     */
+    const originalCreate = captureMethod(URL, 'createObjectURL');
+    URL.createObjectURL = function reticleObservedObjectUrl(obj) {
+        const url = objectUrl(obj);
+        if (typeof Blob !== 'undefined' && obj instanceof Blob) {
+            // Started here, awaited at report time — never blocking the app's own download path.
+            const text = TEXTUAL.test(obj.type)
+                ? obj.text().catch(() => undefined)
+                : Promise.resolve(undefined);
+            known.set(url, { type: obj.type, size: obj.size, text });
+        }
+        return url;
+    };
+    const report = (url, filename) => {
+        const record = known.get(url);
+        if (record === undefined)
+            return;
+        known.delete(url);
+        void record.text.then((text) => {
+            emitDownload(record, filename, text);
+        });
+    };
+    const emitDownload = (record, filename, text) => {
+        const data = { mimeType: record.type, bytes: record.size };
+        if (filename !== undefined && filename.length > 0)
+            data['filename'] = filename;
+        if (text !== undefined) {
+            // The LINE COUNT is reported even without preview capture: it is a number, not content, and it
+            // is the whole tell for "25 rows in a file the toast calls 128".
+            data['lines'] = text.split('\n').filter((l) => l.length > 0).length;
+            if (opts.capturePreview === true) {
+                const { body, truncated } = projectBody(text.slice(0, PREVIEW_CHARS), record.type);
+                data['preview'] = body;
+                if (truncated)
+                    data['previewTruncated'] = true;
+            }
+        }
+        emit(EventType.DOWNLOAD, data);
+    };
+    /**
+     * An anchor click carries the NAME. Captured at the document level so it sees the click whether the
+     * app dispatches it programmatically or a human does, and whether or not the anchor is in the DOM.
+     */
+    const onClick = (event) => {
+        const target = event.target;
+        const anchor = target instanceof Element ? target.closest('a[download]') : null;
+        if (anchor === null)
+            return;
+        report(anchor.getAttribute('href') ?? '', anchor.getAttribute('download') ?? undefined);
+    };
+    document.addEventListener('click', onClick, true);
+    // A programmatic `a.click()` on an anchor never inserted into the document dispatches no bubbling
+    // event this listener can see, so the anchor path is patched too.
+    const originalClick = captureMethod(HTMLAnchorElement.prototype, 'click');
+    HTMLAnchorElement.prototype.click = function reticleObservedAnchorClick() {
+        if (this.hasAttribute('download')) {
+            report(this.getAttribute('href') ?? '', this.getAttribute('download') ?? undefined);
+        }
+        originalClick.call(this);
+    };
+    return () => {
+        // A REAL restore, so teardown leaves the page exactly as it was found.
+        document.removeEventListener('click', onClick, true);
+        URL.createObjectURL = originalCreate;
+        HTMLAnchorElement.prototype.click = originalClick;
+        known.clear();
+    };
+}

package/dist/observers/focus.d.ts

@@ -7,4 +7,3 @@ export declare function focusLabel(el: EventTarget | null): string | undefined;
  * FOCUS_CHANGE {to, from, toBody}. Reversible.
  */
 export declare function installFocus(emit: Emit): Teardown;
-//# sourceMappingURL=focus.d.ts.map

package/dist/observers/focus.js

@@ -46,4 +46,3 @@ export function installFocus(emit) {
         document.removeEventListener('focusout', onFocusOut);
     };
 }
-//# sourceMappingURL=focus.js.map

package/dist/observers/frames.d.ts

@@ -0,0 +1,12 @@
+import type { Teardown } from './types.js';
+/** Every same-origin frame body at or beneath `root`, in document order. */
+export declare function sameOriginFrameBodies(root: ParentNode): HTMLElement[];
+/**
+ * Call `attach` for every same-origin frame body now and after each frame load.
+ *
+ * A frame that navigates gets a BRAND NEW document, so the old observation is dead and re-attaching on
+ * `load` is not optional — without it, observation silently stops the first time an embedded panel
+ * routes. Attaching twice to the same node is harmless (MutationObserver de-duplicates), so no
+ * bookkeeping is kept.
+ */
+export declare function observeSameOriginFrames(attach: (body: HTMLElement) => void): Teardown;

package/dist/observers/frames.js

@@ -0,0 +1,67 @@
+/**
+ * Same-origin `<iframe>` documents, wired into the top document's observation.
+ *
+ * A `MutationObserver` is scoped to the node it is given, and a frame's document is a DIFFERENT node
+ * tree — so a click inside an embedded panel changed its text and `observe` reported an empty window.
+ * Measured on a console with an embedded SLA panel: the click landed, the panel updated, and the
+ * observe window held zero DOM events. That is the false-green shape exactly — "nothing happened" is
+ * what an agent concludes, and it is wrong.
+ *
+ * A MutationObserver CAN observe a node in another same-origin document, so the fix is to hand it the
+ * frame bodies. Cross-origin frames stay unreachable and keep their existing blind-spot declaration.
+ *
+ * Network is NOT covered here. A frame's `fetch` lives in the frame's own realm and the top realm's
+ * patch never sees it, so requests it makes are invisible — declared as a blind spot rather than
+ * partially instrumented, because a half-seen request channel is worse than an admitted one.
+ */
+/** Frames-inside-frames, bounded. Real embeds nest once, occasionally twice. */
+const DEPTH_MAX = 3;
+function bodyOf(frame) {
+    try {
+        return frame.contentDocument?.body ?? null;
+    }
+    catch {
+        return null; // cross-origin — not ours to read
+    }
+}
+/** Every same-origin frame body at or beneath `root`, in document order. */
+export function sameOriginFrameBodies(root) {
+    const found = [];
+    const walk = (node, depth) => {
+        if (depth >= DEPTH_MAX)
+            return;
+        for (const frame of node.querySelectorAll('iframe')) {
+            const body = bodyOf(frame);
+            if (body === null)
+                continue;
+            found.push(body);
+            walk(body, depth + 1);
+        }
+    };
+    walk(root, 0);
+    return found;
+}
+/**
+ * Call `attach` for every same-origin frame body now and after each frame load.
+ *
+ * A frame that navigates gets a BRAND NEW document, so the old observation is dead and re-attaching on
+ * `load` is not optional — without it, observation silently stops the first time an embedded panel
+ * routes. Attaching twice to the same node is harmless (MutationObserver de-duplicates), so no
+ * bookkeeping is kept.
+ */
+export function observeSameOriginFrames(attach) {
+    const attachAll = () => {
+        for (const body of sameOriginFrameBodies(document))
+            attach(body);
+    };
+    attachAll();
+    // `load` does not bubble, but it DOES reach a capturing listener on the document.
+    const onLoad = (event) => {
+        if (event.target instanceof HTMLIFrameElement)
+            attachAll();
+    };
+    document.addEventListener('load', onLoad, true);
+    return () => {
+        document.removeEventListener('load', onLoad, true);
+    };
+}

package/dist/observers/health.d.ts

@@ -5,4 +5,3 @@ import type { Emit, Teardown } from './types.js';
  * tab blind. Uses a native (pre-bound) timer so a frozen app clock (reticle_clock) never stalls it.
  */
 export declare function installHealth(emit: Emit): Teardown;
-//# sourceMappingURL=health.d.ts.map

package/dist/observers/health.js

@@ -1,9 +1,38 @@
-import { EventType, HealthReason, SESSION_HEALTH } from '@reticlehq/core';
+import { EventType, HealthReason, RETICLE_IPC_GLOBAL, SESSION_HEALTH } from '@reticlehq/core';
 import { nativeSetInterval } from '../timers/native-timers.js';
+/**
+ * Which shell this page runs in. Reported with health because it is what makes a timeout
+ * diagnosable: an occluded WKWebView is SUSPENDED by macOS, so the session stays connected while
+ * every command times out — and a URL cannot tell a Tauri dev server from a plain localhost app, so
+ * the runtime has to come from the page itself.
+ */
+function detectRuntime() {
+    const w = window;
+    if (w['__TAURI_INTERNALS__'] !== undefined || w['__TAURI__'] !== undefined)
+        return 'tauri';
+    if (navigator.userAgent.includes('Electron') || w[RETICLE_IPC_GLOBAL] !== undefined)
+        return 'electron';
+    return 'web';
+}
+/**
+ * The rendering engine, coarse on purpose. Three buckets — never the UA string itself, which is
+ * high-cardinality and semi-identifying. Order matters: every Chromium UA also contains "Safari", and
+ * Gecko is the only engine that reports a real `Gecko/` build token.
+ */
+function detectEngine() {
+    const ua = navigator.userAgent;
+    if (/Chrome|Chromium|Edg\//.test(ua))
+        return 'blink';
+    if (/Gecko\/|Firefox/.test(ua))
+        return 'gecko';
+    return 'webkit';
+}
 function snapshotHealth() {
     return {
         hidden: document.visibilityState === 'hidden',
         focused: document.hasFocus(),
+        runtime: detectRuntime(),
+        engine: detectEngine(),
     };
 }
 /**
@@ -30,4 +59,3 @@ export function installHealth(emit) {
         window.removeEventListener('blur', onBlur);
     };
 }
-//# sourceMappingURL=health.js.map

package/dist/observers/install-all.d.ts

@@ -0,0 +1,5 @@
+import type { Emit, Teardown } from './types.js';
+export interface InstallOptions {
+    captureBodies: boolean;
+}
+export declare function installAllObservers(emit: Emit, options: InstallOptions): Teardown[];

package/dist/observers/install-all.js

@@ -0,0 +1,63 @@
+/**
+ * Install every page observer, guarded.
+ *
+ * Extracted from `reticle.ts` because it is one job with one rule, and because that file is the SDK's
+ * public surface — the more of this that lived there, the harder it was to see what `connect()`
+ * actually does.
+ *
+ * THE RULE: one observer failing must never stop the others. This array used to be built bare, so a
+ * single `install*` that threw took the whole `connect()` down with it — one bad patch on one exotic
+ * page and the app got no instrumentation at all, silently, because the SDK\'s own catch blocks
+ * ensured nobody ever found out. Each install is now wrapped: the healthy observers still run, the
+ * failure is reported over the bridge, and the caller gets a teardown list of the same length.
+ */
+import { installDom } from './dom.js';
+import { installStorage } from './storage.js';
+import { installStoreState } from './state.js';
+import { installFocus } from './focus.js';
+import { installBlindSpots } from './blind-spots.js';
+import { installDownload } from './download.js';
+import { installNetwork } from './network.js';
+import { installIpc, ipcNetOverrides } from './ipc.js';
+import { installPerf } from './perf.js';
+import { installRoute } from './route.js';
+import { installConsole } from './console.js';
+import { installAnimation } from './animation.js';
+import { installScroll } from './scroll.js';
+import { installHealth } from './health.js';
+import { reportSdkFailure, SdkSite } from './sdk-failure.js';
+/** Run one install, reporting rather than throwing if it cannot start. */
+function guard(emit, site, install) {
+    try {
+        return install();
+    }
+    catch (error) {
+        reportSdkFailure(emit, site, error);
+        return () => { }; // nothing was installed, so there is nothing to tear down
+    }
+}
+export function installAllObservers(emit, options) {
+    return [
+        // Composition happens HERE, not inside the network observer: the network observer knows
+        // nothing about desktop IPC, and the IPC observer knows nothing about fetch plumbing.
+        guard(emit, SdkSite.NETWORK_OBSERVER, () => installNetwork(emit, {
+            captureBodies: options.captureBodies,
+            reinterpret: ipcNetOverrides,
+        })),
+        // Desktop backends are reached over IPC, not HTTP — inert on a plain web page.
+        guard(emit, SdkSite.IPC_OBSERVER, () => installIpc(emit, { captureBodies: options.captureBodies })),
+        guard(emit, SdkSite.ANIMATION_OBSERVER, () => installPerf(emit)),
+        guard(emit, SdkSite.ROUTER_OBSERVER, () => installRoute(emit)),
+        guard(emit, SdkSite.CONSOLE_OBSERVER, () => installConsole(emit)),
+        guard(emit, SdkSite.ANIMATION_OBSERVER, () => installAnimation(emit)),
+        guard(emit, SdkSite.DOM_OBSERVER, () => installScroll(emit)),
+        guard(emit, SdkSite.DOM_OBSERVER, () => installDom(emit)),
+        guard(emit, SdkSite.STORE_ADAPTER, () => installStorage(emit)), // storage WRITES → STORAGE_CHANGE diffs (pull remains the fallback)
+        guard(emit, SdkSite.STORE_ADAPTER, () => installStoreState(emit)), // subscribed-store mutations → STATE_CHANGE path diffs
+        guard(emit, SdkSite.DOM_OBSERVER, () => installFocus(emit)), // element focus movement → FOCUS_CHANGE (focus-to-body = a regression)
+        // Files the app PRODUCES — never cross the network, so no outside-the-page tool can see them.
+        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
+    ];
+}

package/dist/observers/ipc.d.ts

@@ -0,0 +1,22 @@
+import type { Emit, Teardown } from './types.js';
+/**
+ * How Tauri v2 reports a command's verdict. The transport answers HTTP 200 whether the Rust command
+ * returned Ok or Err — the verdict is in this response header, which Tauri explicitly CORS-exposes so
+ * JS may read it. Without translating it, every failed command is recorded as a successful request.
+ */
+export declare const TAURI_RESPONSE_HEADER_NAME = "Tauri-Response";
+/**
+ * Fields to override on a NET_REQUEST that turned out to be a Tauri IPC call, or null when the
+ * request was ordinary HTTP. Pure — the network observer calls this with the response header it
+ * already holds, so IPC knowledge stays in this file.
+ */
+export declare function ipcNetOverrides(url: string, header: (name: string) => string | null): Record<string, unknown> | undefined;
+/**
+ * Subscribe to the Electron preload shim, if this app installed it. Inert on Tauri (whose calls the
+ * network observer handles) and on a plain web page.
+ */
+export interface IpcOptions {
+    /** Forward the IPC payloads the preload recorded. Off by default, like the HTTP body capture. */
+    captureBodies?: boolean;
+}
+export declare function installIpc(emit: Emit, options?: IpcOptions): Teardown;

package/dist/observers/ipc.js

@@ -0,0 +1,121 @@
+import { BlindSpotKind, EventType, IPC_URL_SCHEME, IpcStatus, NetInitiator, RETICLE_IPC_GLOBAL, } from '@reticlehq/core';
+import { observeSafely } from './types.js';
+/**
+ * How Tauri v2 reports a command's verdict. The transport answers HTTP 200 whether the Rust command
+ * returned Ok or Err — the verdict is in this response header, which Tauri explicitly CORS-exposes so
+ * JS may read it. Without translating it, every failed command is recorded as a successful request.
+ */
+export const TAURI_RESPONSE_HEADER_NAME = 'Tauri-Response';
+const TAURI_RESPONSE_ERROR = 'error';
+/** Rust/IPC vocabulary rather than HTTP's, so the text never claims a transport status it lacks. */
+const IPC_STATUS_TEXT = { OK: 'Ok', ERROR: 'Err' };
+/**
+ * Tauri's IPC endpoint. The last path segment is the command name.
+ *
+ * TWO spellings, because Tauri v2 uses a different one per platform and matching only the first is a
+ * silent false green on Windows: macOS/Linux get the custom scheme `ipc://localhost/archive_todo`,
+ * while Windows (and Android) need a real http origin and get
+ * `http://ipc.localhost/archive_todo` — the hostname `desktop-doctor` already tells people to put in
+ * their CSP. Unmatched, a Windows `invoke` was recorded as an ordinary HTTP request, so the
+ * `Tauri-Response` translation never ran and every command that returned `Err` was banked as a
+ * successful 200. `.localhost` is reserved for loopback by RFC 6761, so this can never match a
+ * remote host.
+ */
+const TAURI_IPC_URL = /^(?:ipc:\/\/[^/]*|https?:\/\/ipc\.localhost(?::\d+)?)\/(.+)$/;
+/**
+ * Fields to override on a NET_REQUEST that turned out to be a Tauri IPC call, or null when the
+ * request was ordinary HTTP. Pure — the network observer calls this with the response header it
+ * already holds, so IPC knowledge stays in this file.
+ */
+export function ipcNetOverrides(url, header) {
+    const match = TAURI_IPC_URL.exec(url);
+    const command = match?.[1];
+    if (command === undefined)
+        return undefined;
+    const ok = header(TAURI_RESPONSE_HEADER_NAME) !== TAURI_RESPONSE_ERROR;
+    return {
+        // Normalize `ipc://localhost/archive_todo` to `ipc://archive_todo`, so a Tauri command and an
+        // Electron channel read identically to the agent and to a saved flow's assertions.
+        url: `${IPC_URL_SCHEME}${command}`,
+        initiator: NetInitiator.IPC,
+        method: NetInitiator.IPC,
+        ok,
+        status: ok ? IpcStatus.OK : IpcStatus.ERROR,
+        // Overwrite the TRANSPORT's statusText. Tauri's fetch genuinely answered 200/"OK", so letting it
+        // through beside a synthetic 500 produced a record that contradicted itself — `status: 500,
+        // statusText: "OK"` reads as nonsense to anyone seeing it cold. The record must tell one story,
+        // and the story that matters is the command's verdict, not the pipe it travelled down.
+        statusText: ok ? IPC_STATUS_TEXT.OK : IPC_STATUS_TEXT.ERROR,
+    };
+}
+/**
+ * Is this page an Electron renderer? Read off the user agent, which Electron stamps and which is
+ * available whether or not the preload ran — the whole point is to recognise a renderer that has
+ * NOT been instrumented.
+ */
+function isElectronRenderer() {
+    return navigator.userAgent.includes('Electron');
+}
+export function installIpc(emit, options = {}) {
+    const channel = window[RETICLE_IPC_GLOBAL];
+    if (typeof channel?.subscribe !== 'function') {
+        // No shim — but on Electron that is not "nothing to observe", it is "everything unobserved".
+        // Tauri needs no shim (its invoke travels as a fetch) and a web page has no IPC at all, so only
+        // Electron gets the declaration. Saying nothing here is what let a missing preload line read as
+        // a clean, empty network view for a whole app.
+        if (isElectronRenderer())
+            emit(EventType.BLIND_SPOT, { kind: BlindSpotKind.UNOBSERVED_IPC, count: 1 });
+        return () => undefined;
+    }
+    const token = channel.subscribe((record) => {
+        observeSafely(() => {
+            const url = `${IPC_URL_SCHEME}${record.channel}`;
+            if (record.phase === 'start') {
+                emit(EventType.NET_PENDING, {
+                    id: record.id,
+                    method: NetInitiator.IPC,
+                    url,
+                    initiator: NetInitiator.IPC,
+                });
+                return;
+            }
+            // A one-way `send` that did not throw has NO verdict — the renderer never learns whether the
+            // main process handled it. Emitting `ok/status` anyway would manufacture the success nobody
+            // reported, so both are omitted and `oneWay` says why. `reticle_network { ok }` then matches
+            // such a record in neither direction, which is the honest answer to "did it work".
+            const verdictless = record.oneWay === true && record.ok === undefined;
+            // Declared, not inferred: the server cannot tell "no verdict" from "not yet settled" without
+            // being told, and a send with nothing to observe must not read as a clean green.
+            if (verdictless)
+                emit(EventType.BLIND_SPOT, { kind: BlindSpotKind.VERDICTLESS_SEND, count: 1 });
+            const ok = record.ok === true;
+            emit(EventType.NET_REQUEST, {
+                id: record.id,
+                method: NetInitiator.IPC,
+                url,
+                ...(verdictless ? {} : { ok, status: ok ? IpcStatus.OK : IpcStatus.ERROR }),
+                ...(record.oneWay === true ? { oneWay: true } : {}),
+                durationMs: record.durationMs ?? 0,
+                initiator: NetInitiator.IPC,
+                ...(record.error === undefined ? {} : { error: record.error }),
+                // Size travels ALWAYS, bodies only on opt-in. The split matters: the verdict layer reports "a
+                // write returned ok and its payload went unread" from the size alone, and it cannot infer that
+                // from an absent field — an unread payload and an empty one would look identical.
+                ...(record.responseSize === undefined ? {} : { responseSize: record.responseSize }),
+                ...(options.captureBodies === true
+                    ? {
+                        ...(record.requestBody === undefined ? {} : { requestBody: record.requestBody }),
+                        ...(record.responseBody === undefined ? {} : { responseBody: record.responseBody }),
+                        ...(record.responseBodyTruncated === true ? { responseBodyTruncated: true } : {}),
+                    }
+                    : {}),
+            });
+        });
+    });
+    // A REAL removal, so teardown leaves the app as it found it. The preload's `invoke` patch stays
+    // deliberately — it is a pass-through with no effect once no subscriber remains, and un-patching
+    // mid-flight would strand any call already inside the wrapper.
+    return () => {
+        channel.unsubscribe?.(token);
+    };
+}

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

@@ -1,3 +1,20 @@
+/**
+ * Is this response body still arriving after the request itself resolved?
+ *
+ * STRUCTURAL, not a content-type allowlist. The first version listed `x-component|x-ndjson|
+ * application/stream` — which is to say "Next.js RSC, plus two guesses". It closed the exact defect
+ * it was written against and left every other streamed response as invisible as before: a chunked
+ * `application/json` from a token API, a streamed HTML document, an export assembled server-side.
+ * Fixing one app's symptom and calling the class solved is how a false green comes back wearing
+ * different clothes.
+ *
+ * The real signal is on the wire: a response with a BODY and no `content-length` is being sent
+ * chunked, which is the definition of "the server is still writing". `content-length` present means
+ * the size was known up front and the body cannot grow.
+ *
+ * Deliberately independent of content type, with one exception above for streams that never end.
+ */
+export declare function isStreamingBody(contentType: string | null, contentLength: string | null): boolean;
 /**
  * Resolve with the body text, or `undefined` if it takes too long.
  *
@@ -16,4 +33,3 @@ export declare function projectBody(rawText: string, contentType: string | null)
     body: string;
     truncated: boolean;
 };
-//# sourceMappingURL=network-body.d.ts.map