@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/server/tree-builder.ts

@@ -10,7 +10,10 @@
  * See design/02-rendering-pipeline.md §"Element Tree Construction"
  */
 
-import type { SegmentNode, RouteFile } from '#/routing/types.js';
+import type { ReactNode } from 'react';
+import type { RouteFile, SegmentNode } from '../routing/types.js';
+import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
+import type { LoadedComponent } from './utils/element-type.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -25,31 +28,29 @@ export interface LoadedModule {
 /** Function that loads a route file's module. */
 export type ModuleLoader = (file: RouteFile) => LoadedModule | Promise<LoadedModule>;
 
-/** A React element — kept opaque to avoid a React dependency in this module. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type ReactElement = any;
-
-/** Function that creates a React element. Matches React.createElement signature. */
+/**
+ * Function that creates a React element. Matches React.createElement signature.
+ *
+ * `props` is typed as `object | null` rather than `Record<string, unknown>` so
+ * that interface types with known keys (e.g. `AccessGateProps`,
+ * `ErrorBoundaryProps`) flow through without an explicit index-signature cast.
+ */
 export type CreateElement = (
   type: unknown,
-  props: Record<string, unknown> | null,
+  props: object | null,
   ...children: unknown[]
-) => ReactElement;
+) => ReactNode;
 
 /**
  * Resolved slot content for a layout.
  * Key is slot name (without @), value is the element tree for that slot.
  */
