@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1c0bdfad

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,9 +127,73 @@ export type {
  */
 export type { InternalHandlerContext } from "./types.js";
 
-// ============================================================================
-// Debug Utilities (Internal)
-// ============================================================================
+/**
+ * @internal
+ * Builds React element trees from route segments.
+ */
+export { renderSegments } from "./segment-system.js";
+
+/**
+ * @internal
+ * Error sanitization and network error utilities.
+ */
+export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
+
+/**
+ * @internal
+ * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
+ */
+export type { ScopedRouteMap } from "./types.js";
+
+/**
+ * @internal
+ * Type-level utilities for reverse URL generation.
+ */
+export type { MergeRoutes, SanitizePrefix } from "./reverse.js";
+
+/**
+ * @internal
+ * Individual telemetry event types.
+ */
+export type {
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  RequestTimeoutEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+} from "./router/telemetry.js";
+
+/**
+ * @internal
+ * Type guard for prerender handler definitions.
+ */
+export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
+
+/**
+ * @internal
+ * Type guard for static handler definitions.
+ */
+export { isStaticHandler } from "./static-handler.js";
+
+/**
+ * @internal
+ * Sentinel used to tag response-type route entries.
+ */
+export { RESPONSE_TYPE } from "./urls.js";
+
+/**
+ * @internal
+ * Debug utilities for route matching performance analysis.
+ */
+export {
+  enableMatchDebug,
+  getMatchDebugStats,
+} from "./router/pattern-matching.js";
 
 /**
  * @internal

package/src/bin/rango.ts

@@ -6,6 +6,8 @@ import {
   writeCombinedRouteTypes,
   detectUnresolvableIncludes,
   detectUnresolvableIncludesForUrlsFile,
+  findNestedRouterConflict,
+  formatNestedRouterConflictError,
   type UnresolvableInclude,
 } from "../build/generate-route-types.ts";
 
@@ -205,6 +207,14 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     console.warn("");
   }
 
+  const nestedRouterConflict = findNestedRouterConflict(routerFiles);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
   // Phase 3: Write all outputs (only reached if diagnostics pass or --static)
   for (const urlsFile of urlsFiles) {
     writePerModuleRouteTypesForFile(urlsFile);
@@ -259,6 +269,14 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
     process.exit(1);
   }
 
+  const nestedRouterConflict = findNestedRouterConflict(routerEntries);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
   let discoverAndWriteRouteTypes: typeof import("../build/runtime-discovery.ts").discoverAndWriteRouteTypes;
   try {
     const mod = await import("../build/runtime-discovery.ts");

package/src/browser/action-coordinator.ts

@@ -1,9 +1,21 @@
-import {
-  classifyActionResponse,
-  type ActionScenario,
-} from "./action-response-classifier.js";
 import type { ActionEntry } from "./event-controller.js";
 
+/**
+ * Post-reconciliation action outcome (discriminated union). Error and
+ * full-update-unsupported cases are handled inline in the bridge before
+ * reconciliation; this only covers successfully-reconciled partial responses.
+ */
+type ActionScenario =
+  | {
+      type: "navigated-away";
+      historyKeyChanged: boolean;
+      onInterceptRoute: boolean;
+    }
+  | { type: "hmr-missing" }
+  | { type: "consolidation-needed"; segmentIds: string[] }
+  | { type: "concurrent-skip"; otherFetchingCount: number }
+  | { type: "normal" };
+
 /**
  * Plain data inputs for classifying a post-reconciliation action outcome.
  * No browser objects or controller references — all values are snapshots.
@@ -33,20 +45,15 @@ export interface ActionOutcomeInput {
   currentInterceptSource: string | null;
 }
 
-/**
- * Compute consolidation segments from concurrent action state.
- *
- * Returns segment IDs that need re-fetching when concurrent actions
- * have each revalidated different parts of the tree, or null if
- * consolidation is not needed.
- */
+// Segment IDs to re-fetch when concurrent actions each revalidated different
+// parts of the tree; null when consolidation does not apply. Returns null while
+// any action is still fetching — consolidation must wait for all to land.
 function computeConsolidationSegments(
   input: ActionOutcomeInput,
 ): string[] | null {
   if (!input.hadAnyConcurrentActions) return null;
   if (input.revalidatedSegments.size === 0) return null;
 
-  // Can't consolidate while any action is still waiting for a server response
   const stillFetchingCount = [...input.inflightActions.values()].filter(
     (a) => a.phase === "fetching",
   ).length;
@@ -55,9 +62,6 @@ function computeConsolidationSegments(
   return Array.from(input.revalidatedSegments);
 }
 
-/**
- * Count other actions still in "fetching" phase (excluding this handle).
- */
 function countOtherFetchingActions(input: ActionOutcomeInput): number {
   let count = 0;
   for (const [, a] of input.inflightActions) {
@@ -69,29 +73,42 @@ function countOtherFetchingActions(input: ActionOutcomeInput): number {
 }
 
 /**
- * Classify a post-reconciliation action outcome into one of 5 scenarios.
- *
- * This is the single entry point for post-action decision logic.
- * It gathers consolidation and concurrency data from the plain inputs,
- * then delegates to the pure classifyActionResponse function.
- *
- * The server-action-bridge calls this after reconciliation to decide
- * whether to render, skip, consolidate, or refetch.
+ * Classify a post-reconciliation action outcome. Ordered priority chain: each
+ * case assumes the earlier ones are false (e.g. concurrent-skip only applies on
+ * the still-current route, consolidation only once no action is still fetching).
+ * The bridge calls this to decide whether to render, skip, consolidate, or refetch.
  */
 export function classifyActionOutcome(
   input: ActionOutcomeInput,
 ): ActionScenario {
-  return classifyActionResponse({
-    actionStartPathname: input.actionStartPathname,
-    currentPathname: input.currentPathname,
-    actionStartLocationKey: input.actionStartLocationKey,
-    currentLocationKey: input.currentLocationKey,
-    reconciledSegmentCount: input.reconciledSegmentCount,
-    matchedCount: input.matchedCount,
-    currentInterceptSource: input.currentInterceptSource,
-    consolidationSegments: computeConsolidationSegments(input),
-    otherFetchingActionCount: countOtherFetchingActions(input),
-  });
-}
+  if (
+    input.currentPathname !== input.actionStartPathname ||
+    input.currentLocationKey !== input.actionStartLocationKey
+  ) {
+    return {
+      type: "navigated-away",
+      historyKeyChanged:
+        input.currentLocationKey !== input.actionStartLocationKey,
+      onInterceptRoute: input.currentInterceptSource !== null,
+    };
+  }
+
+  if (input.reconciledSegmentCount < input.matchedCount) {
+    return { type: "hmr-missing" };
+  }
+
+  const consolidationSegments = computeConsolidationSegments(input);
+  if (consolidationSegments && consolidationSegments.length > 0) {
+    return { type: "consolidation-needed", segmentIds: consolidationSegments };
+  }
+
+  const otherFetchingActionCount = countOtherFetchingActions(input);
+  if (otherFetchingActionCount > 0) {
+    return {
+      type: "concurrent-skip",
+      otherFetchingCount: otherFetchingActionCount,
+    };
+  }
 
-export type { ActionScenario };
+  return { type: "normal" };
+}

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

@@ -0,0 +1,39 @@
+import type { ComponentType, ReactNode } from "react";
+
+/**
+ * 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.
+ *
+ * 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
+   *  rango-state localStorage key) so sibling apps on the same origin
+   *  cannot observe each other's cache invalidations. */
+  routerId?: string;
+  rootLayout?: ComponentType<{ children: ReactNode }>;
+  basename?: string;
+  version?: string;
+}
+
+/**
+ * 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;
+}
+
+export function createAppShellRef(initial: AppShell): AppShellRef {
+  return {
+    get: () => initial,
+  };
+}

package/src/browser/app-version.ts

@@ -0,0 +1,14 @@
+/**
+ * Mutable app version — updated after HMR revalidation.
+ * Read by prefetch, navigation, and context code.
+ */
+
+let currentVersion: string | undefined;
+
+export function getAppVersion(): string | undefined {
+  return currentVersion;
+}
+
+export function setAppVersion(version: string | undefined): void {
+  currentVersion = version;
+}

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);
+    }
+  };
+}