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

package/dist/plugins/static-build.d.ts

@@ -1,55 +1,275 @@
 /**
  * timber-static-build — Vite sub-plugin for static output mode.
  *
- * When `output: 'static'` is set in timber.config.ts, this plugin:
- * 1. Validates that no dynamic APIs (cookies(), headers()) are used
- * 2. When client JavaScript is disabled, rejects 'use client' and 'use server' directives
- * 3. Coordinates build-time rendering of all pages
+ * When `output: 'static'` is set in timber.config.ts:
+ * 1. The plugin validates that no dynamic APIs (getCookies(), getHeaders())
+ *    are used
+ * 2. `runStaticGeneration`, the static generation step of the post-build
+ *    phase (plugins/post-build.ts), renders all routes to static HTML + RSC
+ *    flight files
  *
- * Design doc: design/15-future-prerendering.md
+ * Design doc: design/11-platform.md §"static output mode"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.ts';
+import type { DirectoryArtifact } from '../adapters/types.ts';
+import type { StaticPageEntry, StaticRedirectEntry } from '../server/static-generator.ts';
+import type { RscManifest } from '../shared/rsc-manifest.ts';
+import { type FsIdentity } from '../adapters/fs-identity.ts';
+/**
+ * A single entry in the RSC manifest injected into static HTML.
+ * Maps an unhashed `/_rsc/*.rsc` path to its hashed URL, with
+ * optional route params inlined to avoid a sidecar fetch.
+ */
+export type { RscManifestEntry, RscManifest } from '../shared/rsc-manifest.ts';
 export interface StaticValidationError {
-    type: 'dynamic-api' | 'nojs-directive';
+    type: 'dynamic-api';
     file: string;
     message: string;
     line?: number;
 }
-export interface StaticOptions {
-    clientJavascriptDisabled: boolean;
-}
 /**
- * Detect usage of dynamic per-request APIs (cookies(), headers())
+ * Detect usage of dynamic per-request APIs (getCookies(), getHeaders())
  * that cannot work at build time in static mode.
  *
  * Returns an array of validation errors.
  */
 export declare function detectDynamicApis(code: string, fileId: string): StaticValidationError[];
 /**
- * Detect 'use client' and 'use server' directives using AST-based parsing.
- * When client JavaScript is disabled, both are hard build errors — no React
- * runtime or server actions are allowed in the output.
+ * Generate a `_redirects` file from collected redirect entries.
+ * Uses the Cloudflare Pages / Netlify format: `/from /to statusCode`
+ *
+ * Both sides are base-prefixed (TIM-1274). `from` is matched by the host
+ * against the request path and `to` is served to the browser as a `Location`,
+ * so both are deployed-URL space while `StaticRedirectEntry` carries route
+ * space — under `base: '/repo/'`, a rule `/old /new 301` would match nothing
+ * and, if it did, would send the browser off the deployment.
  *
- * When client JavaScript is enabled, these are allowed (client components
- * hydrate, server actions get extracted to API endpoints).
+ * An off-origin `to` is left alone: `redirectExternal()` produces an absolute
+ * URL, and a protocol-relative one addresses another host too. Neither is a
+ * path on this deployment, so neither takes the prefix.
+ *
+ * @param base Normalized deployment base (see `shared/base-path.ts`).
+ * @internal Exported for testing.
  */
-export declare function detectDirectives(code: string, fileId: string, options: StaticOptions): StaticValidationError[];
+export declare function generateRedirectsFile(redirects: StaticRedirectEntry[], base: string): string;
 /**
- * Run all static mode validations on a source file.
+ * Determine the output file path for a static page entry.
+ *
+ * Pages: /about → about/index.html, / → index.html
+ * RSC:   /about → _rsc/about/index.rsc, / → _rsc/index.rsc
+ * API:   /feed.xml → feed.xml, /api/data → api/data
  *
- * Combines:
- * - Dynamic API detection (cookies, headers) — always in static mode
- * - Directive detection ('use client', 'use server') — only when client JS is disabled
+ * The RSC shape mirrors the HTML shape for the reason the HTML shape has it:
+ * a route gets a directory and the artifact is the `index` inside it, so the
+ * mapping is injective. See `shared/rsc-payload-path.ts` (TIM-1266).
  */
