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

package/dist/routing/collision-probe.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The order-dependence oracle shared by every route collision validator.
+ *
+ * A "collision space" is a set of pages that compete for URLs with each other:
+ * the main tree, each parallel slot, each intercepting subtree. Two pages in
+ * one space that answer the same URL are ambiguous — `matchNode` resolves the
+ * tie by whichever `children` array lists first, so which page renders is
+ * decided by filesystem enumeration order and renaming a route group can flip
+ * it. Every space rejects that shape, and they all reject it the same way,
+ * through this module.
+ *
+ * **The check asks the real matcher rather than modelling it.** For each leaf
+ * we build a URL it matches, then run `matchUrlParts` twice — once on the
+ * space, once on a clone with every `children` array reversed — and compare the
+ * winners. A URL answered by two or more candidates in the same priority tier
+ * resolves to whichever comes first in `children`, so reversing the arrays
+ * flips it; a URL with a single winner, or one settled by a higher tier, is
+ * unaffected. Order-dependence is therefore detected exactly, with no second
+ * copy of the precedence rules to drift.
+ *
+ * That drift is why this is written as an oracle. The interception validator's
+ * first version normalized each pattern into a "match shape" and compared
+ * shapes, which meant reimplementing `matchNode`'s tiers, its group flattening,
+ * and its zero-length optional-catch-all handling. Five review rounds found
+ * five divergences between the two — param spelling, a zero-length catch-all,
+ * the bracket tokens colliding with legal static directory names, a page
+ * settling a grouped catch-all, and a page settling a *direct* one (which the
+ * model could not express at all, because `matchNode` checks every route-group
+ * page before any direct optional catch-all). Each fix was locally right and
+ * the next divergence surfaced anyway. The model was the defect.
+ *
+ * **Every claim made here is existential** — "here is a URL these two contend
+ * for" — which is what a finite set of probes can actually establish. The
+ * reverse, "this page can never win any URL", is universal, and a probe's
+ * silence is not evidence for it: a leaf that loses every probe may still own
+ * URLs no probe visited. An earlier revision reported that as an
+ * unreachable-page error and produced two false build errors in one review
+ * round. Probe inadequacy must only ever cost a missed collision, never a
+ * rejected app — so nothing here may report a leaf as unreachable.
+ *
+ * See design/07-routing.md §"Comparing Routes by the URLs They Match".
+ */
+import type { SegmentNode } from './types.js';
+/** One page-or-route-bearing node in a collision space. */
+export interface ProbeLeaf {
+    /** The file that serves it — what the error message names. */
+    filePath: string;
+    /**
+     * The nodes from the space root down to this leaf that contribute URL parts
+     * — route groups excluded, since they are transparent for matching. Empty
+     * for the space root's own page: `matchUrlParts` matches parts against the
+     * root's *children*, so the root itself consumes nothing.
+     */
+    chain: SegmentNode[];
+}
+/** Two files in one space that a single URL resolves to order-dependently. */
+export interface ProbedCollision {
+    /** The contended URL, written for a human (see `describeProbeUrl`). */
+    url: string;
+    /** The file that wins in filesystem order. */
+    first: string;
+    /** The file that wins when every `children` array is reversed. */
+    second: string;
+}
+/**
+ * Find a URL in this collision space whose winner depends on `children` order,
+ * or null if every probed URL resolves the same way in both orderings.
+ *
+ * `spaceRoot` is the node `matchUrlParts` starts from — the app root, a slot
+ * node, or an intercepting directory. `base` is the URL that root sits at, used
+ * only to render the reported URL.
+ */
+export declare function findOrderDependentCollision(spaceRoot: SegmentNode, leaves: Iterable<ProbeLeaf>, base: string): ProbedCollision | null;
+/**
+ * The values a probe's dynamic parts are tried with, in order.
+ *
+ * A probe stands in for "any value" at a dynamic position, so it is only useful
+ * if it reaches the leaf it was built for. A *static* sibling's literal name or
+ * a more specific *affixed* sibling's pattern can claim it instead, and that
+ * higher-priority segment then wins in both orderings — a genuine tie
+ * underneath goes unreported, which is safe but is the whole thing these
+ * validators are for.
+ *
+ * Which values are claimable is a question about `matchNode`'s precedence, so
+ * `probeUrlsForLeaf` asks `matchUrlParts` rather than deciding it here. This
+ * only has to offer enough shapes for the search to find one that works: an
+ * affixed sibling constrains the head of the value, its tail, or both, so head
+ * and tail are varied over an alphanumeric alphabet. The head varies fastest
+ * because a prefix is the more common affix. Exhausting the list is a missed
+ * collision like any other inadequate probe, so this is a search and not a
+ * proof — nothing downstream may treat it as one.
+ *
+ * Exported so a test that has to *name* a capturing static sibling can derive
+ * the name from this list rather than restate it — a fixture spelling the value
+ * out by hand stops being a capture the moment the list changes, and passes.
+ *
+ * Three revisions of a hand-built value each dodged one more capture and were
+ * each followed by another (avoid static names; avoid affix boundary
+ * characters; avoid re-affixed forms of static names — then a strictly more
+ * specific affixed sibling, TIM-1313). Each rule was modelling affix precedence
+ * by hand, which is what the match-shape model was deleted for.
+ */
+export declare function probeCandidates(minLength?: number): Generator<string>;
+//# sourceMappingURL=collision-probe.d.ts.map

