@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/shared/als-slots.ts

@@ -0,0 +1,74 @@
+/**
+ * ALS getter slots for the isomorphic `define*` modules.
+ *
+ * `searchParams.get()` and `segmentParams.get()` read per-request state out of
+ * `server/als-registry.ts`, but the modules that expose them are *isomorphic*:
+ * `search-params/define.ts` and `segment-params/define.ts` are imported by
+ * `'use client'` components for their hooks, so neither may import
+ * `node:async_hooks` — not even transitively, because the dep optimizer
+ * pre-bundles them before per-environment resolution runs. So the server
+ * registers its getter into a slot at module-init time and the define modules
+ * read the slot.
+ *
+ * The slots live here, in a module with **no imports at all**, rather than in
+ * the define modules themselves. That is the whole point: `request-context.ts`
+ * has to reach the setter, and when the setter lived in
+ * `search-params/define.ts` every server entry that touched
+ * `@timber-js/app/server` pulled that module — and therefore its `'use client'`
+ * import of `client/use-query-states.ts`, and therefore `nuqs` — into the
+ * server graph. `nuqs` named-imports `createContext`/`useContext` from React,
+ * which React's `react-server` export withholds, so `@timber-js/app`,
+ * `@timber-js/app/server`, `@timber-js/app/cookies` and `@timber-js/app/cache`
+ * all failed to instantiate under the `react-server` condition (TIM-1298).
+ * A leaf module breaks the edge without a registration ceremony on either side.
+ *
+ * Registration must be eager, not a call-time `await import()`: the async
+ * microtask a dynamic import introduces loses AsyncLocalStorage context inside
+ * React's RSC Flight renderer, which broke `getSearchParams()` in parallel slot
+ * pages (TIM-523).
+ *
+ * See design/23-search-params.md §"defineSearchParams — The Factory" and
+ * design/41-global-params.md.
+ */
+
+import type { CoercedParams } from './param-value.ts';
+
+interface AlsSlot<T> {
+  /** Register the server-side getter. Called once at module-init time. */
+  set(fn: () => T): void;
+  /** Read through to the registered getter, or throw the client-side message. */
+  get(): T;
+}
+
+function createAlsSlot<T>(message: string): AlsSlot<T> {
+  let fn: (() => T) | undefined;
+  return {
+    set(next) {
+      fn = next;
+    },
+    get() {
+      if (!fn) throw new Error(message);
+      return fn();
+    },
+  };
+}
+
+const searchParamsSlot = createAlsSlot<URLSearchParams>(
+  '[timber] searchParams.get() is only available on the server. ' +
+    'Use searchParams.useQueryStates() on the client.'
+);
+
+const segmentParamsSlot = createAlsSlot<CoercedParams>(
+  '[timber] segmentParams.get() is only available on the server. ' +
+    'Use segmentParams.useSegmentParams() on the client.'
+);
+
+/** @internal Called from `server/request-context.ts` at module init. */
+export const _setGetSearchParamsFn = searchParamsSlot.set;
+/** @internal Read by `search-params/define.ts` inside `.get()`. */
+export const getSearchParamsFromAls = searchParamsSlot.get;
+
+/** @internal Called from `server/request-context.ts` at module init. */
+export const _setGetSegmentParamsFn = segmentParamsSlot.set;
+/** @internal Read by `segment-params/define.ts` inside `.get()`. */
+export const getSegmentParamsFromAls = segmentParamsSlot.get;

package/src/shared/base-path.ts

