@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/src/cloudflare/tracing.ts

@@ -0,0 +1,112 @@
+/**
+ * Cloudflare custom-spans integration.
+ *
+ * Bridges the router's observable phases (request, middleware, action, loaders,
+ * handler, render, ssr, response, background) onto Cloudflare Workers custom
+ * spans so they show up in the trace waterfall and OpenTelemetry exports next
+ * to the platform's automatic spans (KV reads, D1 queries, fetch calls), with
+ * correct nesting.
+ *
+ * Usage (Cloudflare preset only):
+ *
+ *   import { createRouter } from "@rangojs/router";
+ *   import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+ *
+ *   export const router = createRouter({
+ *     tracing: createCloudflareTracing(),
+ *   });
+ *
+ * The runner reads `executionContext.tracing` (the same object as
+ * `import { tracing } from "cloudflare:workers"`) at call time. It is therefore
+ * dependency-free: no `cloudflare:workers` import and no hard dependency on
+ * `@cloudflare/workers-types`, matching the convention in cache/cf. When the
+ * worker is not running on a tracing-enabled Cloudflare runtime — Node, dev
+ * without a tracing destination, an older runtime — `executionContext.tracing`
+ * is undefined and every span call falls through to the work directly, so the
+ * request behaves exactly as if tracing were off. Whether spans are actually
+ * recorded is governed by the `observability`/tracing block in wrangler config.
+ *
+ * Span duration note: enterSpan ends a span when its callback's returned value
+ * (or promise) settles. For the streaming phases (request/render/ssr) that is at
+ * stream CONSTRUCTION, not body-drain; rango.response marks that handoff
+ * boundary explicitly (it wraps only response finalization, never the body).
+ * Instrumentation is best-effort and never wraps or buffers the response body,
+ * so it cannot regress streaming or latency. A loader/Suspense child that
+ * resolves mid-stream therefore keeps a rango.loader span that can extend past
+ * its render parent — overlapping spans are valid. Uses only the typed enterSpan
+ * API; spans bound work up to stream-handoff, matching the co-emitted perf
+ * metric. On deployed Workers a rango.response span may report 0 ms (non-I/O
+ * timers are frozen); its position and attributes are the value.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+import {
+  type RouterTracingConfig,
+  type SpanRunner,
+  type TracingToggleOptions,
+  NOOP_TRACE_SPAN,
+} from "../router/tracing.js";
+
+/**
+ * Minimal local view of Cloudflare's `Span`. Declared here (not imported from
+ * `@cloudflare/workers-types`) to avoid a hard type dependency.
+ */
+interface CloudflareSpan {
+  readonly isTraced: boolean;
+  setAttribute(key: string, value?: boolean | number | string): void;
+}
+
+/** Minimal local view of Cloudflare's `Tracing` (only enterSpan is used). */
+interface CloudflareTracing {
+  enterSpan<T>(name: string, callback: (span: CloudflareSpan) => T): T;
+}
+
+/**
+ * Options for createCloudflareTracing. Alias of the shared
+ * {@link TracingToggleOptions} (`enabled` master switch + per-phase `spans`
+ * toggles); the name is public API.
+ */
+export type CloudflareTracingOptions = TracingToggleOptions;
+
+/**
+ * Resolve the per-request Cloudflare tracer from the active execution context.
+ * Returns undefined off-Cloudflare or when tracing is not enabled for the
+ * worker, in which case the caller runs the work without a span.
+ */
+function getRequestTracer(): CloudflareTracing | undefined {
+  const executionContext = _getRequestContext()?.executionContext as
+    | { tracing?: CloudflareTracing }
+    | undefined;
+  const tracing = executionContext?.tracing;
+  return tracing && typeof tracing.enterSpan === "function"
+    ? tracing
+    : undefined;
+}
+
+const cloudflareSpanRunner: SpanRunner = (name, fn) => {
+  const tracer = getRequestTracer();
+  if (!tracer) return fn(NOOP_TRACE_SPAN);
+  // enterSpan runs the callback now and ends the span when its return value
+  // (or returned promise) settles; spans nest by JS async context. fn's param
+  // is the narrower TraceSpan, so the wider CloudflareSpan satisfies it directly.
+  return tracer.enterSpan(name, fn);
+};
+
+/**
+ * Create the tracing config for a Cloudflare router. Pass the result to
+ * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
+ * action, loaders, handler, render, ssr, response, and background phases; pass
+ * `spans` to turn individual phases off.
+ *
+ * @see createOTelTracing (`@rangojs/router`) for the same slot on any platform
+ *   with an OpenTelemetry SDK.
+ */
+export function createCloudflareTracing(
+  options: CloudflareTracingOptions = {},
+): RouterTracingConfig {
+  return {
+    runner: cloudflareSpanRunner,
+    enabled: options.enabled ?? true,
+    spans: options.spans,
+  };
+}

