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

package/dist/routing/scanner.d.ts

@@ -7,7 +7,7 @@
  * timber.js file conventions. Does NOT handle request matching — this
  * is discovery only.
  */
-import type { RouteTree, SegmentType, ScannerConfig, InterceptionMarker } from './types.js';
+import type { RouteTree, ScannerConfig } from './types.js';
 /**
  * Scan the app/ directory and build the route tree.
  *
@@ -16,13 +16,4 @@ import type { RouteTree, SegmentType, ScannerConfig, InterceptionMarker } from '
  * @returns The complete route tree
  */
 export declare function scanRoutes(appDir: string, config?: ScannerConfig): RouteTree;
-/**
- * Classify a directory name into its segment type.
- */
-export declare function classifySegment(dirName: string): {
-    type: SegmentType;
-    paramName?: string;
-    interceptionMarker?: InterceptionMarker;
-    interceptedSegmentName?: string;
-};
 //# sourceMappingURL=scanner.d.ts.map

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,EAET,WAAW,EAEX,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AA6CpB;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,SAAS,CAwBhF;AAyBD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG;IAChD,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC,CA8CA"}
+{"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/schema-validation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Schema key/value validation against the filesystem route tree.
+ *
+ * Runs at codegen time (build + dev) to catch mismatches between
+ * app/schema.ts keys and the actual dynamic segments on disk.
+ *
+ * Design doc: design/41-global-params.md
+ */
+import type { RouteTree } from './types.js';
+export interface SchemaWarning {
+    type: 'stale-key' | 'missing-key' | 'bracket-mismatch';
+    key: string;
+    message: string;
+    filesystemKey?: string;
+}
+/**
+ * Collect all unique bracket-keyed dynamic segment names from a route tree.
+ * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+ */
+export declare function collectDynamicSegmentsFromTree(tree: RouteTree): Set<string>;
+/**
+ * Validate schema keys against the filesystem route tree.
+ *
+ * Returns warnings for:
+ * - Stale keys: schema keys that don't match any filesystem segment
+ * - Bracket form mismatches: same param name, different bracket form
+ * - Missing keys: filesystem segments not registered in schema (informational)
+ */
+export declare function validateSchemaAgainstRoutes(tree: RouteTree, appDir: string): SchemaWarning[];
+/**
+ * Core validation: compare schema keys against filesystem segments.
+ * Exported separately for testing without filesystem dependencies.
+ */
+export declare function validateKeys(schemaKeys: string[], filesystemSegments: Set<string>): SchemaWarning[];
+//# sourceMappingURL=schema-validation.d.ts.map

package/dist/routing/schema-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-validation.d.ts","sourceRoot":"","sources":["../../src/routing/schema-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAIzD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,GAAG,aAAa,GAAG,kBAAkB,CAAC;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,CAI3E;AAiCD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAY5F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAAE,EACpB,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,GAC9B,aAAa,EAAE,CA+DjB"}

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

@@ -0,0 +1,114 @@
+/**
+ * Shared segment classifier — both URL tokens and filesystem directory names.
+ *
+ * `classifyUrlSegment(token)` is a pure single-pass character parser that
+ * classifies a route segment token (e.g. "dashboard", "[id]", "[...slug]",
+ * "[[...path]]") into a typed discriminated union. NO regex, NO Node.js-only
+ * APIs — safe to import from browser code (used by `Link` interpolation).
+ *
+ * `classifySegment(dirName)` is the build-time directory-name classifier
+ * used by the scanner. It recognizes timber-only conventions (private
+ * `_*`, parallel `@*`, route groups `(name)`, intercepting routes
+ * `(.)`/`(..)`/`(...)`/`(..)(..)`) and delegates bracket syntax to
+ * `classifyUrlSegment`. It is the **single source of truth** for what
+ * counts as a routing segment — there is no separate copy in the
+ * scanner. (TIM-848.)
+ *
+ * Malformed input falls through to `{ kind: 'static' }` — the safe default.
+ *
+ * If you change the bracket syntax, update ONLY this file. Every
+ * consumer imports from here.
+ *
+ * See design/07-routing.md §"Route Segments"
+ */
+import type { InterceptionMarker, SegmentType } from './types.js';
+export type UrlSegment = {
+    kind: 'static';
+    value: string;
+} | {
+    kind: 'dynamic';
+    name: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    kind: 'catch-all';
+    name: string;
+} | {
+    kind: 'optional-catch-all';
+    name: string;
+};
+/**
+ * Classify a URL path segment token.
+ *
+ * Walks the string left-to-right in one pass:
+ *   1. Find the first '[' — characters before it are the prefix.
+ *   2. Count opening brackets (1 or 2) to detect optional.
+ *   3. Check for '...' to detect catch-all.
+ *   4. Read the param name up to the closing bracket.
+ *   5. Validate the expected closing sequence (']' or ']]').
+ *   6. Characters after the close are the suffix.
+ *   7. Reject affixes on catch-all/optional-catch-all.
+ *   8. Reject affixes that contain '[' or ']' (no multi-param segments).
+ *
+ * Any structural violation → static (safe default).
+ */
+export declare function classifyUrlSegment(token: string): UrlSegment;
+/** Result of classifying a filesystem directory name. */
+export interface SegmentClassification {
+    type: SegmentType;
+    paramName?: string;
+    paramPrefix?: string;
+    paramSuffix?: string;
+    interceptionMarker?: InterceptionMarker;
+    interceptedSegmentName?: string;
+}
+/**
+ * Classify a directory name into its segment type.
+ *
+ * Recognizes all timber file-system conventions in priority order:
+ *   1. Private folders: `_name` (excluded from routing)
+ *   2. Parallel route slots: `@name`
+ *   3. Intercepting routes: `(.)name`, `(..)name`, `(...)name`, `(..)(..)name`
+ *   4. Route groups: `(name)`
+ *   5. Bracket syntax: `[id]`, `[...slug]`, `[[...path]]` (delegated to
+ *      `classifyUrlSegment`)
+ *   6. Static: anything else
+ *
+ * If you change the bracket syntax, update only `classifyUrlSegment`.
+ * 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

@@ -0,0 +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;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-codegen.d.ts

@@ -0,0 +1,38 @@
+/**
+ * $segment type generation and directory-to-route mapping.
+ *
+ * Generates per-route $segment.d.ts files in .timber/types/ that mirror
+ * the app/ directory structure. TypeScript's rootDirs feature makes these
+ * importable as './$segment' from route files.
+ *
+ * Design doc: design/41-global-params.md §The $segment Module
+ */
+import type { RouteTree } from './types.js';
+/** Info carried per directory for type generation. */
+export interface SegmentInfo {
+    /** The URL route pattern (groups and slots stripped). e.g. '/[artistSlug]/[year]' */
+    route: string;
+    /** The full tree path including groups and slots — uniquely identifies a segment.
+     *  e.g. '/(browse)/[artistSlug]/@shows/[year]' */
+    segmentPath: string;
+}
+/**
+ * Build a map of absolute filesystem directory → segment info.
+ * Used by resolveId to map a $segment import's importer to the correct route,
+ * and by writeSegmentTypes to generate per-route $segment.d.ts files.
+ *
+ * Walks every segment (not just leaves) so layouts and middleware
+ * at any depth can import $segment.
+ */
+export declare function buildDirToRouteMap(tree: RouteTree, appDir: string): Map<string, SegmentInfo>;
+/**
+ * Generate the full $segment.d.ts content for a segment.
+ */
+export declare function generateSegmentDts(info: SegmentInfo): string;
+/**
+ * Generate per-route $segment.d.ts files in .timber/types/ mirroring
+ * the app/ directory structure. These files are importable via TypeScript's
+ * rootDirs feature.
+ */
+export declare function writeSegmentTypes(routeTree: RouteTree, appDir: string, root: string): Promise<void>;
+//# sourceMappingURL=segment-codegen.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"segment-codegen.d.ts","sourceRoot":"","sources":["../../src/routing/segment-codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAEzD,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IACd;sDACkD;IAClD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAuB5F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAM5D;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAqBf"}

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

@@ -0,0 +1,117 @@
+/**
+ * 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;
+/**
+ * Compute a content key for a parallel route slot.
+ *
+ * The content key encodes everything that determines the slot's rendered
+ * output for a given navigation: the slot key (which includes the owning
+ * segment's identity and the slot name), the URL parts consumed by the
+ * owning segment (which determine parent params the slot page might
+ * read), the matched page file (or a sentinel for `default.tsx`), and
+ * the slot's own extracted params.
+ *
+ * The slot key prevents cross-group collisions: two route groups at the
+ * same URL level each owning a `@sidebar` slot produce different keys
+ * even when both fall back to `default.tsx`.
+ *
+ * The key is opaque to the client — it stores whatever the server sent
+ * and advertises it back. The server computes the destination key and
+ * checks membership. This eliminates the need for the server to
+ * reconstruct the client's state from a departing URL.
+ *
+ * See design/07-routing.md §"Segment Tree Diffing on Navigation"
+ */
+export declare function computeSlotContentKey(slotKey: string, ownerParts: string[], entryFile: string | null, slotParams: Record<string, string | 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;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAAE,EACpB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAC5C,MAAM,CASR"}

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/types.d.ts

@@ -3,6 +3,23 @@
  *
  * The route tree is built by scanning the app/ directory and recognizing
  * file conventions (page.*, layout.*, middleware.ts, access.ts, route.ts, etc.).
+ *
+ * **Single shape, two specializations** (TIM-848):
+ *
+ * `SegmentNode<TFile>` is the one canonical in-memory shape for the
+ * timber route tree. The same interface is used at build time (with
+ * `TFile = RouteFile`) and at request time (with `TFile = ManifestFile`,
+ * see `server/route-matcher.ts`). Walkers parameterized over `TFile`
+ * work on either, eliminating the previous duplication between
+ * `SegmentNode` (Map-based) and `ManifestSegmentNode` (object-based).
+ *
+ * Keyed groups (`slots`, `statusFiles`, `jsonStatusFiles`,
+ * `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.
+ *
+ * See design/07-routing.md §"Route Tree Shape" and design/18-build-system.md
+ * §"Route Manifest Shape".
  */
 /** Segment type classification */
 export type SegmentType = 'static' | 'dynamic' | 'catch-all' | 'optional-catch-all' | 'group' | 'slot' | 'intercepting' | 'private';
@@ -15,21 +32,41 @@ export type SegmentType = 'static' | 'dynamic' | 'catch-all' | 'optional-catch-a
 export type InterceptionMarker = '(.)' | '(..)' | '(...)' | '(..)(..)';
 /** All recognized interception markers, ordered longest-first for parsing. */
 export declare const INTERCEPTION_MARKERS: InterceptionMarker[];
-/** A single file discovered in a route segment */
+/**
+ * A single file discovered in a route segment at build time.
+ *
+ * The runtime equivalent (`ManifestFile`, defined in
+ * `server/route-matcher.ts`) replaces `extension` with a lazy `load`
+ * function. Walkers that only need `filePath` are parameterized over
+ * `TFile` and accept either.
+ */
 export interface RouteFile {
     /** Absolute path to the file */
     filePath: string;
     /** File extension without leading dot (e.g. "tsx", "ts", "mdx") */
     extension: string;
 }
-/** A node in the segment tree */
-export interface SegmentNode {
+/**
+ * A node in the segment tree.
+ *
+ * Generic over `TFile` so the same interface describes both the
+ * build-time tree (`SegmentNode<RouteFile>`, the default) and the
+ * runtime manifest tree (`SegmentNode<ManifestFile>`, aliased as
+ * `ManifestSegmentNode`). All keyed groups use `Record` (not `Map`)
+ * so the build-time tree serializes to the virtual route manifest
+ * with no shape transform.
+ */
+export interface SegmentNode<TFile = RouteFile> {
     /** The raw directory name (e.g. "dashboard", "[id]", "(auth)", "@sidebar") */
     segmentName: string;
     /** Classified segment type */
     segmentType: SegmentType;
     /** The dynamic param name, if dynamic (e.g. "id" for "[id]", "slug" for "[...slug]") */
     paramName?: string;
+    /** Literal prefix before the dynamic bracket (e.g. "img-" for "img-[id].png") */
+    paramPrefix?: string;
+    /** Literal suffix after the dynamic bracket (e.g. ".png" for "img-[id].png") */
+    paramSuffix?: string;
     /** The URL path prefix at this segment level (e.g. "/dashboard") */
     urlPath: string;
     /** For intercepting segments: the marker used, e.g. "(.)". */
@@ -39,37 +76,48 @@ export interface SegmentNode {
      * E.g., for "(.)photo" this is "photo".
      */
     interceptedSegmentName?: string;
-    page?: RouteFile;
-    layout?: RouteFile;
-    middleware?: RouteFile;
-    access?: RouteFile;
-    route?: RouteFile;
-    error?: RouteFile;
-    default?: RouteFile;
+    page?: TFile;
+    layout?: TFile;
+    middleware?: TFile;
+    access?: TFile;
+    route?: TFile;
+    error?: TFile;
+    default?: TFile;
     /** Status-code files: 4xx.tsx, 5xx.tsx, {status}.tsx (component format) */
-    statusFiles?: Map<string, RouteFile>;
+    statusFiles?: Record<string, TFile>;
     /** JSON status-code files: 4xx.json, 5xx.json, {status}.json */
-    jsonStatusFiles?: Map<string, RouteFile>;
+    jsonStatusFiles?: Record<string, TFile>;
     /** denied.tsx — slot-only denial rendering */
-    denied?: RouteFile;
-    /** Legacy compat: not-found.tsx (maps to 404), forbidden.tsx (403), unauthorized.tsx (401) */
-    legacyStatusFiles?: Map<string, RouteFile>;
-    /** prerender.ts — signals build-time pre-rendering for this segment's shell */
-    prerender?: RouteFile;
-    /** search-params.ts — typed search params definition for this route */
-    searchParams?: RouteFile;
+    denied?: TFile;
     /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
-    metadataRoutes?: Map<string, RouteFile>;
-    children: SegmentNode[];
+    metadataRoutes?: Record<string, TFile>;
+    children: SegmentNode<TFile>[];
     /** Parallel route slots (keyed by slot name without @) */
-    slots: Map<string, SegmentNode>;
+    slots: Record<string, SegmentNode<TFile>>;
 }
-/** The full route tree output from the scanner */
-export interface RouteTree {
+/**
+ * The full route tree output from the scanner (or the root of the
+ * runtime route manifest, when `TFile = ManifestFile`).
+ *
+ * Generic so the same wrapper carries app-root metadata for both
+ * shapes. The runtime manifest extends this with `viteRoot` (see
+ * `ManifestRoot` in `server/route-matcher.ts`).
+ */
+export interface RouteTree<TFile = RouteFile> {
     /** The root segment node (representing app/) */
-    root: SegmentNode;
+    root: SegmentNode<TFile>;
     /** All discovered proxy.ts files (should be at most one, in app/) */
-    proxy?: RouteFile;
+    proxy?: TFile;
+    /**
+     * Global error page: app/global-error.{tsx,ts,jsx,js}
+     *
+     * Rendered as a standalone full-page replacement (no layout wrapping)
+     * when no segment-level error file is found. SSR-only render path.
+     * Must provide its own <html> and <body>.
+     *
+     * See design/10-error-handling.md §"Tier 2 — Global Error Page"
+     */
+    globalError?: TFile;
 }
 /** Configuration passed to the scanner */
 export interface ScannerConfig {

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kCAAkC;AAClC,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,oBAAoB,GACpB,OAAO,GACP,MAAM,GACN,cAAc,GACd,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAEvE,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,EAAyC,CAAC;AAE/F,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAGhC,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACrC,gEAAgE;IAChE,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACzC,8CAA8C;IAC9C,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,8FAA8F;IAC9F,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC3C,+EAA+E;IAC/E,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,uEAAuE;IACvE,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,sFAAsF;IACtF,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAGxC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,0DAA0D;IAC1D,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACjC;AAED,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,IAAI,EAAE,WAAW,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,8BAA8B;AAC9B,eAAO,MAAM,uBAAuB,UAA6B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,kCAAkC;AAClC,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,oBAAoB,GACpB,OAAO,GACP,MAAM,GACN,cAAc,GACd,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAEvE,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,EAAyC,CAAC;AAE/F;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,SAAS;IAC5C,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAGhC,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,UAAU,CAAC,EAAE,KAAK,CAAC;IACnB,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,OAAO,CAAC,EAAE,KAAK,CAAC;IAChB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACpC,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACxC,8CAA8C;IAC9C,MAAM,CAAC,EAAE,KAAK,CAAC;IAEf,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAGvC,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;IAC/B,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;CAC3C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS,CAAC,KAAK,GAAG,SAAS;IAC1C,gDAAgD;IAChD,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;IACzB,qEAAqE;IACrE,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC;CACrB;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,8BAA8B;AAC9B,eAAO,MAAM,uBAAuB,UAA6B,CAAC"}

package/dist/routing/walkers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared route-tree walkers (TIM-848).
+ *
+ * Tiny helpers that walk a `SegmentNode<TFile>` tree generically. Both the
+ * build-time tree (`SegmentNode<RouteFile>`) and the runtime manifest
+ * tree (`SegmentNode<ManifestFile>`) flow through these helpers because
+ * the walker only reads the structural fields shared by both shapes
+ * (`children`, `slots`, `page`, `route`, `urlPath`).
+ *
+ * Before this module, three near-identical `collectRoutes` functions
+ * lived in `plugins/dev-404-page.ts`, `plugins/build-report.ts`, and
+ * `routing/codegen.ts`. The codegen one is special-purpose (it
+ * accumulates `ParamEntry[]` and resolves codec chains) and stays
+ * local; the other two now share `collectLeafRoutes` from this file.
+ */
+import type { SegmentNode } from './types.js';
+/** A leaf route discovered while walking the segment tree. */
+export interface LeafRoute<TFile> {
+    /** URL path of the leaf (root is "/"). */
+    urlPath: string;
+    /** Segment chain from root to this leaf, inclusive. */
+    segments: SegmentNode<TFile>[];
+    /** The page file at this leaf, if any. */
+    page?: TFile;
+    /** The route handler file at this leaf, if any. */
+    route?: TFile;
+}
+/** Options for `collectLeafRoutes`. */
+export interface CollectLeafRoutesOptions {
+    /**
+     * If true, recurse into parallel slots and emit slot leaves alongside
+     * the main route tree. Defaults to `false` because slots render
+     * alongside their parent at the same URL and are not separately
+     * URL-addressable. The build report excludes slots; route-listing
+     * UIs that want to show "all leaves with a page handler" can opt in.
+     */
+    includeSlots?: boolean;
+}
+/**
+ * Walk a segment tree and collect every leaf with a `page` or `route`
+ * handler. Generic over `TFile` so it works on both the build-time
+ * scanner output and the runtime manifest tree.
+ *
+ * - Pages and route handlers at the same URL produce two distinct
+ *   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>[];
+//# sourceMappingURL=walkers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"walkers.d.ts","sourceRoot":"","sources":["../../src/routing/walkers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,8DAA8D;AAC9D,MAAM,WAAW,SAAS,CAAC,KAAK;IAC9B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;IAC/B,0CAA0C;IAC1C,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,mDAAmD;IACnD,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,uCAAuC;AACvC,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EACxB,OAAO,GAAE,wBAA6B,GACrC,SAAS,CAAC,KAAK,CAAC,EAAE,CAMpB"}

package/dist/rsc-runtime/rsc.d.ts

@@ -10,5 +10,5 @@
  * Keep this as thin pass-through re-exports — the value is the single choke
  * point, not abstraction.
  */
-export { renderToReadableStream, loadServerAction, decodeReply, decodeAction, } from '@vitejs/plugin-rsc/rsc';
+export { renderToReadableStream, loadServerAction, decodeReply, decodeAction, encryptActionBoundArgs, decryptActionBoundArgs, createFromReadableStream, } from '@vitejs/plugin-rsc/rsc';
 //# sourceMappingURL=rsc.d.ts.map

package/dist/rsc-runtime/rsc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rsc.d.ts","sourceRoot":"","sources":["../../src/rsc-runtime/rsc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,YAAY,GACb,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"rsc.d.ts","sourceRoot":"","sources":["../../src/rsc-runtime/rsc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EAOtB,wBAAwB,GACzB,MAAM,wBAAwB,CAAC"}