@@ -0,0 +1,80 @@
+/**
+ * Deployment base path — Vite's resolved `base`, as it applies to the URLs
+ * timber addresses at runtime.
+ *
+ * A static build deployed under a sub-path (`base: '/repo/'`, the GitHub
+ * Pages project-site layout) serves every generated file below that prefix:
+ * the document for `/about` lives at `/repo/about/index.html`, its flight
+ * payload at `/repo/_rsc/about/index.rsc`. The client works in *route space* — the
+ * paths the app declares — so both a strip (browser URL → route path) and a
+ * prefix (route-space path → URL) are needed, and this module owns both.
+ *
+ * Pure functions, no state: the caller supplies the base. `client/rsc-fetch.ts`
+ * holds the client's copy, set at bootstrap from `virtual:timber-config`.
+ *
+ * See design/11-platform.md §"Deploying under a non-root base" (TIM-1261).
+ */
+
+/** `https://cdn.example.com/`, `//cdn.example.com/` — a base pointing off-origin. */
+function isAbsoluteUrlBase(base: string): boolean {
+  return base.startsWith('//') || /^[a-z][a-z0-9+.-]*:\/\//i.test(base);
+}
+
+/**
+ * True when `base` is document-relative (`'./'`, `'foo/'`) — it makes asset
+ * URLs resolve against whatever document loaded them, which says nothing
+ * about where the deployment sits, so no prefix can be computed from it.
+ */
+export function isRelativeBase(base: string | undefined): boolean {
+  if (!base) return false;
+  return !base.startsWith('/') && !isAbsoluteUrlBase(base);
+}
+
+/**
+ * Normalize Vite's `base` into a path prefix. Always returns a value with a
+ * leading and trailing slash.
+ *
+ * Two forms carry no usable deployment prefix and normalize to `/`:
+ *
+ * - **An absolute-URL base** points *assets* at a CDN. The HTML documents and
+ *   `.rsc` payloads are still served from the deployment origin, so their
+ *   URLs stay root-relative. This is correct, not a degradation.
+ * - **A relative base** — see `isRelativeBase`. The static build warns,
+ *   because SPA navigation then only works at the domain root.
+ */
+export function normalizeBasePath(base: string | undefined): string {
+  if (!base) return '/';
+  if (isAbsoluteUrlBase(base) || isRelativeBase(base)) return '/';
+  return base.endsWith('/') ? base : `${base}/`;
+}
+
+/**
+ * Strip the base prefix from a browser pathname, returning the route-space
+ * path. With base `/repo/`: `/repo/about` → `/about`, `/repo/` and `/repo`
+ * → `/`.
+ *
+ * A pathname outside the base is returned unchanged. It cannot be served by
+ * this deployment at all, so there is no better answer than letting the
+ * resulting fetch 404 and the router hard-navigate — visibly wrong beats
+ * silently rewritten.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export function stripBasePath(base: string, pathname: string): string {
+  if (base === '/') return pathname;
+  const withoutTrailingSlash = base.slice(0, -1);
+  if (pathname === withoutTrailingSlash) return '/';
+  if (!pathname.startsWith(base)) return pathname;
+  return pathname.slice(withoutTrailingSlash.length);
+}
+
+/**
+ * Prefix a route-space, root-relative path with the base.
+ * `/_rsc/about/index.rsc` → `/repo/_rsc/about/index.rsc`.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export function withBasePath(base: string, path: string): string {
+  if (base === '/') return path;
+  return path.startsWith('/') ? base.slice(0, -1) + path : `${base}${path}`;
+}

package/src/shared/href-validation.ts

@@ -0,0 +1,159 @@
+/**
+ * Shared href/URL validation for all navigation sinks.
+ *
+ * Used by <Link>, useRouter().push/replace, and redirectExternal().
+ * Single source of truth for dangerous-scheme detection — prevents
+ * control-character smuggling that bypasses naive regex checks.
+ *
+ * See design/13-security.md §"Link scheme injection" (test #9)
+ * and design/07-routing.md §"<Link> Scheme Validation".
+ */
+
+/**
+ * All C0 control characters (U+0000–U+001F) that browsers strip during
+ * URL preprocessing. Browsers and `new URL()` strip the full C0 range,
+ * not just tab/LF/CR — so we must match that behavior to prevent
+ * bypass vectors like `\x00javascript:alert(1)`.
+ */
+// eslint-disable-next-line no-control-regex -- intentional: must match all C0 controls to prevent bypass
+const CONTROL_CHARS_RE = /[\x00-\x1f]/g;
+
+const DANGEROUS_SCHEMES = new Set(['javascript:', 'data:', 'vbscript:']);
+
+/**
+ * Strip C0 control chars and leading whitespace, then extract the scheme.
+ * Returns the lowercase scheme (e.g. "javascript:") or null if no scheme.
+ */
+function extractScheme(href: string): string | null {
+  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart();
+  const match = /^([a-z][a-z0-9+.-]*:)/i.exec(cleaned);
+  return match ? match[1].toLowerCase() : null;
+}
+
+/**
+ * Validate an href for navigation sinks (<Link>, useRouter, etc.).
+ *
+ * Rejects dangerous schemes (javascript:, data:, vbscript:) even when
+ * control characters are embedded to bypass naive regex checks.
+ * Also rejects protocol-relative URLs (//evil.com).
+ *
+ * Throws on rejection. Safe hrefs pass through silently.
+ */
+export function validateNavigationHref(href: string): void {
+  // Normalize for validation: strip C0 controls, trim, then replace backslashes
+  // with forward slashes. Browsers normalize \ → / during URL resolution, so
+  // "/\evil.com" becomes "//evil.com" (protocol-relative open redirect).
+  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\', '/');
+
+  // Protocol-relative URLs can redirect to attacker-controlled origins
+  if (cleaned.startsWith('//')) {
+    throw new Error(
+      `Navigation received a protocol-relative or backslash-prefixed URL: "${href}". ` +
+        'Use an absolute URL with an explicit scheme or a relative path.'
+    );
+  }
+
+  const scheme = extractScheme(href);
+  if (scheme && DANGEROUS_SCHEMES.has(scheme)) {
+    throw new Error(
+      `Navigation received a dangerous href: "${href}". ` +
+        'javascript:, data:, and vbscript: URLs are not allowed.'
+    );
+  }
+}
+
+/**
+ * Check if an href is internal (same-origin navigation) or external.
+ *
+ * Strips control characters before checking so that "java\tscript:" is
+ * correctly identified as having a scheme (and thus not internal).
+ */
+export function isInternalHref(href: string): boolean {
+  const cleaned = href.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\', '/');
+
+  if (cleaned.startsWith('//')) return false;
+  if (cleaned.startsWith('/') || cleaned.startsWith('#') || cleaned.startsWith('?')) return true;
+
+  const scheme = extractScheme(href);
+  if (scheme) return false;
+
+  return true;
+}
+
+/** Pattern matching absolute URLs: any scheme (http:, javascript:, …) or protocol-relative // */
+const ABSOLUTE_URL_RE = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
+
+/**
+ * Assert that a redirect target is a relative path — rejects absolute and
+ * protocol-relative URLs. Used by both the server `redirect()` primitive and
+ * the client next/navigation shim so they enforce identical semantics.
+ *
+ * Normalizes for validation only: strips C0 controls, trims, then replaces
+ * backslashes with forward slashes. Browsers normalize \ → / during URL
+ * resolution, so "/\evil.com" becomes "//evil.com" (protocol-relative open
+ * redirect). See design/13-security.md tests #8, #8a–#8c.
+ */
+export function assertRelativeRedirectPath(path: string): void {
+  const cleaned = path.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\', '/');
+
+  if (ABSOLUTE_URL_RE.test(cleaned)) {
+    throw new Error(
+      `redirect() only accepts relative URLs. Got absolute URL: "${path}". ` +
+        'Use redirectExternal(url, allowList) for external redirects.'
+    );
+  }
+
+  // eslint-disable-next-line no-control-regex -- intentional: must match C0 controls
+  if (/[\x00-\x1f]/.test(path)) {
+    throw new Error(
+      `redirect() received a path containing control characters (U+0000–U+001F). ` +
+        'Sanitize user input before passing it to redirect().'
+    );
+  }
+}
+
+const SAFE_REDIRECT_SCHEMES = new Set(['http:', 'https:']);
+
+/**
+ * Validate and canonicalize an external redirect URL.
+ *
+ * Requires http: or https: scheme and checks origin against an allow-list.
+ * Returns the parsed canonical URL string (from URL.href) to prevent
+ * raw user input from reaching the Location header.
+ *
+ * @throws On invalid URL, dangerous scheme, or origin not in allow-list.
+ */
+export function validateExternalRedirectUrl(url: string, allowList: string[]): string {
+  // Strip control chars before parsing to prevent scheme smuggling
+  const cleaned = url.replace(CONTROL_CHARS_RE, '').trimStart();
+
+  if (cleaned.startsWith('//')) {
+    throw new Error(
+      `redirectExternal() received a protocol-relative URL: "${url}". ` +
+        'Use an absolute URL with http: or https: scheme.'
+    );
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(cleaned);
+  } catch {
+    throw new Error(`redirectExternal() received an invalid URL: "${url}"`);
+  }
+
+  if (!SAFE_REDIRECT_SCHEMES.has(parsed.protocol)) {
+    throw new Error(
+      `redirectExternal() received a non-http(s) URL: "${url}". ` +
+        'Only http: and https: schemes are allowed for external redirects.'
+    );
+  }
+
+  if (!allowList.includes(parsed.origin)) {
+    throw new Error(
+      `redirectExternal() target "${parsed.origin}" is not in the allow-list. ` +
+        `Allowed: [${allowList.join(', ')}]`
+    );
+  }
+
+  return parsed.href;
+}

