@rangojs/router 0.22.1 → 0.24.0

package/src/client-urls/server-projection.ts

@@ -1,4 +1,3 @@
-import { requestHeaders } from "../server/request-headers.js";
 import * as React from "react";
 import type { SearchSchemaValue } from "../search-params.js";
 import { getLoaderLazy } from "../server/loader-registry.js";
@@ -7,7 +6,11 @@ import {
   getUrlPrefix,
   type InterceptSelectorContext,
 } from "../server/context.js";
-import type { LoaderDefinition, TrailingSlashMode } from "../types.js";
+import type {
+  LoaderDefinition,
+  ShouldRevalidateFn,
+  TrailingSlashMode,
+} from "../types.js";
 import type {
   PartialPrerenderProps,
   PathOptions,
@@ -16,11 +19,8 @@ import type {
 import type { PathHelpers } from "../urls/path-helper-types.js";
 import type { AllUseItems } from "../route-types.js";
 import { urls } from "../urls/urls-function.js";
-import {
-  CLIENT_REVALIDATION_HEADER,
-  decodeClientRevalidationDecisions,
-  type ClientRevalidationDecisions,
-} from "./revalidation-protocol.js";
+import { isHoistedRevalidateRef } from "./hoisted-revalidate.js";
+import { getClientUrlRevalidator } from "./revalidate-registry.js";
 import {
   ClientUrlsGroupLayout,
   ClientUrlsInterceptLoading,
@@ -96,6 +96,16 @@ export interface ClientUrlProjectionRoute {
    *  document renders await them before first flush. Absent (= none) in
    *  projections serialized before the option existed. */
   readonly awaitedLoaderIndices?: readonly number[];
+  /** Indices into loaderIds of loaders declared loader(Def, { prefetch:
+   *  false }); materialization passes the option through to the server
+   *  loader(), so a prefetch of the route defers them. Absent (= none) in
+   *  projections serialized before the option existed. */
+  readonly deferrableLoaderIndices?: readonly number[];
+  /** Per loader (aligned with loaderIds), the keys of its hoisted
+   *  revalidate() predicates in declaration order; materialization attaches
+   *  the registered predicates (revalidate-registry.ts). Absent when no
+   *  loader declares one. */
+  readonly loaderRevalidate?: readonly (readonly string[])[];
   /** Data-only transition config (never `when`); absent in projections
    *  serialized before transition support. */
   readonly transition?: Readonly<ClientTransitionConfig>;
@@ -268,7 +278,28 @@ function serializeTransition(
   return Object.freeze(config) as Readonly<ClientTransitionConfig>;
 }
 
-function serializeRoute(route: ClientUrlRouteRecord): ClientUrlProjectionRoute {
+/** Options for {@link serializeClientUrlPatterns}. */
+export interface SerializeClientUrlPatternsOptions {
+  /**
+   * The definition was loaded through the rango Vite plugin (route
+   * discovery), which moves every revalidate() predicate to the server and
+   * leaves a marker: a plain function then is a site the build could not
+   * see, and fails loudly.
+   */
+  readonly hoisted?: boolean;
+}
+
+function indicesWhere<T>(
+  items: readonly T[],
+  pred: (item: T) => boolean,
+): number[] {
+  return items.flatMap((item, index) => (pred(item) ? [index] : []));
+}
+
+function serializeRoute(
+  route: ClientUrlRouteRecord,
+  options: SerializeClientUrlPatternsOptions,
+): ClientUrlProjectionRoute {
   const loaderIds = route.loaders.map(({ loader }, index) => {
     if (typeof loader.$$id !== "string" || loader.$$id.length === 0) {
       throw projectionError(
@@ -279,9 +310,29 @@ function serializeRoute(route: ClientUrlRouteRecord): ClientUrlProjectionRoute {
     return loader.$$id;
   });
 
-  const awaitedLoaderIndices = route.loaders
-    .map(({ ssr }, index) => (ssr === false ? index : -1))
-    .filter((index) => index >= 0);
+  const loaderRevalidate = route.loaders.map(({ loader, revalidate }) =>
+    revalidate.flatMap((entry) => {
+      if (isHoistedRevalidateRef(entry)) return [entry.$$rangoRevalidate];
+      if (options.hoisted) {
+        throw new Error(
+          `clientUrls() revalidate() on loader "${loader.$$id}" of route ` +
+            `"${route.pattern}" was not hoisted to the server: call the ` +
+            "builder's revalidate() helper with an inline function or an " +
+            "imported predicate.",
+        );
+      }
+      return [];
+    }),
+  );
+
+  const awaitedLoaderIndices = indicesWhere(
+    route.loaders,
+    ({ ssr }) => ssr === false,
+  );
+  const deferrableLoaderIndices = indicesWhere(
+    route.loaders,
+    ({ prefetch }) => prefetch === false,
+  );
 
   const transition = serializeTransition(route);
   return Object.freeze({
@@ -294,6 +345,16 @@ function serializeRoute(route: ClientUrlRouteRecord): ClientUrlProjectionRoute {
     ...(awaitedLoaderIndices.length > 0
       ? { awaitedLoaderIndices: Object.freeze(awaitedLoaderIndices) }
       : {}),
+    ...(deferrableLoaderIndices.length > 0
+      ? { deferrableLoaderIndices: Object.freeze(deferrableLoaderIndices) }
+      : {}),
+    ...(loaderRevalidate.some((keys) => keys.length > 0)
+      ? {
+          loaderRevalidate: Object.freeze(
+            loaderRevalidate.map((keys) => Object.freeze(keys)),
+          ),
+        }
+      : {}),
     ...(transition ? { transition } : {}),
     ...(typeof route.transition?.when === "function"
       ? { transitionWhen: true as const }
@@ -325,16 +386,41 @@ function serializeIntercept(
 
 export function serializeClientUrlPatterns(
   patterns: ClientUrlPatterns,
+  options: SerializeClientUrlPatternsOptions = {},
 ): ClientUrlProjection {
   return Object.freeze({
     version: 1 as const,
-    routes: Object.freeze(patterns.routes.map(serializeRoute)),
+    routes: Object.freeze(
+      patterns.routes.map((route) => serializeRoute(route, options)),
+    ),
     intercepts: Object.freeze(
       (patterns.intercepts ?? []).map(serializeIntercept),
     ),
   });
 }
 
+/**
+ * The projection of a clientUrls() module from its namespace, or undefined
+ * when its default export is not a clientUrls() definition. Discovery
+ * (vite/discovery/client-urls-projection.ts) and the testing "use client"
+ * transform (testing/internal/client-urls-projection.ts) both project a
+ * module through it.
+ */
+export function projectClientUrlsModule(
+  namespace: Readonly<Record<string, unknown>>,
+  options: SerializeClientUrlPatternsOptions = {},
+): ClientUrlProjection | undefined {
+  const definition = namespace.default;
+  if (
+    (typeof definition !== "object" && typeof definition !== "function") ||
+    definition === null ||
+    (definition as { __brand?: unknown }).__brand !== "client-urls"
+  ) {
+    return undefined;
+  }
+  return serializeClientUrlPatterns(definition as ClientUrlPatterns, options);
+}
+
 export function isClientUrlPatterns(
   value: unknown,
 ): value is ClientUrlPatterns {
@@ -425,53 +511,42 @@ export function clearClientUrlProjections(): void {
 }
 
 /**
- * Per-request memo for decoded client revalidation decisions: the synthesized
- * predicate below runs once per loader stub per revalidation pass, and every
- * stub reads the same header.
- */
-const decisionsByRequest = new WeakMap<
-  Request,
-  ClientRevalidationDecisions | null
->();
-
-function clientDecisionsFor(
-  request: Request | undefined,
-): ClientRevalidationDecisions | null {
-  if (!request) return null;
-  if (decisionsByRequest.has(request)) {
-    return decisionsByRequest.get(request) ?? null;
-  }
-  const decoded = decodeClientRevalidationDecisions(
-    requestHeaders(request).get(CLIENT_REVALIDATION_HEADER),
-  );
-  decisionsByRequest.set(request, decoded);
-  return decoded;
-}
-
-/**
- * The server end of client-run per-loader revalidation: clientUrls()
- * revalidate() predicates EXECUTE in the browser (they are client-module
- * code), and their decisions arrive on the request header. This synthesized
- * predicate — attached to every materialized loader stub — honors a decision
- * addressed to its loader id and otherwise returns the locked default, which
- * is also the behavior for requests that carry no decisions (no-JS, PE,
- * prefetch, document loads). Decisions can only address client-urls stubs;
- * server-tree loaders never see this predicate.
+ * The revalidate() predicates of one materialized loader. A definition
+ * object (unit tests, the testing primitives) carries its functions. A
+ * client reference resolves the projection's content keys in the registry
+ * the group's hoisted module filled when it loaded; a key with no
+ * registration fails loudly here, at materialization, never at a request.
  */
-function makeClientDecisionRevalidate(
-  loaderId: string,
-): (args: {
-  defaultShouldRevalidate: boolean;
-  context: { request: Request };
-}) => boolean {
-  return ({ defaultShouldRevalidate, context }) => {
-    const decisions = clientDecisionsFor(context?.request);
-    if (decisions) {
-      if (decisions.skip.includes(loaderId)) return false;
-      if (decisions.force.includes(loaderId)) return true;
+function loaderRevalidators(
+  reference: ClientUrlDefinitionSource,
+  route: ClientUrlProjectionRoute,
+  loaderIndex: number,
+): ShouldRevalidateFn<any, any>[] {
+  const fromRegistry = (key: string): ShouldRevalidateFn<any, any> => {
+    if (!getClientUrlRevalidator(key)) {
+      const id = isClientUrlReference(reference) ? reference.$$id : "(inline)";
+      throw new Error(
+        `clientUrls() revalidate() on loader "${route.loaderIds[loaderIndex]}" ` +
+          `of route "${route.pattern}" in "${id}" has no server ` +
+          `registration (key "${key}"). The rango Vite plugin registers ` +
+          "hoisted predicates when the group's module loads in the RSC " +
+          "environment; a transform that changed the predicate's syntax " +
+          "in one environment only also causes this.",
+      );
     }
-    return defaultShouldRevalidate;
+    // Looked up per call: a dev re-evaluation of the hoisted module
+    // re-registers the key with functions bound to the current imports.
+    return (args) => getClientUrlRevalidator(key)!(args);
   };
+  if (isClientUrlPatterns(reference)) {
+    const record = reference.routes.find(({ id }) => id === route.id);
+    return (record?.loaders[loaderIndex]?.revalidate ?? []).map((entry) =>
+      isHoistedRevalidateRef(entry)
+        ? fromRegistry(entry.$$rangoRevalidate)
+        : entry,
+    );
+  }
+  return (route.loaderRevalidate?.[loaderIndex] ?? []).map(fromRegistry);
 }
 
 function createLoaderStub(id: string): LoaderDefinition<unknown> {
@@ -551,15 +626,25 @@ function materializeRouteItems(
             }),
           materializedPathOptions(route, clientGroup),
           () => [
-            ...route.loaderIds.map((id, loaderIndex) =>
-              loader(
+            ...route.loaderIds.map((id, loaderIndex) => {
+              const revalidators = loaderRevalidators(
+                reference,
+                route,
+                loaderIndex,
+              );
+              return loader(
                 createLoaderStub(id),
-                route.awaitedLoaderIndices?.includes(loaderIndex)
-                  ? { ssr: false }
-                  : undefined,
-                () => [revalidate(makeClientDecisionRevalidate(id))],
-              ),
-            ),
+                {
+                  ...(route.awaitedLoaderIndices?.includes(loaderIndex) && {
+                    ssr: false,
+                  }),
+                  ...(route.deferrableLoaderIndices?.includes(loaderIndex) && {
+                    prefetch: false,
+                  }),
+                },
+                () => revalidators.map((fn) => revalidate(fn)),
+              );
+            }),
             ...(route.hasLoading
               ? [
                   loading(
@@ -703,7 +788,8 @@ export function clientUrlIncludePatterns(
       throw new Error(
         `include() could not resolve the server projection for clientUrls() module "${id}". ` +
           'The definition must be the default export of a "use client" module so the ' +
-          "Vite discovery pass can project it; in unit tests pass the clientUrls() object directly.",
+          "Vite discovery pass can project it; in a Vitest project, rangoUseClientTransform() " +
+          "from @rangojs/router/testing/vitest projects it.",
       );
     }
     return materializeRouteItems(source, projection, helpers);

package/src/client-urls/types.ts

@@ -1,10 +1,12 @@
 import type { ComponentType, ReactNode } from "react";
 import type {
-  IsActionFn,
   LoaderDefinition,
   LoaderOptions,
+  ShouldRevalidateFn,
   TransitionConfig,
 } from "../types.js";
+import type { DefaultEnv } from "../types/global-namespace.js";
+import type { HoistedRevalidateRef } from "./hoisted-revalidate.js";
 import type { TrieMatchResult } from "../router/trie-matching.js";
 import type { PathOptions } from "../urls/pattern-types.js";
 import type { SearchSchema } from "../search-params.js";
@@ -50,69 +52,17 @@ export type ClientLayoutFn = <const TItems extends ClientUrlItems>(
   children: () => TItems,
 ) => ClientUrlItem & TypedLayoutItem<ExtractRoutes<TItems>>;
 
-/**
- * Arguments a clientUrls() revalidate() predicate receives. A client-computable
- * subset of the server ShouldRevalidateFn args — the predicate RUNS IN THE
- * BROWSER (it is declared in a "use client" module and never crosses the
- * projection boundary); only its decision is sent to the server. There is no
- * `context` — no server handler context exists where this executes. `isAction`
- * is the same callable matcher as on the server, not a boolean.
- */
-export interface ClientRevalidateArgs {
-  /** Full URL of the page being navigated away from (current location). */
-  readonly currentUrl: URL;
-  /** Full URL of the navigation target (equals currentUrl for actions). */
-  readonly nextUrl: URL;
-  /** Route params of the held client route (definition-local match). */
-  readonly currentParams: Record<string, string>;
-  /** Route params for the navigation target (definition-local match). */
-  readonly nextParams: Record<string, string>;
-  /**
-   * The current default decision for this loader, computed client-side with
-   * the same rules the server applies to the request the decisions ride on:
-   * `true` when they ride the action POST itself, otherwise `true` when
-   * params/search changed. (An action-triggered refetch GET gets navigation
-   * defaults — matching the server — even though `isAction()` is true.)
-   * Earlier predicates' `{ defaultShouldRevalidate }` verdicts thread into
-   * this value, exactly like the server chain. Return it for default
-   * behavior plus your own conditions.
-   */
-  readonly defaultShouldRevalidate: boolean;
-  /** True when this is a stale history-entry background revalidation. */
-  readonly stale: boolean;
-  /**
-   * Same {@link IsActionFn} the server `revalidate()` predicate receives.
-   * In the browser the match is against the action stub's hashed `$$id`
-   * (the id the action request carries) — not the RSC file-path `$id`.
-   */
-  readonly isAction: IsActionFn;
-  /**
-   * The triggering server action's id, when this is an action. In the
-   * browser this is the hashed `hash#export` form (`$$id`), not the RSC
-   * file-path `src/...#export`. Prefer `isAction(ref)` — a substring of
-   * `path#export` will not match here in production.
-   */
-  readonly actionId?: string;
-}
-
-/**
- * Client-run per-loader predicate, with the same chain semantics as the
- * server's `revalidate()` (src/router/revalidation.ts): a boolean is a HARD
- * decision that short-circuits the rest of the chain; a
- * `{ defaultShouldRevalidate }` object updates the running suggestion, which
- * later predicates receive as their `defaultShouldRevalidate`; `void` /
- * `null` / `undefined` defers to the current suggestion — so
- * `isAction(CartActions) || undefined` defers to the locked default.
- * Predicates must be synchronous; the object form requires a boolean value.
- */
-export type ClientRevalidateFn = (
-  args: ClientRevalidateArgs,
-) => boolean | { defaultShouldRevalidate: boolean } | null | void;
-
 export interface ClientUrlLoaderRecord {
   readonly loader: LoaderDefinition<any, any>;
-  /** Client-run per-loader revalidation predicates; empty = locked defaults. */
-  readonly revalidate: readonly ClientRevalidateFn[];
+  /**
+   * Per-loader revalidate() predicates, run on the server; empty = the
+   * router's defaults. Under the rango Vite plugin the browser and SSR copies
+   * hold the marker the build left in place of each hoisted predicate.
+   */
+  readonly revalidate: readonly (
+    | ShouldRevalidateFn<any, DefaultEnv>
+    | HoistedRevalidateRef
+  )[];
   /**
    * loader(Def, { ssr: false }): document renders await this loader before
    * first flush (see {@link LoaderOptions}). Projected into the server tree,
@@ -120,6 +70,14 @@ export interface ClientUrlLoaderRecord {
    * regardless.
    */
   readonly ssr?: false;
+  /**
+   * loader(Def, { prefetch: false }): a prefetch of the route defers this
+   * loader and the click that adopts it runs it in its fill request (see
+   * {@link LoaderOptions}). Projected onto the materialized stub. Inside
+   * intercept() it is not recorded: intercept loaders ignore the flag, as in
+   * urls().
+   */
+  readonly prefetch?: false;
 }
 
 /**
@@ -172,8 +130,7 @@ export interface ClientUrlHelpers {
   readonly layout: ClientLayoutFn;
   /**
    * Attach a projected loader. The optional use callback may contain
-   * revalidate() only — a CLIENT-RUN per-loader predicate; its decision (not
-   * the function) is sent with the revalidation request.
+   * revalidate() only: a per-loader predicate the server runs, as in urls().
    *
    * Pass `{ ssr: false }` — the same knob as loading(fallback, { ssr:
    * false }) — to await this loader before first flush on DOCUMENT requests
@@ -183,22 +140,33 @@ export interface ClientUrlHelpers {
    * route the flag BAKES: the loader executes at shell capture and its
    * settled return freezes into the shell (nested promises stay live
    * holes).
+   *
+   * Pass `{ prefetch: false }` to keep this loader out of the route's
+   * prefetches (see {@link LoaderOptions}): an in-group click still shows
+   * the destination at once, commits the adopted prefetch with the other
+   * loaders' data, and runs only the flagged loaders in its one fill
+   * request. A `layout()` loader with the flag is flagged on every route
+   * below it. Inside intercept() the flag is accepted and ignored, as in
+   * urls().
    */
   readonly loader: <TData>(
     definition: LoaderDefinition<TData>,
-    optionsOrUse?: LoaderOptions | ClientUrlUse,
+    optionsOrUse?: Pick<LoaderOptions, "ssr" | "prefetch"> | ClientUrlUse,
     use?: ClientUrlUse,
   ) => ClientUrlItem;
   readonly loading: (component: ReactNode) => ClientUrlItem;
   /**
    * Per-loader revalidation predicate, valid inside a loader() use callback
-   * only. Runs IN THE BROWSER with client-computable args (including the
-   * callable `isAction(...refs)` matcher); return true to re-run the loader,
-   * false to keep held data. Absent predicates (and requests that carry no
-   * decisions: no-JS, PE, prefetch, document loads) follow the locked server
-   * defaults.
+   * only. It runs ON THE SERVER with the same arguments as a urls() loader's
+   * revalidate() (`actionResult`, `formData`, `context`, `isAction`, route
+   * names, ...): the build moves it out of this "use client" module. It may
+   * reference imports and globals only; a binding of this module, `this`,
+   * `import()`, a browser global, an `async` function or an import from a
+   * "use client" module fails the build with its file and line.
    */
-  readonly revalidate: (fn: ClientRevalidateFn) => ClientUrlItem;
+  readonly revalidate: (
+    fn: ShouldRevalidateFn<any, DefaultEnv>,
+  ) => ClientUrlItem;
   /**
    * Declare an intercept for a named route in THIS definition. The target is
    * dot-local (`.detail`); scoping is module-local — only navigations whose

package/src/client.tsx

@@ -30,6 +30,7 @@ import { AuditedOutletProvider, OutletProvider } from "./outlet-provider.js";
 import { INTERNAL_RANGO_SUSPENSE_AUDIT } from "./internal-suspense-audit.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import { getBoundaryContent } from "./segment-boundary-content.js";
+import { asStream } from "./browser/defer.js";
 
 /**
  * Render the content for a named parallel/intercept slot segment.
@@ -41,6 +42,13 @@ import { getBoundaryContent } from "./segment-boundary-content.js";
 function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
   if (!segment) return null;
 
+  // A slot that streams with no loading() gets a boundary with no fallback
+  // around its promise. A deferred slot's hole (`prefetch: false`) is a
+  // Defer, not a promise: it is what its fill resolves, and the slot it
+  // stands for was awaited, so every later render of the page has the
+  // content here with no boundary around it. The hole takes that place, read
+  // by React (browser/defer.ts asStream): another element here and the slot
+  // is mounted again when the page is next rendered.
   const content: ReactNode =
     segment.loading || segment.component instanceof Promise ? (
       <RouteContentWrapper
@@ -49,7 +57,7 @@ function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
         segmentId={segment.id}
       />
     ) : (
-      (segment.component ?? null)
+      ((asStream(segment.component) as ReactNode) ?? null)
     );
 
   const hasOwnLoaders = !!(segment.loaderDataPromise && segment.loaderIds);
@@ -511,7 +519,3 @@ export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
 
 export type { LoaderDefinition } from "./types.js";
 export type { ActionRef, IsActionFn } from "./types.js";
-export type {
-  ClientRevalidateArgs,
-  ClientRevalidateFn,
-} from "./client-urls/types.js";

package/src/context-var.ts

@@ -125,8 +125,38 @@ export function contextGet(
   return variables[keyOrVar.key];
 }
 
-/** Keys that must never be used as string variable names */
-const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Keys that must never be used as string variable names, nor as a fetchable
+ * loader's request params (rsc/loader-fetch.ts).
+ */
+export const FORBIDDEN_KEYS: ReadonlySet<string> = new Set([
+  "__proto__",
+  "constructor",
+  "prototype",
+]);
+
+/**
+ * `target[key] = value` as an own data property, `__proto__` included: that
+ * assignment would call Object.prototype's setter and replace the target's
+ * prototype, which Flight refuses to serialize (#1109). Loader data parsed
+ * from JSON, cookie names and the like can carry the key.
+ */
+export function assignOwn(
+  target: Record<string, unknown>,
+  key: string,
+  value: unknown,
+): void {
+  if (key === "__proto__") {
+    Object.defineProperty(target, key, {
+      value,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    });
+  } else {
+    target[key] = value;
+  }
+}
 
 export interface ContextSetOptions {
   /**

package/src/errors.ts

@@ -296,6 +296,25 @@ export function isSkip(value: unknown): value is Skip {
   return value instanceof Skip;
 }
 
+/**
+ * A request middleware rewrote (`throw rewrite()`) more than `maxHops` times,
+ * or to the URL it was on. Reported through `onError` (phase "routing") and
+ * answered with 508. `trail` lists the URLs, the visitor's first.
+ */
+export class RewriteLoopError extends Error {
+  name = "RewriteLoopError" as const;
+  readonly trail: readonly string[];
+
+  constructor(trail: readonly string[], maxHops: number) {
+    super(
+      `Infinite rewrite loop: ${trail.join(" -> ")}. A request is rewritten ` +
+        `at most ${maxHops} times, and never to the URL it is on.`,
+    );
+    Object.setPrototypeOf(this, RewriteLoopError.prototype);
+    this.trail = trail;
+  }
+}
+
 /**
  * Thrown by the partial updater when the server responds with a redirect payload
  * that carries location state. Caught by navigate() to re-navigate to the
@@ -345,6 +364,21 @@ export function invariant(condition: any, message: string): asserts condition {
   }
 }
 
+/**
+ * Rejects a boolean-only DSL option that holds anything else (undefined
+ * passes), as an invariant.
+ */
+export function assertBooleanOption(
+  value: unknown,
+  option: string,
+  effect: string,
+): void {
+  invariant(
+    value === undefined || typeof value === "boolean",
+    `${option} must be a boolean (got ${JSON.stringify(value)}). Omit it (or pass true) to ${effect}.`,
+  );
+}
+
 /**
  * Sanitize errors for production - prevents leaking sensitive information
  *

package/src/handles/deferred-resolution.ts

@@ -1,5 +1,6 @@
 import type { HandleData, HandleStore } from "../server/handle-store.js";
 import { isThenable } from "./is-thenable.js";
+import { isPushedByKey, pushedByKey } from "./pushed-by.js";
 
 /**
  * Runtime-neutral resolution of deferred (Promise) handle values. Shared by the
@@ -39,7 +40,8 @@ export function deferredHandleNames(data: HandleData): Set<string> {
  * thenables). A rejected deferred is dropped, and a deferred that resolves to
  * `null`/`undefined` is dropped (the `.defer({ else })` skip semantics), so a
  * nullish deferred slot never reaches a collector. Sync (non-thenable) values —
- * including a legitimate sync `null` push — pass through unchanged.
+ * including a legitimate sync `null` push — pass through unchanged. A
+ * pushedBy record (pushed-by.ts) loses the entries of the dropped values.
  */
 export async function resolveDeferredHandleValues(
   data: HandleData,
@@ -47,22 +49,37 @@ export async function resolveDeferredHandleValues(
   const out: HandleData = {};
   await Promise.all(
     Object.entries(data).flatMap(([handleName, segments]) => {
+      if (isPushedByKey(handleName)) return [];
       out[handleName] = {};
+      const byName = pushedByKey(handleName);
+      const pushedBy = data[byName];
       return Object.entries(segments).map(async ([segmentId, values]) => {
-        out[handleName][segmentId] = await resolveValues(values);
+        const resolved = await resolveValues(values);
+        out[handleName][segmentId] = keptValues(resolved);
+        const by = pushedBy?.[segmentId];
+        if (by) {
+          (out[byName] ??= {})[segmentId] = by.filter(
+            (_, i) => resolved[i].keep,
+          );
+        }
       });
     }),
   );
   return out;
 }
 
+interface ResolvedValue {
+  keep: boolean;
+  value: unknown;
+}
+
 // Resolve each entry IN ORDER. A non-thenable passes through verbatim (including
 // a legitimate sync `null`/`undefined` push — the "await iff thenable" contract).
 // A thenable is awaited and dropped when it rejects OR resolves to null/undefined
 // (the `.defer({ else })` skip semantics: a forgotten resolver times out to
 // `else ?? undefined`), so a nullish deferred slot never reaches a collector.
-async function resolveValues(values: unknown[]): Promise<unknown[]> {
-  const resolved = await Promise.all(
+function resolveValues(values: unknown[]): Promise<ResolvedValue[]> {
+  return Promise.all(
     values.map(async (v) => {
       if (!isThenable(v)) return { keep: true, value: v };
       try {
@@ -73,6 +90,9 @@ async function resolveValues(values: unknown[]): Promise<unknown[]> {
       }
     }),
   );
+}
+
+function keptValues(resolved: ResolvedValue[]): unknown[] {
   return resolved.filter((r) => r.keep).map((r) => r.value);
 }
 
@@ -141,8 +161,11 @@ export function recordedHandleData(
   const recorded: HandleData = {};
   for (const segmentId of segmentIds) {
     const kept = handleStore.getDataForSegment(segmentId, true);
+    const pushedBy = handleStore.getPushedBy(segmentId, true);
     for (const handleName in kept) {
       (recorded[handleName] ??= {})[segmentId] = kept[handleName];
+      const by = pushedBy?.[handleName];
+      if (by) (recorded[pushedByKey(handleName)] ??= {})[segmentId] = by;
     }
   }
   return recorded;
@@ -163,7 +186,7 @@ export async function resolveSegmentHandleValues(
   const out: Record<string, unknown[]> = {};
   await Promise.all(
     Object.entries(segHandles).map(async ([handleName, values]) => {
-      out[handleName] = await resolveValues(values);
+      out[handleName] = keptValues(await resolveValues(values));
     }),
   );
   return out;