package/dist/routing/collision-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collision-probe.d.ts","sourceRoot":"","sources":["../../src/routing/collision-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAQ9C,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,WAAW,EACtB,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,eAAe,GAAG,IAAI,CA4CxB;AA2CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAiB,eAAe,CAAC,SAAS,SAAI,GAAG,SAAS,CAAC,MAAM,CAAC,CA6BjE"}

package/dist/routing/collision-spaces.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Route collision spaces.
+ *
+ * A collision space is a set of routes that compete for URLs with each other,
+ * and there are three: the main tree, each parallel slot, and each intercepting
+ * subtree. This module owns the first two; `interception.ts` owns the third.
+ * All of them decide order-dependence with the one oracle in
+ * `collision-probe.ts`, so they cannot drift on what counts as two routes
+ * answering a single URL.
+ *
+ * See design/07-routing.md §"Route Collisions".
+ */
+import type { SegmentNode } from './types.js';
+/**
+ * Validate that no two pages/routes in one collision space answer the same URL.
+ *
+ * Two route groups like (auth)/login/page.tsx and (marketing)/login/page.tsx both claim
+ * /login — the scanner must detect and reject this at build time.
+ *
+ * Each parallel slot is validated as its OWN collision space: a slot's pages
+ * intentionally share URL paths with the parent tree (that's the point of
+ * parallel routes), but two route groups INSIDE one slot claiming the same
+ * URL — e.g. @side/(a)/x/page.tsx + @side/(b)/x/page.tsx — still collide.
+ */
+export declare function validateRouteGroupCollisions(root: SegmentNode): void;
+//# sourceMappingURL=collision-spaces.d.ts.map

package/dist/routing/collision-spaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collision-spaces.d.ts","sourceRoot":"","sources":["../../src/routing/collision-spaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAEpE"}

package/dist/routing/index.js