-export declare function validateStaticMode(code: string, fileId: string, options: StaticOptions): StaticValidationError[];
+export declare function staticOutputPath(entry: StaticPageEntry): string;
 /**
- * Create the timber-static-build Vite plugin.
+ * Records which entry claimed each output path and reports second claims.
+ *
+ * Two entries landing on one path is not a rendering failure — both render
+ * fine — so nothing downstream notices. The file is written twice, the second
+ * write wins, and the deployment serves one route's bytes at another route's
+ * URL with the same content type and the same shape (TIM-1266).
+ *
+ * The naming rules are injective by construction (a route path is a directory
+ * and the artifact is the `index` inside it), so a collision here means either
+ * two entries were enumerated for one URL or a route reached a path the
+ * framework reserves for itself (`404.html`). Both are build errors: there is
+ * no correct file to write.
+ *
+ * Two entries can also be unwritable together without claiming the same
+ * string: one wants a file where the other wants a directory (`about` from an
+ * API route, `about/index.html` from a page). The filesystem does refuse that
+ * one — `EISDIR` on the rename, `ENOTDIR` on the mkdir, depending on which
+ * lands second — but an errno names a path, and in the rename case the path
+ * it names is the write's temp file. Reported here instead, so the message says which
+ * two routes.
+ *
+ * Collisions are **collected, not thrown**. `onEntry` runs inside the
+ * generator, whose RSC branch treats a throw as "this payload is unavailable,
+ * SPA navigation falls back to a full load" and swallows it — which for a
+ * collision is the wrong end state, since the two payloads are still
+ * ambiguous. The caller raises them once generation is done.
+ *
+ * @internal Exported for testing.
+ */
+export declare class StaticOutputPaths {
+    private readonly claimed;
+    /** Every ancestor directory of a claimed path, mapped to its claimant. */
+    private readonly directories;
+    private readonly collisions;
+    /**
+     * @param identity How the output filesystem decides two paths name one
+     *   file, from `detectFsIdentity`. The guard predicts whether two writes
+     *   land on one file, which is a property of the filesystem — so it is
+     *   asked, not assumed. Folding unconditionally would reject `/Foo` beside
+     *   `/foo` on Linux, where both are perfectly servable files.
+     */
+    private readonly identity;
+    constructor(identity?: FsIdentity);
+    /** The identity under which the filesystem will compare this path. */
+    private key;
+    /**
+     * Claim `relPath` for `entry`. Returns false when the path cannot be
+     * written alongside an earlier claim, in which case the caller must not
+     * write the file — the losing entry is recorded and the build fails at
+     * the end.
+     */
+    claim(relPath: string, entry: StaticPageEntry): boolean;
+    /** Throw if any two entries could not both be written. */
+    assertNoCollisions(): void;
+}
+/**
+ * Writes generated entries into the static output directory, one file per
+ * entry, refusing any write that would land on a path another entry holds.
+ *
+ * @internal Exported for testing.
+ */
+export declare class StaticSiteWriter {
+    /** Content-Type per URL path for extensionless API routes (TIM-1241). */
+    readonly contentTypes: Record<string, string>;
+    private readonly paths;
+    private readonly staticDir;
+    constructor(staticDir: string, identity?: FsIdentity);
+    write(entry: StaticPageEntry): Promise<void>;
+    /** Throw if any two entries could not both be written. */
+    assertNoCollisions(): void;
+}
+/**
+ * Remove artifacts a generation pass produces only *conditionally*, so none
+ * of them can survive from an earlier build into this one.
+ *
+ * Pages are not in this set: every page is rewritten each pass, and a page
+ * whose route was deleted is a different problem (a stale file nothing links
+ * to) from the one here.
+ *
+ * - `_rsc/` because the files are content-hashed. Left in place, a previous
+ *   build's already-hashed payload gets hashed again and accumulates.
+ * - `_redirects` because it is written only when this pass found redirects.
+ *   A build whose redirects were removed would otherwise ship the previous
+ *   build's rules — and would break the merge exemption in
+ *   `shared/static-platform-files.ts`, which lets the pre-rendered copy
+ *   overwrite `public/_redirects` on the grounds that it *contains* it. That
+ *   holds only for a file the current pass produced (TIM-1266).
+ *
+ * @internal Exported for testing.
+ */
+export declare function cleanConditionalArtifacts(staticDir: string): Promise<void>;
+/**
+ * Run `fn` with `MessageChannel` instrumented, then stop every channel opened
+ * while it ran from holding the process open.
+ *
+ * Static generation is the only build pass that renders **HTML** in the build
+ * process: it imports the built app bundle and drives the full SSR pipeline
+ * through it. React's scheduler opens a `MessageChannel` at module scope in
+ * that bundle (`scheduler`'s DOM build) and never closes it, and a ref'd
+ * `MessagePort` keeps Node's event loop alive on its own — so `timber build`
+ * finished the site, printed its summary, and then hung forever. Server-mode
+ * builds are unaffected because nothing there renders through react-dom.
+ *
+ * `unref()` is the whole fix: it leaves the port working and only drops the
+ * "keep the process alive" property. It is applied **after** `fn` resolves, so
+ * a render in flight can never be cut short by the process exiting under it —
+ * an unref'd port would let Node exit while the scheduler still had a
+ * continuation queued, which is a silently truncated page rather than a hang.
+ *
+ * Nothing renders after this pass. If that ever changes, the release has to
+ * move to the end of whatever renders last.
+ *
+ * @internal Exported for testing.
+ */
+export declare function withSchedulerPortsReleased<T>(fn: () => Promise<T>): Promise<T>;
+/** The pre-rendered site a static generation pass wrote. */
+export interface StaticSite {
+    pages: DirectoryArtifact;
+    /** Content-Type per URL path for extensionless API outputs (TIM-1241). */
+    contentTypes: Record<string, string>;
+    /** `[RSC_PAYLOAD_DIR]` when payloads were written and content-hashed, else none. */
+    immutableDirs: string[];
+}
+/**
+ * Load the built RSC entry and run the static generation pass — the static
+ * generation step of the post-build phase (plugins/post-build.ts).
+ *
+ * The build manifest it renders with is already final: the phase merged the
+ * RSC assets manifest into it and published it before this step. Unlike
+ * prebuilt capture, this needs the FULL pipeline handler, so
+ * __TIMBER_CAPTURE_MODE__ must be false.
+ *
+ * Returns the site only once it is complete, so an adapter is never handed a
+ * directory a failed pass left half-written — a failure throws instead.
+ */
+export declare function runStaticGeneration(ctx: PluginContext, rscDir: string): Promise<StaticSite>;
+/**
+ * Warn when Vite's `base` is document-relative (`'./'`) in static mode.
+ *
+ * Payload URLs are addressed from the deployment root plus the base prefix.
+ * A relative base gives no prefix to compute (see shared/base-path.ts), so
+ * `/_rsc/about.rsc` is requested at the domain root — correct only when the
+ * site is served from there. The build still succeeds: relative bases work
+ * fine for assets, and for a root-served site nothing is wrong. The warning
+ * exists so a sub-path deployment does not silently degrade to a hard
+ * navigation on every link.
+ *
+ * Skipped when client JS is disabled — there is no SPA navigation and no
+ * payload fetch to mis-address.
+ *
+ * @internal Exported for testing.
+ */
+export declare function warnUnusableBase(ctx: PluginContext): void;
+/**
+ * Compute a short content hash for immutable caching.
+ * Uses 8 chars of base64url-encoded SHA-256, matching Vite's asset hash style.
+ */
+export declare function contentHash(data: Buffer | Uint8Array): string;
+/**
+ * Hash all RSC flight payloads in `_rsc/`, rename them with content
+ * hashes, and build a manifest with optional inlined route params.
  *
- * Only active when output: 'static' is configured.
+ * Before: `_rsc/index.rsc`, `_rsc/about.rsc`
+ * After:  `_rsc/index-B7YxEKdN.rsc`, `_rsc/about-C8ZzFLfO.rsc`
+ *
+ * The manifest maps the original `_rsc/` URL to an entry object:
+ * `{"/_rsc/index.rsc":{"url":"/_rsc/index-B7YxEKdN.rsc"}, ...}`
+ *
+ * Keys and URLs are **route-space**: root-relative, never carrying Vite's
+ * `base`. The client applies the base once, at fetch time
+ * (`client/rsc-fetch.ts` → `toStaticRscUrl`), so the generated site stays
+ * relocatable and the base has exactly one expression at runtime rather
+ * than two that must agree. See TIM-1261.
+ *
+ * Route params (from `routeParams`) are inlined into the manifest
+ * entry, eliminating the need for .params.json sidecar files. TIM-1255.
+ *
+ * Injected into HTML as:
+ * `<script>window.__TIMBER_RSC_MANIFEST__={...}</script>`
+ *
+ * @internal Exported for testing.
+ */
+export declare function hashRscPayloads(staticDir: string): Promise<RscManifest>;
+/**
+ * Inject the RSC manifest into all HTML files as a `<script>` tag
+ * before `</head>`. This lets the client resolve hashed RSC URLs
+ * without an extra network request.
+ *
+ * @internal Exported for testing.
+ */
+export declare function injectRscManifestIntoHtml(staticDir: string, manifest: RscManifest): Promise<void>;
+/**
+ * Read a user-authored `_redirects` file from the project's `public/`
+ * directory. Returns `null` if no file exists.
+ *
+ * @internal Exported for testing.
+ */
+export declare function readUserRedirects(root: string): Promise<string | null>;
+/**
+ * Create the timber-static-build Vite plugin.
  *
- * Hooks:
- * - transform: Validates source files for static mode violations
+ * Only active when output: 'static' is configured. Validates source files
+ * for static mode violations; rendering the site is `runStaticGeneration`,
+ * which the post-build phase calls.
  */
 export declare function timberStaticBuild(ctx: PluginContext): Plugin;
 //# sourceMappingURL=static-build.d.ts.map

