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

package/src/__internal.ts

@@ -9,10 +9,6 @@
  * adding them to the public API.
  */
 
-// ============================================================================
-// Segment Resolution (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Internal representation of a resolved route segment.
@@ -26,10 +22,6 @@ export type { ResolvedSegment, SegmentMetadata } from "./types.js";
  */
 export type { MatchResult, SlotState } from "./types.js";
 
-// ============================================================================
-// Intercept System (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Context for intercept route selection.
@@ -40,10 +32,6 @@ export type {
   InterceptWhenFn,
 } from "./server/context.js";
 
-// ============================================================================
-// Browser State (Internal)
-// ============================================================================
-
 /**
  * @internal
  * RSC protocol payload structure.
@@ -68,10 +56,6 @@ export type {
   NavigationUpdate,
 } from "./browser/types.js";
 
-// ============================================================================
-// Handle System (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Internal handle storage mechanism.
@@ -84,26 +68,17 @@ export type { HandleStore, HandleData } from "./server/handle-store.js";
  */
 export type { SegmentHandleData } from "./cache/types.js";
 
-// ============================================================================
-// Cache Internals
-// ============================================================================
-
 /**
  * @internal
  * Internal cache entry data structure.
  */
 export type {
   CachedEntryData,
-  CachedEntryResult,
   CacheGetResult,
   SerializedSegmentData,
   CacheDefaults,
 } from "./cache/types.js";
 
-// ============================================================================
-// Router Context (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Router context for AsyncLocalStorage.
@@ -114,10 +89,6 @@ export type {
   InterceptResult,
 } from "./router/router-context.js";
 
