@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

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

@@ -14,26 +14,96 @@
  * See design/13-security.md §"State tree manipulation"
  */
 
+import { swallow } from './logger.js';
+import { matchUrlParts } from './tree-match.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+
+// ─── Segment Key Computation ─────────────────────────────────────
+
+/**
+ * Segment node shape expected by computeSegmentKeys.
+ * Matches the relevant fields from ManifestSegmentNode without
+ * importing it (avoids circular deps from routing → server).
+ */
+interface SegmentKeyInput {
+  urlPath: string;
+  segmentName?: string;
+  segmentType?: string;
+}
+
+/**
+ * Compute state-tree keys for a segment chain.
+ *
+ * Non-group segments use their urlPath as-is. Route groups accumulate
+ * ancestor group names to produce globally unique keys:
+ *   app/(a)/(shared)/dashboard → keys: ['/', '/(a)', '/(a)/(shared)', '/dashboard']
+ *
+ * This is the single source of truth for segment keys — used by the
+ * element builder (skip decisions, SegmentOutlet props), segment info
+ * (X-Timber-Segments header), and the client cache/state tree.
+ */
+export function computeSegmentKeys(segments: SegmentKeyInput[]): string[] {
+  const keys: string[] = [];
+  let prevKey = '';
+
+  for (const segment of segments) {
+    if (segment.segmentType === 'group') {
+      const base = prevKey === '/' ? '' : prevKey;
+      const key = `${base}/${segment.segmentName}`;
+      keys.push(key);
+      prevKey = key;
+    } else {
+      keys.push(segment.urlPath);
+      prevKey = segment.urlPath;
+    }
+  }
+
+  return keys;
+}
+
+/**
+ * Compute a unique key for a parallel route slot.
+ * Format: `{parentSegmentId}/@{slotName}`, e.g. `/@sidebar` or `/dashboard/@modal`.
+ */
+export function computeSlotKey(parentSegmentId: string, slotName: string): string {
+  const name = slotName.startsWith('@') ? slotName : `@${slotName}`;
+  const prefix = parentSegmentId === '/' ? '' : parentSegmentId;
+  return `${prefix}/${name}`;
+}
+
+// ─── State Tree Parsing ──────────────────────────────────────────
+
+/** Parsed client state tree with segment paths and optional slot paths. */
+export interface ClientStateTree extends Set<string> {
+  slots?: 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 };
+    const hasSegments = Array.isArray(parsed.segments) && parsed.segments.length > 0;
+    const hasSlots = Array.isArray(parsed.slots) && parsed.slots.length > 0;
+    if (!hasSegments && !hasSlots) {
       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;
+    return result;
+  } catch (err) {
+    swallow(err, 'malformed X-Timber-State-Tree header');
     return null;
   }
 }
@@ -42,36 +112,113 @@ 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 ─────────────────────────────────────────
+
+interface ShouldSkipSlotArgs {
+  slotKey: string;
+  clientSlots: Set<string> | null;
+  slotNode: ManifestSegmentNode;
+  departingUrlParts: string[];
+  destinationUrlParts: string[];
+}
+
+/**
+ * Determine whether a parallel route slot can be skipped.
+ *
+ * A slot is skipped when ALL of:
+ * 1. The client has this slot cached (slotKey is in clientSlots)
+ * 2. The slot's matched page is the SAME for both the departing and
+ *    destination URLs (same page file + same extracted params)
+ *
+ * The comparison uses matchUrlParts to find what each URL would match
+ * in the slot's sub-tree, then compares the matched page file and params.
+ *
+ * This is a performance optimization only, NOT a security boundary.
+ * Slot access.ts always runs via SlotAccessGate regardless.
+ */
+export function shouldSkipSlot({
+  slotKey,
+  clientSlots,
+  slotNode,
+  departingUrlParts,
+  destinationUrlParts,
+}: ShouldSkipSlotArgs): boolean {
+  if (!clientSlots) return false;
+  if (!clientSlots.has(slotKey)) return false;
+
+  const departingMatch = matchUrlParts(slotNode, departingUrlParts);
+  const destinationMatch = matchUrlParts(slotNode, destinationUrlParts);
+
+  // Both null (no match) — slot shows default.tsx in both cases
+  if (!departingMatch && !destinationMatch) return true;
+  // One null, one not — match changed
+  if (!departingMatch || !destinationMatch) return false;
+
+  const departingLeaf = departingMatch.chain[departingMatch.chain.length - 1];
+  const destinationLeaf = destinationMatch.chain[destinationMatch.chain.length - 1];
+
+  // Both must have a page, and the page file must be the same
+  if (!departingLeaf.page || !destinationLeaf.page) {
+    return !departingLeaf.page && !destinationLeaf.page;
+  }
+  if (departingLeaf.page.filePath !== destinationLeaf.page.filePath) return false;
+
+  // Compare extracted params — if any differ, the slot content may change
+  return paramsEqual(departingMatch.params, destinationMatch.params);
+}
+
+function paramsEqual(
+  a: Record<string, string | string[]>,
+  b: Record<string, string | string[]>
+): boolean {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    const va = a[key];
+    const vb = b[key];
+    if (Array.isArray(va) && Array.isArray(vb)) {
+      if (va.length !== vb.length || va.some((v, i) => v !== vb[i])) return false;
+    } else if (va !== vb) {
+      return false;
+    }
+  }
+  return true;
 }

