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

package/dist/plugins/fonts.d.ts

@@ -1,83 +1,26 @@
 /**
- * timber-fonts — Vite sub-plugin for build-time font processing.
+ * timber-fonts — Vite sub-plugin shell for build-time font processing.
  *
- * Handles:
- * - Virtual module resolution for `@timber/fonts/google` and `@timber/fonts/local`
- * - Static analysis of font function calls during `transform`
- * - @font-face CSS generation and scoped class output
- * - Size-adjusted fallback font generation
+ * This file is intentionally thin: it wires the Vite plugin hooks to the
+ * pipeline + per-concern modules under `../fonts/`. All real logic lives
+ * in:
  *
- * Does NOT handle (separate tasks):
- * - Google Fonts downloading/caching (timber-nk5)
- * - Build manifest / Early Hints integration (timber-qnx)
+ * - `../fonts/pipeline.ts`        — `FontPipeline` (state, mutators)
+ * - `../fonts/transform.ts`       — transform-hook logic, parsing helpers
+ * - `../fonts/dev-middleware.ts`  — dev font binary server
+ * - `../fonts/virtual-modules.ts` — virtual module ID constants + source
+ *
+ * The public exports below are the stable API that the test suite and
+ * other parts of the framework import. Anything new should be added to
+ * one of the per-concern modules and re-exported here only if external
+ * consumers need it.
  *
  * Design doc: 24-fonts.md
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { ExtractedFont, GoogleFontConfig } from '#/fonts/types.js';
-/**
- * Registry of fonts extracted during transform.
- * Keyed by a unique font ID derived from family + config.
- */
-export type FontRegistry = Map<string, ExtractedFont>;
-/**
- * Extract static font config from a font function call in source code.
- *
- * Parses patterns like:
- *   const inter = Inter({ subsets: ['latin'], weight: '400', display: 'swap', variable: '--font-sans' })
- *
- * Returns null if the call cannot be statically analyzed.
- *
- * Uses acorn AST parsing for robust handling of comments, trailing commas,
- * and multi-line configs.
- */
-export declare function extractFontConfig(callSource: string): GoogleFontConfig | null;
-/**
- * Detect if a source file contains dynamic/computed font function calls
- * that cannot be statically analyzed.
- *
- * Returns the offending expression if found, null if all calls are static.
- *
- * Uses acorn AST parsing for accurate detection.
- */
-export declare function detectDynamicFontCall(source: string, importedNames: string[]): string | null;
-/**
- * Parse import specifiers from a source file that imports from
- * `@timber/fonts/google` or `next/font/google`.
- *
- * Returns the list of imported font names (e.g. ['Inter', 'JetBrains_Mono']).
- */
-export declare function parseGoogleFontImports(source: string): string[];
-/**
- * Parse the original (remote) font family names from imports.
- *
- * Returns a map of local name → family name.
- * e.g. { Inter: 'Inter', JetBrains_Mono: 'JetBrains Mono' }
- */
-export declare function parseGoogleFontFamilies(source: string): Map<string, string>;
-/**
- * Generate CSS for a single extracted font.
- *
- * Includes @font-face rules (for local fonts), fallback @font-face,
- * and the scoped class rule.
- */
-export declare function generateFontCss(font: ExtractedFont): string;
-/**
- * Generate the CSS output for all extracted fonts.
- *
- * Includes @font-face rules for local fonts, fallback @font-face rules,
- * and scoped classes.
- */
-export declare function generateAllFontCss(registry: FontRegistry): string;
-/**
- * Parse the local name used for the default import of `@timber/fonts/local`.
- *
- * Handles:
- *   import localFont from '@timber/fonts/local'
- *   import myLoader from '@timber/fonts/local'
- */
-export declare function parseLocalFontImportName(source: string): string | null;
+import type { PluginContext } from '../plugin-context.js';
+export { FontPipeline } from '../fonts/pipeline.js';
+export { generateFontId, extractFontConfig, detectDynamicFontCall, parseGoogleFontImports, parseGoogleFontFamilies, parseLocalFontImportName, } from '../fonts/transform.js';
 /**
  * Create the timber-fonts Vite plugin.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../../src/plugins/fonts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAGlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAmCxE;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AA4CtD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAE7E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAE5F;AAUD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkB/D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAqB3E;AAwED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAmB3D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAMjE;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKtE;AAqED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwVtD"}
+{"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../../src/plugins/fonts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAiC,MAAM,MAAM,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA2B1D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA8OtD"}

package/dist/plugins/mdx.d.ts

@@ -8,7 +8,7 @@
  * Design doc: 20-content-collections.md §"The timber-mdx Plugin"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 /**
  * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root
  * or in src/. Root takes precedence, matching Next.js behavior.

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

@@ -1 +1 @@
-{"version":3,"file":"mdx.d.ts","sourceRoot":"","sources":["../../src/plugins/mdx.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAelE;AA+BD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA0GpD"}
+{"version":3,"file":"mdx.d.ts","sourceRoot":"","sources":["../../src/plugins/mdx.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAKnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAelE;AAiED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA2GpD"}

package/dist/plugins/prebuilt-capture.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Post-build prebuilt capture — Node-side orchestration (TIM-1119).
+ *
+ * Runs from timber-prebuilt's `buildApp` post hook, after Vite's 5-step
+ * build sequence. Imports the BUILT `rsc/index.js` (the bundle carries
+ * the react-server condition resolved at build time, so a plain dynamic
+ * import works) and calls its `__timber_capturePrebuilt` export — the
+ * capture itself must run inside the bundle's module graph, where the
+ * component registry and flight renderer live. See
+ * server/prebuilt-builder.ts and design/44-render-at-build-time.md
+ * §Build Phase.
+ *
+ * This side owns PERSISTENCE: each captured payload is written to
+ * `.timber/dist/prebuilt/<componentId>/<cacheKey>.flight` atomically
+ * (temp file + rename — a crashed build never leaves a torn artifact
+ * under its final name), and `manifest.json` is written last, only after
+ * every payload it references is fully on disk. Keeping node:fs on the
+ * plugin side keeps it out of the server bundle, which must also run on
+ * Cloudflare Workers.
+ *
+ * NOTE: importing the built entry runs the app's production startup —
+ * instrumentation.ts register() and the configured cache handler load
+ * inside the build process. That is by design (prebuilt components may
+ * call timber.cache), and it only happens when the app actually declares
+ * prebuilt components.
+ */
+import type { PluginContext } from '../plugin-context.js';
+import type { CaptureSummary, CapturedEntry } from '../server/prebuilt-builder.js';
+export interface PrebuiltArtifactWriter {
+    write(entry: CapturedEntry): Promise<void>;
+    /** Write manifest.json (if any entries exist). Returns the entry count. */
+    finalize(): Promise<number>;
+}
+/**
+ * Create the writer for `.timber/dist/prebuilt/`. Storage layout per
+ * design/44 §Storage: one directory per component ID, one `.flight` file
+ * per cache key, one manifest.json mapping componentId + key → file +
+ * metadata.
+ */
+export declare function createPrebuiltArtifactWriter(prebuiltDir: string): PrebuiltArtifactWriter;
+/**
+ * Remove any `prebuilt/` output left by a previous build in this
+ * directory (watch mode, `emptyOutDir: false`). A stale manifest would
+ * make adapters ship payloads from an OLD build — reviving them serves
+ * outdated content with that build's chunk references instead of the
+ * intended miss → live render. Runs unconditionally at the start of the
+ * post-build hook, BEFORE the capture decision: a build whose app no
+ * longer declares any prebuilt components must also shed the artifacts
+ * (codex P2 on PR #836).
+ */
+export declare function cleanPrebuiltDir(buildDir: string): Promise<void>;
+/**
+ * Load the built RSC entry and run the capture pass. Throws (failing the
+ * build) on infrastructure errors — missing/unloadable entry — and on
+ * dynamic-context hard errors (cookies()/headers() in a prerendered
+ * component). Per-entry data errors skip-and-report per design/44
+ * §Build-Phase Error Handling.
+ */
+export declare function runPrebuiltCapture(ctx: PluginContext): Promise<CaptureSummary>;
+//# sourceMappingURL=prebuilt-capture.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prebuilt-capture.d.ts","sourceRoot":"","sources":["../../src/plugins/prebuilt-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAkB,cAAc,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAanG,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B;AASD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB,CAwCxF;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AASD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAiFpF"}

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