package/dist/plugins/static-build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"static-build.d.ts","sourceRoot":"","sources":["../../src/plugins/static-build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAOhD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,aAAa,GAAG,gBAAgB,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,wBAAwB,EAAE,OAAO,CAAC;CACnC;AAiBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,qBAAqB,EAAE,CA2BvF;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,GACrB,qBAAqB,EAAE,CA8BzB;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,GACrB,qBAAqB,EAAE,CAOzB;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA0C5D"}
+{"version":3,"file":"static-build.d.ts","sourceRoot":"","sources":["../../src/plugins/static-build.ts"],"names":[],"mappings":"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"}

package/dist/routing/codegen-shared.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared codegen helpers — import-path computation and codec chain type
+ * builders.
+ *
+ * Extracted from `codegen.ts` so `link-codegen.ts` can use the same
+ * helpers without a cyclic import.
+ */
+import type { ParamEntry } from './codegen-types.ts';
+/**
+ * Compute a relative import specifier for a codec/page file, stripping
+ * the .ts/.tsx extension and resolving against the codegen output dir.
+ */
+export declare function codecImportPath(codecFilePath: string, importBase: string | undefined): string;
+/**
+ * Build a TypeScript type expression for a single param using the global
+ * schema's InferCodecType. Falls back to the param's base type when
+ * schema doesn't declare this param (schemas are opt-in per key).
+ *
+ * Uses `infer` to extract the codec value rather than direct indexing
+ * because TypeScript doesn't narrow index validity inside a conditional
+ * type's true branch — `typeof schema.segmentParams[K]` produces TS2538
+ * even when the condition proves K is a valid key. In .d.ts files that
+ * error is suppressed and the type silently becomes `any`.
+ */
+export declare function buildSchemaParamType(p: ParamEntry, fallback?: string): string;
+//# sourceMappingURL=codegen-shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codegen-shared.d.ts","sourceRoot":"","sources":["../../src/routing/codegen-shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAI7E"}

