@timber-js/app 0.2.0-alpha.184 → 0.2.0-alpha.186

package/src/routing/slot-placement.ts

@@ -0,0 +1,97 @@
+/**
+ * Parallel slot placement.
+ *
+ * One rule: a slot is resolved only for a segment on the **matched route
+ * chain**, and a slot's own subtree is never on that chain. So a slot declared
+ * anywhere inside another slot's subtree can never render, and is rejected at
+ * build time rather than left as a directory the author will keep editing.
+ *
+ * See design/07-routing.md §"Parallel Routes".
+ */
+
+import type { SegmentNode } from './types.js';
+
+/**
+ * Reject every parallel slot that no renderer reaches.
+ *
+ * **Where slots are resolved.** Two places read `segment.slots`, and both walk
+ * the main route chain: `route-element-builder.ts` (the RSC render) and
+ * `tree-builder.ts`. Neither is reachable from inside a slot. The slot's own
+ * subtree is rendered by `slot-resolver.ts`, which walks the slot's matched
+ * chain to apply that chain's layouts, error boundaries and access gates
+ * (`wrapWithIntermediateSegments`, `wrapWithLayout`) and never reads `.slots`
+ * on any of those nodes. So `app/feed/@modal/photo/@side/page.tsx` and
+ * everything below it is dead: the file is scanned, typed, code-split and
+ * shipped, and no request can render it.
+ *
+ * That is the TIM-1278 failure — a directory that silently never renders —
+ * and the reason it is a build error rather than a documented limit is that
+ * nothing at request time can report it. A slot that does not match renders
+ * `default.tsx` or `null`, which is exactly what a slot the resolver never
+ * looked at also produces, so the author sees the *designed* behaviour of a
+ * non-matching slot and has no signal to distinguish it from a slot that
+ * cannot match at all.
+ *
+ * **Interception is incidental.** TIM-1311 arrived as
+ * `feed/@modal/(.)photo/@side`, and the interception contributes nothing: the
+ * identical `feed/@modal/photo/@side` never renders either, for the same
+ * reason and with no marker anywhere. Rejecting only the intercepting spelling
+ * would have drawn a line the author cannot see from the directory names.
+ *
+ * The children-path interception shape is **not** affected and must not be:
+ * its intercepting node joins the main chain (`server/children-interception.ts`
+ * splices `[…owner ancestors, interceptingNode, …descendants]` into an ordinary
+ * `RouteMatch`), so `route-element-builder.ts` resolves slots on it and below
+ * it exactly as it does for any other chain segment. `(browse)/(...)photo/[id]/@side`
+ * renders; `feed/@modal/(.)photo/@side` does not. The discriminator is the slot
+ * boundary, which is what this walk tracks — not the marker.
+ */
+export function validateSlotPlacement(root: SegmentNode): void {
+  walkForSlotPlacement(root, '', null);
+}
+
+/**
+ * `enclosingSlotPath` is the `app/`-relative path of the nearest slot at or
+ * above `node`, or null on the main chain. It is carried rather than recomputed
+ * so the error can name the slot that swallows the offender — "this is inside
+ * @modal" is the part of the diagnosis the author cannot see from the offending
+ * path alone.
+ */
+function walkForSlotPlacement(
+  node: SegmentNode,
+  path: string,
+  enclosingSlotPath: string | null
+): void {
+  for (const [slotName, slotNode] of Object.entries(node.slots)) {
+    const slotPath = path ? `${path}/@${slotName}` : `@${slotName}`;
+    if (enclosingSlotPath !== null) {
+      throwNestedSlot(slotPath, enclosingSlotPath);
+    }
+    walkForSlotPlacement(slotNode, slotPath, slotPath);
+  }
+
+  for (const child of node.children) {
+    walkForSlotPlacement(
+      child,
+      path ? `${path}/${child.segmentName}` : child.segmentName,
+      enclosingSlotPath
+    );
+  }
+}
+
+function throwNestedSlot(slotPath: string, enclosingSlotPath: string): never {
+  throw new Error(
+    `Build error: parallel slot nested inside another parallel slot.\n` +
+      `  Directory: app/${slotPath}\n` +
+      `  Inside:    app/${enclosingSlotPath}\n` +
+      `A parallel slot is resolved only for a segment on the matched route chain, and a ` +
+      `slot's own subtree is never on that chain — the slot resolver walks the slot's ` +
+      `matched chain to apply its layouts, error boundaries and access gates, and never ` +
+      `looks at slots declared inside it. So app/${slotPath} and everything below it can ` +
+      `never render, and no request-time signal can tell you: an unreachable slot ` +
+      `produces exactly what a slot that simply did not match produces.\n` +
+      `Declare the slot on a segment of the main route chain instead, or move its pages ` +
+      `into app/${enclosingSlotPath}'s own subtree.\n` +
+      `See design/07-routing.md §"Parallel Routes".`
+  );
+}

