@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.41

package/dist/index.d.ts

@@ -63,23 +63,39 @@ 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;
     /** 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 +121,49 @@ 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;
+    };
     topLoader?: {
         /** Whether the top-loader is enabled. Default: true. */
         enabled?: boolean;
@@ -119,32 +178,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,6 +204,8 @@ 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;
 }
@@ -183,6 +218,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'
@@ -191,6 +234,21 @@ 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.
@@ -204,5 +262,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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"}