package/src/shared/merge-search-params.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared utility for merging preserved search params into a target URL.
+ *
+ * Used by both <Link> (client) and redirect() (server). Extracted to a shared
+ * module to avoid importing client code ('use client') from server modules.
+ */
+
+/**
+ * Merge preserved search params from the current URL into a target href.
+ *
+ * When `preserve` is `true`, all current search params are merged.
+ * When `preserve` is a `string[]`, only the named params are merged.
+ *
+ * The target href's own search params take precedence — preserved params
+ * are only added if the target doesn't already define them.
+ *
+ * @param targetHref - The resolved target href (may already contain query string)
+ * @param currentSearch - The current URL's search string (e.g. "?private=access&page=2")
+ * @param preserve - `true` to preserve all, or `string[]` to preserve specific params
+ * @returns The target href with preserved search params merged in
+ */
+export function mergePreservedSearchParams(
+  targetHref: string,
+  currentSearch: string,
+  preserve: true | string[]
+): string {
+  const currentParams = new URLSearchParams(currentSearch);
+  if (currentParams.size === 0) return targetHref;
+
+  // Split hash fragment from target before processing query params.
+  // Hash must come after query string: /path?query=value#hash
+  const hashIdx = targetHref.indexOf('#');
+  const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;
+  const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : '';
+
+  // Split target into path and existing query
+  const qIdx = hrefWithoutHash.indexOf('?');
+  const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;
+  const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : '');
+
+  // Collect params to preserve (that aren't already in the target)
+  const merged = new URLSearchParams(targetParams);
+  for (const [key, value] of currentParams) {
+    // Only preserve if: (a) not already in target, and (b) included in preserve list
+    if (!targetParams.has(key)) {
+      if (preserve === true || preserve.includes(key)) {
+        merged.append(key, value);
+      }
+    }
+  }
+
+  const qs = merged.toString();
+  const pathWithQuery = qs ? `${targetPath}?${qs}` : targetPath;
+  return pathWithQuery + hash;
+}

