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

package/dist/fonts/transform.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Transform-hook logic for the timber-fonts plugin.
+ *
+ * Scans source files for font function calls (`Inter({...})`,
+ * `localFont({...})`), validates that they are statically analysable,
+ * registers the extracted fonts in the `FontPipeline`, and rewrites the
+ * call sites to static `FontResult` literals so the runtime never has to
+ * evaluate the font function.
+ *
+ * Uses a single OXC (via vite.parseAst) parse of the source file (via `findFontCallSites`)
+ * and magic-string for precise source rewrites with source maps.
+ *
+ * Design doc: 24-fonts.md
+ */
+import MagicString from 'magic-string';
+import type { GoogleFontConfig } from './types.ts';
+import type { FontPipeline } from './pipeline.ts';
+/**
+ * Generate a unique font ID from family + config hash.
+ *
+ * The ID intentionally includes every property that affects the rendered
+ * `@font-face` output (`weight`, `style`, `subsets`, `display`) so that an
+ * HMR edit changing any of those produces a new ID and the registry is
+ * forced to re-emit fresh CSS.
+ */
+export declare function generateFontId(family: string, config: GoogleFontConfig): string;
+/**
+ * Extract static font config from a font function call source.
+ *
+ * Returns `null` if the call cannot be statically analysed.
+ */
+export declare function extractFontConfig(callSource: string): GoogleFontConfig | null;
+/**
+ * Detect dynamic/computed font function calls that cannot be statically
+ * analysed. Returns the offending expression text, or `null` if all calls
+ * are static.
+ */
+export declare function detectDynamicFontCall(source: string, importedNames: string[]): string | null;
+/**
+ * Parse the local names imported from `@timber/fonts/google` /
+ * `next/font/google`. e.g. `import { Inter, JetBrains_Mono as Mono }` →
+ * `['Inter', 'Mono']`.
+ */
+export declare function parseGoogleFontImports(source: string): string[];
+/**
+ * Parse Google font imports into a `localName → familyName` map.
+ *
+ * e.g. `import { JetBrains_Mono as Mono }` → `{ Mono: 'JetBrains Mono' }`.
+ * The original (pre-`as`) name is converted from PascalCase-with-underscores
+ * to the human-readable family name by replacing `_` with a space.
+ */
+export declare function parseGoogleFontFamilies(source: string): Map<string, string>;
+/**
+ * Parse the local name used for the default import of `@timber/fonts/local`.
+ *
+ * Handles either spelling and arbitrary local names:
+ *   import localFont from '@timber/fonts/local'
+ *   import myLoader from 'next/font/local'
+ */
+export declare function parseLocalFontImportName(source: string): string | null;
+/** Type for the Vite plugin's `this.error` callback. */
+type EmitError = (msg: string) => never;
+/**
+ * Run the timber-fonts transform pass on a single source file.
+ *
+ * Parses the source once with OXC (via vite.parseAst), walks the AST to find font imports
+ * and call sites, then uses magic-string to rewrite call sites to static
+ * `FontResult` literals and strip the import declarations. Returns a
+ * source map alongside the transformed code.
+ *
+ * Returns `null` if the file does not import from any font virtual module.
+ *
+ * Pre-filtering (extension allow-list, node_modules exclusion, and code
+ * substring checks) is handled by Vite 8's rolldown-native `transform.filter`
+ * in the plugin hook definition (plugins/fonts.ts). See TIM-840, TIM-1147.
+ */
+export declare function runFontsTransform(code: string, id: string, pipeline: FontPipeline, emitError: EmitError): {
+    code: string;
+    map: ReturnType<MagicString['generateMap']>;
+} | null;
+export {};
+//# sourceMappingURL=transform.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/fonts/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,WAAW,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAUlE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAsBlD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAM/E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAE5F;AAOD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAU3E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKtE;AASD,wDAAwD;AACxD,KAAK,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,KAAK,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,SAAS,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,UAAU,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAA;CAAE,GAAG,IAAI,CAsJtE"}

package/dist/fonts/types.d.ts

@@ -6,6 +6,7 @@
  *
  * Design doc: 24-fonts.md
  */