@@ -1,4 +1,4 @@
-import { i as INTERCEPTION_MARKERS, n as classifyUrlSegment, r as DEFAULT_PAGE_EXTENSIONS, t as classifySegment } from "../_chunks/segment-classify-Byy425ng.js";
-import { i as scanRoutes } from "../_chunks/cli-schema-sync-BTWEKJXo.js";
-import { a as generateRouteMap, i as validateSchemaAgainstRoutes, n as collectInterceptionRewrites, r as collectDynamicSegmentsFromTree, t as collectLeafRoutes } from "../_chunks/walkers-_6zKFlch.js";
+import { a as collectInterceptionRewrites, i as scanRoutes } from "../_chunks/cli-schema-sync-CKgHC2MB.js";
+import { a as INTERCEPTION_MARKERS, i as DEFAULT_PAGE_EXTENSIONS, n as classifyUrlSegment, t as classifySegment } from "../_chunks/segment-classify-C539Pa2O.js";
+import { i as generateRouteMap, n as collectDynamicSegmentsFromTree, r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "../_chunks/walkers-BhhwI9TD.js";
 export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS, classifySegment, classifyUrlSegment, collectDynamicSegmentsFromTree, collectInterceptionRewrites, collectLeafRoutes, generateRouteMap, scanRoutes, validateSchemaAgainstRoutes };

package/dist/routing/interception.d.ts

@@ -16,26 +16,255 @@
  *
  * See design/07-routing.md §"Intercepting Routes"
  */
