@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

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.ts';
+
+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/slot-content-cache-context.ts

@@ -0,0 +1,43 @@
+/**
+ * SlotContentCacheContext — the router-owned record of slot content the
+ * client has *committed*.
+ *
+ * The server omits a parallel slot's content when the client advertised a
+ * matching content key (`skip=true`, TIM-1370), and the outlet at that
+ * position must render what it displayed before. This Map, keyed by
+ * segmentPath, is where that content lives.
+ *
+ * Ownership and write discipline (TIM-1423):
+ *
+ * - **One instance per router.** `createTimberRouter` creates the Map and
+ *   provides it above every tree it hands to React — hydration included,
+ *   which builds its chain through the same `renderTree`. It is not a
+ *   module or `globalThis` singleton: a process-wide Map executed during
+ *   SSR would be shared by concurrent requests.
+ * - **Written only at commit.** `SegmentOutlet` writes from a layout effect,
+ *   never during render. A render React discards — a transition superseded
+ *   before it commits, a Suspense retry — leaves the Map untouched, so a
+ *   later `skip=true` can only ever resolve to content the user actually saw.
+ *   The content-key record the client advertises (`SegmentCache`, published
+ *   by `NavigationRoot`'s layout effect on the same commit) and this Map
+ *   are therefore written by the same React commit and cannot describe
+ *   different trees.
+ * - **`null` outside a router.** SSR renders no provider and the outlet then
+ *   neither reads nor writes: the server never emits `skip` during SSR, and
+ *   layout effects do not run there. The default is `null` rather than a
+ *   shared Map so that "no provider" cannot silently become "shared cache".
+ *
+ * Singleton across bundler-duplicated chunks via `createGlobalContext`.
+ */
+
+'use client';
+
+import type { ReactNode } from 'react';
+import { createGlobalContext } from './global-context.ts';
+
+export type SlotContentCache = Map<string, ReactNode>;
+
+export const SlotContentCacheContext = createGlobalContext<SlotContentCache | null>(
+  '__timber_slot_content_cache_ctx',
+  null
+);

package/src/client/slot-context.ts

