@reticlehq/browser 2.2.1 → 2.3.0

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

package/dist/observers/network-body.js

@@ -21,6 +21,32 @@ const CAPTURABLE_CONTENT = /application\/json|text\/|application\/xml|x-www-form
  * observability SDK. Never read these; the frame observer covers SSE properly.
  */
 const STREAMING_CONTENT = /event-stream|x-ndjson|application\/stream/i;
+/**
+ * Content types that stay OPEN by design — watching them would make every first settle pay the full
+ * watch bound for a stream doing exactly its job. Real SSE is covered by the EventSource observer.
+ */
+const ENDLESS_BY_DESIGN = /event-stream/i;
+/**
+ * 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 function isStreamingBody(contentType, contentLength) {
+    if (contentType !== null && ENDLESS_BY_DESIGN.test(contentType))
+        return false;
+    return contentLength === null;
+}
 /**
  * Longest the SDK will wait on a response-body clone before emitting without it.
  *
@@ -140,4 +166,3 @@ export function projectBody(rawText, contentType) {
     const truncated = oversized || out.length > MAX_BODY_CHARS;
     return { body: out.length > MAX_BODY_CHARS ? out.slice(0, MAX_BODY_CHARS) : out, truncated };
 }
-//# sourceMappingURL=network-body.js.map

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

@@ -5,4 +5,3 @@
  * The hash is preserved and the URL is returned byte-for-byte when nothing matched.
  */
 export declare function redactUrl(raw: string): string;
-//# sourceMappingURL=network-redact.d.ts.map

package/dist/observers/network-redact.js

