@rangojs/router 0.0.0-experimental.80 → 0.0.0-experimental.80daa23e

package/src/browser/react/use-reverse.ts

@@ -0,0 +1,106 @@
+"use client";
+
+import { useCallback } from "react";
+import type { LocalReverseFunction } from "../../reverse.js";
+import { substitutePatternParams } from "../../router/substitute-pattern-params.js";
+import { serializeSearchParams } from "../../search-params.js";
+import { useMount } from "./use-mount.js";
+import { useParams } from "./use-params.js";
+
+type RouteEntry = string | { readonly path: string };
+type LocalRouteMap = Readonly<Record<string, RouteEntry>>;
+
+function getPattern(entry: RouteEntry | undefined): string | undefined {
+  if (entry === undefined) return undefined;
+  return typeof entry === "string" ? entry : entry.path;
+}
+
+/**
+ * Join an include mount prefix with a mount-relative pattern.
+ *
+ * `pattern === "/"` is the index of the local module — under a non-root
+ * mount it must collapse so `/` under `/blog` becomes `/blog`, not
+ * `/blog/`. This matches `ctx.reverse(".index")` on the server.
+ */
+function joinMount(mount: string, pattern: string): string {
+  if (pattern === "/") {
+    if (mount === "" || mount === "/") return "/";
+    return mount.endsWith("/") ? mount.slice(0, -1) : mount;
+  }
+  const normalizedMount = mount === "/" ? "" : mount.replace(/\/+$/, "");
+  return normalizedMount + pattern;
+}
+
+/**
+ * Mount-aware reverse function for a locally-imported `routes` map.
+ *
+ * The `routes` map you pass IS the scope: `reverse("name")` looks the name up
+ * in that map (verbatim), prefixes the result with the surrounding `include()`
+ * mount path via `useMount()`, and substitutes params — auto-filling from the
+ * current matched route's params, with explicit params overriding. A module's
+ * components can therefore reverse their own routes without knowing where the
+ * module is mounted: include it under any prefix and the URLs resolve correctly.
+ *
+ * The leading dot is optional and cosmetic: `reverse("post")` and
+ * `reverse(".post")` resolve identically. The dot exists only as a readability
+ * convention and for parity with `ctx.reverse(".name")` on the server; here the
+ * passed map is the scope, so there is no separate global namespace to
+ * disambiguate and the dot carries no meaning.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { Link, useReverse } from "@rangojs/router/client";
+ * import { routes as blogRoutes } from "../urls/blog.gen.js";
+ *
+ * function BlogNav() {
+ *   const reverse = useReverse(blogRoutes);
+ *   return (
+ *     <>
+ *       <Link to={reverse("index")}>Blog</Link>
+ *       <Link to={reverse("post", { postId: "hello" })}>Post</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useReverse<const TRoutes extends LocalRouteMap>(
+  routes: TRoutes,
+): LocalReverseFunction<TRoutes> {
+  const mount = useMount();
+  const currentParams = useParams();
+
+  return useCallback(
+    ((
+      name: string,
+      explicitParams?: Record<string, string | undefined>,
+      search?: Record<string, unknown>,
+    ): string => {
+      // The leading dot is optional. The passed map IS the scope, so a dot to
+      // signal "local" is unnecessary — "detail" and ".detail" resolve the same.
+      // A dot is accepted (and stripped) for readability / ctx.reverse parity.
+      const lookupName = name.startsWith(".") ? name.slice(1) : name;
+      const entry = (routes as LocalRouteMap)[lookupName];
+      const pattern = getPattern(entry);
+      if (pattern === undefined) {
+        throw new Error(`Unknown route: "${name}"`);
+      }
+
+      const joined = joinMount(mount, pattern);
+
+      const mergedParams = explicitParams
+        ? { ...currentParams, ...explicitParams }
+        : currentParams;
+
+      const substituted = substitutePatternParams(joined, mergedParams, name);
+
+      if (search) {
+        const qs = serializeSearchParams(search);
+        if (qs) return `${substituted}?${qs}`;
+      }
+
+      return substituted;
+    }) as LocalReverseFunction<TRoutes>,
+    [routes, mount, currentParams],
+  );
+}

package/src/browser/react/use-router.ts

@@ -2,21 +2,34 @@
 
 import { useContext, useMemo } from "react";
 import { NavigationStoreContext } from "./context.js";
-import { prefetchDirect } from "../prefetch/fetch.js";
+import { useMount } from "./use-mount.js";
+import { prefetchDirect } from "../prefetch/loader.js";
 import { getAppVersion } from "../app-version.js";
 import type { RouterInstance, RouterNavigateOptions } from "../types.js";
 
 /**
  * Hook to access router actions (push, replace, refresh, prefetch, back, forward).
  *
- * Returns a STABLE reference that never changes, so components using
- * useRouter() do not re-render on navigation state changes.
+ * Returns a STABLE reference per component, so components using useRouter()
+ * do not re-render on navigation state changes.
  * For reactive navigation state, use useNavigation() instead.
  *
+ * Methods read `basename` from the context on each call. It is set once from
+ * the initial payload and is stable within a session — a cross-app navigation
+ * is a full document load (X-RSC-Reload), so the target app mounts fresh with
+ * its own basename.
+ *
+ * RELATIVE paths (no leading `/`, no scheme/query/hash) resolve against the
+ * current include() mount: `router.push("cart")` inside `include("/shop")`
+ * navigates to `/shop/cart`. Absolute paths stay APP-absolute — unlike
+ * basename, the mount is scoped, and absolute pushes legitimately target
+ * outside it, so they are never auto-prefixed.
+ *
  * @example
  * ```tsx
  * const router = useRouter();
- * router.push("/products");
+ * router.push("/products");   // app-absolute
+ * router.push("cart");        // mount-relative
  * router.replace("/login", { scroll: false });
  * router.prefetch("/dashboard");
  * router.back();
@@ -24,12 +37,17 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
  */
 export function useRouter(): RouterInstance {
   const ctx = useContext(NavigationStoreContext);
+  const mount = useMount();
 
   if (!ctx) {
     throw new Error("useRouter must be used within NavigationProvider");
   }
 
-  // Stable reference: ctx is itself stable (NavigationProvider memoizes with [])
+  // Stable reference per component: ctx is stable and mount is a static
+  // property of the component's position in the tree; reads on each method
+  // call pick up live basename values from the context (backed by a live
+  // ref in NavigationProvider), so app-switch transitions are reflected
+  // without recreating this object.
   return useMemo<RouterInstance>(() => {
     /** Prefix a root-relative path with basename if not already prefixed. */
     function withBasename(url: string): string {
@@ -39,38 +57,71 @@ export function useRouter(): RouterInstance {
       return url === "/" ? bn : bn + url;
     }
 
+    /**
+     * Resolve a navigation/prefetch target. RELATIVE paths — a leading word
+     * character or `./`, never a scheme (`http:`, `mailto:`), query, or
+     * hash form — join onto the include mount and then take the basename
+     * pass like any root-relative path. Everything else passes through
+     * unchanged.
+     */
+    function resolveTarget(url: string): string {
+      const relative = url.startsWith("./") ? url.slice(2) : url;
+      if (
+        !/^[A-Za-z0-9]/.test(relative) ||
+        /^[a-z][a-z0-9+.-]*:/i.test(relative)
+      ) {
+        return withBasename(url);
+      }
+      const base = mount === "/" ? "" : mount.replace(/\/$/, "");
+      return withBasename(`${base}/${relative}`);
+    }
+
     return {
       push(url: string, options?: RouterNavigateOptions): Promise<void> {
-        return ctx.navigate(withBasename(url), { ...options, replace: false });
+        return ctx.navigate(resolveTarget(url), { ...options, replace: false });
       },
 
       replace(url: string, options?: RouterNavigateOptions): Promise<void> {
-        return ctx.navigate(withBasename(url), { ...options, replace: true });
+        return ctx.navigate(resolveTarget(url), { ...options, replace: true });
       },
 
       refresh(): Promise<void> {
         return ctx.refresh();
       },
 
-      prefetch(url: string): void {
+      prefetch(url: string, options?: { key?: ":source" }): void {
         const segmentState = ctx.store?.getSegmentState();
         if (segmentState) {
           prefetchDirect(
-            withBasename(url),
+            resolveTarget(url),
             segmentState.currentSegmentIds,
             getAppVersion(),
             ctx.store?.getRouterId?.(),
+            options?.key,
           );
         }
       },
 
       back(): void {
-        window.history.back();
+        // Avoid escaping the host on the first entry of this session.
+        // Prefer the Navigation API; fall back to the router-stamped
+        // history.state.idx (set by pushHistoryWithIdx) for older browsers.
+        const nav = (window as { navigation?: { canGoBack: boolean } })
+          .navigation;
+        const canGoBack =
+          nav && typeof nav.canGoBack === "boolean"
+            ? nav.canGoBack
+            : ((window.history.state as { idx?: number } | null)?.idx ?? 0) > 0;
+        if (canGoBack) {
+          window.history.back();
+        } else {
+          ctx.navigate(withBasename("/"), { replace: true });
+        }
       },
 
       forward(): void {
         window.history.forward();
       },
     };
-  }, []);
+  }, [mount]);
 }

