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

package/dist/client/use-segment-params.d.ts

@@ -0,0 +1,55 @@
+/**
+ * useParams() — client-side hook for accessing route params.
+ *
+ * Returns the dynamic route parameters for the current URL.
+ * When called with a route pattern argument, TypeScript narrows
+ * the return type to the exact params shape for that route.
+ *
+ * Two layers of type narrowing work together:
+ * 1. The generic overload here uses the Routes interface directly —
+ *    `useParams<R>()` returns `Routes[R]['segmentParams']`.
+ * 2. Build-time codegen generates per-route string-literal overloads
+ *    in the .d.ts file for IDE autocomplete (see routing/codegen.ts).
+ *
+ * When the Routes interface is empty (no codegen yet), the generic
+ * overload has `keyof Routes = never`, so only the fallback matches.
+ *
+ * One unconditional read of ParamsContext, on every side (TIM-1425):
+ *
+ * - In the browser, `PayloadRoot` publishes the payload's params above the
+ *   merge point on every render path. Params update atomically with the RSC
+ *   tree — no timing gap (TIM-1294, TIM-1297).
+ * - During SSR, the wrapper chain mounts the same `PayloadRoot`, fed the
+ *   `params` half of `splitPayloadRoot(root)` — the identical derivation
+ *   the browser performs at hydration (TIM-1424).
+ * - In the RSC environment, this module is never evaluated — the shims plugin
+ *   resolves next/navigation to navigation-rsc.ts (TIM-1420).
+ * - Called outside a component entirely, React itself throws its
+ *   invalid-hook-call error.
+ *
+ * The module-level subscribe/notify machinery and the `currentParams`
+ * snapshot that used to back a fourth fallback tier are gone (TIM-1425):
+ * the provider is unconditional on every render path, so nothing read them.
+ *
+ * Design doc: design/09-typescript.md §"Typed Routes"
+ */
+import type { CoercedParams } from '../shared/param-value.ts';
+import type { Routes } from '../index.ts';
+/**
+ * Read the current route's dynamic params.
+ *
+ * The optional `_route` argument exists only for TypeScript narrowing —
+ * it does not affect the runtime return value.
+ *
+ * Throws when no `PayloadRoot` is above the caller (a component rendered
+ * outside the timber app — in tests, render inside the timber providers).
+ *
+ * @overload Typed — when a known segment path is passed, returns the
+ *   exact params shape from the generated Routes interface.
+ * @overload Fallback — returns the generic params record.
+ */
+export declare function useSegmentParams<R extends keyof Routes>(segmentPath: R): Routes[R] extends {
+    segmentParams: infer P;
+} ? P : CoercedParams;
+export declare function useSegmentParams(segmentPath?: string): CoercedParams;
+//# sourceMappingURL=use-segment-params.d.ts.map

package/dist/client/use-segment-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-segment-params.d.ts","sourceRoot":"","sources":["../../src/client/use-segment-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI1C;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,MAAM,EACrD,WAAW,EAAE,CAAC,GACb,MAAM,CAAC,CAAC,CAAC,SAAS;IAAE,aAAa,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,aAAa,CAAC;AACpE,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC"}

