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

package/src/client/navigation-commit.ts

@@ -0,0 +1,318 @@
+/**
+ * What it means for a page to be "current" on the client.
+ *
+ * One module owns every write that makes a navigation's destination the
+ * current page, and the read that describes the current page back to the
+ * server. Keeping them together is the point: `X-Timber-State-Tree` is
+ * derived from the segment cache, so the thing that publishes and the thing
+ * that reports have to agree about when a page becomes current.
+ *
+ * See design/19-client-navigation.md §"State Update Invariants".
+ */
+
+import { buildSegmentTree, type SegmentCache } from './segment-cache.ts';
+import type { HistoryStack } from './history.ts';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.ts';
+import type { ParamsSource } from '../shared/payload-root.ts';
+import type { NavigationState } from './navigation-context.ts';
+import { parseRouterUrl } from './router-url.ts';
+import {
+  statusPageRendered,
+  _setStatusPageRendered,
+  onStatusPageRendered,
+  _setOnStatusPageRendered,
+} from './state.ts';
+
+// ─── What a status page teaches the cache ─────────────────────────────────
+//
+// A status page replaces a subtree: a deny page lands at the segment owning
+// the matched file and nothing below it mounts; an `error.tsx` fallback
+// discards everything under the boundary that rendered it. `X-Timber-Segments`
+// nonetheless describes the whole chain the payload was built against — it
+// must, because a partial navigation picks its merge point out of it — so the
+// cache has to be told not to learn from such a tree.
+//
+// The HTTP status used to say so, and could not be trusted to: an RSC payload
+// response commits one macrotask after its first chunk, and a nested
+// component that denies after I/O puts its row in the stream after the
+// status line has gone out (TIM-1489). The only thing that reliably knows a
+// status page rendered is the status page itself, and the only moment that
+// matters is the commit that puts it on screen — so every status page the
+// framework produces is wrapped in `StatusPageMarker`, whose layout effect
+// reports on each commit that renders it. Layout effects run child-before-
+// parent, so the report lands before `NavigationRoot`'s publish of that
+// same commit, and never for a render React discards. Without Suspense
+// around the row, the transition cannot commit until the row has arrived, so
+// this covers the delayed nested case too, which no status ever could.
+//
+// The report also clears the cache on the spot, because not every commit
+// has a navigation to consume it: a deny row arriving inside a Suspense
+// boundary after its navigation published, or a status document being
+// hydrated, would otherwise leave a tree in the cache that is no longer on
+// screen. Consuming the flag at commit is what keeps the same navigation from
+// re-seeding it a moment later. Both are over-approximations — a page-level
+// deny leaves every layout standing — at the cost of one full render on the
+// next navigation.
+//
+// Slot boundaries do not report: a slot degrading is the page staying, and
+// the chain it mounted is the chain the header describes. See TIM-1356,
+// TIM-1495, design/04-authorization.md §"Where a Deny Page Renders".
+
+/**
+ * Record that a status page for the main route is on screen. Called from
+ * `StatusPageMarker`'s layout effect; consumed by the commit of the
+ * navigation whose tree it belongs to, and acted on immediately for the
+ * commits that have none.
+ */
+export function reportStatusPageRendered(): void {
+  _setStatusPageRendered(true);
+  onStatusPageRendered?.();
+}
+
+/** Everything a commit needs to describe the page it makes current. */
+export interface NavigationCommitInput {
+  payload: unknown;
+  /** The params that payload published — replayed with it on popstate. */
+  params: ParamsSource;
+  /**
+   * The rendered chain's metadata, or null/undefined when this commit
+   * carries none at all — a revalidation payload, or a history entry
+   * stored before the channel existed.
+   *
+   * An empty *array* is a different statement from an absent one: the
+   * server rendered a route with no layout-bearing segments (a layoutless
+   * app — the missing-root-layout check is a warning, not an error), so
+   * the correct tree is the empty one. Collapsing the two left the
+   * departing route's tree in place, which `treePaths` then reported as
+   * mounted — enough to select an intercepting rewrite whose slot is not
+   * on screen (TIM-1282).
+   */
+  segmentInfo?: SegmentInfo[] | null;
+  /** When true, clear the segment cache if segmentInfo is absent
+   *  (popstate replay for entries without layout metadata). */
+  clearSegmentCacheOnEmpty?: boolean;
+  /**
+   * Layouts the server skipped on this response (`X-Timber-Skipped-Segments`),
+   * when it came from a fetch. Omitted by replays and revalidation.
+   *
+   * Together with `skipped` slot entries in `segmentInfo`, this decides
+   * whether the payload can be *replayed*. A partial payload only renders
+   * merged over the tree on screen, and a `skip=true` outlet resolves against
+   * the slot content cache at render time — so a stored copy of either,
+   * replayed later, shows whatever the client holds *then*, not what was on
+   * screen when the entry committed. Such entries store a null payload and
+   * traversals to them fetch instead. Decided here, not at the fetch call
+   * sites, because there are three of those (`performNavigationFetch`,
+   * `refresh()`, and uncached traversal) and a rule applied at one of them
+   * holds by accident: `performNavigationFetch` had the check and
+   * `fetchCommitAndRender` did not, so a back/forward fetch that was
+   * answered with skips stored the holes (TIM-1432).
+   */
+  skippedSegments?: string[] | null;
+}
+
+/** Whether a response skipped layouts — its payload merges over the tree on screen. */
+export function isPartialNavigation(skippedSegments: string[] | null | undefined): boolean {
+  return skippedSegments != null && skippedSegments.length > 0;
+}
+
+/**
+ * Whether a payload can stand on its own when replayed from the history
+ * stack. See `NavigationCommitInput.skippedSegments`.
+ */
+function isReplayable(opts: NavigationCommitInput): boolean {
+  return !isPartialNavigation(opts.skippedSegments) && !hasSkippedSlot(opts.segmentInfo);
+}
+
+function hasSkippedSlot(segmentInfo: SegmentInfo[] | null | undefined): boolean {
+  return segmentInfo?.some((s) => s.slot && s.skipped) ?? false;
+}
+
+/**
+ * The metadata a committed page keeps — on its history entry, and as the
+ * current page's `committedSegmentInfo()`. `skipped` describes the
+ * *response* — "this slot's content was omitted" — and neither stores such
+ * a payload (the entry stores null). Kept, the flag outlives the response:
+ * `applyActionResult()` reuses the current page's metadata beside a full
+ * re-render and would have that judged non-replayable too.
+ */
+function storedSegmentInfo(segmentInfo: SegmentInfo[] | null | undefined) {
+  if (!hasSkippedSlot(segmentInfo)) return segmentInfo;
+  return segmentInfo!.map(({ skipped: _skipped, ...rest }) => rest);
+}
+
+/**
+ * A navigation's destination, split into what a render needs and what a
+ * commit publishes.
+ */
+export interface PreparedNavigation {
+  /** The state the incoming tree renders with. Pure — safe before winning. */
+  navState: NavigationState;
+  /** Publishes the destination. Call only once the render has won. */
+  commit: () => void;
+}
+
+export interface NavigationCommitter {
+  prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation;
+  currentStateTree(): StateTree | undefined;
+  /**
+   * The segment metadata of the page the last commit made current, as that
+   * commit recorded it — null when it carried none.
+   *
+   * Server-action responses carry no segment metadata, so a revalidation
+   * re-renders the current page with this. It is the committer's own record
+   * rather than a history-stack lookup: the stack is keyed by the URL string
+   * a navigation was asked for, and the current page is known by
+   * `window.location`'s spelling of it, and the two need not agree
+   * (`/a?` against `/a`, a percent-encoded path against a decoded one).
+   */
+  committedSegmentInfo(): SegmentInfo[] | null;
+  /** Whether segment reuse is currently suppressed (TIM-1466). */
+  isSegmentReuseSuppressed(): boolean;
+  /** Lift segment reuse suppression after fresh data has been fetched (TIM-1466). */
+  restoreSegmentReuse(): void;
+}
+
+/**
+ * Derive the navigation state (pathname + search) a URL renders with.
+ *
+ * Pure. The value travels with the tree it describes — callers pass it to
+ * `wrapPayload`, and the router's record of the displayed tree keeps it
+ * beside that tree — so there is no store to publish it to (TIM-1541).
+ */
+export function deriveNavigationState(url: string): NavigationState {
+  // Params are not part of it. They travel with the payload and are published
+  // by the one client-owned `ParamsProvider` as the new tree renders, which is
+  // also what clears the previous route's — a route with no params of its own
+  // still publishes an empty record (TIM-1294/TIM-1297, and the clearing
+  // requirement from TIM-1285).
+  const parsed = parseRouterUrl(url);
+  return { pathname: parsed.pathname || '/', search: parsed.search };
+}
+
+export function createNavigationCommitter(deps: {
+  segmentCache: SegmentCache;
+  historyStack: HistoryStack;
+  /** Read at call time — the router's `clientSegmentCache` opt-in. */
+  clientSegmentCache: () => boolean | undefined;
+}): NavigationCommitter {
+  const { segmentCache, historyStack } = deps;
+
+  // See `committedSegmentInfo`. Written only by a commit.
+  let committedSegmentInfo: SegmentInfo[] | null = null;
+
+  // See `reportStatusPageRendered`: a status page that commits with no
+  // navigation to consume the report still empties the cache.
+  _setOnStatusPageRendered(() => segmentCache.clear());
+
+  /**
+   * Update the segment cache from server-provided segment metadata.
+   *
+   * Runs whether or not `clientSegmentCache` is enabled: the tree is also
+   * where the mounted tree paths come from, and those cross on every
+   * navigation. What the flag gates is which parts get serialized — see
+   * `currentStateTree`.
+   */
+  function updateSegmentCache(segmentInfo: SegmentInfo[]): void {
+    const tree = buildSegmentTree(segmentInfo);
+    if (tree) {
+      segmentCache.set('/', tree);
+    }
+  }
+
+  return {
+    committedSegmentInfo: () => committedSegmentInfo,
+    isSegmentReuseSuppressed: () => segmentCache.isReuseSuppressed(),
+    restoreSegmentReuse: () => segmentCache.restoreReuse(),
+
+    /**
+     * The X-Timber-State-Tree to send with the next RSC request.
+     *
+     * Two different things travel on one header. `segments`/`slots` are the
+     * caching opt-in and are omitted unless `clientSegmentCache` is on.
+     * `treePaths` is how the server learns which route is actually mounted,
+     * which stops being derivable from the address bar as soon as a modal is
+     * open — so it crosses regardless (TIM-1282). Undefined when there is
+     * nothing to say, so a no-op header never enters the `_rsc` cache key.
+     *
+     * Reads what the last *committed* navigation published, so a superseded
+     * navigation's destination can never end up describing the mounted tree
+     * (TIM-1301).
+     */
+    currentStateTree(): StateTree | undefined {
+      const tree = segmentCache.serializeStateTree();
+      if (deps.clientSegmentCache()) return tree;
+      return tree.treePaths ? { segments: [], treePaths: tree.treePaths } : undefined;
+    },
+
+    /**
+     * Prepare all navigation-owned state for a new page — without publishing
+     * any of it. Every code path that changes the "current page" must go
+     * through this function, which is what makes "forgot a field" impossible
+     * by construction.
+     *
+     * Returns the destination's `NavigationState`, which is a pure function of
+     * the URL and is what the incoming tree is *rendered* with, plus a
+     * `commit` thunk that performs the writes that make a page current:
+     * 1. Segment cache — update from server-provided segment metadata
+     * 2. The current page's segment metadata (`committedSegmentInfo`)
+     * 3. History stack — store the payload for instant back/forward replay
+     *
+     * Pathname and search are not written here: they are the returned
+     * `navState`, which the tree renders with and the router's record of the
+     * displayed tree keeps (browser-entry/router-init.ts `publishTree`).
+     *
+     * Nothing is written until `commit()` runs, and on a transitioned
+     * navigation it runs only once the transition is known to have won — see
+     * `renderViaTransition` and `NavigationRoot`. A navigation superseded
+     * while its payload was in flight never calls it, so the cache, the
+     * pathname the client reports and the history stack all keep describing
+     * the route still on screen (TIM-1301).
+     *
+     * Callers with state of their own to publish — the address bar, the
+     * client's record of the mounted tree — wrap this thunk rather than
+     * commit beside it, so there stays exactly one moment at which a page
+     * becomes current.
+     */
+    prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation {
+      const navState = deriveNavigationState(url);
+      const payload = isReplayable(opts) ? opts.payload : null;
+
+      // The tree this navigation renders has not rendered yet. Whatever a
+      // boundary reported before now belongs to a commit that had no
+      // navigation to consume it — a hydration, a row that arrived inside a
+      // Suspense boundary after its navigation had published — and must not
+      // be charged to this one.
+      _setStatusPageRendered(false);
+
+      return {
+        navState,
+        commit() {
+          // A tree in which a boundary rendered a status page is not one to
+          // cache — see the module note. Read at commit rather than at
+          // prepare because that is when the boundary has spoken: the row it
+          // renders may not have existed when the response headers were read.
+          // The history entry records the same thing, or a traversal back to
+          // this URL would replay the metadata this drops.
+          const cacheable = !statusPageRendered;
+          _setStatusPageRendered(false);
+          const segmentInfo = cacheable ? opts.segmentInfo : [];
+
+          if (segmentInfo && segmentInfo.length > 0) {
+            updateSegmentCache(segmentInfo);
+          } else if (segmentInfo?.length === 0 || opts.clearSegmentCacheOnEmpty) {
+            segmentCache.clear();
+          }
+
+          committedSegmentInfo = storedSegmentInfo(segmentInfo) ?? null;
+
+          historyStack.push(url, {
+            payload,
+            params: opts.params,
+            segmentInfo: committedSegmentInfo,
+          });
+        },
+      };
+    },
+  };
+}