@@ -0,0 +1,106 @@
+/**
+ * Per-module syntactic facts for request-dependency analysis.
+ *
+ * This module is deliberately dumb: it records *what the source says*, with no
+ * knowledge of which specifiers or names are interesting. Every judgement —
+ * "is this an accessor", "is this a definition object" — lives in `origin.ts`,
+ * which resolves a binding to the module it actually came from.
+ *
+ * That split is the point. The previous shape asked each module in isolation
+ * "do you import `getSearchParams` from `@timber-js/app/server` and call it",
+ * which any indirection defeats: a barrel re-export, a namespace import, a
+ * factory reached through the app's own `_lib`. Each of those was a separate
+ * hole and each was found separately (TIM-1291). Recording bindings and edges
+ * here, and resolving them across the graph there, closes the family instead of
+ * its members.
+ *
+ * See design/19-client-navigation.md §"Why the slot comparison ignores the query".
+ */
+import type { ProgramNode } from '../callsite-ast.js';
+/**
+ * One module-graph edge introduced by an `import` or `export … from`.
+ *
+ * `imported` is the name as it exists in the *source* module: an export name,
+ * `'default'`, or `'*'` for a namespace/star form.
+ */
+export interface ImportEdge {
+    source: string;
+    imported: string;
+}
+/** The callee of `const x = f()` / `const x = ns.f()`. */
+export type CalleeRef = {
+    kind: 'local';
+    name: string;
+} | {
+    kind: 'member';
+    object: string;
+    property: string;
+};
+export interface ModuleFacts {
+    /** Local name → the edge that bound it (`import { a as b } from 'x'`). */
+    importedBindings: Map<string, ImportEdge>;
+    /** Exported name → edge, for `export { a as b } from 'x'`. */
+    reExports: Map<string, ImportEdge>;
+    /** Sources of anonymous `export * from 'x'`, in source order. */
+    starReExports: string[];
+    /** Exported name → local name, for `export { x }`, `export const x = …`. */
+    localExports: Map<string, string>;
+    /** Local variable name → the callee that produced its value. */
+    factoryCalls: Map<string, CalleeRef>;
+    /** Local names invoked directly: `f()`. */
+    calledLocals: Set<string>;
+    /** `ns.f()` → `ns` → `{ f }`. */
+    calledMembers: Map<string, Set<string>>;
+    /** Base identifier of a `.get()` chain: `x.get()`, `x().get()`, `x.p.get()`. */
+    getterLocals: Set<string>;
+    /** `ns.defs.get()` → `ns` → `{ defs }`. */
+    getterMembers: Map<string, Set<string>>;
+    /** Every name the module *body* mentions — import/export clauses excluded. */
+    referencedLocals: Set<string>;
+    /** Specifier → resolved module id, filled by the plugin via `this.resolve`. */
+    resolvedSources: Map<string, string>;
+    /** Specifiers that failed to resolve — treated as request-dependent. */
+    unresolvedSources: Set<string>;
+}
+/** `export default` has no local name of its own; this stands in for one. */
+export declare const DEFAULT_EXPORT = "default";
+export declare function createModuleFacts(): ModuleFacts;
+/**
+ * Specifiers the origin walk can actually reach, so the plugin resolves those
+ * and not every import in the file.
+ *
+ * A re-export edge is always reachable — a downstream module can ask for any
+ * name it forwards. An `import` edge is reachable through any local name the
+ * module body mentions, or that it re-exports.
+ *
+ * The name set must be **the same one the taint rules consult**. Deriving it
+ * from the call shapes instead (called, `.get()`d, member-called, minted from)
+ * left `read(filters)` — a definition passed as an argument — with its
+ * specifier unresolved, so the origin walk reported it inert and the page read
+ * as request-independent. Two hand-maintained lists of "names that matter" is
+ * one list too many; this is the one, and `referencedLocals` is a superset of
+ * every call shape by construction, since each of them is an identifier the
+ * walk visits. (Codex review round 1 on PR #991.)
+ */
+export declare function usedSources(facts: ModuleFacts): Set<string>;
+/**
+ * True when the module cannot affect any answer, so its facts need not be kept.
+ *
+ * Every judgement bottoms out at a module edge: a call site resolves through
+ * `importedBindings`, a chain link through `reExports` / `starReExports`. A
+ * module with none of those can only ever resolve to `none` — its exports lead
+ * to locals that lead nowhere — which is exactly what a *missing* entry
+ * produces. Dropping it is behaviour-preserving and keeps the dev-time map from
+ * holding an entry for every leaf module in the graph.
+ */
+export declare function contributesNothing(facts: ModuleFacts): boolean;
+/**
+ * Record every binding, module edge, and call shape in one module.
+ *
+ * Names are recorded without scope analysis, so a parameter that shadows an
+ * imported name is credited to the import. That direction is deliberate: a
+ * needlessly request-dependent segment costs a re-render, a wrongly static one
+ * serves stale content.
+ */
+export declare function analyzeModule(program: ProgramNode): ModuleFacts;
+//# sourceMappingURL=analysis.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../../../src/plugins/request-dep/analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,WAAW,EAKZ,MAAM,oBAAoB,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC1C,8DAA8D;IAC9D,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,iEAAiE;IACjE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,gEAAgE;IAChE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACrC,2CAA2C;IAC3C,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,iCAAiC;IACjC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACxC,gFAAgF;IAChF,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,2CAA2C;IAC3C,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACxC,8EAA8E;IAC9E,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,+EAA+E;IAC/E,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,wEAAwE;IACxE,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAChC;AAED,6EAA6E;AAC7E,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,wBAAgB,iBAAiB,IAAI,WAAW,CAe/C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,CAa3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAM9D;AAsRD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,CAsB/D"}

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

