@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/dist/routing/convention-lint.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Convention linter — validates common misconfigurations in the route tree.
+ *
+ * Runs at scan time (build and dev startup). Each check produces a warning
+ * with the file path, what's wrong, and what to do about it.
+ *
+ * Most checks are warnings — they don't block the build. The goal is to catch
+ * issues that would otherwise produce cryptic runtime behavior (silent 404s,
+ * empty pages, confusing React errors).
+ *
+ * A check emits `level: 'error'` only when the misconfiguration is *proven*
+ * (never inferred from an absence the analysis cannot see through) and fatal
+ * to rendering. `plugins/routing.ts` turns those into a thrown build error,
+ * so a false positive there refuses a working app — see
+ * `classifyClientBoundaryFile` for how that bar is met.
+ *
+ * Design doc: 07-routing.md, 10-error-handling.md
+ */
+import type { RouteTree } from './types.ts';
+export interface ConventionWarning {
+    /** Warning ID for deduplication and filtering. */
+    id: string;
+    /** Human-readable single-line summary. */
+    summary: string;
+    /** Multi-line details with file path and fix suggestion. */
+    details: string;
+    /** Severity: 'warn' for potential issues, 'error' for definite misconfigurations. */
+    level: 'warn' | 'error';
+}
+/**
+ * Run all convention lint checks on a route tree.
+ *
+ * Returns an array of warnings. Empty array means everything looks good.
+ */
+export declare function lintConventions(tree: RouteTree, appDir: string): ConventionWarning[];
+/**
+ * Check if the app/ directory exists. Called before scanning.
+ * Returns a warning if missing, or null if the directory exists.
+ */
+export declare function checkAppDirExists(appDir: string): ConventionWarning | null;
+export interface FormatOptions {
+    /**
+     * Emit ANSI escapes. Off when the text becomes an `Error` message —
+     * whoever prints it decides its formatting, and colored escapes inside
+     * an exception leak into logs and stack traces.
+     */
+    color?: boolean;
+}
+/**
+ * Format warnings for terminal output.
+ *
+ * Groups by severity, uses colors, and includes fix suggestions.
+ */
+export declare function formatConventionWarnings(warnings: ConventionWarning[], options?: FormatOptions): string;
+//# sourceMappingURL=convention-lint.d.ts.map

package/dist/routing/convention-lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convention-lint.d.ts","sourceRoot":"","sources":["../../src/routing/convention-lint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAa,SAAS,EAAe,MAAM,YAAY,CAAC;AAapE,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAyCpF;AA8dD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAe1E;AAUD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAkCR"}

package/dist/routing/export-detect.d.ts

@@ -0,0 +1,91 @@
+/**
+ * AST-based export detection for route files.
+ *
+ * Uses Vite's `parseAst` (backed by oxc) to precisely detect named and
+ * default exports, replacing the regex-based approach that was fragile
+ * with TypeScript syntax (type exports, `as` aliases, comments, etc.).
+ */
+/**
+ * Check if a file exports a specific named export.
+ * Returns false if the file doesn't exist or can't be parsed.
+ */
+export declare function fileHasExport(filePath: string, exportName: string): boolean;
+/**
+ * Check if a file has any of the given named exports.
+ * Returns the set of matching export names.
+ */
+export declare function fileHasAnyExport(filePath: string, exportNames: readonly string[]): Set<string>;
+/**
+ * Check if a file has a default export.
+ * Returns false if the file doesn't exist or can't be parsed.
+ */
+export declare function fileHasDefaultExport(filePath: string): boolean;
+/**
+ * Whether the default export is *provably* a value constructed by this module:
+ * `export default function/class/() => {}`, or a name bound to a function or
+ * class declared here — whether it leaves via `export default Name` or
+ * `export { Name as default }`. Both spellings are the same fact about where
+ * the value was built, so both must answer the same way.
+ *
+ * This is the sound half of "is this a server component?". A file with no
+ * `'use client'` directive whose default export is built here is a server
+ * component, full stop. Everything else — `export { default } from
+ * './client-thing'`, `export default Imported`, `export default memo(X)`,
+ * an unparseable file — returns false, because the exported value may have
+ * been minted in a module that *does* carry the directive. Callers must not
+ * infer "server component" from a missing directive alone.
+ */
+export declare function fileDefaultExportIsLocalValue(filePath: string): boolean;
+/**
+ * Check if a file has any `export * from '...'` declarations.
+ * Returns false if the file doesn't exist or can't be parsed.
+ */
+export declare function fileHasStarExport(filePath: string): boolean;
+/**
+ * Parsed value of `export const prerender` from a route file.
+ *
+ * - `true` / `false` — literal boolean
+ * - `{ ttl?, tags? }` — ISR options object (prerender: true is implied)
+ * - `undefined` — no `export const prerender` found
+ *
+ * See design/45-cache-lifetimes.md §"Route-Level Static".
+ */
+export type PrerenderExportValue = boolean | {
+    ttl?: number;
+    tags?: string[];
+};
+/**
+ * Extract the value of `export const prerender` from a file.
+ * Returns undefined if the file doesn't export `prerender` or can't be parsed.
+ *
+ * Supports:
+ *   export const prerender = true;
+ *   export const prerender = false;
+ *   export const prerender = { ttl: 3600, tags: ['docs'] };
+ */
+export declare function getPrerenderExport(filePath: string): PrerenderExportValue | undefined;
+/**
+ * How a file declares the per-route CSRF exemption.
+ *
+ * - `'absent'` — no runtime export named `csrf`.
+ * - `'exempt'` — exactly `export const csrf = false` (wrappers like
+ *   `false as const` allowed), declared in this file.
+ * - `'invalid'` — some other `csrf` export: another value, `let`, a
+ *   destructured binding, a specifier or named re-export (`export { csrf }`,
+ *   `export { x as "csrf" }`), a function or class. `export * from` is not
+ *   followed: a `csrf` it carries is neither exempt nor an error.
+ *
+ * The exemption is read from source at build time, never from the loaded
+ * module, because the CSRF gate runs before any user code (see
+ * design/08-forms-and-actions.md §"Per-route exemption"). Only the literal
+ * form can be read that way; any other spelling is a build error rather
+ * than a silent "not exempt", so what the developer wrote is what runs.
+ */
+export type CsrfExport = 'absent' | 'exempt' | 'invalid';
+export declare function getCsrfExport(filePath: string): CsrfExport;
+/**
+ * Check if a file starts with a specific directive (e.g. "use client").
+ * Directives are string literal expression statements at the top of the file.
+ */
+export declare function fileHasDirective(filePath: string, directive: string): boolean;
+//# sourceMappingURL=export-detect.d.ts.map