package/src/routing/types.ts

@@ -14,7 +14,7 @@
  * `SegmentNode` (Map-based) and `ManifestSegmentNode` (object-based).
  *
  * Keyed groups (`slots`, `statusFiles`, `jsonStatusFiles`,
- * `legacyStatusFiles`, `metadataRoutes`) are plain `Record<string, …>`
+ * `metadataRoutes`) are plain `Record<string, …>`
  * objects rather than `Map`s so that the build-time tree can be
  * serialized into the virtual route manifest with no shape transform.
  *
@@ -110,8 +110,6 @@ export interface SegmentNode<TFile = RouteFile> {
   jsonStatusFiles?: Record<string, TFile>;
   /** denied.tsx — slot-only denial rendering */
   denied?: TFile;
-  /** Legacy compat: not-found.tsx (maps to 404), forbidden.tsx (403), unauthorized.tsx (401) */
-  legacyStatusFiles?: Record<string, TFile>;
 
   /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
   metadataRoutes?: Record<string, TFile>;

package/src/routing/walkers.ts

@@ -49,6 +49,12 @@ export interface CollectLeafRoutesOptions {
  *   entries (the build report deduplicates by URL afterward).
  * - Parallel slots are skipped unless `includeSlots: true` (slots
  *   share their parent's URL and are not addressable on their own).
+ * - Intercepting subtrees are skipped unconditionally. They render only
+ *   on soft navigation and add no URL depth, so their computed `urlPath`s
+ *   are not addresses — listing them would advertise routes (`/[year]`)
+ *   that no request can reach. This matches every other consumer of the
+ *   tree that produces URLs: the sitemap generator, the static generator,
+ *   prerendering and the prebuilt-payload builder all skip them too.
  * - Result is sorted by `urlPath` for deterministic output.
  */
 export function collectLeafRoutes<TFile>(
@@ -68,6 +74,8 @@ function walk<TFile>(
   result: LeafRoute<TFile>[],
   includeSlots: boolean
 ): void {
+  if (node.segmentType === 'intercepting') return;
+
   const currentChain = [...chain, node];
   const path = node.urlPath || '/';
 

package/src/search-params/define.ts

@@ -14,35 +14,12 @@ import { useQueryStates as clientUseQueryStates } from '../client/use-query-stat
 import { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.js';
 import type { StandardSchemaV1 } from '../schema-bridge.js';
 import type { Codec } from '../codec.js';
-
-// Server-only reference for .get() — avoids pulling server ALS into client bundles.
-// In client environments, .get() throws before reaching this code path.
-//
-// IMPORTANT: This is set eagerly via _setGetSearchParamsFn() at server startup
-// (called from request-context.ts module initialization). It must NOT use
-// dynamic `await import()` at call time because the async microtask from the
-// dynamic import loses AsyncLocalStorage context in React's RSC Flight renderer,
-// breaking getSearchParams() in parallel slot pages. See TIM-523.
-let _getSearchParamsFn: (() => URLSearchParams) | undefined;
-
-/**
- * Register the getSearchParams function. Called once at module load time
- * from request-context.ts to avoid dynamic import at call time.
- * @internal
- */
-export function _setGetSearchParamsFn(fn: () => URLSearchParams): void {
-  _getSearchParamsFn = fn;
-}
-
-function getSearchParamsFromAls(): URLSearchParams {
-  if (!_getSearchParamsFn) {
-    throw new Error(
-      '[timber] searchParams.get() is only available on the server. ' +
-        'Use searchParams.useQueryStates() on the client.'
-    );
-  }
-  return _getSearchParamsFn();
-}
+// Server-only reference for .get() — avoids pulling server ALS into client
+// bundles. In client environments, .get() throws before reaching this code
+// path. The slot lives in its own leaf module so that `request-context.ts`
+// can register the getter without importing this file, which would drag
+// `nuqs` into every server entry (TIM-1298). See shared/als-slots.ts.
+import { getSearchParamsFromAls } from '../shared/als-slots.js';
 
 // ---------------------------------------------------------------------------
 // Types

package/src/segment-params/define.ts

@@ -16,33 +16,10 @@
 import type { Codec } from '../codec.js';
 import { type StandardSchemaV1, resolveCodecOrSchema } from '../schema-bridge.js';
 import { useSegmentParams as clientUseSegmentParams } from '../client/use-segment-params.js';
-
-// ---------------------------------------------------------------------------
-// Server-only ALS reference for .get()
-// ---------------------------------------------------------------------------
-
-// Same pattern as search-params: eagerly registered at server startup
-// to avoid dynamic imports that lose ALS context. See TIM-523.
-let _getSegmentParamsFn: (() => Record<string, string | string[]>) | undefined;
-
-/**
- * Register the getSegmentParams function. Called once at module load time
- * from request-context.ts to avoid dynamic import at call time.
- * @internal
- */
-export function _setGetSegmentParamsFn(fn: () => Record<string, string | string[]>): void {
-  _getSegmentParamsFn = fn;
-}
-
-function getSegmentParamsFromAls(): Record<string, string | string[]> {
-  if (!_getSegmentParamsFn) {
-    throw new Error(
-      '[timber] segmentParams.get() is only available on the server. ' +
-        'Use segmentParams.useSegmentParams() on the client.'
-    );
-  }
-  return _getSegmentParamsFn();
-}
+// Server-only ALS reference for .get(), eagerly registered at server startup
+// from a leaf module so this file stays out of the server graph. Same slot
+// mechanism as search-params. See shared/als-slots.ts, TIM-523, TIM-1298.
+import { getSegmentParamsFromAls } from '../shared/als-slots.js';
 
 // ---------------------------------------------------------------------------
 // Types

package/src/server/action-handler.ts

@@ -296,7 +296,9 @@ async function handleRscAction(
     // serialized together so React Flight handles both in one stream.
     payload = {
       _action: result.actionResult,
-      _tree: result.revalidation.element,
+      // The payload root, not a bare tree: it carries the revalidated
+      // route's params too, and the client publishes them (TIM-1297).
+      _tree: result.revalidation.payload,
     };
     headers['X-Timber-Revalidation'] = '1';
     // Metadata (<title>/<meta>/<link>) now rides the revalidation element

package/src/server/actions.ts

@@ -20,10 +20,13 @@ import { withSpan } from './tracing';
 import { revalidationAls, type RevalidationState } from './als-registry.js';
 // ─── Types ───────────────────────────────────────────────────────────────
 
-/** Result of rendering a revalidation — element tree before RSC serialization. */
+/** Result of rendering a revalidation — payload root before RSC serialization. */
 export interface RevalidationResult {
-  /** React element tree (pre-serialization — passed to renderToReadableStream). */
-  element: unknown;
+  /**
+   * The payload root — tree plus the params it rendered with, exactly as an
+   * ordinary route payload. The client splits it in `applyRevalidation`.
+   */
+  payload: unknown;
 }
 
 /** Renderer function that builds a React element tree for a given path. */

package/src/server/als-registry.ts

@@ -32,6 +32,7 @@
  */
 
 import '#server-only-guard';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { DebugComponentEntry } from './rsc-entry/helpers.js';
 
@@ -113,7 +114,7 @@ export interface RequestContextStore {
    *
    * See design/07-routing.md §"Parallel Slot Params"
    */
-  slotParamsMap?: Map<string, Record<string, string | string[]>>;
+  slotParams?: SlotParamsRecord;
   /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
   cookieJar: Map<string, CookieEntry>;
   /** Whether the response has flushed (headers committed). */

package/src/server/build-manifest.ts

@@ -49,13 +49,26 @@ export interface BuildManifest {
   requestDep?: Record<string, boolean>;
 }
 
-/** Empty build manifest used in dev mode. */
+/**
+ * Empty build manifest used in dev mode, and the single source of truth for
+ * what an empty manifest contains.
+ *
+ * `virtual:timber-build-manifest` serializes this constant into its generated
+ * source rather than restating it — one literal for the dev module, one for the
+ * production module's `globalThis.__TIMBER_BUILD_MANIFEST__ ?? …` fallback.
+ * They were three hand-written objects that had already drifted: this one and
+ * the dev literal were missing `requestDep` while the production fallback had
+ * it, so a reader who grepped the built bundle for `requestDep` found the one
+ * copy that mentioned it and read the fallback as the shipped map (TIM-1300).
+ * A field added here now reaches every copy.
+ */
 export const EMPTY_BUILD_MANIFEST: BuildManifest = {
   css: {},
   js: {},
   modulepreload: {},
   fonts: {},
   metadataRouteHashes: {},
+  requestDep: {},
 };
 
 /** Segment shape expected by collectRouteCss (matches ManifestSegmentNode). */

package/src/server/chain-url-parts.ts

@@ -0,0 +1,163 @@
+/**
+ * How much of the URL a matched segment chain has consumed.
+ *
+ * One question — "which URL parts had been consumed by the time segment `i`
+ * rendered?" — asked by four things that must all agree:
+ *
+ * - the layout depth handed to `SegmentProvider` (`route-element-builder.ts`),
+ *   which `useSelectedLayoutSegment(s)` indexes the live pathname with;
+ * - `slotUrlParts`, which slices the destination pathname for slot matching;
+ * - `resolveSlotProps`, which slices the *departing* pathname the same way to
+ *   decide whether a slot can be skipped;
+ * - `skippable-prefix.ts`, which does the same for the contiguous skip prefix.
+ *
+ * They were four separate `extractUrlParts(...).length` calls. That was fine
+ * while the answer was a plain walk, and stopped being fine when interception
+ * gave it a second term (TIM-1280): the fix landed on the layout depth alone
+ * and the other three kept the old walk, so a layout and the slots beside it
+ * disagreed about how deep they were. Hence one function, in its own module,
+ * rather than a helper on the side of whichever caller was fixed first.
+ *
+ * See design/07-routing.md §"Intercepting Routes".
+ */
+
+import type { ManifestSegmentNode } from './route-matcher.js';
+import type { RouteMatch } from './pipeline.js';
+import { effectiveUrlSegment } from '../routing/segment-classify.js';
+import { computeInterceptedBase } from '../routing/interception.js';
+
+/**
+ * Extract raw URL path parts from a 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[]`).
+ *
+ * The root segment is named '' and consumes nothing, so it is skipped here
+ * rather than by each caller — callers that pass a chain including the root
+ * (interception anchoring, slot-skip slicing) would otherwise have to remember
+ * to filter it, and one that forgot would push an empty part and shift every
+ * subsequent index by one.
+ *
+ * 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.
+ *
+ * Each node is read through `effectiveUrlSegment`, so an intercepting
+ * directory contributes the URL part it intercepts (`(.)item` → `item`,
+ * `(.)[id]` → the bound value). A children-path interception puts such a node
+ * in the *main* chain, and reading it directly would classify it as neither
+ * static nor param-bearing — it would contribute nothing, and every part after
+ * it would shift by one.
+ */
+export function extractUrlParts(
+  segments: ManifestSegmentNode[],
+  mainParams: Record<string, string | string[]>
+): string[] {
+  const parts: string[] = [];
+  for (const node of segments) {
+    const seg = effectiveUrlSegment(node);
+    // The root's *directory* name is empty; read it off the node, since an
+    // intercepting node's effective name is the one it intercepts.
+    if (seg.segmentType === 'group') continue;
+    if (node.segmentName === '') 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);
+      }
+    }
+  }
+  return parts;
+}
+
+/**
+ * Where a children-path interception sits in the target pathname, or null when
+ * the chain contains none.
+ *
+ * `anchor` is the intercepted base's length — the URL index the intercepting
+ * node occupies — from the same `computeInterceptedBase` that rewrite
+ * generation and the slot resolver both go through, so the three cannot
+ * disagree about which part a marker points at.
+ */
+function interceptionAnchor(
+  segments: ManifestSegmentNode[]
+): { index: number; anchor: number } | null {
+  const index = segments.findIndex((s) => s.segmentType === 'intercepting');
+  if (index <= 0) return null;
+
+  const owner = segments[index - 1];
+  const base = computeInterceptedBase(owner.urlPath, segments[index].interceptionMarker ?? '(.)');
+  return { index, anchor: base === '/' ? 0 : base.slice(1).split('/').length };
+}
+
+/**
+ * The URL parts the chain has consumed through `index`, inclusive.
+ *
+ * For an ordinary chain this is just the walk. Two things make it more than
+ * that, and both are cases where a node stands for a different number of URL
+ * parts than itself:
+ *
+ * - A **catch-all** consumes as many parts as the request supplies, which the
+ *   walk already handles (its param value is an array).
+ * - An **interception with a climbing marker** intercepts a URL that starts
+ *   *above* its owner, so the owner's own URL segment — and any static
+ *   ancestor between the intercepted base and the owner — is not in the target
+ *   at all. `feed/(..)photo/[id]` at `/photo/42` still has `feed` in the
+ *   chain, and counting it puts everything after it off by one.
+ *
+ * So everything above the interception clamps to the anchor, and everything
+ * from it down counts forward from there. The owner chain is param-free by
+ * build-time rule and the intercepted base is a prefix of the owner's
+ * `urlPath`, so the target's leading `anchor` parts *are* the owner chain's
+ * leading `anchor` parts — which is what makes the clamped prefix real values
+ * rather than placeholders. For `(.)` the base is the owner's own path, so the
+ * clamp is a no-op and this reduces to the plain walk.
+ */
+export function consumedUrlParts(
+  segments: ManifestSegmentNode[],
+  index: number,
+  match: RouteMatch
+): string[] {
+  const rawParams = match.rawSegmentParams ?? match.segmentParams ?? {};
+  const partsThrough = (from: number, to: number) =>
+    extractUrlParts(segments.slice(from, to + 1), rawParams);
+
+  const interception = interceptionAnchor(segments);
+  if (!interception) return partsThrough(0, index);
+
+  const targetPrefix = partsThrough(0, interception.index - 1).slice(0, interception.anchor);
+
+  if (index < interception.index) {
+    // Above the interception: an ancestor is never deeper than the anchor.
+    return targetPrefix.slice(0, Math.min(partsThrough(0, index).length, interception.anchor));
+  }
+  // At or below it: the intercepting subtree's parts ARE the target's.
+  return [...targetPrefix, ...partsThrough(interception.index, index)];
+}
+
+/**
+ * The index in `match.segments` of a segment, or -1.
+ *
+ * Split out so the three slot call sites and the layout-depth one derive their
+ * slice point identically — `indexOf` plus `consumedUrlParts` — instead of
+ * each inlining the pair.
+ */
+export function consumedPartsThroughSegment(
+  segment: ManifestSegmentNode,
+  match: RouteMatch
+): string[] {
+  const index = match.segments.indexOf(segment);
+  if (index < 0) return [];
+  return consumedUrlParts(match.segments as ManifestSegmentNode[], index, match);
+}

package/src/server/children-interception.ts

@@ -0,0 +1,115 @@
+/**
+ * Children-path interception — the sibling layout swap (TIM-1280).
+ *
+ * The second shape interception has. An intercepting directory that is a
+ * direct child of an ordinary segment or route group renders *in place of*
+ * `children` for that directory's own layout chain:
+ *
+ * ```
+ * app/(landing)/layout.tsx
+ * app/(landing)/[artistSlug]/[year]/[month]/[day]/page.tsx      ← hard nav
+ * app/(browse)/layout.tsx
+ * app/(browse)/(...)[artistSlug]/[year]/[month]/[day]/page.tsx  ← soft nav from (browse)
+ * ```
+ *
+ * There is no overlay, no slot, and no `default.tsx`. Nothing is re-matched
+ * either — and that is the point. The modal shape re-matches
+ * `interceptingPrefix`, a URL, and route groups contribute nothing to a URL,
+ * so an owner like `app/(browse)/` serializes to "/" and re-matching it
+ * resolves through whichever group owns the canonical page. This resolver
+ * addresses the owner by **tree path** instead, which never collapses.
+ *
+ * The result is an ordinary `RouteMatch` whose chain runs
+ * `[…owner ancestors, interceptingNode, …its matched descendants]`. Every
+ * consumer downstream — `tree-builder.ts`, the element builder, access gates,
+ * middleware — sees a segment chain and needs to know nothing about
+ * interception. That is why this feature adds no rendering path: the chain
+ * *is* the feature.
+ *
+ * See design/07-routing.md §"Intercepting Routes".
+ */
+
+import type { RouteMatch } from './pipeline.js';
+import { collectMiddlewareChain, type ManifestSegmentNode } from './route-matcher.js';
+import { findInterceptingMatch } from './slot-interception.js';
+import { treePathNames } from '../routing/segment-keys.js';
+
+/**
+ * Resolve a children-path interception to a complete route match.
+ *
+ * `interceptingScope` is the rewrite's own build-time field — the tree path of
+ * the directory that owns the interception. The pipeline has already
+ * established that the client's rendered tree passes through it; this
+ * translates it into the chain to render.
+ *
+ * Returns null when the scope names no directory in this manifest, or when no
+ * intercepting child of that directory matches the target. Both are fail-safe:
+ * the caller keeps the canonical target match, so the page the user gets is
+ * the one a hard navigation would have produced.
+ */
+export type InterceptedRouteMatcher = (
+  targetPathname: string,
+  interceptingScope: string
+) => RouteMatch | null;
+
+/** Build a children-path interception resolver over a runtime manifest. */
+export function createInterceptedRouteMatcher(root: ManifestSegmentNode): InterceptedRouteMatcher {
+  return (targetPathname, interceptingScope) => {
+    const ancestors = findChainByTreePath(root, interceptingScope);
+    if (!ancestors) return null;
+
+    const owner = ancestors[ancestors.length - 1];
+    // The same resolver the slot path uses. It takes an arbitrary node, buckets
+    // its intercepting children by the URL index their marker anchors them to,
+    // and walks each bucket with the shared tree walker — so marker depth,
+    // static-before-dynamic sibling ordering and catch-all handling are one
+    // implementation across both shapes rather than two that must agree.
+    const result = findInterceptingMatch(owner, targetPathname);
+    if (!result) return null;
+
+    // `result.chain` is [owner, interceptingNode, …descendants]; splice the
+    // owner's own ancestry in front of it to get a root-anchored chain.
+    const segments = [...ancestors, ...result.chain.slice(1)];
+
+    return {
+      segments,
+      // Every segment above the intercepting node is static or a route group —
+      // `validateInterceptionPlacement` rejects a dynamic one at build time,
+      // precisely because the intercepted URL carries no value to bind it
+      // with. So the intercepting subtree's params are the whole record.
+      segmentParams: result.slotParams,
+      middlewareChain: collectMiddlewareChain(segments),
+    };
+  };
+}
+
+/**
+ * Find the chain from the root to the segment with this tree path.
+ *
+ * Tree paths are `computeSegmentTreePaths` — the directory path with slots
+ * elided — so this walks `children` only, which is also exactly the set of
+ * positions a children-path interception can own: an intercepting directory
+ * inside a slot subtree is rejected at build time unless it is a direct slot
+ * child, and that shape is the modal one.
+ *
+ * Sibling directories cannot share a name, so a tree path names at most one
+ * node and the walk needs no tie-break. This is the property `urlPath` and
+ * `computeSegmentKeys` both lack — see the note on `computeSegmentTreePaths`.
+ */
+function findChainByTreePath(
+  root: ManifestSegmentNode,
+  treePath: string
+): ManifestSegmentNode[] | null {
+  const names = treePathNames(treePath);
+  const chain: ManifestSegmentNode[] = [root];
+  let node = root;
+
+  for (const name of names) {
+    const next = node.children.find((child) => child.segmentName === name);
+    if (!next) return null;
+    chain.push(next);
+    node = next;
+  }
+
+  return chain;
+}