@@ -0,0 +1,75 @@
+/**
+ * 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) reads the request: it calls a request accessor (`getHeaders`,
+ * `getSearchParams`, `cookies`, …) or calls `.get()` on a value minted by
+ * `defineSearchParams` / `defineCookie`.
+ *
+ * "Calls a request accessor" is decided by resolving the call site's binding
+ * back through import and re-export edges (`origin.ts`), not by matching the
+ * calling module's own import declarations. That distinction is the whole
+ * ticket: a barrel, an alias, or a namespace import used to make a page that
+ * reads the query look static, and a static slot is cached and skipped on a
+ * query-only navigation — serving stale content (TIM-1273, TIM-1291).
+ *
+ * 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';
+import { type ModuleFacts } from './analysis.js';
+export type { ModuleFacts } from './analysis.js';
+export { analyzeModule, usedSources } from './analysis.js';
+export { createOriginResolver } from './origin.js';
+export declare function isFrameworkModule(id: string): boolean;
+export interface ReachabilityInput {
+    factsMap: ReadonlyMap<string, ModuleFacts>;
+    getImports: (id: string) => string[];
+    /**
+     * Does the graph this walk runs over contain this module at all?
+     *
+     * Only the entry needs asking. Every other id the walk visits comes out of
+     * `getImports`, which enumerates edges the graph already resolved, so those
+     * are known by construction. The entry comes from outside — the route
+     * manifest's `filePath`, produced by the scanner from the filesystem — and
+     * nothing guarantees it is spelled the way the graph spells it, or that the
+     * module has been pulled through the pipeline yet.
+     */
+    isKnownModule: (id: string) => boolean;
+}
+/**
+ * Walk the module graph from an entry, returning true if any module reachable
+ * from it reads the request.
+ *
+ * Two passes, and the second is a deliberately blunt backstop:
+ *
+ * 1. **Binding origins.** For each reachable module, resolve every call site's
+ *    binding to its origin. This is precise and indifferent to indirection.
+ * 2. **Definition reachability.** A module that calls `.get()` on *something*
+ *    it imported, with a module holding a definition factory reachable behind
+ *    that import, counts too. The origin walk cannot see through a value that
+ *    is computed rather than bound — `getFilterCookie(key).get()`, where the
+ *    helper returns a definition — and this pass can.
+ *
+ * The second pass over-reports by construction, which is the safe direction: a
+ * needlessly request-dependent segment costs a re-render, a wrongly static one
+ * serves stale content.
+ *
+ * An entry the graph does not contain is an edge we failed to walk, not the
+ * absence of one — the same rule an unresolvable specifier gets. Without the
+ * check it reads as an entry with no imports and no facts, and both passes fall
+ * through to `false`: confidently request-INdependent, for a module nothing
+ * ever looked at. In the build that answer is worse than no answer, because it
+ * is written into `requestDep` as a definite `false` and the runtime's own
+ * "absent key → conservative" fallback never fires.
+ */
+export declare function isReachableTaintSource(entryId: string, input: ReachabilityInput): boolean;
+export declare function timberRequestDep(ctx: PluginContext): Plugin;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/request-dep/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAkD,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjG,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAInD,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKrD;AAgCD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IACrC;;;;;;;;;OASG;IACH,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAgCzF;AAyED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAkI3D"}

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

