@rangojs/router 0.0.0-experimental.131 → 0.0.0-experimental.132

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/event-controller.ts

@@ -10,7 +10,10 @@ import type {
   HandleData,
   StreamingToken,
 } from "./types.js";
-import { filterSegmentOrder } from "./react/filter-segment-order.js";
+import {
+  filterSegmentOrder,
+  filterRouteSegmentIds,
+} from "./react/filter-segment-order.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -703,9 +706,7 @@ export function createEventController(
     const newSegmentOrder = filterSegmentOrder(rawMatched);
     // Separate list for useSegments(): "layouts and routes only" — strip
     // parallels (".@") and loader sub-ids (D digit) without reordering.
-    const newRouteSegmentIds = rawMatched.filter(
-      (id) => !id.includes(".@") && !/D\d+\./.test(id),
-    );
+    const newRouteSegmentIds = filterRouteSegmentIds(rawMatched);
 
     if (isPartial && newSegmentOrder.length > 0) {
       // Partial update: merge new data with existing

package/src/browser/partial-update.ts

@@ -191,9 +191,10 @@ export function createPartialUpdater(
     const { payload, streamComplete: rawStreamComplete } = fetchResult;
     debugLog("payload.metadata", payload.metadata);
 
-    const streamComplete = rawStreamComplete.then(() => {
-      streamingToken.end();
-    });
+    // Side effect only: end the streaming token once the stream settles.
+    // The wrapped promise was never read as a value; only the .end() matters.
+    // The .catch keeps an unhandled rejection from leaking if the stream errors.
+    rawStreamComplete.then(() => streamingToken.end()).catch(() => {});
 
     const currentRouterId = store.getRouterId?.();
     if (
@@ -400,19 +401,34 @@ export function createPartialUpdater(
             ? reconciled.interceptSegments
             : undefined,
       };
-      const newTree = await (signal
-        ? Promise.race([
+      let newTree: Awaited<ReturnType<typeof renderSegments>>;
+      if (signal) {
+        // Race render against abort. Store the abort handler and register it
+        // { once:true } so a non-aborted render (which wins the race) can
+        // remove it in finally — otherwise the listener stays attached and the
+        // rejecting promise never settles. Mirrors teeWithCompletion in
+        // browser/response-adapter.ts.
+        let onAbort: (() => void) | undefined;
+        const abortPromise = new Promise<never>((_, reject) => {
+          if (signal.aborted) {
+            reject(new DOMException("Navigation aborted", "AbortError"));
+            return;
+          }
+          onAbort = () =>
+            reject(new DOMException("Navigation aborted", "AbortError"));
+          signal.addEventListener("abort", onAbort, { once: true });
+        });
+        try {
+          newTree = await Promise.race([
             renderSegments(reconciled.mainSegments, renderOptions),
-            new Promise<never>((_, reject) => {
-              if (signal.aborted) {
-                reject(new DOMException("Navigation aborted", "AbortError"));
-              }
-              signal.addEventListener("abort", () => {
-                reject(new DOMException("Navigation aborted", "AbortError"));
-              });
-            }),
-          ])
-        : renderSegments(reconciled.mainSegments, renderOptions));
+            abortPromise,
+          ]);
+        } finally {
+          if (onAbort) signal.removeEventListener("abort", onAbort);
+        }
+      } else {
+        newTree = await renderSegments(reconciled.mainSegments, renderOptions);
+      }
 
       if (signal?.aborted) {
         debugLog("[Browser] Ignoring stale navigation (aborted before commit)");
@@ -540,7 +556,7 @@ export function createPartialUpdater(
           });
         });
       } else if (mode.type === "action") {
-        startTransition(async () => {
+        startTransition(() => {
           if (fullHasTransition && addTransitionType) {
             addTransitionType("action");
           }

package/src/browser/react/NavigationProvider.tsx

@@ -29,6 +29,7 @@ import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
 import { cancelAllPrefetches } from "../prefetch/queue.js";
 import { handleNavigationEnd } from "../scroll-restoration.js";
 import { createAppShellRef, type AppShellRef } from "../app-shell.js";
+import { startConnectionWarmup } from "../connection-warmup.js";
 import { debugLog } from "../logging.js";
 
 /**
@@ -250,91 +251,13 @@ export function NavigationProvider({
     return value;
   }, []);
 
-  // Connection warmup: keep TLS alive after idle periods.
-  // After 60s of no user interaction, marks connection as "cold".
-  // On next interaction or visibility change, sends a HEAD request to warm TLS
-  // before the user actually clicks a link.
+  // Connection warmup: keep TLS alive after idle periods. After 60s of no
+  // interaction the connection is marked cold; the next pointer/touch
+  // interaction or visibility change warms TLS via a HEAD request before the
+  // user clicks a link. State machine lives in connection-warmup.ts.
   useEffect(() => {
     if (!warmupEnabled) return;
-
-    const IDLE_TIMEOUT = 60_000;
-    const DEBOUNCE_DELAY = 150;
-
-    let idleTimer: ReturnType<typeof setTimeout> | undefined;
-    let debounceTimer: ReturnType<typeof setTimeout> | undefined;
-    let isCold = false;
-    let warmupListenersAttached = false;
-
-    function sendWarmup() {
-      isCold = false;
-      fetch("/?_rsc_warmup", { method: "HEAD" }).catch(() => {});
-    }
-
-    function triggerWarmup() {
-      if (!isCold) return;
-      clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(() => {
-        sendWarmup();
-        detachWarmupListeners();
-        resetIdleTimer();
-      }, DEBOUNCE_DELAY);
-    }
-
-    function onVisibilityChange() {
-      if (document.visibilityState === "visible" && isCold) {
-        triggerWarmup();
-      }
-    }
-
-    function attachWarmupListeners() {
-      if (warmupListenersAttached) return;
-      warmupListenersAttached = true;
-      document.addEventListener("visibilitychange", onVisibilityChange);
-      document.addEventListener("mousemove", triggerWarmup, { once: true });
-      document.addEventListener("touchstart", triggerWarmup, { once: true });
-    }
-
-    function detachWarmupListeners() {
-      warmupListenersAttached = false;
-      document.removeEventListener("visibilitychange", onVisibilityChange);
-      document.removeEventListener("mousemove", triggerWarmup);
-      document.removeEventListener("touchstart", triggerWarmup);
-    }
-
-    function markCold() {
-      isCold = true;
-      attachWarmupListeners();
-    }
-
-    function resetIdleTimer() {
-      clearTimeout(idleTimer);
-      isCold = false;
-      idleTimer = setTimeout(markCold, IDLE_TIMEOUT);
-    }
-
-    // Activity events that reset the idle timer
-    const activityEvents = [
-      "mousemove",
-      "keydown",
-      "touchstart",
-      "scroll",
-    ] as const;
-    const activityOptions: AddEventListenerOptions = { passive: true };
-
-    for (const event of activityEvents) {
-      document.addEventListener(event, resetIdleTimer, activityOptions);
-    }
-
-    resetIdleTimer();
-
-    return () => {
-      clearTimeout(idleTimer);
-      clearTimeout(debounceTimer);
-      detachWarmupListeners();
-      for (const event of activityEvents) {
-        document.removeEventListener(event, resetIdleTimer);
-      }
-    };
+    return startConnectionWarmup();
   }, [warmupEnabled]);
 
   // Cancel non-matching prefetches when navigation starts.

package/src/browser/react/filter-segment-order.ts

@@ -51,3 +51,20 @@ export function filterSegmentOrder(matched: string[]): string[] {
   }
   return result;
 }
+
+/**
+ * Build the "layouts and routes only" id list for useSegments().segmentIds.
+ *
+ * Strips parallel slot ids (contain ".@") and loader sub-ids ("D" followed by
+ * a digit, e.g. "M0L0D1.user") without reordering. Distinct from
+ * filterSegmentOrder, which also reorders slots after their parent for handle
+ * collection.
+ *
+ * Shared by SSR (ssr/index.tsx) and the client event controller
+ * (event-controller.ts) so both produce identical output; if they diverge,
+ * useSegments().segmentIds rendered during SSR and after hydration disagree
+ * and React reports a hydration mismatch.
+ */
+export function filterRouteSegmentIds(matched: string[]): string[] {
+  return matched.filter((id) => !id.includes(".@") && !/D\d+\./.test(id));
+}

package/src/browser/react/use-link-status.ts

@@ -102,7 +102,7 @@ export function useLinkStatus(): LinkStatus {
       return;
     }
 
-    return ctx.eventController.subscribe(() => {
+    const update = () => {
       const state = ctx.eventController.getState();
       const isPending = isPendingFor(linkTo, state.pendingUrl, origin);
 
@@ -119,7 +119,15 @@ export function useLinkStatus(): LinkStatus {
         // Always update base state
         setBasePending(isPending);
       }
-    });
+    };
+
+    // Catch-up: re-read state synchronously on mount before subscribing, so a
+    // navigation that started between the seeding render and this effect commit
+    // isn't dropped until the next (debounced) notify. Mirrors usePathname /
+    // useSearchParams.
+    update();
+
+    return ctx.eventController.subscribe(update);
   }, [linkTo, origin]);
 
   // If not inside a Link, return not pending

package/src/browser/react/use-navigation.ts

@@ -70,7 +70,7 @@ export function useNavigation<T>(
 
   // Subscribe to event controller state changes (only runs on client)
   useEffect(() => {
-    return ctx.eventController.subscribe(() => {
+    const update = () => {
       const currentState = ctx.eventController.getState();
       const publicState = toPublicState(currentState);
       const nextSelected = selectorRef.current
@@ -109,7 +109,15 @@ export function useNavigation<T>(
         // Always update base state so UI reflects current state
         setBaseValue(nextSelected);
       }
-    });
+    };
+
+    // Catch-up: re-read state synchronously on mount before subscribing, so a
+    // state change between the seeding render and this effect commit isn't
+    // dropped until the next (debounced) notify. Mirrors usePathname /
+    // useSearchParams.
+    update();
+
+    return ctx.eventController.subscribe(update);
   }, []);
 
   return value as T | PublicNavigationState;

package/src/build/route-types/ast-route-extraction.ts

@@ -15,19 +15,26 @@ import { extractParamsFromPattern } from "./param-extraction.js";
  * the pattern, name, params, and optional search schema from each.
  * Skips unnamed paths (no { name: "..." }).
  */
-export function extractRoutesFromSource(code: string): Array<{
+export function extractRoutesFromSource(
+  code: string,
+  sourceFileArg?: ts.SourceFile,
+): Array<{
   name: string;
   pattern: string;
   params?: Record<string, string>;
   search?: Record<string, string>;
 }> {
-  const sourceFile = ts.createSourceFile(
-    "input.tsx",
-    code,
-    ts.ScriptTarget.Latest,
-    true,
-    ts.ScriptKind.TSX,
-  );
+  // Reuse a caller-provided SourceFile (parsed once per scan) when given;
+  // otherwise parse the block here. The walk does not mutate the tree.
+  const sourceFile =
+    sourceFileArg ??
+    ts.createSourceFile(
+      "input.tsx",
+      code,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TSX,
+    );
   const routes: Array<{
     name: string;
     pattern: string;

package/src/build/route-types/include-resolution.ts

@@ -22,6 +22,61 @@ export interface UnresolvableInclude {
   detail: string;
 }
 
+// ---------------------------------------------------------------------------
+// Per-scan memo
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-scan memo shared across the include-resolution recursion. Keys are
+ * absolute file paths; values cache the readFileSync result and the
+ * ts.SourceFile parsed from the FULL file source. A separate blockSources map
+ * caches parses of extracted sub-blocks (urls() call text), keyed by the exact
+ * block string, so the two extractors (routes + includes) for the same block
+ * share a single parse.
+ *
+ * The memo is purely a performance accelerator: same input -> same parse, so
+ * generated output is identical to the un-memoized path. A fresh memo is
+ * created per top-level scan entry, so stale file edits between scans are never
+ * served.
+ */
+export interface ScanMemo {
+  files: Map<string, string>;
+  blockSourceFiles: Map<string, ts.SourceFile>;
+}
+
+export function createScanMemo(): ScanMemo {
+  return { files: new Map(), blockSourceFiles: new Map() };
+}
+
+function parseBlock(memo: ScanMemo | undefined, block: string): ts.SourceFile {
+  if (memo) {
+    const cached = memo.blockSourceFiles.get(block);
+    if (cached) return cached;
+  }
+  const sf = ts.createSourceFile(
+    "input.tsx",
+    block,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  if (memo) memo.blockSourceFiles.set(block, sf);
+  return sf;
+}
+
+function readSourceMemoized(
+  memo: ScanMemo | undefined,
+  realPath: string,
+): string {
+  if (memo) {
+    const cached = memo.files.get(realPath);
+    if (cached !== undefined) return cached;
+  }
+  const source = readFileSync(realPath, "utf-8");
+  if (memo) memo.files.set(realPath, source);
+  return source;
+}
+
 // ---------------------------------------------------------------------------
 // AST-based include() parsing
 // ---------------------------------------------------------------------------
@@ -47,7 +102,10 @@ function extractNamePrefixFromInclude(node: ts.CallExpression): string | null {
  * Returns both resolved includes (identifier second args) and unresolvable
  * includes (factory calls, etc.) with reasons.
  */
-export function extractIncludesWithDiagnostics(code: string): {
+export function extractIncludesWithDiagnostics(
+  code: string,
+  sourceFileArg?: ts.SourceFile,
+): {
   resolved: Array<{
     pathPrefix: string;
     variableName: string;
@@ -60,13 +118,16 @@ export function extractIncludesWithDiagnostics(code: string): {
     detail: string;
   }>;
 } {
-  const sourceFile = ts.createSourceFile(
-    "input.tsx",
-    code,
-    ts.ScriptTarget.Latest,
-    true,
-    ts.ScriptKind.TSX,
-  );
+  // Reuse a caller-provided SourceFile (parsed once per scan) when given.
+  const sourceFile =
+    sourceFileArg ??
+    ts.createSourceFile(
+      "input.tsx",
+      code,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TSX,
+    );
   const resolved: Array<{
     pathPrefix: string;
     variableName: string;
@@ -206,14 +267,18 @@ export function resolveImportPath(
 function extractUrlsBlockForVariable(
   code: string,
   varName: string,
+  sourceFileArg?: ts.SourceFile,
 ): string | null {
-  const sourceFile = ts.createSourceFile(
-    "input.tsx",
-    code,
-    ts.ScriptTarget.Latest,
-    true,
-    ts.ScriptKind.TSX,
-  );
+  // Reuse a caller-provided full-source SourceFile (parsed once per scan).
+  const sourceFile =
+    sourceFileArg ??
+    ts.createSourceFile(
+      "input.tsx",
+      code,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TSX,
+    );
   let result: string | null = null;
 
   function visit(node: ts.Node) {
@@ -249,11 +314,15 @@ function buildRouteMapFromBlock(
   visited: Set<string>,
   searchSchemasOut?: Record<string, Record<string, string>>,
   diagnosticsOut?: UnresolvableInclude[],
+  memo?: ScanMemo,
 ): Record<string, string> {
   const routeMap: Record<string, string> = {};
 
+  // Parse the block once and share the SourceFile between both extractors.
+  const blockSourceFile = parseBlock(memo, block);
+
   // Extract local path() routes
-  const localRoutes = extractRoutesFromSource(block);
+  const localRoutes = extractRoutesFromSource(block, blockSourceFile);
   for (const { name, pattern, search } of localRoutes) {
     routeMap[name] = pattern;
     if (search && searchSchemasOut) {
@@ -262,8 +331,10 @@ function buildRouteMapFromBlock(
   }
 
   // Extract include() calls with diagnostics for unresolvable ones
-  const { resolved: includes, unresolvable } =
-    extractIncludesWithDiagnostics(block);
+  const { resolved: includes, unresolvable } = extractIncludesWithDiagnostics(
+    block,
+    blockSourceFile,
+  );
 
   if (diagnosticsOut) {
     for (const entry of unresolvable) {
@@ -298,12 +369,17 @@ function buildRouteMapFromBlock(
         imported.exportedName,
         visited,
         diagnosticsOut,
+        undefined,
+        memo,
       );
     } else {
-      // Check if variable exists as a same-file urls() definition
+      // Check if variable exists as a same-file urls() definition. Share the
+      // full-source SourceFile parse via the memo (block === fullSource hits the
+      // same cache entry already used above).
       const sameFileBlock = extractUrlsBlockForVariable(
         fullSource,
         variableName,
+        parseBlock(memo, fullSource),
       );
       if (!sameFileBlock) {
         if (diagnosticsOut) {
@@ -322,6 +398,8 @@ function buildRouteMapFromBlock(
         variableName,
         visited,
         diagnosticsOut,
+        undefined,
+        memo,
       );
     }
 
@@ -361,6 +439,9 @@ function buildRouteMapFromBlock(
  * @param inlineBlock - Optional pre-extracted code block (e.g. from an inline
  *   builder function). When provided, variableName is ignored and the block
  *   is parsed directly for path()/include() calls.
+ * @param memo - Per-scan readFileSync/parse memo. A fresh one is created at the
+ *   top-level entry and threaded through the recursion so each file is read and
+ *   parsed once per scan. Behavior-preserving (same input -> same output).
  */
 export function buildCombinedRouteMapWithSearch(
   filePath: string,
@@ -368,11 +449,13 @@ export function buildCombinedRouteMapWithSearch(
   visited?: Set<string>,
   diagnosticsOut?: UnresolvableInclude[],
   inlineBlock?: string,
+  memo?: ScanMemo,
 ): {
   routes: Record<string, string>;
   searchSchemas: Record<string, Record<string, string>>;
 } {
   visited = visited ?? new Set();
+  memo = memo ?? createScanMemo();
   const realPath = resolve(filePath);
   const key = variableName ? `${realPath}:${variableName}` : realPath;
   if (visited.has(key)) {
@@ -383,7 +466,7 @@ export function buildCombinedRouteMapWithSearch(
 
   let source: string;
   try {
-    source = readFileSync(realPath, "utf-8");
+    source = readSourceMemoized(memo, realPath);
   } catch {
     return { routes: {}, searchSchemas: {} };
   }
@@ -392,7 +475,11 @@ export function buildCombinedRouteMapWithSearch(
   if (inlineBlock) {
     block = inlineBlock;
   } else if (variableName) {
-    const extracted = extractUrlsBlockForVariable(source, variableName);
+    const extracted = extractUrlsBlockForVariable(
+      source,
+      variableName,
+      parseBlock(memo, source),
+    );
     if (!extracted) return { routes: {}, searchSchemas: {} };
     block = extracted;
   } else {
@@ -407,6 +494,7 @@ export function buildCombinedRouteMapWithSearch(
     visited,
     searchSchemas,
     diagnosticsOut,
+    memo,
   );
 
   // Remove from visited so sibling branches can include the same variable