@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.140

package/src/client/rsc-fetch.ts

@@ -20,10 +20,18 @@ import type { RouterDeps } from './router';
 /** Result of fetching an RSC payload — includes head elements and segment metadata. */
 export interface FetchResult {
   payload: unknown;
+  /**
+   * Promise that settles when the RSC decode completes or fails.
+   * The payload thenable is NOT awaited before returning (for streaming),
+   * so callers must monitor this to catch async decode errors
+   * (truncated streams, Flight parse failures) that would otherwise
+   * become unhandled rejections.
+   */
+  decodePromise: Promise<void> | null;
   headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
+  /** Route params from X-Timber-Params header for populating useSegmentParams(). */
   params: Record<string, string | string[]> | null;
   /** Segment paths that were skipped by the server (for client-side merging). */
   skippedSegments: string[] | null;
@@ -58,6 +66,43 @@ function appendRscParam(url: string): string {
   return `${url}${separator}_rsc=${generateCacheBustId()}`;
 }
 
+// ─── Deployment ID ───────────────────────────────────────────────
+
+/**
+ * The client's deployment ID, set at bootstrap from the runtime config.
+ * Sent with every RSC/action request for version skew detection.
+ * Null in dev mode. See TIM-446.
+ */
+let clientDeploymentId: string | null = null;
+
+/** Set the client deployment ID. Called once at bootstrap. */
+export function setClientDeploymentId(id: string | null): void {
+  clientDeploymentId = id;
+}
+
+/** Get the client deployment ID. */
+export function getClientDeploymentId(): string | null {
+  return clientDeploymentId;
+}
+
+// ─── Reload Signal ───────────────────────────────────────────────
+
+/** Header name used by the server to signal a version skew reload. */
+export const RELOAD_HEADER = 'X-Timber-Reload';
+
+/** Header name for the client's deployment ID. */
+export const DEPLOYMENT_ID_HEADER = 'X-Timber-Deployment-Id';
+
+/**
+ * Check if a response signals a version skew reload.
+ * Triggers a full page reload if the server indicates the client is stale.
+ */
+export function checkReloadSignal(response: Response): boolean {
+  return response.headers.get(RELOAD_HEADER) === '1';
+}
+
+// ─── Header Builder ──────────────────────────────────────────────
+
 export function buildRscHeaders(
   stateTree: { segments: string[] } | undefined,
   currentUrl?: string
@@ -75,11 +120,29 @@ export function buildRscHeaders(
   if (currentUrl) {
     headers['X-Timber-URL'] = currentUrl;
   }
+  // Send deployment ID for version skew detection (TIM-446).
+  // The server compares this against the current build's ID.
+  // On mismatch, the server signals a reload instead of returning
+  // an RSC payload with mismatched module references.
+  if (clientDeploymentId) {
+    headers[DEPLOYMENT_ID_HEADER] = clientDeploymentId;
+  }
   return headers;
 }
 
 // ─── Response Header Extraction ──────────────────────────────────
 
+/** Dev-only warning for malformed framework headers. Tree-shaken in production. */
+function warnMalformedHeader(headerName: string, raw: string): void {
+  if (process.env.NODE_ENV !== 'production') {
+    const preview = raw.length > 200 ? raw.slice(0, 200) + '…' : raw;
+    console.warn(
+      `[timber] Malformed ${headerName} header \u2014 JSON.parse failed. ` +
+        `This indicates a framework bug or header corruption. Raw (first 200 chars): ${preview}`
+    );
+  }
+}
+
 /**
  * Extract head elements from the X-Timber-Head response header.
  * Returns null if the header is missing or malformed.
@@ -90,6 +153,7 @@ export function extractHeadElements(response: Response): HeadElement[] | null {
   try {
     return JSON.parse(decodeURIComponent(header));
   } catch {
+    warnMalformedHeader('X-Timber-Head', header);
     return null;
   }
 }
@@ -108,6 +172,7 @@ export function extractSegmentInfo(response: Response): SegmentInfo[] | null {
   try {
     return JSON.parse(header);
   } catch {
+    warnMalformedHeader('X-Timber-Segments', header);
     return null;
   }
 }
@@ -127,6 +192,7 @@ export function extractSkippedSegments(response: Response): string[] | null {
     const parsed = JSON.parse(header);
     return Array.isArray(parsed) ? parsed : null;
   } catch {
+    warnMalformedHeader('X-Timber-Skipped-Segments', header);
     return null;
   }
 }
@@ -135,7 +201,7 @@ export function extractSkippedSegments(response: Response): string[] | null {
  * Extract route params from the X-Timber-Params response header.
  * Returns null if the header is missing or malformed.
  *
- * Used to populate useParams() after client-side navigation.
+ * Used to populate useSegmentParams() after client-side navigation.
  */
 export function extractParams(response: Response): Record<string, string | string[]> | null {
   const header = response.headers.get('X-Timber-Params');
@@ -143,6 +209,7 @@ export function extractParams(response: Response): Record<string, string | strin
   try {
     return JSON.parse(header);
   } catch {
+    warnMalformedHeader('X-Timber-Params', header);
     return null;
   }
 }
@@ -161,6 +228,84 @@ export class RedirectError extends Error {
   }
 }
 
+/**
+ * Thrown when the server signals a version skew (X-Timber-Reload header).
+ * Caught in navigate() to trigger a full page reload via triggerStaleReload().
+ * See TIM-446.
+ */
+export class VersionSkewError extends Error {
+  constructor() {
+    super('Version skew detected — server has been redeployed');
+  }
+}
+
+/**
+ * Thrown when the server returns an error for an RSC payload request.
+ * The server sends X-Timber-Error header and a JSON body instead of a
+ * broken RSC stream for any RenderError (4xx or 5xx). Caught in
+ * navigate() to trigger a hard navigation so the server can render
+ * the error page as HTML.
+ *
+ * See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+ */
+export class ServerErrorResponse extends Error {
+  readonly status: number;
+  readonly url: string;
+  constructor(status: number, url: string) {
+    super(`Server error ${status} during navigation to ${url}`);
+    this.status = status;
+    this.url = url;
+  }
+}
+
+// ─── Stream Completion Tracking ───────────────────────────────────
+
+/**
+ * Wrap a response body stream to track when it's fully consumed.
+ * Returns a new body that passes all chunks through unchanged, plus
+ * a `done` promise that resolves when the last chunk is read (or
+ * rejects if the stream errors).
+ *
+ * Used to keep React transitions open for the full RSC stream
+ * duration — createFromFetch's thenable resolves on shell arrival,
+ * but we need stream completion for useOptimistic pending state.
+ */
+function trackStreamCompletion(body: ReadableStream<Uint8Array>): {
+  body: ReadableStream<Uint8Array>;
+  done: Promise<void>;
+} {
+  let resolveDone!: () => void;
+  let rejectDone!: (e: unknown) => void;
+  const done = new Promise<void>((res, rej) => {
+    resolveDone = res;
+    rejectDone = rej;
+  });
+
+  const reader = body.getReader();
+  const tracked = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await reader.read();
+        if (result.done) {
+          controller.close();
+          resolveDone();
+        } else {
+          controller.enqueue(result.value);
+        }
+      } catch (error) {
+        controller.error(error);
+        rejectDone(error);
+      }
+    },
+    cancel(reason) {
+      reader.cancel(reason);
+      resolveDone();
+    },
+  });
+
+  return { body: tracked, done };
+}
+
 // ─── Fetch ───────────────────────────────────────────────────────
 
 /**
@@ -175,7 +320,8 @@ export async function fetchRscPayload(
   url: string,
   deps: RouterDeps,
   stateTree?: { segments: string[] },
-  currentUrl?: string
+  currentUrl?: string,
+  signal?: AbortSignal
 ): Promise<FetchResult> {
   const rscUrl = appendRscParam(url);
   const headers = buildRscHeaders(stateTree, currentUrl);
@@ -186,12 +332,23 @@ export async function fetchRscPayload(
     //
     // Intercept the response to read X-Timber-Head before createFromFetch
     // consumes the body. Reading headers does NOT consume the body stream.
-    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual' });
+    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
     let headElements: HeadElement[] | null = null;
     let segmentInfo: SegmentInfo[] | null = null;
     let params: Record<string, string | string[]> | null = null;
     let skippedSegments: string[] | null = null;
+    // Track when the full RSC body stream is consumed (not just shell).
+    // Initialized to resolved for bodyless responses; overwritten when
+    // the response has a body.
+    let streamDone: Promise<void> = Promise.resolve();
+
     const wrappedPromise = fetchPromise.then((response) => {
+      // Version skew detection (TIM-446): if the server signals a reload,
+      // throw VersionSkewError so the caller (router navigate) can trigger
+      // a full page reload via triggerStaleReload().
+      if (checkReloadSignal(response)) {
+        throw new VersionSkewError();
+      }
       // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
       // for RSC payload requests instead of a raw 302, because fetch with
       // redirect: "manual" turns 302s into opaque redirects (status 0, null body)
@@ -202,21 +359,61 @@ export async function fetchRscPayload(
       if (redirectLocation) {
         throw new RedirectError(redirectLocation);
       }
+      // Detect server error responses. The server returns X-Timber-Error header
+      // with a JSON body instead of a broken RSC stream for any RenderError
+      // (4xx or 5xx). Hard-navigate so the server renders the error page as HTML.
+      // See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+      if (response.headers.get('X-Timber-Error') === '1') {
+        throw new ServerErrorResponse(response.status, url);
+      }
       headElements = extractHeadElements(response);
       segmentInfo = extractSegmentInfo(response);
       params = extractParams(response);
       skippedSegments = extractSkippedSegments(response);
+
+      // Wrap the body to track full stream consumption. createFromFetch's
+      // thenable resolves when the root model (shell) arrives, but we need
+      // to know when ALL chunks are read so the React transition stays
+      // open for the full streaming duration (keeps useOptimistic alive).
+      if (response.body) {
+        const tracked = trackStreamCompletion(response.body);
+        streamDone = tracked.done;
+        streamDone.catch(() => {}); // prevent unhandled rejection
+        return new Response(tracked.body, {
+          headers: response.headers,
+          status: response.status,
+        });
+      }
       return response;
     });
-    // Await so headElements/segmentInfo/params are populated before we return.
-    // Also await the decoded payload — createFromFetch returns a thenable
-    // that resolves to the React element tree.
+    // Await headers so headElements/segmentInfo/params are populated.
     await wrappedPromise;
-    const payload = await deps.decodeRsc(wrappedPromise);
-    return { payload, headElements, segmentInfo, params, skippedSegments };
+    // Start decoding but do NOT await — return the in-progress thenable.
+    // React can render a Flight thenable directly: it suspends on unresolved
+    // parts and progressively renders as chunks arrive, spreading work across
+    // frames instead of blocking the main thread in one burst.
+    const payload = deps.decodeRsc(wrappedPromise);
+    // Combine stream completion with payload error propagation.
+    // streamDone keeps the transition open for the full RSC stream
+    // duration (useOptimistic pending state). payloadError propagates
+    // decode failures (stale client references, Flight parse errors)
+    // so the router's catch block can trigger recovery (stale reload).
+    const payloadError = new Promise<void>((_, reject) => {
+      Promise.resolve(payload).then(() => {}, reject);
+    });
+    payloadError.catch(() => {});
+    const decodePromise = Promise.race([streamDone, payloadError]);
+    return {
+      payload,
+      decodePromise,
+      headElements,
+      segmentInfo,
+      params,
+      skippedSegments,
+    };
   }
   // Test/fallback path: return raw text
-  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual' });
+  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
   // Check for redirect in test path too
   if (response.status >= 300 && response.status < 400) {
     const location = response.headers.get('Location');
@@ -226,6 +423,7 @@ export async function fetchRscPayload(
   }
   return {
     payload: await response.text(),
+    decodePromise: null,
     headElements: extractHeadElements(response),
     segmentInfo: extractSegmentInfo(response),
     params: extractParams(response),

package/src/client/segment-cache.ts

@@ -11,7 +11,7 @@ export interface PrefetchResult {
   headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo?: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
+  /** Route params from X-Timber-Params header for populating useSegmentParams(). */
   params?: Record<string, string | string[]> | null;
   /** Segment paths skipped by the server (for client-side merging). */
   skippedSegments?: string[] | null;
