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

package/src/server/als-registry.ts

@@ -6,28 +6,66 @@
  * this registry and re-export public accessor functions.
  *
  * Why: ALS instances require singleton semantics — if two copies of the
- * same ALS exist (one from a relative import, one from a barrel import),
- * one module writes to its copy and another reads from an empty copy.
- * Centralizing ALS creation in a single module eliminates this class of bug.
+ * same ALS exist (one from a relative import, one from a barrel import,
+ * or the same file re-evaluated by Vite after an HMR invalidation), one
+ * module writes to its copy and another reads from an empty copy.
+ * Centralizing ALS creation in a single module + anchoring each instance
+ * on `globalThis` under a `Symbol.for(...)` key eliminates this class of
+ * bug, including the Vite-dev case where module instance split would
+ * otherwise hand two copies of this file out of a single evaluation cycle.
  *
- * The `timber-shims` plugin ensures `@timber-js/app/server` resolves to
- * src/ in RSC and SSR environments, so all import paths converge here.
+ * The `timber-shims` plugin remaps `@timber-js/app/server` to src/ in
+ * RSC and SSR environments so import-specifier paths converge here, and
+ * the `globalThis[SYMBOL_FOR]` anchor below closes the remaining gap: any
+ * second evaluation of this module picks up the ALS the first evaluation
+ * already stored rather than instantiating a fresh one. Same pattern the
+ * Cloudflare bindings ALS uses in `adapters/cloudflare.ts`.
  *
  * DO NOT create ALS instances outside this file. If you need a new ALS,
  * add it here and import from `./als-registry.js` in the consuming module.
+ * Inside this file, always route through `getOrCreateAls(symbol)` — a raw
+ * `new AsyncLocalStorage()` reintroduces the instance-split hazard.
  *
  * See design/18-build-system.md §"Module Singleton Strategy" and
- * §"Singleton State Registry".
+ * §"Singleton State Registry". Regression test:
+ * `tests/als-registry-singleton.test.ts`.
  */
 
+import '#server-only-guard';
+import type { CoercedParams } from '../shared/param-value.js';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import type { DebugComponentEntry } from './rsc-entry/helpers.js';
+
+/**
+ * Return a process-wide singleton `AsyncLocalStorage` keyed by `symbol`.
+ *
+ * `Symbol.for(...)` keys live in the cross-realm symbol registry, and
+ * `globalThis` is shared across every module evaluation inside the same
+ * Node.js process. Together they give a stable anchor that survives
+ * re-evaluation of this file — the second evaluation observes the
+ * `globalThis[symbol]` slot already populated by the first and hands
+ * back the identical ALS instance.
+ */
+function getOrCreateAls<T>(symbol: symbol): AsyncLocalStorage<T> {
+  const g = globalThis as unknown as Record<symbol, unknown>;
+  const existing = g[symbol];
+  if (existing instanceof AsyncLocalStorage) {
+    return existing as AsyncLocalStorage<T>;
+  }
+  const created = new AsyncLocalStorage<T>();
+  g[symbol] = created;
+  return created;
+}
 
 // ─── Request Context ──────────────────────────────────────────────────────
-// Used by: request-context.ts (headers(), cookies(), searchParams())
+// Used by: request-context.ts (getHeaders(), getCookies(), getSearchParams())
 // Design doc: design/04-authorization.md
 
 /** @internal — import via request-context.ts public API */