package/src/shared/param-value.ts

@@ -0,0 +1,281 @@
+/**
+ * The canonical form of a segment param value.
+ *
+ * `getSegmentParams()` on the server and `useSegmentParams()` on the client
+ * must return the same value — same prototype, same own properties. This
+ * module is how that is guaranteed, and the mechanism matters:
+ *
+ * **Both sides are images of one normalizer.** A codec's output is deep-cloned
+ * into a closed canonical domain at coercion time, and *that clone* is what the
+ * server returns and what goes on the wire. Server and client agree by
+ * construction, because neither holds the codec's original.
+ *
+ * That replaces predicting what React Flight would do to an arbitrary value.
+ * Prediction is what the previous design attempted and it cannot be finished:
+ * the question "will Flight's decode output be observably identical to this
+ * input?" ranges over every way a JS object can carry state that is not in its
+ * serialization — own keys, enumerability, symbols, holes, accessors,
+ * subclassing, exotic objects — and a `Proxy` defeats it outright, since a
+ * lying `getPrototypeOf` trap makes any static check unsound. Twelve review
+ * findings on PR #992 were each one more case of that set, and the set does
+ * not close.
+ *
+ * Normalizing closes it. The only remaining question is whether Flight
+ * round-trips the normalizer's *output range* — a finite domain we defined,
+ * covered by `tests/e2e/segment-params.test.ts` against the real serializer.
+ *
+ * ## The domain
+ *
+ * - `undefined`, `null`, `string`, `number`, `boolean`, `bigint`
+ * - null-prototype objects, own enumerable string keys only
+ * - dense arrays
+ * - `Date`, `Map`, `Set` — rebuilt, never the codec's instance
+ *
+ * ...and it is a **tree**: no value appears twice, and nothing is cyclic.
+ * That is not a simplification, it is the last prediction being removed.
+ * Flight encodes a `Date` by value at each occurrence but tracks plain objects
+ * for reference dedup, so preserving aliasing would carry it across for some
+ * types and drop it for others — and knowing which is exactly the kind of
+ * guess this design exists to stop making (codex, PR #992). A tree has no
+ * sharing to preserve or lose, so what Flight does about it is unobservable.
+ *
+ * Anything else throws, naming the param and what it was. Note what is *not*
+ * a rejection: a `Date` subclass normalizes to a `Date`, a decorated array to
+ * a plain one, a sparse array to a dense one, a getter to the value it
+ * returned. Those used to be twelve separate checks. They are not divergences
+ * any more, because the normalization happens once and both sides see its
+ * result — so they need no checks at all.
+ *
+ * Own properties that Flight would drop (non-enumerable, symbol-keyed) are
+ * dropped here instead, symmetrically. Prototype pollution is handled by the
+ * same pass: `__proto__` is never copied, and every object is
+ * `Object.create(null)` (design/13-security.md #36b/#36c, TIM-873).
+ *
+ * ## The prototype flip
+ *
+ * Flight refuses to serialize a null-prototype object, so the canonical form
+ * cannot go on the wire as-is. `toPlainRecord` and `toNullProtoRecord` flip
+ * the prototype on the way out and back. They are exact inverses and both
+ * total, because they only ever see canonical values — there is nothing to
+ * validate and no shape to special-case.
+ *
+ * See design/41-global-params.md §"Transport".
+ */
+
+// ─── Post-coercion param types ──────────────────────────────────────────
+
+/**
+ * A single segment param value after codec coercion and normalization.
+ *
+ * Before coercion, every param is `string | string[]` (the raw URL part).
+ * After `app/schema.ts` codecs run, a param can be any value in the
+ * `normalizeParamValue` domain below. This type replaces the previous
+ * `string | string[]` declaration, which was a lie whenever a codec
+ * produced a non-string value (TIM-1347).
+ *
+ * The typed accessor `getSegmentParams(SEGMENT_PATH)` resolves through
+ * the schema and returns the exact type the codec declares. This type
+ * covers the untyped/no-argument form and internal plumbing.
+ */
+export type CoercedParamValue =
+  | string
+  | number
+  | boolean
+  | bigint
+  | null
+  | undefined
+  | Date
+  | Map<CoercedParamValue, CoercedParamValue>
+  | Set<CoercedParamValue>
+  | CoercedParamValue[]
+  | { [key: string]: CoercedParamValue };
+
+/**
+ * A record of coerced segment params, keyed by param name.
+ *
+ * This is the post-coercion type for `segmentParams` throughout the
+ * framework. Before coercion (route matcher output, `rawSegmentParams`),
+ * the type is `Record<string, string | string[]>`.
+ */
+export type CoercedParams = Record<string, CoercedParamValue>;
+
+/** Types the canonical form rebuilds rather than rejects. */
+const REBUILT = ['Date', 'Map', 'Set'] as const;
+
+/** The domain, for error messages. Derived, never a second hand-written list. */
+const DOMAIN = `a string, number, boolean, bigint, null, undefined, a plain object, an array, or ${REBUILT.join('/')}`;
+
+function reject(path: string, was: string, hint: string): never {
+  throw new Error(
+    `[timber] Segment param "${path || '(root)'}" was coerced to ${was}, which cannot ` +
+      `cross to the client. A param value may be ${DOMAIN}.\n` +
+      `  ${hint}\n` +
+      `  See design/41-global-params.md §"Transport".`
+  );
+}
+
+function describe(value: object): string {
+  return (value as { constructor?: { name?: string } }).constructor?.name ?? 'an object';
+}
+
+/**
+ * Deep-clone a codec's output into the canonical form, or throw.
+ *
+ * `seen` accumulates every object the walk has entered, and a second encounter
+ * is rejected. That is one rule for two things — a shared reference and a cycle
+ * are both "this object again" — and it is what keeps the result a tree.
+ */
+export function normalizeParamValue(value: unknown, path = ''): CoercedParamValue {
+  return normalize(value, path, new Set());
+}
+
+function normalize(value: unknown, path: string, seen: Set<object>): CoercedParamValue {
+  if (value === null) return null;
+
+  const kind = typeof value;
+  if (kind === 'string' || kind === 'number' || kind === 'boolean' || kind === 'bigint') {
+    return value as string | number | boolean | bigint;
+  }
+  if (kind === 'undefined') return undefined;
+  if (kind === 'function') {
+    reject(path, 'a function', 'Return the data it would produce, not the function.');
+  }
+  if (kind === 'symbol') {
+    reject(path, 'a symbol', 'Return a string instead — a symbol has no wire representation.');
+  }
+
+  const object = value as object;
+  if (seen.has(object)) {
+    throw new Error(
+      `[timber] Segment param "${path || '(root)'}" is a value that already appears ` +
+        `elsewhere in the same param — a shared reference or a cycle. A param value is a ` +
+        `tree: React Flight carries a repeated \`Date\` by value and a repeated object by ` +
+        `reference, so sharing would survive for some types and not others.\n` +
+        `  Return separate values, or move the shared part outside the params.\n` +
+        `  See design/41-global-params.md §"Transport".`
+    );
+  }
+  seen.add(object);
+
+  if (Array.isArray(object)) {
+    // Read by index, so holes become `undefined` — on both sides, which is
+    // the point. A subclass and any own properties are left behind for the
+    // same reason: the clone is a plain, dense array either way.
+    const out: CoercedParamValue[] = [];
+    for (let index = 0; index < object.length; index++) {
+      out.push(normalize((object as unknown[])[index], `${path}[${index}]`, seen));
+    }
+    return out;
+  }
+
+  if (object instanceof Date) {
+    // A fresh Date, so a subclass or an attached property cannot travel half
+    // way and be dropped by the wire.
+    return new Date(object.getTime());
+  }
+
+  if (object instanceof Map) {
+    const out = new Map<CoercedParamValue, CoercedParamValue>();
+    for (const [key, entry] of object) {
+      out.set(
+        normalize(key, `${path}<key>`, seen),
+        normalize(entry, `${path}.get(${keyLabel(key)})`, seen)
+      );
+    }
+    return out;
+  }
+
+  if (object instanceof Set) {
+    const out = new Set<CoercedParamValue>();
+    let index = 0;
+    for (const entry of object) out.add(normalize(entry, `${path}[${index++}]`, seen));
+    return out;
+  }
+
+  // Everything else is judged by its prototype. A `Proxy` can lie here, and
+  // that is fine: whatever it answers, the clone below reads through it once
+  // and both sides see the same snapshot.
+  const prototype = Object.getPrototypeOf(object);
+  if (prototype !== null && prototype !== Object.prototype) {
+    reject(
+      path,
+      `a ${describe(object)} instance`,
+      'Return a plain object with the fields you need.'
+    );
+  }
+
+  // Own *enumerable string* keys only — the rest is what Flight would drop,
+  // so dropping it here keeps the two sides identical. `__proto__` is skipped
+  // rather than copied: it has a language-level setter that would change the
+  // prototype chain of the copy (TIM-655, TIM-855, TIM-873).
+  const out: Record<string, CoercedParamValue> = Object.create(null);
+  for (const key of Object.keys(object)) {
+    if (key === '__proto__') continue;
+    out[key] = normalize(
+      (object as Record<string, unknown>)[key],
+      path ? `${path}.${key}` : key,
+      seen
+    );
+  }
+  return out;
+}
+
+function keyLabel(key: unknown): string {
+  return typeof key === 'string' ? JSON.stringify(key) : String(key);
+}
+
+// ─── Prototype flip ──────────────────────────────────────────────
+
+/**
+ * Canonical form → wire form. React Flight rejects a null prototype
+ * ("Classes or null prototypes are not supported"), so objects cross as plain
+ * ones and are restored on arrival.
+ */
+export function toPlainRecord<T>(value: T): T {
+  return reproto(value, {}) as T;
+}
+
+/** Wire form → canonical form. The exact inverse of `toPlainRecord`. */
+export function toNullProtoRecord<T>(value: T): T {
+  return reproto(value, null) as T;
+}
+
+/**
+ * Rebuild a canonical value with objects on `proto`.
+ *
+ * Total by construction: its input is always canonical, so the cases are the
+ * domain and nothing else. No validation, no shape it might not have seen, and
+ * no cycle to guard — a canonical value is a tree. That is what moving the
+ * checking to `normalizeParamValue` bought.
+ */
+function reproto(value: unknown, proto: object | null): unknown {
+  if (value === null || typeof value !== 'object') return value;
+
+  const object = value as object;
+
+  // A Date carries no nested values, so it crosses as itself.
+  if (object instanceof Date) return object;
+
+  if (Array.isArray(object)) {
+    return (object as unknown[]).map((item) => reproto(item, proto));
+  }
+
+  if (object instanceof Map) {
+    const out = new Map<unknown, unknown>();
+    for (const [key, entry] of object) out.set(reproto(key, proto), reproto(entry, proto));
+    return out;
+  }
+
+  if (object instanceof Set) {
+    const out = new Set<unknown>();
+    for (const entry of object) out.add(reproto(entry, proto));
+    return out;
+  }
+
+  const out: Record<string, unknown> = proto === null ? Object.create(null) : {};
+  for (const key of Object.keys(object)) {
+    if (key === '__proto__') continue;
+    out[key] = reproto((object as Record<string, unknown>)[key], proto);
+  }
+  return out;
+}