@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

package/dist/cookies/define-cookie.d.ts

@@ -2,28 +2,35 @@
  * defineCookie — typed cookie definitions.
  *
  * Bundles name + codec + options into a reusable CookieDefinition<T>
- * with .get(), .set(), .delete() server methods and a .useCookie() client hook.
+ * with async .getCookie(), .setCookie(), .deleteCookie() server methods
+ * and a sync .useCookie() client hook.
+ *
+ * Server methods are async to future-proof the API for v2 features
+ * (signed cookies via crypto.subtle, encrypted cookies, external stores).
  *
  * Reuses the SearchParamCodec protocol via fromSchema() bridge.
  * Validation on read returns the codec default (never throws).
  *
+ * IMPORTANT: This module must NOT have top-level value imports from either
+ * server or client modules. Server methods lazy-import request-context;
+ * useCookie() lazy-imports use-cookie. This ensures:
+ * - Client bundles don't pull in ALS/server code
+ * - RSC bundles don't pull in useSyncExternalStore/client code
+ * - Tree-shaking is not required for correctness
+ *
  * See design/29-cookies.md §"Typed Cookies with Schema Validation"
  */
-import type { CookieOptions } from '#/server/request-context.js';
+import type { CookieOptions } from '../server/request-context.js';
+import type { Codec } from '../codec.js';
 /**
  * A codec that converts between string cookie values and typed values.
- * Intentionally identical to SearchParamCodec<T>.
+ * Type alias for the shared Codec<T> protocol.
  */
-export interface CookieCodec<T> {
-    parse(value: string | string[] | undefined): T;
-    serialize(value: T): string | null;
-}
+export type CookieCodec<T> = Codec<T>;
 /** Options for defineCookie: codec + CookieOptions merged. */
