@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

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.
+ *
+ * Segment params are NOT here — see the note on NavigationState below.
  *
  * By wrapping the RSC payload element in NavigationProvider inside
  * renderRoot(), 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,26 @@
  * See design/19-client-navigation.md §"NavigationContext"
  */
 
-import React, { createElement, type ReactNode } from 'react';
+import { createContext, useContext, createElement, type ReactNode } from 'react';
+import type { SlotParamsRecord } from '../shared/slot-params.ts';
 
 // ---------------------------------------------------------------------------
 // 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 +69,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());
 }
 
 // ---------------------------------------------------------------------------
@@ -118,13 +124,8 @@ export interface NavigationProviderProps {
 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);
 }
 
 // ---------------------------------------------------------------------------
@@ -149,7 +150,7 @@ 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: '/' } };
+    g[NAV_STATE_KEY] = { current: { pathname: '/', search: '' } };
   }
   return g[NAV_STATE_KEY] as { current: NavigationState };
 }
@@ -163,57 +164,25 @@ export function getNavigationState(): NavigationState {
 }
 
 // ---------------------------------------------------------------------------
-// Pending Navigation Context (same module for singleton guarantee)
+// Pending navigation state lives in the router, not here
 // ---------------------------------------------------------------------------
 
 /**
- * Separate context for the in-flight navigation URL. Provided by
- * TransitionRoot (urgent useState), consumed by LinkStatusProvider
- * and useNavigationPending.
+ * 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).
  *
- * 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.
+ * 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.
+ *
+ * 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);
-}

package/src/client/navigation-root.tsx

@@ -0,0 +1,224 @@
+/**
+ * NavigationRoot — the component the router renders the page through.
+ *
+ * It is stateless. The router owns the displayed tree and drives React with
+ * `root.render(<NavigationRoot rendered={{ element, publish }} />)` inside a
+ * synchronous `startTransition` (see `client/react-root.ts`). A transition
+ * update keeps the committed tree on screen while the incoming one resolves,
+ * instead of replacing it with a Suspense fallback — the reason this
+ * component exists (TIM-1306).
+ *
+ * It used to hold the tree in `useState` and register `setState` closures
+ * into module globals during render so the router could reach into it, with a
+ * second set of stand-in closures for the window before a root existed
+ * (TIM-600). Inverting that — router calls React, not the reverse — deleted
+ * all of it (TIM-1431). Next.js's `use-action-queue.ts` says it wants this
+ * shape and cannot have it because it must decode Flight during render;
+ * timber decodes in `router-pipeline.ts`, so nothing stands in the way.
+ *
+ * What this component does own is **the commit-time publish**: a navigation's
+ * state (segment cache, address bar, history stack, pathname) is published
+ * from a layout effect keyed on the tree object, so the event that puts a
+ * route on screen is the event that makes it current (TIM-1301). Props work
+ * for that exactly as state did.
+ *
+ * This component holds no pending state. The `TopLoader` it renders and the
+ * public `usePendingNavigation()` both subscribe to the router's external
+ * pending store; NavigationRoot's own `pendingUrl` was a second, unread
+ * representation of the same fact and is gone (TIM-1307).
+ *
+ * Hard navigation guard: When a hard navigation is triggered (500 error,
+ * version skew), the component throws an unresolved thenable AFTER all
+ * hooks to suspend forever — preventing React from rendering children
+ * during page teardown. The throw must come after hooks to satisfy
+ * React's rules (same hook count every render) while still preventing
+ * child renders that could hit hook count mismatches in components
+ * whose positions shift during teardown. This pattern is borrowed from
+ * Next.js (app-router.tsx pushRef.mpaNavigation — also after hooks).
+ *
+ * See design/05-streaming.md §"deferSuspenseFor"
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+
+import { createElement, Fragment, useLayoutEffect, useRef, type ReactNode } from 'react';
+import { TopLoader, type TopLoaderConfig } from './top-loader.tsx';
+
+// ─── Rendered Tree ──────────────────────────────────────────────
+
+/**
+ * The tree the router has handed to React, and the state publish that belongs
+ * to it. They travel as one object so React's commit of the tree is the event
+ * that publishes — see the effect in NavigationRoot. Every `render` builds a
+ * fresh one, which is what keys that effect: a tree is published once, however
+ * many times React re-runs the effect for it.
+ */
+export interface RenderedTree {
+  element: ReactNode;
+  /**
+   * Publishes the navigation's state — segment cache, pathname, address bar,
+   * history stack, and the client's record of the mounted tree — and
+   * announces it to listeners outside React. Runs when React commits
+   * `element`, never before (TIM-1301). Null for a render that has nothing to
+   * publish on commit (hydration, the shallow search re-wrap).
+   */
+  publish: (() => void) | null;
+}
+
+/**
+ * Hand a tree to React in a transition. `publish` runs when React commits it.
+ *
+ * Every path that puts a page on screen goes through one of these — a
+ * navigation, a revalidation, a popstate replay, a shallow search re-wrap —
+ * and it is always a synchronous `startTransition` around `root.render`.
+ * The production one is `createReactRoot().render`.
+ */
+export type NavigationRender = (element: ReactNode, publish: (() => void) | null) => void;
+
+// ─── Hard Navigation Guard ──────────────────────────────────────
+
+/**
+ * Module-level flag indicating a hard (MPA) navigation is in progress.
+ *
+ * When true:
+ * - NavigationRoot throws an unresolved thenable to suspend forever,
+ *   preventing React from rendering children during page teardown
+ *   (avoids "Rendered more hooks" crashes).
+ * - The Navigation API handler skips interception, letting the browser
+ *   perform a full page load (prevents infinite loops where
+ *   window.location.href → navigate event → router.navigate → 500 →
+ *   window.location.href → ...).
+ *
+ * Uses globalThis for singleton guarantee across chunks (same pattern
+ * as NavigationContext). See design/19-client-navigation.md §"Singleton
+ * Guarantee via globalThis".
+ */
+const HARD_NAV_KEY = Symbol.for('__timber_hard_navigating');
+
+function getHardNavStore(): { value: boolean } {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[HARD_NAV_KEY]) {
+    g[HARD_NAV_KEY] = { value: false };
+  }
+  return g[HARD_NAV_KEY] as { value: boolean };
+}
+
+/**
+ * Set the hard-navigating flag. Call this BEFORE setting
+ * window.location.href or window.location.reload() to prevent:
+ * 1. React from rendering children during page teardown
+ * 2. Navigation API from intercepting the hard navigation
+ */
+export function setHardNavigating(value: boolean): void {
+  getHardNavStore().value = value;
+}
+
+/**
+ * Check if a hard navigation is in progress.
+ * Used by NavigationRoot (throw unresolvedThenable) and by the
+ * Navigation API handler (skip interception).
+ */
+export function isHardNavigating(): boolean {
+  return getHardNavStore().value;
+}
+
+/**
+ * A thenable that never resolves. When thrown during React render,
+ * it causes the component to suspend forever — React keeps the
+ * old committed tree visible and never attempts to render children.
+ *
+ * This is the same pattern Next.js uses in app-router.tsx for MPA
+ * navigations (pushRef.mpaNavigation → throw unresolvedThenable).
+ */
+// for React's Suspense mechanism. Same pattern as Next.js's unresolvedThenable.
+// eslint-disable-next-line unicorn/no-thenable -- Intentionally a never-resolving thenable
+const unresolvedThenable = { then() {} } as PromiseLike<never>;
+
+// ─── Component ───────────────────────────────────────────────────
+
+/**
+ * Root component the router renders the page through.
+ *
+ * Renders the TopLoader alongside the tree it is given. Neither adds a DOM
+ * element on the hydration path, so the tree matches the server HTML.
+ *
+ * Rendered only by `createReactRoot` (client/react-root.ts): hydration passes
+ * `{ element, publish: null }`, and every later render is a synchronous
+ * `startTransition(() => root.render(...))` with a fresh `rendered` object.
+ */
+export function NavigationRoot({
+  rendered,
+  topLoaderConfig,
+}: {
+  rendered: RenderedTree;
+  topLoaderConfig?: TopLoaderConfig;
+}): ReactNode {
+  // Publish the navigation's state when React commits its tree — not when the
+  // tree is handed over. A tree React is still waiting on, or one a later
+  // navigation replaces before React renders it, has been *given* to React
+  // without being on screen; publishing then describes a route the user never
+  // saw, which is the defect this ordering exists to prevent (TIM-1301).
+  //
+  // A **layout** effect, so the publish lands before the browser paints and,
+  // more importantly, before every descendant's passive effect. A destination
+  // component that navigates from a mount effect — a redirect guard, a
+  // `refresh()` on mount — would otherwise start its navigation while the
+  // segment cache, address bar and pathname still described the departing
+  // route, and send an X-Timber-State-Tree for a tree that is no longer
+  // mounted (codex on #998).
+  //
+  // Descendant *layout* effects still run first: React runs layout effects
+  // child-before-parent, and the only way to precede them would be a fiber
+  // rendered as an earlier sibling of the payload. That is not free here —
+  // `server/ssr-wrappers.tsx` mirrors this component's fiber shape so `useId`
+  // agrees across hydration, and an extra sibling shifts every id in the
+  // payload subtree. A layout effect that navigates on mount is the price.
+  //
+  // Keyed on the tree object rather than on the effect run. A publish moves
+  // the address bar, which is not idempotent, so any second invocation for the
+  // same tree — an effect re-run React is entitled to perform, StrictMode's
+  // double-invoke — must be a no-op rather than a second history entry.
+  const publishedRef = useRef<RenderedTree | null>(null);
+  useLayoutEffect(() => {
+    if (publishedRef.current === rendered) return;
+    publishedRef.current = rendered;
+    rendered.publish?.();
+  }, [rendered]);
+
+  // ─── Hard navigation guard ─────────────────────────────────
+  // When a hard navigation is in progress (500 error, version skew),
+  // suspend forever to prevent React from rendering children during
+  // page teardown. This avoids "Rendered more hooks" crashes in
+  // CHILD components whose hook counts may shift during teardown.
+  //
+  // CRITICAL: This throw MUST come AFTER all hooks (the useRef and
+  // useLayoutEffect above). React requires the same hooks to run on every
+  // render. If we threw before hooks, React would see 0 hooks on the
+  // re-render vs 2 on the initial render — triggering the exact "Rendered
+  // more hooks" error we're trying to prevent.
+  //
+  // By placing it after hooks but before the return, all hooks
+  // satisfy React's rules, but the thrown thenable prevents any
+  // children from rendering. Same pattern as Next.js app-router.tsx
+  // (pushRef.mpaNavigation — also placed after all hooks).
+  if (isHardNavigating()) {
+    throw unresolvedThenable;
+  }
+
+  // Inject TopLoader alongside the element tree. It subscribes to the router's
+  // pending store itself, so it takes no props from here beyond its config,
+  // and only it re-renders when a navigation starts or ends. Rendered only
+  // when not explicitly disabled via config.
+  //
+  // This Fragment is a FORK — two children — so it advances React's tree
+  // context and shifts every `useId` below it. `server/ssr-wrappers.tsx`
+  // mirrors it for exactly that reason; a single-child wrapper would not need
+  // a mirror. See tests/ssr-wrapper-parity.test.ts.
+  const showTopLoader = topLoaderConfig?.enabled !== false;
+  if (!showTopLoader) return rendered.element;
+  return createElement(
+    Fragment,
+    null,
+    createElement(TopLoader, { config: topLoaderConfig }),
+    rendered.element
+  );
+}