@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.81

package/src/server/slot-resolver.ts

@@ -16,16 +16,132 @@
  * 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';
 
 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, {});
+}
+
+// ─── Segment Tree Matching ──────────────────────────────────────────────────
+
+/**
+ * Find a matching child node for a URL segment name.
+ *
+ * Tries matches in priority order:
+ * 1. Static segment (exact name match)
+ * 2. Dynamic segment ([param])
+ * 3. Catch-all or optional-catch-all ([...param] / [[...param]])
+ * 4. Group children (transparent wrappers)
+ *
+ * Returns `{ node, consumesRest }` where `consumesRest` is true for catch-all
+ * segments that consume all remaining URL parts.
+ */
+function findMatchingChild(
+  children: ManifestSegmentNode[],
+  segmentName: string
+): { node: ManifestSegmentNode; consumesRest: boolean } | null {
+  // 1. Static match
+  for (const child of children) {
+    if (child.segmentType === 'static' && child.segmentName === segmentName) {
+      return { node: child, consumesRest: false };
+    }
+  }
+
+  // 2. Dynamic match
+  for (const child of children) {
+    if (child.segmentType === 'dynamic') {
+      return { node: child, consumesRest: false };
+    }
+  }
+
+  // 3. Catch-all match — consumes all remaining segments
+  for (const child of children) {
+    if (child.segmentType === 'catch-all' || child.segmentType === 'optional-catch-all') {
+      return { node: child, consumesRest: true };
+    }
+  }
+
+  // 4. Group children (transparent)
+  for (const child of children) {
+    if (child.segmentType === 'group') {
+      for (const groupChild of child.children ?? []) {
+        if (groupChild.segmentName === segmentName) {
+          return { node: groupChild, consumesRest: false };
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Walk a segment tree from `startNode`, matching each part in `parts` against
+ * child nodes. Returns the chain of matched nodes (including startNode) and the
+ * final node, or null if any part fails to match.
+ */
+function walkSegmentTree(
+  startNode: ManifestSegmentNode,
+  parts: { segmentName: string }[] | string[],
+  initialChain: ManifestSegmentNode[] = [startNode]
+): { chain: ManifestSegmentNode[]; leaf: ManifestSegmentNode } | null {
+  const chain = [...initialChain];
+  let currentNode = startNode;
+
+  for (const part of parts) {
+    const segName = typeof part === 'string' ? part : part.segmentName;
+    const directChildren = currentNode.children ?? [];
+    const match = findMatchingChild(directChildren, segName);
+
+    if (!match) return null;
+
+    chain.push(match.node);
+    currentNode = match.node;
+
+    // Catch-all segments consume all remaining parts
+    if (match.consumesRest) break;
+  }
+
+  return { chain, leaf: currentNode };
+}
+
+// ─── Slot Element Resolution ────────────────────────────────────────────────
+
 /**
  * Resolve the element for a parallel slot.
  *
@@ -40,7 +156,6 @@ type CreateElementFn = (...args: unknown[]) => React.ReactElement;
 export async function resolveSlotElement(
   slotNode: ManifestSegmentNode,
   match: RouteMatch,
-  paramsPromise: Promise<Record<string, string | string[]>>,
   h: CreateElementFn,
   interception?: InterceptionContext
 ): Promise<React.ReactElement | null> {
@@ -54,125 +169,68 @@ 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;
-
+    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;
+      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;
+            }
+            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;
           }
-          throw error;
-        }
-      };
-
-      let element: React.ReactElement = h(SafeSlotPage, {
-        params: paramsPromise,
-        searchParams: {},
-      });
+        };
+        element = h(SafeSlotPage, {});
+      }
 
       // 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,
-            });
-          }
-        }
-      }
+      element = await wrapWithIntermediateSegments(slotMatch.chain, element, h);
 
       // 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, {});
-            }
-          }
-
-          // 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: {} });
-            }
-          }
-
-          const params = await paramsPromise;
-          element = h(SlotAccessGate, {
-            accessFn,
-            params,
-            searchParams: {},
-            deniedFallback,
-            defaultFallback,
-            children: element,
-          });
-        }
-      }
+      element = await wrapWithAccessGate(slotNode, element, h);
 
       // 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,
-          });
-        }
-      }
+      element = await wrapWithLayout(slotNode, element, h);
 
       // Wrap with slot root's error boundaries (outermost)
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, h);
@@ -180,7 +238,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,18 +253,81 @@ 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 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.
+ */
+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);
   }
+  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. */
@@ -267,74 +388,10 @@ function findSlotMatch(slotNode: ManifestSegmentNode, match: RouteMatch): SlotMa
     return null;
   }
 
-  // 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;
-      }
-    }
-
-    // Try dynamic segments if no static match
-    if (!found) {
-      for (const child of directChildren) {
-        if (child.segmentType === 'dynamic') {
-          found = child;
-          break;
-        }
-      }
-    }
-
-    // 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;
-      }
-    }
-
-    // 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;
-        }
-      }
-    }
-
-    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 };
+  // Walk the slot's children to match remaining URL segments
+  const result = walkSegmentTree(slotNode, remainingSegments);
+  if (result && result.leaf.page) {
+    return { page: result.leaf.page, chain: result.chain };
   }
   return null;
 }
@@ -374,59 +431,17 @@ function findInterceptingMatch(
 
     // Walk the intercepting child's sub-tree to match remaining target parts
     const remaining = targetParts.slice(matchIdx + 1);
-    const chain: ManifestSegmentNode[] = [slotNode, child];
 
     if (remaining.length === 0) {
       if (child.page) {
-        return { page: child.page, chain };
+        return { page: child.page, chain: [slotNode, child] };
       }
       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;
-        }
-      }
-
-      // 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 };
+    const result = walkSegmentTree(child, remaining, [slotNode, child]);
+    if (result && result.leaf.page) {
+      return { page: result.leaf.page, chain: result.chain };
     }
   }