@rangojs/router 0.0.0-experimental.125 → 0.0.0-experimental.126

package/src/build/index.ts

@@ -22,15 +22,14 @@ export {
   type GeneratedManifest,
 } from "./generate-manifest.js";
 
-export {
-  buildRouteTrie,
-  buildPerRouterTrie,
-  type TrieNode,
-  type TrieLeaf,
-} from "./route-trie.js";
-
-export { collectFallbackClientRefs } from "./collect-fallback-refs.js";
-
+// buildRouteTrie / buildPerRouterTrie / collectFallbackClientRefs and the
+// TrieNode/TrieLeaf types are NOT exported here: they are build-pipeline
+// internals, not public API. Their only build-time consumer (the Vite
+// discovery pass) imports them directly from source via a relative path
+// (vite/discovery/discover-routers.ts), and the runtime RSC realm likewise
+// imports route-trie.js directly (rsc/manifest-init.ts). Keeping them off the
+// public ./build surface (#569 decision 6) means consumers can't mistake them
+// for intended API. generateManifest* / route-types / hashParams stay public.
 export {
   writePerModuleRouteTypes,
   extractRoutesFromSource,

package/src/build/route-trie.ts

@@ -22,9 +22,6 @@ export interface TrieLeaf {
   sp: string;
   /** Ancestry shortCodes from root to route [M0L0, M0L0L0, M0L0L0R499] */
   a: string[];
-  /** Optional param names declared on the route. Absent params are
-   * omitted from the matched params record (read as `undefined`). */
-  op?: string[];
   /** Constraint validation: paramName -> allowed values */
   cv?: Record<string, string[]>;
   /** Ordered param names for this route (positional) */
@@ -100,9 +97,49 @@ export function buildRouteTrie(
     });
   }
 
+  sortSuffixParams(root);
   return root;
 }
 