package/dist/routing/export-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-detect.d.ts","sourceRoot":"","sources":["../../src/routing/export-detect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4HH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAU3E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAc9F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAU9D;AAoED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAiCvE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAU3D;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AA8C/E;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CA+CrF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAsC1D;AA+BD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAgB7E"}

package/dist/routing/file-cache.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Read a file's text content, returning a cached copy when the file
+ * hasn't been modified since the last read (checked via mtime + size).
+ *
+ * Falls back to a fresh read on any stat/read error.
+ */
+export declare function readFileCached(filePath: string): string;
+//# sourceMappingURL=file-cache.d.ts.map

package/dist/routing/file-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.d.ts","sourceRoot":"","sources":["../../src/routing/file-cache.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYvD"}

package/dist/routing/index.d.ts

@@ -1,8 +1,14 @@
-export { scanRoutes, classifySegment } from './scanner.js';
-export { generateRouteMap } from './codegen.js';
-export type { CodegenOptions } from './codegen.js';
-export type { RouteTree, SegmentNode, SegmentType, RouteFile, ScannerConfig, InterceptionMarker, } from './types.js';
-export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
-export { collectInterceptionRewrites } from './interception.js';
-export type { InterceptionRewrite } from './interception.js';
+export { scanRoutes } from './scanner.ts';
+export { generateRouteMap } from './codegen.ts';
+export type { CodegenOptions } from './codegen.ts';
+export type { RouteTree, SegmentNode, SegmentType, RouteFile, ScannerConfig, InterceptionMarker, } from './types.ts';
+export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.ts';
+export { collectInterceptionRewrites } from './interception.ts';
+export type { InterceptionRewrite } from './interception.ts';
+export { classifyUrlSegment, classifySegment } from './segment-classify.ts';
+export type { UrlSegment, SegmentClassification } from './segment-classify.ts';
+export { collectLeafRoutes } from './walkers.ts';
+export type { LeafRoute, CollectLeafRoutesOptions } from './walkers.ts';
+export { validateSchemaAgainstRoutes, collectDynamicSegmentsFromTree, } from './schema-validation.ts';
+export type { SchemaWarning } from './schema-validation.ts';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,SAAS,EACT,aAAa,EACb,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,SAAS,EACT,aAAa,EACb,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC5E,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,SAAS,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/routing/index.js