package/src/browser/react/use-search-params.ts

@@ -1,37 +1,129 @@
 "use client";
 
-import { useContext, useState, useEffect, useRef } from "react";
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { NavigationStoreContext } from "./context.js";
 import type { ReadonlyURLSearchParams } from "../types.js";
 
 /**
- * Hook to access the current URL search params.
+ * Accepted shapes for the setter: a full replacement for the search string.
+ * Record values are stringified; array values append one entry per element;
+ * null/undefined values are skipped (ergonomic conditional spreads).
+ */
+export type SearchParamsInit =
+  | string
+  | URLSearchParams
+  | ReadonlyURLSearchParams
+  | Record<
+      string,
+      | string
+      | number
+      | boolean
+      | readonly (string | number | boolean)[]
+      | null
+      | undefined
+    >;
+
+export interface SetSearchParamsOptions {
+  /** Replace the current history entry instead of pushing (default false). */
+  replace?: boolean;
+  /** Scroll behavior for the navigation (default: router default, scroll). */
+  scroll?: boolean;
+  /**
+   * Set false to skip the server fetch and only update the URL (default
+   * true). Purely client-derived search state (open accordions, view modes)
+   * needs no loader re-run; all location-aware hooks still update. Same
+   * contract as NavigateOptions.revalidate — it only applies because the
+   * setter never changes the pathname.
+   */
+  revalidate?: boolean;
+}
+
+export type SetSearchParams = (
+  init: SearchParamsInit | ((prev: URLSearchParams) => SearchParamsInit),
+  options?: SetSearchParamsOptions,
+) => Promise<void>;
+
+function normalizeInit(init: SearchParamsInit): URLSearchParams {
+  if (typeof init === "string") return new URLSearchParams(init);
+  if (init instanceof URLSearchParams) return new URLSearchParams(init);
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(init)) {
+    if (value == null) continue;
+    if (Array.isArray(value)) {
+      for (const entry of value) params.append(key, String(entry));
+    } else {
+      params.append(key, String(value));
+    }
+  }
+  return params;
+}
+
+/**
+ * Hook to read and write the current URL search params
+ * (React Router-style tuple).
  *
- * Returns a read-only URLSearchParams object from the committed location.
- * Updates when navigation completes, not during pending navigation.
+ * The first element is a read-only URLSearchParams from the COMMITTED
+ * location — it updates when navigation completes, not during a pending
+ * navigation. During document SSR it carries the LIVE request's search (the
+ * SSR store is seeded from SSRRenderOptions.search), and the browser's
+ * first render seeds from its own store location (window.location) — the
+ * same URL, so hydration matches. Ppr capture/resume renders seed the SHELL
+ * KEY's search (sorted, cache.searchParams filter applied — search is part
+ * of shell identity like every other ppr key), so static-part reads bake
+ * markup consistent with the shell's own key. Two edges: a param EXCLUDED
+ * by cache.searchParams is absent in shell renders but present in the
+ * browser (exclusion declares "does not affect markup" — reading one
+ * anyway hydration-mismatches), and toString() renders sorted order while
+ * the browser holds the raw URL order.
  *
- * Note: During SSR the search params are not available (the server only sends
- * the pathname). The hook returns empty params during SSR and syncs from
- * the browser URL on mount.
+ * The setter REPLACES the whole search string (React Router semantics) and
+ * navigates to the current pathname with the new params — a same-route
+ * navigation, so route loaders re-evaluate per their revalidate() contract
+ * and the commit holds previous content (the same-structure transition
+ * lane). Pass a function to merge with the current params: it receives a
+ * MUTABLE copy read at call time. The hash is dropped, like React Router.
  *
  * @example
  * ```tsx
- * const searchParams = useSearchParams();
- * const query = searchParams.get("q"); // "react"
- * const page = searchParams.get("page"); // "2"
+ * const [searchParams, setSearchParams] = useSearchParams();
+ * const category = searchParams.get("category");
+ *
+ * // Replace the whole search string
+ * setSearchParams({ category: "electronics" });
+ *
+ * // Merge with what's there now
+ * setSearchParams((prev) => {
+ *   prev.set("page", "2");
+ *   return prev;
+ * });
+ *
+ * // Filter UIs usually want replace + preserved scroll
+ * setSearchParams({ category: "home" }, { replace: true, scroll: false });
  * ```
  */