+/**
+ * Sort every node's suffix-param map (`node.xp`) by descending suffix length so
+ * the matcher tries the most specific suffix first. Overlapping suffixes like
+ * `.min.js` and `.js` must resolve by specificity, not route declaration order:
+ * a request for `/app.min.js` should match `:file.min.js`, not `:file.js`.
+ *
+ * This started as a bug — `walkTrie` iterates `node.xp` in object order and
+ * returns the first suffix the segment ends with, so the winner depended on
+ * which route was declared first. Sorting at build time fixes it allocation-free
+ * on the match hot path: the serialized production trie preserves this key order
+ * through JSON.parse, so dev (per-request rebuild) and production match
+ * identically. Array.prototype.sort is stable (ES2019+), so equal-length
+ * suffixes keep their declaration order — the router's existing tiebreak.
+ */
+function sortSuffixParams(node: TrieNode): void {
+  if (node.xp) {
+    const sorted: Record<string, { n: string; c: TrieNode }> = {};
+    for (const suffix of Object.keys(node.xp).sort(
+      (a, b) => b.length - a.length,
+    )) {
+      sorted[suffix] = node.xp[suffix];
+    }
+    node.xp = sorted;
+  }
+  if (node.s) {
+    for (const child of Object.values(node.s)) {
+      sortSuffixParams(child);
+    }
+  }
+  if (node.p) {
+    sortSuffixParams(node.p.c);
+  }
+  if (node.xp) {
+    for (const child of Object.values(node.xp)) {
+      sortSuffixParams(child.c);
+    }
+  }
+}
+
 /**
  * Build a per-router trie from a generated manifest. This is the single
  * construction path shared by build/discovery (discover-routers.ts, serialized
@@ -158,18 +195,14 @@ function insertRoute(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: Omit<TrieLeaf, "op" | "cv" | "pa">,
+  leaf: Omit<TrieLeaf, "cv" | "pa">,
 ): void {
-  // op (full optional list) and cv (full constraint map) are route-level and
-  // identical on every terminal, so compute them once on the shared base.
-  const optionalParams: string[] = [];
+  // cv (full constraint map) is route-level and identical on every terminal,
+  // so compute it once on the shared base.
   const constraints: Record<string, string[]> = {};
 
   for (const seg of segments) {
     if (seg.type === "param") {
-      if (seg.optional) {
-        optionalParams.push(seg.value);
-      }
       if (seg.constraint) {
         constraints[seg.value] = seg.constraint;
       }
@@ -178,7 +211,6 @@ function insertRoute(
 
   const leafBase: Omit<TrieLeaf, "pa"> = {
     ...leaf,
-    ...(optionalParams.length > 0 ? { op: optionalParams } : {}),
     ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
   };
 

package/src/cache/cache-runtime.ts

@@ -21,6 +21,7 @@ import {
   createClientTemporaryReferenceSet,
 } from "@vitejs/plugin-rsc/rsc";
 import { getRequestContext } from "../server/request-context.js";
+import { isUnderTestRunner } from "../runtime-env.js";
 import {
   isTainted,
   CACHED_FN_SYMBOL,
@@ -59,6 +60,10 @@ async function replyToCacheKey(encoded: string | FormData): Promise<string> {
   return text;
 }
 
+// Cached-fn ids already warned about running uncached under a test runner, so
+// the test-ergonomics warning fires once per fn rather than once per call.
+const warnedUncachedUnderTest = new Set<string>();
+
 // ============================================================================
 // Core: registerCachedFunction
 // ============================================================================
@@ -91,6 +96,22 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // and nothing is lost on a (non-existent) hit. Same applies to the
     // non-serializable-args bypass below.
     if (!store?.getItem) {
+      // Test-ergonomics guard: under a test runner, a "use cache" function that
+      // executes with no item-capable store seeded is exercising the UNCACHED
+      // path — a green test that proves nothing about caching. Warn once per fn
+      // id so the author knows to seed a cacheStore. Advisory (never throws), so
+      // a test that DELIBERATELY runs uncached is unaffected. Gated on the test
+      // runner (process.env.VITEST, not folded) so production never evaluates it.
+      if (isUnderTestRunner() && !warnedUncachedUnderTest.has(id)) {
+        warnedUncachedUnderTest.add(id);
+        console.warn(
+          `[rango] "use cache" function "${id}" executed but no cacheStore was ` +
+            `seeded; the cached path is NOT under test (it ran uncached). Pass ` +
+            `{ cacheStore, cacheProfiles } to runLoader/runMiddleware/renderHandler/` +
+            `runInRequestContext (or configure createRouter({ cache }) for dispatch) ` +
+            `to exercise it.`,
+        );
+      }
       const scoped = runWithCacheTagScope(() => fn.apply(this, args));
       const result = await scoped.result;
       // Still record the runtime tags into the request set so a cacheTag() in an

package/src/cache/document-cache.ts

@@ -55,6 +55,16 @@ interface CacheDirectives {
 function parseCacheControl(header: string | null): CacheDirectives | null {
   if (!header) return null;
 
+  // RFC 7234: in a SHARED cache, `private` and `no-store` forbid storage and
+  // MUST win over `s-maxage` even though `private, s-maxage` is contradictory.
+  // The document cache is a shared edge store, so refuse both regardless of any
+  // s-maxage / stale-while-revalidate also present. Match standalone directive
+  // tokens (start/end, whitespace, comma, semicolon, or `=` bounded), not a
+  // substring, so a value containing "private" cannot false-veto.
+  if (/(^|[\s,;])(private|no-store)(?=$|[\s,;=])/i.test(header)) {
+    return null;
+  }
+
   const directives: CacheDirectives = {};
 
   // Parse s-maxage

package/src/cache/profile-registry.ts

@@ -1,9 +1,11 @@
 /**
- * Cache Profile Registry
+ * Cache profile resolution.
  *
- * Named cache profiles for "use cache" directive.
- * Profiles define TTL, SWR, and optional default tags.
- * Set by createRouter() at startup, read by registerCachedFunction() at runtime.
+ * Named cache profiles for the "use cache" directive define TTL, SWR, and
+ * optional default tags. createRouter() resolves the user's profiles once via
+ * resolveCacheProfiles() and threads the resulting map onto each request
+ * context; the "use cache: <profile>" runtime path reads it from there
+ * (request-scoped) — there is no global registry.
  */
 
 export interface CacheProfile {
@@ -17,10 +19,6 @@ export interface CacheProfile {
 
 const DEFAULT_PROFILE: CacheProfile = { ttl: 900, swr: 1800 };
 
-let _profiles: Record<string, CacheProfile> = {
-  default: DEFAULT_PROFILE,
-};
-
 const PROFILE_NAME_RE = /^[a-zA-Z0-9_-]+$/;
 
 /**
@@ -49,29 +47,3 @@ export function resolveCacheProfiles(
   }
   return merged;
 }
-
-/**
- * Set all cache profiles in the global registry.
- * Called by createRouter() at startup for DSL-time resolution
- * (cache("profileName") reads from this during route definition).
- *
- * WARNING: This is global mutable state. It exists only for DSL-time
- * reads. Runtime resolution (registerCachedFunction) uses request-scoped
- * profiles and does NOT read from this registry.
- */
-export function setCacheProfiles(profiles: Record<string, CacheProfile>): void {
-  _profiles = resolveCacheProfiles(profiles);
-}
-
-/**
- * Read a profile out of the global registry by name.
- *
- * There is currently no production reader: the "use cache: <profile>" runtime
- * path resolves from the request-scoped _cacheProfiles map (see
- * cache-runtime.ts), and the route DSL has no cache("profileName") form (see
- * dsl-helpers.ts). This accessor exists so tests can assert what
- * setCacheProfiles() wrote into the global registry.
- */
-export function getCacheProfile(name: string): CacheProfile | undefined {
-  return _profiles[name];
-}

package/src/client.rsc.tsx

@@ -63,5 +63,8 @@ export { useHref } from "./browser/react/use-href.js";
 export { useReverse } from "./browser/react/use-reverse.js";
 
 export { useHandle } from "./browser/react/use-handle.js";
+// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
+// (a `ctx.use(Handle).defer()` slot) until it resolves.
+export type { DeferredHandleEntry } from "./defer.js";
 
 export { useLocationState } from "./browser/react/location-state.js";

package/src/client.tsx

@@ -344,6 +344,8 @@ export type {
   RouterInstance,
   RouterNavigateOptions,
   ReadonlyURLSearchParams,
+  ActionState,
+  ActionLifecycleState,
 } from "./browser/types.js";
 
 export {
@@ -382,6 +384,9 @@ export {
 
 export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
+// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
+// (a `ctx.use(Handle).defer()` slot) until it resolves.
+export type { DeferredHandleEntry } from "./defer.js";
 
 export { Meta } from "./handles/meta.js";
 export { MetaTags } from "./handles/MetaTags.js";

package/src/context-var.ts

@@ -70,6 +70,18 @@ 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 }).

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/handles/breadcrumbs.ts

@@ -39,18 +39,29 @@ export interface BreadcrumbItem {
 /**
  * Collect function for Breadcrumbs handle.
  * Flattens segments in parent-to-child order with deduplication by href
- * (last item for each href wins).
+ * (last item for each href wins). Deferred slots (`ctx.use(Breadcrumbs).defer()`)
+ * arrive as pending Promise entries with no href yet; they are passed through by
+ * identity and excluded from the href dedup so concurrent deferred crumbs do not
+ * all collapse under a single `undefined` href.
  */
 function collectBreadcrumbs(segments: BreadcrumbItem[][]): BreadcrumbItem[] {
   const all = segments.flat();
-  const seen = new Map<string, number>();
 
+  const isResolvedItem = (item: unknown): item is BreadcrumbItem =>
+    item != null &&
+    typeof item === "object" &&
+    typeof (item as { then?: unknown }).then !== "function" &&
+    typeof (item as { href?: unknown }).href === "string";
+
+  const seen = new Map<string, number>();
   for (let i = 0; i < all.length; i++) {
-    seen.set(all[i].href, i);
+    if (isResolvedItem(all[i])) seen.set(all[i].href, i);
   }
 
-  // Return items in order, keeping only the last occurrence per href
-  return all.filter((item, index) => seen.get(item.href) === index);
+  // Deferred items bypass dedup (excluded via !isResolvedItem check).
+  return all.filter(
+    (item, index) => !isResolvedItem(item) || seen.get(item.href) === index,
+  );
 }
 
 /**

package/src/index.rsc.ts

@@ -114,6 +114,13 @@ export type {
 
 // Handle API
 export { createHandle, isHandle, type Handle } from "./handle.js";
+export {
+  DEFAULT_DEFER_TIMEOUT_MS,
+  type DeferOptions,
+  type DeferredHandleEntry,
+  type HandlePush,
+  type HandlePushFn,
+} from "./defer.js";
 
 // Context variable API (typed ctx.set/ctx.get tokens)
 export { createVar, type ContextVar } from "./context-var.js";

package/src/index.ts

@@ -140,6 +140,13 @@ export function redirect(): never {
 
 // Handle API (universal - works on both server and client)
 export { createHandle, isHandle, type Handle } from "./handle.js";
+export {
+  DEFAULT_DEFER_TIMEOUT_MS,
+  type DeferOptions,
+  type DeferredHandleEntry,
+  type HandlePush,
+  type HandlePushFn,
+} from "./defer.js";
 
 // Context variable API (typed ctx.set/ctx.get tokens)
 export { createVar, type ContextVar } from "./context-var.js";

package/src/redirect-origin.ts

@@ -0,0 +1,100 @@
+/**
+ * Runtime-neutral same-origin redirect rule.
+ *
+ * Shared by the client redirect guard (`browser/validate-redirect-origin.ts`,
+ * which validates redirect targets the client JS is about to navigate to) and
+ * the server outgoing-redirect guard (`rsc/redirect-guard.ts`, which validates
+ * every browser-followed `Location` header before it leaves the handler). Kept
+ * at the `src/` root so both layers import the ONE rule and cannot drift -- a
+ * cross-origin target blocked on the JS/fetch path is blocked identically on the
+ * no-JS (PE) and full-page document paths.
+ */
+
+/**
+ * Resolve a redirect target against the current origin.
+ *
+ * Returns the canonical (normalized) same-origin href -- which also collapses
+ * protocol-relative (`//evil.com`) and other ambiguous forms -- or `null` when
+ * the target resolves to a different origin or is unparseable. Pure: no logging,
+ * no side effects.
+ */
+export function resolveSameOriginRedirect(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  try {
+    const target = new URL(url, currentOrigin);
+    if (target.origin !== currentOrigin) {
+      return null;
+    }
+    return target.href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate an explicit off-origin redirect target (`redirect(url, { external:
+ * true })`).
+ *
+ * `external` opts out of the same-origin rule, but NOT out of scheme safety:
+ * only `http:`/`https:` targets are allowed. A redirect ultimately reaches the
+ * browser via `window.location.assign()` on the SPA/action client paths, so a
+ * forged or mistaken `redirect("javascript:...", { external: true })` would be a
+ * scriptable navigation if the scheme were not checked here. Returns the
+ * normalized href for an http(s) target (same- or cross-origin), or `null`
+ * otherwise. Pure: no logging, no side effects.
+ */
+export function resolveExternalRedirect(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  try {
+    const target = new URL(url, currentOrigin);
+    if (target.protocol !== "http:" && target.protocol !== "https:") {
+      return null;
+    }
+    return target.href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Out-of-band brand for `redirect(url, { external: true })`.
+ *
+ * The external opt-in MUST be settable only by app code calling `redirect(...,
+ * { external: true })`, never by an attacker. An earlier design carried the
+ * opt-in as a wire header (`x-rango-redirect-external`), but a wire header is
+ * forgeable: a proxy-style response route that copies an attacker-controlled
+ * upstream response's headers would let `302 Location: https://evil` plus that
+ * header bypass the same-origin guard without app code ever opting in. So the
+ * opt-in is now an out-of-band brand on the Response object itself, tracked in a
+ * `WeakSet` that cannot cross the wire. `redirect()` brands the Response; the
+ * small set of internal redirect-rebuild paths (middleware `mergeResponse`,
+ * `carryOverRedirectHeaders`, the response-route rewrap) transfer the brand onto
+ * the rebuilt Response; the guard and the SPA intercept read it. An upstream
+ * Response an app proxies is never branded, so its forged header is inert.
+ *
+ * Fail-closed: if a rebuild path ever drops the brand, the redirect is
+ * neutralized to the app root rather than allowed off-host.
+ */
+const externalRedirects = new WeakSet<Response>();
+
+/** Brand a Response as an explicit `{ external: true }` redirect (out-of-band). */
+export function markExternalRedirect(response: Response): void {
+  externalRedirects.add(response);
+}
+
+/** Read the out-of-band `{ external: true }` brand off a Response. */
+export function isExternalRedirect(response: Response): boolean {
+  return externalRedirects.has(response);
+}
+
+/**
+ * Reserved internal header name. No longer a trust signal -- the external
+ * opt-in is the out-of-band brand above. It is kept only so the redirect-rebuild
+ * paths and the guard can defensively strip any value (e.g. one forged by a
+ * proxied upstream) and guarantee it never reaches the browser.
+ */
+export const EXTERNAL_REDIRECT_MARKER: string = "x-rango-redirect-external";