-import type { SegmentNode } from './types.js';
-/** A conditional rewrite rule generated from an intercepting route. */
-export interface InterceptionRewrite {
+import type { SegmentNode, InterceptionMarker } from './types.js';
+/** Fields shared by both interception shapes. */
+interface InterceptionRewriteBase {
     /**
      * The URL pattern that this rewrite intercepts (the target of navigation).
      * E.g., "/photo/[id]" for a (.)photo/[id] interception.
      */
     interceptedPattern: string;
     /**
-     * The URL prefix that the client must be navigating FROM for this rewrite
-     * to apply. Matched against the X-Timber-URL header.
-     * E.g., "/feed" for a (.)photo/[id] inside /feed/@modal/.
+     * The tree path of the segment that OWNS the slot holding this
+     * intercepting route (`computeSegmentTreePaths`, e.g. "/feed",
+     * "/(browse)", "/(browse)/feed", or "/" at the app root).
+     *
+     * The rewrite only applies when the source route — the page the user is
+     * navigating FROM — passes through that directory, because only then
+     * does the slot holding the intercepting page exist in the rendered
+     * tree. The server checks this by matching X-Timber-URL and testing its
+     * segment chain's tree paths for this value.
+     *
+     * Neither of the identities already in the codebase works here:
+     *
+     * - A **URL prefix** cannot express it. Route groups contribute nothing
+     *   to `urlPath`, so `(browse)/@detail/(...)x` and a genuinely
+     *   root-level `@modal/(...)x` both have prefix "/" while meaning very
+     *   different things.
+     * - A **state-tree key** (`computeSegmentKeys`) cannot either. It
+     *   qualifies a group with its ancestry but resets to `urlPath` at the
+     *   next URL-visible segment, so `(browse)/feed` and `(landing)/feed`
+     *   both key as "/feed" — and a navigation inside `(landing)/feed/…`
+     *   would reach `(browse)/feed`'s slot.
+     *
+     * Tree paths never reset, so two directories that render different
+     * layouts never share one. "/" as a scope means the app root, which
+     * every route passes through — preserving the intentional
+     * match-from-anywhere behavior of a root-level `(...)` interception
+     * (TIM-1006) without an exemption. See TIM-1279.
+     */
+    interceptingScope: string;
+}
+/**
+ * A conditional rewrite rule generated from an intercepting route.
+ *
+ * `mode` records which of the two shapes the directory expresses, because the
+ * two render through entirely different mechanisms and the fields they need
+ * are not the same. It is a union rather than a flag so a reader cannot
+ * re-match `interceptingPrefix` on the shape that has no such pathname.
+ *
+ * See design/07-routing.md §"Intercepting Routes".
+ */
+export type InterceptionRewrite = SlotInterceptionRewrite | ChildrenInterceptionRewrite;
+/**
+ * A **modal overlay** interception — the intercepting directory is a direct
+ * child of a parallel slot (`feed/@modal/(.)photo/[id]`).
+ *
+ * The server re-matches the *source* route and the slot resolver finds the
+ * intercepting child inside the slot, so the intercepting page layers over
+ * the page the user was already on.
+ */
+export interface SlotInterceptionRewrite extends InterceptionRewriteBase {
+    mode: 'slot';
+    /**
+     * The pathname the server re-matches when this rewrite applies — the
+     * intercepting slot owner's URL path. E.g., "/feed" for a (.)photo/[id]
+     * inside /feed/@modal/.
+     *
+     * This is a build-time constant, never a client-supplied value: the
+     * X-Timber-URL header selects a rewrite but never becomes the rendered
+     * pathname.
      */
     interceptingPrefix: string;
 }
+/**
+ * A **sibling layout swap** interception — the intercepting directory is a
+ * direct child of an ordinary segment or route group
+ * (`(browse)/(...)[artistSlug]/…`).
+ *
+ * There is no overlay, no slot and no `default.tsx`: the intercepting page
+ * *replaces* `children` for the owner's layout chain. Nothing is re-matched
+ * either. The server resolves the owner by `interceptingScope` — a tree path,
+ * which identifies exactly one directory — and builds the rendered chain as
+ * `[…owner ancestors, interceptingNode, …its matched descendants]`. That is an
+ * ordinary segment chain, so `tree-builder.ts` renders it with no knowledge
+ * that interception happened.
+ *
+ * Resolving the owner from the tree rather than from a URL is what makes this
+ * shape work where the modal shape cannot: `interceptingPrefix` is
+ * URL-derived, and a route group contributes nothing to `urlPath`, so an owner
+ * like `app/(browse)/` serializes to "/" and re-matching it lands in whichever
+ * group owns the canonical page. A tree path never collapses (TIM-1280).
+ */
+export interface ChildrenInterceptionRewrite extends InterceptionRewriteBase {
+    mode: 'children';
+}
+/**
+ * A set of sibling interceptors that compete for one URL position.
+ *
+ * `base` is the intercepted base they share — the URL their own segments sit
+ * directly under — and `anchorIndex` is how many URL parts that base spans,
+ * which is the index in a target pathname their segments are matched at.
+ * Deeper anchors are more local and are tried first.
+ */
+export interface InterceptorAnchorGroup<TFile> {
+    base: string;
+    anchorIndex: number;
+    interceptors: SegmentNode<TFile>[];
+}
+/**
+ * Group an owner's intercepting children by the URL position they contend for.
+ *
+ * This is the definition of *which interceptors compete*, and it has exactly
+ * one caller shape on each side of the build: `findInterceptingMatch` resolves
+ * a group with one `matchUrlParts` walk, and
+ * `assertNoInterceptedPatternCollisions` validates the same group as one
+ * collision space. Written twice, the two would be free to disagree about what
+ * competes — and a resolver that walks a wider set than the validator checked
+ * is precisely the order-dependence the validator exists to reject (TIM-1310).
+ *
+ * Contention is keyed by the computed intercepted **base**, not by the marker:
+ * under an owner at `/feed`, `(..)` and `(...)` both base at `/` and are both
+ * matched at index 0, so they are one group. Different bases are different
+ * positions — a `(.)` interceptor can never claim a target that belongs to a
+ * `(..)` one beside it, because the base must also match the target's leading
+ * parts.
+ *
+ * The base is a URL *pattern*, so its length is its part count only because
+ * every pattern part stands for exactly one URL part. A catch-all in the base
+ * breaks that, and `assertInterceptedBaseIsCountable` rejects the shape at
+ * build time.
+ *
+ * A node missing either marker field is skipped, which `classifySegment` never
+ * produces — it sets both whenever it reports `'intercepting'`. Stating the
+ * filter here rather than defaulting the marker is what makes the validator and
+ * the resolver see the same set: such a node renders nothing either way, and a
+ * validator more permissive than the resolver would be checking a candidate
+ * that never competes while the resolver walks one nobody checked.
+ *
+ * `children` is read directly rather than flattened through route groups,
+ * matching both resolvers: the slot resolver reads `slotNode.children`, and an
+ * interceptor deeper inside a slot subtree is rejected by
+ * `validateInterceptionPlacement`. On the children path an interceptor under a
+ * route group is legal and the *group* is its owner, so it is grouped with that
+ * group's other interceptors — which is again exactly what the resolver walks,
+ * since it resolves the owner by tree path.
+ */
+export declare function groupByInterceptedAnchor<TFile>(ownerUrlPath: string, children: readonly SegmentNode<TFile>[]): InterceptorAnchorGroup<TFile>[];
 /**
  * Collect all interception rewrite rules from the route tree.
  *
  * Walks the tree recursively. For each intercepting segment, computes the
  * intercepted URL based on the marker and the segment's position.
+ *
+ * The list is returned **deepest scope first**, which is what makes
+ * `findInterceptionMatch`'s first-match rule deterministic; see
+ * `sortByScopeDepth`.
  */
 export declare function collectInterceptionRewrites(root: SegmentNode): InterceptionRewrite[];
+/**
+ * Validate that every intercepting segment sits where it can actually render.
+ *
+ * There are exactly two positions a renderer exists for, and they are the two
+ * shapes interception has:
+ *
+ * 1. **Direct child of a parallel slot** — the modal overlay. The slot
+ *    resolver scans a slot node's *direct children* for an intercepting
+ *    segment (`server/slot-interception.ts`). Nothing between the slot and
+ *    the intercepting directory is allowed, because nothing walks it.
+ * 2. **Direct child of an ordinary segment or route group** — the sibling
+ *    layout swap (TIM-1280). The pipeline resolves the owner by tree path and
+ *    builds the rendered chain through the intercepting node itself
+ *    (`server/children-interception.ts`).
+ *
+ * Everywhere else, rewrite generation still emits a rewrite and nothing
+ * renders it: the rewrite matches the soft navigation, and the user is served
+ * the page they were already on under a changed URL (TIM-1278). The rejected
+ * positions are:
+ *
+ * - **Inside a slot subtree but not directly under the slot**
+ *   (`@modal/(inner)/(.)photo`). Neither renderer applies: the slot resolver
+ *   only reads direct children, and the children-path resolver builds a
+ *   *chain*, which cannot express a descent through a slot.
+ * - **Inside another intercepting subtree** (`(.)a/(.)b`). Left unvalidated
+ *   `collectLeavesWithRewrites` walks the inner one as an ordinary URL
+ *   segment and emits a pattern containing a literal "(.)b".
+ *
+ * Two further shapes are rejected here (TIM-1288). Both are about a catch-all,
+ * and both are specific to interception: elsewhere in the tree the same
+ * shapes are inert or fail safely, and the general "nothing below a catch-all
+ * is reachable" rule is tracked as TIM-1286.
+ *
+ * And one is specific to the children path: an owner chain that binds params
+ * (see `assertOwnerChainBindsNoParams`).
+ */
+export declare function validateInterceptionPlacement(root: SegmentNode): void;
+/**
+ * The URL-matching identity of an intercepting node, as a node.
+ *
+ * `matchUrlParts` reads `segmentType` directly and knows nothing about
+ * interception, so a marker'd directory has to be handed to it under the
+ * identity of the segment it intercepts — `(.)[id]` as `[id]`. Priority
+ * ordering, affix stripping and catch-all handling then come from the shared
+ * walker rather than from a second classifier here.
+ *
+ * Shared with `findInterceptingMatch` for the same reason the grouping is: the
+ * collision space is the resolver's synthetic anchor parent, so its children
+ * have to carry the identity the resolver gives them or the validator would be
+ * probing a tree that does not match the one served. The caller keeps its own
+ * map back to the real node — the proxy is a matching identity, not a
+ * replacement (tree paths still need the directory name).
+ */
+export declare function interceptorProxy<TFile>(node: SegmentNode<TFile>): SegmentNode<TFile>;
+/**
+ * Compute the base URL that an intercepting route intercepts, given the
+ * parent's URL path and the interception marker.
+ *
+ * - (.)  — same level: parent's URL path
+ * - (..) — one level up: parent's parent URL path
+ * - (...) — root level: /
+ * - (..)(..) — two levels up: parent's grandparent URL path
+ *
+ * The result is a URL **pattern**, not a URL — `parentUrlPath` carries the
+ * directory names, so a dynamic ancestor appears as `/docs/[...path]`.
+ * Rewrite generation wants exactly that. The slot resolver imports this to
+ * locate the intercepted segment in a concrete target pathname, and must
+ * therefore account for a bracket part standing for a different number of
+ * URL parts than itself (TIM-1281).
+ *
+ * Climbing past the root clamps to `/` rather than erroring, so generation
+ * and resolution never disagree about what an over-reaching marker
+ * intercepts.
+ */
+/**
+ * The URL pattern an intercepting directory's own page sits at — its
+ * `computeInterceptedBase` joined with the segment it intercepts.
+ *
+ * The root case is why this is a function rather than a template literal at
+ * each caller: a base of `/` must not produce `//photo`. Rewrite generation
+ * and the collision validator both start their walk from this value, so the
+ * two describe the same URLs by construction.
+ */
+export declare function computeInterceptedUrlBase(parentUrlPath: string, marker: InterceptionMarker, interceptedSegmentName: string): string;
+/**
+ * An intercepted base joined with one segment beneath it.
+ *
+ * The whole content of the "function rather than a template literal" rule
+ * above: a base of `/` must not produce `//photo`. The collision validator has
+ * the base in hand already (it groups by it) and joins through this rather than
+ * re-deriving it from an owner path, so both callers spell the root case once.
+ */
+export declare function joinInterceptedBase(base: string, segmentName: string): string;
+export declare function computeInterceptedBase(parentUrlPath: string, marker: InterceptionMarker): string;
+export {};
 //# sourceMappingURL=interception.d.ts.map

package/dist/routing/interception.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interception.d.ts","sourceRoot":"","sources":["../../src/routing/interception.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,YAAY,CAAC;AAElE,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,WAAW,GAAG,mBAAmB,EAAE,CAIpF"}
+{"version":3,"file":"interception.d.ts","sourceRoot":"","sources":["../../src/routing/interception.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAa,MAAM,YAAY,CAAC;AAQ7E,iDAAiD;AACjD,UAAU,uBAAuB;IAC/B;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,uBAAuB,GAAG,2BAA2B,CAAC;AAExF;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAwB,SAAQ,uBAAuB;IACtE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,2BAA4B,SAAQ,uBAAuB;IAC1E,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB,CAAC,KAAK;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAC5C,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,SAAS,WAAW,CAAC,KAAK,CAAC,EAAE,GACtC,sBAAsB,CAAC,KAAK,CAAC,EAAE,CAuBjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,WAAW,GAAG,mBAAmB,EAAE,CAIpF;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAOrE;AAwPD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAEpF;AA4WD;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,kBAAkB,EAC1B,sBAAsB,EAAE,MAAM,GAC7B,MAAM,CAER;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAOhG"}

package/dist/routing/manifest-codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-codegen.d.ts","sourceRoot":"","sources":["../../src/routing/manifest-codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,SAAS,EAA0B,MAAM,YAAY,CAAC;AAyBpE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+IhF;AAID;;;;GAIG;AACH,wBAAgB,kCAAkC,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAuC1E;AAQD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA8B3D"}
+{"version":3,"file":"manifest-codegen.d.ts","sourceRoot":"","sources":["../../src/routing/manifest-codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,SAAS,EAA0B,MAAM,YAAY,CAAC;AAyBpE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiJhF;AAID;;;;GAIG;AACH,wBAAgB,kCAAkC,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAuC1E;AAQD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA8B3D"}

package/dist/routing/scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/routing/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,SAAS,EAIT,aAAa,EAEd,MAAM,YAAY,CAAC;AAwBpB;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,SAAS,CA4ChF"}
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/routing/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,SAAS,EAIT,aAAa,EAEd,MAAM,YAAY,CAAC;AA2BpB;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,SAAS,CAsDhF"}

package/dist/routing/segment-classify.d.ts

@@ -78,4 +78,37 @@ export interface SegmentClassification {
  * If you change the directory-prefix conventions, update this function.
  */
 export declare function classifySegment(dirName: string): SegmentClassification;
+/**
+ * The URL-matching identity of a segment node.
+ *
+ * For every node except an intercepting one this is the node itself. An
+ * intercepting node is different: its directory name carries a marker
+ * (`(.)photo`, `(.)[id]`), so the node's own `segmentType` is
+ * `'intercepting'` and the bracket syntax of the segment it intercepts was
+ * never classified. Everything that has to reason about *the URL part this
+ * node stands for* — matching it, and keying its param for codec coercion —
+ * needs that classification.
+ *
+ * Deriving it here, from `interceptedSegmentName`, keeps interception out
+ * of `classifySegment`'s output and out of the serialized manifest: there
+ * is no second copy of the classification to drift from this one. The
+ * returned `segmentName` is the intercepted name (`photo`, `[id]`), NOT the
+ * node's directory name — callers that need the directory name for tree
+ * paths must keep reading the node. See TIM-1281.
+ */
+export interface UrlSegmentIdentity {
+    segmentName: string;
+    segmentType: SegmentType;
+    paramName?: string;
+    paramPrefix?: string;
+    paramSuffix?: string;
+}
+export declare function effectiveUrlSegment(node: {
+    segmentName: string;
+    segmentType: SegmentType;
+    paramName?: string;
+    paramPrefix?: string;
+    paramSuffix?: string;
+    interceptedSegmentName?: string;
+}): UrlSegmentIdentity;
 //# sourceMappingURL=segment-classify.d.ts.map

package/dist/routing/segment-classify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"segment-classify.d.ts","sourceRoot":"","sources":["../../src/routing/segment-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGlE,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CA4E5D;AAID,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,CAuCtE"}
+{"version":3,"file":"segment-classify.d.ts","sourceRoot":"","sources":["../../src/routing/segment-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGlE,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CA4E5D;AAID,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,CAuCtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC,GAAG,kBAAkB,CAsBrB"}

package/dist/routing/segment-keys.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Segment key computation — the stable identity of a segment in the route tree.
+ *
+ * A segment key is the string that names a segment across the RSC/SSR/client
+ * boundary: it appears in the X-Timber-State-Tree header, the X-Timber-Segments
+ * header, SegmentOutlet props, the client segment cache, and (since TIM-1279)
+ * interception scoping.
+ *
+ * This module lives in `routing/` rather than `server/` because the keys are a
+ * property of the route tree itself — both the build-time scanner tree and the
+ * runtime manifest tree produce identical keys for the same directory, which is
+ * what lets a build-time value (an interception scope) be compared against a
+ * request-time matched chain.
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+ */
+/**
+ * Segment node shape expected by computeSegmentKeys.
+ *
+ * Structurally satisfied by both `SegmentNode` (build time) and
+ * `ManifestSegmentNode` (request time) — keys depend only on the
+ * URL path and the segment classification, never on file payloads.
+ */
+export interface SegmentKeyInput {
+    urlPath: string;
+    segmentName?: string;
+    segmentType?: string;
+}
+/**
+ * Compute state-tree keys for a segment chain.
+ *
+ * Non-group segments use their urlPath as-is. Route groups accumulate
+ * ancestor group names to produce globally unique keys:
+ *   app/(a)/(shared)/dashboard → keys: ['/', '/(a)', '/(a)/(shared)', '/dashboard']
+ *
+ * **An intercepting segment switches the chain to name accumulation for good.**
+ * A children-path interception (TIM-1280) puts an intercepting node and its
+ * descendants into the *main* rendered chain, and their `urlPath`s are not
+ * URLs: interception adds no URL depth, so `app/(browse)/(...)[artistSlug]/[year]`
+ * carries `/` and `/[year]`. Keyed by urlPath the intercepting node would
+ * collide with its own owner, and `[year]` with any top-level `[year]` route —
+ * so a client that had one mounted would reuse the wrong cached layout. The
+ * switch is sticky rather than per-node because the *descendants* are where
+ * the false URLs are; the intercepting node alone is not the problem.
+ *
+ * This is the single source of truth for segment keys — used by the
+ * element builder (skip decisions, SegmentOutlet props), segment info
+ * (X-Timber-Segments header), the client cache/state tree, and
+ * interception scoping (`routing/interception.ts`).
+ */
+export declare function computeSegmentKeys(segments: SegmentKeyInput[]): string[];
+/**
+ * Compute tree paths for a segment chain — the directory path of each segment
+ * with slots elided, e.g. `app/(browse)/feed` → `/(browse)/feed`.
+ *
+ * This is `computeSegmentKeys` with the group branch applied to *every*
+ * segment rather than only to groups. That one difference is the whole point:
+ * `computeSegmentKeys` resets to `urlPath` at each URL-visible segment, so
+ * `(browse)/feed` and `(landing)/feed` both key as `/feed`. Two directories
+ * that render different layouts must not share an identity.
+ *
+ * Used for interception scoping (`routing/interception.ts`), where the
+ * question is "does this route pass through *that* directory?" — not "does it
+ * render this URL?". Not interchangeable with `computeSegmentKeys`: the state
+ * tree is keyed by URL on purpose, because the client caches by URL.
+ */
+export declare function computeSegmentTreePaths(segments: SegmentKeyInput[]): string[];
+/**
+ * The directory names a tree path is built from — `/` is none, `/feed/(a)` is
+ * `['feed', '(a)']`.
+ *
+ * The inverse of the walk above, and it lives beside it so the format is
+ * stated once: `findChainByTreePath` (`server/children-interception.ts`) walks
+ * these names back down the tree to the directory the path addresses, and
+ * `treePathDepth` counts them. Both are readings of the same string, and a
+ * reader that disagreed with the producer about what separates two names
+ * resolves an interception to the wrong node or to none.
+ */
+export declare function treePathNames(treePath: string): string[];
+/**
+ * How many directories a tree path names — `/` is 0, `/feed` is 1,
+ * `/feed/(a)` is 2.
+ *
+ * Two tree paths on a single rendered chain are strictly nested, so on that
+ * chain depth orders them totally — which is what makes it usable as "the
+ * deeper of these two directories" wherever a route passes through both
+ * (`routing/interception.ts`).
+ */
+export declare function treePathDepth(treePath: string): number;
+/**
+ * Compute a unique key for a parallel route slot.
+ * Format: `{parentSegmentId}/@{slotName}`, e.g. `/@sidebar` or `/dashboard/@modal`.
+ */
+export declare function computeSlotKey(parentSegmentId: string, slotName: string): string;
+//# sourceMappingURL=segment-keys.d.ts.map

package/dist/routing/segment-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-keys.d.ts","sourceRoot":"","sources":["../../src/routing/segment-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAmBxE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAmB7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAExD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIhF"}

package/dist/routing/slot-placement.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 declare function validateSlotPlacement(root: SegmentNode): void;
+//# sourceMappingURL=slot-placement.d.ts.map

package/dist/routing/slot-placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-placement.d.ts","sourceRoot":"","sources":["../../src/routing/slot-placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAE7D"}

package/dist/routing/walkers.d.ts

@@ -45,6 +45,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 declare function collectLeafRoutes<TFile>(root: SegmentNode<TFile>, options?: CollectLeafRoutesOptions): LeafRoute<TFile>[];