-export function useSearchParams(): ReadonlyURLSearchParams {
+export function useSearchParams(): [ReadonlyURLSearchParams, SetSearchParams] {
   const ctx = useContext(NavigationStoreContext);
 
-  // Always initialize with empty URLSearchParams to match SSR output
-  // and avoid hydration mismatch. The useEffect below syncs from
-  // the real URL after hydration.
-  const [searchParams, setSearchParams] = useState<ReadonlyURLSearchParams>(
-    () => new URLSearchParams(),
-  );
+  // Seed from the store location on BOTH sides (mirrors usePathname): the
+  // SSR store carries the live request's search, the browser store carries
+  // window.location — same URL, so the hydration renders agree. No ctx
+  // (no provider) seeds empty.
+  const [searchParams, setSearchParamsState] =
+    useState<ReadonlyURLSearchParams>(() => {
+      const location = ctx?.eventController.getState().location as
+        | URL
+        | undefined;
+      return new URLSearchParams(location?.searchParams);
+    });
 
-  const prevSearch = useRef("");
+  const prevSearch = useRef(searchParams.toString());
 
   useEffect(() => {
     if (!ctx) return;
@@ -41,16 +133,42 @@ export function useSearchParams(): ReadonlyURLSearchParams {
       const nextSearch = location.searchParams.toString();
       if (nextSearch !== prevSearch.current) {
         prevSearch.current = nextSearch;
-        // Create a snapshot so callers cannot mutate the source URLSearchParams
-        setSearchParams(new URLSearchParams(nextSearch));
+        setSearchParamsState(new URLSearchParams(nextSearch));
       }
     };
 
-    // Sync on mount (picks up search params from browser URL)
     update();
 
     return ctx.eventController.subscribe(update);
   }, []);
 
-  return searchParams;
+  // Reads the committed location at CALL time (not the render closure), so a
+  // functional init always merges against fresh params even when the caller's
+  // closure is stale.
+  const setSearchParams = useCallback<SetSearchParams>((init, options) => {
+    if (!ctx) {
+      throw new Error(
+        "useSearchParams setter must be used within NavigationProvider",
+      );
+    }
+    const location = ctx.eventController.getState().location as URL;
+    const resolved =
+      typeof init === "function"
+        ? init(new URLSearchParams(location.searchParams))
+        : init;
+    const search = normalizeInit(resolved).toString();
+    const url = search ? `${location.pathname}?${search}` : location.pathname;
+    return ctx.navigate(url, {
+      replace: options?.replace ?? false,
+      ...(options?.scroll !== undefined ? { scroll: options.scroll } : {}),
+      ...(options?.revalidate !== undefined
+        ? { revalidate: options.revalidate }
+        : {}),
+    });
+  }, []);
+
+  return useMemo(
+    () => [searchParams, setSearchParams],
+    [searchParams, setSearchParams],
+  );
 }

package/src/browser/react/use-segments.ts

@@ -25,15 +25,18 @@ function parsePathname(pathname: string): string[] {
 }
 
 /**
- * Build segments state from event controller
+ * Build segments state from event controller. `segmentIds` is the
+ * route-only list (parallels and loaders stripped) — distinct from the
+ * controller's `segmentOrder` which drives handle collection and includes
+ * parallel slot ids.
  */
 function buildSegmentsState(
   location: URL,
-  segmentOrder: string[],
+  routeSegmentIds: string[],
 ): SegmentsState {
   return {
     path: parsePathname(location.pathname),
-    segmentIds: segmentOrder,
+    segmentIds: routeSegmentIds,
     location,
   };
 }
@@ -74,7 +77,7 @@ export function useSegments<T>(
     const handleState = ctx.eventController.getHandleState();
     const segmentsState = buildSegmentsState(
       location as URL,
-      handleState.segmentOrder,
+      handleState.routeSegmentIds,
     );
     return selector ? selector(segmentsState) : segmentsState;
   });
