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

package/src/browser/navigation-transaction.ts

@@ -13,7 +13,6 @@ import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
 import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 
-// Re-export for consumers that import from navigation-transaction
 export { resolveNavigationState } from "./history-state.js";
 
 /** Check if a history state object contains location state keys. */
@@ -25,7 +24,6 @@ function hasLocationState(state: unknown): boolean {
   );
 }
 
-// Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
   (Symbol as any).dispose = Symbol("Symbol.dispose");
 }
@@ -114,7 +112,6 @@ export function createNavigationTransaction(
   let committed = false;
   const currentUrl = window.location.href;
 
-  // Start navigation in event controller (this sets loading state)
   const handle = eventController.startNavigation(url, options);
 
   /**
@@ -138,72 +135,50 @@ export function createNavigationTransaction(
 
     const parsedUrl = new URL(url, window.location.origin);
 
-    // Generate history key from URL (with intercept suffix for separate caching)
     const historyKey = generateHistoryKey(url, { intercept });
 
-    // For cache-only commits (stale revalidation), only update cache and return
-    // Don't touch store state or history - user may have navigated elsewhere
     if (cacheOnly) {
       const currentHandleData = eventController.getHandleState().data;
       store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
-      // Complete the navigation handle so currentNavigation is cleared.
-      // Without this, the entry lingers and weakens state-machine invariants.
       handle.complete(parsedUrl);
       debugLog("[Browser] Cache-only commit, historyKey:", historyKey);
       return { scroll: false };
     }
 
-    // Save current scroll position before navigating
     handleNavigationStart();
 
-    // Update segment state atomically
     store.setSegmentIds(segmentIds);
     store.setCurrentUrl(url);
     store.setPath(parsedUrl.pathname);
 
     store.setHistoryKey(historyKey);
 
-    // Cache segments with current handleData for this history entry
     const currentHandleData = eventController.getHandleState().data;
     store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
 
-    // For server actions, skip URL/history updates but still complete navigation
     if (storeOnly) {
       debugLog("[Browser] Store updated (action)");
-      // Complete navigation to clear loading state
       handle.complete(parsedUrl);
       return { scroll: false };
     }
 
-    // Build history state - include user state, intercept info, and server-set state
     const historyState = buildHistoryState(
       opts.state,
       { intercept, sourceUrl: interceptSourceUrl },
       serverState,
     );
 
-    // Snapshot old state before pushState/replaceState overwrites it.
-    // Used to detect when location state is being cleared.
     const oldState = window.history.state;
 
-    // Update browser URL (stamps history.state.idx for back() first-entry detection)
     pushHistoryWithIdx(historyState, url, replace ?? false);
-    // Ensure new history entry has a scroll restoration key
     ensureHistoryKey();
 
-    // Notify location state hooks when either old or new state carries
-    // location state. This covers both "set new state" and "clear old state"
-    // for same-page navigations where components don't remount.
     if (hasLocationState(oldState) || hasLocationState(historyState)) {
       window.dispatchEvent(new Event("__rsc_locationstate"));
     }
 
-    // Complete the navigation in event controller (sets idle state, updates location)
     handle.complete(parsedUrl);
 
-    // NOTE: Scroll is NOT handled here. The caller (partial-update.ts) handles
-    // scroll AFTER onUpdate() so React has the new content before we scroll.
-
     debugLog(
       "[Browser] Navigation committed, historyKey:",
       historyKey,
@@ -217,10 +192,6 @@ export function createNavigationTransaction(
     handle,
     commit,
 
-    /**
-     * Create a bound transaction with pre-configured URL options
-     * segmentIds and segments provided at commit time (after they're resolved)
-     */
     with(
       opts: Omit<CommitOptions, "segmentIds" | "segments">,
     ): BoundTransaction {
@@ -264,13 +235,10 @@ export function createNavigationTransaction(
     },
 
     [Symbol.dispose]() {
-      // Superseded: another navigation took over.
       if (handle.signal.aborted) {
         return;
       }
 
-      // Failed (not committed): keep the target URL -- the error UI owns it.
-      // Just reset the event controller to idle.
       if (!committed) {
         handle[Symbol.dispose]();
       }

package/src/browser/partial-update.ts

@@ -24,20 +24,12 @@ import { debugLog } from "./logging.js";
 import { validateRedirectOrigin } from "./validate-redirect-origin.js";
 import type { NavigationUpdate } from "./types.js";
 
-/** Build a scroll payload from the commit's scroll option */
 function toScrollPayload(
   scroll: boolean | undefined,
 ): NonNullable<NavigationUpdate["scroll"]> {
   return { enabled: scroll !== false ? scroll : false };
 }
 
-/**
- * Whether to wrap an update in startViewTransition.
- *
- * Intercept-driven updates only mutate the parallel slot — the main outlet
- * shows the same content — so transitions on the underlying main segments
- * shouldn't fire (otherwise their elements get hoisted above the modal).
- */
 function shouldStartViewTransition(segments: ResolvedSegment[]): boolean {
   let hasIntercept = false;
   let hasTransition = false;
@@ -112,15 +104,6 @@ export type PartialUpdater = (
   mode?: UpdateMode,
 ) => Promise<void>;
 
-/**
- * Create a partial updater for fetching and applying RSC partial updates
- *
- * This function is shared between navigation-bridge and server-action-bridge
- * to handle partial RSC updates with HMR resilience.
- *
- * @param config - Partial update configuration
- * @returns fetchPartialUpdate function
- */
 export function createPartialUpdater(
   config: PartialUpdateConfig,
 ): PartialUpdater {
@@ -132,21 +115,12 @@ export function createPartialUpdater(
     getVersion = () => undefined,
   } = config;
 
-  /**
-   * Get current page's cached segments as an array
-   */
   function getCurrentCachedSegments(): ResolvedSegment[] {
     const currentKey = store.getHistoryKey();
     const cached = store.getCachedSegments(currentKey);
     return cached?.segments || [];
   }
 
-  /**
-   * Fetch partial update and trigger UI update
-   *
-   * @param tx - Transaction for committing segment state (required)
-   * @param signal - AbortSignal to check if navigation is stale (not for aborting fetch)
-   */
   async function fetchPartialUpdate(
     targetUrl: string,
     segmentIds: string[] | undefined,
@@ -158,20 +132,16 @@ export function createPartialUpdater(
     const segmentState = store.getSegmentState();
     const url = targetUrl || window.location.href;
 
-    // Capture history key at start for stale revalidation consistency check
     const historyKeyAtStart = store.getHistoryKey();
 
     const interceptSourceUrl = mode.interceptSourceUrl;
 
-    // When leaving intercept, filter out intercept-specific segments
     let segments: string[];
     if (mode.type === "leave-intercept") {
       const currentSegments = segmentIds ?? segmentState.currentSegmentIds;
       const currentCached = getCurrentCachedSegments();
       const interceptIds = new Set(
-        currentCached
-          .filter((s) => s.namespace?.startsWith("intercept:"))
-          .map((s) => s.id),
+        currentCached.filter(isInterceptSegment).map((s) => s.id),
       );
       segments = currentSegments.filter((id) => !interceptIds.has(id));
       debugLog(
@@ -181,12 +151,6 @@ export function createPartialUpdater(
       segments = segmentIds ?? segmentState.currentSegmentIds;
     }
 
-    // For intercept revalidation, use the intercept source URL as previousUrl.
-    // For leave-intercept, tx.currentUrl captures window.location.href at tx
-    // creation, which on popstate is already the destination URL and would
-    // tell the server "from == to". segmentState.currentUrl still points at
-    // the URL the cached segments render (the intercept URL), which is the
-    // correct "from" for the server's diff computation.
     const previousUrl =
       mode.type === "leave-intercept"
         ? segmentState.currentUrl || tx.currentUrl
@@ -200,9 +164,6 @@ export function createPartialUpdater(
       debugLog(`[Browser] Intercept context from: ${interceptSourceUrl}`);
     }
 
-    // Get cached segments for merging with server diff.
-    // When navigating with targetCacheSegments, use those for consistency.
-    // Otherwise fall back to current page's segments (for same-route revalidation).
     const targetCache =
       mode.type === "navigate" && mode.targetCacheSegments?.length
         ? mode.targetCacheSegments
@@ -213,22 +174,16 @@ export function createPartialUpdater(
       `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
     );
 
-    // Fetch partial payload (no abort signal - RSC doesn't support it well)
     let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
     fetchResult = await client.fetchPartial({
       targetUrl: url,
       segmentIds: segments,
       previousUrl,
-      // Mark stale when explicitly requested OR when no segments are sent
-      // (action redirect sends empty segments for a fresh render).
       staleRevalidation:
         mode.type === "stale-revalidation" || segments.length === 0,
       version: getVersion(),
       routerId: store.getRouterId?.(),
     });
-    // Mark navigation as streaming (response received, now parsing RSC).
-    // Called after fetchPartial so pendingUrl stays set during the network wait,
-    // allowing useLinkStatus to show per-link pending indicators.
     const streamingToken = tx.startStreaming();
     const { payload, streamComplete: rawStreamComplete } = fetchResult;
     debugLog("payload.metadata", payload.metadata);
@@ -237,13 +192,6 @@ export function createPartialUpdater(
       streamingToken.end();
     });
 
-    // Integrity guard (defense in depth). The server redirects on a cross-app
-    // routerId mismatch (X-RSC-Reload), so a partial payload's routerId must
-    // match this client's. If it doesn't — a stale/edge cache keyed without the
-    // routerId, a proxy mixing app responses, or a server classification bug —
-    // do NOT splice a foreign app's segments and client references into this
-    // document. Force a full reload so the server re-establishes the
-    // authoritative document for this URL.
     const currentRouterId = store.getRouterId?.();
     if (
       payload.metadata?.routerId &&
@@ -258,7 +206,6 @@ export function createPartialUpdater(
       return;
     }
 
-    // Handle server-side redirect with state
     if (payload.metadata?.redirect) {
       if (signal?.aborted) {
         debugLog("[Browser] Ignoring stale redirect (aborted)");
@@ -288,7 +235,6 @@ export function createPartialUpdater(
       debugLog(`[Browser] Partial update - matched: ${matched?.join(", ")}`);
       debugLog(`[Browser] Diff: ${diff?.join(", ")}`);
 
-      // If diff is empty, nothing changed on server side.
       if (!diff || diff.length === 0) {
         const matchedIds = matched || [];
         const cacheMap = new Map(cachedSegs.map((s) => [s.id, s]));
@@ -296,7 +242,6 @@ export function createPartialUpdater(
           .map((id: string) => cacheMap.get(id))
           .filter(Boolean) as ResolvedSegment[];
 
-        // When navigating with cached segments to a different route, render them.
         if (mode.type === "navigate" && targetCache) {
           debugLog(
             "[Browser] No diff but navigating with cached segments - rendering target route",
@@ -311,10 +256,6 @@ export function createPartialUpdater(
             existingSegments,
           );
 
-          // tx.commit() cached the source page's handleData because
-          // eventController hasn't been updated yet. Overwrite with the
-          // correct cached handleData to prevent cache corruption on
-          // subsequent navigations to this same URL.
           if (mode.targetCacheHandleData) {
             store.updateCacheHandleData(
               store.getHistoryKey(),
@@ -322,10 +263,6 @@ export function createPartialUpdater(
             );
           }
 
-          // Include cachedHandleData in metadata so NavigationProvider can restore
-          // breadcrumbs and other handle data from cache.
-          // Remove `handles` from metadata to prevent NavigationProvider from
-          // processing an empty handles stream, which would clear the cached breadcrumbs.
           const { handles: _unusedHandles, ...metadataWithoutHandles } =
             payload.metadata!;
           const cachedUpdate = {
@@ -352,7 +289,6 @@ export function createPartialUpdater(
           return;
         }
 
-        // When leaving intercept, force re-render even with empty diff
         if (mode.type === "leave-intercept") {
           debugLog(
             "[Browser] Leaving intercept - forcing re-render to remove modal",
@@ -377,7 +313,6 @@ export function createPartialUpdater(
           return;
         }
 
-        // Same route revalidation with no changes - skip UI update
         debugLog(
           "[Browser] No changes - all revalidations returned false, keeping existing UI",
         );
@@ -386,7 +321,6 @@ export function createPartialUpdater(
         return;
       }
 
-      // Reconcile server segments with cached segments (single source of truth)
       const matchedIds = matched || [];
       const actor: ReconcileActor =
         mode.type === "stale-revalidation" || mode.type === "action"
@@ -402,7 +336,6 @@ export function createPartialUpdater(
         insertMissingDiff: true,
       });
 
-      // HMR RESILIENCE: Check if we're missing any matched segments
       const reconciledIdSet = new Set(reconciled.segments.map((s) => s.id));
       const missingIds = matchedIds.filter(
         (id: string) => !reconciledIdSet.has(id),
@@ -430,7 +363,6 @@ export function createPartialUpdater(
           `[Browser] HMR detected: Missing ${missingCount} segments. Refetching all...`,
         );
 
-        // Refetch with empty segments = server sends everything
         return fetchPartialUpdate(url, [], true, signal, tx, mode);
       }
 
@@ -439,7 +371,6 @@ export function createPartialUpdater(
         return;
       }
 
-      // Rebuild tree on client (await for loader data resolution)
       const renderOptions = {
         isAction: mode.type === "action",
         forceAwait: mode.type === "stale-revalidation",
@@ -462,21 +393,15 @@ export function createPartialUpdater(
           ])
         : renderSegments(reconciled.mainSegments, renderOptions));
 
-      // Final abort check before committing - another navigation may have started
       if (signal?.aborted) {
         debugLog("[Browser] Ignoring stale navigation (aborted before commit)");
         return;
       }
 
-      // Check if this is an intercept response (any slot is active)
       const isInterceptResponse = hasActiveInterceptSlots(
         payload.metadata?.slots,
       );
 
-      // Track intercept context (only on navigation, not actions or stale revalidation)
-      // Use the authoritative source from mode/history state when restoring an
-      // intercept via popstate cache miss; fall back to the current URL for fresh
-      // intercept navigations.
       const effectiveInterceptSource =
         interceptSourceUrl || segmentState.currentUrl;
       if (mode.type !== "action" && mode.type !== "stale-revalidation") {
@@ -487,9 +412,6 @@ export function createPartialUpdater(
         }
       }
 
-      // Commit navigation - use server's matched as the authoritative segment ID list.
-      // reconciled.segments may be missing IDs (e.g., loader segments not in diff or cache)
-      // but the server's matched always includes all expected segment IDs.
       const allSegmentIds = matchedIds;
       const serverLocationState = payload.metadata?.locationState;
       const overrides: CommitOverrides | undefined = isInterceptResponse
@@ -508,7 +430,6 @@ export function createPartialUpdater(
         overrides,
       );
 
-      // For stale revalidation: verify history key hasn't changed before updating UI
       if (mode.type === "stale-revalidation") {
         const historyKeyNow = store.getHistoryKey();
         if (historyKeyNow !== historyKeyAtStart) {
@@ -521,8 +442,6 @@ export function createPartialUpdater(
 
       debugLog("[partial-update] updating document");
 
-      // Emit update to trigger React render.
-      // Scroll info is included so NavigationProvider applies it after React commits.
       const hasTransition = shouldStartViewTransition(reconciled.segments);
       const scrollPayload = toScrollPayload(navScroll);
 
@@ -559,7 +478,6 @@ export function createPartialUpdater(
       debugLog("[Browser] Navigation complete");
       return;
     } else {
-      // Full update (fallback)
       console.warn(`[Browser] Full update (fallback)`);
 
       const segments = payload.metadata?.segments || [];

package/src/browser/prefetch/cache.ts

@@ -31,6 +31,12 @@
  *
  * Replaces the previous browser HTTP cache approach which was unreliable
  * due to response draining race conditions and browser inconsistencies.
+ *
+ * State here lives in module-level singletons (cache, inflight, generation,
+ * cacheTTL, etc.) rather than a per-instance factory. This is correct because
+ * exactly one router is live per document — an SPA navigation crossing a
+ * host-router boundary forces a full document reload — so the singletons are
+ * effectively per-document. Unit tests reset them via clearPrefetchCache().
  */
 
 import { abortAllPrefetches } from "./queue.js";
@@ -61,9 +67,6 @@ export interface DecodedPrefetch {
   scope: "source" | "wildcard";
 }
 
-// Default TTL: 5 minutes. Overridden by initPrefetchCache() with
-// the server-configured prefetchCacheTTL from router options.
-// 0 disables the in-memory cache entirely.
 let cacheTTL = 300_000;
 
 /**
@@ -92,41 +95,12 @@ interface PrefetchCacheEntry {
 const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
 
-/**
- * In-flight promise map. When a prefetch fetch+decode is in progress, its
- * Promise<DecodedPrefetch | null> is stored here so navigation can await it
- * instead of starting a duplicate request. Resolves to null when the prefetch
- * failed, was aborted, or carried a control header (reload/redirect) that the
- * navigation must re-fetch to act on.
- */
 const inflightPromises = new Map<string, Promise<DecodedPrefetch | null>>();
 
-/**
- * Alias map for in-flight promises registered under multiple keys (see
- * dual inflight in prefetch/fetch.ts). Records each key's sibling set so
- * that consuming or clearing any one key atomically removes every alias —
- * guaranteeing a single consumer for the shared decode.
- */
 const inflightAliases = new Map<string, string[]>();
 
-/**
- * Keys whose in-flight prefetch promise was adopted by a navigation (via
- * `consumeInflightPrefetch`). A `DecodedPrefetch` carries a single-use
- * `metadata.handles` async generator; the adopter drains it. The same entry is
- * also published to the `cache` map by `storePrefetch` when the fetch resolves
- * — which runs AFTER adoption (adoption only succeeds while the fetch is still
- * in flight, so the entry is not yet cached). Without this guard the adopted,
- * now-drained entry would be left in the cache and served to a later navigation
- * whose handle generator yields nothing, silently dropping that route's
- * breadcrumbs. Recording the adopted keys lets `storePrefetch` skip publishing
- * them, keeping the existing one-time-consumption contract (a consumed prefetch
- * is gone; the next navigation re-fetches).
- */
 const adoptedKeys = new Set<string>();
 
-// Generation counter incremented on each clearPrefetchCache(). Fetches that
-// started before a clear carry a stale generation and must not store their
-// response (the data may be stale due to a server action invalidation).
 let generation = 0;
 
 /**
@@ -306,9 +280,6 @@ export function markPrefetchInflight(key: string): void {
   inflight.add(key);
 }
 
-/**
- * Store the in-flight Promise for a prefetch so navigation can reuse it.
- */
 export function setInflightPromise(
   key: string,
   promise: Promise<DecodedPrefetch | null>,
@@ -337,20 +308,10 @@ export function clearPrefetchInflight(key: string): void {
     inflight.delete(k);
     inflightPromises.delete(k);
     inflightAliases.delete(k);
-    // Clear any adopted marker too, so a fetch that failed before storePrefetch
-    // (the marker's normal consumer) does not strand it across the next prefetch.
     adoptedKeys.delete(k);
   });
 }
 
-/**
- * Invalidate all prefetch state. Called when server actions mutate data.
- * Clears the in-memory cache, cancels in-flight prefetches, and rotates
- * the Rango state key so CDN-cached responses are also invalidated.
- *
- * Uses abortAllPrefetches (hard cancel) because in-flight responses
- * may contain stale data after a mutation.
- */
 export function clearPrefetchCache(): void {
   generation++;
   inflight.clear();

package/src/browser/prefetch/queue.ts

@@ -71,10 +71,13 @@ function scheduleDrain(): void {
       Promise.race([waitForViewportImages(), wait(IMAGE_WAIT_TIMEOUT)]),
     )
     .then(() => {
-      drainScheduled = false;
-      // Stale drain: a cancel/abort happened while we were waiting.
-      // A fresh scheduleDrain will be called by whatever enqueues next.
+      // Stale drain: a cancel/abort happened while we were waiting, and a fresh
+      // scheduleDrain may already own drainScheduled for the new generation.
+      // Bail WITHOUT clearing the flag so we don't clobber the live wait's
+      // single-in-flight-drain coalescing (clearing it here would let the next
+      // enqueue start a third overlapping wait).
       if (gen !== drainGeneration) return;
+      drainScheduled = false;
       if (queue.length > 0) drain();
     });
 }

package/src/browser/rango-state.ts

@@ -32,23 +32,13 @@ import {
   serializeStateCookie,
 } from "./cookie-name.js";
 
-// The resolved cookie name this document is bound to (server-resolved, read
-// from payload metadata at boot). Bare default until initRangoState runs.
 let cookieName: string = DEFAULT_STATE_COOKIE_PREFIX;
 
-// Build version for this document, used as the prefix of minted values.
 let currentVersion = "0";
 
-// Write-through mirror of the value. Authoritative only when the cookie is
-// unreadable. `cookieBacked` records whether the mirror was last confirmed
-// present in the jar, so a present->absent transition (an external clear) is
-// detected exactly once instead of re-firing on every subsequent read.
 let mirror: string | null = null;
 let cookieBacked = false;
 
-// External-rotation observer, registered by the store-handle wiring (so a
-// sibling tab's rotation or a server Set-Cookie marks the history cache stale).
-// Null until registered; self-rotations never call it.
 let externalRotationObserver: ((value: string) => void) | null = null;
 
 /**
@@ -81,7 +71,6 @@ function readCookie(name: string): CookieRead {
   } catch {
     return { readable: false, value: null };
   }
-  // Shared parser with the server seat so both read the same jar entry.
   return { readable: true, value: getRawCookieValue(raw, name) };
 }
 
@@ -91,14 +80,9 @@ function writeCookie(name: string, value: string): void {
     typeof location !== "undefined" && location.protocol === "https:";
   try {
     document.cookie = serializeStateCookie(name, value, secure);
-  } catch {
-    // Write failures are silently absorbed; the mirror carries the value.
-  }
+  } catch {}
 }
 
-// Mint a fresh value: same version, a timestamp strictly greater than the
-// current one (the in-memory mirror is the previous value). The monotonic guard
-// lives in mintStateValue, shared with the server seat.
 function mintValue(): string {
   return mintStateValue(currentVersion, mirror);
 }
@@ -195,9 +179,6 @@ export function invalidateRangoState(): void {
   writeCookie(cookieName, mirror);
 }
 
-// One-time migration: remove the legacy localStorage keys this mechanism used
-// before the cookie cutover. No value porting — a fresh cookie mint just misses
-// cleanly. Idempotent: scans for `rango-state` and `rango-state:{routerId}`.
 function cleanupLegacyStorage(): void {
   if (typeof localStorage === "undefined") return;
   try {
@@ -209,7 +190,5 @@ function cleanupLegacyStorage(): void {
       }
     }
     for (const key of toRemove) localStorage.removeItem(key);
-  } catch {
-    // localStorage unavailable; nothing to clean.
-  }
+  } catch {}
 }

package/src/browser/react/Link.tsx

@@ -39,8 +39,6 @@ import {
   unobserveForPrefetch,
 } from "../prefetch/observer.js";
 
-// Touch device detection for adaptive strategy.
-// Checked once at module load (Link.tsx is "use client", runs only in browser).
 const isTouchDevice =
   typeof window !== "undefined" && window.matchMedia("(hover: none)").matches;
 

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 { debugLog } from "../logging.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -70,7 +71,7 @@ async function processHandles(
     // This prevents handle data from cancelled navigations polluting
     // the current route's breadcrumbs (e.g., quick popstate after clicking a link).
     if (historyKey !== store.getHistoryKey()) {
-      console.log(
+      debugLog(
         "[NavigationProvider] Stopping handle processing - user navigated away",
       );
       return;

package/src/browser/react/ScrollRestoration.tsx

@@ -14,17 +14,21 @@ export interface ScrollRestorationProps {
    * Return location.pathname to restore scroll based on path
    * (useful for keeping scroll position on the same page).
    *
+   * Provide a stable reference: a module-level function or one wrapped in
+   * useCallback. The init effect re-runs when getKey's identity changes, and
+   * teardown clears in-memory scroll positions — a fresh inline arrow on every
+   * parent render would discard unpersisted positions mid-session.
+   *
    * @example
    * ```tsx
+   * // Stable module-level getKey (recommended)
+   * const byPathname = (location) => location.pathname;
+   *
    * // Restore based on pathname (same URL = same scroll)
-   * <ScrollRestoration
-   *   getKey={(location) => location.pathname}
-   * />
+   * <ScrollRestoration getKey={byPathname} />
    *
    * // Restore based on unique history entry (default)
-   * <ScrollRestoration
-   *   getKey={(location) => location.key}
-   * />
+   * // <ScrollRestoration /> — omit getKey to use location.key
    * ```
    */
   getKey?: (location: {

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

@@ -46,8 +46,6 @@ export function filterSegmentOrder(matched: string[]): string[] {
     const slots = slotsByParent.get(id);
     if (slots) result.push(...slots);
   }
-  // Defensive: any slot whose parent is missing from the filtered list still
-  // gets included rather than silently dropped. Shouldn't happen in practice.
   for (const [parent, slots] of slotsByParent) {
     if (!nonSlotSet.has(parent)) result.push(...slots);
   }