@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

package/src/defer.ts

@@ -0,0 +1,196 @@
+/**
+ * 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 the renderer `use()`s; RSC Flight
+ * streams it as a late row, so a deferred-aware consumer reading the handle
+ * (`useHandle`) sees that entry as a `Promise` until it resolves (see
+ * {@link DeferredHandleEntry}). The hazard that guards against bugs: a deferred
+ * slot whose resolver is never called would keep the Flight stream — and the HTTP
+ * response — open 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 the request.
+ */
+
+/** 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 appears in the accumulated handle data as a pending
+   * `Promise` until it resolves (see {@link DeferredHandleEntry}); a
+   * deferred-aware consumer narrows thenable entries (`use()`/`await` + null
+   * check) before dereferencing.
+   */
+  defer(options?: DeferOptions<TData>): HandlePushFn<TData>;
+};
+
+/**
+ * A handle entry a deferred-aware consumer may read from `useHandle`: either a
+ * resolved value, or a pending `Promise` that resolves to the value, to `else`,
+ * or (when no `else` was given) `undefined` on timeout. Reading code should treat
+ * thenable entries as such and narrow before dereferencing.
+ */
+export type DeferredHandleEntry<TData> =
+  | TData
+  | Promise<TData | null | undefined>;
+
+// 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;
+}

package/src/deps/ssr.ts

