@timber-js/app 0.2.0-alpha.17 → 0.2.0-alpha.170

package/src/server/slot-resolver.ts

@@ -16,33 +16,71 @@
  * See design/02-rendering-pipeline.md §"Parallel Slots"
  */
 
-import { TimberErrorBoundary } from '#/client/error-boundary.js';
-import SlotErrorFallback from '#/client/slot-error-fallback.js';
+import { TimberErrorBoundary } from '../client/error-boundary.js';
+import SlotErrorFallback from '../client/slot-error-fallback.js';
 import { SlotAccessGate } from './access-gate.js';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
+import { isClientReference } from './route-element-builder.js';
+import { loadModule } from './safe-load.js';
 import type { InterceptionContext, RouteMatch } from './pipeline.js';
-import { DenySignal } from './primitives.js';
+import { DenySignal, RedirectSignal } from './primitives.js';
+import { logRenderError } from './logger.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
+import { setSlotParams } from './request-context.js';
+import { coerceSlotParams } from './param-coercion.js';
+import { matchUrlParts } from './tree-match.js';
 
 type CreateElementFn = (...args: unknown[]) => React.ReactElement;
 
+// ─── Module Loading Helpers ─────────────────────────────────────────────────
+
+/**
+ * Load a module and extract its default export as a component function.
+ * Returns undefined if no default export exists.
+ */
+async function loadComponent(loader: {
+  load: () => Promise<unknown>;
+  filePath: string;
+}): Promise<((...args: unknown[]) => unknown) | undefined> {
+  const mod = await loadModule(loader);
+  return mod.default as ((...args: unknown[]) => unknown) | undefined;
+}
+
+/**
+ * Load and render the default.tsx fallback for a slot node.
+ * Returns null if the slot has no default.tsx or it has no default export.
+ */
+async function renderDefaultFallback(
+  slotNode: ManifestSegmentNode,
+  h: CreateElementFn
+): Promise<React.ReactElement | null> {
+  if (!slotNode.default) return null;
+  const DefaultComp = await loadComponent(slotNode.default);
+  if (!DefaultComp) return null;
+  return h(DefaultComp, {});
+}
+
+// ─── Slot Element Resolution ────────────────────────────────────────────────
+
 /**
  * Resolve the element for a parallel slot.
  *
  * Finds a matching page in the slot's sub-tree for the current route.
  * Falls back to default.tsx if no match, or null if no default.
  *
- * When a match is found, the element is wrapped with:
- * 1. Error boundaries from each segment in the slot's matched chain
- * 2. Layouts from each segment in the slot's matched chain
- * 3. SlotAccessGate if the slot root has access.ts
+ * When a match is found, the element is wrapped per segment in the slot's
+ * matched chain with (innermost → outermost):
+ * 1. Error boundaries
+ * 2. Layout
+ * 3. SlotAccessGate if the segment has access.ts (gate OUTSIDE the layout,
+ *    so a denied layout never executes — see TIM-1074)
  */
 export async function resolveSlotElement(
   slotNode: ManifestSegmentNode,
   match: RouteMatch,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn,
-  interception?: InterceptionContext
+  interception?: InterceptionContext,
+  parentTreePath?: string
 ): Promise<React.ReactElement | null> {
   // When interception is active, try to match intercepting children in this
   // slot against the target pathname. If an intercepting child matches, render
@@ -54,125 +92,89 @@ export async function resolveSlotElement(
     : findSlotMatch(slotNode, match);
 
   if (slotMatch) {
-    const mod = (await slotMatch.page.load()) as Record<string, unknown>;
-    if (mod.default) {
-      const SlotPage = mod.default as (...args: unknown[]) => unknown;
+    // Store per-slot params in ALS so getSegmentParams(segmentPath) returns
+    // the slot's own param types (e.g. catch-all → string[] vs dynamic → string).
+    if (parentTreePath && Object.keys(slotMatch.slotParams).length > 0) {
+      // Build the full tree path: parent prefix + slot chain segment names.
+      const slotSuffix = slotMatch.chain
+        .map((s) => s.segmentName)
+        .filter(Boolean)
+        .join('/');
+      const prefix = parentTreePath === '/' ? '' : parentTreePath;
+      const fullSlotPath = `${prefix}/${slotSuffix}`;
+
+      // Coerce slot params through global schema codecs (same as main route).
+      const coerced = coerceSlotParams(slotMatch.chain, slotMatch.slotParams);
+      setSlotParams(fullSlotPath, coerced);
+    }
 
+    const SlotPage = await loadComponent(slotMatch.page);
+    if (SlotPage) {
       // Load default.tsx fallback for notFound() handling in the slot page.
       // When a slot page calls notFound() or deny(), it should gracefully
       // degrade to default.tsx or null — not crash the page. This matches
       // Next.js behavior. See design/02-rendering-pipeline.md
       // §"Slot Access Failure = Graceful Degradation"
-      let denyFallback: React.ReactElement | null = null;
-      if (slotNode.default) {
-        const defaultMod = (await slotNode.default.load()) as Record<string, unknown>;
-        const DefaultComp = defaultMod.default as ((...args: unknown[]) => unknown) | undefined;
-        if (DefaultComp) {
-          denyFallback = h(DefaultComp, { params: paramsPromise, searchParams: {} });
-        }
-      }
-
-      // Wrap the slot page to catch DenySignal (from notFound() or deny())
-      // at the component level. This prevents the signal from reaching the
-      // RSC onError callback and being tracked as a page-level denial, which
-      // would cause the pipeline to replace the entire successful SSR response
-      // with a deny page. Instead, the slot gracefully degrades.
-      const denyFallbackCapture = denyFallback;
-      const SafeSlotPage = async (props: Record<string, unknown>) => {
-        try {
-          return await (SlotPage as (props: Record<string, unknown>) => unknown)(props);
-        } catch (error) {
-          if (error instanceof DenySignal) {
-            return denyFallbackCapture;
-          }
-          throw error;
-        }
-      };
-
-      let element: React.ReactElement = h(SafeSlotPage, {
-        params: paramsPromise,
-        searchParams: {},
-      });
-
-      // Wrap with error boundaries and layouts from intermediate slot segments
-      // (everything between slot root and leaf). Process innermost-first, same
-      // order as route-element-builder.ts handles main segments. The slot root
-      // (index 0) is handled separately after the access gate below.
-      for (let i = slotMatch.chain.length - 1; i > 0; i--) {
-        const seg = slotMatch.chain[i];
-
-        // Error boundaries from this segment
-        element = await wrapSegmentWithErrorBoundaries(seg, element, h);
-
-        // Layout from this segment
-        if (seg.layout) {
-          const layoutMod = (await seg.layout.load()) as Record<string, unknown>;
-          if (layoutMod.default) {
-            const Layout = layoutMod.default as (...args: unknown[]) => unknown;
-            element = h(Layout, {
-              params: paramsPromise,
-              searchParams: {},
-              children: element,
-            });
-          }
-        }
-      }
-
-      // Wrap in SlotAccessGate if slot root has access.ts.
-      // On denial: denied.tsx → default.tsx → null (graceful degradation).
-      // See design/04-authorization.md §"Slot-Level Auth".
-      if (slotNode.access) {
-        const accessMod = (await slotNode.access.load()) as Record<string, unknown>;
-        const accessFn = accessMod.default as
-          | ((ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown)
-          | undefined;
-        if (accessFn) {
-          // Load denied.tsx fallback
-          let deniedFallback: React.ReactElement | null = null;
-          if (slotNode.denied) {
-            const deniedMod = (await slotNode.denied.load()) as Record<string, unknown>;
-            const DeniedComponent = deniedMod.default as
-              | ((...args: unknown[]) => unknown)
-              | undefined;
-            if (DeniedComponent) {
-              deniedFallback = h(DeniedComponent, {});
+      const denyFallback = await renderDefaultFallback(slotNode, h);
+
+      // Build the slot page element.
+      // Client references ('use client' pages) must NOT be called as functions —
+      // they are proxy objects that throw when invoked. For client references,
+      // use createElement directly. Error catching is unnecessary because client
+      // references are serialized as references in the RSC Flight stream — they
+      // don't execute on the server. See TIM-627.
+      //
+      // For server components, wrap in SafeSlotPage to catch ALL errors at the
+      // component level. This prevents errors from leaving unresolved Flight
+      // rows in the RSC stream — see TIM-524 for details.
+      let element: React.ReactElement;
+      if (isClientReference(SlotPage)) {
+        element = h(SlotPage, {});
+      } else {
+        const SafeSlotPage = async (props: Record<string, unknown>) => {
+          try {
+            return await (SlotPage as (props: Record<string, unknown>) => unknown)(props);
+          } catch (error) {
+            // RedirectSignal must propagate — the pipeline handles redirects
+            // at the top level. Swallowing it here would silently return
+            // fallback content instead of redirecting. See TIM-554.
+            if (error instanceof RedirectSignal) {
+              throw error;
             }
-          }
-
-          // Load default.tsx fallback
-          let defaultFallback: React.ReactElement | null = null;
-          if (slotNode.default) {
-            const defaultMod = (await slotNode.default.load()) as Record<string, unknown>;
-            const DefaultComp = defaultMod.default as ((...args: unknown[]) => unknown) | undefined;
-            if (DefaultComp) {
-              defaultFallback = h(DefaultComp, { params: paramsPromise, searchParams: {} });
+            if (error instanceof DenySignal) {
+              return denyFallback;
             }
+            // Log the error but don't re-throw — returning fallback ensures
+            // the Flight row is resolved and the page hydrates correctly.
+            logRenderError({
+              method: '',
+              path: '',
+              error,
+            });
+            return denyFallback;
           }
-
-          const params = await paramsPromise;
-          element = h(SlotAccessGate, {
-            accessFn,
-            params,
-            searchParams: {},
-            deniedFallback,
-            defaultFallback,
-            children: element,
-          });
-        }
+        };
+        element = h(SafeSlotPage, {});
       }
 
-      // Wrap with slot root's layout (outermost, outside access gate)
-      if (slotNode.layout) {
-        const layoutMod = (await slotNode.layout.load()) as Record<string, unknown>;
-        if (layoutMod.default) {
-          const Layout = layoutMod.default as (...args: unknown[]) => unknown;
-          element = h(Layout, {
-            params: paramsPromise,
-            searchParams: {},
-            children: element,
-          });
-        }
-      }
+      // Wrap with error boundaries, layouts, and access gates from
+      // intermediate slot segments (everything between slot root and leaf).
+      // Process innermost-first, same order as route-element-builder.ts
+      // handles main segments. The slot root (index 0) is handled below.
+      element = await wrapWithIntermediateSegments(slotMatch.chain, element, h);
+
+      // Wrap with slot root's layout — INSIDE the access gate, so the layout
+      // server component never executes when access.ts denies. See TIM-1074.
+      element = await wrapWithLayout(slotNode, element, h);
+
+      // Wrap in SlotAccessGate if slot root has access.ts. The gate is
+      // OUTSIDE the layout, matching the segment model in
+      // route-element-builder.ts: a denied layout must not render, or it
+      // would fetch/serialize protected data into the RSC Flight stream.
+      // On denial: denied.tsx → default.tsx → null (graceful degradation),
+      // rendered WITHOUT the denied slot's own layout.
+      // See design/04-authorization.md §"Slot-Level Auth".
+      element = await wrapWithAccessGate(slotNode, element, h);
 
       // Wrap with slot root's error boundaries (outermost)
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, h);
@@ -180,7 +182,7 @@ export async function resolveSlotElement(
       // Catch-all error boundary: ensures slot errors NEVER propagate to the
       // parent layout. Without this, a slot without error.tsx that throws
       // causes SSR's renderToReadableStream to reject, triggering renderDenyPage
-      // which re-executes all layout server components (including headers() calls
+      // which re-executes all layout server components (including getHeaders() calls
       // that fail in the SSR environment). The null fallback means the slot
       // degrades to nothing — consistent with the slot access denial behavior.
       // See design/02-rendering-pipeline.md §"Slot Access Failure = Graceful Degradation"
@@ -195,24 +197,101 @@ export async function resolveSlotElement(
   }
 
   // No matching page — render default.tsx fallback
-  if (slotNode.default) {
-    const mod = (await slotNode.default.load()) as Record<string, unknown>;
-    if (mod.default) {
-      const DefaultComponent = mod.default as (...args: unknown[]) => unknown;
-      return h(DefaultComponent, { params: paramsPromise, searchParams: {} });
-    }
+  return renderDefaultFallback(slotNode, h);
+}
+
+// ─── Element Wrapping Helpers ───────────────────────────────────────────────
+
+/**
+ * Wrap an element with error boundaries, access gates, and layouts from
+ * intermediate slot segments (indices 1..n, skipping the slot root at index 0).
+ * Processes innermost-first to match route-element-builder.ts ordering.
+ *
+ * Access gates are enforced for every intermediate segment that has access.ts,
+ * not just the slot root. Without this, nested slot children (e.g.,
+ * @admin/reports/access.ts) and intercepting route children with access.ts
+ * would bypass authorization. See TIM-999.
+ *
+ * Wrap order per segment (innermost → outermost): error boundaries → layout
+ * → access gate. The gate must be OUTSIDE the layout so a denying access.ts
+ * prevents the layout server component from executing — otherwise the layout
+ * would fetch/serialize protected data into the RSC Flight stream. Matches
+ * route-element-builder.ts. See TIM-1074.
+ */
+async function wrapWithIntermediateSegments(
+  chain: ManifestSegmentNode[],
+  element: React.ReactElement,
+  h: CreateElementFn
+): Promise<React.ReactElement> {
+  for (let i = chain.length - 1; i > 0; i--) {
+    const seg = chain[i];
+    element = await wrapSegmentWithErrorBoundaries(seg, element, h);
+    element = await wrapWithLayout(seg, element, h);
+    element = await wrapWithAccessGate(seg, element, h);
   }
+  return element;
+}
 
-  // No page and no default — slot renders nothing
-  return null;
+/**
+ * Wrap an element with a segment's layout component, if present.
+ */
+async function wrapWithLayout(
+  node: ManifestSegmentNode,
+  element: React.ReactElement,
+  h: CreateElementFn
+): Promise<React.ReactElement> {
+  if (!node.layout) return element;
+  const Layout = await loadComponent(node.layout);
+  if (!Layout) return element;
+  return h(Layout, { children: element });
+}
+
+/**
+ * Wrap an element with a SlotAccessGate if the node has access.ts.
+ * On denial: denied.tsx → default.tsx → null (graceful degradation).
+ */
+async function wrapWithAccessGate(
+  slotNode: ManifestSegmentNode,
+  element: React.ReactElement,
+  h: CreateElementFn
+): Promise<React.ReactElement> {
+  if (!slotNode.access) return element;
+
+  const accessFn = await loadComponent(slotNode.access);
+  if (!accessFn) return element;
+
+  // Pass the component (not pre-built element) so SlotAccessGate can
+  // forward DenySignal.data as dangerouslyPassData dynamically. See TIM-488.
+  let DeniedComponent: ((...args: unknown[]) => unknown) | null = null;
+  if (slotNode.denied) {
+    DeniedComponent = (await loadComponent(slotNode.denied)) ?? null;
+  }
+
+  // Extract slot name from the directory name (strip @ prefix)
+  const slotName = slotNode.segmentName?.replace(/^@/, '') ?? '';
+
+  const defaultFallback = await renderDefaultFallback(slotNode, h);
+
+  return h(SlotAccessGate, {
+    accessFn,
+    DeniedComponent,
+    slotName,
+    createElement: h,
+    defaultFallback,
+    children: element,
+  });
 }
 
+// ─── Slot Matching ──────────────────────────────────────────────────────────
+
 /** Result of matching a slot's sub-tree against the current route. */
 interface SlotMatchResult {
   /** The page file at the matched leaf. */
   page: NonNullable<ManifestSegmentNode['page']>;
   /** The full chain of slot nodes traversed (slot root → … → leaf with page). */
   chain: ManifestSegmentNode[];
+  /** Params collected from the slot's segment chain (may differ from main route params). */
+  slotParams: Record<string, string | string[]>;
 }
 
 /**
@@ -231,7 +310,7 @@ interface SlotMatchResult {
  * to find the deepest matching page.
  */
 function findSlotMatch(slotNode: ManifestSegmentNode, match: RouteMatch): SlotMatchResult | null {
-  const segments = match.segments as unknown as ManifestSegmentNode[];
+  const segments = match.segments;
 
   // Find the parent segment that owns this slot by comparing urlPaths.
   // The slot's urlPath matches its parent's urlPath (slots don't add URL depth).
@@ -253,90 +332,60 @@ function findSlotMatch(slotNode: ManifestSegmentNode, match: RouteMatch): SlotMa
   // against the slot's children.
   const remainingSegments = parentIndex >= 0 ? segments.slice(parentIndex + 1) : [];
 
-  // If no remaining segments, the slot's own page matches
-  if (remainingSegments.length === 0) {
-    if (slotNode.page) {
-      return { page: slotNode.page, chain: [slotNode] };
-    }
-    // Check for optional-catch-all child — [[...slug]] matches zero segments
-    for (const child of slotNode.children ?? []) {
-      if (child.segmentType === 'optional-catch-all' && child.page) {
-        return { page: child.page, chain: [slotNode, child] };
-      }
-    }
-    return null;
-  }
+  // Extract raw URL parts from the remaining main-route segments.
+  // Use rawSegmentParams (pre-coercion) to ensure we get actual URL strings,
+  // not codec-transformed values. Fall back to segmentParams for tests/compat.
+  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
+  const urlParts = extractUrlParts(remainingSegments, rawParams);
 
-  // Walk the slot's children to match remaining URL segments.
-  // Track the chain so we can apply error boundaries and layouts.
-  const chain: ManifestSegmentNode[] = [slotNode];
-  let currentNode = slotNode;
-  for (const seg of remainingSegments) {
-    const childName = seg.segmentName;
-    const directChildren = currentNode.children ?? [];
-
-    let found: ManifestSegmentNode | null = null;
-    for (const child of directChildren) {
-      // Exact static match
-      if (child.segmentType === 'static' && child.segmentName === childName) {
-        found = child;
-        break;
-      }
-    }
+  // Match URL parts against the slot's segment tree using the shared walker.
+  // Handles zero parts (slot's own page), catch-all, optional-catch-all,
+  // groups, backtracking, and correct priority ordering.
+  const result = matchUrlParts(slotNode, urlParts);
+  if (!result) return null;
 
-    // Try dynamic segments if no static match
-    if (!found) {
-      for (const child of directChildren) {
-        if (child.segmentType === 'dynamic') {
-          found = child;
-          break;
-        }
-      }
-    }
+  const leaf = result.chain[result.chain.length - 1];
+  if (!leaf.page) return null;
 
-    // Try catch-all segments — these consume ALL remaining URL segments,
-    // so we break out of the outer loop immediately.
-    if (!found) {
-      for (const child of directChildren) {
-        if (child.segmentType === 'catch-all' || child.segmentType === 'optional-catch-all') {
-          found = child;
-          break;
-        }
-      }
-      if (found) {
-        chain.push(found);
-        currentNode = found;
-        break;
-      }
-    }
+  return { page: leaf.page, chain: result.chain, slotParams: result.params };
+}
 
-    // Try group children (transparent)
-    if (!found) {
-      for (const child of directChildren) {
-        if (child.segmentType === 'group') {
-          for (const groupChild of child.children ?? []) {
-            if (groupChild.segmentName === childName) {
-              found = groupChild;
-              break;
-            }
-          }
-          if (found) break;
-        }
+/**
+ * Extract raw URL path parts from a main-route segment chain.
+ *
+ * Each dynamic segment consumed one URL part (its param value).
+ * Static segments consumed their own name. Groups are transparent.
+ * Catch-all segments consumed multiple parts (their param value is string[]).
+ *
+ * Uses rawSegmentParams (pre-coercion) to get actual URL strings.
+ * Values are coerced to String() defensively in case a codec leaked
+ * a non-string value into the params map.
+ */
+function extractUrlParts(
+  segments: ManifestSegmentNode[],
+  mainParams: Record<string, string | string[]>
+): string[] {
+  const parts: string[] = [];
+  for (const seg of segments) {
+    if (seg.segmentType === 'group') continue;
+    if (seg.segmentType === 'static') {
+      parts.push(seg.segmentName);
+    } else if (seg.paramName) {
+      const value = mainParams[seg.paramName];
+      if (Array.isArray(value)) {
+        parts.push(...value.map(String));
+      } else if (value !== undefined) {
+        // Reconstruct the original URL part for affixed segments.
+        // The param value is the stripped middle (e.g. "123" for [id].png
+        // matching "123.png"), so we re-attach prefix/suffix so that slot
+        // matching through matchUrlParts sees the original part.
+        const prefix = seg.paramPrefix ?? '';
+        const suffix = seg.paramSuffix ?? '';
+        parts.push(prefix + String(value) + suffix);
       }
     }
-
-    if (!found) {
-      // No matching child in slot tree — slot doesn't match this URL
-      return null;
-    }
-    chain.push(found);
-    currentNode = found;
-  }
-
-  if (currentNode.page) {
-    return { page: currentNode.page, chain };
   }
-  return null;
+  return parts;
 }
 
 /**
@@ -372,61 +421,19 @@ function findInterceptingMatch(
     }
     if (matchIdx < 0) continue;
 
-    // Walk the intercepting child's sub-tree to match remaining target parts
+    // Match remaining target parts against the intercepting child's sub-tree.
     const remaining = targetParts.slice(matchIdx + 1);
-    const chain: ManifestSegmentNode[] = [slotNode, child];
-
-    if (remaining.length === 0) {
-      if (child.page) {
-        return { page: child.page, chain };
-      }
-      continue;
-    }
-
-    let currentNode = child;
-    let matched = true;
-    for (const part of remaining) {
-      const children = currentNode.children ?? [];
-      let found: ManifestSegmentNode | null = null;
-
-      // Static match
-      for (const c of children) {
-        if (c.segmentType === 'static' && c.segmentName === part) {
-          found = c;
-          break;
-        }
+    const result = matchUrlParts(child, remaining);
+    if (result) {
+      const leaf = result.chain[result.chain.length - 1];
+      if (leaf.page) {
+        return {
+          page: leaf.page,
+          // Prepend slotNode — matchUrlParts starts from child, not slot root
+          chain: [slotNode, ...result.chain],
+          slotParams: result.params,
+        };
       }
-
-      // Dynamic match
-      if (!found) {
-        for (const c of children) {
-          if (c.segmentType === 'dynamic') {
-            found = c;
-            break;
-          }
-        }
-      }
-
-      // Catch-all match
-      if (!found) {
-        for (const c of children) {
-          if (c.segmentType === 'catch-all' || c.segmentType === 'optional-catch-all') {
-            found = c;
-            break;
-          }
-        }
-      }
-
-      if (!found) {
-        matched = false;
-        break;
-      }
-      chain.push(found);
-      currentNode = found;
-    }
-
-    if (matched && currentNode.page) {
-      return { page: currentNode.page, chain };
     }
   }