@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.186

package/src/client/segment-cache.ts

@@ -1,15 +1,29 @@
 // Segment Cache — stores the mounted segment tree and prefetched payloads
 // See design/19-client-navigation.md for architecture details.
 
+import type { PublishedParams } from '../shared/payload-root.js';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.js';
+
 // ─── Types ───────────────────────────────────────────────────────
 
 /** A prefetched RSC result with optional segment metadata. */
 export interface PrefetchResult {
   payload: unknown;
+  /**
+   * Completion of the full Flight stream, when the prefetch is still decoding.
+   * Carried through to the navigation that consumes the entry so a decode
+   * failure reaches *that* navigation's recovery rather than dying with the
+   * prefetch (TIM-1275).
+   */
+  decodePromise?: Promise<void> | 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 useSegmentParams(). */
-  params?: Record<string, string | string[]> | null;
+  /**
+   * The params published beside `payload`, split off the same payload root.
+   * Carried so a consumed prefetch publishes the params of the tree it is
+   * about to render, and not the ones already on screen.
+   */
+  params?: PublishedParams | Promise<PublishedParams>;
   /** Segment paths skipped by the server (for client-side merging). */
   skippedSegments?: string[] | null;
 }
@@ -21,6 +35,11 @@ export interface PrefetchResult {
 export interface SegmentNode {
   /** The segment's URL pattern (e.g., "/", "/dashboard", "/projects/[id]") */
   segment: string;
+  /**
+   * The segment's `app/` directory path, groups included (e.g. `/(browse)/feed`).
+   * Undefined for slot nodes and for servers that predate the field.
+   */
+  treePath?: string;
   /** The RSC flight payload for this segment (opaque to the cache) */
   payload: unknown;
   /**
@@ -39,15 +58,6 @@ export interface SegmentNode {
   denied?: boolean;
 }
 
-/**
- * Serialized state tree sent via X-Timber-State-Tree header.
- * Only sync segments are included — async segments always re-render.
- */
-export interface StateTree {
-  segments: string[];
-  slots?: string[];
-}
-
 // ─── Segment Cache ───────────────────────────────────────────────
 
 /**
@@ -85,20 +95,32 @@ export class SegmentCache {
    * client can actually merge (i.e., segments whose cached element tree
    * contains an inner SegmentProvider the merger can splice into).
    *
+   * `treePaths` is collected UNFILTERED, unlike `segments` and `slots`. Those
+   * two answer "what may the server skip re-rendering?", so every reason a
+   * segment cannot be reused is a reason to leave it out. `treePaths` answers
+   * "what is mounted right now?" for interception scoping — a request-dependent
+   * layout is still on screen, and dropping it would silently narrow the scope
+   * the server sees and cancel a modal that should open (TIM-1282).
+   *
    * This is a performance optimization only, NOT a security boundary.
    * The server always runs all access.ts files regardless of the state tree.
    */
   serializeStateTree(mergeableFilter?: Set<string>): StateTree {
     const segments: string[] = [];
     const slots: string[] = [];
+    const treePaths: string[] = [];
     if (this.root) {
       collectSyncSegments(this.root, segments, mergeableFilter);
       collectSyncSlots(this.root, slots);
+      collectTreePaths(this.root, treePaths);
     }
     const tree: StateTree = { segments };
     if (slots.length > 0) {
       tree.slots = slots;
     }
+    if (treePaths.length > 0) {
+      tree.treePaths = treePaths;
+    }
     return tree;
   }
 }
@@ -117,6 +139,20 @@ function collectSyncSegments(
   }
 }
 