@@ -0,0 +1,50 @@
+/**
+ * SlotContext — delivers live slot content to SlotOutlet holes inside
+ * cached component shells (TIM-1173).
+ *
+ * A `cache.component(Fn, { slots: [...] })` shell is captured with a
+ * stable <SlotOutlet slot={name} /> client reference in place of each
+ * declared slot prop. At request time the revived shell is wrapped in a
+ * SlotsProvider carrying the live slot values; each outlet reads its
+ * value from this context by name.
+ *
+ * Providers MERGE per-key with their parent: an inner SlotsProvider
+ * inherits the outer's values and overrides only the keys it declares.
+ * Two sibling instances each have their own provider and resolve
+ * independently. Layouts use a reserved slot name (LAYOUT_CHILDREN_SLOT)
+ * that cannot collide with user-declared slot names (TIM-1191).
+ *
+ * Generalizes the original layout children pattern (TIM-1181) from a
+ * single implicit `children` hole on layouts to explicitly declared,
+ * named slot props on any cached component. Layouts use this same
+ * context with the reserved LAYOUT_CHILDREN_SLOT key (TIM-1191).
+ *
+ * SINGLETON GUARANTEE: globalThis + Symbol.for — the RSC client bundler
+ * can duplicate this module across chunks; globalThis guarantees a single
+ * context instance.
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import React, { type ReactNode } from 'react';
+
+export type SlotValues = Record<string, ReactNode>;
+
+const CTX_KEY = Symbol.for('__timber_slot_ctx');
+
+function getOrCreateContext(): React.Context<SlotValues | null> {
+  const existing = (globalThis as Record<symbol, unknown>)[CTX_KEY] as
+    | React.Context<SlotValues | null>
+    | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext === 'function') {
+    const ctx = React.createContext<SlotValues | null>(null);
+    (globalThis as Record<symbol, unknown>)[CTX_KEY] = ctx;
+    return ctx;
+  }
+  return undefined as unknown as React.Context<SlotValues | null>;
+}
+
+export const SlotContext = getOrCreateContext();

package/src/client/slot-outlet.tsx

@@ -0,0 +1,22 @@
+/**
+ * SlotOutlet — the hole in a cached component shell (TIM-1173).
+ *
+ * At capture time the prebuilt runtime renders the wrapped component with
+ * <SlotOutlet slot={name} /> in place of each declared slot prop. Being a
+ * client component, it serializes into the flight payload as a stable,
+ * deterministic client reference — the same bytes regardless of what live
+ * content will fill the hole. At request time the revived shell sits under
+ * a SlotsProvider and each outlet reads its live value from SlotContext.
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import { useContext } from 'react';
+import { SlotContext } from './slot-context.ts';
+
+export function SlotOutlet({ slot }: { slot: string }) {
+  const values = useContext(SlotContext);
+  return values ? (values[slot] ?? null) : null;
+}

package/src/client/slot-provider.tsx

@@ -0,0 +1,32 @@
+/**
+ * SlotsProvider — wraps a revived cached shell to supply live slot content
+ * to the SlotOutlet holes inside it (TIM-1173).
+ *
+ * Values MERGE with the nearest parent provider so that nesting a
+ * cache.component SlotsProvider inside a layout SlotsProvider preserves
+ * the layout's `children` slot while adding the component's own slots.
+ * Inner values override outer ones with the same name (spread order).
+ *
+ * Tree structure per cached-component instance:
+ *   SlotsProvider(values={children: <Live />})
+ *     └── revived shell
+ *          └── SlotOutlet(slot="children") → reads context → <Live />
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import { createElement, useContext, type ReactNode } from 'react';
+import { SlotContext, type SlotValues } from './slot-context.ts';
+
+interface SlotsProviderProps {
+  values: SlotValues;
+  children: ReactNode;
+}
+
+export function SlotsProvider({ values, children }: SlotsProviderProps) {
+  const parent = useContext(SlotContext);
+  const merged = parent ? { ...parent, ...values } : values;
+  return createElement(SlotContext.Provider, { value: merged }, children);
+}

package/src/client/ssr-data.ts

@@ -1,17 +1,20 @@
 /**
  * SSR Data — per-request state for client hooks during server-side rendering.
  *
- * RSC and SSR are separate Vite module graphs (see design/18-build-system.md),
- * so the RSC environment's request-context ALS is not visible to SSR modules.
- * This module provides getter/setter functions that ssr-entry.ts uses to
- * populate per-request data for React's render.
+ * `useCookie()` and `<Link preserveSearchParams>` have no React context to
+ * read their request values from during SSR, so the SSR entry hands them
+ * the request's cookies and search string through this module.
+ * `useSearchParams()` reads NavigationContext and uses getSsrData() only to
+ * detect that it is rendering on the server. Route
+ * params do not travel here — client components read them from
+ * `ParamsContext`, decoded from the payload root.
  *
- * Request isolation: On the server, ssr-entry.ts registers an ALS-backed
- * provider via registerSsrDataProvider(). getSsrData() reads from the ALS
- * store, ensuring correct per-request data even when Suspense boundaries
- * resolve asynchronously across concurrent requests. The module-level
- * setSsrData/clearSsrData functions are kept as a fallback for tests
- * and environments without ALS.
+ * Request isolation: ssr-entry.ts registers an ALS-backed provider via
+ * registerSsrDataProvider(), so getSsrData() reads the current request's
+ * store even when Suspense boundaries resolve asynchronously across
+ * concurrent requests. There is no module-level fallback: outside an SSR
+ * render (in the browser, or before the provider is registered) there is no
+ * request, and getSsrData() returns undefined.
  *
  * IMPORTANT: This module must NOT import node:async_hooks or any Node.js-only
  * APIs, as it's imported by 'use client' hooks that are bundled for the browser.
@@ -22,31 +25,21 @@
  * See design/18-build-system.md §"Singleton State Registry"
  */
 