package/dist/codec.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @timber-js/app/codec — Shared codec protocol and Standard Schema bridge.
+ *
+ * The canonical import path for codec primitives shared across search params,
+ * route params, and cookies.
+ *
+ * Design doc: design/23a-search-params-triage.md §"Unify Codec<T> type"
+ */
+/**
+ * A codec that converts between string values and typed values.
+ *
+ * The canonical protocol shared across search params, cookies, and
+ * any future timber feature that needs string ↔ typed conversion.
+ */
+export interface Codec<T> {
+    /** String → typed value. Receives undefined when the value is absent. */
+    parse(value: string | string[] | undefined): T;
+    /** Typed value → string. Return null to omit/clear. */
+    serialize(value: T): string | null;
+}
+/**
+ * Marker interface for codecs designed for catch-all segments (`[...slug]`).
+ * These codecs expect `string[]` input from the router.
+ */
+export interface CatchAllCodec<T> extends Codec<T> {
+    readonly __catchAll: true;
+}
+/**
+ * Marker interface for codecs designed for optional catch-all segments (`[[...slug]]`).
+ * These codecs expect `string[] | undefined` input from the router.
+ */
+export interface OptionalCatchAllCodec<T> extends Codec<T> {
+    readonly __catchAll: true;
+    readonly __optional: true;
+}
+/**
+ * Recursive JSON-serializable type. The canonical definition for data that
+ * can safely cross the RSC → client boundary.
+ *
+ * Previously exported from both @timber-js/app/server and @timber-js/app/client.
+ * Moved here so there is exactly one canonical import path.
+ */
+export type JsonSerializable = string | number | boolean | null | JsonSerializable[] | {
+    [key: string]: JsonSerializable;
+};
+export { fromArraySchema, } from './schema-bridge.ts';
+export type { StandardSchemaV1, StandardSchemaResult } from './schema-bridge.ts';
+export declare const codec: {
+    readonly string: {
+        parse(value: string | string[] | undefined): string;
+        serialize(value: string): string | null;
+    };
+    readonly integer: {
+        parse(value: string | string[] | undefined): number;
+        serialize(value: number): string | null;
+    };
+    readonly slug: {
+        parse(value: string | string[] | undefined): string;
+        serialize(value: string): string | null;
+    };
+    readonly stringArray: {
+        __catchAll: true;
+        parse(value: string | string[] | undefined): string[];
+        serialize(value: string[]): string | null;
+    };
+    readonly catchAll: <T>(inner: Codec<T>) => CatchAllCodec<T[]>;
+    readonly optionalCatchAll: <T>(inner: Codec<T>) => OptionalCatchAllCodec<T[] | undefined>;
+};
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,yEAAyE;IACzE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,CAAC,CAAC;IAC/C,uDAAuD;IACvD,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,gBAAgB,EAAE,GAClB;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAA;CAAE,CAAC;AAIxC,OAAO,EAEL,eAAe,GAIhB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAIjF,eAAO,MAAM,KAAK;;qBAED,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM;yBAGlC,MAAM,GAAG,MAAM,GAAG,IAAI;;;qBAM1B,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM;yBAQlC,MAAM,GAAG,MAAM,GAAG,IAAI;;;qBAM1B,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM;yBAOlC,MAAM,GAAG,MAAM,GAAG,IAAI;;;;qBAO1B,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE;yBAIpC,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI;;wBAKlC,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,KAAG,aAAa,CAAC,CAAC,EAAE,CAAC;gCAgB/B,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,KAAG,qBAAqB,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC;CAepE,CAAC"}

package/dist/codec.js

@@ -0,0 +1,76 @@
+import { t as fromArraySchema } from "./_chunks/schema-bridge-C83xa9lT.js";
+//#region src/codec.ts
+var codec = {
+	string: {
+		parse(value) {
+			return Array.isArray(value) ? value.join("/") : value ?? "";
+		},
+		serialize(value) {
+			return value;
+		}
+	},
+	integer: {
+		parse(value) {
+			const str = Array.isArray(value) ? value[0] : value;
+			if (!str || !/^(?:0|-?[1-9]\d*)$/.test(str)) throw new Error(`Expected integer, got '${str}'`);
+			const n = Number(str);
+			if (!Number.isSafeInteger(n)) throw new Error(`Expected integer, got '${str}'`);
+			return n;
+		},
+		serialize(value) {
+			return String(value);
+		}
+	},
+	slug: {
+		parse(value) {
+			const str = Array.isArray(value) ? value[0] : value;
+			if (!str || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(str)) throw new Error(`Invalid slug: '${str}'`);
+			return str;
+		},
+		serialize(value) {
+			return value;
+		}
+	},
+	stringArray: {
+		__catchAll: true,
+		parse(value) {
+			if (Array.isArray(value)) return value;
+			return value ? [value] : [];
+		},
+		serialize(value) {
+			return value.join("/");
+		}
+	},
+	catchAll(inner) {
+		return {
+			__catchAll: true,
+			parse(value) {
+				const arr = Array.isArray(value) ? value : value !== void 0 ? [value] : [];
+				if (arr.length === 0) throw new Error("Catch-all segment requires at least one value");
+				return arr.map((item) => inner.parse(item));
+			},
+			serialize(value) {
+				return value.map((item) => inner.serialize(item)).join("/");
+			}
+		};
+	},
+	optionalCatchAll(inner) {
+		return {
+			__catchAll: true,
+			__optional: true,
+			parse(value) {
+				const arr = Array.isArray(value) ? value : value !== void 0 ? [value] : [];
+				if (arr.length === 0) return void 0;
+				return arr.map((item) => inner.parse(item));
+			},
+			serialize(value) {
+				if (!value || value.length === 0) return null;
+				return value.map((item) => inner.serialize(item)).join("/");
+			}
+		};
+	}
+};
+//#endregion
+export { codec, fromArraySchema };
+
+//# sourceMappingURL=codec.js.map