@@ -30,13 +30,17 @@ export function redactUrl(raw) {
     let newQuery = query;
     if (query !== '') {
         const params = new URLSearchParams(query);
+        let queryChanged = false;
         for (const key of [...params.keys()]) {
             if (isSensitiveKey(key)) {
                 params.set(key, REDACTED_VALUE);
-                changed = true;
+                queryChanged = true;
             }
         }
-        newQuery = params.toString();
+        if (queryChanged) {
+            newQuery = params.toString();
+            changed = true;
+        }
     }
     const segments = authority.split('/');
     for (let i = 0; i + 1 < segments.length; i++) {
@@ -63,4 +67,3 @@ export function redactUrl(raw) {
     const queryOut = queryStart === -1 ? '' : `?${newQuery}`;
     return `${segments.join('/')}${queryOut}${newHash}`;
 }
-//# sourceMappingURL=network-redact.js.map

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

@@ -0,0 +1,23 @@
+import type { Emit } from './types.js';
+/**
+ * Watch a STREAMED response body to its end, so `settled` cannot pass while the server is still
+ * writing.
+ *
+ * `fetch` resolves at HEADERS. On a Next.js App Router page the RSC payload's NET_REQUEST landed
+ * 16 ms in, the shell rendered at 3013, and the Suspense boundary's rows arrived at 3902 — 889 ms
+ * in which NOTHING was observed. Quiet is exactly what settle tests for, so it passed with the
+ * fallback still on screen and zero rows rendered: a green on every streaming boundary.
+ *
+ * STRUCTURAL, not an allowlist: a response with a body and no `content-length` is being sent
+ * chunked, which is the wire's own way of saying the server is still writing. An earlier version
+ * gated on a content-type list containing `x-component` — "Next.js RSC, plus two guesses" — which
+ * closed the one defect it was written against and left every other streamed response as invisible
+ * as before. The clone is DRAINED as it arrives rather than buffered, so watching costs a second
+ * read of bytes already in flight, not a second copy held in memory.
+ *
+ * BOUNDED both ways: an endless stream (SSE over fetch, a live feed) must not hold `settled` open
+ * forever, so the watch gives up after STREAM_WATCH_MS and closes the record anyway, marked
+ * `gaveUp`. That is the safe direction — a settle that eventually proceeds beats one that never
+ * does — and it says which happened rather than pretending the stream ended.
+ */
+export declare function watchStreamedBody(emit: Emit, res: Response, id: string, url: string, contentType: string | null, contentLength: string | null): void;

package/dist/observers/network-stream.js

@@ -0,0 +1,102 @@
+/**
+ * Watching a STREAMED response body to its end, so `settled` cannot pass mid-stream.
+ *
+ * Split out of network.ts, which was already at its line cap. One question: when did this response
+ * actually finish arriving?
+ */
+import { EventType, StreamDirection, StreamTransport } from '@reticlehq/core';
+import { isStreamingBody } from './network-body.js';
+import { nativeClearTimeout, nativeSetTimeout } from '../timers/native-timers.js';
+/**
+ * Longest a streamed response body is watched before the record is closed anyway.
+ *
+ * An endless stream must never hold `settled` open forever. Ten seconds is longer than any
+ * page-render stream and short enough that a genuinely endless one costs one settle window, not the
+ * session.
+ */
+const STREAM_WATCH_MS = 10_000;
+/**
+ * Watch a STREAMED response body to its end, so `settled` cannot pass while the server is still
+ * writing.
+ *
+ * `fetch` resolves at HEADERS. On a Next.js App Router page the RSC payload's NET_REQUEST landed
+ * 16 ms in, the shell rendered at 3013, and the Suspense boundary's rows arrived at 3902 — 889 ms
+ * in which NOTHING was observed. Quiet is exactly what settle tests for, so it passed with the
+ * fallback still on screen and zero rows rendered: a green on every streaming boundary.
+ *
+ * STRUCTURAL, not an allowlist: a response with a body and no `content-length` is being sent
+ * chunked, which is the wire's own way of saying the server is still writing. An earlier version
+ * gated on a content-type list containing `x-component` — "Next.js RSC, plus two guesses" — which
+ * closed the one defect it was written against and left every other streamed response as invisible
+ * as before. The clone is DRAINED as it arrives rather than buffered, so watching costs a second
+ * read of bytes already in flight, not a second copy held in memory.
+ *
+ * BOUNDED both ways: an endless stream (SSE over fetch, a live feed) must not hold `settled` open
+ * forever, so the watch gives up after STREAM_WATCH_MS and closes the record anyway, marked
+ * `gaveUp`. That is the safe direction — a settle that eventually proceeds beats one that never
+ * does — and it says which happened rather than pretending the stream ended.
+ */
+export function watchStreamedBody(emit, res, id, url, contentType, contentLength) {
+    // `=== null` is not enough: jsdom's Response has no `body` at all, and older/polyfilled
+    // implementations return undefined. Reaching for `.getReader()` on that threw an unhandled
+    // rejection out of a detached promise — an observability layer throwing into the host page, from
+    // code the host never called. Duck-type the reader instead of trusting the shape.
+    if (!isStreamingBody(contentType, contentLength))
+        return;
+    if (typeof res.body?.getReader !== 'function')
+        return;
+    let clone;
+    try {
+        clone = res.clone();
+    }
+    catch {
+        return; // already consumed or locked — the app owns it; observing it would take it away
+    }
+    const body = clone.body;
+    if (body === null)
+        return;
+    emit(EventType.NET_STREAM, {
+        transport: StreamTransport.FETCH,
+        direction: StreamDirection.OPEN,
+        url,
+        id,
+    });
+    void (async () => {
+        const reader = body.getReader();
+        let gaveUp = false;
+        // The deadline must be a TIMER, not a check after each read. An idle stream parks inside
+        // `read()` waiting for a chunk that may never come, so a post-read check never runs and the
+        // record never closes — which would hold `settled` open forever on exactly the endless streams
+        // the bound exists to protect against.
+        let timer;
+        const expired = new Promise((resolve) => {
+            timer = nativeSetTimeout(() => resolve('expired'), STREAM_WATCH_MS);
+        });
+        try {
+            for (;;) {
+                const next = await Promise.race([reader.read(), expired]);
+                if (next === 'expired') {
+                    gaveUp = true;
+                    void reader.cancel().catch(() => undefined);
+                    break;
+                }
+                if (next.done)
+                    break;
+            }
+        }
+        catch {
+            /* aborted or errored — the stream is over either way, which is what we report */
+        }
+        finally {
+            if (timer !== undefined)
+                nativeClearTimeout(timer);
+        }
+        emit(EventType.NET_STREAM, {
+            transport: StreamTransport.FETCH,
+            direction: StreamDirection.CLOSE,
+            url,
+            id,
+            ...(gaveUp ? { gaveUp: true } : {}),
+        });
+    })();
+}

package/dist/observers/network.d.ts

@@ -2,9 +2,20 @@ import type { Emit, Teardown } from './types.js';
 import { redactUrl } from './network-redact.js';
 export { redactUrl };
 /** 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.
+ *
+ * The seam exists so this observer stays ignorant of desktop IPC. A Tauri `invoke` arrives here as an
+ * ordinary fetch to an `ipc://` protocol, and the header that says whether the Rust command
+ * succeeded means nothing to a network observer — so the knowledge lives in the IPC observer and is
+ * passed IN, rather than this module importing it. Returns undefined to leave the record untouched.
+ */
+export type NetResponseReinterpreter = (url: string, header: (name: string) => string | null) => Record<string, unknown> | undefined;
 export interface NetworkOptions {
     /** Capture request/response bodies (text-like content only, redacted, per-body capped). */
     captureBodies?: boolean;
+    /** Optional hook that reinterprets a completed request — see NetResponseReinterpreter. */
+    reinterpret?: NetResponseReinterpreter;
 }
 /** Pure: the first real app-code frame in a stack string, capped. Exported for unit testing. */
 export declare function firstAppFrame(stack: string | undefined): string | undefined;
@@ -20,4 +31,3 @@ export interface NetTiming {
  */
 export declare function extractTiming(entry: PerformanceResourceTiming | undefined): NetTiming;
 export declare function installNetwork(emit: Emit, opts?: NetworkOptions): Teardown;
-//# sourceMappingURL=network.d.ts.map

package/dist/observers/network.js

@@ -2,6 +2,7 @@ import { BlindSpotKind, EventType, RETICLE_WS_PATH, StreamTransport, StreamDirec
 import { captureMethod } from '../patching/capture-method.js';
 import { isCapturableType, projectBody, withBodyDeadline } from './network-body.js';
 import { redactUrl } from './network-redact.js';
+import { watchStreamedBody } from './network-stream.js';
 // Redaction moved to its own cohesive module (network.ts is at its line cap); re-exported so callers
 // and the existing test suite keep importing it from here.
 export { redactUrl };
@@ -191,6 +192,7 @@ function isNativeFetch(fn) {
 const OURS = new WeakSet();
 export function installNetwork(emit, opts = {}) {
     const captureBodies = opts.captureBodies === true;
+    const reinterpret = opts.reinterpret;
     // Keep the true original for teardown identity, plus a window-bound copy to invoke
     // (fetch throws "Illegal invocation" if called with the wrong `this`).
     const origFetch = window.fetch;
@@ -230,6 +232,8 @@ export function installNetwork(emit, opts = {}) {
             // headers-received, so it stays honest whether or not we read the body.
             const headersAt = performance.now();
             const contentType = res.headers.get('content-type');
+            // The request is done; the BODY may not be. Watch it so settle cannot pass mid-stream.
+            watchStreamedBody(emit, res, id, url, contentType, res.headers.get('content-length'));
             const emitRequest = (responseBodyFields) => {
                 emit(EventType.NET_REQUEST, {
                     id,
@@ -244,6 +248,9 @@ export function installNetwork(emit, opts = {}) {
                     ...netResponseMeta(res.statusText, contentType, res.headers.get('content-length')),
                     ...projectRequestBody(init?.body, captureBodies),
                     ...responseBodyFields,
+                    // Applied LAST so a reinterpreted verdict wins over the transport's own fields — a Tauri
+                    // command that returned Err still travelled down a fetch that answered HTTP 200.
+                    ...(reinterpret?.(url, (name) => res.headers.get(name)) ?? {}),
                 });
             };
             if (captureBodies && isCapturableType(contentType)) {
@@ -511,4 +518,3 @@ export function installNetwork(emit, opts = {}) {
         }
     };
 }
-//# sourceMappingURL=network.js.map

package/dist/observers/perf.d.ts

@@ -10,4 +10,3 @@ import type { Emit, Teardown } from './types.js';
  * would otherwise be install time.
  */
 export declare function installPerf(emit: Emit): Teardown;
-//# sourceMappingURL=perf.d.ts.map

package/dist/observers/perf.js

@@ -59,4 +59,3 @@ export function installPerf(emit) {
             po.disconnect();
     };
 }
-//# sourceMappingURL=perf.js.map

package/dist/observers/route.d.ts

@@ -1,4 +1,3 @@
 import type { Emit, Teardown } from './types.js';
 /** Patch the History API + listen to popstate/hashchange to emit route.change. */
 export declare function installRoute(emit: Emit): Teardown;
-//# sourceMappingURL=route.d.ts.map

package/dist/observers/route.js

@@ -62,4 +62,3 @@ export function installRoute(emit) {
         window.removeEventListener('hashchange', onNav);
     };
 }
-//# sourceMappingURL=route.js.map

package/dist/observers/scroll.d.ts

@@ -1,4 +1,3 @@
 import type { Emit, Teardown } from './types.js';
 /** Observe scroll position + reveal-on-scroll for modern scroll-reactive UIs. */
 export declare function installScroll(emit: Emit): Teardown;
-//# sourceMappingURL=scroll.d.ts.map