package/src/server/status-code-resolver.ts

@@ -5,6 +5,12 @@
  * correct file to render by walking the fallback chain described in
  * design/10-error-handling.md §"Status-Code Files".
  *
+ * **Generic over `TFile`** (TIM-848). Walks `SegmentNode<TFile>` trees
+ * regardless of whether `TFile` is the build-time `RouteFile` or the
+ * runtime `ManifestFile`. Before TIM-848 there were two near-identical
+ * resolvers — one for the Map-based scanner output and one for the
+ * object-based runtime manifest. Now there is one.
+ *
  * Supports two format families:
  * - 'component' (default): .tsx/.jsx/.mdx status files → React rendering pipeline
  * - 'json': .json status files → raw JSON response, no React
@@ -17,17 +23,16 @@
  *   Pass 3 — error.tsx (leaf → root)
  *   Pass 4 — framework default (returns null)
  *
- * **JSON chain (4xx):**
- *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
+ * **JSON chain (4xx and 5xx):**
+ *   Pass 1 — json status files (leaf → root): {status}.json → {category}.json
  *   Pass 2 — framework default JSON (returns null, caller provides bare JSON)
  *
- * **5xx (component only):**
+ * **5xx component:**
  *   Per-segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
- *   Then global-error.tsx (future)
  *   Then framework default (returns null)
  */
 
-import type { SegmentNode, RouteFile } from '#/routing/types.js';
+import type { SegmentNode } from '../routing/types.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -42,9 +47,9 @@ export type StatusFileKind =
 export type StatusFileFormat = 'component' | 'json';
 
 /** Result of resolving a status-code file for a segment chain. */