package/dist/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","names":[],"sources":["../src/codec.ts"],"sourcesContent":["/**\n * @timber-js/app/codec — Shared codec protocol and Standard Schema bridge.\n *\n * The canonical import path for codec primitives shared across search params,\n * route params, and cookies.\n *\n * Design doc: design/23a-search-params-triage.md §\"Unify Codec<T> type\"\n */\n\n// ─── Codec protocol ──────────────────────────────────────────────────────\n\n/**\n * A codec that converts between string values and typed values.\n *\n * The canonical protocol shared across search params, cookies, and\n * any future timber feature that needs string ↔ typed conversion.\n */\nexport interface Codec<T> {\n  /** String → typed value. Receives undefined when the value is absent. */\n  parse(value: string | string[] | undefined): T;\n  /** Typed value → string. Return null to omit/clear. */\n  serialize(value: T): string | null;\n}\n\n/**\n * Marker interface for codecs designed for catch-all segments (`[...slug]`).\n * These codecs expect `string[]` input from the router.\n */\nexport interface CatchAllCodec<T> extends Codec<T> {\n  readonly __catchAll: true;\n}\n\n/**\n * Marker interface for codecs designed for optional catch-all segments (`[[...slug]]`).\n * These codecs expect `string[] | undefined` input from the router.\n */\nexport interface OptionalCatchAllCodec<T> extends Codec<T> {\n  readonly __catchAll: true;\n  readonly __optional: true;\n}\n\n/**\n * Recursive JSON-serializable type. The canonical definition for data that\n * can safely cross the RSC → client boundary.\n *\n * Previously exported from both @timber-js/app/server and @timber-js/app/client.\n * Moved here so there is exactly one canonical import path.\n */\nexport type JsonSerializable =\n  | string\n  | number\n  | boolean\n  | null\n  | JsonSerializable[]\n  | { [key: string]: JsonSerializable };\n\n// ─── Standard Schema bridge ──────────────────────────────────────────────\n\nexport {\n  // fromSchema,\n  fromArraySchema,\n  // validateSync,\n  // isStandardSchema,\n  // isCodec,\n} from './schema-bridge.ts';\nexport type { StandardSchemaV1, StandardSchemaResult } from './schema-bridge.ts';\n\n// ─── Built-in segment param codecs ───────────────────────────────────────\n\nexport const codec = {\n  string: {\n    parse(value: string | string[] | undefined): string {\n      return Array.isArray(value) ? value.join('/') : (value ?? '');\n    },\n    serialize(value: string): string | null {\n      return value;\n    },\n  } satisfies Codec<string>,\n\n  integer: {\n    parse(value: string | string[] | undefined): number {\n      const str = Array.isArray(value) ? value[0] : value;\n      if (!str || !/^(?:0|-?[1-9]\\d*)$/.test(str))\n        throw new Error(`Expected integer, got '${str}'`);\n      const n = Number(str);\n      if (!Number.isSafeInteger(n)) throw new Error(`Expected integer, got '${str}'`);\n      return n;\n    },\n    serialize(value: number): string | null {\n      return String(value);\n    },\n  } satisfies Codec<number>,\n\n  slug: {\n    parse(value: string | string[] | undefined): string {\n      const str = Array.isArray(value) ? value[0] : value;\n      if (!str || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(str)) {\n        throw new Error(`Invalid slug: '${str}'`);\n      }\n      return str;\n    },\n    serialize(value: string): string | null {\n      return value;\n    },\n  } satisfies Codec<string>,\n\n  stringArray: {\n    __catchAll: true as const,\n    parse(value: string | string[] | undefined): string[] {\n      if (Array.isArray(value)) return value;\n      return value ? [value] : [];\n    },\n    serialize(value: string[]): string | null {\n      return value.join('/');\n    },\n  } satisfies CatchAllCodec<string[]>,\n\n  catchAll<T>(inner: Codec<T>): CatchAllCodec<T[]> {\n    return {\n      __catchAll: true as const,\n      parse(value: string | string[] | undefined): T[] {\n        const arr = Array.isArray(value) ? value : value !== undefined ? [value] : [];\n        if (arr.length === 0) {\n          throw new Error('Catch-all segment requires at least one value');\n        }\n        return arr.map((item) => inner.parse(item));\n      },\n      serialize(value: T[]): string | null {\n        return value.map((item) => inner.serialize(item)).join('/');\n      },\n    };\n  },\n\n  optionalCatchAll<T>(inner: Codec<T>): OptionalCatchAllCodec<T[] | undefined> {\n    return {\n      __catchAll: true as const,\n      __optional: true as const,\n      parse(value: string | string[] | undefined): T[] | undefined {\n        const arr = Array.isArray(value) ? value : value !== undefined ? [value] : [];\n        if (arr.length === 0) return undefined;\n        return arr.map((item) => inner.parse(item));\n      },\n      serialize(value: T[] | undefined): string | null {\n        if (!value || value.length === 0) return null;\n        return value.map((item) => inner.serialize(item)).join('/');\n      },\n    };\n  },\n} as const;\n"],"mappings":";;AAqEA,IAAa,QAAQ;CACnB,QAAQ;EACN,MAAM,OAA8C;GAClD,OAAO,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK,GAAG,IAAK,SAAS;EAC5D;EACA,UAAU,OAA8B;GACtC,OAAO;EACT;CACF;CAEA,SAAS;EACP,MAAM,OAA8C;GAClD,MAAM,MAAM,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK;GAC9C,IAAI,CAAC,OAAO,CAAC,qBAAqB,KAAK,GAAG,GACxC,MAAM,IAAI,MAAM,0BAA0B,IAAI,EAAE;GAClD,MAAM,IAAI,OAAO,GAAG;GACpB,IAAI,CAAC,OAAO,cAAc,CAAC,GAAG,MAAM,IAAI,MAAM,0BAA0B,IAAI,EAAE;GAC9E,OAAO;EACT;EACA,UAAU,OAA8B;GACtC,OAAO,OAAO,KAAK;EACrB;CACF;CAEA,MAAM;EACJ,MAAM,OAA8C;GAClD,MAAM,MAAM,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK;GAC9C,IAAI,CAAC,OAAO,CAAC,6BAA6B,KAAK,GAAG,GAChD,MAAM,IAAI,MAAM,kBAAkB,IAAI,EAAE;GAE1C,OAAO;EACT;EACA,UAAU,OAA8B;GACtC,OAAO;EACT;CACF;CAEA,aAAa;EACX,YAAY;EACZ,MAAM,OAAgD;GACpD,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO;GACjC,OAAO,QAAQ,CAAC,KAAK,IAAI,CAAC;EAC5B;EACA,UAAU,OAAgC;GACxC,OAAO,MAAM,KAAK,GAAG;EACvB;CACF;CAEA,SAAY,OAAqC;EAC/C,OAAO;GACL,YAAY;GACZ,MAAM,OAA2C;IAC/C,MAAM,MAAM,MAAM,QAAQ,KAAK,IAAI,QAAQ,UAAU,KAAA,IAAY,CAAC,KAAK,IAAI,CAAC;IAC5E,IAAI,IAAI,WAAW,GACjB,MAAM,IAAI,MAAM,+CAA+C;IAEjE,OAAO,IAAI,KAAK,SAAS,MAAM,MAAM,IAAI,CAAC;GAC5C;GACA,UAAU,OAA2B;IACnC,OAAO,MAAM,KAAK,SAAS,MAAM,UAAU,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG;GAC5D;EACF;CACF;CAEA,iBAAoB,OAAyD;EAC3E,OAAO;GACL,YAAY;GACZ,YAAY;GACZ,MAAM,OAAuD;IAC3D,MAAM,MAAM,MAAM,QAAQ,KAAK,IAAI,QAAQ,UAAU,KAAA,IAAY,CAAC,KAAK,IAAI,CAAC;IAC5E,IAAI,IAAI,WAAW,GAAG,OAAO,KAAA;IAC7B,OAAO,IAAI,KAAK,SAAS,MAAM,MAAM,IAAI,CAAC;GAC5C;GACA,UAAU,OAAuC;IAC/C,IAAI,CAAC,SAAS,MAAM,WAAW,GAAG,OAAO;IACzC,OAAO,MAAM,KAAK,SAAS,MAAM,UAAU,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG;GAC5D;EACF;CACF;AACF"}