package/dist/routing/codegen-types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared types for route codegen modules.
+ *
+ * Lives in its own file so `link-codegen.ts` and `codegen.ts` can import
+ * the same `RouteEntry` / `ParamEntry` shapes without a cyclic
+ * dependency between the two.
+ */
+/** A single route entry extracted from the segment tree. */
+export interface RouteEntry {
+    /** URL path pattern (e.g. "/products/[id]") */
+    urlPath: string;
+    /** Full tree path including groups and slots (e.g. "/(browse)/[artistSlug]/@shows/[year]").
+     *  Uniquely identifies a segment — unlike urlPath which strips groups/slots. */
+    segmentPath: string;
+    /** Accumulated params from all ancestor dynamic segments */
+    params: ParamEntry[];
+    /** Whether this is an API route (route.ts) vs page route */
+    isApiRoute: boolean;
+    /**
+     * Whether a request can reach this segment — it has a `page` or `route`.
+     *
+     * False for a segment that only hosts a layout/middleware/access above the
+     * leaf. Those still need typed `getSegmentParams(SEGMENT_PATH)` overloads
+     * (they have a `$segment` module), but must NOT appear in urlPath-keyed
+     * emissions — the `Routes` interface and `<Link>` — because their urlPath
+     * is not an addressable route. See TIM-1342.
+     */
+    isRoutable: boolean;
+    /** Whether this entry lives inside a parallel slot (@name). Slot entries
+     *  share their parent's urlPath — urlPath-keyed emissions dedupe them,
+     *  preferring the non-slot entry. segmentPath-keyed emissions keep all. */
+    isSlotRoute?: boolean;
+    /**
+     * Whether this entry lives inside an intercepting subtree.
+     *
+     * Such an entry has **no URL of its own**. Interception adds no URL depth,
+     * so the scanner's `urlPath` for the subtree is the owner's path with the
+     * descendants' names appended — `(browse)/(...)[artistSlug]/[year]` computes
+     * `/[year]`, which is not the route it renders at (that is
+     * `/[artistSlug]/[year]`) and is not reachable by any request. It is also
+     * soft-navigation-only.
+     *
+     * So these entries are dropped from every urlPath-keyed emission (`Routes`,
+     * `useQueryStates`, typed `<Link>`) rather than deduped against the
+     * canonical route: dedupe only helps where the paths happen to collide, and
+     * a non-colliding computed path would be published as a real route.
+     * segmentPath-keyed emissions keep them, so the intercepting page's own
+     * params stay typed.
+     */
+    isInterceptingRoute?: boolean;
+    /** Whether a global schema (app/schema.ts) exists for this app */
+    hasSchema?: boolean;
+}
+export interface ParamEntry {
+    name: string;
+    /** Bracket-wrapped segment name as it appears in the filesystem and schema.
+     *  e.g. '[id]', '[...slug]', '[[...slug]]' */
+    bracketName: string;
+    type: 'string' | 'string[]' | 'string[] | undefined';
+}
+//# sourceMappingURL=codegen-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codegen-types.d.ts","sourceRoot":"","sources":["../../src/routing/codegen-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB;oFACgF;IAChF,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;+EAE2E;IAC3E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;;;;;;;;OAgBG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;kDAC8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,sBAAsB,CAAC;CACtD"}