package/src/component-utils.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ComponentType } from "react";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 /**
  * Symbol used by React to mark client component references.
@@ -48,11 +49,21 @@ export function isClientComponent(
  *
  * @param component - The component to check
  * @param name - Name to use in error message (e.g., "document")
+ * @param opts.allowServerInTest - When true AND running under a test runner
+ *   (`isUnderTestRunner()`), relax ONLY the "use client" requirement: a server
+ *   component is accepted. The plugin's "use client" transform does not run in a
+ *   bare unit test, so a real exported `document` (almost every app sets one) has
+ *   no client marker and would otherwise throw at `createRouter`, blocking
+ *   `dispatch`/`assertGeneratedRoutesMatch` against the real router. The document
+ *   reference is irrelevant to those (no Flight render). The "not a JSX element"
+ *   guard still fires, and a real dev/build still throws (mirrors the runtime
+ *   fallback-id gating in handle.ts/loader.ts).
  * @throws Error if the component is not a client component
  */
 export function assertClientComponent(
   component: ComponentType<unknown> | unknown,
   name: string,
+  opts?: { allowServerInTest?: boolean },
 ): asserts component is ComponentType<unknown> {
   if (typeof component !== "function") {
     throw new Error(
@@ -62,6 +73,14 @@ export function assertClientComponent(
     );
   }
 
+  // Under a test runner the "use client" transform did not run, so a real
+  // server-rendered `document` has no client marker; accept it (the reference is
+  // never serialized in dispatch/route-map checks). Outside a test runner this
+  // still throws — the build-time safety net is preserved.
+  if (opts?.allowServerInTest && isUnderTestRunner()) {
+    return;
+  }
+
   if (!isClientComponent(component)) {
     throw new Error(
       `${name} must be a client component with "use client" directive at the top of the file. ` +

package/src/components/DefaultDocument.tsx

@@ -2,11 +2,13 @@
 
 import type { ReactNode, ReactElement } from "react";
 import { MetaTags } from "../handles/MetaTags.js";
+import { Scripts } from "../handles/Scripts.js";
 
 /**
  * Default document component that provides a basic HTML structure.
  * Used when no custom document is provided to createRouter.
- * Includes MetaTags for automatic charset, viewport, and route meta support.
+ * Includes MetaTags for automatic charset, viewport, and route meta support,
+ * and Scripts (head + body sites) so the Script handle works out of the box.
  *
  * Uses suppressHydrationWarning on <html> because the theme script
  * may modify class/style attributes before React hydrates.
@@ -20,8 +22,12 @@ export function DefaultDocument({
     <html lang="en" suppressHydrationWarning>
       <head>
         <MetaTags />
+        <Scripts />
       </head>
-      <body>{children}</body>
+      <body>
+        <Scripts position="body" />
+        {children}
+      </body>
     </html>
   );
 }

package/src/context-var.ts

@@ -12,6 +12,9 @@
  * interface PaginationData { current: number; total: number }
  * export const Pagination = createVar<PaginationData>();
  *
+ * // Non-cacheable var — ctx.get(User) throws inside a cache() boundary
+ * export const User = createVar<UserData>({ cache: false });
+ *
  * // handler
  * ctx.set(Pagination, { current: 1, total: 4 });
  *
@@ -23,18 +26,36 @@
 export interface ContextVar<T> {
   readonly __brand: "context-var";
   readonly key: symbol;
+  /** When false, ctx.get(var) throws inside a cache() boundary. */
+  readonly cache: boolean;
   /** Phantom field to carry the type parameter. Never set at runtime. */
   readonly __type?: T;
 }
 
+export interface ContextVarOptions {
+  /**
+   * When false, marks this variable as non-cacheable.
+   * Reading this var with ctx.get() inside a cache() boundary throws. Use for
+   * inherently request-specific data (user sessions, auth tokens, etc.) that
+   * must never be baked into cached segments.
+   *
+   * @default true
+   */
+  cache?: boolean;
+}
+
 /**
  * Create a typed context variable token.
  *
  * The returned object is used with ctx.set(token, value) and ctx.get(token)
  * for compile-time-checked data flow between handlers, layouts, and middleware.
  */
-export function createVar<T>(): ContextVar<T> {
-  return { __brand: "context-var" as const, key: Symbol() };
+export function createVar<T>(options?: ContextVarOptions): ContextVar<T> {
+  return {
+    __brand: "context-var" as const,
+    key: Symbol(),
+    cache: options?.cache !== false,
+  };
 }
 
 /**
@@ -49,6 +70,48 @@ export function isContextVar(value: unknown): value is ContextVar<unknown> {
   );
 }
 
+/**
+ * Does a variables object hold any entries? Counts both string keys and the
+ * symbol-keyed entries (context vars are stored under symbols), so an object
+ * carrying only symbol-keyed vars is still reported as non-empty.
+ */
+export function hasContextVars(variables: object): boolean {
+  return (
+    Object.keys(variables).length > 0 ||
+    Object.getOwnPropertySymbols(variables).length > 0
+  );
+}
+
+/**
+ * Symbol used as a Set stored on the variables object to track
+ * which keys hold non-cacheable values (from write-level { cache: false }).
+ */
+const NON_CACHEABLE_KEYS: unique symbol = Symbol.for(
+  "rango:non-cacheable-keys",
+);
+
+function getNonCacheableKeys(variables: any): Set<string | symbol> {
+  if (!variables[NON_CACHEABLE_KEYS]) {
+    variables[NON_CACHEABLE_KEYS] = new Set();
+  }
+  return variables[NON_CACHEABLE_KEYS];
+}
+
+/**
+ * Check if a variable value is non-cacheable (either var-level or write-level).
+ */
+export function isNonCacheable(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+): boolean {
+  if (typeof keyOrVar !== "string" && !keyOrVar.cache) {
+    return true; // var-level policy
+  }
+  const key = typeof keyOrVar === "string" ? keyOrVar : keyOrVar.key;
+  const set = variables[NON_CACHEABLE_KEYS] as Set<string | symbol> | undefined;
+  return set?.has(key) ?? false; // write-level policy
+}
+
 /**
  * Read a variable from the variables store.
  * Accepts either a string key (legacy) or a ContextVar token (typed).
@@ -64,6 +127,17 @@ export function contextGet(
 /** Keys that must never be used as string variable names */
 const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
+export interface ContextSetOptions {
+  /**
+   * When false, marks this specific write as non-cacheable.
+   * "Least cacheable wins" — if either the var definition or this option
+   * says cache: false, the value is non-cacheable.
+   *
+   * @default true (inherits from createVar)
+   */
+  cache?: boolean;
+}
+
 /**
  * Write a variable to the variables store.
  * Accepts either a string key (legacy) or a ContextVar token (typed).
@@ -72,6 +146,7 @@ export function contextSet(
   variables: any,
   keyOrVar: string | ContextVar<any>,
   value: any,
+  options?: ContextSetOptions,
 ): void {
   if (typeof keyOrVar === "string") {
     if (FORBIDDEN_KEYS.has(keyOrVar)) {
@@ -80,7 +155,14 @@ export function contextSet(
       );
     }
     variables[keyOrVar] = value;
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar);
+    }
   } else {
     variables[keyOrVar.key] = value;
+    // Track write-level non-cacheable (var-level is checked via keyOrVar.cache)
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar.key);
+    }
   }
 }

package/src/debug.ts

@@ -2,7 +2,7 @@
  * Debug utilities for manifest inspection and comparison
  */
 
-import type { EntryData } from "./server/context";
+import { getParallelSlotCount, type EntryData } from "./server/context";
 
 /**
  * Serialized entry for debug output
@@ -64,7 +64,7 @@ export function serializeManifest(
       hasLoader: entry.loader?.length > 0,
       hasMiddleware: entry.middleware?.length > 0,
       hasErrorBoundary: entry.errorBoundary?.length > 0,
-      parallelCount: entry.parallel?.length ?? 0,
+      parallelCount: getParallelSlotCount(entry.parallel),
       interceptCount: entry.intercept?.length ?? 0,
     };
 

package/src/decode-loader-results.ts

@@ -0,0 +1,160 @@
+import type { ReactNode } from "react";
+import { createElement } from "react";
+import { isLoaderDataResult } from "./types.js";
+import { LoaderRedirect } from "./loader-redirect.js";
+
+/**
+ * Markers for loader-thrown AUTHORITY SIGNALS (notFound()/redirect()) on the
+ * reconstructed read-site error. Siblings of LOADER_ERROR_FALLBACK, routed
+ * differently by StreamedLoaderErrorBoundary: NOT_FOUND renders the
+ * server-rendered not-found UI riding the envelope; REDIRECT triggers a
+ * client replace-navigation to the (server-resolved, same-origin-guarded)
+ * target. Signals are control flow, not failures — they take precedence over
+ * the plain error-fallback path.
+ *
+ * Only decodeLoaderEntry (the read-site path — client components, so the
+ * throw lands in the router-owned boundary; during document SSR, Fizz emits
+ * the Suspense fallback and replays the throw at hydration) throws these.
+ * decodeLoaderResults runs during the SERVER tree build on forceAwait/action
+ * lanes, where a throw would collapse the whole payload — it routes signals
+ * through the errorFallback slot instead (same visual: the slot replaces the
+ * children under OutletProvider).
+ */
+export const LOADER_NOT_FOUND_FALLBACK: unique symbol = Symbol(
+  "rango.loaderNotFound",
+);
+export const LOADER_REDIRECT: unique symbol = Symbol("rango.loaderRedirect");
+
+function throwSignal(result: any): void {
+  if (result.notFound === true) {
+    const err = new Error(result.error?.message ?? "Not found");
+    err.name = result.error?.name ?? "DataNotFoundError";
+    (err as any)[LOADER_NOT_FOUND_FALLBACK] = result.fallback ?? null;
+    throw err;
+  }
+  if (result.redirect) {
+    const err = new Error(result.error?.message ?? "Loader redirect");
+    err.name = "LoaderRedirect";
+    (err as any)[LOADER_REDIRECT] = result.redirect;
+    throw err;
+  }
+}
+
+/**
+ * Non-throwing signal resolution for the aggregate path. Returns the node to
+ * place in the errorFallback slot, or undefined when the result carries no
+ * signal.
+ */
+function signalFallback(result: any): ReactNode | undefined {
+  if (result.notFound === true) {
+    return (result.fallback ?? null) as ReactNode;
+  }
+  if (result.redirect) {
+    return createElement(LoaderRedirect, {
+      to: (result.redirect as { to: string }).to,
+    });
+  }
+  return undefined;
+}
+
+// Shared by segment-system (server) and LoaderResolver (client) so the
+// legacy/ok/error-fallback/throw decode of resolved loader values lives once.
+// Last failing loader wins errorFallback; an error without a fallback throws.
+export function decodeLoaderResults(
+  resolvedData: any[],
+  loaderIds: string[],
+): { loaderData: Record<string, any>; errorFallback: ReactNode } {
+  const loaderData: Record<string, any> = {};
+  let errorFallback: ReactNode = null;
+
+  for (let i = 0; i < loaderIds.length; i++) {
+    const id = loaderIds[i];
+    const result = resolvedData[i];
+
+    if (!isLoaderDataResult(result)) {
+      loaderData[id] = result;
+      continue;
+    }
+
+    if (result.ok) {
+      loaderData[id] = result.data;
+      continue;
+    }
+
+    // Authority signals take the errorFallback slot (this decode runs during
+    // the server tree build on forceAwait/action lanes — throwing here would
+    // collapse the payload). A signal outranks a plain error fallback and
+    // stops the scan: notFound renders the server-rendered 404 UI, redirect
+    // mounts LoaderRedirect which navigates.
+    const signal = signalFallback(result);
+    if (signal !== undefined) {
+      return { loaderData, errorFallback: signal };
+    }
+
+    // null/undefined is the producer's ONLY "no boundary found" sentinel
+    // (loader-resolution.ts sets fallback: null for the no-boundary and the
+    // fallback-render-threw cases). A matched boundary's rendered ReactNode can
+    // legitimately be falsy (0, "", false), so test for null explicitly rather
+    // than truthiness, otherwise a valid falsy fallback is discarded and the
+    // original loader error is rethrown.
+    if (result.fallback != null) {
+      errorFallback = result.fallback;
+    } else {
+      // No boundary: rethrow preserving the ErrorInfo identity (name/stack/
+      // code/cause) instead of a stripped generic Error.
+      const info = result.error;
+      const err = new Error(
+        info.message,
+        info.cause !== undefined ? { cause: info.cause } : undefined,
+      );
+      if (info.name) err.name = info.name;
+      if (info.stack) err.stack = info.stack;
+      if (info.code !== undefined) (err as { code?: string }).code = info.code;
+      throw err;
+    }
+  }
+
+  return { loaderData, errorFallback };
+}
+
+/**
+ * Marker property carrying the errorBoundary() fallback on a read-site loader
+ * error. decodeLoaderEntry attaches the pre-rendered boundary node (produced
+ * server-side by loader-resolution) to the thrown error; the router-owned
+ * StreamedLoaderErrorBoundary above the readers (segment-system wires it for
+ * every loader-bearing segment) catches by this marker and renders the
+ * fallback — restoring the build-time errorFallback-swap contract for
+ * streamed loaders. Errors without the marker rethrow to the app's boundaries.
+ */
+export const LOADER_ERROR_FALLBACK: unique symbol = Symbol(
+  "rango.loaderErrorFallback",
+);
+
+/**
+ * Streaming useLoader: single-entry decode for read-site resolution. Mirrors
+ * decodeLoaderResults for one result. An error entry throws the reconstructed
+ * error (name/stack/code/cause preserved); when the entry carries an
+ * errorBoundary() fallback, the node rides the throw via
+ * LOADER_ERROR_FALLBACK for the boundary above the readers to render.
+ */
+export function decodeLoaderEntry(result: any): any {
+  if (!isLoaderDataResult(result)) {
+    return result;
+  }
+  if (result.ok) {
+    return result.data;
+  }
+  throwSignal(result);
+  const info = result.error;
+  const err = new Error(
+    info.message,
+    info.cause !== undefined ? { cause: info.cause } : undefined,
+  );
+  if (info.name) err.name = info.name;
+  if (info.stack) err.stack = info.stack;
+  if (info.code !== undefined) (err as { code?: string }).code = info.code;
+  if (result.fallback != null) {
+    (err as any)[LOADER_ERROR_FALLBACK] = result.fallback;
+  }
+  throw err;
+}

package/src/defer.ts

@@ -0,0 +1,185 @@
+/**
+ * Deferred handle values — "decide synchronously, resolve late".
+ *
+ * A handle is pushed from code that holds `ctx` (a route/layout handler), so the
+ * decision to push lands before the handles stream seals. But the value often
+ * isn't known there — it may come from a deep async component far from the
+ * handler. `ctx.use(Handle).defer()` reserves the handle's slot now (synchronous,
+ * so ordering and the pre-seal timing hold) and returns a resolver with the SAME
+ * signature as the push: you call it later, anywhere in the render, with the same
+ * value you would have passed to the push.
+ *
+ *   const breadcrumb = ctx.use(Breadcrumbs);   // (item) => void  &  .defer()
+ *   const resolve = breadcrumb.defer({ timeoutMs: 5000, else: null });
+ *   // deep async component, far from ctx:
+ *   resolve({ label, href, content });          // identical call, just deferred
+ *
+ * Under the hood the reserved slot is a Promise. Handle values are resolved
+ * before any consumer sees them (resolve-by-default: the full render resolves
+ * server-side, navigation resolves client-side before apply), so `useHandle`
+ * receives the resolved value, never the Promise. The hazard that guards against
+ * bugs: a deferred slot whose resolver is never called would keep the render —
+ * and the HTTP response — waiting forever. So a deferred auto-resolves to `else`
+ * after `timeoutMs` (default {@link DEFAULT_DEFER_TIMEOUT_MS}) if the resolver is
+ * never called, degrading gracefully (and warning in dev) instead of hanging.
+ */
+
+/** Default auto-resolve window. Long enough for genuine deep async work, short
+ *  enough that a forgotten resolve does not hang the response indefinitely. */
+export const DEFAULT_DEFER_TIMEOUT_MS = 10_000;
+
+/** Options for `ctx.use(Handle).defer()`. */
+export interface DeferOptions<TData> {
+  /**
+   * Auto-resolve to `else` after this many ms if the resolver is never called,
+   * so a forgotten resolve cannot hold the Flight stream — and thus the HTTP
+   * response — open. Defaults to {@link DEFAULT_DEFER_TIMEOUT_MS}. `0` or
+   * `Infinity` disable the timeout intentionally (not recommended on a request
+   * path). Any other non-finite or negative value is treated as a mistake and
+   * falls back to the default rather than silently disabling the safety net.
+   * Named `timeoutMs` to match the router's `*Ms` duration convention.
+   */
+  timeoutMs?: number;
+  /**
+   * Value the slot resolves to if the timeout fires before the resolver is
+   * called. Defaults to `undefined` (the deferred item is skipped/empty). For
+   * renderable handle content, `null` is the usual graceful fallback, so the
+   * type admits `null` even when `TData` does not.
+   */
+  else?: TData | null;
+}
+
+/**
+ * The call signature shared by a handle push and the resolver returned by
+ * `.defer()`: a concrete value, a `Promise` of the value (Flight streams it as a
+ * late row), or a thunk returning a `Promise` (called immediately).
+ */
+export type HandlePushFn<TData> = (
+  data: TData | Promise<TData> | (() => Promise<TData>),
+) => void;
+
+/**
+ * The push function returned by `ctx.use(Handle)`. Call it to push a value now,
+ * or call `.defer()` to reserve the slot now and resolve the value later (e.g.
+ * from a deep async component) with a timeout safety net.
+ */
+export type HandlePush<TData> = HandlePushFn<TData> & {
+  /**
+   * Reserve this handle's slot synchronously and return a resolver that is
+   * push-equal: it takes the same argument shapes as the push (value, Promise, or
+   * thunk) and behaves identically. Two things the resolver adds over a direct
+   * push: a timeout (if the resolver is never called, the slot auto-resolves to
+   * `options.else` after `options.timeoutMs`; calling the resolver cancels it),
+   * and — on the action/revalidation path only — a thunk it runs does NOT
+   * re-enter the deadlock-guard push-callback scope a direct push thunk gets,
+   * because a deferred resolver fires after the handler phase has closed.
+   *
+   * The reserved slot is resolved before any consumer reads it
+   * (resolve-by-default), so `useHandle` receives the resolved value (or the
+   * `else` fallback on timeout), never a Promise.
+   */
+  defer(options?: DeferOptions<TData>): HandlePushFn<TData>;
+};
+
+// Internal: a timeout-bounded { promise, resolve }. Not part of the public API
+// (the public surface is `ctx.use(Handle).defer()`); exported for `withDefer`
+// and unit tests only. Resolves to `T`, the `else` fallback, or `undefined`.
+export function createDeferred<T>(options?: {
+  timeoutMs?: number;
+  fallback?: T | null;
+}): {
+  promise: Promise<T | null | undefined>;
+  resolve: (value: T | null | undefined) => void;
+} {
+  let resolveInner!: (value: T | null | undefined) => void;
+  let settled = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const promise = new Promise<T | null | undefined>((resolve) => {
+    resolveInner = resolve;
+  });
+
+  const finish = (value: T | null | undefined): void => {
+    if (settled) return;
+    settled = true;
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    resolveInner(value);
+  };
+
+  // 0 and Infinity are documented intentional disables. Any other non-finite or
+  // negative value (NaN, -1, a bad parsed config/env) is a mistake — fall back to
+  // the default rather than SILENTLY disabling the safety net, which would let a
+  // forgotten resolve hang the Flight stream and the response forever.
+  const requested = options?.timeoutMs ?? DEFAULT_DEFER_TIMEOUT_MS;
+  let ms: number;
+  if (requested === 0 || requested === Infinity) {
+    ms = requested;
+  } else if (Number.isFinite(requested) && requested > 0) {
+    ms = requested;
+  } else {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        `[rango] defer(): invalid timeout ${String(requested)}; using the ` +
+          `${DEFAULT_DEFER_TIMEOUT_MS}ms default so the safety net stays on. ` +
+          `Use 0 or Infinity to disable the timeout intentionally.`,
+      );
+    }
+    ms = DEFAULT_DEFER_TIMEOUT_MS;
+  }
+
+  if (ms > 0 && ms !== Infinity) {
+    timer = setTimeout(() => {
+      if (process.env.NODE_ENV !== "production") {
+        console.warn(
+          `[rango] A deferred handle value was not resolved within ${ms}ms; ` +
+            `resolving to the fallback so the response can flush. Call the ` +
+            `resolver from the component that produces the value, or raise timeoutMs.`,
+        );
+      }
+      finish(options?.fallback);
+    }, ms);
+    // Don't let a pending timer alone keep a Node process alive (no-op on workerd).
+    (timer as { unref?: () => void }).unref?.();
+  }
+
+  return { promise, resolve: finish };
+}
+
+/**
+ * Attach `.defer()` to a handle push function. The deferred slot is reserved by
+ * pushing the deferred promise through the same push (so ordering, sealing, and
+ * Flight streaming all reuse the existing path); the returned resolver settles it.
+ */
+export function withDefer<TData>(push: HandlePushFn<TData>): HandlePush<TData> {
+  const handlePush = push as HandlePush<TData>;
+  // Safe to mutate push in place: each ctx.use(Handle) call (request-context.ts,
+  // loader-resolution.ts) builds a fresh closure, so .defer never leaks across
+  // handles or requests.
+  handlePush.defer = (options) => {
+    const deferred = createDeferred<TData>({
+      timeoutMs: options?.timeoutMs,
+      fallback: options?.else,
+    });
+    // Reserve the slot now by pushing the pending promise (the renderer use()s it).
+    push(deferred.promise as Promise<TData>);
+    // The resolver is push-equal: a thunk is invoked immediately (as push does)
+    // and a Promise is adopted by the reserved slot. Calling it settles the slot
+    // and cancels the timeout — the timeout only fires if it is never called.
+    const resolveSlot = deferred.resolve as (
+      value: TData | Promise<TData>,
+    ) => void;
+    return (data) => {
+      // The thunk runs without re-entering the push-callback scope a direct push
+      // thunk gets on the action/revalidation path (loader-resolution.ts): a
+      // deferred resolver fires from a deep component after the handler phase has
+      // closed, so there is no live deadlock-guard window to exempt.
+      resolveSlot(
+        typeof data === "function" ? (data as () => Promise<TData>)() : data,
+      );
+    };
+  };
+  return handlePush;
+}