package/dist/config-types.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Timber configuration types.
+ *
+ * Extracted to a shared file so both the public entry point (index.ts)
+ * and internal plugin-context.ts can import them without circular deps.
+ */
+/** 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;
+}
+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;
+    allowedOrigins?: string[];
+    csrf?: boolean;
+    limits?: {
+        actionBodySize?: string;
+        uploadBodySize?: string;
+        maxFields?: number;
+    };
+    forms?: {
+        /**
+         * Strip sensitive fields (passwords, tokens, CVV, SSN, etc.) from the
+         * `submittedValues` echoed back on validation failure.
+         *
+         * Applied to both the with-JS (`createActionClient`) and no-JS (form POST
+         * re-render) paths. Safe-by-default: the built-in deny-list is active
+         * unless you explicitly opt out.
+         *
+         * - `true` / omitted — use the built-in deny-list (default, recommended).
+         * - `false` — do not strip anything. Dev convenience only; never do this
+         *   in production — plaintext passwords end up in `defaultValue` attributes,
+         *   browser history, proxy logs, and the back-forward cache.
+         * - `string[]` — additional field names to strip, merged with the built-in list.
+         *
+         * The built-in list matches (case-insensitive, substring match on
+         * normalized names) the following patterns: password / passwd / pwd,
+         * secret, apiKey, accessToken, refreshToken, cvv, cvc, cardNumber,
+         * cardCvc, ssn, socialSecurityNumber, otp, totp, mfaCode, twoFactorCode,
+         * privateKey — plus exact match on `token` (exact-only to avoid
+         * false positives on `csrfToken`).
+         *
+         * **Function predicates are not supported at the global level** because
+         * `timber.config.ts` is JSON-serialized into the runtime config and
+         * functions cannot cross that boundary. For custom predicates, use
+         * the per-action override: `createActionClient({ stripSensitiveFields:
+         * (name) => ... })` (functions are supported at the per-action level
+         * since `createActionClient` runs in the same module graph as user code).
+         *
+         * See TIM-816.
+         */
+        stripSensitiveFields?: boolean | readonly string[];
+    };
+    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.
+     *
+     * Setting 0 uses a 120-second safety ceiling rather than disabling
+     * the timeout entirely.
+     * 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: `'total'` in dev and production. Detailed mode logs a
+     * stream-lifecycle line per request, so it is opt-in everywhere.
+     *
+     * 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;
+    /**
+     * Build-time performance budgets. When exceeded, the build report emits
+     * a warning (does not fail the build).
+     */
+    budget?: {
+        /** Warn when any route's first-load JS (gzip) exceeds this many bytes. */
+        firstLoadJs?: number;
+    };
+    /**
+     * 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/Markdown compilation options passed to vite-plugin-satteri.
+     *
+     * Satteri's plugin API is visitor-based (`defineMdastPlugin` /
+     * `defineHastPlugin` from the `satteri` package) — unified
+     * remark/rehype plugins are not supported.
+     *
+     * Set to `false` to disable timber's MDX support entirely — even when a
+     * `content/` directory exists. Use this when registering your own MDX
+     * compiler (e.g. `@mdx-js/rollup` for the unified pipeline) directly in
+     * `vite.config.ts`.
+     *
+     * See design/20-content-collections.md.
+     */
+    mdx?: false | {
+        /** MDAST-stage plugins (created with satteri's `defineMdastPlugin`). */
+        mdastPlugins?: unknown[];
+        /** HAST-stage plugins (created with satteri's `defineHastPlugin`). */
+        hastPlugins?: unknown[];
+        /**
+         * Parser feature toggles. Defaults: `gfm: true`, `frontmatter: true`,
+         * everything else (math, directive, wikilinks, …) off.
+         */
+        features?: Record<string, unknown>;
+    };
+    /**
+     * 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 for automatic memoization of components
+     * and hooks at build time.
+     *
+     * - `true` or omitted — enabled with default options (default)
+     * - `{ 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` — disabled
+     *
+     * Uses `@vitejs/plugin-react`'s native OXC-based compiler path
+     * (`react({ compiler: ... })`), which handles JSX and compilation in
+     * a single Rust pass — no Babel required.
+     *
+     * Note: enabling the compiler disables React Fast Refresh. HMR still
+     * works (modules re-evaluate on save) but component state is not
+     * preserved across edits.
+     *
+     * `oxc-transform-react` is included as a direct 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 `generateStaticSegmentParams()` 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;
+    };
+    /**
+     * Override the build output directory.
+     *
+     * The resolved path is relative to the project root. Timber config
+     * takes precedence over Vite's `build.outDir`. If neither is set,
+     * defaults to `.timber/dist`.
+     *
+     * @example
+     * ```ts
+     * // timber.config.ts
+     * export default defineConfig({
+     *   buildDir: 'build',        // outputs to <root>/build/
+     *   buildDir: '.timber/dist', // default
+     * });
+     * ```
+     */
+    buildDir?: string;
+    /**
+     * Enable the client-side segment cache for partial navigation.
+     *
+     * When enabled, the router serializes the mounted segment tree into an
+     * `X-Timber-State-Tree` header on every client navigation. The server
+     * skips re-rendering unchanged sync layouts and sends a partial RSC
+     * payload. The client merges the partial payload with its cached segments.
+     *
+     * When disabled (the default), every navigation gets a full RSC payload.
+     *
+     * This is a performance optimization only — not a security boundary.
+     * The server always runs all `access.ts` files regardless.
+     *
+     * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+     */
+    clientSegmentCache?: boolean;
+    /**
+     * Cache behavior configuration.
+     */
+    cache?: {
+        /**
+         * Promote the runtime-tier cache.component key-discipline warning to a
+         * hard error. When true, a cached component that reads request context
+         * (cookies, headers, searchParams) during a capture render throws
+         * instead of logging — the tainted payload is never cached.
+         *
+         * Default: false (structured error-level diagnostic, rate-limited per
+         * component). Recommended true for any app serving authenticated content.
+         *
+         * See design/45-cache-lifetimes.md §Enforcement.
+         */
+        strictKeyDiscipline?: 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;
+    };
+}
+//# sourceMappingURL=config-types.d.ts.map

