@timber-js/app 0.2.0-alpha.10 → 0.2.0-alpha.100

package/dist/client/state.d.ts

@@ -3,7 +3,7 @@
  *
  * ALL mutable module-level state that must have singleton semantics across
  * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,
- * use-params.ts, use-search-params.ts, unload-guard.ts) import from this file
+ * use-segment-params.ts, use-search-params.ts, unload-guard.ts) import from this file
  * and re-export thin wrapper functions.
  *
  * Why: In Vite dev, a module is instantiated separately if reached via different

package/dist/client/top-loader.d.ts

@@ -3,11 +3,11 @@
  *
  * Shows an animated progress bar at the top of the viewport while an RSC
  * navigation is in flight. Injected automatically by the framework into
- * TransitionRoot — users never render this component directly.
+ * NavigationRoot — users never render this component directly.
  *
  * Configuration is via timber.config.ts `topLoader` key. Enabled by default.
  * Users who want a fully custom progress indicator disable the built-in one
- * (`topLoader: { enabled: false }`) and use `useNavigationPending()` directly.
+ * (`topLoader: { enabled: false }`) and use `usePendingNavigation()` directly.
  *
  * Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%
  * width over ~30s using ease-out timing. When navigation completes, the bar
@@ -21,7 +21,7 @@
  * stays invisible during the delay period. If navigation finishes before the
  * delay, the bar was never visible so the finish transition is also invisible.
  *