@@ -111,6 +111,8 @@ function collectSyncSegments(
  */
 export interface SegmentInfo {
   path: string;
+  /** Outlet key — includes route group name when applicable (e.g., "/(marketing)"). */
+  segmentId?: string;
   isAsync: boolean;
 }
 
@@ -137,8 +139,9 @@ export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefin
   let parent: SegmentNode | undefined;
 
   for (const info of layouts) {
+    const id = info.segmentId ?? info.path;
     const node: SegmentNode = {
-      segment: info.path,
+      segment: id,
       payload: null,
       isAsync: info.isAsync,
       children: new Map(),
@@ -149,7 +152,7 @@ export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefin
     }
 
     if (parent) {
-      parent.children.set(info.path, node);
+      parent.children.set(id, node);
     }
 
     parent = node;

package/src/client/segment-outlet.tsx

@@ -0,0 +1,77 @@
+/**
+ * SegmentOutlet — client component boundary at each layout segment.
+ *
+ * Each layout in the segment tree is wrapped with a SegmentOutlet that:
+ * 1. Knows its segment path (prop from the server)
+ * 2. Reads from SegmentUpdateContext for partial navigation updates
+ * 3. Caches its rendered content in a ref across navigations
+ *
+ * On full navigation: receives new children via props, caches and renders them.
+ * On partial navigation (this segment skipped): the context map has no entry
+ * for this path, so the outlet returns cached content — preserving layout state.
+ * On partial navigation (this segment updated): the context map has content
+ * for this path, so the outlet renders the update.
+ *
+ * Uses React context instead of useSyncExternalStore to stay compatible
+ * with concurrent rendering (transitions). All outlets re-render when the
+ * context value changes, but each bails out quickly if its segment has
+ * no update — same approach as Next.js LayoutRouter.
+ *
+ * Security: performance optimization only. The server always runs all
+ * access.ts files regardless of segment skipping.
+ * See design/13-security.md §"State tree manipulation".
+ */
+
+'use client';
+
+import { useContext, useRef, type ReactNode } from 'react';
+import { SegmentUpdateContext } from './segment-update-context.js';
+
+export interface SegmentOutletProps {
+  /**
+   * Unique identifier for this segment. For normal segments this is the
+   * urlPath (e.g., "/", "/dashboard"). For route groups this includes the
+   * group name (e.g., "/(marketing)") to distinguish siblings that share
+   * the same urlPath. Must match the segmentId used in state-tree-diff.ts.
+   */
+  segmentPath: string;
+
+  /** The segment's React subtree (layout + inner content). */
+  children: ReactNode;
+}
+
+/**
+ * Client component boundary at each layout segment in the element tree.
+ *
+ * On full navigation (context map is empty): renders children, caches in ref.
+ * On partial navigation: checks the context map for an update at segmentPath.
+ *   - Update found → renders update, caches in ref.
+ *   - No update → returns cached content (layout state preserved).
+ *
+ * React preserves component instances across reactRoot.render() calls
+ * when the same type appears at the same tree position. The ref persists
+ * across navigations because SegmentOutlet is reconciled, not remounted.
+ */
+export function SegmentOutlet({ segmentPath, children }: SegmentOutletProps) {
+  const updates = useContext(SegmentUpdateContext);
+  const contentRef = useRef<ReactNode>(null);
+
+  const update = updates.get(segmentPath);
+
+  if (update !== undefined) {
+    contentRef.current = update;
+    return update;
+  }
+
+  if (contentRef.current === null) {
+    contentRef.current = children;
+    return children;
+  }
+
+  if (children !== contentRef.current) {
+    contentRef.current = children;
+    return children;
+  }
+
+  return contentRef.current;
+}

package/src/client/segment-update-context.ts

@@ -0,0 +1,42 @@
+/**
+ * SegmentUpdateContext — React context for partial navigation updates.
+ *
+ * During partial navigation (server skips unchanged sync layouts), the
+ * router builds a Map of segment path → ReactNode updates and passes it
+ * as the context value. Mounted SegmentOutlet components read from this
+ * context to decide whether to render the update or their cached content.
+ *
+ * SINGLETON GUARANTEE: Uses globalThis + Symbol.for — same pattern as
+ * NavigationContext. The RSC client bundler can duplicate this module
+ * across chunks (browser-entry graph + client-reference graph). With
+ * ESM output, each chunk gets its own module scope — a bare createContext
+ * at module level would create separate instances per chunk. globalThis
+ * guarantees a single instance regardless of duplication.
+ *
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+ */
+
+'use client';
+
+import React, { type ReactNode } from 'react';
+
+export const EMPTY_SEGMENT_UPDATES = new Map<string, ReactNode>();
+
+const CTX_KEY = Symbol.for('__timber_segment_update_ctx');
+
+function getOrCreateContext(): React.Context<Map<string, ReactNode>> {
+  const existing = (globalThis as Record<symbol, unknown>)[CTX_KEY] as
+    | React.Context<Map<string, ReactNode>>
+    | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext === 'function') {
+    const ctx = React.createContext<Map<string, ReactNode>>(EMPTY_SEGMENT_UPDATES);
+    (globalThis as Record<symbol, unknown>)[CTX_KEY] = ctx;
+    return ctx;
+  }
+  // RSC environment — createContext not available. Return a dummy that
+  // won't be used (outlets only render on the client).
+  return undefined as unknown as React.Context<Map<string, ReactNode>>;
+}
+
+export const SegmentUpdateContext = getOrCreateContext();

package/src/client/shallow-url.ts

@@ -0,0 +1,22 @@
+/**
+ * Shallow URL replacement — update the browser URL bar without triggering
+ * RSC navigation, TopLoader, or any server round-trip.
+ *
+ * Uses the Navigation API's `info: { shallow: true }` when available (Chrome),
+ * which the navigate event handler intercepts with a no-op handler. Falls back
+ * to raw `history.replaceState` (Safari/Firefox — no navigate event fired).
+ */
+
+import { getNavigationApi } from './navigation-api.js';
+
+export function replaceUrl(url: string): void {
+  const nav = getNavigationApi();
+  if (nav) {
+    nav.navigate(url, {
+      history: 'replace',
+      info: { shallow: true },
+    });
+  } else {
+    history.replaceState(history.state, '', url);
+  }
+}

package/src/client/ssr-data.ts

@@ -41,12 +41,20 @@ export interface SsrData {
   /** The request's route params (e.g. { id: '123' }) */
   params: Record<string, string | string[]>;
   /**
-   * Mutable reference to NavContext for error boundary → RSC communication.
-   * When TimberErrorBoundary catches a DenySignal, it sets
-   * `_navContext._denyHandledByBoundary = true` to prevent the RSC entry
-   * from promoting the denial to page-level. See LOCAL-298.
+   * Mutable reference to NavContext for error boundary → pipeline communication.
+   *
+   * When TimberErrorBoundary catches a DenySignal during SSR, it:
+   * 1. Sets `statusCode` to the deny status (e.g., 403) — so the HTTP
+   *    Response has the correct status code without a re-render.
+   * 2. Sets `_denyHandledByBoundary = true` — so the pipeline skips
+   *    the redundant renderDenyPage() re-render.
+   *
+   * This runs synchronously during Fizz rendering, BEFORE onShellReady,
+   * so the status code is committed before any bytes are sent.
+   *
+   * See TIM-664, design/04-authorization.md §"React.cache Scope in Deny/Error Re-renders"
    */
-  _navContext?: { _denyHandledByBoundary?: boolean };
+  _navContext?: { statusCode?: number; _denyHandledByBoundary?: boolean };
 }
 
 // ─── ALS-Backed Provider ─────────────────────────────────────────

package/src/client/stale-reload.ts

@@ -16,6 +16,16 @@
 
 const RELOAD_FLAG_KEY = '__timber_stale_reload';
 
+/**
+ * In-memory fallback counter for environments where sessionStorage is
+ * unavailable (private browsing, storage full, extension interference).
+ * Incremented each time triggerStaleReload() falls into the catch path.
+ * If the counter exceeds 0 on a subsequent call, the reload is suppressed
+ * to prevent an infinite loop. Resets naturally on page load (module
+ * re-evaluates) and can be manually reset via clearStaleReloadFlag().
+ */
+let memoryReloadCount = 0;
+
 /**
  * Check if an error is a stale client reference error from React's
  * Flight client. These errors have the message pattern:
@@ -32,6 +42,34 @@ export function isStaleClientReference(error: unknown): boolean {
   return msg.includes('Could not find the module') || msg.includes('client reference not found');
 }
 
+/**
+ * Check if an error is a chunk load failure from a dynamic import.
+ *
+ * After a deployment, old chunk filenames no longer exist. When the client
+ * tries to dynamically import a chunk that's been replaced, the browser
+ * throws one of these errors:
+ *
+ * - Chromium: "Failed to fetch dynamically imported module: <url>"
+ * - Firefox: "error loading dynamically imported module: <url>"
+ * - Safari: "Importing a module script failed."
+ * - Vite/Rollup: "Unable to preload CSS for <url>"
+ *
+ * See TIM-446
+ */
+export function isChunkLoadError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const msg = error.message.toLowerCase();
+  return (
+    msg.includes('failed to fetch dynamically imported module') ||
+    msg.includes('error loading dynamically imported module') ||
+    msg.includes('importing a module script failed') ||
+    msg.includes('unable to preload css') ||
+    // Webpack-style chunk load errors (unlikely in Vite but defensive)
+    msg.includes('loading chunk') ||
+    msg.includes('loading css chunk')
+  );
+}
+
 /**
  * Trigger a full page reload to pick up new bundles.
  *
@@ -65,9 +103,33 @@ export function triggerStaleReload(): boolean {
     window.location.reload();
     return true;
   } catch {
-    // sessionStorage may be unavailable (private browsing, storage full, etc.)
-    // Fall back to reloading without loop protection
-    console.warn('[timber] Stale client reference detected. Reloading page.');
+    // sessionStorage unavailable (private browsing, storage full, etc.)
+    // Use document.cookie as a reload-persistent fallback loop guard.
+    // Module-level memoryReloadCount resets on every reload, so it can't
+    // detect cross-reload loops. Cookies persist across reloads and are
+    // available even when sessionStorage is blocked (TIM-576).
+    const cookieFlag = document.cookie.includes(RELOAD_FLAG_KEY + '=1');
+    if (cookieFlag || memoryReloadCount > 0) {
+      console.warn(
+        '[timber] Stale client reference detected again after reload. ' +
+          'Not reloading to prevent infinite loop. ' +
+          'This may indicate a deployment issue — try a hard refresh.'
+      );
+      return false;
+    }
+
+    memoryReloadCount++;
+    // Set a short-lived cookie (60s) as the persistent loop guard.
+    // It auto-expires so it won't block future legitimate reloads.
+    try {
+      document.cookie = `${RELOAD_FLAG_KEY}=1; max-age=60; path=/; SameSite=Lax`;
+    } catch {
+      // Cookie API unavailable — proceed anyway, memoryReloadCount guards same-page loops
+    }
+    console.warn(
+      '[timber] Stale client reference detected — the server has been ' +
+        'redeployed with new bundles. Reloading to pick up the new version.'
+    );
     window.location.reload();
     return true;
   }
@@ -79,9 +141,16 @@ export function triggerStaleReload(): boolean {
  * reference error should trigger a fresh reload attempt.
  */
 export function clearStaleReloadFlag(): void {
+  memoryReloadCount = 0;
   try {
     sessionStorage.removeItem(RELOAD_FLAG_KEY);
   } catch {
     // sessionStorage unavailable — nothing to clear
   }
+  // Also clear the cookie fallback
+  try {
+    document.cookie = `${RELOAD_FLAG_KEY}=; max-age=0; path=/; SameSite=Lax`;
+  } catch {
+    // Cookie API unavailable
+  }
 }

package/src/client/state.ts

@@ -3,7 +3,7 @@
  *
  * ALL mutable module-level state that must have singleton semantics across
  * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,
- * use-params.ts, use-search-params.ts, unload-guard.ts) import from this file
+ * use-segment-params.ts, use-search-params.ts, unload-guard.ts) import from this file
  * and re-export thin wrapper functions.
  *
  * Why: In Vite dev, a module is instantiated separately if reached via different
@@ -50,7 +50,7 @@ export function _setCurrentSsrData(data: SsrData | undefined): void {
   currentSsrData = data;
 }
 
-// ─── Route Params (from use-params.ts) ──────────────────────────────────────
+// ─── Route Params (from use-segment-params.ts) ──────────────────────────────────────
 
 /** Current route params snapshot — replaced (not mutated) on each navigation. */
 export let currentParams: Record<string, string | string[]> = {};