@@ -1,2 +1 @@
-// Re-export @vitejs/plugin-rsc/ssr for internal use by virtual entries
 export { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";

package/src/encode-kv.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared key=value serialization core.
+ *
+ * One encode+join rule shared by every deterministic query-string serializer
+ * in the codebase (cache keys, route-param strings, search-param strings,
+ * prerender param hashes). Each call site differs only in how it pre-filters
+ * and orders the pairs it hands in, plus whether it sorts; the encoding itself
+ * (`encodeURIComponent(k)=encodeURIComponent(v)` joined by `&`) is identical.
+ *
+ * Dependency-free leaf module so any layer (build-time prerender hashing,
+ * runtime cache keys, client search-param serialization) can import it without
+ * pulling in cache/router internals.
+ */
+
+export interface EncodeKVOptions {
+  /**
+   * Sort pairs by key in codepoint (byte) order before joining. Byte order via
+   * the `<` operator, NOT localeCompare, so the result is identical across
+   * Node, Workers, and browsers regardless of runtime locale.
+   *
+   * Defaults to false (insertion order preserved).
+   */
+  sort?: boolean;
+}
+
+/**
+ * Serialize an array of [key, value] pairs to a deterministic query string
+ * (no leading `?`). Both key and value are passed through encodeURIComponent
+ * so a key/value containing `&` or `=` cannot collide with a structurally
+ * different pair set.
+ *
+ * Callers are responsible for any filtering (e.g. dropping reserved params) and
+ * any value coercion (e.g. String(v), skipping null/undefined) BEFORE calling.
+ * This function never inspects or skips values; it encodes exactly what it is
+ * given so each call site keeps its own existing output.
+ */
+export function encodeKV(
+  pairs: Iterable<readonly [string, string]>,
+  options: EncodeKVOptions = {},
+): string {
+  const list = [...pairs];
+  if (list.length === 0) return "";
+  if (options.sort) {
+    list.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  }
+  return list
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+}

package/src/errors.ts

@@ -225,7 +225,6 @@ export function isNetworkError(error: unknown): boolean {
 export class RouterError extends Error {
   name = "RouterError" as const;
   code: string;
-  type?: string;
   status: number;
   cause?: unknown;
 
@@ -234,7 +233,6 @@ export class RouterError extends Error {
     message: string,
     options?: {
       status?: number;
-      type?: string;
       cause?: unknown;
     },
   ) {
@@ -242,7 +240,6 @@ export class RouterError extends Error {
     Object.setPrototypeOf(this, RouterError.prototype);
     this.code = code;
     this.status = options?.status ?? 500;
-    this.type = options?.type;
     this.cause = options?.cause;
   }
 }

package/src/escape-script.ts

@@ -0,0 +1,52 @@
+/**
+ * Escape a JSON (or JSON-derived) string for safe embedding inside an HTML
+ * <script> element via dangerouslySetInnerHTML. Without this a value containing
+ * "</script>" closes the tag early — the rest of the page leaks as raw HTML, and
+ * in an executable script the trailing content runs. Escaping "<" defeats the
+ * early close; ">" and "&" are escaped for completeness so the serialized payload
+ * can never form HTML syntax. The result is still valid JSON and a valid JS
+ * string literal (\uXXXX escapes are legal in both) and re-parses identically.
+ *
+ * Used by every site that interpolates JSON.stringify(...) into inline <script>
+ * content: the JSON-LD meta descriptors (handles/MetaTags) and the FOUC theme
+ * init script (theme/theme-script).
+ */
+export function escapeJsonForScript(json: string): string {
+  return json
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026");
+}
+
+/**
+ * Escape an inline <script> body so it cannot terminate or corrupt the document.
+ * Two sequences are rewritten, each via a JS escape that is valid in string,
+ * template, regex (including the `u`/`v` flags), and JSON contexts — so the body
+ * still parses identically as code AND as JSON (application/json, ld+json):
+ * - "</script" -> "<\/script": stops a literal close tag inside the body from
+ *   ending the element early. `\/` is a valid JSON escape and a valid regex escape.
+ * - "<!--": the "!" (U+0021) is emitted as a unicode escape (see the replacement
+ *   string below), so the literal "<!--" token never reaches the HTML parser. A
+ *   literal "<!--" puts the parser into the "script data escaped" state and a
+ *   following "<script" into "script data DOUBLE escaped", where the real
+ *   "</script>" no longer closes the element — `var x = "<!--<script>"` would
+ *   swallow the rest of the document. The unicode-escape form decodes back to "!"
+ *   in string/template/JSON/regex contexts, unlike "\!" (invalid JSON, invalid
+ *   /u-regex escape).
+ * Real operators such as `a < b` and `a && b` are untouched (unlike
+ * escapeJsonForScript, which \u-escapes every "<", "&", ">").
+ *
+ * GUARANTEE / LIMITATION: value-preserving for the contexts where these sequences
+ * legitimately appear — string/template literals, regexes (incl. `u`/`v`), and
+ * JSON. It is NOT source-text-preserving (e.g. String.raw`</script>` sees the
+ * extra backslash), and it cannot rewrite "</script"/"<!--" that appear as bare
+ * code (a legacy `<!--` line comment, or `</script` outside any literal) — neither
+ * occurs in valid script payloads. Not a general sanitizer for arbitrary UNTRUSTED
+ * source; for untrusted dynamic data, JSON-encode it and read it back, rather than
+ * inlining it as code.
+ *
+ * Used by the Script handle's <Scripts> renderer for inline `children`.
+ */
+export function escapeScriptBody(js: string): string {
+  return js.replace(/<!--/g, "<\\u0021--").replace(/<\/(script)/gi, "<\\/$1");
+}

package/src/handle.ts

@@ -1,4 +1,5 @@
 import { missingInjectedIdError } from "./missing-id-error.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 /**
  * Handle definition for accumulating data across route segments.
@@ -45,10 +46,10 @@ function defaultCollect<T>(segments: T[][]): T[] {
 // Used by useHandle() to recover collect when handle is deserialized from RSC prop.
 const collectRegistry = new Map<string, (segments: unknown[][]) => unknown>();
 
-/**
- * Look up a collect function from the registry by handle $$id.
- * Returns undefined if not registered (falls back to defaultCollect in useHandle).
- */
+// Monotonic counter for runtime fallback ids (see createHandle). Only used
+// when no build id was injected (a bare unit test).
+let runtimeHandleIdCounter = 0;
+
 export function getCollectFn(
   id: string,
 ): ((segments: unknown[][]) => unknown) | undefined {
@@ -95,24 +96,36 @@ export function createHandle<TData, TAccumulated = TData[]>(
   collect?: (segments: TData[][]) => TAccumulated,
   __injectedId?: string,
 ): Handle<TData, TAccumulated> {
-  const handleId = __injectedId ?? "";
+  let handleId = __injectedId ?? "";
 
-  if (!handleId && process.env.NODE_ENV === "development") {
-    throw missingInjectedIdError("Handle", "createHandle");
+  // No build-injected id. Under a test runner: fall back to a synthetic id so the
+  // collect registers below and the handle is exercisable in tests (useHandle,
+  // collectHandle, renderRoute's `handles` run the REAL collect). Otherwise (dev
+  // or a real build) it means an UNSUPPORTED handler shape the plugin skipped —
+  // fail loud. The rich, stack-parsing diagnostic stays behind the NODE_ENV check
+  // so a production build folds it away and tree-shakes missing-id-error.ts out,
+  // shipping the small throw instead. isUnderTestRunner() is runtime-safe.
+  if (!handleId) {
+    if (isUnderTestRunner()) {
+      handleId = `__rango_runtime_handle_${runtimeHandleIdCounter++}`;
+    } else if (process.env.NODE_ENV !== "production") {
+      throw missingInjectedIdError("Handle", "createHandle");
+    } else {
+      throw new Error(
+        "[rango] Handle is missing $$id — the build plugin did not inject one. " +
+          "Export it as `export const X = createHandle(...)`.",
+      );
+    }
   }
 
   const collectFn =
     collect ??
     (defaultCollect as unknown as (segments: TData[][]) => TAccumulated);
 
-  // Register collect in module-level registry so useHandle() can recover it
-  // when the handle is deserialized from RSC props (toJSON strips collect).
-  if (handleId) {
-    collectRegistry.set(
-      handleId,
-      collectFn as (segments: unknown[][]) => unknown,
-    );
-  }
+  collectRegistry.set(
+    handleId,
+    collectFn as (segments: unknown[][]) => unknown,
+  );
 
   return {
     __brand: "handle" as const,
@@ -120,9 +133,6 @@ export function createHandle<TData, TAccumulated = TData[]>(
   };
 }
 
-/**
- * Type guard to check if a value is a Handle.
- */
 export function isHandle(value: unknown): value is Handle<unknown, unknown> {
   return (
     typeof value === "object" &&

package/src/handles/MetaTags.tsx

@@ -8,6 +8,10 @@
  *
  * When theme is enabled in the router config, MetaTags also renders
  * the theme initialization script to prevent FOUC (flash of unstyled content).
+ * This makes MetaTags the sole FOUC-script injector for apps that render it;
+ * the standalone `<ThemeScript />` is only needed when MetaTags is not used.
+ * Rendering both is safe (the inline script guards listener registration) but
+ * redundant.
  *
  * @example
  * ```tsx
@@ -27,10 +31,12 @@
 import { use } from "react";
 import { useHandle } from "../browser/react/use-handle.js";
 import { Meta } from "./meta.js";
+import { isThenable } from "./is-thenable.js";
 import type { MetaDescriptor, MetaDescriptorBase } from "../router/types.js";
 import { useThemeContext } from "../theme/theme-context.js";
 import { generateThemeScript } from "../theme/theme-script.js";
 import { useNonce } from "../browser/react/nonce-context.js";
+import { escapeJsonForScript } from "../escape-script.js";
 
 // Type guards for MetaDescriptorBase variants
 function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
@@ -91,30 +97,27 @@ function hasTagName(
 }
 
 /**
- * Check if a value is a Promise.
+ * Check if a value is a Promise. Uses the shared thenable predicate (callable
+ * `then`) so collect (meta.ts) and render never disagree: an object carrying a
+ * non-callable `then` (e.g. `{ then: 5 }`) is a SYNC descriptor on both sides,
+ * not a Promise that would crash React's `use()`.
  */
 function isPromise(value: unknown): value is Promise<unknown> {
-  return value !== null && typeof value === "object" && "then" in value;
+  return isThenable(value);
 }
 
-/**
- * Render a single meta descriptor as a React element.
- */
 function renderMetaDescriptor(
   descriptor: MetaDescriptorBase,
   index: number,
 ): React.ReactNode {
-  // charset
   if (hasCharSet(descriptor)) {
     return <meta key="charSet" charSet={descriptor.charSet} />;
   }
 
-  // title
   if (hasTitle(descriptor)) {
     return <title key="title">{descriptor.title}</title>;
   }
 
-  // name + content (description, viewport, etc.)
   if (hasNameContent(descriptor)) {
     return (
       <meta
@@ -125,7 +128,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // property + content (Open Graph, etc.)
   if (hasPropertyContent(descriptor)) {
     return (
       <meta
@@ -136,7 +138,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // http-equiv + content
   if (hasHttpEquivContent(descriptor)) {
     return (
       <meta
@@ -147,9 +148,10 @@ function renderMetaDescriptor(
     );
   }
 
-  // JSON-LD structured data
   if (hasScriptLdJson(descriptor)) {
-    const json = JSON.stringify(descriptor["script:ld+json"]);
+    const json = escapeJsonForScript(
+      JSON.stringify(descriptor["script:ld+json"]),
+    );
     return (
       <script
         key={`ld-json-${index}`}
@@ -159,7 +161,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // Custom tagName (meta or link with arbitrary attributes)
   if (hasTagName(descriptor)) {
     const { tagName, ...rest } = descriptor;
     if (tagName === "link") {
@@ -180,7 +181,6 @@ function renderMetaDescriptor(
     }
   }
 
-  // Fallback: treat as meta attributes
   return (
     <meta
       key={`meta-fallback-${index}`}
@@ -189,17 +189,54 @@ function renderMetaDescriptor(
   );
 }
 
-/**
- * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
- */
-function AsyncMetaTag({
+// Sentinel a rejected async descriptor resolves to: renderMetaDescriptor sees
+// no recognized fields and returns nothing renderable (see renderRejected).
+const REJECTED_META: unique symbol = Symbol("rango.rejectedMeta");
+
+// Cache the rejection-swallowing wrapper per source promise so use() gets a
+// stable reference across re-renders (a fresh .then() each render would make
+// React treat it as a new pending promise and never settle). WeakMap keys on
+// the original promise so entries are collected with it.
+const safeMetaPromises = new WeakMap<
+  Promise<MetaDescriptorBase>,
+  Promise<MetaDescriptorBase | typeof REJECTED_META>
+>();
+
+function toSafeMetaPromise(
+  promise: Promise<MetaDescriptorBase>,
+): Promise<MetaDescriptorBase | typeof REJECTED_META> {
+  let safe = safeMetaPromises.get(promise);
+  if (!safe) {
+    // Swallow the rejection at the promise boundary, not via an error boundary:
+    // an error boundary above a suspended use() makes React abandon the whole
+    // Suspense subtree (and on the server switch it to client rendering). A
+    // settled-to-sentinel promise degrades the single bad descriptor to nothing
+    // while every sibling descriptor still renders.
+    //
+    // Normalize via Promise.resolve first: a collected async descriptor may be a
+    // non-native thenable (a React wakeable in SSR/RSC) whose .then() returns
+    // void rather than a Promise. Calling .then directly would leave `safe`
+    // undefined and use(undefined) would throw ("unsupported type passed to
+    // use()"), 500-ing the page. Promise.resolve adopts the thenable into a
+    // native Promise whose .then always returns one.
+    safe = Promise.resolve(promise).then(
+      (value) => value,
+      () => REJECTED_META,
+    );
+    safeMetaPromises.set(promise, safe);
+  }
+  return safe;
+}
+
+export function AsyncMetaTag({
   promise,
   index,
 }: {
   promise: Promise<MetaDescriptorBase>;
   index: number;
 }): React.ReactNode {
-  const resolved = use(promise);
+  const resolved = use(toSafeMetaPromise(promise));
+  if (resolved === REJECTED_META) return null;
   return renderMetaDescriptor(resolved, index);
 }