@@ -0,0 +1,61 @@
+/**
+ * Binding-origin resolution across the module graph.
+ *
+ * Given a local name at a call site, walk import and re-export edges until the
+ * binding lands somewhere that can be classified: a framework request accessor,
+ * a definition factory, a definition object minted by one, or nothing of
+ * interest. The walk is what makes the analysis indifferent to how the app
+ * organises its own code — a barrel, an alias, a namespace import, and a
+ * re-export chain five hops deep all reach the same origin (TIM-1291).
+ *
+ * The asymmetry that governs every judgement here: over-reporting costs a
+ * re-render, under-reporting serves stale content to a client that cached a
+ * slot whose render varies with the query. So an edge we cannot follow resolves
+ * to `unknown`, and `unknown` counts as request-dependent.
+ *
+ * See design/19-client-navigation.md §"Why the slot comparison ignores the query".
+ */
+import type { ModuleFacts } from './analysis.js';
+/** Every specifier the classifier recognises without resolving it. */
+export declare const FRAMEWORK_SOURCES: ReadonlySet<string>;
+export type Origin = 
+/** A request accessor: `getSearchParams`, `cookies`, … */
+{
+    kind: 'accessor';
+}
+/** A definition factory: `defineSearchParams`, `defineCookie`. */
+ | {
+    kind: 'factory';
+}
+/** A value minted by a definition factory — `.get()` on it reads the request. */
+ | {
+    kind: 'definition';
+}
+/** A namespace object for a framework module (`import * as h from 'next/headers'`). */
+ | {
+    kind: 'framework-namespace';
+    source: string;
+}
+/** A namespace object for an app module. */
+ | {
+    kind: 'namespace';
+    moduleId: string;
+}
+/** An edge that could not be followed. Treated as request-dependent. */
+ | {
+    kind: 'unknown';
+}
+/** Resolved, and not interesting. */
+ | {
+    kind: 'none';
+};
+export interface OriginResolver {
+    /** Does this module itself read the request? */
+    isTainted(moduleId: string): boolean;
+    /** Does this module hold a definition factory binding? */
+    isDefinitionModule(moduleId: string): boolean;
+    /** Does this module call `.get()` on a binding it imported? */
+    callsGetterOnImport(moduleId: string): boolean;
+}
+export declare function createOriginResolver(factsMap: ReadonlyMap<string, ModuleFacts>): OriginResolver;
+//# sourceMappingURL=origin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../../../src/plugins/request-dep/origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAyB,WAAW,EAAE,MAAM,eAAe,CAAC;AAwBxE,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAGhD,CAAC;AAIH,MAAM,MAAM,MAAM;AAChB,0DAA0D;AACxD;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE;AACtB,kEAAkE;GAChE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE;AACrB,iFAAiF;GAC/E;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE;AACxB,uFAAuF;GACrF;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACjD,4CAA4C;GAC1C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AACzC,wEAAwE;GACtE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE;AACrB,qCAAqC;GACnC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAkCrB,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC,0DAA0D;IAC1D,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9C,+DAA+D;IAC/D,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAChD;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,cAAc,CA0M/F"}

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;AAYlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA+C1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwRxD"}