@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/dist/plugins/prebuilt-options-analysis.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Static analysis of `cache.component(fn, options)` option literals for
+ * the timber-prebuilt transform: can this call site's options put the
+ * component in the prerender tier?
+ *
+ * Runtime-tier call sites must do NO build work — recording them would
+ * make the post-build hook import the built RSC entry (running production
+ * startup) and load route modules for routes that have nothing to
+ * prerender (codex P2 on PR #836). The analysis is conservative in one
+ * direction only: over-inclusion costs a wasted entry load (the capture
+ * pass re-checks the real options at runtime and skips), under-inclusion
+ * would silently skip prerendering.
+ */
+import type { CallExpressionNode, PositionedNode } from './callsite-ast.js';
+/** Unwrap TS expression wrappers (`as`, `satisfies`, `!`, parens). */
+export declare function unwrapExpression(node: PositionedNode): PositionedNode;
+/**
+ * Can this call site's options put the component in the prerender tier?
+ * The answer is static only when the options argument is an object
+ * literal:
+ *
+ *   - literal with `prerender: true`            → yes
+ *   - literal with `prerender: false`/absent    → no  (spread-free)
+ *   - literal with statically ACTIVE `slots` + certain runtime lifetime
+ *     → no — registration strips `prerender` for active slot components
+ *       (TIM-1173), so attributing the callsite would make the post-build
+ *       hook import the RSC entry and enumerate route params for entries
+ *       the capture pass then skips (codex P2 on PR #890)
+ *   - anything else (identifier, spread, non-literal values)
+ *     → conservatively yes — the capture pass re-checks at runtime
+ *
+ * Properties walk in source order with last-write-wins, mirroring
+ * object-literal evaluation: `{ prerender: false, ...opts }` may end up
+ * prerenderable (the spread can override), while `{ ...opts,
+ * prerender: false }` is statically false (codex P2 on PR #836).
+ * Computed keys are treated like spreads — they may evaluate to any of
+ * the tracked names.
+ */
+export declare function mayPrerender(call: CallExpressionNode): boolean;
+//# sourceMappingURL=prebuilt-options-analysis.d.ts.map

package/dist/plugins/prebuilt-options-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prebuilt-options-analysis.d.ts","sourceRoot":"","sources":["../../src/plugins/prebuilt-options-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAS5E,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAMrE;AAsED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAoD9D"}

package/dist/plugins/prebuilt.d.ts

@@ -0,0 +1,82 @@
+/**
+ * timber-prebuilt — Vite plugin that detects `cache.component(...)` call
+ * sites and rewrites them to `__prebuilt(stableId, component, options)`.
+ *
+ * `timber.cache.component(Component, { prerender: true })` is a build-time
+ * transform, not a runtime function (design/44-render-at-build-time.md
+ * §Registration, surface API renamed by design/45-cache-lifetimes.md). The
+ * rewrite registers the component in the server-side prebuilt registry under
+ * a stable ID that keys its cached flight payloads.
+ *
+ * Detected callsite forms (mirrors timber-cache-transform, TIM-1054):
+ *   - named imports, including aliases:
+ *       `import { cache } from '@timber-js/app/cache'` + `cache.component(fn, opts)`
+ *   - namespace imports:
+ *       `import * as timber` + `timber.cache.component(fn, opts)`
+ * Computed access (`cache['component']`) is deliberately not matched — the
+ * untransformed call reaches the runtime `cache.component` fallback
+ * (cache/cache-api.ts), which warns once and renders dynamically.
+ *
+ * Matching is an ALLOWLIST of module-scope positions: the direct initializer
+ * of a top-level variable declarator (including exported ones) and a
+ * top-level `export default cache.component(...)`, with TS expression
+ * wrappers (`as`, `satisfies`, `!`) unwrapped. Nothing else is walked — no
+ * function/class/loop bodies, no params, no call arguments. Two reasons:
+ * (1) `__prebuilt` must register exactly once at module load time; the
+ * post-build capture pass walks the registry after loading modules, so a
+ * call inside a function registers too late to ever be prebuilt, and a call
+ * in a loop would re-register per iteration. (2) Name-based callee matching
+ * is only shadow-proof in these positions — nested scopes can rebind `cache`
+ * (`function render(cache) {...}`, `for (const cache of caches) ...`), and
+ * rewriting those would corrupt user code; a top-level declarator initializer
+ * cannot see a shadow of an import binding (redeclaration error). Calls in
+ * other positions fall back to the runtime path like other untraceable forms.
+ *
+ * The rewrite per mode:
+ *   production:  cache.component(fn, opts)  →  __prebuilt("<id>", fn, opts)
+ *   dev:         cache.component(fn, opts)  →  __prebuiltDev("<name>", fn, opts)
+ *
+ * with `import { __prebuilt } from '#server-internal'` prepended. In dev the
+ * wrapper is a no-op that logs once per component and renders dynamically —
+ * no caching, no markers (design/44 §Dev Mode).
+ *
+ * Component identity: `<name>_<hash16>`, e.g. `blogbody_a1b2c3d4e5f6a7b8`.
+ * The name prefix is the declaring variable's name (lowercased, for legible
+ * manifest keys and log lines); the hash is the same content-derived callsite
+ * scheme as the data cache transform (callsite-ast.ts) — deterministic across
+ * builds for unchanged calls, immune to inserting/reordering other calls, and
+ * fresh when the component or its options change. Component cache entries are
+ * per-deploy (design/45 §Per-deploy namespacing) so cross-deploy ID reuse is
+ * not a poisoning vector, but content-derived IDs keep prebuilt artifacts
+ * addressable across incremental edits for free.
+ *
+ * The transform is skipped in the client environment: server components never
+ * execute there, and `#server-internal` resolves to an empty stub in the
+ * client bundle (plugins/shims.ts).
+ *
+ * See TIM-1118, design/44-render-at-build-time.md, design/45-cache-lifetimes.md.
+ */
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+/**
+ * Generate the stable component ID for a cache.component() call site:
+ * `<sanitized-name>_<content-hash16>`. Exported for testing.
+ */
+export declare function generatePrebuiltId(relativeModulePath: string, statementText: string, callSpanText: string, occurrence: number, displayName: string): string;
+/** Rollup getModuleInfo shape (subset — static + dynamic imports). */
+export interface PrebuiltModuleInfo {
+    importedIds: string[];
+    dynamicallyImportedIds?: string[];
+}
+/**
+ * Collect the prebuilt component IDs transitively reachable from a route
+ * file, following static AND dynamic imports. Same pattern as the
+ * client-reference walk in build-manifest.ts; dynamic imports are included
+ * because a dynamically-imported module still registers its components
+ * when it eventually loads — attribution over-approximating registration
+ * is handled at capture time (an attributed-but-unregistered component is
+ * reported and skipped).
+ */
+export declare function collectReachablePrebuiltComponents(entryModuleId: string, moduleComponents: Map<string, string[]>, getModuleInfo: (id: string) => PrebuiltModuleInfo | null): string[];
+export declare function timberPrebuilt(ctx: PluginContext): Plugin;
+//# sourceMappingURL=prebuilt.d.ts.map

package/dist/plugins/prebuilt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prebuilt.d.ts","sourceRoot":"","sources":["../../src/plugins/prebuilt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAoH1D;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,MAAM,EAC1B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,MAAM,CAUR;AAID,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EACvC,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,kBAAkB,GAAG,IAAI,GACvD,MAAM,EAAE,CAgBV;AA8HD,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAkSzD"}

package/dist/plugins/prerender-sugar.d.ts

@@ -0,0 +1,42 @@
+/**
+ * timber-prerender-sugar — Vite plugin that desugars `export const prerender`
+ * on page and layout files into `cache.component(...)` wrappers.
+ *
+ * Design doc: design/45-cache-lifetimes.md §"Route-Level Static" and
+ * §"Layout Propagation".
+ *
+ * `export const prerender = true` on a page is pure sugar: it desugars to
+ * wrapping the page's default export in `timber.cache.component(Component,
+ * { prerender: true })`. Layout propagation cascades a layout's
+ * `export const prerender` to descendant pages via most-specific-wins:
+ * walk the segment tree from leaf to root, first explicit value wins.
+ *
+ * A layout that declares `export const prerender` is ALSO wrapped — the
+ * layout's flight payload is its own static shell (`children` is a
+ * separate component boundary), so caching it is natural (nav, sidebar,
+ * footer benefit from build-time rendering). See design/45 §Layout
+ * Propagation.
+ *
+ * This transform runs BEFORE timber-prebuilt so the generated
+ * `cache.component(...)` call is picked up by the callsite rewrite.
+ */
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+import type { SegmentNode } from '../routing/types.js';
+import { type PrerenderExportValue } from '../routing/export-detect.js';
+/**
+ * Walk the segment tree and resolve the effective prerender value for
+ * every page and layout. Returns a map from file path to resolved value.
+ *
+ * **Pages:** walk from leaf toward root; first explicit `export const prerender`
+ * wins (page > nearest layout > ... > root layout). If none, dynamic.
+ *
+ * **Layouts:** a layout that declares `export const prerender` is wrapped
+ * directly (its own shell is a separate component boundary from `children`).
+ * Layouts without their own declaration are NOT wrapped — they don't
+ * inherit from ancestors, because wrapping a layout's shell without the
+ * author's explicit opt-in would cache content they may expect to be dynamic.
+ */
+export declare function resolvePagePrerender(root: SegmentNode): Map<string, PrerenderExportValue>;
+export declare function timberPrerenderSugar(ctx: PluginContext): Plugin;
+//# sourceMappingURL=prerender-sugar.d.ts.map

package/dist/plugins/prerender-sugar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prerender-sugar.d.ts","sourceRoot":"","sources":["../../src/plugins/prerender-sugar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAY5F;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAgCzF;AAuFD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA4J/D"}

package/dist/plugins/request-dep.d.ts

@@ -0,0 +1,21 @@
+/**
+ * timber-request-dep — Static module-graph analysis for request-dependency.
+ *
+ * Replaces runtime ALS-based taint tracking with a build/dev-time computed
+ * map: segment entry file → statically request-dependent?
+ *
+ * A segment/slot is request-dependent iff any module reachable from its
+ * layout/page/default in the RSC module graph (stopping at client-reference
+ * boundaries) imports and calls a request accessor (getHeaders, cookies,
+ * getSearchParams, etc.) or calls .get() on a search-params/cookie
+ * definition object.
+ *
+ * This is deterministic, covers children/barrels/node_modules/Suspense-
+ * deferred code, and is computed before any byte is flushed.
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+ */
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+export declare function timberRequestDep(ctx: PluginContext): Plugin;
+//# sourceMappingURL=request-dep.d.ts.map

package/dist/plugins/request-dep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-dep.d.ts","sourceRoot":"","sources":["../../src/plugins/request-dep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAoT1D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA0G3D"}

package/dist/plugins/routing.d.ts

@@ -8,6 +8,6 @@
  * Design docs: 18-build-system.md §"Virtual Modules", 07-routing.md
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 export declare function timberRouting(ctx: PluginContext): Plugin;
 //# sourceMappingURL=routing.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAWlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA2DhD,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA2GxD"}
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAqBlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAwG1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAuNxD"}

package/dist/plugins/server-bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-bundle.d.ts","sourceRoot":"","sources":["../../src/plugins/server-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CA6H7C"}
+{"version":3,"file":"server-bundle.d.ts","sourceRoot":"","sources":["../../src/plugins/server-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAoCnC,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAuK7C"}

package/dist/plugins/shims.d.ts

@@ -5,15 +5,39 @@
  * shim implementations. This enables Next.js-compatible libraries
  * (nuqs, next-intl, etc.) to work unmodified.
  *
- * NOTE: This plugin does NOT resolve @timber-js/app/* subpath imports.
- * Those are handled by Vite's native package.json `exports` resolution,
- * which maps them to dist/ files. This ensures a single module instance
- * for shared modules like request-context (ALS singleton).
+ * This plugin also remaps ALL @timber-js/app/* subpath imports to src/ in
+ * server environments (RSC + SSR). This is required because dist/ chunks
+ * are pre-built and miss Vite's RSC transforms (e.g. createContext from
+ * 'react' doesn't exist in RSC's React build). It also ensures a single
+ * module instance for shared mutable state. See SUBPATH_SRC_MAP and TIM-568.
  *
  * Design doc: 18-build-system.md §"Shim Map"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
+/**
+ * Map from @timber-js/app/<subpath> to relative src/ file paths.
+ *
+ * Used by the catch-all resolveId rule to remap subpath imports to src/
+ * in server environments. When adding a new subpath export to package.json,
+ * add it here too — tests/shims-drift.test.ts enumerates package.json
+ * exports and fails if an entry is missing. See TIM-568.
+ *
+ * Exported for the drift test.
+ */
+export declare const SUBPATH_SRC_MAP: Record<string, string>;
+/**
+ * Runtime value exports of @timber-js/app/server, stubbed in the client
+ * (browser) environment so a stray client-side import fails with a clear
+ * call-time error instead of a confusing bundler error.
+ *
+ * Must stay in sync with the actual runtime exports of server/index.ts —
+ * tests/shims-drift.test.ts compares this list against
+ * Object.keys(import('../server/index.ts')) and fails on drift.
+ * Type-only exports (DenyOptions, AccessContext, …) are erased at runtime
+ * and must NOT appear here.
+ */
+export declare const SERVER_STUB_EXPORTS: readonly string[];
 /**
  * Create the timber-shims Vite plugin.
  *

package/dist/plugins/shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/plugins/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAiDhD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CA4JvD"}
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/plugins/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAsB1D;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAsBlD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EA6BhD,CAAC;AA2CF;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAkPvD"}

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

@@ -2,47 +2,26 @@
  * 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
+ * 1. Validates that no dynamic APIs (getCookies(), getHeaders()) are used
+ * 2. Coordinates build-time rendering of all pages
  *
  * Design doc: design/15-future-prerendering.md
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 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.
- *
- * When client JavaScript is enabled, these are allowed (client components
- * hydrate, server actions get extracted to API endpoints).
- */
-export declare function detectDirectives(code: string, fileId: string, options: StaticOptions): StaticValidationError[];
-/**
- * Run all static mode validations on a source file.
- *
- * Combines:
- * - Dynamic API detection (cookies, headers) — always in static mode
- * - Directive detection ('use client', 'use server') — only when client JS is disabled
- */
-export declare function validateStaticMode(code: string, fileId: string, options: StaticOptions): StaticValidationError[];
 /**
  * Create the timber-static-build Vite plugin.
  *

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":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAM1D,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAmBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,qBAAqB,EAAE,CA2BvF;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA2C5D"}

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

@@ -0,0 +1,67 @@
+/**
+ * Shared codegen helpers — import-path computation, codec chain type
+ * builder, and searchParams type formatter.
+ *
+ * Extracted from `codegen.ts` so `link-codegen.ts` can use the same
+ * helpers without a cyclic import.
+ */
+import type { ParamEntry, RouteEntry } from './codegen-types.js';
+/**
+ * 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;
+/** Name of the shared helper type emitted at the top of the .d.ts. */
+export declare const RESOLVE_SEGMENT_FIELD_TYPE_NAME = "_TimberResolveSegmentField";
+/**
+ * Helper type emitted once at the top of the generated `.d.ts` and
+ * referenced by every codec-chain conditional. Without this shared
+ * helper, the inline expansion would duplicate the fallback branch on
+ * every step and grow O(2^N) in chain depth (a single deep nested route
+ * could blow up the file size and TS performance). With the helper,
+ * each step reuses the named type and growth is O(N).
+ *
+ * The helper is a 2-arg conditional: given a typeof import expression
+ * (`Def`), a key (`K`), and a fallback (`F`), it returns `T[K]` if
+ * `Def extends ParamsDefinition<T>` and `K extends keyof T`, otherwise
+ * `F`. The codec chain composes calls to this helper.
+ */
+export declare function emitResolveSegmentFieldHelper(): string;
+/**
+ * Build a TypeScript type expression that resolves a single param's
+ * codec by walking a chain of params.ts files in priority order.
+ *
+ * Each entry in the chain emits one application of the shared
+ * `_TimberResolveSegmentField` helper type. Composing N applications
+ * grows linearly with chain depth (O(N) characters), unlike an inline
+ * conditional that would duplicate the fallback in each branch and
+ * grow O(2^N).
+ *
+ * The closest match (position 0 in the chain) is checked first; if its
+ * `segmentParams` definition declares the key, its inferred type wins.
+ * Otherwise we fall through to the next entry, and finally to the
+ * provided fallback. See TIM-834.
+ */
+export declare function buildCodecChainType(p: ParamEntry, importBase: string | undefined, fallback: string): 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;
+/**
+ * Format the searchParams type for a route entry.
+ *
+ * When a page.tsx (or params.ts) exports searchParams, we reference its
+ * inferred type via an import type. The import path is relative to
+ * `importBase` (the directory where the .d.ts will be written). When
+ * importBase is undefined, falls back to a bare relative path.
+ */
+export declare function formatSearchParamsType(route: RouteEntry, importBase?: 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,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7F;AAED,sEAAsE;AACtE,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAE5E;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,IAAI,MAAM,CAOtD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,UAAU,EACb,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,GACf,MAAM,CAaR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAI7E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAOrF"}

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

@@ -0,0 +1,64 @@
+/**
+ * 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 the page.tsx exports searchParams */
+    hasSearchParams: boolean;
+    /** Absolute path to the page file that exports searchParams (for import paths) */
+    searchParamsPagePath?: string;
+    /** Whether this is an API route (route.ts) vs page route */
+    isApiRoute: 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 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';
+    /**
+     * Ordered list of params.ts files in the route chain that may declare
+     * a codec for this param, in priority order — **closest-to-leaf
+     * first**. The generated type emits a chain that picks the first
+     * entry whose `segmentParams` definition declares this param key.
+     *
+     * This array is the SAME for every param in a given route entry
+     * (it is the route's full ancestry of params.ts files in leaf-first
+     * order); the type-level conditional in `buildCodecChainType`
+     * narrows per-key. Sharing the array matches the runtime semantics
+     * of `coerceSegmentParams`, which walks segments top-down and lets
+     * later (deeper) coercions overwrite earlier ones — closest-to-leaf
+     * wins for both types and runtime.
+     *
+     * See TIM-834.
+     */
+    codecFilePaths?: string[];
+    /**
+     * Per-segment legacy fallback: a layout.tsx or page.tsx that exports
+     * `segmentParams` directly (pre-TIM-508 convention). Used only when
+     * the chain has no params.ts files at all. Does NOT participate in
+     * inheritance — a layout/page export is per-segment only.
+     *
+     * @internal Set during `collectRoutes`; consumed at leaf time when
+     *   building the final `codecFilePaths`.
+     */
+    legacyCodecFilePath?: string;
+}
+//# 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,gDAAgD;IAChD,eAAe,EAAE,OAAO,CAAC;IACzB,kFAAkF;IAClF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAC;IACpB;;+EAE2E;IAC3E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,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;IACrD;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B"}

package/dist/routing/codegen.d.ts

@@ -10,14 +10,19 @@
 import type { RouteTree } from './types.js';
 /** 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;AAWzD,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/convention-lint.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ *
+ * These are warnings, not errors — 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).
+ *
+ * Design doc: 07-routing.md, 10-error-handling.md
+ */
+import type { RouteTree } from './types.js';
+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;
+/**
+ * Format warnings for terminal output.
+ *
+ * Groups by severity, uses colors, and includes fix suggestions.
+ */
+export declare function formatConventionWarnings(warnings: ConventionWarning[]): 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;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAWzD,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,CA2BpF;AAgQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAe1E;AAWD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAgC9E"}

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

@@ -0,0 +1,56 @@
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;AAgGH;;;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;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;;;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"}