@@ -83,47 +86,36 @@ export function useSegments<T>(
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
-  // Track selector identity to detect when the selector function changes.
-  // Only then do we eagerly recompute during render to avoid staleness.
-  // Without this guard, no-selector mode causes infinite re-renders because
-  // buildSegmentsState creates fresh arrays that fail Object.is checks.
   const prevSelectorIdentity = useRef(selector);
 
-  // Cache SegmentsState to stabilize nested references (path, segmentIds
-  // arrays) so selectors returning composite values don't cause spurious
-  // render-time setState calls.
   const segmentsCache = useRef<{
     location: URL;
-    segmentOrder: string[];
+    routeSegmentIds: string[];
     state: SegmentsState;
   } | null>(null);
 
-  // Recompute selected value from current store state and apply selector.
-  // Shared by the render-time eager check and the subscription callback.
   function recompute(
     sel: ((state: SegmentsState) => T) | undefined,
   ): T | SegmentsState {
     const location = ctx!.eventController.getLocation();
     const handleState = ctx!.eventController.getHandleState();
 
-    // Reuse cached state when inputs haven't changed by reference,
-    // keeping array/object references stable for composite selectors.
     const cache = segmentsCache.current;
     let segmentsState: SegmentsState;
     if (
       cache &&
       cache.location === location &&
-      cache.segmentOrder === handleState.segmentOrder
+      cache.routeSegmentIds === handleState.routeSegmentIds
     ) {
       segmentsState = cache.state;
     } else {
       segmentsState = buildSegmentsState(
         location as URL,
-        handleState.segmentOrder,
+        handleState.routeSegmentIds,
       );
       segmentsCache.current = {
         location: location as URL,
-        segmentOrder: handleState.segmentOrder,
+        routeSegmentIds: handleState.routeSegmentIds,
         state: segmentsState,
       };
     }
@@ -162,8 +154,6 @@ export function useSegments<T>(
       unsubscribeNav();
       unsubscribeHandles();
     };
-    // Stable subscription: selector changes are handled via selectorRef,
-    // state comparison uses prevState ref. No re-subscribe needed.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 

package/src/browser/response-adapter.ts

@@ -2,6 +2,16 @@ import { validateRedirectOrigin } from "./validate-redirect-origin.js";
 
 type HeaderResult = { url: string } | "blocked" | null;
 
+/**
+ * Null-body statuses: the Fetch spec forbids pairing these with a body, so
+ * `new Response(body, { status })` throws ("Response with null body status
+ * cannot have body"). fetch() can still surface one WITH a body straight from
+ * the network layer (never the JS constructor): a 304 stale-while-revalidate
+ * prefetch revalidated to Not Modified (body from cache), or a 204 soft
+ * redirect. teeWithCompletion must not re-run those through `new Response`.
+ */
+const NULL_BODY_STATUS = new Set([101, 204, 205, 304]);
+
 /**
  * Extract and validate an RSC response header URL (X-RSC-Reload, X-RSC-Redirect).
  * Returns { url } if valid, "blocked" if present but invalid origin, null if absent.
@@ -24,21 +34,92 @@ export function emptyResponse(): Response {
   return new Response(null, { status: 200 });
 }
 
+/**
+ * Whether an RSC content response carries a server-stamped router identity
+ * (`X-RSC-Router-Id`) that DIFFERS from the id this client expects (its own
+ * routerId, also sent as `_rsc_rid`). Pre-decode integrity check: lets a caller
+ * refuse a foreign app's payload before `createFromFetch` imports its chunks.
+ *
+ * True ONLY when both the header and the expected id are present and differ. An
+ * absent header (control-only reload/redirect responses are not stamped) or an
+ * absent expected id (e.g. before the client is seeded) is a pass-through —
+ * never a false reject.
+ */
+export function isForeignRouterId(
+  response: Response,
+  expectedId: string | undefined,
+): boolean {
+  const got = response.headers.get("X-RSC-Router-Id");
+  if (!got || !expectedId) return false;
+  return got !== expectedId;
+}
+
+/**
+ * Handle the X-RSC-Reload control header (server requests a full page reload on
+ * a version mismatch). Returns a short-circuit response when the header is
+ * present -- emptyResponse() if the URL was blocked by origin validation, or a
+ * never-resolving promise while the page reloads -- and null when absent, so
+ * the caller continues processing (e.g. the X-RSC-Redirect check). Scoped to
+ * X-RSC-Reload only; redirect handling differs between callers.
+ */
+export function handleReloadHeader(
+  response: Response,
+  opts: { onBlocked: () => void; onReload: (url: string) => void },
+): Response | Promise<Response> | null {
+  const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
+  if (reload === "blocked") {
+    opts.onBlocked();
+    return emptyResponse();
+  }
+  if (reload) {
+    opts.onReload(reload.url);
+    window.location.href = reload.url;
+    return new Promise<Response>(() => {});
+  }
+  return null;
+}
+
 /**
  * Tee a response body for RSC parsing and stream completion tracking.
  * Returns a new Response with one branch; the other is consumed to detect
  * end-of-stream, calling onComplete when done.
  *
- * If the response has no body, onComplete fires synchronously.
+ * `onComplete` receives `endedCleanly`: true only on a normal EOF drain, false
+ * on a read error or an abort (the signal cancelled the reader). Callers that
+ * gate a "fully complete" fast path (e.g. prefetch's `entry.complete`) must
+ * treat a non-clean end as incomplete — a broken stream is not complete data.
+ *
+ * If the response has no body, onComplete fires synchronously with `true`
+ * (an empty body is a clean, complete stream).
  * If signal is provided, an abort cancels the tracking reader.
+ *
+ * `silent` suppresses the stream-error log. Prefetch passes it: a speculative,
+ * low-priority prefetch that is aborted or never consumed can error its stream
+ * benignly, which is not worth surfacing. The fresh-navigation path keeps the
+ * log (default), where a stream error reflects a real failed navigation.
  */
 export function teeWithCompletion(
   response: Response,
-  onComplete: () => void,
+  onComplete: (endedCleanly: boolean) => void,
   signal?: AbortSignal,
+  silent = false,
 ): Response {
-  if (!response.body) {
-    onComplete();
+  // Once-guard: a mid-stream read error runs both the finally block and the
+  // rejection's .catch, so onComplete must be settled exactly once across all
+  // paths (no-body early return, finally, catch).
+  let settled = false;
+  const settle = (endedCleanly: boolean) => {
+    if (!settled) {
+      settled = true;
+      onComplete(endedCleanly);
+    }
+  };
+
+  // Empty body, or a null-body status fetch() paired with a body: either way the
+  // body can't be re-attached via `new Response` below. Settle and pass the
+  // original response through; its body (when present) stays readable downstream.
+  if (!response.body || NULL_BODY_STATUS.has(response.status)) {
+    settle(true);
     return response;
   }
 
@@ -48,21 +129,31 @@ export function teeWithCompletion(
     const reader = trackingStream.getReader();
     const onAbort = signal ? reader.cancel.bind(reader) : undefined;
     if (onAbort) signal!.addEventListener("abort", onAbort, { once: true });
+    // Only a loop that reaches `done` is a clean EOF. A read error rejects out
+    // of the try and still runs the finally, so the finally must NOT assume
+    // clean — it gates on this flag (false on error) AND on signal.aborted
+    // (an abort cancels the reader so read() resolves { done: true } and the
+    // loop breaks here normally, NOT in the .catch — re-check the signal to
+    // catch that case).
+    let cleanEof = false;
     try {
       while (true) {
         const { done } = await reader.read();
-        if (done) break;
+        if (done) {
+          cleanEof = true;
+          break;
+        }
       }
     } finally {
       if (onAbort) signal!.removeEventListener("abort", onAbort);
       reader.releaseLock();
-      onComplete();
+      settle(cleanEof && !signal?.aborted);
     }
   })().catch((error) => {
-    if (!signal?.aborted) {
+    if (!silent && !signal?.aborted) {
       console.error("[Browser] Error reading tracking stream:", error);
     }
-    onComplete();
+    settle(false);
   });
 
   return new Response(rscStream, {