@@ -1,2 +1,5 @@
-import { a as DEFAULT_PAGE_EXTENSIONS, i as scanRoutes, n as generateRouteMap, o as INTERCEPTION_MARKERS, r as classifySegment, t as collectInterceptionRewrites } from "../_chunks/interception-BOoWmLUA.js";
-export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS, classifySegment, collectInterceptionRewrites, generateRouteMap, scanRoutes };
+import { a as INTERCEPTION_MARKERS, i as DEFAULT_PAGE_EXTENSIONS, n as classifyUrlSegment, t as classifySegment } from "../_chunks/segment-classify-C539Pa2O.js";
+import { d as collectInterceptionRewrites, n as scanRoutes } from "../_chunks/scanner-DmqdxzbW.js";
+import { t as generateRouteMap } from "../_chunks/codegen-Bps1sLKJ.js";
+import { n as collectDynamicSegmentsFromTree, r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "../_chunks/walkers-Czu2jXFq.js";
+export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS, classifySegment, classifyUrlSegment, collectDynamicSegmentsFromTree, collectInterceptionRewrites, collectLeafRoutes, generateRouteMap, scanRoutes, validateSchemaAgainstRoutes };

package/dist/routing/interception-overlap.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pattern intersection for intercepted URL patterns.
+ *
+ * Checks whether two intercepted URL patterns can both match the same concrete
+ * URL. Used by the cross-mode claim check (TIM-1319) to detect when a
+ * children-path interceptor and a slot interceptor from the same owner overlap.
+ *
+ * This is not the order-dependence oracle (`findOrderDependentCollision`) the
+ * within-mode collision checks use. `findInterceptionMatch` picks the mode by
+ * first-match on `pathnameMatchesPattern`, which has no priority tiers, so a
+ * static `/feed/foo` and a dynamic `/feed/[id]` both match `/feed/foo` even
+ * though `matchUrlParts` would resolve the static deterministically. The
+ * intersection test catches that: it walks both patterns segment by segment and
+ * asks whether any value satisfies both.
+ *
+ * This is not a model of `matchNode` precedence — that decides *which*
+ * candidate wins when several match one URL. This decides the prior question:
+ * *do* they both match one URL at all? The two questions are independent, and
+ * conflating them is what caused TIM-1308's five-round drift.
+ */
+/**
+ * Check whether two intercepted URL patterns can both match the same concrete
+ * URL. Returns a display string for the overlapping URL, or null.
+ *
+ * Walks both patterns segment by segment:
+ * - Two statics: must be identical.
+ * - Static + dynamic: static must satisfy the dynamic's affix constraints.
+ * - Two dynamics: affix constraints must be compatible.
+ * - A catch-all at either side: compatible with everything remaining.
+ *
+ * If the patterns differ in length, they can only overlap if the longer one's
+ * extra part is an optional catch-all (which also matches zero segments).
+ */
+export declare function interceptedPatternsOverlap(p1: string, p2: string): string | null;
+//# sourceMappingURL=interception-overlap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"interception-overlap.d.ts","sourceRoot":"","sources":["../../src/routing/interception-overlap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmChF"}

package/dist/routing/interception.d.ts

@@ -16,31 +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.ts';
+/** 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.
      */
-    interceptingPrefix: string;
+    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';
     /**
-     * Segments chain from root → intercepting leaf. Used to build the element
-     * tree when the interception is active.
+     * 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.
      */
