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

package/src/server/ssr-wrappers.tsx

@@ -0,0 +1,162 @@
+/**
+ * SSR wrapper chain — the same components the client hydration tree renders.
+ *
+ * During hydration, React's useId() generates deterministic IDs based on
+ * the component's position in the fiber tree. If the SSR tree has fewer
+ * wrapper components than the client hydration tree, every useId() call
+ * produces different IDs — causing hydration mismatches in libraries like
+ * Radix UI that rely on useId() internally.
+ *
+ * The client tree (`renderTree` in browser-entry/router-init.ts, used by
+ * hydrate.ts too) wraps the RSC element with:
+ *   NavigationRoot → Fragment(TopLoader, ...) →
+ *     TimberNuqsAdapter → NuqsAdapterProvider →
+ *       SlotContentCacheContext.Provider → SegmentUpdateContext.Provider →
+ *         NavigationProvider → PayloadRoot → ParamsProvider → element
+ *
+ * The SSR tree renders the REAL NavigationProvider and PayloadRoot rather
+ * than no-op mirrors (TIM-1424). Two consequences:
+ *
+ * 1. `usePathname()` / `useSearchParams()` resolve from NavigationContext
+ *    during SSR — the same code path as the browser — with the request's
+ *    pathname and raw search string. The raw string preserves repeated
+ *    query keys (`?tag=a&tag=b`) and, since TIM-1428, is the only
+ *    representation of search state here — it feeds the nuqs SSR adapter
+ *    too, so no collapsed record exists to drift from it.
+ * 2. `useSegmentParams()` resolves from ParamsContext, published by
+ *    PayloadRoot from the same payload root row the browser will read —
+ *    one derivation on both sides instead of two that must agree.
+ *
+ * Per-request isolation is by construction: the provider values are part
+ * of this request's element tree, so concurrent requests cannot observe
+ * each other's values — stronger than the ALS path, which remains for
+ * `useCookie()`.
+ *
+ * **What actually shifts a useId is a fork, not depth.** `useId` derives from
+ * React's tree context, which only changes where a fiber has more than one
+ * child — here, `Fragment(TopLoader, element)`. A single-child wrapper, plain
+ * component or context provider, leaves every id below it unchanged; that is
+ * verified by tests/ssr-wrapper-parity.test.ts, not assumed. So the
+ * client-only `SegmentUpdateContext.Provider` and
+ * `SlotContentCacheContext.Provider` (single child each) have no mirror
+ * here and need none. Mirror a new wrapper only if it branches.
+ *
+ * Related issues: facebook/react#24669, radix-ui/primitives#3700
+ * See design/02-rendering-pipeline.md §"RSC → SSR → Client Hydration"
+ */
+
+import { createElement, Fragment, type ReactNode } from 'react';
+import { withNuqsSsrAdapter } from './nuqs-ssr-provider.tsx';
+import { NavigationProvider } from '../client/navigation-context.ts';
+import { PayloadRoot } from '../client/params-context.ts';
+
+/**
+ * SSR equivalent of NavigationRoot.
+ *
+ * On the client, the router renders NavigationRoot via `root.render` in a transition,
+ * rendering `Fragment(TopLoader, element)` — or the element alone when the top
+ * loader is disabled.
+ *
+ * The Fragment is the part that matters: it forks, so it advances React's tree
+ * context. Both sides must agree on whether it is there, which is why
+ * `hasTopLoader` is threaded in from the same config the client reads.
+ */
+function SsrNavigationRoot({
+  children,
+  hasTopLoader,
+}: {
+  children?: ReactNode;
+  hasTopLoader: boolean;
+}): ReactNode {
+  if (hasTopLoader) {
+    return createElement(Fragment, null, createElement(SsrTopLoader, null), children);
+  }
+  return children as ReactNode;
+}
+
+/**
+ * SSR equivalent of TopLoader.
+ * Exists as a fiber node to match the client tree depth; renders nothing.
+ */
+function SsrTopLoader(): ReactNode {
+  return null;
+}
+
+/**
+ * SSR equivalent of TimberNuqsAdapter component boundary.
+ * The actual NuqsAdapterProvider (from createAdapterProvider) is added
+ * inside this wrapper via withNuqsSsrAdapter, matching the client's
+ * TimberNuqsAdapter → NuqsAdapterProvider nesting.
+ */
+function SsrNuqsWrapper({ search, children }: { search: string; children?: ReactNode }): ReactNode {
+  // withNuqsSsrAdapter creates a NuqsAdapterProvider (from createAdapterProvider),
+  // which is the same component factory used by TimberNuqsAdapter on the client.
+  // Both produce the same internal component boundary depth.
+  return withNuqsSsrAdapter(search, children);
+}
+
+/** Per-request inputs for the SSR wrapper chain. */
+export interface SsrWrapOptions {
+  /** Request pathname for NavigationProvider. */
+  pathname: string;
+  /**
+   * Raw app-visible query string (`''` or `?…`) for NavigationProvider AND
+   * the nuqs SSR adapter — one representation, preserving repeated keys
+   * (`?tag=a&tag=b`) on both consumers (TIM-1428).
+   */
+  search: string;
+  /**
+   * The payload's params, or a thenable of them, for PayloadRoot — the
+   * `params` half of `splitPayloadRoot(root)`. Same source the browser
+   * hands to the same component during hydration.
+   */
+  paramsSource: unknown;
+  /** Whether the top loader is enabled (must match client config). */
+  hasTopLoader: boolean;
+}
+
+/**
+ * Wrap the SSR element tree with the same component boundaries as the
+ * client hydration tree — real providers, not mirrors — so hooks resolve
+ * identically on both sides and useId() matches.
+ *
+ * Client tree (browser-entry/hydrate.ts):
+ *   NavigationRoot
+ *     → Fragment(TopLoader, element)
+ *       → TimberNuqsAdapter
+ *         → NuqsAdapterProvider (from createAdapterProvider)
+ *           → SlotContentCacheContext.Provider (client-only, single child)
+ *             → SegmentUpdateContext.Provider  (client-only, single child)
+ *               → NavigationProvider
+ *                 → PayloadRoot → ParamsProvider
+ *                   → [RSC element]
+ *
+ * SSR tree (this function):
+ *   SsrNavigationRoot
+ *     → Fragment(SsrTopLoader, element)
+ *       → SsrNuqsWrapper
+ *         → NuqsAdapterProvider (from withNuqsSsrAdapter → createAdapterProvider)
+ *           → NavigationProvider              (real — same component)
+ *             → PayloadRoot → ParamsProvider  (real — same components)
+ *               → [RSC element]
+ */
+export function wrapSsrElement(element: ReactNode, opts: SsrWrapOptions): ReactNode {
+  // Build inside-out to match the client's createElement chain in
+  // browser-entry/router-init.ts renderTree(), which hydration builds with too.
+
+  // 1. Innermost: PayloadRoot publishes the payload's params over the tree.
+  const withParams = createElement(PayloadRoot, { source: opts.paramsSource }, element);
+
+  // 2. NavigationProvider with the request's address-bar state.
+  const withNav = createElement(
+    NavigationProvider,
+    { value: { pathname: opts.pathname, search: opts.search } },
+    withParams
+  );
+
+  // 3. TimberNuqsAdapter equivalent (wraps withNuqsSsrAdapter for the actual nuqs provider)
+  const withNuqs = createElement(SsrNuqsWrapper, { search: opts.search }, withNav);
+
+  // 4. Outermost: NavigationRoot equivalent (the TopLoader fork)
+  return createElement(SsrNavigationRoot, { hasTopLoader: opts.hasTopLoader }, withNuqs);
+}

