@rangojs/router 0.17.0 → 0.19.0

package/src/router/segment-resolution/mask-nested.ts

@@ -1,14 +1,17 @@
 /**
- * Capture-side nested-thenable masking — the mechanism behind "nested-promise
- * shape is the liveness declaration" for BOTH bake-lane loader containers
- * (loader-cache.ts) and pushed handle containers (the capture handle store's
- * push wrap in rsc/shell-capture.ts).
+ * Capture-side nested thenables. Masking is the mechanism behind "nested-
+ * promise shape is the liveness declaration" for the loader lane: bake-lane
+ * loader containers (loader-cache.ts) and DSL loader handle pushes (the
+ * capture handle store's push wrap in rsc/shell-capture.ts). Handler handle
+ * pushes are handler output and bake: the capture waits for their nested
+ * promises instead (settleNestedThenables).
  *
  * Deliberately a LEAF module: loader-mask (the other natural home) imports
  * request-context, so any funnel importing the mask from there inherits that
- * graph. This module imports only is-thenable.
+ * graph. This module imports only is-thenable and react.
  */
 
+import { cloneElement, isValidElement, type ReactElement } from "react";
 import { isThenable } from "../../handles/is-thenable.js";
 
 /**
@@ -23,18 +26,127 @@ export function createMaskedLoaderPromise<T = unknown>(): Promise<T> {
   return new Promise<T>(() => {});
 }
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
+/**
+ * A data object the container walks descend into: prototype Object.prototype
+ * or null, and no symbol `$$typeof`. React elements, lazy nodes and references
+ * are plain objects too, told apart by that symbol (Flight switches on it).
+ * They are React's, not data: an element's dev-only fields (`_debugStack`,
+ * `_debugTask`, `_debugInfo`, `ref`) are non-enumerable, so a key-by-key copy
+ * drops them and dev Flight refuses it ("Attempted to render <x> without
+ * development properties", issue #942).
+ */
+export function isPlainDataObject(
+  value: unknown,
+): value is Record<string, unknown> {
   if (typeof value !== "object" || value === null) return false;
   const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
+  if (proto !== Object.prototype && proto !== null) return false;
+  return typeof (value as { $$typeof?: unknown }).$$typeof !== "symbol";
+}
+
+type KeyValidated = { _store?: { validated?: unknown } };
+
+/**
+ * cloneElement with only the given props replaced, keeping React's dev key
+ * validation. React 19 dev cloneElement resets `_store.validated`, so a
+ * keyless child of a static children list (validated at creation) would warn
+ * "Each child in a list should have a unique key" once cloned. Pass only the
+ * props that change: cloneElement re-parents the element (owner) when its
+ * config carries `ref`.
+ */
+export function cloneElementWithProps(
+  element: ReactElement,
+  props: Record<string, unknown>,
+): ReactElement {
+  const clone = cloneElement(element, props);
+  const from = (element as KeyValidated)._store;
+  const to = (clone as KeyValidated)._store;
+  if (from && to) to.validated = from.validated;
+  return clone;
+}
+
+/**
+ * Resolves once `value` and every thenable reachable from it through plain
+ * data objects, arrays and React element props has settled, following what
+ * each thenable resolves to. A rejection counts as settled: the consumer that
+ * encodes the value reports it. Other objects are leaves (the same walk as
+ * maskNestedContainerThenables), so a promise inside a Map is not waited for.
+ * An element is walked through its props only (`<X data={promise} />` in a
+ * handle value is handler output too), never its owner or type, and is never
+ * rebuilt: nothing is copied, only awaited.
+ *
+ * The capture waits on this for HANDLER handle pushes (shell-capture.ts):
+ * handler output is baked, so its promises must settle before the doc record
+ * encodes the handles every HIT replays.
+ */
+export function settleNestedThenables(value: unknown): Promise<void> {
+  const pending: Promise<void>[] = [];
+  someNestedThenable(value, (thenable) => {
+    pending.push(
+      Promise.resolve(thenable).then(settleNestedThenables, () => undefined),
+    );
+    return false;
+  });
+  return pending.length === 0
+    ? Promise.resolve()
+    : Promise.all(pending).then(() => undefined);
+}
+
+/**
+ * The walk settleNestedThenables and holdsThenable share: visit each thenable
+ * reachable from `value` through plain data objects, arrays and React element
+ * props (never an element's owner or type), the shapes
+ * maskNestedContainerThenables masks; every other object is a leaf. Stops at
+ * the first visit that returns true and reports whether one did.
+ */
+function someNestedThenable(
+  value: unknown,
+  visit: (thenable: PromiseLike<unknown>) => boolean,
+): boolean {
+  let seen: Set<object> | undefined;
+  const walk = (v: unknown): boolean => {
+    if (isThenable(v)) return visit(v);
+    if (typeof v !== "object" || v === null) return false;
+    if (isValidElement<Record<string, unknown>>(v)) return walk(v.props);
+    if (!Array.isArray(v) && !isPlainDataObject(v)) return false;
+    seen ??= new Set();
+    if (seen.has(v)) return false;
+    seen.add(v);
+    // Own enumerable values, as maskNestedContainerThenables walks
+    // Object.keys: an array's non-index properties are walked too.
+    return Object.values(v).some(walk);
+  };
+  return walk(value);
 }
 
 /**
- * Deep-copy a container with every NESTED thenable replaced by a masked
+ * True when `value` is a thenable or holds one where the capture's loader
+ * push funnel masks it (maskNestedContainerThenables): through plain data
+ * objects, arrays and React element props. Such a push stays out of a shell's
+ * record and reaches a HIT only from a run of its loader there, so a HIT
+ * keeps it; a push without one is the record's (HandleStore.pushRestored).
+ */
+export function holdsThenable(value: unknown): boolean {
+  return someNestedThenable(value, () => true);
+}
+
+/**
+ * Optional single-walk report for maskNestedContainerThenables: `thenable`
+ * flips true when the walk masked at least one thenable. The capture push
+ * funnel reads it for a loader push: a container with a masked nested
+ * promise keeps its loader tag, so the handle encode never waits on a mask.
+ * Same single-pass shape as elideLoaderContainer's `hasHole`.
+ */
+export interface MaskReport {
+  thenable: boolean;
+}
+
+/**
+ * Copy a container with every NESTED thenable replaced by a masked
  * (never-resolving) promise. Applied during shell capture to (a) bake-lane
- * loader containers (loader-cache.ts) and (b) pushed handle containers
- * (shell-capture.ts capture store push wrap) — the two rango-owned funnels
- * where consumers declare per-request data by promise SHAPE.
+ * loader containers (loader-cache.ts) and (b) DSL loader handle pushes
+ * (shell-capture.ts capture store push wrap) — the rango-owned funnels where
+ * a loader declares per-request data by promise SHAPE.
  *
  * Why: a nested promise that happened to SETTLE before the capture's quiet
  * window closed used to bake its value into the SHARED shell (and, for
@@ -46,23 +158,16 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * Masking makes the consuming subtree postpone as a hole no matter when the
  * promise settles: liveness by declaration, not by racing the window.
  *
- * Only plain objects/arrays are traversed; other values are leaves. The INPUT
- * IS NEVER MUTATED — handler-side loader consumption (the consumption-lane
- * rule, semantic-matrix PPR3) shares the raw container and must keep real
- * values. Cycles are preserved as cycles in the copy.
+ * Plain data objects, arrays and React element props are traversed: JSX
+ * carrying a promise (`<Reviews data={fetchReviews()} />`) declares
+ * per-request data the same way a plain container does. Other values, lazy
+ * nodes included, are leaves. Copy-on-write: a subtree without a thenable
+ * comes back by identity, so an element is rebuilt only when its props hold
+ * one, and then through cloneElementWithProps, which keeps its type, key,
+ * owner, dev fields and key validation. The INPUT IS NEVER MUTATED: a handler
+ * that reads the loader (`ctx.use`) reads the raw container and must keep
+ * real values. Cycles are preserved as cycles in the copy.
  */