-import {
-  ssrDataProvider,
-  currentSsrData,
-  _setSsrDataProvider,
-  _setCurrentSsrData,
-} from './state.js';
+import { ssrDataProvider, _setSsrDataProvider } from './state.ts';
 
 // ─── Types ────────────────────────────────────────────────────────
 
 export interface SsrData {
-  /** The request's URL pathname (e.g. '/dashboard/settings') */
-  pathname: string;
-  /** The request's search params as a plain record */
-  searchParams: Record<string, string>;
-  /** The request's cookies as name→value pairs */
-  cookies: Map<string, string>;
-  /** 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.
+   * The request's raw app-visible query string (`''` or `?…`), matching what
+   * `window.location.search` will hold after hydration. The raw string is
+   * the only representation carried here: it preserves repeated keys
+   * (`?tag=a&tag=b`), which a collapsed `Record<string, string>` cannot
+   * (TIM-1428). Parse with `new URLSearchParams(search)` where needed.
    */
-  _navContext?: { _denyHandledByBoundary?: boolean };
+  search: string;
+  /** The request's cookies as name→value pairs */
+  cookies: Map<string, string>;
 }
 
 // ─── ALS-Backed Provider ─────────────────────────────────────────
@@ -66,53 +59,20 @@ export interface SsrData {
 // See timber-shims plugin resolveId for details.
 
 /**
- * Register an ALS-backed SSR data provider. Called once at module load
- * by ssr-entry.ts to wire up per-request data via AsyncLocalStorage.
- *
- * When registered, getSsrData() reads from the provider (ALS store)
- * instead of module-level state, ensuring correct isolation for
- * concurrent requests with streaming Suspense.
+ * Register the SSR data provider. Called once at module load by
+ * ssr-entry.ts to wire up per-request data via AsyncLocalStorage; tests
+ * register their own provider (and `undefined` to reset).
  */
-export function registerSsrDataProvider(provider: () => SsrData | undefined): void {
+export function registerSsrDataProvider(provider: (() => SsrData | undefined) | undefined): void {
   _setSsrDataProvider(provider);
 }
 
-// ─── Module-Level Fallback ────────────────────────────────────────
-//
-// Used by tests and as a fallback when no ALS provider is registered.
-
-/**
- * Set the SSR data for the current request via module-level state.
- *
- * In production, ssr-entry.ts uses ALS (runWithSsrData) instead.
- * This function is retained for tests and as a fallback.
- */
-export function setSsrData(data: SsrData): void {
-  _setCurrentSsrData(data);
-}
-
-/**
- * Clear the SSR data after rendering completes.
- *
- * In production, ALS scope handles cleanup automatically.
- * This function is retained for tests and as a fallback.
- */
-export function clearSsrData(): void {
-  _setCurrentSsrData(undefined);
-}
-
 /**
  * Read the current request's SSR data. Returns undefined when called
  * outside an SSR render (i.e. on the client after hydration).
  *
- * Prefers the ALS-backed provider when registered (server-side),
- * falling back to module-level state (tests, legacy).
- *
  * Used by client hooks' server snapshot functions.
  */
 export function getSsrData(): SsrData | undefined {
-  if (ssrDataProvider) {
-    return ssrDataProvider();
-  }
-  return currentSsrData;
+  return ssrDataProvider?.();
 }

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.ts';
+
+// ─── 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

@@ -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
@@ -19,8 +19,8 @@
  * §"Singleton State Registry".
  */
 
-import type { RouterInstance } from './router.js';
-import type { SsrData } from './ssr-data.js';
+import type { RouterInstance } from './router-types.ts';
+import type { SsrData } from './ssr-data.ts';
 
 // ─── Router (from router-ref.ts) ──────────────────────────────────────────
 
@@ -34,8 +34,8 @@ export function _setGlobalRouter(router: RouterInstance | null): void {
 // ─── SSR Data Provider (from ssr-data.ts) ──────────────────────────────────
 
 /**
- * ALS-backed SSR data provider. When registered, getSsrData() reads from
- * this function (ALS store) instead of module-level currentSsrData.
+ * ALS-backed SSR data provider, registered by the SSR entry. getSsrData()
+ * reads through it; unset in the browser.
  */
 export let ssrDataProvider: (() => SsrData | undefined) | undefined;
 
@@ -43,25 +43,6 @@ export function _setSsrDataProvider(provider: (() => SsrData | undefined) | unde
   ssrDataProvider = provider;
 }
 
-/** Fallback SSR data for tests and environments without ALS. */
-export let currentSsrData: SsrData | undefined;
-
-export function _setCurrentSsrData(data: SsrData | undefined): void {
-  currentSsrData = data;
-}
-
-// ─── Route Params (from use-params.ts) ──────────────────────────────────────
-
-/** Current route params snapshot — replaced (not mutated) on each navigation. */
-export let currentParams: Record<string, string | string[]> = {};
-
-export function _setCurrentParams(params: Record<string, string | string[]>): void {
-  currentParams = params;
-}
-
-/** Listeners notified when currentParams changes. */
-export const paramsListeners = new Set<() => void>();
-
 // ─── Search Params Cache (from use-search-params.ts) ────────────────────────
 
 /** Cached search string — avoids reparsing when URL hasn't changed. */
@@ -81,3 +62,29 @@ export let unloading = false;
 export function _setUnloading(value: boolean): void {
   unloading = value;
 }
+
+// ─── Status Page Commit Flag (from navigation-commit.ts) ────────────────────
+
+/**
+ * Whether a status page for the main route has rendered since the last
+ * navigation was prepared. Raised by `StatusPageMarker`, consumed by the
+ * navigation's commit. See navigation-commit.ts §"What a status page
+ * teaches the cache".
+ */
+export let statusPageRendered = false;
+
+export function _setStatusPageRendered(value: boolean): void {
+  statusPageRendered = value;
+}
+
+/**
+ * What a status page report does beyond raising the flag: registered by the
+ * router's committer so the report can clear the segment cache at once, for
+ * the commits no navigation consumes (a row arriving inside Suspense after
+ * its navigation published, a status document being hydrated).
+ */
+export let onStatusPageRendered: (() => void) | undefined;
+
+export function _setOnStatusPageRendered(handler: (() => void) | undefined): void {
+  onStatusPageRendered = handler;
+}

package/src/client/status-page-marker.tsx

@@ -0,0 +1,32 @@
+'use client';
+
+/**
+ * The one way a status page tells the router it is on screen.
+ *
+ * A status page replaces a subtree, and the segment cache must not learn a
+ * chain that never mounted (see `navigation-commit.ts` §"What a status page
+ * teaches the cache"). Status pages are produced in three places — an
+ * in-tree catch site rendering the page it owns, the server's fallback
+ * renderers, and a client boundary rendering its fallback for a Flight row —
+ * and every one of them wraps the page in this marker, so the report does
+ * not depend on which producer it was. In particular the in-tree case, the
+ * common `access.ts` deny, never involves a client boundary at all.
+ *
+ * A layout effect, on every commit that renders the marker rather than on
+ * mount only: React reuses the fiber when one status page is replaced by
+ * another at the same position, and the second one must report too. Layout
+ * effects run child-before-parent, so the report lands before the ancestor
+ * `NavigationRoot` publishes the same commit, and never for a render React
+ * discards. Idempotent, so StrictMode's double invocation and a status page
+ * re-rendering on its own state are harmless. See TIM-1495.
+ */
+
+import { useLayoutEffect, type ReactNode } from 'react';
+import { reportStatusPageRendered } from './navigation-commit.ts';
+
+export function StatusPageMarker({ children }: { children: ReactNode }): ReactNode {
+  useLayoutEffect(() => {
+    reportStatusPageRendered();
+  });
+  return children;
+}