-    segmentPath: SegmentNode[];
+    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 `route-element-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;IAC3B;;;OAGG;IACH,WAAW,EAAE,WAAW,EAAE,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;AAS7E,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;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAOrE;AAkYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAEpF;AAsXD;;;;;;;;;;;;;;;;;;;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/link-codegen.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Typed `<Link>` codegen — interface augmentation generation.
+ *
+ * Extracted from `codegen.ts` to keep that file under the project's
+ * 500-line cap. This module owns everything that emits the
+ * `interface LinkFunction { ... }` augmentation blocks in the generated
+ * `.timber/timber-routes.d.ts`.
+ *
+ * Two augmentation blocks are emitted:
+ *
+ * 1. **Per-route discriminated union** (`formatTypedLinkOverloads`) —
+ *    one call signature whose props is a union keyed on `href`. TS
+ *    narrows by literal href and reports prop errors against the
+ *    matched variant. See TIM-835 and `design/09-typescript.md`.
+ *
+ * 2. **Catch-all overloads** (`formatLinkCatchAllOverloads`) — external
+ *    href literals (`http://`, `mailto:`, etc.) and a computed-string
+ *    `<H extends string>` signature for runtime-computed paths.
+ *
+ * Block ordering is critical for error UX: per-route is emitted FIRST
+ * so that, after TS's "later overload set ordered first" merge rule,
+ * the discriminated union ends up LAST in resolution order — the
+ * overload TS reports against on failure.
+ */
+import type { ParamEntry, RouteEntry } from './codegen-types.ts';
+/**
+ * The `searchParams` prop type, emitted identically on every Link variant
+ * — per-route pattern, resolved template, and catch-all.
+ *
+ * TIM-1343: there is no per-route narrowing any more. `params.ts` is gone,
+ * so codegen has no definition to read a `SearchParamsDefinition<T>` from.
+ * Type safety moved to the value's construction site instead: callers write
+ * `definition.buildSearchParams({ ... })`, which checks `Partial<T>` there
+ * and returns a query STRING — the only shape that survives the RSC Flight
+ * boundary. A plain record is the uncodec'd escape hatch. See `client/link.tsx` §"searchParams prop shapes".
+ *
+ * Declared once so the three emission sites cannot drift apart.
+ */
+export declare const SEARCH_PARAMS_PROP_TYPE = "string | Record<string, unknown>";
+/** Shared Link base-props type literal used in every emitted call signature. */
+export declare const LINK_BASE_PROPS_TYPE = "Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & { prefetch?: boolean; scroll?: boolean; preserveSearchParams?: true | string[]; onNavigate?: import('./client/link.js').OnNavigateHandler; children?: import('react').ReactNode }";
+/**
+ * Build a TypeScript template literal pattern for a dynamic route.
+ * e.g. '/products/[id]'        → '/products/${string}'
+ *      '/blog/[...slug]'       → '/blog/${string}'
+ *      '/docs/[[...path]]'     → '/docs/${string}' (also matches /docs)
+ *      '/[org]/[repo]'         → '/${string}/${string}'
+ */
+export declare function buildResolvedPattern(route: RouteEntry): string | null;
+/**
+ * Format the segmentParams type for Link overloads.
+ *
+ * Link params accept `string | number` for single dynamic segments
+ * (convenience — values are stringified at runtime). Catch-all and
+ * optional catch-all remain `string[]` / `string[] | undefined`.
+ *
+ * With a global schema, the schema codec's inferred type wins. Without
+ * one, a URL segment is a raw string (widened to string | number for
+ * Link convenience) — per-segment codec chains were deleted in TIM-1342.
+ */
+export declare function formatLinkParamsType(params: ParamEntry[], hasSchema?: boolean): string;
+/**
+ * Catch-all call signatures for `<Link>` — external hrefs and computed
+ * `string` variables. Emitted from codegen in a SEPARATE
+ * `declare module` block (declared AFTER the per-route block) so the TS
+ * "later overload set ordered first" rule places these catch-all
+ * signatures ahead of per-route in resolution order, leaving per-route
+ * as the final overload whose error message is reported on failure.
+ *
+ * The conditional `string extends H ? ... : never` protection preserves
+ * TIM-624's guarantee that unknown internal path literals don't match
+ * the catch-all — typos like `<Link href="/typo" />` still error.
+ */
+export declare function formatLinkCatchAllOverloads(): string[];
+/**
+ * Generate typed per-route Link call signatures via LinkFunction
+ * interface merging.
+ *
+ * TIM-835: This emits a SINGLE call signature whose props is a
+ * discriminated union keyed on `href`. TypeScript narrows the union by
+ * the literal `href` at the call site, then checks the rest of the
+ * props against the matched variant. When `segmentParams` or
+ * `searchParams` is wrong, TS reports the error against the matched
+ * variant — naming the user's actual `href` and the offending field.
+ *
+ * Before TIM-835, this function emitted N separate per-route overloads
+ * (one per route, sometimes two for dynamic routes). When ALL overloads
+ * failed, TS would pick an arbitrary failed overload (heuristically the
+ * "last tried") to render the diagnostic, often pointing at a route
+ * completely unrelated to the one the user wrote. The discriminated
+ * union sidesteps overload-resolution heuristics entirely.
+ *
+ * Open property shapes (`Record<string, unknown>` instead of `never`)
+ * for `segmentParams` on routes that don't declare them keep generic
+ * `LinkProps`-spreading wrappers compiling. (Aligned with TIM-833.)
+ *
+ * TIM-832: this function still emits the per-route block FIRST and the
+ * catch-all block follows, so per-route remains the LAST overload set in
+ * resolution order — the one TS reports against on failure. With a
+ * discriminated union there is only one call signature in this block,
+ * so the resolved-template-vs-pattern ordering reduces to placing the
+ * pattern variant before the resolved-template variant inside the union.
+ */
+export declare function formatTypedLinkOverloads(routes: RouteEntry[], hasSchema?: boolean): string[];
+//# sourceMappingURL=link-codegen.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"link-codegen.d.ts","sourceRoot":"","sources":["../../src/routing/link-codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIjE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,qCAAqC,CAAC;AAE1E,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,8PAC4N,CAAC;AAE9P;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAoBrE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAWtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,EAAE,CA+DtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAwE5F"}