package/src/client/navigation-context.ts

@@ -3,27 +3,30 @@
 /**
  * NavigationContext — React context for navigation state.
  *
- * Holds the current route params and pathname, updated atomically
- * with the RSC tree on each navigation. This replaces the previous
- * useSyncExternalStore approach for useParams() and usePathname(),
- * which suffered from a timing gap: the new tree could commit before
- * the external store re-renders fired, causing a frame where both
- * old and new active states were visible simultaneously.
+ * Holds the current pathname and search, updated atomically with the RSC
+ * tree on each navigation. This replaces the previous useSyncExternalStore
+ * approach for usePathname() and useSearchParams(), which suffered from a
+ * timing gap: the new tree could commit before the external store
+ * re-renders fired, causing a frame where both old and new active states
+ * were visible simultaneously.
  *
- * By wrapping the RSC payload element in NavigationProvider inside
- * renderRoot(), the context value and the element tree are passed to
+ * Segment params are NOT here — see the note on NavigationState below.
+ *
+ * By wrapping the RSC payload element in NavigationProvider inside the
+ * router's `renderTree` (browser-entry/router-init.ts), the context value and the element tree are passed to
  * reactRoot.render() in the same call — atomic by construction.
- * All consumers (useParams, usePathname) see the new values in the
+ * All consumers (usePathname, useSearchParams) see the new values in the
  * same render pass as the new tree.
  *
- * During SSR, no NavigationProvider is mounted. Hooks fall back to
- * the ALS-backed getSsrData() for per-request isolation.
+ * During SSR, the wrapper chain mounts this same provider with the
+ * request's pathname and raw search string (TIM-1424), so the hooks
+ * resolve through the identical code path on both sides. Per-request
+ * isolation is by construction — the value is part of the request's
+ * element tree.
  *
- * IMPORTANT: createContext and useContext are NOT available in the RSC
- * environment (React Server Components use a stripped-down React).
- * The context is lazily initialized on first access, and all functions
- * that depend on these APIs are safe to call from any environment —
- * they return null or no-op when the APIs aren't available.
+ * This module is `'use client'` and is never evaluated in the RSC
+ * environment. The shims plugin resolves next/navigation to
+ * navigation-rsc.ts in RSC, which has throwing stubs (TIM-1420).
  *
  * SINGLETON GUARANTEE: All shared mutable state uses globalThis via
  * Symbol.for keys. The RSC client bundler can duplicate this module
@@ -39,15 +42,25 @@
  * See design/19-client-navigation.md §"NavigationContext"
  */
 