+import type { CachedFont } from './google.ts';
 /** Configuration passed to a Google font function (e.g. `Inter({ ... })`). */
 export interface GoogleFontConfig {
     weight?: string | string[];
@@ -20,6 +21,8 @@ export interface LocalFontSrc {
     path: string;
     weight?: string;
     style?: string;
+    /** Content-hashed basename for production builds (e.g. `MyFont-Bold-a1b2c3d4.woff2`). */
+    hashedBasename?: string;
 }
 /** Configuration passed to `localFont()`. */
 export interface LocalFontConfig {
@@ -44,7 +47,16 @@ export interface FontResult {
     /** CSS custom property name when `variable` is specified (e.g. `--font-sans`). */
     variable?: string;
 }
-/** Internal representation of a font extracted during static analysis. */
+/**
+ * Internal representation of a font extracted during static analysis.
+ *
+ * `ExtractedFont` is the **registration input** to `FontPipeline.register()`.
+ * Once a font has been registered the pipeline stores a `FontEntry` (which
+ * extends `ExtractedFont` with optional resolved `@font-face` descriptors
+ * and cached binary files). External code that needs to model a font that
+ * is not yet inside a pipeline (e.g. test fixtures) should use
+ * `ExtractedFont` directly.
+ */
 export interface ExtractedFont {
     /** Unique identifier for this font instance (e.g. `inter-400-normal-latin`). */
     id: string;
@@ -82,4 +94,38 @@ export interface FontFaceDescriptor {
     display?: string;
     unicodeRange?: string;
 }
+/**
+ * The unified per-font store entry held inside `FontPipeline`.
+ *
+ * Combines what used to live in three parallel maps:
+ *
+ * - `registry: Map<string, ExtractedFont>`            → the base extracted config
+ * - `googleFontFacesMap: Map<string, FontFaceDescriptor[]>` → `faces`
+ * - `cachedFonts: CachedFont[]` (flat, family-grouped)       → `cachedFiles`
+ *
+ * `pruneFor` drops the entry **and** all of its attached state in one
+ * operation, so future code paths cannot reintroduce a TIM-824-style
+ * desync between parallel maps.
+ *
+ * See TIM-829.
+ */
+export interface FontEntry extends ExtractedFont {
+    /**
+     * Pre-resolved `@font-face` descriptors. Populated in `buildStart`
+     * (production) or lazily in `load` (dev). For local fonts the descriptors
+     * are derived from the source list at CSS-generation time and are not
+     * stored here.
+     */
+    faces?: FontFaceDescriptor[];
+    /**
+     * Downloaded Google Font binaries that back this entry's `@font-face`
+     * declarations. Empty for local fonts and in dev mode (where Google fonts
+     * are served straight from the CDN).
+     *
+     * Multiple entries that share the same `family` will hold references to
+     * the same `CachedFont` objects. The bundle emitter dedupes by
+     * `hashedFilename` so each binary is written exactly once.
+     */
+    cachedFiles?: CachedFont[];
+}
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/fonts/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC7B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oDAAoD;IACpD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/fonts/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC7B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oDAAoD;IACpD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,SAAU,SAAQ,aAAa;IAC9C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAE7B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;CAC5B"}

package/dist/fonts/virtual-modules.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Virtual module source generators for the timber-fonts plugin.
+ *
+ * The plugin exposes three virtual modules:
+ *
+ * - `@timber/fonts/google` — exports Google font loader functions. The
+ *   transform hook replaces actual call sites with static `FontResult`
+ *   objects, so this module is only loaded as a fallback (e.g. when the
+ *   transform hook hasn't run yet, or when an unknown font is referenced
+ *   via the default export proxy).
+ * - `@timber/fonts/local` — exports `localFont()` as a fallback default.
+ * - `virtual:timber-font-css/<hash>.css` — per-importer CSS module that
+ *   holds the combined `@font-face` + fallback + class CSS for every
+ *   font registered under that importer. The transform hook injects a
+ *   side-effect `import 'virtual:timber-font-css/<hash>.css'` into each
+ *   file that calls a font function, so Vite's CSS pipeline picks it up
+ *   like any other CSS asset. @vitejs/plugin-rsc's `collectCss` walks
+ *   the RSC module graph, finds the virtual module, and injects a
+ *   `<link rel="stylesheet" data-rsc-css-href=...>` via React Float —
+ *   the same machinery component CSS rides on (TIM-828).
+ *
+ *   The `.css` suffix is load-bearing: Vite's `isCSSRequest` regex matches
+ *   on file extension, so keeping it in the virtual id is how we tell
+ *   Vite's CSS pipeline (dev HMR + build asset emission) that this
+ *   module is CSS. The old `virtual:timber-font-css-register` side-effect
+ *   module, `globalThis.__timber_font_css` channel, and inline `<style>`
+ *   tag in the RSC entry were all removed in TIM-828.
+ *
+ * Design doc: 24-fonts.md
+ */
+import type { ExtractedFont } from './types.ts';
+export declare const VIRTUAL_GOOGLE = "@timber/fonts/google";
+export declare const VIRTUAL_LOCAL = "@timber/fonts/local";
+export declare const RESOLVED_GOOGLE = "\0@timber/fonts/google";
+export declare const RESOLVED_LOCAL = "\0@timber/fonts/local";
+/**
+ * Prefix used for the per-importer virtual CSS modules. The full id is
+ * `virtual:timber-font-css/<hash>.css` where `<hash>` is a short SHA-256
+ * digest of the importer path. We encode the hash (not the path itself)
+ * so the id stays filesystem-safe and opaque to downstream consumers.
+ */
+export declare const VIRTUAL_FONT_CSS_PREFIX = "virtual:timber-font-css/";
+export declare const VIRTUAL_FONT_CSS_SUFFIX = ".css";
+export declare const RESOLVED_FONT_CSS_PREFIX: string;
+export declare class VirtualFontCssIdMap {
+    private readonly map;
+    /**
+     * Return a stable virtual module id for `importer`. Calling this twice
+     * with the same importer returns the same id. Registering under an
+     * existing hash is idempotent.
+     */
+    idFor(importer: string): string;
+    /** Decode the importer from a resolved (or unresolved) virtual css id. */
+    importerFor(id: string): string | undefined;
+    /** True if `id` is any form of the virtual font css module. */
+    matches(id: string): boolean;
+    /** Drop every registered mapping. Used by tests. */
+    clear(): void;
+}
+/**
+ * Generate the virtual module source for `@timber/fonts/google`.
+ *
+ * The transform hook replaces real call sites at build time, so this
+ * module only matters as a runtime fallback. We export a Proxy default
+ * that handles any font name plus named exports for known families
+ * (for tree-shaking).
+ */
+export declare function generateGoogleVirtualModule(fonts: Iterable<ExtractedFont>): string;
+/**
+ * Generate the virtual module source for `@timber/fonts/local`.
+ *
+ * Like the google virtual module, this is a runtime fallback. The
+ * transform hook normally replaces `localFont(...)` calls with static
+ * `FontResult` objects at build time.
+ */
+export declare function generateLocalVirtualModule(): string;
+//# sourceMappingURL=virtual-modules.d.ts.map

package/dist/fonts/virtual-modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-modules.d.ts","sourceRoot":"","sources":["../../src/fonts/virtual-modules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,cAAc,yBAAyB,CAAC;AACrD,eAAO,MAAM,aAAa,wBAAwB,CAAC;AACnD,eAAO,MAAM,eAAe,2BAA2B,CAAC;AACxD,eAAO,MAAM,cAAc,0BAA0B,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAClE,eAAO,MAAM,uBAAuB,SAAS,CAAC;AAC9C,eAAO,MAAM,wBAAwB,QAAiC,CAAC;AAiBvE,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;IAEjD;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI9B;IAED,0EAA0E;IAC1E,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAS1C;IAED,+DAA+D;IAC/D,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAG3B;IAED,oDAAoD;IACpD,KAAK,IAAI,IAAI,CAEZ;CACF;AAUD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAqClF;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAcnD"}

package/dist/index.d.ts

@@ -1,198 +1,52 @@
-import type { PluginOption } from 'vite';
-import type { RouteTree } from './routing/types';
-import type { BuildManifest } from './server/build-manifest';
-import type { StartupTimer } from './utils/startup-timer';
-/** Configuration for client-side JavaScript output. */
-export interface ClientJavascriptConfig {
-    /** When true, no client JS bundles are emitted or referenced in HTML. */
-    disabled: boolean;
-    /**
-     * When `disabled` is true, still inject the Vite HMR client in dev mode
-     * so hot reloading works during development. Default: true.
-     */
-    enableHMRInDev?: boolean;
-}
-/** Fully resolved client JavaScript configuration (no optionals). */
-export interface ResolvedClientJavascript {
-    disabled: boolean;
-    enableHMRInDev: boolean;
-}
-export interface TimberUserConfig {
-    output?: 'server' | 'static';
-    /**
-     * Enable timber debug logging in production builds.
-     *
-     * When `true`, timber's own diagnostics (dev warnings, verbose logging)
-     * are active even in production mode. React stays in production mode —
-     * only timber's logs are affected.
-     *
-     * Can also be enabled at runtime via the `TIMBER_DEBUG` environment variable.
-     *
-     * Default: `false`.
-     */
-    debug?: boolean;
-    /**
-     * Control client-side JavaScript output.
-     *
-     * Boolean shorthand:
-     *   `clientJavascript: false` disables all client JS (equivalent to `{ disabled: true }`).
-     *   `clientJavascript: true` enables client JS (the default).
-     *
-     * Object form:
-     *   `clientJavascript: { disabled: true, enableHMRInDev: true }` disables client JS
-     *   in production but preserves Vite HMR in dev mode.
-     *
-     * When `disabled` is true, `enableHMRInDev` defaults to `true`.
-     * Server-side JS still runs — this only affects what is sent to the browser.
-     */
-    clientJavascript?: boolean | ClientJavascriptConfig;
-    adapter?: unknown;
-    cacheHandler?: unknown;
-    allowedOrigins?: string[];
-    csrf?: boolean;
-    limits?: {
-        actionBodySize?: string;
-        uploadBodySize?: string;
-        maxFields?: number;
-    };
-    pageExtensions?: string[];
-    /**
-     * Slow request threshold in milliseconds. Requests exceeding this emit
-     * a warning via the logger. Set to 0 to disable. Default: 3000.
-     *
-     * See design/17-logging.md §"slowRequestMs".
-     */
-    slowRequestMs?: number;
-    /** Dev-mode options. These have no effect in production builds. */
-    dev?: {
-        /** Threshold in ms to highlight slow phases in dev logging output. Default: 200. */
-        slowPhaseMs?: number;
-    };
-    /**
-     * Cookie signing configuration. See design/29-cookies.md §"Signed Cookies".
-     *
-     * Provide `secret` for a single key, or `secrets` (array) for key rotation.
-     * When `secrets` is used, index 0 is the signing key; all are tried for verification.
-     */
-    cookies?: {
-        /** Single signing secret. Shorthand for `secrets: [secret]`. */
-        secret?: string;
-        /** Array of signing secrets for key rotation. Index 0 signs; all verify. */
-        secrets?: string[];
-    };
-    /**
-     * Control Server-Timing header output.
-     *
-     * - `'detailed'` — per-phase breakdown (proxy, middleware, render). Useful
-     *   for APM / network monitoring. Exposes phase names to clients.
-     * - `'total'` — single `total;dur=N` entry. Safe to expose, gives
-     *   browser DevTools useful timing without internal details.
-     * - `false` — no Server-Timing header at all.
-     *
-     * Default: `'detailed'` in dev, `'total'` in production.
-     *
-     * This is separate from `debug` / `TIMBER_DEBUG` — it's an intentional
-     * decision to expose timing data to clients, not a side effect of debug
-     * logging.
-     */
-    serverTiming?: 'detailed' | 'total' | false;
-    /**
-     * Override the app directory location. By default, timber auto-detects
-     * `app/` at the project root, falling back to `src/app/`.
-     *
-     * Set this to a relative path from the project root (e.g. `'src/app'`)
-     * to use a custom location.
-     */
-    appDir?: string;
-    /** MDX compilation options passed to @mdx-js/rollup. See design/20-content-collections.md. */
-    mdx?: {
-        remarkPlugins?: unknown[];
-        rehypePlugins?: unknown[];
-        recmaPlugins?: unknown[];
-        remarkRehypeOptions?: Record<string, unknown>;
-    };
-    /**
-     * Built-in top-loader progress bar for client navigations.
-     * Shows an animated bar at the top of the viewport during RSC navigations.
-     * Enabled by default — set `enabled: false` to opt out.
-     *
-     * Users who want a fully custom progress indicator should disable this
-     * and use `useNavigationPending()` directly.
-     *
-     * See LOCAL-336 for design decisions.
-     */
-    topLoader?: {
-        /** Whether the top-loader is enabled. Default: true. */
-        enabled?: boolean;
-        /** Bar color. Default: '#2299DD'. */
-        color?: string;
-        /** Bar height in pixels. Default: 3. */
-        height?: number;
-        /** Show subtle glow/shadow effect. Default: true. */
-        shadow?: boolean;
-        /** Delay in ms before showing the bar (avoids flash on fast navs). Default: 0. */
-        delay?: number;
-        /** CSS z-index. Default: 1600. */
-        zIndex?: number;
-    };
-}
-/**
- * Resolve `clientJavascript` into a fully resolved config.
- */
-export declare function resolveClientJavascript(config: TimberUserConfig): ResolvedClientJavascript;
 /**
- * Shared context object passed to all sub-plugins via closure.
+ * @timber-js/app — Root entry point (public API).
  *
- * Sub-plugins communicate through this context — not through Vite's
- * plugin API or global state.
- * See design/18-build-system.md §"Shared Plugin Context".
- */
-export interface PluginContext {
-    config: TimberUserConfig;
-    /** Resolved client JavaScript configuration */
-    clientJavascript: ResolvedClientJavascript;
-    /** The scanned route tree (populated by timber-routing, consumed by timber-entries) */
-    routeTree: RouteTree | null;
-    /** Absolute path to the app/ directory */
-    appDir: string;
-    /** Absolute path to the project root */
-    root: string;
-    /** Whether the dev server is running (set by timber-root-sync in configResolved) */
-    dev: boolean;
-    /** CSS build manifest (populated by adapter after client build, null in dev) */
-    buildManifest: BuildManifest | null;
-    /** Startup timer for profiling cold start phases (active in dev, no-op in prod) */
-    timer: StartupTimer;
-}
-/**
- * Resolve the app directory. Checks (in order):
- * 1. Explicit `configAppDir` from timber.config.ts
- * 2. `<root>/app`
- * 3. `<root>/src/app`
+ * User-facing exports: timber(), defineConfig(), TimberUserConfig, Routes.
  *
- * Throws if none exist.
- */
-export declare function resolveAppDir(root: string, configAppDir?: string): string;
-/**
- * Detect config keys set in both inline (vite.config.ts) and file (timber.config.ts)
- * and warn the user. The `output` key is excluded because it defaults to 'server'
- * in createPluginContext and would always appear as an inline key.
+ * Internal helpers (PluginContext, resolveAppDir, loadTimberConfigFile,
+ * warnConfigConflicts, resolveClientJavascript) live in plugin-context.ts
+ * and are NOT re-exported here. Sub-plugins import them via relative paths.
  *
- * Returns the list of conflicting key names (for testing).
+ * Design doc: 18-build-system.md §"Plugin Architecture"
  */
-export declare function warnConfigConflicts(inline: TimberUserConfig, fileConfig: TimberUserConfig): string[];
-export declare function timber(config?: TimberUserConfig): PluginOption[];
+import type { PluginOption } from 'vite';
+import type { TimberUserConfig } from './config-types.ts';
+export type { TimberUserConfig } from './config-types.ts';
+export type { Metadata, MetadataRoute, MetadataHandler, MetadataResult } from './server/types.ts';
 /**
  * Route map interface — augmented by the generated timber-routes.d.ts.
  *
  * Each key is a route path pattern. Values have:
- *   params: shape of URL params (e.g. { id: string })
- *   searchParams: parsed type from search-params.ts, or {} if none
+ *   segmentParams: shape of URL segment params (e.g. { id: string })
+ *
+ * There is no `searchParams` member: since TIM-1343 the framework does not
+ * scan for search-param definitions, so it has nothing to type them with. A
+ * definition carries its own type to call sites through an ordinary import.
  *
  * This interface is empty by default and populated via codegen.
  * See design/09-typescript.md §"Typed Routes".
  */
 export interface Routes {
 }
+/**
+ * Type-safe helper for timber.config.ts files.
+ *
+ * A pass-through identity function that provides autocomplete and
+ * type checking for timber configuration. No runtime validation —
+ * purely a DX convenience (same pattern as Vite's defineConfig).
+ *
+ * @example
+ * ```ts
+ * // timber.config.ts
+ * import { defineConfig } from '@timber-js/app';
+ *
+ * export default defineConfig({
+ *   output: 'server',
+ *   pageExtensions: ['tsx', 'ts', 'mdx'],
+ * });
+ * ```
+ */
+export declare function defineConfig(config: TimberUserConfig): TimberUserConfig;
+export declare function timber(config?: TimberUserConfig): PluginOption[];
 export default timber;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAU,YAAY,EAAE,MAAM,MAAM,CAAC;AA0CjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAa1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAQ1D,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAElG;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,MAAM;CAAG;AAE1B;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAEvE;AAyGD,wBAAgB,MAAM,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAyXhE;eAEc,MAAM"}