-export const requestContextAls = new AsyncLocalStorage<RequestContextStore>();
+export const requestContextAls = getOrCreateAls<RequestContextStore>(
+  Symbol.for('timber:request-context-als')
+);
 
 export interface RequestContextStore {
   /** Incoming request headers (read-only view). */
@@ -39,28 +77,102 @@ export interface RequestContextStore {
   /** Original (pre-overlay) frozen headers, kept for overlay merging. */
   originalHeaders: Headers;
   /**
-   * Promise resolving to the route's typed search params (when search-params.ts
-   * exists) or to the raw URLSearchParams. Stored as a Promise so the framework
-   * can later support partial pre-rendering where param resolution is deferred.
+   * Raw URLSearchParams for the current request.
+   * To get typed parsed params, import a search params definition and
+   * call `.parse(searchParams())`.
+   */
+  searchParams: URLSearchParams;
+  /**
+   * Raw search string from the request URL (e.g. "?foo=bar&baz=1").
+   * Available synchronously for use in `redirect()` with `preserveSearchParams`.
    */
-  searchParamsPromise: Promise<URLSearchParams | Record<string, unknown>>;
+  searchString: string;
+  /**
+   * Coerced segment params for the current request.
+   * Set by the pipeline after route matching and param coercion, before
+   * middleware and rendering. Pages and layouts read params via
+   * `getSegmentParams()` instead of receiving them as a prop.
+   *
+   * See design/07-routing.md §"params.ts — Convention File for Typed Params"
+   */
+  segmentParams?: CoercedParams;
+  /**
+   * The matched segment path (e.g. '/(browse)/[artistSlug]/[year]').
+   * Includes route groups and parallel slots — uniquely identifies the
+   * segment in the route tree. Set by the pipeline alongside segmentParams.
+   * Used by getSegmentParams() for dev-mode validation.
+   * See design/41-global-params.md §Runtime Validation
+   */
+  matchedSegmentPath?: string;
+  /**
+   * Per-slot coerced segment params, keyed by the slot's full tree path
+   * (e.g. '/(browse)/@shows/[artistSlug]/[...year]').
+   *
+   * Each slot walks its own segment tree and may interpret URL parts
+   * differently from the main route (e.g. catch-all vs dynamic). This
+   * map stores slot-specific params so getSegmentParams(segmentPath)
+   * returns the correct types for slot pages.
+   *
+   * See design/07-routing.md §"Parallel Slot Params"
+   */
+  slotParams?: SlotParamsRecord;
   /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
   cookieJar: Map<string, CookieEntry>;
   /** Whether the response has flushed (headers committed). */
   flushed: boolean;
   /** Whether the current context allows cookie mutation. */
   mutableContext: boolean;
+  /**
+   * Set by AccessGate or PageDenyBoundary when a DenySignal is caught
+   * server-side (inside the React tree, before React Flight sees it).
+   * The pipeline reads this after render to set the HTTP status code.
+   * See TIM-666.
+   */
+  denyStatus?: number;
+  /**
+   * Callback fired when setDenyStatus() is called. Used by shellSettled
+   * to short-circuit when any component catches a DenySignal in-tree,
+   * regardless of which component caught it (AccessGate, TracedLayout,
+   * or PageDenyBoundary). See TIM-1208.
+   */
+  onDenyStatus?: () => void;
+  /**
+   * Dev-only: getter for the current request's RSC debug components.
+   * Set by renderRoute() so onPipelineError can include component tree
+   * context for render-phase errors without module-level shared state.
+   */
+  debugComponentsGetter?: () => DebugComponentEntry[];
+  /**
+   * Index of the first segment whose AccessGate denied during render.
+   * Recorded by AccessGate when it catches a DenySignal so post-render
+   * consumers (buildSegmentInfo, X-Timber-Segments header) can bound
+   * the segment list without a pre-render access pass. Infinity when
+   * no segment denied. See TIM-1363.
+   */
+  _firstDeniedSegmentIndex?: number;
+  /**
+   * Metadata entries collected during render by MetadataCollector.
+   * Populated per-segment in tree order (root→page) during
+   * renderToReadableStream. Entries may contain promises for dynamic
+   * metadata (resolved concurrently with page rendering, TIM-1367).
+   * MetadataHead awaits all entries before merging.
+   * See TIM-1363, TIM-1367, design/16-metadata.md.
+   */
+  _metadataEntries?: Array<{
+    metadata: import('./types.js').Metadata | Promise<import('./types.js').Metadata | null>;
+    isPage: boolean;
+  }>;
 }
 
 /** A single outgoing cookie entry in the cookie jar. */
 export interface CookieEntry {
   name: string;
   value: string;
-  options: import('./request-context.js').CookieOptions;
+  options: import('./cookie-context.js').CookieOptions;
 }
 
 // ─── Tracing ──────────────────────────────────────────────────────────────
-// Used by: tracing.ts (traceId(), spanId())
+// Used by: tracing.ts (getTraceId(), getSpanId())
 // Design doc: design/17-logging.md
 
 export interface TraceStore {
@@ -68,10 +180,17 @@ export interface TraceStore {
   traceId: string;
   /** OTEL span ID if available, undefined otherwise. */
   spanId?: string;
+  /**
+   * Innermost active native platform span (e.g. Cloudflare's `Span` from
+   * tracing.enterSpan()). Tracked so setSpanAttribute() can set attributes
+   * after span creation — the platform API has no getActiveSpan() equivalent.
+   * Saved/restored by withSpan() around each callback. See TIM-1135.
+   */
+  platformSpan?: import('./tracing.js').PlatformSpan;
 }
 
 /** @internal — import via tracing.ts public API */
-export const traceAls = new AsyncLocalStorage<TraceStore>();
+export const traceAls = getOrCreateAls<TraceStore>(Symbol.for('timber:trace-als'));
 
 // ─── Server-Timing ────────────────────────────────────────────────────────
 // Used by: server-timing.ts (recordTiming(), withTiming())
@@ -82,7 +201,7 @@ export interface TimingStore {
 }
 
 /** @internal — import via server-timing.ts public API */
-export const timingAls = new AsyncLocalStorage<TimingStore>();
+export const timingAls = getOrCreateAls<TimingStore>(Symbol.for('timber:timing-als'));
 
 // ─── Revalidation ─────────────────────────────────────────────────────────
 // Used by: actions.ts (revalidatePath(), revalidateTag())
@@ -96,14 +215,18 @@ export interface RevalidationState {
 }
 
 /** @internal — import via actions.ts public API */
-export const revalidationAls = new AsyncLocalStorage<RevalidationState>();
+export const revalidationAls = getOrCreateAls<RevalidationState>(
+  Symbol.for('timber:revalidation-als')
+);
 
 // ─── Form Flash ───────────────────────────────────────────────────────────
 // Used by: form-flash.ts (getFormFlash())
 // Design doc: design/08-forms-and-actions.md §"No-JS Error Round-Trip"
 
 /** @internal — import via form-flash.ts public API */
-export const formFlashAls = new AsyncLocalStorage<import('./form-flash.js').FormFlashData>();
+export const formFlashAls = getOrCreateAls<import('./form-flash.js').FormFlashData>(
+  Symbol.for('timber:form-flash-als')
+);
 
 // ─── Early Hints Sender ──────────────────────────────────────────────────
 // Used by: early-hints-sender.ts (sendEarlyHints103())
@@ -113,7 +236,9 @@ export const formFlashAls = new AsyncLocalStorage<import('./form-flash.js').Form
 export type EarlyHintsSenderFn = (links: string[]) => void;
 
 /** @internal — import via early-hints-sender.ts public API */
-export const earlyHintsSenderAls = new AsyncLocalStorage<EarlyHintsSenderFn>();
+export const earlyHintsSenderAls = getOrCreateAls<EarlyHintsSenderFn>(
+  Symbol.for('timber:early-hints-sender-als')
+);
 
 // ─── waitUntil Bridge ────────────────────────────────────────────────────
 // Used by: waituntil-bridge.ts (waitUntil())
@@ -123,4 +248,18 @@ export const earlyHintsSenderAls = new AsyncLocalStorage<EarlyHintsSenderFn>();
 export type WaitUntilFn = (promise: Promise<unknown>) => void;
 
 /** @internal — import via waituntil-bridge.ts public API */
-export const waitUntilAls = new AsyncLocalStorage<WaitUntilFn>();
+export const waitUntilAls = getOrCreateAls<WaitUntilFn>(Symbol.for('timber:wait-until-als'));
+
+// ─── Workers Cache Purge Bridge ─────────────────────────────────────────
+// Used by: workers-cache-bridge.ts (runWithWorkersCachePurge())
+// Design doc: design/06-caching.md, design/25-production-deployments.md
+
+/** Workers Cache purge function from Cloudflare ExecutionContext.cache. */
+export interface WorkersCachePurgeCtx {
+  purge(opts: { tags: string[] }): Promise<void>;
+}
+
+/** @internal — import via workers-cache-bridge.ts public API */
+export const workersCachePurgeAls = getOrCreateAls<WorkersCachePurgeCtx>(
+  Symbol.for('timber:workers-cache-purge-als')
+);

package/src/server/asset-headers.ts

@@ -8,13 +8,25 @@
  * Unhashed assets (e.g. /favicon.ico) get a shorter cache with revalidation:
  *   Cache-Control: public, max-age=3600, must-revalidate
  *
- * This is applied automatically by the framework for static assets served
- * from the build output. Page responses are NOT affected — those are
- * controlled by the developer via middleware.ts or proxy.ts.
+ * The `_headers` file lists hashed asset paths (/assets/*, /_timber/fonts/*) as
+ * wildcard rules and unhashed files as per-file rules. At runtime, adapters
+ * that see static file requests (nitro, preview) also set Cache-Control via
+ * `getAssetCacheControl()`. On Cloudflare Workers Static Assets, the worker
+ * never sees static file requests — the `_headers` file is the only mechanism.
+ * Page responses are NOT affected — those are controlled by the developer
+ * via middleware.ts or proxy.ts.
  *
  * Design docs: 18-build-system.md, 06-caching.md
  */
 
+import { IMMUTABLE_CACHE, STATIC_CACHE } from '../adapters/shared.js';
+
+// Re-export cache constants and generateHeadersFile from the shared adapter
+// module. The canonical definitions live in adapters/shared.ts because
+// adapters are loaded by Node before Vite's resolver is available — they
+// can only import from within their own directory.
+export { IMMUTABLE_CACHE, STATIC_CACHE, generateHeadersFile } from '../adapters/shared.js';
+
 /**
  * Regex matching Vite-hashed asset filenames.
  *
@@ -30,18 +42,6 @@
  */
 const HASHED_ASSET_RE = /[-.][\da-f]{8,}\.\w+$/;
 
-/** One year in seconds (365 days). */
-const ONE_YEAR = 31_536_000;
-
-/** One hour in seconds. */
-const ONE_HOUR = 3_600;
-
-/** Cache-Control value for hashed (immutable) assets. */
-export const IMMUTABLE_CACHE = `public, max-age=${ONE_YEAR}, immutable`;
-
-/** Cache-Control value for unhashed static assets. */
-export const STATIC_CACHE = `public, max-age=${ONE_HOUR}, must-revalidate`;
-
 /**
  * Check if a URL path looks like a hashed asset.
  */
@@ -57,25 +57,3 @@ export function isHashedAsset(pathname: string): boolean {
 export function getAssetCacheControl(pathname: string): string {
   return isHashedAsset(pathname) ? IMMUTABLE_CACHE : STATIC_CACHE;
 }
-
-/**
- * Generate a `_headers` file for static asset cache control.
- *
- * The `_headers` file is a platform convention supported by Cloudflare Workers
- * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
- * HTTP response headers.
- *
- * Vite places all hashed chunks under `/assets/` — these get immutable caching.
- * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.
- */
-export function generateHeadersFile(): string {
-  return `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
-
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/*
-  Cache-Control: ${STATIC_CACHE}
-`;
-}

package/src/server/body-limits.ts

@@ -53,6 +53,9 @@ export function parseBodySize(size: string): number {
   }
 }
 
+/** Strict integer pattern: one or more digits, nothing else. */
+const STRICT_INTEGER_RE = /^\d+$/;
+
 /** Check whether a request body exceeds the configured size limit (stateless, no ALS). */
 export function enforceBodyLimits(
   req: Request,
@@ -66,11 +69,16 @@ export function enforceBodyLimits(
     return { ok: false, status: 411 };
   }
 
-  const bodySize = Number.parseInt(contentLength, 10);
-  if (Number.isNaN(bodySize)) {
+  // Reject malformed values: multiple values ("100, 999999"), negative numbers,
+  // floats ("100.5"), or non-numeric strings. parseInt would silently parse
+  // the first number from "100, 999999" as 100, letting the real body through.
+  const trimmed = contentLength.trim();
+  if (!STRICT_INTEGER_RE.test(trimmed)) {
     return { ok: false, status: 411 };
   }
 
+  const bodySize = Number.parseInt(trimmed, 10);
+
   const limit = resolveLimit(kind, config);
   return bodySize <= limit ? { ok: true } : { ok: false, status: 413 };
 }

package/src/server/build-manifest.ts

@@ -35,14 +35,40 @@ export interface BuildManifest {
   modulepreload: Record<string, string[]>;
   /** Map from input file path to font assets used by that module. */
   fonts: Record<string, ManifestFontEntry[]>;
+  /**
+   * Cache-busting hashes for metadata route files (opengraph-image, etc.).
+   * Map from file path (relative to project root) to short content hash.
+   * In dev mode this is empty — a startup nonce is used instead.
+   */
+  metadataRouteHashes?: Record<string, string>;
+  /**
+   * Static request-dependency map from the Vite plugin's module-graph analysis.
+   * Map from segment entry file path to whether it's request-dependent.
+   * Used by buildSegmentInfo() for X-Timber-Segments in production.
+   */
+  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). */
@@ -85,22 +111,15 @@ export function collectRouteCss(segments: SegmentWithFiles[], manifest: BuildMan
  * via injectHead() before </head>.
  */
 export function buildCssLinkTags(cssUrls: string[]): string {
+  // Emit only <link rel="stylesheet"> — no preload tags. CSS preloading
+  // is handled by 103 Early Hints (Link header) which fires before the
+  // HTML stream. Float also emits `<link rel="stylesheet" data-precedence>`
+  // at the top of <head> during Fizz rendering — the browser discovers
+  // CSS from that tag. A <link rel="preload"> here would arrive *after*
+  // Float's stylesheet tag and trigger "Preload was ignored" warnings.
   return cssUrls.map((url) => `<link rel="stylesheet" href="${url}">`).join('');
 }
 
-/**
- * Generate a Link header value for CSS preload hints.
- *
- * Cloudflare CDN automatically converts Link headers with rel=preload
- * into 103 Early Hints responses. This avoids platform-specific 103
- * sending code.
- *
- * Example output: `</assets/root.css>; rel=preload; as=style, </assets/page.css>; rel=preload; as=style`
- */
-export function buildLinkHeaders(cssUrls: string[]): string {
-  return cssUrls.map((url) => `<${url}>; rel=preload; as=style`).join(', ');
-}
-
 // ─── Font utilities ──────────────────────────────────────────────────────
 
 /**
@@ -148,44 +167,8 @@ export function buildFontPreloadTags(fonts: ManifestFontEntry[]): string {
     .join('');
 }
 
-/**
- * Generate Link header values for font preload hints.
- *
- * Cloudflare CDN converts Link headers with rel=preload into 103 Early Hints.
- *
- * Example: `</fonts/inter.woff2>; rel=preload; as=font; crossorigin`
- */
-export function buildFontLinkHeaders(fonts: ManifestFontEntry[]): string {
-  return fonts.map((f) => `<${f.href}>; rel=preload; as=font; crossorigin`).join(', ');
-}
-
 // ─── JS chunk utilities ──────────────────────────────────────────────────
 
-/**
- * Collect JS chunk URLs for a matched route's segment chain.
- *
- * Walks segments root → leaf, collecting the JS chunk for each layout
- * and page. Deduplicates while preserving order.
- */
-export function collectRouteJs(segments: SegmentWithFiles[], manifest: BuildManifest): string[] {
-  const seen = new Set<string>();
-  const result: string[] = [];
-
-  for (const segment of segments) {
-    for (const file of [segment.layout, segment.page]) {
-      if (!file) continue;
-      const jsUrl = manifest.js[file.filePath];
-      if (!jsUrl) continue;
-      if (!seen.has(jsUrl)) {
-        seen.add(jsUrl);
-        result.push(jsUrl);
-      }
-    }
-  }
-
-  return result;
-}
-
 /**
  * Collect modulepreload URLs for a matched route's segment chain.
  *
@@ -225,10 +208,3 @@ export function collectRouteModulepreloads(
 export function buildModulepreloadTags(urls: string[]): string {
   return urls.map((url) => `<link rel="modulepreload" href="${url}">`).join('');
 }
-
-/**
- * Generate a <script type="module"> tag for a JS entry point.
- */
-export function buildEntryScriptTag(url: string): string {
-  return `<script type="module" src="${url}"></script>`;
-}

package/src/server/canonicalize.ts

@@ -13,11 +13,14 @@ export type CanonicalizeResult = { ok: true; pathname: string } | { ok: false; s
 /**
  * Encoded separators that produce a 400 rejection.
  * %2f (/) and %5c (\) cause path-confusion attacks.
+ *
+ * Shared between the runtime canonicalizer and the build-time route scanner
+ * to ensure both enforce identical security rules. See design/13-security.md.
  */
-const ENCODED_SEPARATOR_RE = /%2f|%5c/i;
+export const ENCODED_SEPARATOR_RE = /%2f|%5c/i;
 
-/** Null byte — rejected. */
-const NULL_BYTE_RE = /%00/i;
+/** Null byte — rejected. Shared with the route scanner. */
+export const NULL_BYTE_RE = /%00/i;
 
 /**
  * Canonicalize a URL pathname.

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` and `skippable-prefix.ts`, which derive content keys
+ *   for slot skip decisions (TIM-1370).
+ *
+ * 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 type { CoercedParams } from '../shared/param-value.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: CoercedParams
+): 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);
+}