-// ============================================================================
-// Match Pipeline (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Route match context during pipeline processing.
@@ -133,10 +104,6 @@ export type {
  */
 export type { RouteMatchResult } from "./router/pattern-matching.js";
 
-// ============================================================================
-// Server Context (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Entry data during route traversal.
@@ -153,10 +120,6 @@ export type {
   EntryPropSegments,
 } from "./server/context.js";
 
-// ============================================================================
-// Handler Context (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Internal handler context with additional props for router internals.
@@ -164,30 +127,18 @@ export type {
  */
 export type { InternalHandlerContext } from "./types.js";
 
-// ============================================================================
-// Rendering (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Builds React element trees from route segments.
  */
 export { renderSegments } from "./segment-system.js";
 
-// ============================================================================
-// Error Utilities (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Error sanitization and network error utilities.
  */
 export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
 
-// ============================================================================
-// Type Utilities (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
@@ -217,10 +168,6 @@ export type {
   RevalidationDecisionEvent,
 } from "./router/telemetry.js";
 
-// ============================================================================
-// Pre-render / Static Handler Guards (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Type guard for prerender handler definitions.
@@ -233,20 +180,12 @@ export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
  */
 export { isStaticHandler } from "./static-handler.js";
 
-// ============================================================================
-// URL Pattern Internals
-// ============================================================================
-
 /**
  * @internal
  * Sentinel used to tag response-type route entries.
  */
 export { RESPONSE_TYPE } from "./urls.js";
 
-// ============================================================================
-// Route Match Debug (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Debug utilities for route matching performance analysis.
@@ -256,10 +195,6 @@ export {
   getMatchDebugStats,
 } from "./router/pattern-matching.js";
 
-// ============================================================================
-// Debug Utilities (Internal)
-// ============================================================================
-
 /**
  * @internal
  * Debug utilities for manifest inspection and comparison.

package/src/browser/action-coordinator.ts

@@ -5,7 +5,7 @@ import type { ActionEntry } from "./event-controller.js";
  * full-update-unsupported cases are handled inline in the bridge before
  * reconciliation; this only covers successfully-reconciled partial responses.
  */
-export type ActionScenario =
+type ActionScenario =
   | {
       type: "navigated-away";
       historyKeyChanged: boolean;

package/src/browser/action-fence.ts

@@ -0,0 +1,47 @@
+/**
+ * Action fence: a refcounted flag that is raised while a server action is in
+ * flight and lowered when it resolves.
+ *
+ * It replaces the eager cache clear the action bridge used to do at action
+ * start. While the fence is up, the decision of whether the action invalidated
+ * anything is deferred to the response:
+ *
+ * - prefetch consumption is suspended (a queued prefetch result is not served),
+ * - a genuine navigation during the flight fetches with `cache: "no-store"` so
+ *   it cannot be served stale bytes from the browser's Vary-keyed HTTP cache,
+ * - popstate reads are treated as stale-while-revalidate.
+ *
+ * Nothing is wiped, rotated, or broadcast while the fence is up — that is what
+ * keeps a sibling tab from seeing a pre-commit signal. Refcounted so concurrent
+ * actions compose: each action raises and lowers its own reference, and the
+ * fence is down only when the count reaches zero.
+ *
+ * The refcount is a single module-level counter, not keyed by routerId.
+ * Consumers (navigation-client.ts, prefetch/fetch.ts, navigation-bridge.ts)
+ * read it unscoped, so an action in one router would suppress another router's
+ * navigation/prefetch caches. This is correct only because two routers cannot
+ * coexist in one live document: an SPA navigation crossing a host-router
+ * boundary forces a full document reload (src/router/request-classification.ts
+ * app-switch terminal), so there is always exactly one live router per
+ * document. A future multi-router-in-one-document feature must not silently
+ * inherit this global, cross-router cache suppression.
+ */
+
+let fenceCount = 0;
+
+export function enterActionFence(): void {
+  fenceCount++;
+}
+
+export function exitActionFence(): void {
+  if (fenceCount > 0) fenceCount--;
+}
+
+export function isActionFenceActive(): boolean {
+  return fenceCount > 0;
+}
+
+/** Test-only: reset the refcount between cases. */
+export function __resetActionFence(): void {
+  fenceCount = 0;
+}

package/src/browser/app-shell.ts

@@ -1,26 +1,17 @@
 import type { ComponentType, ReactNode } from "react";
 
 /**
- * App-shell metadata: the set of per-router fields that describe the
- * "envelope" around the current app's segment tree. These fields are set
- * from the initial RSC payload and must be replaced atomically when the
- * client navigates into a different router (app switch).
+ * App-shell metadata: the per-router fields describing the "envelope" around
+ * the current app's segment tree — the rootLayout (Document), basename,
+ * version, and router identity. Set once from the initial RSC payload and read
+ * through the AppShellRef when rendering segments.
  *
- * Intentionally NOT part of the shell (all document-lifetime):
- * - themeConfig / initialTheme: ThemeProvider is mounted above the segment
- *   tree and must not remount on smooth transitions.
- * - warmupEnabled: attached to the NavigationProvider's lifetime effect;
- *   toggling it mid-session would tear down and restart idle listeners.
- *   Also not serialized on every full-render path (e.g. the not-found
- *   fallback), so carrying it here would be unreliable.
- * - prefetchCacheTTL: the not-found full-render payload does not serialize
- *   it, so a cross-app nav into a 404 would silently erase the setting.
- *   Mutable shell fields must be serialized on EVERY full-render path,
- *   otherwise absent fields are indistinguishable from "new app has no
- *   value" and the old app's value is dropped.
- *
- * A new document navigation (hard reload) applies these fields from the
- * target app's initial payload.
+ * This is a per-document value. A navigation that crosses a host-router app
+ * boundary is a full document load (the server returns X-RSC-Reload for it;
+ * see request-classification.ts, mode "app-switch"), so the target app's shell
+ * — along with everything else document-level (theme, warmup, prefetch-TTL) —
+ * is established fresh by the target app's own load. The shell is never swapped
+ * in place within a session.
  */
 export interface AppShell {
   /** Router identity. Used to namespace per-app client state (e.g. the
@@ -33,20 +24,16 @@ export interface AppShell {
 }
 
 /**
- * Mutable container for the active app shell. Read-through via `get()` so
- * closures capture the ref, not the shell, and pick up updates at call time.
+ * Container for the active app shell. Read-through via `get()` so closures
+ * (e.g. the segment renderer) capture the ref and read the shell at call time
+ * rather than closing over a stale snapshot.
  */
 export interface AppShellRef {
   get(): AppShell;
-  update(next: AppShell): void;
 }
 
 export function createAppShellRef(initial: AppShell): AppShellRef {
-  let current = initial;
   return {
-    get: () => current,
-    update: (next) => {
-      current = next;
-    },
+    get: () => initial,
   };
 }

package/src/browser/connection-warmup.ts

@@ -0,0 +1,134 @@
+/**
+ * Connection warmup: keep TLS alive after idle periods.
+ *
+ * After IDLE_TIMEOUT of no user interaction the connection is marked "cold".
+ * On the next pointer/touch interaction or a visibility change, a HEAD request
+ * warms the TLS connection before the user actually clicks a link.
+ *
+ * Extracted from NavigationProvider so the idle/cold/warmup state machine is
+ * unit-testable with an injected environment (document, fetch, timers).
+ *
+ * Ordering bug this guards against: the warmup listeners (mousemove/touchstart)
+ * share events with the idle-reset listeners, and the idle-reset listener is
+ * registered first, so it clears the live "cold" flag before the warmup
+ * listener reads it on the same event. A separate coldLatch — set when the
+ * connection goes cold and cleared only when warmup fires or listeners detach,
+ * never by the idle reset — lets the warmup decision see the pre-reset cold
+ * state regardless of listener ordering.
+ */
+
+const IDLE_TIMEOUT = 60_000;
+const DEBOUNCE_DELAY = 150;
+
+type TimerHandle = ReturnType<typeof setTimeout>;
+
+export interface WarmupEnv {
+  doc: Pick<
+    Document,
+    "addEventListener" | "removeEventListener" | "visibilityState"
+  >;
+  fetch: typeof fetch;
+  setTimeout: (fn: () => void, ms: number) => TimerHandle;
+  clearTimeout: (handle: TimerHandle | undefined) => void;
+}
+
+function defaultEnv(): WarmupEnv {
+  return {
+    doc: document,
+    fetch: (...args) => fetch(...args),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+  };
+}
+
+/**
+ * Start the connection-warmup state machine. Returns a cleanup function that
+ * cancels timers and removes all listeners.
+ */
+export function startConnectionWarmup(
+  env: WarmupEnv = defaultEnv(),
+): () => void {
+  const { doc, setTimeout: setT, clearTimeout: clearT } = env;
+
+  let idleTimer: TimerHandle | undefined;
+  let debounceTimer: TimerHandle | undefined;
+  // Cold latch for the warmup decision — see module header. Set in markCold;
+  // cleared only when warmup fires or listeners detach, NOT by resetIdleTimer,
+  // so triggerWarmup sees the pre-reset cold state regardless of listener
+  // ordering (the idle-reset listener runs first on a shared mousemove event).
+  let coldLatch = false;
+  let warmupListenersAttached = false;
+
+  function sendWarmup() {
+    coldLatch = false;
+    env.fetch("/?_rsc_warmup", { method: "HEAD" }).catch(() => {});
+  }
+
+  function triggerWarmup() {
+    if (!coldLatch) return;
+    clearT(debounceTimer);
+    debounceTimer = setT(() => {
+      sendWarmup();
+      detachWarmupListeners();
+      resetIdleTimer();
+    }, DEBOUNCE_DELAY);
+  }
+
+  function onVisibilityChange() {
+    if (doc.visibilityState === "visible" && coldLatch) {
+      triggerWarmup();
+    }
+  }
+
+  function attachWarmupListeners() {
+    if (warmupListenersAttached) return;
+    warmupListenersAttached = true;
+    doc.addEventListener("visibilitychange", onVisibilityChange);
+    doc.addEventListener("mousemove", triggerWarmup, { once: true });
+    doc.addEventListener("touchstart", triggerWarmup, { once: true });
+  }
+
+  function detachWarmupListeners() {
+    warmupListenersAttached = false;
+    coldLatch = false;
+    doc.removeEventListener("visibilitychange", onVisibilityChange);
+    doc.removeEventListener("mousemove", triggerWarmup);
+    doc.removeEventListener("touchstart", triggerWarmup);
+  }
+
+  function markCold() {
+    coldLatch = true;
+    attachWarmupListeners();
+  }
+
+  function resetIdleTimer() {
+    clearT(idleTimer);
+    idleTimer = setT(markCold, IDLE_TIMEOUT);
+  }
+
+  // Activity events that reset the idle timer. mousemove/touchstart overlap
+  // with the warmup listeners; this listener is registered first, which is the
+  // ordering the coldLatch defends against.
+  const activityEvents = [
+    "mousemove",
+    "keydown",
+    "touchstart",
+    "scroll",
+  ] as const;
+  const activityOptions: AddEventListenerOptions = { passive: true };
+
+  for (const event of activityEvents) {
+    doc.addEventListener(event, resetIdleTimer, activityOptions);
+  }
+
+  resetIdleTimer();
+
+  return () => {
+    clearT(idleTimer);
+    clearT(debounceTimer);
+    detachWarmupListeners();
+    for (const event of activityEvents) {
+      doc.removeEventListener(event, resetIdleTimer);
+    }
+  };
+}

package/src/browser/cookie-name.ts

@@ -0,0 +1,140 @@
+/**
+ * Rango state cookie: value codec and attribute serialization.
+ *
+ * Shared by the client (the document.cookie writer in rango-state.ts) and the
+ * server (the Set-Cookie writer in invalidateClientCache). Environment-agnostic:
+ * no window/document access and no name composition.
+ *
+ * Name RESOLUTION deliberately lives elsewhere (router init, see
+ * router/state-cookie-name.ts). Keeping composition out of this shared module
+ * is what lets the client read the server-resolved name verbatim and compose
+ * nothing.
+ */
+
+/** Default prefix when `stateCookiePrefix` is unset or empty after sanitization. */
+export const DEFAULT_STATE_COOKIE_PREFIX = "rango-state";
+
+/** Internal response header carrying the keepClientCache() directive. */
+export const KEEP_CACHE_HEADER = "x-rango-keep-cache";
+
+// Per-client signal headers (lower-case) that a SHARED response cache must never
+// store or replay (Finding #3): a `Set-Cookie` (rango state rotation, or any
+// cookie a loader set) and the keepClientCache() directive. Strip-all-Set-Cookie
+// is deliberate — a shared store can't know the resolved cookie name, and any
+// per-client cookie in a cacheable document is the hazard. Single source for the
+// predicate, presence check, and strip below.
+const PER_CLIENT_SIGNAL_HEADERS: readonly string[] = [
+  "set-cookie",
+  KEEP_CACHE_HEADER,
+];
+
+/** True for a per-client signal header. */
+export function isPerClientSignalHeader(name: string): boolean {
+  return PER_CLIENT_SIGNAL_HEADERS.includes(name.toLowerCase());
+}
+
+/** True if `headers` carries any per-client signal. */
+export function hasPerClientSignal(headers: Headers): boolean {
+  return PER_CLIENT_SIGNAL_HEADERS.some((name) => headers.has(name));
+}
+
+/** Remove every per-client signal header from `headers` in place. */
+export function stripPerClientSignals(headers: Headers): void {
+  for (const name of PER_CLIENT_SIGNAL_HEADERS) headers.delete(name);
+}
+
+/**
+ * Read the raw, UNDECODED value of a single cookie from a cookie string (a
+ * `document.cookie` jar or a request `Cookie` header). Shared by both seats so
+ * the client mirror and the server monotonic-guard read the SAME jar entry —
+ * their agreement is the guard's contract. First match wins (the entry the
+ * client's mirror holds); exact name boundary via the `=`; an empty value
+ * (`name=`) returns null (treated as absent, not a usable prior value).
+ */
+export function getRawCookieValue(
+  cookieString: string | null,
+  name: string,
+): string | null {
+  if (!cookieString) return null;
+  const target = name + "=";
+  for (const part of cookieString.split(";")) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith(target)) {
+      const value = trimmed.slice(target.length);
+      return value === "" ? null : value;
+    }
+  }
+  return null;
+}
+
+/**
+ * Encode a state value for the wire: `encodeURIComponent(version):timestamp`.
+ * Only the build-derived version is encoded (it is arbitrary); the `:`
+ * separator and numeric timestamp stay raw, so the `{version}:{timestamp}`
+ * shape survives and `:` is a legal cookie-value octet.
+ */
+export function encodeStateValue(version: string, timestamp: number): string {
+  return `${encodeURIComponent(version)}:${timestamp}`;
+}
+
+/** Parsed state value. `version` is decoded; `timestamp` is the raw integer. */
+export interface StateValue {
+  version: string;
+  timestamp: number;
+}
+
+/**
+ * Decode a wire value back into `{version, timestamp}`. Returns null for a
+ * malformed value (no `:`, empty version, or non-numeric timestamp) so callers
+ * mint fresh instead of trusting garbage.
+ */
+export function decodeStateValue(raw: string): StateValue | null {
+  const colon = raw.indexOf(":");
+  if (colon <= 0) return null;
+  const timestamp = Number(raw.slice(colon + 1));
+  if (!Number.isFinite(timestamp)) return null;
+  let version: string;
+  try {
+    version = decodeURIComponent(raw.slice(0, colon));
+  } catch {
+    // A malformed percent-escape (e.g. "%:1") must mint fresh, not throw —
+    // a thrown URIError here would 500 the server seat or fail client boot.
+    return null;
+  }
+  return { version, timestamp };
+}
+
+/**
+ * Mint a fresh state value whose timestamp is strictly greater than the previous
+ * one, so a re-mint inside the same millisecond (or a backward clock step) still
+ * differs from the current value. `prevRaw` is the current wire value (the
+ * client's in-memory mirror, or the server's inbound header/cookie) or null; its
+ * timestamp is the floor. Shared by both seats so the monotonic guard lives once.
+ */
+export function mintStateValue(
+  version: string,
+  prevRaw: string | null,
+): string {
+  const prevTs = prevRaw ? (decodeStateValue(prevRaw)?.timestamp ?? 0) : 0;
+  const ts = Math.max(Date.now(), prevTs + 1);
+  return encodeStateValue(version, ts);
+}
+
+/**
+ * Attribute string for the state cookie. Session cookie (no Max-Age/Expires),
+ * Path=/ (whole app), SameSite=Lax (sent on top-level navigations), and Secure
+ * only on https so the document.cookie write does not silently fail on plain
+ * http dev. Never HttpOnly (the client reads and writes it).
+ */
+export function stateCookieAttributes(secure: boolean): string {
+  return `; Path=/; SameSite=Lax${secure ? "; Secure" : ""}`;
+}
+
+/** Serialize a full `name=value` cookie string with the state attributes. */
+export function serializeStateCookie(
+  name: string,
+  value: string,
+  secure: boolean,
+): string {
+  return `${name}=${value}${stateCookieAttributes(secure)}`;
+}