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

package/src/client/params-context.ts

@@ -0,0 +1,187 @@
+/**
+ * Segment params context — the one channel params use to reach the browser.
+ *
+ * Params ride the RSC payload's root row as a sibling of the tree
+ * (`{ tree, params, slotParams }`), rather than in four side channels that
+ * raced to seed them: a response header, an inline script, and two build-time
+ * manifest fields all previously carried the same record, each with its own
+ * `JSON.stringify` (TIM-1294).
+ *
+ * Riding the payload is what makes them *typed*. `defineSchema` takes any
+ * `Codec<T>`, so a coerced param is whatever the codec returned — a `Date`, a
+ * `bigint` — and `JSON.stringify` either flattened it to a string or threw
+ * mid-response. React Flight carries those values natively, so the client
+ * reads the value the server produced instead of a lossy copy of it. See
+ * design/41-global-params.md §"Transport".
+ *
+ * **The client owns the provider.** There is exactly one `ParamsProvider` in
+ * the browser's tree, rendered by `PayloadRoot` above the point where a
+ * partial navigation splices the new payload into the retained tree. It has to
+ * be there and it has to be alone: a provider *inside* the payload lands below
+ * the retained region, whose own root is the departing route's provider, so
+ * every reader in a skipped layout resolves to the departing record and no
+ * amount of wrapping above it helps (TIM-1297).
+ *
+ * Ordering still holds without a bootstrap contract, for the same reason it
+ * did when the provider was in the tree: a provider renders before its own
+ * descendants by construction, so `useSegmentParams()` is correct during
+ * hydration without anything having to run before `hydrateRoot()`.
+ */
+
+'use client';
+
+import React, { createElement, useMemo, use } from 'react';
+import { toNullProtoRecord, type CoercedParams } from '../shared/param-value.ts';
+import { readPublishedParams, type PublishedParams } from '../shared/payload-root.ts';
+import type { SlotParamsRecord } from '../shared/slot-params.ts';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+export type ParamsContextValue = PublishedParams;
+
+// ─── Context ─────────────────────────────────────────────────────
+
+/**
+ * SINGLETON GUARANTEE: globalThis + `Symbol.for`, the same pattern as
+ * `NavigationContext` and `SegmentUpdateContext`.
+ *
+ * The RSC client bundler can duplicate a module across chunks, and with ESM
+ * output each chunk gets its own module scope — so a bare `createContext` at
+ * module level yields one context per chunk. This module is now reached from
+ * *both* graphs: `PayloadRoot` is imported by the browser entry, while
+ * `useParamsContext()` arrives through the client-reference graph with the
+ * app's own components. A duplicate would put the provider on instance A and
+ * every reader on instance B, so `useContext` returns `null` and every
+ * `useSegmentParams()` call throws the outside-the-timber-app-tree error
+ * even though the provider is mounted (the module-snapshot fallback it once
+ * silently landed on was deleted in TIM-1425).
+ *
+ * This module was the one client context without the guard — harmless while
+ * the provider travelled inside the payload, in the same graph as its readers,
+ * and load-bearing the moment the client started rendering it (TIM-1297).
+ *
+ * The React APIs are reached through the namespace rather than named imports,
+ * for the same reason `segment-update-context.ts` and `navigation-context.ts`
+ * do it: React's `react-server` export provides neither `createContext` nor
+ * `useContext`, and a *named* ESM import of a missing export fails at module
+ * instantiation — before any feature check could run. This module is reachable
+ * from every entry a Server Component imports, so the named form crashed
+ * those entries outright (codex, PR #992; originally reproduced against
+ * `@timber-js/app/segment-params`, an entry point since deleted by TIM-1342 —
+ * the hazard is unchanged for the entries that remain).
+ *
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+ */
+const PARAMS_CTX_KEY = Symbol.for('__timber_params_ctx');
+
+function getOrCreateContext(): React.Context<ParamsContextValue | null> {
+  const store = globalThis as Record<symbol, unknown>;
+  const existing = store[PARAMS_CTX_KEY] as React.Context<ParamsContextValue | null> | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext !== 'function') {
+    // RSC environment — no contexts here. Nothing in this module runs on that
+    // side; it only has to import cleanly.
+    return undefined as unknown as React.Context<ParamsContextValue | null>;
+  }
+  const ctx = React.createContext<ParamsContextValue | null>(null);
+  store[PARAMS_CTX_KEY] = ctx;
+  return ctx;
+}
+
+const ParamsContext = getOrCreateContext();
+
+/**
+ * Read the params provided by the tree. Returns null only when no provider
+ * is above the caller — a component rendered outside a timber route. During
+ * SSR the wrapper chain mounts `PayloadRoot` too (TIM-1424), so both sides
+ * resolve through this context.
+ */
+export function useParamsContext(): ParamsContextValue | null {
+  return React.useContext(ParamsContext);
+}
+
+// ─── Provider ────────────────────────────────────────────────────
+
+interface ParamsProviderProps {
+  params: CoercedParams;
+  slotParams: SlotParamsRecord | null;
+  children?: React.ReactNode;
+}
+
+/**
+ * Provides the current navigation's params to everything below it.
+ *
+ * Rendered only by `PayloadRoot`. Not exported: a second provider anywhere in
+ * the tree would shadow this one for the region below it, which is precisely
+ * the defect TIM-1297 fixed.
+ *
+ * This used to also write a module-level snapshot during render, as the
+ * fallback for `useSegmentParams()` called outside a component. That tier is
+ * gone (TIM-1425) — the provider is unconditional on every render path,
+ * browser and SSR alike, so the hook reads context or throws. Removing the
+ * write also removes render-phase shared mutation from the SSR environment,
+ * where concurrent requests rendered through this component.
+ */
+function ParamsProvider({ params, slotParams, children }: ParamsProviderProps) {
+  // Restore the null prototype the wire could not carry. Flight rejects a
+  // null-prototype object, so `withPublishedParams` flattens the records;
+  // rebuilding them here is what keeps `params.constructor` returning
+  // `undefined` instead of a function for a param the route does not define
+  // (design/13-security.md #36c). Memoized on the props so a re-render with
+  // the same records does not rebuild — the identity of what the hook returns
+  // is load-bearing for `useEffect` dependencies (TIM-1285).
+  const value = useMemo(
+    () => ({
+      params: toNullProtoRecord(params),
+      slotParams: toNullProtoRecord(slotParams),
+    }),
+    [params, slotParams]
+  );
+
+  return createElement(ParamsContext.Provider, { value }, children);
+}
+
+// ─── Payload root ────────────────────────────────────────────────
+
+/**
+ * The client's root: publishes a payload's params over the tree being shown.
+ *
+ * Rendered at the same position in the wrapper chain on **every** render path
+ * — hydration, full navigation, partial navigation, popstate replay, shallow
+ * search sync, and revalidation from a server action. Being unconditional is
+ * load-bearing twice over: an element type that appears on one render and not
+ * the next remounts everything below it, destroying exactly the layout state a
+ * partial navigation exists to preserve; and a reader in a skipped layout has
+ * to have *some* provider above it on every path or it falls back to the
+ * module-level snapshot.
+ *
+ * `children` is the tree to display, which is not always `source`'s tree:
+ *
+ * - Full navigation, hydration, replay — `source` is the payload being shown,
+ *   and `children` is its own tree.
+ * - **Partial navigation** — `children` is the *retained* tree and `source` is
+ *   the *incoming* payload. This is the case the whole design exists for: the
+ *   retained tree is not re-rendered, so the destination's params can only
+ *   reach it from above, and this provider is above it.
+ *
+ * `source` may be a thenable, in which case this suspends on the payload's
+ * root row. That happens on the hydration path only, where the payload
+ * promise was going to be rendered at this position anyway. Every other path
+ * resolves the row in the router — inside the navigation transition — and
+ * hands over a settled value, so a decode rejection surfaces where React
+ * renders the tree and is caught by the error boundary *around* it, rather
+ * than here, above every boundary the app has.
+ */
+export function PayloadRoot({ source, children }: { source: unknown; children?: React.ReactNode }) {
+  const resolved = isThenable(source) ? use(source) : source;
+  const { params, slotParams } = readPublishedParams(resolved);
+  return createElement(ParamsProvider, { params, slotParams }, children);
+}
+
+function isThenable(value: unknown): value is Promise<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === 'function'
+  );
+}

