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

package/dist/index.d.ts

@@ -1,296 +1,17 @@
-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;
-    /**
-     * 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;
-    };
-    /**
-     * 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.
-     */
-    /**
-     * 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;
-        /** 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;
-    /** 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;
-}
-/**
- * Resolve the app directory. Checks (in order):
- * 1. Explicit `configAppDir` from timber.config.ts
- * 2. `<root>/app`
- * 3. `<root>/src/app`
- *
- * 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.
+ * User-facing exports: timber(), defineConfig(), TimberUserConfig, Routes.
  *
- * 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'
- * 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[];
-/**
- * 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[];
+import type { PluginOption } from 'vite';
+import type { TimberUserConfig } from './config-types.js';
+export type { TimberUserConfig } from './config-types.js';
 /**
  * Route map interface — augmented by the generated timber-routes.d.ts.
  *
@@ -322,5 +43,21 @@ export interface Routes {
  * ```
  */
 export declare function defineConfig(config: TimberUserConfig): TimberUserConfig;
+/**
+ * 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[];
 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;AAyBjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAY1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;GASG;AAEH,MAAM,WAAW,MAAM;CAAG;AAE1B;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAEvE;AAgGD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAuMhE;AAED,eAAe,MAAM,CAAC"}