-export interface StatusFileResolution {
+export interface StatusFileResolution<TFile> {
   /** The matched route file. */
-  file: RouteFile;
+  file: TFile;
   /** The HTTP status code (always the original status, not the file's code). */
   status: number;
   /** How the file was matched. */
@@ -57,9 +62,9 @@ export interface StatusFileResolution {
 export type SlotDeniedKind = 'denied' | 'default';
 
 /** Result of resolving a slot denied file. */
-export interface SlotDeniedResolution {
+export interface SlotDeniedResolution<TFile> {
   /** The matched route file (denied.tsx or default.tsx). */
-  file: RouteFile;
+  file: TFile;
   /** Slot name without @ prefix. */
   slotName: string;
   /** How the file was matched. */
@@ -70,14 +75,61 @@ export interface SlotDeniedResolution {
 
 /**
  * Maps legacy file convention names to their corresponding HTTP status codes.
- * Only used in the 4xx component fallback chain.
+ * Only used in the 4xx component fallback chain. Exported so the in-tree
+ * deny chain (deny-boundary.ts) uses the same mapping — see TIM-1081.
  */
-const LEGACY_FILE_TO_STATUS: Record<string, number> = {
+export const LEGACY_FILE_TO_STATUS: Record<string, number> = {
   'not-found': 404,
   'forbidden': 403,
   'unauthorized': 401,
 };
 
+/** Reverse index: status code → legacy file name. Built once at module load. */
+const STATUS_TO_LEGACY_FILE: Record<number, string> = Object.fromEntries(
+  Object.entries(LEGACY_FILE_TO_STATUS).map(([name, status]) => [status, name])
+);
+
+// ─── Lookup Helpers ──────────────────────────────────────────────────────
+
+/**
+ * Look up `{statusStr}` then `{categoryKey}` (e.g. "4xx" / "5xx") in a
+ * status-file group on a single segment. Shared by all three fallback
+ * chains — the only structural difference between component 4xx,
+ * component 5xx, and JSON resolution is *which* group is searched and
+ * how the per-segment loop is layered around it.
+ */
+function lookupInGroup<TFile>(
+  group: Record<string, TFile> | undefined,
+  statusStr: string,
+  categoryKey: string,
+  segmentIndex: number,
+  status: number
+): StatusFileResolution<TFile> | null {
+  if (!group) return null;
+  const exact = group[statusStr];
+  if (exact) return { file: exact, status, kind: 'exact', segmentIndex };
+  const category = group[categoryKey];
+  if (category) return { file: category, status, kind: 'category', segmentIndex };
+  return null;
+}
+
+/**
+ * Look up the legacy convention file (`not-found.tsx` / `forbidden.tsx` /
+ * `unauthorized.tsx`) for `status` on a single segment. Returns null if
+ * `status` has no legacy mapping or the file isn't present.
+ */
+function lookupLegacy<TFile>(
+  group: Record<string, TFile> | undefined,
+  status: number,
+  segmentIndex: number
+): StatusFileResolution<TFile> | null {
+  if (!group) return null;
+  const name = STATUS_TO_LEGACY_FILE[status];
+  if (!name) return null;
+  const file = group[name];
+  return file ? { file, status, kind: 'legacy', segmentIndex } : null;
+}
+
 // ─── Resolver ────────────────────────────────────────────────────────────────
 
 /**
@@ -91,101 +143,50 @@ const LEGACY_FILE_TO_STATUS: Record<string, number> = {
  * @param segments - The matched segment chain from root (index 0) to leaf (last).
  * @param format - The response format family ('component' or 'json'). Defaults to 'component'.
  */
-export function resolveStatusFile(
+export function resolveStatusFile<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>,
+  segments: ReadonlyArray<SegmentNode<TFile>>,
   format: StatusFileFormat = 'component'
-): StatusFileResolution | null {
-  if (status >= 400 && status <= 499) {
-    return format === 'json' ? resolve4xxJson(status, segments) : resolve4xx(status, segments);
-  }
-  if (status >= 500 && status <= 599) {
-    // JSON format for 5xx uses the same json chain pattern
-    return format === 'json' ? resolve5xxJson(status, segments) : resolve5xx(status, segments);
-  }
-  return null;
+): StatusFileResolution<TFile> | null {
+  if (status < 400 || status > 599) return null;
+  if (format === 'json') return resolveJson(status, segments);
+  if (status <= 499) return resolve4xx(status, segments);
+  return resolve5xx(status, segments);
 }
 
 /**
- * 4xx component fallback chain (three separate passes):
- *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
- *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
- *   Pass 3 — error.tsx (leaf → root)
+ * 4xx component fallback chain — three separate full passes leaf→root.
+ *
+ * The passes must be separate (not interleaved per-segment) so that a
+ * root-level `404.tsx` beats a leaf-level `error.tsx`. The 5xx chain
+ * inverts this and is per-segment: a leaf's `error.tsx` beats a root's
+ * `5xx.tsx`. This asymmetry is the only reason these two functions exist
+ * separately.
+ *
+ *   Pass 1 — {status}.tsx → 4xx.tsx           (statusFiles)
+ *   Pass 2 — not-found / forbidden / unauthorized (legacyStatusFiles)
+ *   Pass 3 — error.tsx                         (error)
  */
-function resolve4xx(
+function resolve4xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
 
-  // Pass 1: status files across all segments (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.statusFiles) continue;
-
-    // Exact match first
-    const exact = segment.statusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    // Category catch-all
-    const category = segment.statusFiles.get('4xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
-  }
-
-  // Pass 2: legacy compat files (leaf → root)
   for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.legacyStatusFiles) continue;
-
-    for (const [name, legacyStatus] of Object.entries(LEGACY_FILE_TO_STATUS)) {
-      if (legacyStatus === status) {
-        const file = segment.legacyStatusFiles.get(name);
-        if (file) {
-          return { file, status, kind: 'legacy', segmentIndex: i };
-        }
-      }
-    }
+    const r = lookupInGroup(segments[i].statusFiles, statusStr, '4xx', i, status);
+    if (r) return r;
   }
 
-  // Pass 3: error.tsx (leaf → root)
   for (let i = segments.length - 1; i >= 0; i--) {
-    if (segments[i].error) {
-      return { file: segments[i].error!, status, kind: 'error', segmentIndex: i };
-    }
+    const r = lookupLegacy(segments[i].legacyStatusFiles, status, i);
+    if (r) return r;
   }
 
-  return null;
-}
-
-/**
- * 4xx JSON fallback chain (single pass):
- *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
- *   No legacy compat, no error.tsx — JSON chain terminates at category catch-all.
- */
-function resolve4xxJson(
-  status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
-  const statusStr = String(status);
-
   for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.jsonStatusFiles) continue;
-
-    // Exact match first
-    const exact = segment.jsonStatusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    // Category catch-all
-    const category = segment.jsonStatusFiles.get('4xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
+    const errorFile = segments[i].error;
+    if (errorFile) {
+      return { file: errorFile, status, kind: 'error', segmentIndex: i };
     }
   }
 
@@ -193,33 +194,22 @@ function resolve4xxJson(
 }
 
 /**
- * 5xx component fallback chain (single pass, per-segment):
- *   At each segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
+ * 5xx component fallback chain — single pass, per-segment leaf→root.
+ *
+ * At each segment: {status}.tsx → 5xx.tsx → error.tsx. A leaf's
+ * `error.tsx` therefore beats a root's `5xx.tsx`, which is the
+ * intentional inverse of the 4xx chain.
  */
-function resolve5xx(
+function resolve5xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
 
   for (let i = segments.length - 1; i >= 0; i--) {
     const segment = segments[i];
-
-    // Exact status file
-    if (segment.statusFiles) {
-      const exact = segment.statusFiles.get(statusStr);
-      if (exact) {
-        return { file: exact, status, kind: 'exact', segmentIndex: i };
-      }
-
-      // Category catch-all
-      const category = segment.statusFiles.get('5xx');
-      if (category) {
-        return { file: category, status, kind: 'category', segmentIndex: i };
-      }
-    }
-
-    // error.tsx at this segment level (for 5xx, checked per-segment)
+    const r = lookupInGroup(segment.statusFiles, statusStr, '5xx', i, status);
+    if (r) return r;
     if (segment.error) {
       return { file: segment.error, status, kind: 'error', segmentIndex: i };
     }
@@ -229,29 +219,22 @@ function resolve5xx(
 }
 
 /**
- * 5xx JSON fallback chain (single pass):
- *   At each segment (leaf → root): {status}.json → 5xx.json
- *   No error.tsx equivalent — JSON chain terminates at category catch-all.
+ * JSON fallback chain (for both 4xx and 5xx) — single pass leaf→root.
+ *
+ * At each segment: {status}.json → {category}.json. No legacy compat,
+ * no error.tsx — the JSON chain terminates at the category catch-all
+ * and the caller falls back to a bare-JSON framework default.
  */
-function resolve5xxJson(
+function resolveJson<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode>
-): StatusFileResolution | null {
+  segments: ReadonlyArray<SegmentNode<TFile>>
+): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
+  const categoryKey = status >= 500 ? '5xx' : '4xx';
 
   for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.jsonStatusFiles) continue;
-
-    const exact = segment.jsonStatusFiles.get(statusStr);
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    const category = segment.jsonStatusFiles.get('5xx');
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
+    const r = lookupInGroup(segments[i].jsonStatusFiles, statusStr, categoryKey, i, status);
+    if (r) return r;
   }
 
   return null;
@@ -267,7 +250,9 @@ function resolve5xxJson(
  *
  * @param slotNode - The segment node for the slot (segmentType === 'slot').
  */
-export function resolveSlotDenied(slotNode: SegmentNode): SlotDeniedResolution | null {
+export function resolveSlotDenied<TFile>(
+  slotNode: SegmentNode<TFile>
+): SlotDeniedResolution<TFile> | null {
   const slotName = slotNode.segmentName.replace(/^@/, '');
 
   if (slotNode.denied) {