-export interface DefineCookieOptions<T> extends Omit<CookieOptions, 'signed'> {
+export interface DefineCookieOptions<T> extends CookieOptions {
     /** Codec for parsing/serializing the cookie value. */
     codec: CookieCodec<T>;
-    /** Sign the cookie with HMAC-SHA256. */
-    signed?: boolean;
 }
 /** A fully typed cookie definition with server and client methods. */
 export interface CookieDefinition<T> {
@@ -34,20 +41,27 @@ export interface CookieDefinition<T> {
     /** The codec used for parsing/serializing. */
     readonly codec: CookieCodec<T>;
     /** Server: read the typed value from the current request. */
-    get(): T;
+    getCookie(): Promise<T>;
     /** Server: set the typed value on the response. */
-    set(value: T): void;
+    setCookie(value: T): Promise<void>;
     /** Server: delete the cookie. */
-    delete(): void;
+    deleteCookie(): Promise<void>;
     /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */
     useCookie(): [T, (value: T) => void, () => void];
 }
+/**
+ * Register the client cookie module. Called by the client entry to wire
+ * up the lazy reference without a top-level import.
+ *
+ * @internal — framework use only
+ */
+export declare function _registerUseCookieModule(mod: typeof import('../client/use-cookie.js')): void;
 /**
  * Define a typed cookie.
  *
  * ```ts
  * import { defineCookie } from '@timber-js/app/cookies';
- * import { fromSchema } from '@timber-js/app/search-params';
+ * import { fromSchema } from '@timber-js/app/codec';
  * import { z } from 'zod/v4';
  *
  * export const themeCookie = defineCookie('theme', {
@@ -55,6 +69,13 @@ export interface CookieDefinition<T> {
  *   httpOnly: false,
  *   maxAge: 60 * 60 * 24 * 365,
  * });
+ *
+ * // Server
+ * const theme = await themeCookie.getCookie();
+ * await themeCookie.setCookie('dark');
+ *
+ * // Client
+ * const [theme, setTheme] = themeCookie.useCookie();
  * ```
  */
 export declare function defineCookie<T>(name: string, options: DefineCookieOptions<T>): CookieDefinition<T>;

package/dist/cookies/define-cookie.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-cookie.d.ts","sourceRoot":"","sources":["../../src/cookies/define-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAMjE;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,CAAC,CAAC;IAC/C,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB,CAAC,CAAC,CAAE,SAAQ,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC;IAC3E,sDAAsD;IACtD,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACtB,wCAAwC;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAE/B,6DAA6D;IAC7D,GAAG,IAAI,CAAC,CAAC;IACT,mDAAmD;IACnD,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACpB,iCAAiC;IACjC,MAAM,IAAI,IAAI,CAAC;IAEf,4FAA4F;IAC5F,SAAS,IAAI,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC;CAClD;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,gBAAgB,CAAC,CAAC,CAAC,CA4DrB"}
+{"version":3,"file":"define-cookie.d.ts","sourceRoot":"","sources":["../../src/cookies/define-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAKlE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;AAEtC,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB,CAAC,CAAC,CAAE,SAAQ,aAAa;IAC3D,sDAAsD;IACtD,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CACvB;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAE/B,6DAA6D;IAC7D,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IACxB,mDAAmD;IACnD,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,iCAAiC;IACjC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B,4FAA4F;IAC5F,SAAS,IAAI,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC;CAClD;AAyBD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,cAAc,yBAAyB,CAAC,GAAG,IAAI,CAE5F;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,gBAAgB,CAAC,CAAC,CAAC,CAiErB"}

package/dist/cookies/index.d.ts

@@ -1,3 +1,5 @@
 export { defineCookie } from './define-cookie.js';
 export type { CookieDefinition, CookieCodec, DefineCookieOptions } from './define-cookie.js';
+export type { Codec } from '../codec.js';
+export { cookies } from '../server/request-context.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cookies/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cookies/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAG7F,YAAY,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/cookies/index.js

@@ -1,84 +1,3 @@
-import "../_chunks/als-registry-B7DbZ2hS.js";
-import { n as cookies } from "../_chunks/request-context-DIkVh_jG.js";
-import "../_chunks/ssr-data-MjmprTmO.js";
-import { t as useCookie } from "../_chunks/use-cookie-DX-l1_5E.js";
-//#region src/cookies/define-cookie.ts
-/**
-* defineCookie — typed cookie definitions.
-*
-* Bundles name + codec + options into a reusable CookieDefinition<T>
-* with .get(), .set(), .delete() server methods and a .useCookie() client hook.
-*
-* Reuses the SearchParamCodec protocol via fromSchema() bridge.
-* Validation on read returns the codec default (never throws).
-*
-* See design/29-cookies.md §"Typed Cookies with Schema Validation"
-*/
-/**
-* Define a typed cookie.
-*
-* ```ts
-* import { defineCookie } from '@timber-js/app/cookies';
-* import { fromSchema } from '@timber-js/app/search-params';
-* import { z } from 'zod/v4';
-*
-* export const themeCookie = defineCookie('theme', {
-*   codec: fromSchema(z.enum(['light', 'dark', 'system']).default('system')),
-*   httpOnly: false,
-*   maxAge: 60 * 60 * 24 * 365,
-* });
-* ```
-*/
-function defineCookie(name, options) {
-	const { codec, ...cookieOpts } = options;
-	const resolvedOptions = { ...cookieOpts };
-	return {
-		name,
-		options: resolvedOptions,
-		codec,
-		get() {
-			const jar = cookies();
-			const raw = resolvedOptions.signed ? jar.getSigned(name) : jar.get(name);
-			return codec.parse(raw);
-		},
-		set(value) {
-			const serialized = codec.serialize(value);
-			if (serialized === null) cookies().delete(name, {
-				path: resolvedOptions.path,
-				domain: resolvedOptions.domain
-			});
-			else cookies().set(name, serialized, resolvedOptions);
-		},
-		delete() {
-			cookies().delete(name, {
-				path: resolvedOptions.path,
-				domain: resolvedOptions.domain
-			});
-		},
-		useCookie() {
-			const [raw, setRaw, deleteRaw] = useCookie(name, {
-				path: resolvedOptions.path,
-				domain: resolvedOptions.domain,
-				maxAge: resolvedOptions.maxAge,
-				expires: resolvedOptions.expires,
-				sameSite: resolvedOptions.sameSite,
-				secure: resolvedOptions.secure
-			});
-			const parsed = codec.parse(raw);
-			const setTyped = (value) => {
-				const serialized = codec.serialize(value);
-				if (serialized === null) deleteRaw();
-				else setRaw(serialized);
-			};
-			return [
-				parsed,
-				setTyped,
-				deleteRaw
-			];
-		}
-	};
-}
-//#endregion
-export { defineCookie };
-
-//# sourceMappingURL=index.js.map
+import { n as cookies } from "../_chunks/request-context-CywiO4jV.js";
+import { n as defineCookie } from "../_chunks/define-cookie-B5mewxwM.js";
+export { cookies, defineCookie };

package/dist/fonts/css.d.ts

@@ -22,6 +22,7 @@ export declare function generateFontFaces(descriptors: FontFaceDescriptor[]): st
  * ```css
  * .timber-font-inter {
  *   --font-sans: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+ *   font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;
  * }
  * ```
  */

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

@@ -1 +1 @@
-{"version":3,"file":"css.d.ts","sourceRoot":"","sources":["../../src/fonts/css.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAWjE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAE3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAErF"}
+{"version":3,"file":"css.d.ts","sourceRoot":"","sources":["../../src/fonts/css.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAWjE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAE3E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAErF"}

package/dist/index.d.ts

@@ -63,23 +63,54 @@ export interface TimberUserConfig {
      * See design/17-logging.md §"slowRequestMs".
      */
     slowRequestMs?: number;
+    /**
+     * Render timeout in milliseconds. If an SSR render or RSC stream read
+     * does not complete within this duration, the render is aborted and
+     * the connection is closed. Protects against hung fetches and Suspense
+     * components that never resolve.
+     *
+     * Set to 0 to disable (not recommended in production).
+     * Default: 30000 (30 seconds).
+     *
+     * See design/02-rendering-pipeline.md §"Streaming Constraints".
+     */
+    renderTimeoutMs?: number;
+    /**
+     * Forward browser console output to the server terminal in dev mode.
+     *
+     * Sets the minimum log level to forward:
+     * - `'error'` — only `console.error`
+     * - `'warn'` — `console.error` + `console.warn` (default)
+     * - `'info'` — `console.error` + `console.warn` + `console.info`
+     * - `'none'` — disabled
+     *
+     * Does not intercept `console.log` or `console.debug` (too noisy).
+     * No effect in production builds.
+     *
+     * See TIM-513.
+     */
+    devBrowserLogs?: 'error' | 'warn' | 'info' | 'none';
     /** 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".
+     * 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.
      *
-     * 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.
+     * 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.
      */
-    cookies?: {
-        /** Single signing secret. Shorthand for `secrets: [secret]`. */
-        secret?: string;
-        /** Array of signing secrets for key rotation. Index 0 signs; all verify. */
-        secrets?: string[];
-    };
+    serverTiming?: 'detailed' | 'total' | false;
     /**
      * Override the app directory location. By default, timber auto-detects
      * `app/` at the project root, falling back to `src/app/`.
@@ -105,6 +136,75 @@ export interface TimberUserConfig {
      *
      * See LOCAL-336 for design decisions.
      */
+    /**
+     * Server action bound args encryption configuration.
+     *
+     * The RSC plugin encrypts closure variables captured by 'use server' functions
+     * using AES-256-GCM so they are opaque and tamper-proof in the Flight payload.
+     * Encryption is always enabled in production.
+     *
+     * The encryption key is auto-generated at build time and embedded in the server bundle,
+     * so all instances running the same build share the same key automatically.
+     * For rolling/blue-green deployments where multiple builds coexist, set
+     * `TIMBER_ACTIONS_ENCRYPTION_KEY` env var to share a key across builds.
+     *
+     * See design/08-forms-and-actions.md §"Security"
+     */
+    actionEncryption?: {
+        /**
+         * Disable encryption in dev mode for easier debugging of bound args.
+         * Has no effect in production — encryption is always enabled.
+         * Default: false (encryption is on in dev too).
+         */
+        disableInDev?: boolean;
+    };
+    /**
+     * Enable the React Compiler (babel-plugin-react-compiler) for automatic
+     * memoization of components and hooks at build time.
+     *
+     * - `true` — enable with default options
+     * - `{ compilationMode, target }` — enable with custom options
+     *   - `compilationMode: 'annotation'` — only compile files with `'use memo'`
+     *   - `target: '18'` — target React 18 (uses react-compiler-runtime package)
+     * - `false` or omitted — disabled (default)
+     *
+     * Uses `@vitejs/plugin-react`'s built-in `reactCompilerPreset`, which:
+     * - Applies Babel only for the compiler pass (OXC handles JSX)
+     * - Automatically scopes to client environment only
+     * - Uses `react/compiler-runtime` built into React 19
+     *
+     * Requires `babel-plugin-react-compiler` as a peer dependency.
+     */
+    reactCompiler?: boolean | {
+        compilationMode?: string;
+        target?: string;
+    };
+    /**
+     * Auto-generate sitemap.xml from the route tree.
+     *
+     * When enabled, timber walks the file-system route tree and produces a sitemap
+     * for all discoverable pages. Dynamic routes with `generateStaticParams()` are
+     * enumerated. Routes protected by `access.ts` are excluded by default.
+     *
+     * If a user-authored `sitemap.ts` or `sitemap.xml` exists at the app root,
+     * auto-generation is disabled — the user takes full control.
+     *
+     * Supports automatic pagination (sitemap index) for sites with > 50,000 URLs.
+     *
+     * See design/16-metadata.md §"Auto-generated Sitemap"
+     */
+    sitemap?: {
+        /** Must be explicitly `true` to enable auto-generation. Default: false. */
+        enabled?: boolean;
+        /** Base URL for absolute URLs in the sitemap. Required when enabled. e.g., 'https://example.com' */
+        baseUrl?: string;
+        /** Default `<changefreq>` for all entries. Optional. */
+        defaultChangeFrequency?: string;
+        /** Default `<priority>` for all entries (0.0–1.0). Optional. */
+        defaultPriority?: number;
+        /** Include routes protected by `access.ts`. Default: false. */
+        includeProtected?: boolean;
+    };
     topLoader?: {
         /** Whether the top-loader is enabled. Default: true. */
         enabled?: boolean;
@@ -119,32 +219,6 @@ export interface TimberUserConfig {
         /** CSS z-index. Default: 1600. */
         zIndex?: number;
     };
-    /**
-     * Response-level caching and deduplication.
-     *
-     * When enabled, concurrent requests to the same URL share a single render
-     * (singleflight), and recently rendered responses are reused from a short-TTL
-     * LRU cache without re-executing the RSC-to-SSR pipeline.
-     *
-     * Set to `false` to disable entirely. Default: enabled with sensible defaults.
-     *
-     * See design/31-benchmarking.md for performance context.
-     */
-    responseCache?: false | {
-        /** Maximum number of entries in the LRU cache. Default: 150. */
-        maxSize?: number;
-        /** TTL for cached entries in milliseconds. Default: 5000 (5s). */
-        ttlMs?: number;
-        /**
-         * When true (default), requests with Cookie or Authorization headers
-         * bypass the cache entirely. This prevents sharing user-specific
-         * responses across requests.
-         *
-         * Set to false to cache all responses regardless of auth state.
-         * Only do this if your pages are truly public and don't vary by user.
-         */
-        publicOnly?: boolean;
-    };
 }
 /**
  * Resolve `clientJavascript` into a fully resolved config.
@@ -171,10 +245,10 @@ export interface PluginContext {
     dev: boolean;
     /** CSS build manifest (populated by adapter after client build, null in dev) */
     buildManifest: BuildManifest | null;
+    /** Per-build deployment ID for version skew detection (null in dev) */
+    deploymentId: string | null;
     /** Startup timer for profiling cold start phases (active in dev, no-op in prod) */
     timer: StartupTimer;
-    /** URL path to font CSS file, set by timber-fonts when fonts are registered */
-    fontCssUrl?: string;
 }
 /**
  * Resolve the app directory. Checks (in order):
@@ -185,6 +259,14 @@ export interface PluginContext {
  * Throws if none exist.
  */
 export declare function resolveAppDir(root: string, configAppDir?: string): string;
+/**
+ * Load timber.config.ts (or .js, .mjs) from the project root.
+ * Returns the config object or null if no config file is found.
+ *
+ * Uses require() which works for ESM modules on Node 22.12+.
+ * This keeps timber() synchronous — no async config loading needed.
+ */
+export declare function loadTimberConfigFile(root: string): TimberUserConfig | null;
 /**
  * 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'
@@ -193,12 +275,27 @@ export declare function resolveAppDir(root: string, configAppDir?: string): stri
  * Returns the list of conflicting key names (for testing).
  */
 export declare function warnConfigConflicts(inline: TimberUserConfig, fileConfig: TimberUserConfig): string[];
+/**
+ * Create the timber Vite plugin array.
+ *
+ * Loads timber.config.ts and all dependencies synchronously before
+ * constructing the plugin array. This ensures ALL plugins — including
+ * the RSC plugin and React Compiler — see the fully merged config
+ * (inline + file-based). No async, no deferred config, no stale reads.
+ *
+ * Requires Node >= 22.12 for synchronous require() of ESM modules
+ * (@vitejs/plugin-rsc is ESM-only).
+ *
+ * Previous versions used async loading and deferred config merging,
+ * causing file-based config for reactCompiler, actionEncryption, and
+ * output mode to be silently ignored. See TIM-451.
+ */
 export declare function timber(config?: TimberUserConfig): PluginOption[];
 /**
  * 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 })
+ *   segmentParams: shape of URL segment params (e.g. { id: string })
  *   searchParams: parsed type from search-params.ts, or {} if none
  *
  * This interface is empty by default and populated via codegen.
@@ -206,5 +303,24 @@ export declare function timber(config?: TimberUserConfig): PluginOption[];
  */
 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 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":"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"}