+/**
+ * Recursively collect the `app/` directory path of every mounted segment.
+ *
+ * Slots are not walked: a slot's own sub-tree can never own an intercepting
+ * slot's scope, because scopes are always ordinary segments (`interception.ts`
+ * derives one from the slot owner's ancestor chain).
+ */
+function collectTreePaths(node: SegmentNode, out: string[]): void {
+  if (node.treePath) out.push(node.treePath);
+  for (const child of node.children.values()) {
+    collectTreePaths(child, out);
+  }
+}
+
 /** Recursively collect cacheable slot paths from the tree */
 function collectSyncSlots(node: SegmentNode, out: string[]): void {
   if (node.slots) {
@@ -135,25 +171,6 @@ function collectSyncSlots(node: SegmentNode, out: string[]): void {
 
 // ─── Segment Tree Builder ────────────────────────────────────────
 
-/**
- * Segment metadata from the server, sent via X-Timber-Segments header.
- * Describes a rendered segment's path and whether it's async.
- */
-export interface SegmentInfo {
-  path: string;
-  /** Outlet key — includes route group name when applicable (e.g., "/(marketing)"). */
-  segmentId?: string;
-  isRequestDependent: boolean;
-  /** True for parallel route slot entries. Slots are keyed by their slot path (e.g., "/@sidebar"). */
-  slot?: boolean;
-  /** Parent segment path for slot entries. Used to attach the slot to the correct SegmentNode. */
-  parentSegment?: string;
-  /** True when the slot's access.ts denied on this render. Denied slots are excluded from the state tree. */
-  denied?: boolean;
-  /** True when the slot was skipped (cached content reused). Payloads with skipped slots are not replayable. */
-  skipped?: boolean;
-}
-
 /**
  * Build a SegmentNode tree from flat segment metadata.
  *
@@ -190,6 +207,7 @@ export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefin
     const id = info.segmentId ?? info.path;
     const node: SegmentNode = {
       segment: id,
+      treePath: info.treePath,
       payload: null,
       isRequestDependent: info.isRequestDependent,
       children: new Map(),
@@ -242,6 +260,58 @@ interface PrefetchEntry {
 /** Sentinel value for negative cache entries (URL is not a route). */
 const NEGATIVE_ENTRY: PrefetchResult = Object.freeze({ payload: null });
 
+/**
+ * Identifies a prefetched payload. A payload is addressed by *every* input that
+ * changes the server's answer, not by the destination alone.
+ *
+ * The server's answer for a destination depends on where the request came
+ * from — that is the whole mechanism behind intercepting routes, and it also
+ * drives slot-skip resolution. A prefetch issued from `/gallery` is a modal
+ * payload; the same URL prefetched from `/` is the full page. Keying on the
+ * destination alone let the first click after a hover be answered with
+ * whichever variant happened to be fetched (TIM-1265).
+ *
+ * `from` alone stopped being enough in TIM-1282. It is a pathname, and once
+ * interception scope comes from the rendered tree rather than the address, one
+ * pathname no longer names one source tree: `/photo/1` is the address both for
+ * a modal open over `(browse)` and for `(landing)`'s canonical page. A key
+ * without the scope hands the modal payload to the canonical page's click,
+ * which renders it without the server's scope check ever running.
+ *
+ * The two reads happen at different instants — `scope` is sampled at hover and
+ * again at click — which is why a tree that changed in between produces a
+ * *miss* and a refetch rather than a wrong hit.
+ */
+export interface PrefetchKey {
+  /** Destination URL — hash-less `pathname + search`, as navigate() fetches it. */
+  url: string;
+  /** Departing pathname — the `X-Timber-URL` the prefetch was issued with. */
+  from: string;
+  /**
+   * The rendered scope the prefetch was issued with — the `treePaths` half of
+   * `X-Timber-State-Tree`, joined. Empty when none crossed.
+   */
+  scope: string;
+}
+
+/**
+ * Compose the map key. Length-prefixed rather than delimiter-joined for the
+ * same reason `shared/rsc-cache-key.ts` is: any delimiter is forgeable by a
+ * value containing it, and a URL may contain any character a delimiter could.
+ */
+function prefetchMapKey(key: PrefetchKey): string {
+  return `${key.from.length}:${key.from}:${key.scope.length}:${key.scope}:${key.url}`;
+}
+
+/**
+ * The `scope` half of a `PrefetchKey`, derived from the state tree that will
+ * actually be sent. Taking it from the header value rather than re-walking the
+ * cache is the point: the key varies by exactly what the request varies by.
+ */
+export function prefetchScopeOf(stateTree: StateTree | undefined): string {
+  return stateTree?.treePaths?.join('\u0000') ?? '';
+}
+
 /**
  * Short-lived cache for hover-triggered prefetches. Entries expire after
  * 30 seconds. When a link is clicked, the prefetched payload is consumed
@@ -254,40 +324,47 @@ export class PrefetchCache {
   private static readonly TTL_MS = 30_000;
   private entries = new Map<string, PrefetchEntry>();
 
-  set(url: string, result: PrefetchResult): void {
-    this.entries.set(url, {
+  set(key: PrefetchKey, result: PrefetchResult): void {
+    this.entries.set(prefetchMapKey(key), {
       result,
       expiresAt: Date.now() + PrefetchCache.TTL_MS,
     });
   }
 
-  get(url: string): PrefetchResult | undefined {
-    const entry = this.entries.get(url);
+  get(key: PrefetchKey): PrefetchResult | undefined {
+    const mapKey = prefetchMapKey(key);
+    const entry = this.entries.get(mapKey);
     if (!entry) return undefined;
     if (Date.now() >= entry.expiresAt) {
-      this.entries.delete(url);
+      this.entries.delete(mapKey);
       return undefined;
     }
     return entry.result;
   }
 
   /** Get and remove the entry (used when navigation consumes a prefetch) */
-  consume(url: string): PrefetchResult | undefined {
-    const result = this.get(url);
+  consume(key: PrefetchKey): PrefetchResult | undefined {
+    const result = this.get(key);
     if (result !== undefined) {
-      this.entries.delete(url);
+      this.entries.delete(prefetchMapKey(key));
     }
     return result;
   }
 
-  /** Store a negative entry — the URL is not a route (non-RSC Content-Type). */
-  setNegative(url: string): void {
-    this.set(url, NEGATIVE_ENTRY);
+  /**
+   * Store a negative entry — the URL is not a route (non-RSC Content-Type).
+   *
+   * Keyed like every other entry even though "not a route" does not actually
+   * vary by departing URL: a source-independent negative would be a second
+   * keying rule to keep correct, and the only cost of the uniform one is a
+   * repeated fetch for a link hovered from a second page.
+   */
+  setNegative(key: PrefetchKey): void {
+    this.set(key, NEGATIVE_ENTRY);
   }
 
   /** Check if the entry is a negative cache entry (URL is not a route). */
-  isNegative(url: string): boolean {
-    const entry = this.get(url);
-    return entry === NEGATIVE_ENTRY;
+  isNegative(key: PrefetchKey): boolean {
+    return this.get(key) === NEGATIVE_ENTRY;
   }
 }

package/src/client/ssr-data.ts

@@ -28,6 +28,7 @@ import {
   _setSsrDataProvider,
   _setCurrentSsrData,
 } from './state.js';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
 
 // ─── Types ────────────────────────────────────────────────────────
 
@@ -40,6 +41,11 @@ export interface SsrData {
   cookies: Map<string, string>;
   /** The request's route params (e.g. { id: '123' }) */
   params: Record<string, string | string[]>;
+  /**
+   * Per-slot params keyed by slot tree path, absent when the request rendered
+   * no slot with params of its own (TIM-1285).
+   */
+  slotParams?: SlotParamsRecord;
   /**
    * Mutable reference to NavContext for error boundary → pipeline communication.
    *

package/src/client/stale-client.ts

@@ -0,0 +1,191 @@
+/**
+ * Stale Client — knowing when this bundle has been superseded.
+ *
+ * Layer 1 of version skew handling (see design/33-version-skew.md) is
+ * proactive: the server compares `X-Timber-Deployment-Id` against the current
+ * build and answers a stale client with `X-Timber-Reload: 1`. That covers
+ * every RSC navigation and every server action — as long as there is a server
+ * in the request path.
+ *
+ * This module is the reactive half, plus the state both halves feed. It
+ * recognizes the two error shapes a stale client produces on its own:
+ *
+ * 1. **Stale client references** — React's Flight client throws
+ *    "Could not find the module …" when an RSC payload names a client module
+ *    ID that isn't in this bundle's manifest.
+ * 2. **Chunk load failures** — a content-hashed chunk that no longer exists on
+ *    the CDN fails to `import()`. Every engine words this differently.
+ *
+ * It matters most for `output: 'static'`, where there is no server to send the
+ * reload header and this is the *only* skew detection that can run.
+ *
+ * **Nothing here reloads the page.** A stale client is recorded, not acted on;
+ * the router turns the next user-initiated navigation into a full document
+ * load. See design/33-version-skew.md §"Recovery on the next navigation" for
+ * why — a self-issued `location.reload()` cannot tell a recovery from a bounce
+ * between two live deployments, and mid-rollout it produces exactly that loop.
+ *
+ * See TIM-1260, TIM-1275.
+ */
+
+// The only import: the shared unload state. Kept minimal because this module
+// is reached from the error boundary, a `'use client'` component evaluated in
+// the SSR graph too — a dependency on the client fetch layer would drag that
+// graph along with it.
+import { isPageUnloading } from './unload-guard.js';
+
+// ─── Error Shapes ────────────────────────────────────────────────
+
+/**
+ * Substrings that identify a failed dynamic import, lowercased for
+ * case-insensitive matching. Engines and bundlers each word this
+ * differently and none of them expose a stable error code.
+ */
+const CHUNK_LOAD_PATTERNS = [
+  // Chromium
+  'failed to fetch dynamically imported module',
+  // Firefox
+  'error loading dynamically imported module',
+  // Safari
+  'importing a module script failed',
+  // Vite's preload helper, for the stylesheet of a lazily-imported chunk
+  'unable to preload css for',
+];
+
+/** Substring React's Flight client uses when a client module ID is unknown. */
+const STALE_REFERENCE_PATTERN = 'could not find the module';
+
+/**
+ * Pull a comparable message out of an unknown thrown value. Rejections cross
+ * enough boundaries (event handlers, `unhandledrejection`, Vite's preload
+ * event) that the value is not reliably an `Error`.
+ */
+function messageOf(error: unknown): string {
+  if (typeof error === 'string') return error.toLowerCase();
+  if (error instanceof Error) return error.message.toLowerCase();
+  if (error && typeof error === 'object' && 'message' in error) {
+    const message = (error as { message: unknown }).message;
+    if (typeof message === 'string') return message.toLowerCase();
+  }
+  return '';
+}
+
+/**
+ * True when the error is React's "client reference not in this manifest"
+ * failure — the payload was produced by a build this bundle doesn't match.
+ */
+export function isStaleClientReference(error: unknown): boolean {
+  return messageOf(error).includes(STALE_REFERENCE_PATTERN);
+}
+
+/**
+ * True when the error is a failed dynamic import or CSS preload — the
+ * content-hashed chunk this bundle asks for is gone from the CDN.
+ */
+export function isChunkLoadError(error: unknown): boolean {
+  if (error instanceof Error && error.name === 'ChunkLoadError') return true;
+  const message = messageOf(error);
+  return CHUNK_LOAD_PATTERNS.some((pattern) => message.includes(pattern));
+}
+
+// ─── Staleness ───────────────────────────────────────────────────
+
+/**
+ * True once this client is known to be running against a superseded
+ * deployment. One-way: a document that has gone stale cannot come back, since
+ * the only way to get fresh code is to load a new document.
+ *
+ * In-memory on purpose. Persisting it would be wrong — the next document gets
+ * whatever build the server hands it, and if that one is stale too it will
+ * find out the same way.
+ */
+let stale = false;
+
+/**
+ * True once {@link initStaleClient} has seen a deployment ID — i.e. this is a
+ * production build. False in dev, where nothing is ever stale: HMR owns code
+ * updates, and a failed dynamic import is a real error the developer needs to
+ * see rather than something a page load fixes.
+ */
+let deployed = false;
+
+/** Whether this client has been superseded by a newer deployment. */
+export function isClientStale(): boolean {
+  return stale;
+}
+
+/**
+ * Record that the origin has told us this client is stale — the `X-Timber-Reload`
+ * header on an RSC or action response. Authoritative, so it is not gated on
+ * anything: a dev server never sends the header in the first place.
+ */
+export function markClientStale(): void {
+  stale = true;
+}
+
+/**
+ * Record staleness if `error` is one of the shapes a superseded bundle
+ * produces. Returns whether it did, so a caller mid-navigation can decide to
+ * hard-navigate instead of surfacing the error.
+ *
+ * Inference, unlike {@link markClientStale}, so it is gated on being a
+ * production build. This is the single place that gate lives — call sites
+ * cannot see each other, and "remember to gate the next one too" is not a
+ * guarantee.
+ */
+export function markStaleFromError(error: unknown): boolean {
+  if (!deployed) return false;
+
+  // A document being torn down aborts its in-flight dynamic imports, and an
+  // aborted import reads exactly like a chunk the CDN has dropped. That is not
+  // evidence of staleness, and the bit outlives the teardown that produced it:
+  // a document entering the back-forward cache is frozen, not destroyed, so a
+  // false positive recorded on the way out would cost the *restored* page its
+  // client-side navigation for good. `unload-guard.ts` clears its own flag on
+  // a persisted `pageshow`; this one is one-way by design, so it has to not be
+  // set in the first place.
+  if (isPageUnloading()) return false;
+
+  if (!isStaleClientReference(error) && !isChunkLoadError(error)) return false;
+  stale = true;
+  return true;
+}
+
+// ─── Initialization ──────────────────────────────────────────────
+
+/**
+ * The underlying error Vite attaches to a `vite:preloadError` event.
+ *
+ * Narrowed at runtime rather than cast: the property is Vite's, not ours, and
+ * a shape change should fall back to matching the event itself rather than
+ * silently reading `undefined` forever.
+ */
+function preloadErrorPayload(event: Event): unknown {
+  return 'payload' in event ? (event as Event & { payload: unknown }).payload : event;
+}
+
+/**
+ * Arm the module, and register the listeners that catch stale-client errors
+ * never passing through the router: a lazily imported client component, a
+ * preloaded stylesheet, anything that rejects outside a navigation.
+ *
+ * No-op when `deploymentId` is null — that is dev. Called from the browser
+ * entry before hydration, so it precedes any render or navigation that could
+ * throw.
+ */
+export function initStaleClient(deploymentId: string | null): void {
+  if (!deploymentId) return;
+  deployed = true;
+
+  // Vite dispatches this for failed chunk/CSS preloads. Note what is *not*
+  // here: `preventDefault()`. Recording staleness is not recovering from this
+  // error — the page is still broken until the user navigates — so Vite must
+  // go on rethrowing it rather than have it silently swallowed.
+  window.addEventListener('vite:preloadError', (event) => {
+    markStaleFromError(preloadErrorPayload(event));
+  });
+
+  window.addEventListener('unhandledrejection', (event: PromiseRejectionEvent) => {
+    markStaleFromError(event.reason);
+  });
+}

package/src/client/state.ts

@@ -19,7 +19,8 @@
  * §"Singleton State Registry".
  */
 
-import type { RouterInstance } from './router.js';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
+import type { RouterInstance } from './router-types.js';
 import type { SsrData } from './ssr-data.js';
 
 // ─── Router (from router-ref.ts) ──────────────────────────────────────────
@@ -59,6 +60,18 @@ export function _setCurrentParams(params: Record<string, string | string[]>): vo
   currentParams = params;
 }
 
+/**
+ * Per-slot params snapshot, keyed by slot tree path — the module-level
+ * fallback behind `useSegmentParams(slotPath)` when no NavigationContext is
+ * mounted (tests, calls outside a component). Replaced, never mutated, on
+ * each navigation. See TIM-1285.
+ */
+export let currentSlotParams: SlotParamsRecord | null = null;
+
+export function _setCurrentSlotParams(slotParams: SlotParamsRecord | null): void {
+  currentSlotParams = slotParams;
+}
+
 /** Listeners notified when currentParams changes. */
 export const paramsListeners = new Set<() => void>();
 

package/src/client/top-loader.tsx

@@ -99,7 +99,8 @@ function ensureKeyframes(): void {
 /**
  * Internal top-loader component. Injected by NavigationRoot.
  *
- * Reads pending navigation state from PendingNavigationContext.
+ * Reads pending navigation state from the router's external store, via
+ * usePendingNavigation() — the one pending representation (TIM-1307).
  * Phase transitions are derived synchronously during render:
  *
  *   hidden → crawling:   when isPending becomes true

package/src/client/unload-guard.ts

@@ -8,6 +8,11 @@
  * unloaded so error boundaries and error handlers can suppress abort-related
  * errors during the unload window.
  *
+ * This is the single owner of "is this document going away". Anything that
+ * needs the answer imports `isPageUnloading()` — an unload flag maintained a
+ * second time somewhere else is a flag that will drift out of agreement with
+ * this one (TIM-1260).
+ *
  * Mutable state is delegated to client/state.ts for singleton guarantees.
  * See design/18-build-system.md §"Singleton State Registry"
  *
@@ -16,16 +21,43 @@
 
 import { unloading, _setUnloading } from './state.js';
 
+/**
+ * Departure is *committed*: `pagehide` has fired, or this document has called
+ * reload() on itself. `beforeunload` alone doesn't qualify — it is
+ * speculative, and the user can still cancel out of it.
+ */
+let committed = false;
+
 if (typeof window !== 'undefined') {
   window.addEventListener('beforeunload', () => {
     _setUnloading(true);
+
+    // An app with an unsaved-changes prompt can have this cancelled. Nothing
+    // fires to say so, so the only signal is that the page is still running
+    // afterwards — and timers are blocked while the modal is up, so this task
+    // cannot run until the user has chosen. If they left, `pagehide` has
+    // already committed and this is a no-op.
+    setTimeout(() => {
+      if (!committed) _setUnloading(false);
+    }, 0);
   });
 
-  // Also detect pagehide for bfcache-aware browsers (Safari).
-  // pagehide fires for both navigations and page hide events.
+  // pagehide is the committed-departure event, and fires for both navigations
+  // and bfcache entry. Safari in particular may skip beforeunload entirely.
   window.addEventListener('pagehide', () => {
+    committed = true;
     _setUnloading(true);
   });
+
+  window.addEventListener('pageshow', (event) => {
+    // A bfcache restore un-does the teardown `pagehide` announced: the same
+    // document is alive again, with this module's state intact. Without the
+    // reset, every consumer would go on suppressing errors on a live page.
+    if (event.persisted) {
+      committed = false;
+      _setUnloading(false);
+    }
+  });
 }
 
 /**

package/src/client/use-cookie.ts

@@ -8,7 +8,14 @@
  * See design/29-cookies.md §"useCookie(name) Hook"
  */
 
-import { useSyncExternalStore } from 'react';
+// Namespace access, not `import { useSyncExternalStore }`. This module is
+// reachable from `@timber-js/app/cookies` — `defineCookie()` exposes both a
+// server `.get()` and a client `.useCookie()`, so the entry is isomorphic and
+// loads in the RSC environment. React's `react-server` export withholds
+// `useSyncExternalStore` exactly as it withholds `createContext`, and a *named*
+// ESM import of a missing export fails at module instantiation, before any
+// code runs. Same rule as `client/params-context.ts` (TIM-1297, TIM-1298).
+import * as React from 'react';
 import { parseCookie, stringifySetCookie } from 'cookie';
 import { getSsrData } from './ssr-data.js';
 import { assertValidCookieName } from '../cookies/validation.js';
@@ -129,7 +136,7 @@ export function useCookie(
     return getCookieValue(name);
   };
 
-  const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  const value = React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 
   // Validate the name once per hook instance — names are typically
   // stable string literals, so this catches the bug at first render

package/src/client/use-router.ts

@@ -14,7 +14,7 @@
  * In timber, navigation calls reactRoot.render() which is a root-level
  * render — startTransition has no effect on root renders.
  *
- * Navigation state (params, pathname) is delivered atomically via
+ * Navigation state (pathname, search) is delivered atomically via
  * NavigationContext embedded in the element tree passed to
  * reactRoot.render(). See design/19-client-navigation.md §"NavigationContext".
  *