@timber-js/app 0.2.0-alpha.33 → 0.2.0-alpha.35

package/src/server/slot-resolver.ts

@@ -26,6 +26,119 @@ 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>;
+}): Promise<((...args: unknown[]) => unknown) | undefined> {
+  const mod = (await loader.load()) as Record<string, unknown>;
+  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,
+  paramsPromise: Promise<Record<string, string | string[]>>,
+  h: CreateElementFn
+): Promise<React.ReactElement | null> {
+  if (!slotNode.default) return null;
+  const DefaultComp = await loadComponent(slotNode.default);
+  if (!DefaultComp) return null;
+  return h(DefaultComp, { params: paramsPromise });
+}
+
+// ─── 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.
  *
@@ -54,36 +167,26 @@ 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: {} });
-        }
-      }
+      const denyFallback = await renderDefaultFallback(slotNode, paramsPromise, h);
 
       // 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;
+            return denyFallback;
           }
           throw error;
         }
@@ -91,88 +194,21 @@ export async function resolveSlotElement(
 
       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,
-            });
-          }
-        }
-      }
+      element = await wrapWithIntermediateSegments(slotMatch.chain, element, paramsPromise, 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, paramsPromise, 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, paramsPromise, h);
 
       // Wrap with slot root's error boundaries (outermost)
       element = await wrapSegmentWithErrorBoundaries(slotNode, element, h);
@@ -195,18 +231,86 @@ 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, paramsPromise, 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,
+  paramsPromise: Promise<Record<string, string | string[]>>,
+  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, paramsPromise, 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,
+  paramsPromise: Promise<Record<string, string | string[]>>,
+  h: CreateElementFn
+): Promise<React.ReactElement> {
+  if (!node.layout) return element;
+  const Layout = await loadComponent(node.layout);
+  if (!Layout) return element;
+  return h(Layout, { params: paramsPromise, 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,
+  paramsPromise: Promise<Record<string, string | string[]>>,
+  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, paramsPromise, h);
+  const params = await paramsPromise;
+
+  return h(SlotAccessGate, {
+    accessFn,
+    params,
+    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 +371,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 +414,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 };
     }
   }
 

package/src/server/ssr-entry.ts

@@ -195,7 +195,7 @@ export async function handleSsr(
     // Client hooks read from getSsrData() which delegates to this
     // ALS store via the registered provider.
     return ssrDataAls.run(ssrData, async () => {
-      // Also set the module-level currentParams for useParams().
+      // Also set the module-level currentParams for useSegmentParams().
       // useParams reads from getSsrData() during SSR (ALS-backed),
       // but setCurrentParams is kept for the client-side path where
       // the segment router updates params on navigation.
@@ -262,6 +262,8 @@ export async function handleSsr(
         }
         const _renderEnd = performance.now();
 
+        // React 19.3+ emits <!DOCTYPE html> automatically when the root
+        // element is <html>, so no framework-level doctype prepend needed.
         const errorHandler = createNodeErrorHandler(navContext.signal);
         const headInjector = createNodeHeadInjector(navContext.headHtml);
         const flightInjector = createNodeFlightInjector(navContext.rscStream);

package/src/server/ssr-render.ts

@@ -289,6 +289,9 @@ function isAbortError(error: unknown): boolean {
  * Build a Response from the SSR HTML stream with the correct
  * status code and headers from the navigation context.
  *
+ * React 19.3+ automatically emits `<!DOCTYPE html>` when the root
+ * element is `<html>`, so no framework-level doctype prepending is needed.
+ *
  * Sets content-type to text/html if not already set by middleware.
  */
 export function buildSsrResponse(