-/**
- * Optional single-walk report for maskNestedContainerThenables: `thenable`
- * flips true when the walk masked at least one thenable. The shell fast path
- * reads it at handle-push time — a pushed container with a nested thenable
- * declares per-request data, and a shell entry whose HANDLER layer made such
- * a declaration cannot be served handler-free (the hole would never fill).
- * Same single-pass shape as elideLoaderContainer's `hasHole`.
- */
-export interface MaskReport {
-  thenable: boolean;
-}
-
 export function maskNestedContainerThenables(
   value: unknown,
   seen: Map<object, unknown> = new Map(),
@@ -72,27 +177,41 @@ export function maskNestedContainerThenables(
     if (report) report.thenable = true;
     return createMaskedLoaderPromise();
   }
+  if (typeof value !== "object" || value === null) return value;
+  const cached = seen.get(value);
+  if (cached !== undefined) return cached;
 
-  if (Array.isArray(value)) {
-    const cached = seen.get(value);
-    if (cached !== undefined) return cached;
-    const out: unknown[] = new Array(value.length);
-    seen.set(value, out);
-    for (let i = 0; i < value.length; i++) {
-      out[i] = maskNestedContainerThenables(value[i], seen, report);
+  if (isValidElement<Record<string, unknown>>(value)) {
+    // Placeholder: a cycle back to this element through its props keeps the
+    // original.
+    seen.set(value, value);
+    const props = value.props;
+    let maskedProps: Record<string, unknown> | undefined;
+    for (const key of Object.keys(props)) {
+      const masked = maskNestedContainerThenables(props[key], seen, report);
+      if (masked !== props[key]) (maskedProps ??= {})[key] = masked;
     }
-    return out;
+    if (!maskedProps) return value;
+    const clone = cloneElementWithProps(value, maskedProps);
+    seen.set(value, clone);
+    return clone;
   }
 
-  if (isPlainObject(value)) {
-    const cached = seen.get(value);
-    if (cached !== undefined) return cached;
-    const out: Record<string, unknown> = {};
+  if (Array.isArray(value) || isPlainDataObject(value)) {
+    const source = value as Record<string, unknown>;
+    const out = (Array.isArray(value) ? new Array(value.length) : {}) as Record<
+      string,
+      unknown
+    >;
     seen.set(value, out);
-    for (const key of Object.keys(value)) {
-      out[key] = maskNestedContainerThenables(value[key], seen, report);
+    let changed = false;
+    for (const key of Object.keys(source)) {
+      out[key] = maskNestedContainerThenables(source[key], seen, report);
+      if (out[key] !== source[key]) changed = true;
     }
-    return out;
+    if (changed) return out;
+    seen.set(value, value);
+    return value;
   }
 
   return value;

package/src/router/segment-resolution/revalidation.ts

@@ -45,7 +45,8 @@ import {
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
-import { observeEvent, observeHandler } from "../instrument.js";
+import { observeEvent, observeSegmentHandler } from "../instrument.js";
+import { runInSegmentTagScope } from "../../cache/cache-tag.js";
 import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
 import {
   track,
@@ -221,7 +222,8 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   // whole-container-mask every loader on this path (a never-settling promise
   // for a loader that should have executed).
   // Outside capture the key only activates the _shellLoaderSeed overlay,
-  // which document-only serveShellHit seeds — inert for partial requests.
+  // which serveShellHit seeds for a document HIT and the PPR partial replay
+  // (matchPartialWithPprReplay) seeds once its doc record hits.
   const bakeLane = !entryLoadingMasksLoaders(entry.loading);
 
   const loadersToRun = revalidationChecks.filter((c) => c.shouldRun);
@@ -240,9 +242,10 @@ export async function resolveLoadersWithRevalidation<TEnv>(
             loaderEntry,
             ctx,
             ctx.pathname,
-            bakeLane || loaderEntry.awaitBeforeFlush === true
-              ? segmentId
-              : null,
+            // `bake`, not awaitBeforeFlush: a navigation evaluation never
+            // carries awaitBeforeFlush, and an ssr: false loader must pin
+            // here exactly as on the document HIT.
+            bakeLane || loaderEntry.bake === true ? segmentId : null,
           ),
         ),
         entry,
@@ -476,7 +479,9 @@ async function resolveParallelSlotComponent<TEnv>(args: {
       handlerRan = true;
       if (hasLoadingFallback) {
         const result =
-          typeof handler === "function" ? handler(context) : handler;
+          typeof handler === "function"
+            ? runInSegmentTagScope(parallelId, handler, context)
+            : handler;
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, parallelId);
           const tracked = deps.trackHandler(result, {
@@ -497,7 +502,9 @@ async function resolveParallelSlotComponent<TEnv>(args: {
         }
       } else {
         component =
-          typeof handler === "function" ? await handler(context) : handler;
+          typeof handler === "function"
+            ? await runInSegmentTagScope(parallelId, handler, context)
+            : handler;
       }
     }
   }
@@ -701,7 +708,6 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       transition: applyViewTransitionDefault(
         parallelEntry.transition,
         deps.viewTransitionDefault,
-        parallelId,
       ),
       params,
       slot,
@@ -842,14 +848,19 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
           : routeEntry.handler;
       if (!routeEntry.loading) {
         const result = handleHandlerResult(
-          await observeHandler(entry.id, handler, context),
+          await observeSegmentHandler(
+            entry.shortCode,
+            entry.id,
+            handler,
+            context,
+          ),
         );
         doneHandler();
         return result;
       }
       if (!actionContext) {
         const result = handleHandlerResult(
-          observeHandler(entry.id, handler, context),
+          observeSegmentHandler(entry.shortCode, entry.id, handler, context),
         );
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, routeEntry.id);
@@ -875,7 +886,12 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         entryId: entry.id,
       });
       const actionResult = handleHandlerResult(
-        await observeHandler(entry.id, handler, context),
+        await observeSegmentHandler(
+          entry.shortCode,
+          entry.id,
+          handler,
+          context,
+        ),
       );
       doneHandler();
       return {
@@ -903,7 +919,6 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     transition: applyViewTransitionDefault(
       entry.transition,
       deps.viewTransitionDefault,
-      entry.shortCode,
     ),
     params,
     belongsToRoute,
@@ -1244,7 +1259,6 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     transition: applyViewTransitionDefault(
       orphan.transition,
       deps.viewTransitionDefault,
-      orphan.shortCode,
     ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });

package/src/router/segment-resolution/view-transition-default.ts

@@ -8,7 +8,6 @@
  */
 
 import type { EntryData } from "../../server/context";
-import { getRequestContext } from "../../server/request-context.js";
 
 /**
  * Resolve a segment's transition config: stamp the `viewTransition` default and
@@ -22,34 +21,20 @@ import { getRequestContext } from "../../server/request-context.js";
  * (or "auto") value is left untouched because it already means "wrap" at the
  * gate, which also avoids needless object allocation and payload growth.
  *
- * `when`: a server-only predicate. It is STRIPPED from the returned config (a
- * function cannot cross Flight or the segment cache). PPR routes evaluate it
- * from the manifest before the pipeline; other routes record it here for the
- * existing post-handler gate. Used by both fresh and revalidation resolution.
+ * `when`: a client reference the server never calls. It is STRIPPED here so no
+ * segment record (segment cache, prerender artifact, shell snapshot) carries
+ * it: those stores JSON-serialize the config and would silently drop it on
+ * some stores and keep it on others. rsc/attach-transition-when.ts attaches it
+ * from the route definition right before Flight instead. Used by both fresh
+ * and revalidation resolution.
  */
 export function applyViewTransitionDefault(
   transition: EntryData["transition"],
   viewTransitionDefault: "auto" | false | undefined,
-  segmentId?: string,
 ): EntryData["transition"] {
   if (!transition) return transition;
   let result = transition;
   if (result.when) {
-    if (segmentId !== undefined) {
-      try {
-        const ctx = getRequestContext();
-        if (!ctx._pprTransitionDecisions?.has(segmentId)) {
-          (ctx._transitionWhen ??= []).push({
-            id: segmentId,
-            when: result.when,
-          });
-        }
-      } catch {
-        // No active request context (e.g. a unit test calling this util
-        // directly). Skip collection; the strip below still applies so the
-        // serialized config never carries the function.
-      }
-    }
     const { when: _when, ...rest } = result;
     result = rest;
   }

package/src/router/telemetry.ts

@@ -14,6 +14,8 @@
  *   - revalidation.decision          (revalidation evaluation)
  */
 
+import { requestHeaders } from "../server/request-headers.js";
+
 interface BaseEvent {
   /** Monotonic timestamp from performance.now() */
   timestamp: number;
@@ -294,10 +296,11 @@ export function getRequestId(request: Request): string {
   const existing = requestIds.get(request);
   if (existing) return existing;
 
+  const headers = requestHeaders(request);
   const candidate =
-    request.headers.get("x-rsc-router-request-id") ??
-    request.headers.get("x-request-id") ??
-    request.headers.get("cf-ray");
+    headers.get("x-rsc-router-request-id") ??
+    headers.get("x-request-id") ??
+    headers.get("cf-ray");
 
   let id: string;
   if (candidate) {

package/src/router/transition-when.ts

@@ -1,76 +1,58 @@
 import { getParallelSlotEntries, type EntryData } from "../server/context.js";
 import type { RequestContext } from "../server/request-context.js";
-import type { TransitionWhenContext } from "../types/segments.js";
+import type { TransitionWhenSite } from "../transition-when-ref.js";
+import type { TransitionWhenFn } from "../types/segments.js";
 
-export type TransitionWhenErrorReporter = (
-  error: unknown,
-  segmentId: string,
-) => void;
-
-export function createTransitionWhenContext<TEnv>(
-  ctx: RequestContext<TEnv>,
-  target?: {
-    params: Record<string, string>;
-    routeName?: string;
-  },
-): TransitionWhenContext<Record<string, string>, TEnv> {
-  return {
-    currentUrl: ctx._gateCurrentUrl,
-    currentParams: ctx._gateCurrentParams,
-    fromRouteName: ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
-    nextUrl: ctx.url,
-    nextParams: target?.params ?? ctx.params,
-    toRouteName: (target?.routeName ??
-      ctx.routeName) as TransitionWhenContext["toRouteName"],
-    actionId: ctx._gateActionId,
-    actionUrl: ctx._gateActionUrl,
-    actionResult: ctx._gateActionResult,
-    formData: ctx._gateFormData,
-    method: ctx.request.method,
-    get: ctx.get,
-    env: ctx.env,
-  };
+/** A matched entry's transition({ when }) and where it was declared. */
+export interface TransitionWhenRecord {
+  readonly when: TransitionWhenFn;
+  readonly site: TransitionWhenSite;
 }
 
-/** Evaluate server-only transition gates before handlers on a PPR route. */
-export function evaluatePprTransitionWhen<TEnv>(
-  entries: EntryData[],
+/**
+ * Record the transition({ when }) references of a matched entry chain, keyed
+ * by the segment id each entry resolves to. The server never calls them:
+ * rsc/attach-transition-when.ts attaches them to the payload's segments right
+ * before Flight, and the browser decides (browser/transition-when.ts).
+ *
+ * Recorded from the static route definition on EVERY match (fresh, cache hit,
+ * prerender, PPR replay) because stored segments never carry them:
+ * applyViewTransitionDefault strips `when` at resolution, since segment stores
+ * JSON-serialize the transition config (dropping a function on some stores,
+ * keeping it by reference on others). Segment ids follow resolution: an
+ * entry's shortCode, and `${owner.shortCode}.${slot}` for a rendered parallel
+ * slot.
+ */
+export function recordTransitionWhenRefs<TEnv>(
+  entries: readonly EntryData[] | undefined,
   ctx: RequestContext<TEnv>,
-  target: {
-    params: Record<string, string>;
-    routeName?: string;
-  },
-  reportError: TransitionWhenErrorReporter,
+  route: { routeName?: string; pattern?: string } = {},
 ): void {
-  const decisions = new Map<string, boolean>();
-  const whenContext = createTransitionWhenContext(ctx, target);
+  const refs = new Map<string, TransitionWhenRecord>();
   const visited = new Set<EntryData>();
 
-  const evaluate = (entry: EntryData, segmentId: string): void => {
+  const record = (entry: EntryData, segmentId: string): void => {
     const when = entry.transition?.when;
-    if (!when) return;
-    try {
-      decisions.set(segmentId, when(whenContext) !== false);
-    } catch (error) {
-      decisions.set(segmentId, false);
-      reportError(error, segmentId);
-    }
+    if (when === undefined) return;
+    refs.set(segmentId, {
+      when,
+      site: { ...route, entryType: entry.type },
+    });
   };
 
   const visitEntryAndOrphanLayouts = (entry: EntryData): void => {
     if (visited.has(entry)) return;
     visited.add(entry);
-    evaluate(entry, entry.shortCode);
+    record(entry, entry.shortCode);
 
     for (const orphan of entry.layout) visitEntryAndOrphanLayouts(orphan);
-    // Rendered parallel slots are leaves identified by their owning segment.
     for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
       entry.parallel,
     )) {
-      evaluate(parallelEntry, `${entry.shortCode}.${slot}`);
+      record(parallelEntry, `${entry.shortCode}.${slot}`);
     }
   };
 
-  for (const entry of entries) visitEntryAndOrphanLayouts(entry);
-  ctx._pprTransitionDecisions = decisions.size > 0 ? decisions : undefined;
+  for (const entry of entries ?? []) visitEntryAndOrphanLayouts(entry);
+  ctx._transitionWhenRefs = refs.size > 0 ? refs : undefined;
 }

package/src/router.ts

@@ -1,3 +1,4 @@
+import { requestHeaders } from "./server/request-headers.js";
 import { type ReactNode } from "react";
 import { createCacheScope } from "./cache/cache-scope.js";
 import { resolveCacheProfiles } from "./cache/profile-registry.js";
@@ -1161,7 +1162,7 @@ export function createRouter<TEnv = any>(
         | null = null;
 
       return async (request: Request, input: RouterRequestInput<TEnv> = {}) => {
-        const requestedDiscoveryEpoch = request.headers.get(
+        const requestedDiscoveryEpoch = requestHeaders(request).get(
           DEV_DISCOVERY_PROBE_HEADER,
         );
         if (

package/src/rsc/attach-transition-when.ts

@@ -0,0 +1,47 @@
+import type { MatchResult } from "../types.js";
+import type { getRequestContext } from "../server/request-context.js";
+import {
+  createTransitionWhenError,
+  isTransitionWhenValidationEnabled,
+  transitionWhenProblem,
+} from "../transition-when-ref.js";
+
+/**
+ * Attach transition({ when }) references to a payload's segments, right before
+ * Flight. Returns a copy for every segment it changes: the input segments may
+ * be the records a cache, prerender, or shell snapshot holds.
+ *
+ * Only a segment that carries `transition` gets its predicate. The config
+ * itself never varies per request, so the segment key and the <ViewTransition>
+ * wrapper depend only on the route definition (#995); the browser decides for
+ * every committed segment, kept ones included (#989).
+ *
+ * Render-time backstop for an invalid `when` that route discovery did not see
+ * (a route evaluated lazily at runtime): it throws the discovery error. A
+ * plain function reaching Flight would otherwise fail with React's generic
+ * "Functions cannot be passed directly to Client Components", or be dropped.
+ */
+export function attachTransitionWhen(
+  segments: MatchResult["segments"],
+  ctx: ReturnType<typeof getRequestContext>,
+): MatchResult["segments"] {
+  const refs = ctx?._transitionWhenRefs;
+  if (!refs) return segments;
+  const strict = isTransitionWhenValidationEnabled();
+  let out = segments;
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    const record = segment.transition ? refs.get(segment.id) : undefined;
+    if (!record || segment.transition!.when === record.when) continue;
+    const problem = transitionWhenProblem(record.when, strict);
+    if (problem) {
+      throw createTransitionWhenError(record.when, problem, record.site);
+    }
+    if (out === segments) out = [...segments];
+    out[i] = {
+      ...segment,
+      transition: { ...segment.transition, when: record.when },
+    };
+  }
+  return out;
+}