package/src/server/state-tree-diff.ts

@@ -14,26 +14,53 @@
  * See design/13-security.md §"State tree manipulation"
  */
 
+import { swallow } from './logger.ts';
+
+// ─── State Tree Parsing ──────────────────────────────────────────
+
+/** Parsed client state tree with segment paths and optional slot paths. */
+export interface ClientStateTree extends Set<string> {
+  slots?: Set<string> | null;
+  /**
+   * `app/` directory paths of the segments currently mounted on the client.
+   * Read only by interception scoping — never by the skip decisions.
+   * See design/07-routing.md §"Intercepting Routes" (TIM-1282).
+   */
+  treePaths?: Set<string> | null;
+}
+
 /**
  * Parse the X-Timber-State-Tree header from a request.
  *
- * Returns a Set of segment paths the client has cached, or null if
+ * Returns a Set of segment paths the client has cached (with an
+ * additional `slots` property for cached slot paths), or null if
  * the header is missing, malformed, or empty. Parsing happens before
  * renderToReadableStream — not inside the React render pass.
  *
- * @returns Set of sync segment paths, or null if no valid state tree
+ * @returns ClientStateTree with segments and slots, or null if no valid state tree
  */
-export function parseClientStateTree(req: Request): Set<string> | null {
+export function parseClientStateTree(req: Request): ClientStateTree | null {
   const header = req.headers.get('X-Timber-State-Tree');
   if (!header) return null;
 
   try {
-    const parsed = JSON.parse(header) as { segments?: unknown };
-    if (!Array.isArray(parsed.segments) || parsed.segments.length === 0) {
+    const parsed = JSON.parse(header) as {
+      segments?: unknown;
+      slots?: unknown;
+      treePaths?: unknown;
+    };
+    const hasSegments = Array.isArray(parsed.segments) && parsed.segments.length > 0;
+    const hasSlots = Array.isArray(parsed.slots) && parsed.slots.length > 0;
+    const hasTreePaths = Array.isArray(parsed.treePaths) && parsed.treePaths.length > 0;
+    if (!hasSegments && !hasSlots && !hasTreePaths) {
       return null;
     }
-    return new Set(parsed.segments as string[]);
-  } catch {
+    const result = new Set(hasSegments ? (parsed.segments as string[]) : []) as ClientStateTree;
+    result.slots = hasSlots ? new Set(parsed.slots as string[]) : null;
+    result.treePaths = hasTreePaths ? new Set(parsed.treePaths as string[]) : null;
+    return result;
+  } catch (err) {
+    swallow(err, 'malformed X-Timber-State-Tree header');
     return null;
   }
 }
@@ -42,36 +69,64 @@ export function parseClientStateTree(req: Request): Set<string> | null {
  * Determine whether a segment's layout rendering can be skipped.
  *
  * A segment is skipped when ALL of the following are true:
- * 1. The client has the segment in its state tree (clientSegments contains urlPath)
- * 2. The layout is sync (not an async function — async layouts always re-render)
- * 3. The segment is NOT the leaf (pages are never cached across navigations)
+ * 1. The client sent a state tree (clientSegments is non-null)
+ * 2. The client has this segment cached (clientSegments contains urlPath)
+ * 3. The segment has a layout (otherwise nothing to skip)
+ * 4. The layout is sync (not an async function — async layouts may depend
+ *    on per-request data and must always re-render)
+ * 5. The segment is NOT the leaf (pages are never cached across navigations)
+ *
+ * Additional constraints enforced by the caller (buildRouteElement):
+ * - Must have a rendered layout below (so SegmentOutlet has content to show)
+ * - Skipped segments must form a contiguous prefix from root
  *
  * Access.ts still runs for skipped segments — this is enforced by the caller
- * (buildRouteElement) which runs all access checks before building the tree.
+ * which wraps with AccessGate regardless of skip status.
  *
- * @param urlPath - The segment's URL path (e.g., "/", "/dashboard")
+ * @param segmentKey - The segment's state-tree key from computeSegmentKeys()
  * @param layoutComponent - The loaded layout component function
  * @param isLeaf - Whether this is the leaf segment (page segment)
  * @param clientSegments - Set of paths from X-Timber-State-Tree, or null
  */
 export function shouldSkipSegment(
-  _urlPath: string,
-  _layoutComponent: ((...args: unknown[]) => unknown) | undefined,
-  _isLeaf: boolean,
-  _clientSegments: Set<string> | null
+  segmentKey: string,
+  layoutComponent: ((...args: unknown[]) => unknown) | undefined,
+  isLeaf: boolean,
+  clientSegments: Set<string> | null
 ): boolean {
-  // DISABLED: Client-side segment merging via React element tree walking
-  // is too fragile for production. The merger's replaceInnerSegment relies
-  // on walking RSC-decoded element trees to find SegmentProvider boundaries,
-  // but production trees contain structures the walker can't handle:
-  // Suspense wrappers, error boundaries, AccessGate components, React lazy
-  // refs, and client component module references.
-  //
-  // The merger infrastructure (segment-merger.ts, element cache, state tree
-  // filtering) is in place and tested. Re-enable when the merger can handle
-  // real RSC element trees — likely requires a SegmentOutlet client component
-  // approach instead of post-hoc element tree walking.
-  //
-  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  return false;
+  if (!clientSegments) return false;
+  if (!clientSegments.has(segmentKey)) return false;
+  if (!layoutComponent) return false;
+  if (isLeaf) return false;
+
+  // Pre-render guard: async layouts may depend on per-request data.
+  // Taint tracking (runInTaintScope) handles the post-render client-side
+  // caching decision via X-Timber-Segments. This server-side check remains
+  // conservative because taint results aren't available at element-build time.
+  if (layoutComponent.constructor.name === 'AsyncFunction') return false;
+
+  return true;
+}
+
+// ─── Slot Skip Decision ─────────────────────────────────────────
+
+/**
+ * Determine whether a parallel route slot can be skipped.
+ *
+ * A slot is skipped when the destination content key — computed from the
+ * owning segment's URL parts, the slot name, the matched entry file, and
+ * the slot's extracted params — is in the set of keys the client advertised.
+ *
+ * This replaced URL-based departing/destination diffing in TIM-1370.
+ * The previous approach reconstructed the client's state by re-matching a
+ * departing URL against each slot's sub-tree, which was a recurring bug
+ * source because the reconstruction could drift from the client's actual
+ * mounted state. The key-based approach is a single set-membership check.
+ *
+ * This is a performance optimization only, NOT a security boundary.
+ * Slot access.ts always runs via SlotAccessGate regardless.
+ */
+export function shouldSkipSlot(contentKey: string, clientSlotKeys: Set<string> | null): boolean {
+  if (!clientSlotKeys) return false;
+  return clientSlotKeys.has(contentKey);
 }