-export type SlotElements = Map<string, ReactElement>;
+export type SlotElements = Map<string, ReactNode>;
 
 /** Configuration for the tree builder. */
 export interface TreeBuilderConfig {
   /** The matched segment chain from root to leaf. */
   segments: SegmentNode[];
-  /** Route params extracted by the matcher (catch-all segments produce string[]). */
-  params: Record<string, string | string[]>;
-  /** Parsed search params (typed or URLSearchParams). */
-  searchParams: unknown;
   /** Loads a route file's module. */
   loadModule: ModuleLoader;
   /** React.createElement or equivalent. */
@@ -77,45 +78,66 @@ export interface TreeBuilderConfig {
  * (backward compat for tree-builder.ts which doesn't run a pre-render pass).
  */
 export interface AccessGateProps {
-  accessFn: (ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
+  accessFn: () => unknown;
   /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
   segmentName?: string;
   /**
-   * Pre-computed verdict from the pre-render pass. When set, AccessGate
-   * replays this verdict synchronously instead of calling accessFn.
-   * - 'pass': render children
-   * - DenySignal/RedirectSignal: throw synchronously
+   * Segment key of the gated segment (`computeSegmentKeys`). Decides whether
+   * a matched deny page renders here or is hoisted to the segment that owns
+   * it. Omitted by construction sites that build no deny chains — with no
+   * chain there is nothing to place. See TIM-1356.
+   */
+  segmentKey?: string;
+  /**
+   * Index of this segment in the matched segment chain. Recorded in ALS
+   * when the gate catches a DenySignal so post-render consumers
+   * (buildSegmentInfo, X-Timber-Segments) can bound the segment list
+   * without a pre-render access pass. See TIM-1363.
+   */
+  segmentIndex?: number;
+  /**
+   * Deny page fallback chain. When provided and a DenySignal is caught,
+   * AccessGate renders the matching deny page in-tree instead of throwing.
+   * This prevents the error from reaching React Flight, eliminating the
+   * second render pass. See TIM-666.
+   *
+   * Omitted for skipped segments — a deny there must hard-navigate to
+   * avoid rendering the deny page inside cached layout chrome (TIM-1074).
+   */
+  denyPages?: import('./deny-boundary.js').DenyPageEntry[];
+  /**
+   * When true, this gate wraps a skipped segment. On deny, the gate
+   * records the deny in ALS and rethrows so the response path can
+   * return rscErrorEnvelope for a client hard-navigate.
+   */
+  skippedSegment?: boolean;
+  /**
+   * Shell settlement callback. Called when the gate finishes (pass or
+   * deny). Tracked by shellSettled so the HTTP status is not committed
+   * before async access checks complete. See TIM-1045, TIM-1363.
    */
-  verdict?:
-    | 'pass'
-    | import('./primitives.js').DenySignal
-    | import('./primitives.js').RedirectSignal;
-  children: ReactElement;
+  onSettled?: () => void;
+  children: ReactNode;
 }
 
 /**
  * Framework-injected slot access gate component.
  * On denial, renders denied.tsx → default.tsx → null instead of failing the page.
+ *
+ * DeniedComponent is passed instead of a pre-built element so that
+ * SlotAccessGate can forward DenySignal.data as dangerouslyPassData
+ * and slotName as the slot prop after catching the signal.
  */
 export interface SlotAccessGateProps {
-  accessFn: (ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
-  deniedFallback: ReactElement | null;
-  defaultFallback: ReactElement | null;
-  children: ReactElement;
-}
-
-/**
- * Framework-injected error boundary wrapper.
- * Wraps content with status-code error boundary handling.
- */
-export interface ErrorBoundaryProps {
-  fallbackComponent: ReactElement | null;
-  status?: number;
-  children: ReactElement;
+  accessFn: () => unknown;
+  /** The denied.tsx component (not a pre-built element). null if no denied.tsx exists. */
+  DeniedComponent: LoadedComponent | null;
+  /** Slot directory name without @ prefix (e.g. "admin", "sidebar"). */
+  slotName: string;
+  /** createElement function for building elements dynamically. */
+  createElement: CreateElement;
+  defaultFallback: ReactNode;
+  children: ReactNode;
 }
 
 // ─── Tree Builder ────────────────────────────────────────────────────────────
@@ -124,8 +146,11 @@ export interface ErrorBoundaryProps {
  * Result of building the element tree.
  */
 export interface TreeBuildResult {
-  /** The root React element tree ready for renderToReadableStream. */
-  tree: ReactElement;
+  /**
+   * The root React element tree ready for renderToReadableStream.
+   * `null` for API routes (route.ts), which don't render a React tree.
+   */
+  tree: ReactNode;
   /** Whether the leaf segment is a route.ts (API endpoint) rather than a page. */
   isApiRoute: boolean;
 }
@@ -143,8 +168,7 @@ export interface TreeBuildResult {
  * Parallel slots are resolved at each layout level and composed as named props.
  */
 export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeBuildResult> {
-  const { segments, params, searchParams, loadModule, createElement, errorBoundaryComponent } =
-    config;
+  const { segments, loadModule, createElement, errorBoundaryComponent } = config;
 
   if (segments.length === 0) {
     throw new Error('[timber] buildElementTree: empty segment chain');
@@ -159,7 +183,7 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
 
   // Start with the page component
   const pageModule = leaf.page ? await loadModule(leaf.page) : null;
-  const PageComponent = pageModule?.default as ((...args: unknown[]) => ReactElement) | undefined;
+  const PageComponent = pageModule?.default as LoadedComponent | undefined;
 
   if (!PageComponent) {
     throw new Error(
@@ -168,21 +192,19 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
     );
   }
 
-  // Build the page element with params and searchParams props
-  let element: ReactElement = createElement(PageComponent, { params, searchParams });
+  // Build the page element — params are accessed via getSegmentParams() from ALS
+  let element: ReactNode = createElement(PageComponent, {});
 
   // Build tree bottom-up: wrap page, then walk segments from leaf to root
   for (let i = segments.length - 1; i >= 0; i--) {
     const segment = segments[i];
 
     // Wrap in error boundaries (status-code files + error.tsx)
-    element = await wrapWithErrorBoundaries(
-      segment,
-      element,
+    element = await wrapSegmentWithErrorBoundaries(segment, element, {
       loadModule,
       createElement,
-      errorBoundaryComponent
-    );
+      errorBoundaryComponent,
+    });
 
     // Wrap in AccessGate if segment has access.ts
     if (segment.access) {
@@ -190,8 +212,6 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
       const accessFn = accessModule.default as AccessGateProps['accessFn'];
       element = createElement('timber:access-gate', {
         accessFn,
-        params,
-        searchParams,
         segmentName: segment.segmentName,
         children: element,
       } satisfies AccessGateProps);
@@ -200,19 +220,17 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
     // Wrap in layout (if exists and not the leaf's page-level wrapping)
     if (segment.layout) {
       const layoutModule = await loadModule(segment.layout);
-      const LayoutComponent = layoutModule.default as
-        | ((...args: unknown[]) => ReactElement)
-        | undefined;
+      const LayoutComponent = layoutModule.default as LoadedComponent | undefined;
 
       if (LayoutComponent) {
         // Resolve parallel slots for this layout
-        const slotProps: Record<string, ReactElement> = {};
-        if (segment.slots.size > 0) {
-          for (const [slotName, slotNode] of segment.slots) {
+        const slotProps: Record<string, ReactNode> = {};
+        const slotNames = Object.keys(segment.slots);
+        if (slotNames.length > 0) {
+          for (const slotName of slotNames) {
+            const slotNode = segment.slots[slotName]!;
             slotProps[slotName] = await buildSlotElement(
               slotNode,
-              params,
-              searchParams,
               loadModule,
               createElement,
               errorBoundaryComponent
@@ -220,12 +238,12 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
           }
         }
 
+        /* eslint-disable react/no-children-prop -- createElement API */
         element = createElement(LayoutComponent, {
           ...slotProps,
-          params,
-          searchParams,
           children: element,
         });
+        /* eslint-enable react/no-children-prop */
       }
     }
   }
@@ -243,64 +261,49 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
  */
 async function buildSlotElement(
   slotNode: SegmentNode,
-  params: Record<string, string | string[]>,
-  searchParams: unknown,
   loadModule: ModuleLoader,
   createElement: CreateElement,
   errorBoundaryComponent: unknown
-): Promise<ReactElement> {
+): Promise<ReactNode> {
   // Load slot page
   const pageModule = slotNode.page ? await loadModule(slotNode.page) : null;
-  const PageComponent = pageModule?.default as ((...args: unknown[]) => ReactElement) | undefined;
+  const PageComponent = pageModule?.default as LoadedComponent | undefined;
 
   // Load default.tsx fallback
   const defaultModule = slotNode.default ? await loadModule(slotNode.default) : null;
-  const DefaultComponent = defaultModule?.default as
-    | ((...args: unknown[]) => ReactElement)
-    | undefined;
+  const DefaultComponent = defaultModule?.default as LoadedComponent | undefined;
 
   // If no page, render default.tsx or null
   if (!PageComponent) {
-    return DefaultComponent ? createElement(DefaultComponent, { params, searchParams }) : null;
+    return DefaultComponent ? createElement(DefaultComponent, {}) : null;
   }
 
-  let element: ReactElement = createElement(PageComponent, { params, searchParams });
+  let element: ReactNode = createElement(PageComponent, {});
 
   // Wrap in error boundaries
-  element = await wrapWithErrorBoundaries(
-    slotNode,
-    element,
+  element = await wrapSegmentWithErrorBoundaries(slotNode, element, {
     loadModule,
     createElement,
-    errorBoundaryComponent
-  );
+    errorBoundaryComponent,
+  });
 
   // Wrap in SlotAccessGate if slot has access.ts
   if (slotNode.access) {
     const accessModule = await loadModule(slotNode.access);
     const accessFn = accessModule.default as SlotAccessGateProps['accessFn'];
 
-    // Load denied.tsx
+    // Load denied.tsx — pass component (not pre-built element) so
+    // SlotAccessGate can forward DenySignal.data dynamically. See TIM-488.
     const deniedModule = slotNode.denied ? await loadModule(slotNode.denied) : null;
-    const DeniedComponent = deniedModule?.default as
-      | ((...args: unknown[]) => ReactElement)
-      | undefined;
-
-    const deniedFallback = DeniedComponent
-      ? createElement(DeniedComponent, {
-          slot: slotNode.segmentName.replace(/^@/, ''),
-          dangerouslyPassData: undefined,
-        })
-      : null;
-    const defaultFallback = DefaultComponent
-      ? createElement(DefaultComponent, { params, searchParams })
-      : null;
+    const DeniedComponent = (deniedModule?.default as LoadedComponent | undefined) ?? null;
+
+    const defaultFallback = DefaultComponent ? createElement(DefaultComponent, {}) : null;
 
     element = createElement('timber:slot-access-gate', {
       accessFn,
-      params,
-      searchParams,
-      deniedFallback,
+      DeniedComponent,
+      slotName: slotNode.segmentName.replace(/^@/, ''),
+      createElement,
       defaultFallback,
       children: element,
     } satisfies SlotAccessGateProps);
@@ -308,75 +311,3 @@ async function buildSlotElement(
 
   return element;
 }
-
-// ─── Error Boundary Wrapping ─────────────────────────────────────────────────
-
-/**
- * Wrap an element with error boundaries from a segment's status-code files.
- *
- * Wrapping order (innermost to outermost):
- *   1. Specific status files (503.tsx, 429.tsx, etc.)
- *   2. Category catch-alls (4xx.tsx, 5xx.tsx)
- *   3. error.tsx (general error boundary)
- *
- * This creates the fallback chain described in design/10-error-handling.md.
- */
-async function wrapWithErrorBoundaries(
-  segment: SegmentNode,
-  element: ReactElement,
-  loadModule: ModuleLoader,
-  createElement: CreateElement,
-  errorBoundaryComponent: unknown
-): Promise<ReactElement> {
-  // Wrapping is applied inside-out. The last wrap call produces the outermost boundary.
-  // Order: specific status → category → error.tsx (outermost)
-
-  if (segment.statusFiles) {
-    // Wrap with specific status files (innermost — highest priority at runtime)
-    for (const [key, file] of segment.statusFiles) {
-      if (key !== '4xx' && key !== '5xx') {
-        const status = parseInt(key, 10);
-        if (!isNaN(status)) {
-          const mod = await loadModule(file);
-          const Component = mod.default;
-          if (Component) {
-            element = createElement(errorBoundaryComponent, {
-              fallbackComponent: Component,
-              status,
-              children: element,
-            } satisfies ErrorBoundaryProps);
-          }
-        }
-      }
-    }
-
-    // Wrap with category catch-alls (4xx.tsx, 5xx.tsx)
-    for (const [key, file] of segment.statusFiles) {
-      if (key === '4xx' || key === '5xx') {
-        const mod = await loadModule(file);
-        const Component = mod.default;
-        if (Component) {
-          element = createElement(errorBoundaryComponent, {
-            fallbackComponent: Component,
-            status: key === '4xx' ? 400 : 500, // category marker
-            children: element,
-          } satisfies ErrorBoundaryProps);
-        }
-      }
-    }
-  }
-
-  // Wrap with error.tsx (outermost — catches anything not matched by status files)
-  if (segment.error) {
-    const errorModule = await loadModule(segment.error);
-    const ErrorComponent = errorModule.default;
-    if (ErrorComponent) {
-      element = createElement(errorBoundaryComponent, {
-        fallbackComponent: ErrorComponent,
-        children: element,
-      } satisfies ErrorBoundaryProps);
-    }
-  }
-
-  return element;
-}

package/src/server/tree-match.ts

@@ -0,0 +1,262 @@
+/**
+ * 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[]>;
+}
+
+export interface TreeMatchOptions {
+  /**
+   * When true (default), only match if the leaf node has a page or route
+   * handler. Set to false for metadata route matching, where we just need
+   * to find the owning segment regardless of whether it has a page.
+   */
+  requireTerminal?: boolean;
+}
+
+/**
+ * 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.
+ *
+ * By default, a match requires a terminal node (one with `page` or
+ * `route`) at the leaf. Pass `{ requireTerminal: false }` to match
+ * any segment (used by metadata route matching).
+ *
+ * @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[],
+  options?: TreeMatchOptions
+): TreeMatchResult<TFile> | null {
+  const chain: SegmentNode<TFile>[] = [];
+  const params: Record<string, string | string[]> = {};
+  const requireTerminal = options?.requireTerminal ?? true;
+
+  if (matchNode(root, parts, 0, chain, params, requireTerminal)) {
+    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);
+}
+
+/** Combined affix length for specificity ordering. */
+function affixLength<TFile>(node: SegmentNode<TFile>): number {
+  return (node.paramPrefix?.length ?? 0) + (node.paramSuffix?.length ?? 0);
+}
+
+/**
+ * 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[]>,
+  requireTerminal: boolean
+): boolean {
+  chain.push(node);
+
+  // All parts consumed — check if this node is terminal (or any node if !requireTerminal)
+  if (index >= parts.length) {
+    if (!requireTerminal || 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, requireTerminal)) {
+          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' && (!requireTerminal || 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, requireTerminal)) {
+        return true;
+      }
+      chain.length -= groupChain.length;
+    }
+  }
+
+  // 2. Affixed dynamic segments (e.g. img-[id].png) — more specific than bare dynamic.
+  //    Sorted by specificity: longer combined prefix+suffix wins.
+  const affixed = effective.filter(
+    ({ child }) =>
+      child.segmentType === 'dynamic' && child.paramName && (child.paramPrefix || child.paramSuffix)
+  );
+  affixed.sort((a, b) => affixLength(b.child) - affixLength(a.child));
+  for (const { child, groupChain } of affixed) {
+    const prefix = child.paramPrefix ?? '';
+    const suffix = child.paramSuffix ?? '';
+    if (
+      part.length > prefix.length + suffix.length &&
+      (!prefix || part.startsWith(prefix)) &&
+      (!suffix || part.endsWith(suffix))
+    ) {
+      const value = part.slice(prefix.length, part.length - (suffix.length || 0));
+      chain.push(...groupChain);
+      const prev = params[child.paramName!];
+      params[child.paramName!] = value;
+      if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) {
+        return true;
+      }
+      // Backtrack
+      chain.length -= groupChain.length;
+      if (prev !== undefined) {
+        params[child.paramName!] = prev;
+      } else {
+        delete params[child.paramName!];
+      }
+    }
+  }
+
+  // 3. Bare dynamic segments ([param])
+  for (const { child, groupChain } of effective) {
+    if (
+      child.segmentType === 'dynamic' &&
+      child.paramName &&
+      !child.paramPrefix &&
+      !child.paramSuffix
+    ) {
+      chain.push(...groupChain);
+      const prev = params[child.paramName];
+      params[child.paramName] = part;
+      if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) {
+        return true;
+      }
+      // Backtrack
+      chain.length -= groupChain.length;
+      if (prev !== undefined) {
+        params[child.paramName] = prev;
+      } else {
+        delete params[child.paramName];
+      }
+    }
+  }
+
+  // 4. Catch-all segments ([...param]) — must be terminal unless the
+  // caller passed requireTerminal:false (metadata route matching needs to
+  // find the owning segment even when it has no page).
+  for (const { child, groupChain } of effective) {
+    if (
+      child.segmentType === 'catch-all' &&
+      child.paramName &&
+      (!requireTerminal || isTerminal(child))
+    ) {
+      chain.push(...groupChain, child);
+      params[child.paramName] = parts.slice(index);
+      return true;
+    }
+  }
+
+  // 5. Optional catch-all segments ([[...param]]) — same terminal rule
+  for (const { child, groupChain } of effective) {
+    if (
+      child.segmentType === 'optional-catch-all' &&
+      child.paramName &&
+      (!requireTerminal || isTerminal(child))
+    ) {
+      chain.push(...groupChain, child);
+      params[child.paramName] = parts.slice(index);
+      return true;
+    }
+  }
+
+  chain.pop();
+  return false;
+}