package/dist/routing/codegen-write.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Route-map codegen writer.
+ *
+ * Materializes the generated route types on disk: `.timber/timber-routes.d.ts`,
+ * `.timber/segment-types.d.ts` (via `writeSegmentTypes`), and the root
+ * `timber-env.d.ts` that references them.
+ *
+ * Lives outside `plugins/routing.ts` because it has two callers with two
+ * different failure policies: the dev/build plugin starts the write off the hot
+ * path and logs failures, while `timber check` awaits it and treats a failure as
+ * fatal — a type check run against absent or stale route types reports errors
+ * about code that is fine. One implementation, two policies, so the bytes on
+ * disk cannot drift between the two commands.
+ *
+ * Design docs: 09-typescript.md §"Typed Routes", 18-build-system.md
+ */
+import type { RouteTree } from './types.ts';
+/**
+ * Path (relative to the project root) of the generated route map declaration
+ * file, and the name of the root file that `/// <reference>`s it.
+ *
+ * Exported because `timber check` has to answer whether the user's tsconfig
+ * pulls these into the program — a question about these exact paths. It derives
+ * them from here rather than restating them, so a rename cannot leave the check
+ * looking for a file nothing writes.
+ */
+export declare const CODEGEN_OUTPUT = ".timber/timber-routes.d.ts";
+/** Root-level file that references the generated declarations. */
+export declare const ENV_DTS_FILENAME = "timber-env.d.ts";
+/**
+ * Resolve once every codegen write started so far has landed on disk.
+ *
+ * Safe to call at any time and from anywhere — writes are tracked per process,
+ * not per plugin instance, so a caller does not need a handle on the plugin
+ * that started them. Never rejects: the tracked copy of each write has its
+ * rejection swallowed, so a failing write cannot turn a teardown barrier into
+ * an unhandled rejection. Callers that care about failure await the promise
+ * `writeRouteCodegen` returned instead.
+ */
+export declare function flushCodegenWrites(): Promise<void>;
+export declare function writeRouteCodegen(tree: RouteTree, appDir: string, root: string): Promise<void>;
+//# sourceMappingURL=codegen-write.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codegen-write.d.ts","sourceRoot":"","sources":["../../src/routing/codegen-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,+BAA+B,CAAC;AAE3D,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AA8ClD;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAcxD;AA2BD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B9F"}

package/dist/routing/codegen.d.ts

@@ -7,17 +7,22 @@
  * This runs at build time and in dev (regenerated on file changes).
  * No runtime overhead — purely static type generation.
  */
-import type { RouteTree } from './types.js';
+import type { RouteTree } from './types.ts';
 /** Options for route map generation. */
 export interface CodegenOptions {
-    /** Absolute path to the app/ directory. Required for search-params.ts detection. */
+    /** Absolute path to the app/ directory. Required for page searchParams detection. */
     appDir?: string;
     /**
      * Absolute path to the directory where the .d.ts file will be written.
-     * Used to compute correct relative import paths for search-params.ts files.
+     * Used to compute correct relative import paths for page files.
      * Defaults to appDir when not provided (preserves backward compat for tests).
      */
     outputDir?: string;
+    /**
+     * Whether a global schema (app/schema.ts) exists.
+     * Auto-detected from appDir when not explicitly set.
+     */
+    hasSchema?: boolean;
 }
 /**
  * Generate a TypeScript declaration file string from a scanned route tree.

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

@@ -1 +1 @@
-{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/routing/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAqBzD,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,CAWtF"}
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/routing/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAMzD,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,CActF"}

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.ts';
+/** 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.ts';
+/**
+ * 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"}