package/src/client/react-root.ts

@@ -0,0 +1,82 @@
+/**
+ * React root host — the one React root the router renders the page through.
+ *
+ * The router owns the displayed tree and drives React: every render is
+ * `startTransition(() => root.render(<NavigationRoot rendered={…} />))`,
+ * synchronous, with a fresh `rendered` object whose `publish` NavigationRoot
+ * runs when React commits that tree (TIM-1301, TIM-1431).
+ *
+ * The root itself is created lazily. On the RSC-payload path `hydrate()`
+ * creates it by hydrating the server HTML. On the JS-only path (no inlined
+ * payload, TIM-600) nothing may create it at bootstrap — `createRoot(document)`
+ * followed by a render would take React ownership of the document and blank
+ * the SSR HTML — so the first `render()` (the first navigation, or a
+ * revalidation after a server action) creates it with the tree it renders.
+ * That first render carries no placeholder, and a fresh root with nothing
+ * committed leaves the container alone until it can commit, so the SSR HTML
+ * stays until the destination is ready (TIM-580).
+ *
+ * `container` is `document` in production; tests pass an element.
+ */
+
+import { addTransitionType, createElement, startTransition, type ReactNode } from 'react';
+import { createRoot, hydrateRoot, type HydrationOptions, type Root } from 'react-dom/client';
+import { NavigationRoot, type NavigationRender, type RenderedTree } from './navigation-root.tsx';
+import type { TopLoaderConfig } from './top-loader.tsx';
+
+export interface ReactRootHost {
+  /**
+   * Hydrate the server HTML with `element` as the initial tree. Nothing is
+   * published on that commit — the router made the page current before
+   * handing it over (`RouterInstance.hydrate`), and React may never commit
+   * it: an early render switches the root to client rendering.
+   */
+  hydrate(element: ReactNode, options?: HydrationOptions): void;
+  /**
+   * Hand a tree to React in a synchronous transition; `publish` runs when
+   * React commits it. Creates the root on first use.
+   */
+  render: NavigationRender;
+  /** Tear the root down (tests). */
+  unmount(): void;
+}
+
+export function createReactRoot(options: {
+  container: Document | Element;
+  topLoaderConfig?: TopLoaderConfig;
+}): ReactRootHost {
+  const { container, topLoaderConfig } = options;
+  let root: Root | null = null;
+
+  const rootElement = (rendered: RenderedTree) =>
+    createElement(NavigationRoot, { rendered, topLoaderConfig });
+
+  return {
+    hydrate(element, hydrationOptions) {
+      root = hydrateRoot(container, rootElement({ element, publish: null }), hydrationOptions);
+    },
+    render(element, publish, types) {
+      const target = (root ??= createRoot(container));
+      // Synchronous, and returns nothing: an async callback would drop the
+      // transition scope at its first await, and a returned thenable would
+      // open an action scope that holds the commit until it settles
+      // (TIM-1306, TIM-1307 — see client/navigation-transition.ts).
+      //
+      // The view transition types go in this scope and no other: React
+      // queues them on the root when the scope closes, and only if the root
+      // then has a transition pending — which `target.render` just made true.
+      // They are claimed by the next transition-only commit, so from here
+      // until this tree commits, another transition commit on the root can
+      // take them, and a superseding render merges its types with these
+      // (design/37-navigation-api.md §"The claim window", TIM-1471).
+      startTransition(() => {
+        for (const type of types) addTransitionType(type);
+        target.render(rootElement({ element, publish }));
+      });
+    },
+    unmount() {
+      root?.unmount();
+      root = null;
+    },
+  };
+}