- * See design/19-client-navigation.md §"useNavigationPending()"
+ * See design/19-client-navigation.md §"usePendingNavigation()"
  * See LOCAL-336 for design decisions.
  */
 export interface TopLoaderConfig {
@@ -31,7 +31,7 @@ export interface TopLoaderConfig {
     color?: string;
     /** Bar height in pixels. Default: 3. */
     height?: number;
-    /** Show subtle glow/shadow effect. Default: true. */
+    /** Show subtle glow/shadow effect. Default: false. */
     shadow?: boolean;
     /** Delay in ms before showing the bar. Default: 0. */
     delay?: number;
@@ -39,7 +39,7 @@ export interface TopLoaderConfig {
     zIndex?: number;
 }
 /**
- * Internal top-loader component. Injected by TransitionRoot.
+ * Internal top-loader component. Injected by NavigationRoot.
  *
  * Reads pending navigation state from PendingNavigationContext.
  * Phase transitions are derived synchronously during render:

package/dist/client/top-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"top-loader.d.ts","sourceRoot":"","sources":["../../src/client/top-loader.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA2F7F"}
+{"version":3,"file":"top-loader.d.ts","sourceRoot":"","sources":["../../src/client/top-loader.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAuG7F"}

package/dist/client/use-cookie.d.ts

@@ -22,6 +22,14 @@ export interface ClientCookieOptions {
     secure?: boolean;
 }
 export type CookieSetter = (value: string, options?: ClientCookieOptions) => void;
+/**
+ * Notify useCookie subscribers that a cookie value changed.
+ * Called by defineCookie's imperative client .set()/.delete() methods
+ * so mounted useCookie() consumers re-render.
+ *
+ * @internal — framework use only
+ */
+export declare function notifyCookieChange(name: string): void;
 /**
  * Reactive hook for reading/writing a client-side cookie.
  *

package/dist/client/use-cookie.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-cookie.d.ts","sourceRoot":"","sources":["../../src/client/use-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,yCAAyC;IACzC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,IAAI,CAAC;AA0ClF;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,mBAAmB,GACnC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC,CAmChF"}
+{"version":3,"file":"use-cookie.d.ts","sourceRoot":"","sources":["../../src/client/use-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,yCAAyC;IACzC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAwClF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAErD;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,mBAAmB,GACnC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC,CAoDhF"}

package/dist/client/use-link-status.d.ts

@@ -1,5 +1,5 @@
 export interface LinkStatus {
-    pending: boolean;
+    isPending: boolean;
 }
 /**
  * React context provided by <Link>. Holds the pending status
@@ -7,10 +7,10 @@ export interface LinkStatus {
  */
 export declare const LinkStatusContext: import("react").Context<LinkStatus>;
 /**
- * Returns `{ pending: true }` while the nearest parent `<Link>` component's
+ * Returns `{ isPending: true }` while the nearest parent `<Link>` component's
  * navigation is in flight. Must be used inside a `<Link>` component's children.
  *
- * Unlike `useNavigationPending()` which is global, this hook is scoped to
+ * Unlike `usePendingNavigation()` which is global, this hook is scoped to
  * the nearest parent `<Link>` — only the link the user clicked shows pending.
  *
  * ```tsx
@@ -18,8 +18,8 @@ export declare const LinkStatusContext: import("react").Context<LinkStatus>;
  * import { Link, useLinkStatus } from '@timber-js/app/client'
  *
  * function Hint() {
- *   const { pending } = useLinkStatus()
- *   return <span className={pending ? 'opacity-50' : ''} />
+ *   const { isPending } = useLinkStatus()
+ *   return <span className={isPending ? 'opacity-50' : ''} />
  * }
  *
  * export function NavLink({ href, children }) {

package/dist/client/use-link-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-link-status.d.ts","sourceRoot":"","sources":["../../src/client/use-link-status.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,qCAAgD,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C"}
+{"version":3,"file":"use-link-status.d.ts","sourceRoot":"","sources":["../../src/client/use-link-status.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,qCAAkD,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C"}

package/dist/client/{use-navigation-pending.d.ts → use-pending-navigation.d.ts}

@@ -10,10 +10,10 @@
  *
  * ```tsx
  * 'use client'
- * import { useNavigationPending } from '@timber-js/app/client'
+ * import { usePendingNavigation } from '@timber-js/app/client'
  *
  * export function NavBar() {
- *   const isPending = useNavigationPending()
+ *   const isPending = usePendingNavigation()
  *   return (
  *     <nav className={isPending ? 'opacity-50' : ''}>
  *       <Link href="/dashboard">Dashboard</Link>
@@ -22,5 +22,5 @@
  * }
  * ```
  */
-export declare function useNavigationPending(): boolean;
-//# sourceMappingURL=use-navigation-pending.d.ts.map
+export declare function usePendingNavigation(): boolean;
+//# sourceMappingURL=use-pending-navigation.d.ts.map

package/dist/client/use-pending-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-pending-navigation.d.ts","sourceRoot":"","sources":["../../src/client/use-pending-navigation.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAI9C"}

package/dist/client/use-query-states.d.ts

@@ -7,7 +7,7 @@
  *
  * Design doc: design/23-search-params.md §"Codec Bridge"
  */
-import type { SearchParamCodec, SearchParamsDefinition, SetParams, QueryStatesOptions } from '#/search-params/create.js';
+import type { SearchParamCodec, SearchParamsDefinition, SetParams, QueryStatesOptions } from '../search-params/define.js';
 /**
  * Read and write typed search params from/to the URL.
  *

package/dist/client/use-query-states.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-query-states.d.ts","sourceRoot":"","sources":["../../src/client/use-query-states.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAoCnC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,aAAa,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,MAAM,EAClE,QAAQ,CAAC,EAAE,kBAAkB,EAC7B,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAyDnB;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,UAAU,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACpC,CAAC,OAAO,CAAC,EAAE,kBAAkB,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAIrD"}
+{"version":3,"file":"use-query-states.d.ts","sourceRoot":"","sources":["../../src/client/use-query-states.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AAoCpC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,aAAa,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,MAAM,EAClE,QAAQ,CAAC,EAAE,kBAAkB,EAC7B,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CA+DnB;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,UAAU,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACpC,CAAC,OAAO,CAAC,EAAE,kBAAkB,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAIrD"}

package/dist/client/use-router.d.ts

@@ -20,7 +20,7 @@
  *
  * For loading UI during navigation, use:
  * - useLinkStatus()          — per-link pending indicator (inside <Link>)
- * - useNavigationPending()   — global navigation pending state
+ * - usePendingNavigation()   — global navigation pending state
  */
 export interface AppRouterInstance {
     /** Navigate to a URL, pushing a new history entry */

package/dist/client/{use-params.d.ts → use-segment-params.d.ts}

@@ -7,7 +7,7 @@
  *
  * Two layers of type narrowing work together:
  * 1. The generic overload here uses the Routes interface directly —
- *    `useParams<R>()` returns `Routes[R]['params']`.
+ *    `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).
  *
@@ -29,7 +29,7 @@
  *
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
-import type { Routes } from '#/index.js';
+import type { Routes } from '../index.js';
 /**
  * Subscribe to params changes.
  * Retained for backward compatibility with tests that verify the
@@ -87,6 +87,8 @@ export declare function notifyParamsListeners(): void;
  *   exact params shape from the generated Routes interface.
  * @overload Fallback — returns the generic params record.
  */
-export declare function useParams<R extends keyof Routes>(route: R): Routes[R]['params'];
-export declare function useParams(route?: string): Record<string, string | string[]>;
-//# sourceMappingURL=use-params.d.ts.map
+export declare function useSegmentParams<R extends keyof Routes>(route: R): Routes[R] extends {
+    segmentParams: infer P;
+} ? P : Record<string, string | string[]>;
+export declare function useSegmentParams(route?: string): Record<string, string | string[]>;
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAS1C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAE/D;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,MAAM,EACrD,KAAK,EAAE,CAAC,GACP,MAAM,CAAC,CAAC,CAAC,SAAS;IAAE,aAAa,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;AACxF,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC"}

package/dist/codec.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @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;
+}
+/**
+ * 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, validateSync, isStandardSchema, isCodec } from './schema-bridge.js';
+export type { StandardSchemaV1, StandardSchemaResult } from './schema-bridge.js';
+//# 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;;;;;;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;AAMxC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC9F,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/codec.js

@@ -0,0 +1,2 @@
+import { a as validateSync, i as isStandardSchema, r as isCodec, t as fromArraySchema } from "./_chunks/schema-bridge-Cxu4l-7p.js";
+export { fromArraySchema, isCodec, isStandardSchema, validateSync };

package/dist/config-types.d.ts

@@ -0,0 +1,294 @@
+/**
+ * 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;
+    cacheHandler?: unknown;
+    allowedOrigins?: string[];
+    csrf?: boolean;
+    limits?: {
+        actionBodySize?: string;
+        uploadBodySize?: string;
+        maxFields?: number;
+    };
+    /**
+     * Server-action form handling.
+     *
+     * See design/08-forms-and-actions.md §"Validation errors" and
+     * design/13-security.md §"Sensitive field stripping".
+     */
+    /**
+     * Server action runtime behavior.
+     *
+     * See design/08-forms-and-actions.md §"Middleware for Server Actions".
+     */
+    actions?: {
+        /**
+         * Run `middleware.ts` on server action requests before dispatching.
+         *
+         * **Default: `true`** — middleware runs on every action POST so
+         * authentication, rate limiting, tenant isolation, IP allow-listing,
+         * and request-header injection apply uniformly to page renders, route
+         * handlers, and server actions. This closes the auth-bypass class of
+         * issue identified by Next.js CVE-2025-29927: developers can put a
+         * single auth check in `middleware.ts` and trust that it gates every
+         * unsafe-method request.
+         *
+         * Set to `false` to restore the legacy behavior where actions skip
+         * middleware entirely. This is **not recommended** outside of niche
+         * cases (e.g. middleware that rewrites POST bodies and would corrupt
+         * action submissions). When false, you are responsible for placing
+         * auth, rate limiting, and other cross-cutting checks inside every
+         * action — typically via `createActionClient({ middleware: ... })`.
+         *
+         * See TIM-871.
+         */
+        runMiddleware?: boolean;
+    };
+    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.
+     *
+     * 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>;
+    };
+    /**
+     * 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;
+    };
+    /**
+     * 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;
+    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,51 @@
+/**
+ * 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.js';
+export interface ConfigError {
+    field: string;
+    message: string;
+    value?: unknown;
+    suggestion?: string;
+}
+/**
+ * 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.
+ */
+export declare function formatConfigErrors(errors: ConfigError[]): string;
+/**
+ * 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;AAI1D,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;CACrB;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,EAAE,CA2JtE;AASD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,CAiBhE;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"}

package/dist/content/index.d.ts

@@ -1,11 +1,2 @@
-/**
- * @timber-js/app/content — Public API for content collections.
- *
- * Re-exports from content-collections and provides timber-specific utilities.
- * Users can import directly from 'content-collections' for generated types,
- * or use this module for the re-exports.
- *
- * Design doc: 20-content-collections.md §"Querying Collections"
- */
-export { defineCollection, defineConfig } from '@content-collections/core';
+export {};
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/content/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/content/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC"}

package/dist/content/index.js

@@ -1,2 +0,0 @@
-import { defineCollection, defineConfig } from "@content-collections/core";
-export { defineCollection, defineConfig };