-import React, { createElement, type ReactNode } from 'react';
+import { createContext, useContext, createElement, type ReactNode } from 'react';
 
 // ---------------------------------------------------------------------------
 // Context type
 // ---------------------------------------------------------------------------
 
+/**
+ * What the browser knows about the current location.
+ *
+ * Params are deliberately absent: they are a property of the tree the server
+ * rendered, not of the address bar, and they now travel inside the payload as
+ * the payload root. Keeping a copy here meant the router had to thread
+ * the record from a response header into context on every path — navigation,
+ * traversal, prefetch, revalidation — and each of those was a place to drop it
+ * (TIM-1294).
+ */
 export interface NavigationState {
-  params: Record<string, string | string[]>;
   pathname: string;
+  search: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -55,49 +68,41 @@ export interface NavigationState {
 // ---------------------------------------------------------------------------
 
 /**
- * The context is created lazily to avoid calling createContext at module
- * level. In the RSC environment, React.createContext doesn't exist —
- * calling it at import time would crash the server.
- *
  * Context instances are stored on globalThis (NOT in module-level
  * variables) because the ESM bundler can duplicate this module across
  * chunks. Module-level variables would create separate instances per
- * chunk — the provider in TransitionRoot (index chunk) would use
- * context A while the consumer in LinkStatusProvider (shared chunk)
+ * chunk — the provider in NavigationRoot (index chunk) would use
+ * context A while the consumer in usePendingNavigation (shared chunk)
  * reads from context B. globalThis guarantees a single instance.
  *
+ * This module is `'use client'` so it is never evaluated in the RSC
+ * environment — `createContext` and `useContext` are always available.
+ * The shims plugin resolves next/navigation to navigation-rsc.ts in RSC,
+ * which has throwing stubs for the hooks (TIM-1420).
+ *
  * See design/27-chunking-strategy.md §"Singleton Safety"
  */
 
-// Symbol keys for globalThis storage — prevents collisions with user code
 const NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');
-const PENDING_CTX_KEY = Symbol.for('__timber_pending_nav_ctx');
 
-function getOrCreateContext(): React.Context<NavigationState | null> | undefined {
+function getOrCreateContext(): import('react').Context<NavigationState | null> {
   const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as
-    | React.Context<NavigationState | null>
+    | import('react').Context<NavigationState | null>
     | undefined;
   if (existing !== undefined) return existing;
-  // createContext may not exist in the RSC environment
-  if (typeof React.createContext === 'function') {
-    const ctx = React.createContext<NavigationState | null>(null);
-    (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;
-    return ctx;
-  }
-  return undefined;
+  const ctx = createContext<NavigationState | null>(null);
+  (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;
+  return ctx;
 }
 
 /**
- * Read the navigation context. Returns null during SSR (no provider)
- * or in the RSC environment (no context available).
- * Internal — used by useParams() and usePathname().
+ * Read the navigation context. Returns null only when no provider is above
+ * the caller — a component rendered outside the timber app.
+ *
+ * Internal — used by usePathname() and useSearchParams().
  */
 export function useNavigationContext(): NavigationState | null {
-  const ctx = getOrCreateContext();
-  if (!ctx) return null;
-  // useContext may not exist in the RSC environment — caller wraps in try/catch
-  if (typeof React.useContext !== 'function') return null;
-  return React.useContext(ctx);
+  return useContext(getOrCreateContext());
 }
 
 // ---------------------------------------------------------------------------
@@ -112,108 +117,36 @@ export interface NavigationProviderProps {
 /**
  * Wraps children with NavigationContext.Provider.
  *
- * Used in browser-entry.ts renderRoot to wrap the RSC payload element
+ * Used in browser-entry/router-init.ts `renderTree` to wrap the RSC payload element
  * so that navigation state updates atomically with the tree render.
  */
 export function NavigationProvider({
   value,
   children,
-}: NavigationProviderProps): React.ReactElement {
-  const ctx = getOrCreateContext();
-  if (!ctx) {
-    // RSC environment — no context available. Return children as-is.
-    return children as React.ReactElement;
-  }
-  return createElement(ctx.Provider, { value }, children);
+}: NavigationProviderProps): import('react').ReactElement {
+  return createElement(getOrCreateContext().Provider, { value }, children);
 }
 
 // ---------------------------------------------------------------------------
-// Module-level state for renderRoot to read
+// Pending navigation state lives in the router, not here
 // ---------------------------------------------------------------------------
 
 /**
- * Navigation state communicated between the router and renderRoot.
- *
- * The router calls setNavigationState() before renderRoot(). The
- * renderRoot callback reads via getNavigationState() to create the
- * NavigationProvider with the correct params/pathname.
- *
- * This is NOT used by hooks directly — hooks read from React context.
+ * There was a second React context here — `PendingNavigationContext`, holding
+ * the in-flight navigation URL, provided by `NavigationRoot` out of a
+ * `useState` — plus a `usePendingNavigationUrl()` reader for it. Both are gone
+ * (TIM-1307).
  *
- * Stored on globalThis (like the context instances above) because the
- * router lives in one chunk while renderRoot lives in another. Module-
- * level variables would be separate per chunk.
- */
-const NAV_STATE_KEY = Symbol.for('__timber_nav_state');
-
-function _getNavStateStore(): { current: NavigationState } {
-  const g = globalThis as Record<symbol, unknown>;
-  if (!g[NAV_STATE_KEY]) {
-    g[NAV_STATE_KEY] = { current: { params: {}, pathname: '/' } };
-  }
-  return g[NAV_STATE_KEY] as { current: NavigationState };
-}
-
-export function setNavigationState(state: NavigationState): void {
-  _getNavStateStore().current = state;
-}
-
-export function getNavigationState(): NavigationState {
-  return _getNavStateStore().current;
-}
-
-// ---------------------------------------------------------------------------
-// Pending Navigation Context (same module for singleton guarantee)
-// ---------------------------------------------------------------------------
-
-/**
- * Separate context for the in-flight navigation URL. Provided by
- * TransitionRoot (urgent useState), consumed by LinkStatusProvider
- * and useNavigationPending.
+ * Nothing read them. `usePendingNavigation()` (use-pending-navigation.ts) and
+ * `TopLoader` both subscribe to the router's external pending store via
+ * `useSyncExternalStore`: sync priority, immune to transition entanglement,
+ * and cleared by `runNavigation`'s supersession-guarded `finally` (TIM-1034).
+ * The context was a parallel representation of the same fact that no consumer
+ * ever migrated to, and one that could not even agree with the store — a
+ * navigation superseded by a cached popstate replay left its URL set until the
+ * next full navigation, because the staleness guard skipped the clear and no
+ * other path touched it.
  *
- * Uses globalThis via Symbol.for for the same reason as NavigationContext
- * above — the bundler may duplicate this module across chunks, and module-
- * level variables would create separate context instances.
- */
-
-function getOrCreatePendingContext(): React.Context<string | null> | undefined {
-  const existing = (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] as
-    | React.Context<string | null>
-    | undefined;
-  if (existing !== undefined) return existing;
-  if (typeof React.createContext === 'function') {
-    const ctx = React.createContext<string | null>(null);
-    (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] = ctx;
-    return ctx;
-  }
-  return undefined;
-}
-
-/**
- * Read the pending navigation URL from context.
- * Returns null during SSR (no provider) or in the RSC environment.
- */
-export function usePendingNavigationUrl(): string | null {
-  const ctx = getOrCreatePendingContext();
-  if (!ctx) return null;
-  if (typeof React.useContext !== 'function') return null;
-  return React.useContext(ctx);
-}
-
-/**
- * Provider for the pending navigation URL. Wraps children with
- * the pending context Provider.
+ * One representation, and it is the router's. See
+ * design/19-client-navigation.md §"How Pending State Works".
  */
-export function PendingNavigationProvider({
-  value,
-  children,
-}: {
-  value: string | null;
-  children?: ReactNode;
-}): React.ReactElement {
-  const ctx = getOrCreatePendingContext();
-  if (!ctx) {
-    return children as React.ReactElement;
-  }
-  return createElement(ctx.Provider, { value }, children);
-}