package/src/client/router-effects.ts

@@ -0,0 +1,235 @@
+/**
+ * Router Effects — full-page navigation and post-paint scroll.
+ *
+ * The two things the router does *to the document* rather than to its own
+ * state: leaving the SPA entirely, and moving the scroll position once React
+ * has committed. Extracted from `router.ts` to keep that file focused on
+ * navigation state (see design/18-build-system.md §"No file >500 lines").
+ *
+ * See design/19-client-navigation.md §"Scroll Restoration"
+ */
+
+import { setHardNavigating } from './navigation-root.tsx';
+import type { RenderOwner } from './navigation-transition.ts';
+import { RedirectError, ServerErrorResponse, NonRscResponse } from './rsc-fetch.ts';
+import { recordSkew } from './router-skew.ts';
+
+/** The subset of `RouterDeps` the post-paint scroll effects need. */
+export interface ScrollEffectDeps {
+  scrollTo: (x: number, y: number) => void;
+  afterPaint?: (callback: () => void) => void;
+  scrollToHash?: (hash: string) => boolean;
+}
+
+export interface ScrollEffects {
+  /**
+   * Schedule scroll restoration after the next paint and fire the
+   * scroll-restored event. Used by navigate, popstate, and refresh.
+   */
+  restoreScrollAfterPaint: (scrollY: number) => void;
+  /**
+   * Scroll to the element matching the URL #fragment after paint, falling
+   * back to scroll-to-top when no element matches (matching full-page-load
+   * behavior for an unknown fragment). Used by forward navigation to a
+   * hash-bearing URL (TIM-1035).
+   */
+  scrollToHashAfterPaint: (hash: string) => void;
+}
+
+export function createScrollEffects(deps: ScrollEffectDeps): ScrollEffects {
+  /** Run a callback after the next paint (after React commit). */
+  function afterPaint(callback: () => void): void {
+    if (deps.afterPaint) {
+      deps.afterPaint(callback);
+    } else {
+      callback();
+    }
+  }
+
+  function restoreScrollAfterPaint(scrollY: number): void {
+    afterPaint(() => {
+      deps.scrollTo(0, scrollY);
+      window.dispatchEvent(new Event('timber:scroll-restored'));
+    });
+  }
+
+  function scrollToHashAfterPaint(hash: string): void {
+    afterPaint(() => {
+      if (deps.scrollToHash?.(hash) !== true) {
+        deps.scrollTo(0, 0);
+      }
+      window.dispatchEvent(new Event('timber:scroll-restored'));
+    });
+  }
+
+  return { restoreScrollAfterPaint, scrollToHashAfterPaint };
+}
+
+/**
+ * Leave the SPA and never come back.
+ *
+ * Every router path that gives up on client-side navigation does the same
+ * three things: flag the hard navigation so the Navigation API and React stop
+ * acting on a dying document, perform the document load, then block forever so
+ * the caller cannot carry on rendering into it. The returned promise is
+ * deliberately unresolvable — `location` assignment does not stop this turn of
+ * the event loop.
+ *
+ * Callers: server error, non-RSC response, and every version skew path
+ * ([33-version-skew.md](../../../../design/33-version-skew.md)).
+ */
+export function leaveSpa(url: string, fromUrl: string): Promise<never> {
+  setHardNavigating(true);
+  hardNavigate(url, fromUrl);
+  return new Promise<never>(() => {});
+}
+
+export interface SpaExitDeps {
+  /** The owner that holds the router right now, or null when idle. */
+  currentOwner: () => RenderOwner | null;
+  /** Supersede whatever is in flight and take ownership. */
+  supersede: () => void;
+}
+
+export interface SpaExits {
+  /**
+   * Leave the SPA — but only if `owner` still owns the router. Every
+   * failure a navigation can end on (a server error, a non-RSC response, a
+   * version skew) can surface long after the user has clicked something else:
+   * a fetch that was never cancellable, a Flight thenable that rejects late.
+   * Hard navigating to the abandoned URL would undo that click, so a
+   * navigation that no longer owns the router does nothing and lets the one
+   * that does drive. Never resolves when it does navigate.
+   *
+   * Must be called from inside the `runNavigation()` callback. That function's
+   * `finally` clears the current controller, so an ownership check downstream
+   * of it compares against `null` and never leaves at all.
+   */
+  leaveSpaIfOwned: (owner: RenderOwner, url: string, fromUrl: string) => Promise<void>;
+
+  /**
+   * Leave the SPA from a path that never entered `runNavigation()` — the
+   * stale-client short circuits, which decide before any fetch is attempted.
+   *
+   * Supersedes first. Nothing else on those paths takes ownership, so without
+   * it an in-flight navigation keeps the router: when its fetch or decode
+   * fails a moment later it still passes its own ownership check and hard
+   * navigates to *its* URL, overwriting the document load started here.
+   */
+  leaveSpaSuperseding: (url: string, fromUrl: string) => Promise<never>;
+}
+
+/**
+ * The two ownership-aware ways out of the SPA.
+ *
+ * Both wrap {@link leaveSpa} with the question "is this navigation still the
+ * one the user is waiting for?" — asked before leaving on a failure, answered
+ * by force on a path that decided before any navigation began. They live
+ * together because every caller of `leaveSpa()` needs one or the other, and
+ * an unguarded call is the bug (TIM-1275, TIM-1276).
+ */
+export function createSpaExits({ currentOwner, supersede }: SpaExitDeps): SpaExits {
+  async function leaveSpaIfOwned(owner: RenderOwner, url: string, fromUrl: string): Promise<void> {
+    if (currentOwner() !== owner) return;
+    await leaveSpa(url, fromUrl);
+  }
+
+  function leaveSpaSuperseding(url: string, fromUrl: string): Promise<never> {
+    supersede();
+    return leaveSpa(url, fromUrl);
+  }
+
+  return { leaveSpaIfOwned, leaveSpaSuperseding };
+}
+
+export interface NavigationRecoveryDeps {
+  /** The owner that holds the router right now, or null when idle. */
+  currentOwner: () => RenderOwner | null;
+  leaveSpaIfOwned: SpaExits['leaveSpaIfOwned'];
+  /**
+   * Replace the current entry with `url` — the router's own `navigate()`,
+   * rendering with `types`: the view transition types of the render the
+   * redirect interrupted, so a redirected Back still animates as Back and a
+   * link's own `transitionTypes` survive the hop (TIM-1471).
+   */
+  navigate: (url: string, types: readonly string[]) => Promise<void>;
+}
+
+/**
+ * Answer the failures an RSC fetch can end on, or report that this one is not
+ * ours to answer.
+ *
+ * Returns `true` when the error was handled; the caller rethrows on `false`.
+ * Handling a failure by leaving the SPA never resolves at all — the document
+ * is going away and the caller must not carry on rendering into it.
+ *
+ * There is exactly one family of these and one response to it, so it lives in
+ * one function rather than once per fetch path. `navigate()`, `refresh()` and
+ * an uncached traversal all reach it: the latter two used to rethrow instead,
+ * and since nobody awaits a traversal that meant pressing Back on a 500 left
+ * the user on the old document with an unhandled rejection (TIM-1277).
+ *
+ * Order matters in exactly one way: `recordSkew()` ends in error-*text*
+ * matching, so it goes last and can never pre-empt a framework control-flow
+ * signal whose message happens to read like a stale bundle. The class checks
+ * above it are mutually exclusive, so their order is free.
+ *
+ * Must be called from inside the `runNavigation()` callback — see
+ * {@link SpaExits.leaveSpaIfOwned}.
+ */
+export function createNavigationRecovery({
+  currentOwner,
+  leaveSpaIfOwned,
+  navigate,
+}: NavigationRecoveryDeps) {
+  return async function recoverFromNavigationError(
+    error: unknown,
+    owner: RenderOwner,
+    url: string,
+    fromUrl: string,
+    /** The view transition types of the render that failed. */
+    types: readonly string[]
+  ): Promise<boolean> {
+    if (error instanceof RedirectError) {
+      // Same ownership rule as leaving the SPA: a superseded navigation must
+      // not steer the document to the destination it was abandoned for.
+      if (currentOwner() !== owner) return true;
+      await navigate(error.redirectUrl, types);
+      return true;
+    }
+    // A server error, a non-RSC response and a version skew all end the same
+    // way: hand `url` back to the server as a document load, so it can render
+    // the outcome as HTML (design/10-error-handling.md §"Error Page Rendering
+    // for Client Navigation").
+    if (
+      error instanceof ServerErrorResponse ||
+      error instanceof NonRscResponse ||
+      recordSkew(error)
+    ) {
+      await leaveSpaIfOwned(owner, url, fromUrl);
+      return true;
+    }
+    return false;
+  };
+}
+
+/**
+ * Perform the full document load.
+ *
+ * `fromUrl` is the URL the navigation departed from, passed explicitly
+ * because the address bar may have already been updated.
+ *
+ * When the target differs from the departure point only by #fragment,
+ * assigning `href` is a hash change, not a load — so assign first (to update
+ * the address bar) and then reload (TIM-1235).
+ */
+export function hardNavigate(url: string, fromUrl: string): void {
+  const current = new URL(fromUrl, window.location.origin);
+  const target = new URL(url, window.location.origin);
+  if (target.pathname === current.pathname && target.search === current.search) {
+    window.location.href = url;
+    window.location.reload();
+  } else {
+    window.location.href = url;
+  }
+}