@timber-js/app 0.2.0-alpha.116 → 0.2.0-alpha.117

package/src/server/slot-resolver.ts

@@ -26,6 +26,9 @@ import type { InterceptionContext, RouteMatch } from './pipeline.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;
 
@@ -57,89 +60,6 @@ async function renderDefaultFallback(
   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 ────────────────────────────────────────────────
 
 /**
@@ -157,7 +77,8 @@ export async function resolveSlotElement(
   slotNode: ManifestSegmentNode,
   match: RouteMatch,
   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
@@ -169,6 +90,22 @@ export async function resolveSlotElement(
     : findSlotMatch(slotNode, match);
 
   if (slotMatch) {
+    // 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.
@@ -334,6 +271,8 @@ interface SlotMatchResult {
   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[]>;
 }
 
 /**
@@ -374,26 +313,54 @@ 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] };
+  // 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);
+
+  // 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;
+
+  const leaf = result.chain[result.chain.length - 1];
+  if (!leaf.page) return null;
+
+  return { page: leaf.page, chain: result.chain, slotParams: result.params };
+}
+
+/**
+ * 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) {
+        parts.push(String(value));
       }
     }
-    return null;
-  }
-
-  // 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;
+  return parts;
 }
 
 /**
@@ -429,19 +396,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);
-
-    if (remaining.length === 0) {
-      if (child.page) {
-        return { page: child.page, chain: [slotNode, child] };
+    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,
+        };
       }
-      continue;
-    }
-
-    const result = walkSegmentTree(child, remaining, [slotNode, child]);
-    if (result && result.leaf.page) {
-      return { page: result.leaf.page, chain: result.chain };
     }
   }
 

package/src/server/tree-match.ts

@@ -0,0 +1,198 @@
+/**
+ * Shared URL-matching tree walker for segment trees.
+ *
+ * Both the main route matcher (`route-matcher.ts`) and slot resolver
+ * (`slot-resolver.ts`) need to walk a SegmentNode tree, matching URL
+ * parts against children with the same priority semantics:
+ *
+ *   static > dynamic > catch-all > optional-catch-all
+ *
+ * Before this module, each had its own walker with subtle divergences
+ * (different group handling, missing backtracking, incomplete
+ * optional-catch-all support). This shared walker is the single
+ * source of truth for URL-to-segment matching.
+ *
+ * See design/07-routing.md §"Request Lifecycle" and TIM-940.
+ */
+
+import type { SegmentNode } from '../routing/types.js';
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+/** Result of matching URL parts against a segment tree. */
+export interface TreeMatchResult<TFile> {
+  /** Matched segment chain from root to leaf, inclusive. */
+  chain: SegmentNode<TFile>[];
+  /** Collected params, keyed by param name. Catch-all params are string[]. */
+  params: Record<string, string | string[]>;
+}
+
+/**
+ * Match URL path parts against a segment tree.
+ *
+ * Walks the tree depth-first with backtracking, applying priority
+ * ordering globally across group boundaries. Returns the matched
+ * segment chain and collected params, or null if no route matches.
+ *
+ * A match requires a terminal node (one with `page` or `route`) at
+ * the leaf. Catch-all and optional-catch-all segments only match if
+ * they are terminal.
+ *
+ * @param root  The root segment node to start matching from.
+ * @param parts URL path parts (e.g. ['blog', 'hello-world']).
+ *              Empty array matches the root itself (if terminal).
+ */
+export function matchUrlParts<TFile>(
+  root: SegmentNode<TFile>,
+  parts: string[]
+): TreeMatchResult<TFile> | null {
+  const chain: SegmentNode<TFile>[] = [];
+  const params: Record<string, string | string[]> = {};
+
+  if (matchNode(root, parts, 0, chain, params)) {
+    return { chain, params };
+  }
+  return null;
+}
+
+// ─── Internal ─────────────────────────────────────────────────────────────
+
+/**
+ * A child node flattened through group segments, along with the
+ * chain of group nodes that must appear in the segment chain
+ * before the child to preserve the tree path.
+ */
+interface EffectiveChild<TFile> {
+  child: SegmentNode<TFile>;
+  groupChain: SegmentNode<TFile>[];
+}
+
+/**
+ * Flatten children through group segments.
+ *
+ * Groups are transparent for URL matching — their non-group descendants
+ * are returned with the chain of group nodes leading to them. This lets
+ * the caller apply priority ordering (static > dynamic > catch-all >
+ * optional-catch-all) across all groups uniformly instead of per-group.
+ */
+function collectEffectiveChildren<TFile>(
+  node: SegmentNode<TFile>,
+  groupChain: SegmentNode<TFile>[] = []
+): EffectiveChild<TFile>[] {
+  const result: EffectiveChild<TFile>[] = [];
+  for (const child of node.children) {
+    if (child.segmentType === 'group') {
+      const nested = collectEffectiveChildren(child, [...groupChain, child]);
+      result.push(...nested);
+    } else {
+      result.push({ child, groupChain });
+    }
+  }
+  return result;
+}
+
+/** A node is terminal if it can serve a response (has a page or route handler). */
+function isTerminal<TFile>(node: SegmentNode<TFile>): boolean {
+  return !!(node.page || node.route);
+}
+
+/**
+ * Recursive depth-first matcher with backtracking.
+ *
+ * Mutates `chain` and `params` in place for performance; backtracks
+ * (restores previous state) when a candidate doesn't lead to a match.
+ */
+function matchNode<TFile>(
+  node: SegmentNode<TFile>,
+  parts: string[],
+  index: number,
+  chain: SegmentNode<TFile>[],
+  params: Record<string, string | string[]>
+): boolean {
+  chain.push(node);
+
+  // All parts consumed — check if this node is terminal
+  if (index >= parts.length) {
+    if (isTerminal(node)) return true;
+
+    // Groups don't consume URL segments, so a group child's page can
+    // match at the same URL depth. Recurse into groups transparently.
+    for (const child of node.children) {
+      if (child.segmentType === 'group') {
+        if (matchNode(child, parts, index, chain, params)) {
+          return true;
+        }
+      }
+    }
+
+    // Optional catch-all with zero segments (direct and through groups).
+    // The param is NOT set — matching Next.js semantics for [[...slug]]
+    // with no path segments.
+    const effective = collectEffectiveChildren(node);
+    for (const { child, groupChain } of effective) {
+      if (child.segmentType === 'optional-catch-all' && isTerminal(child)) {
+        chain.push(...groupChain, child);
+        return true;
+      }
+    }
+
+    chain.pop();
+    return false;
+  }
+
+  const part = parts[index];
+
+  // Flatten children through groups so priority ordering applies globally.
+  const effective = collectEffectiveChildren(node);
+
+  // 1. Static segments (exact name match)
+  for (const { child, groupChain } of effective) {
+    if (child.segmentType === 'static' && child.segmentName === part) {
+      chain.push(...groupChain);
+      if (matchNode(child, parts, index + 1, chain, params)) {
+        return true;
+      }
+      chain.length -= groupChain.length;
+    }
+  }
+
+  // 2. Dynamic segments ([param])
+  for (const { child, groupChain } of effective) {
+    if (child.segmentType === 'dynamic' && child.paramName) {
+      chain.push(...groupChain);
+      const prev = params[child.paramName];
+      params[child.paramName] = part;
+      if (matchNode(child, parts, index + 1, chain, params)) {
+        return true;
+      }
+      // Backtrack
+      chain.length -= groupChain.length;
+      if (prev !== undefined) {
+        params[child.paramName] = prev;
+      } else {
+        delete params[child.paramName];
+      }
+    }
+  }
+
+  // 3. Catch-all segments ([...param]) — must be terminal
+  for (const { child, groupChain } of effective) {
+    if (child.segmentType === 'catch-all' && child.paramName && isTerminal(child)) {
+      chain.push(...groupChain, child);
+      params[child.paramName] = parts.slice(index);
+      return true;
+    }
+  }
+
+  // 4. Optional catch-all segments ([[...param]]) — must be terminal
+  for (const { child, groupChain } of effective) {
+    if (child.segmentType === 'optional-catch-all' && child.paramName && isTerminal(child)) {
+      chain.push(...groupChain, child);
+      params[child.paramName] = parts.slice(index);
+      return true;
+    }
+  }
+
+  chain.pop();
+  return false;
+}