package/dist/config-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-types.d.ts","sourceRoot":"","sources":["../src/config-types.ts"],"names":[],"mappings":"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"}

package/dist/config-validation.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Config validation — validates timber.config.ts at startup.
+ *
+ * Runs in the plugin's configResolved hook (once, at startup/build).
+ * Each check produces a clear error message with the invalid value,
+ * what's expected, and how to fix it.
+ *
+ * Design doc: 18-build-system.md
+ */
+import type { TimberUserConfig } from './config-types.ts';
+export interface ConfigError {
+    field: string;
+    message: string;
+    value?: unknown;
+    suggestion?: string;
+    /**
+     * Refuse to start rather than log. Most config errors only warn — Vite may
+     * still work partially — but a fatal one would leave a security check
+     * running on a value the developer did not mean (`allowedOrigins`).
+     */
+    fatal?: true;
+}
+/**
+ * Validate a TimberUserConfig object.
+ *
+ * Returns an array of errors. Empty array means the config is valid.
+ * Does not throw — the caller decides how to surface errors.
+ */
+export declare function validateConfig(config: TimberUserConfig): ConfigError[];
+/**
+ * Format config errors for terminal output. Pass `color: false` for text
+ * that goes into a thrown `Error` — escapes there reach CI logs and the
+ * Vite overlay as raw bytes.
+ */
+export declare function formatConfigErrors(errors: ConfigError[], { color }?: {
+    color?: boolean;
+}): string;
+/**
+ * Surface config errors at startup: non-fatal ones are written to stderr
+ * (Vite may still work partially, and the message guides the fix); fatal
+ * ones then stop startup with a thrown error. Non-fatal errors are written
+ * first so a fatal one does not hide them.
+ */
+export declare function reportConfigErrors(errors: ConfigError[], write?: (text: string) => void): void;
+/**
+ * Add timber-specific context to an error message that references virtual modules.
+ *
+ * If the error message contains a `virtual:timber-*` ID, appends a
+ * human-readable explanation. Does not replace the original message.
+ */
+export declare function addVirtualModuleContext(errorMessage: string): string;
+interface PeerDepResult {
+    name: string;
+    status: 'ok' | 'missing';
+}
+/**
+ * Check that required peer dependencies are installed.
+ *
+ * Uses require.resolve with a try/catch — no fs scanning.
+ * Returns only the missing packages.
+ */
+export declare function checkPeerDependencies(projectRoot: string): PeerDepResult[];
+/**
+ * Format missing peer dependencies as an actionable warning.
+ */
+export declare function formatMissingPeers(results: PeerDepResult[]): string;
+export {};
+//# sourceMappingURL=config-validation.d.ts.map

package/dist/config-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-validation.d.ts","sourceRoot":"","sources":["../src/config-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAK1D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,IAAI,CAAC;CACd;AAsCD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,EAAE,CAuLtE;AA+ED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EAAE,EACrB,EAAE,KAAY,EAAE,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GACzC,MAAM,CAkBR;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EAAE,EACrB,KAAK,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAA2C,GACnE,IAAI,CAKN;AAeD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAOpE;AAID,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,IAAI,GAAG,SAAS,CAAC;CAC1B;AAOD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,EAAE,CAmB1E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAgBnE"}