@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/client/use-search-params.ts

@@ -4,53 +4,31 @@
  * Returns a read-only URLSearchParams instance reflecting the current
  * URL's query string. Updates when client-side navigation changes the URL.
  *
- * This is a thin wrapper over window.location.search, provided for
- * Next.js API compatibility (libraries like nuqs import useSearchParams
- * from next/navigation).
+ * One unconditional read of NavigationContext, on every side (TIM-1425):
+ *
+ * - In the browser, the provider is updated atomically with the RSC tree
+ *   during full navigations, AND by syncShallowSearch() for shallow URL
+ *   updates (nuqs shallow: true, replaceUrl, or any external
+ *   pushState/replaceState that changes the query string). See router-init.ts.
+ * - During SSR, the wrapper chain mounts the same provider carrying the
+ *   request's RAW query string (TIM-1424), so repeated keys
+ *   (`?tag=a&tag=b`) survive — the collapsed record the ALS context holds
+ *   cannot represent them.
+ * - In the RSC environment, this module is never evaluated — the shims plugin
+ *   resolves next/navigation to navigation-rsc.ts (TIM-1420).
  *
  * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
  * URLSearchParams. Mutation methods (set, delete, append) work on the
  * local copy but do NOT affect the URL — use the router or nuqs for that.
  *
- * During SSR, reads the request search params from the SSR ALS context
- * (populated by ssr-entry.ts) instead of window.location.
- *
- * All mutable state is delegated to client/state.ts for singleton guarantees.
- * See design/18-build-system.md §"Singleton State Registry"
+ * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
  */
 
-import { useSyncExternalStore } from 'react';
-import { getSsrData } from './ssr-data.js';
-import { cachedSearch, cachedSearchParams, _setCachedSearch } from './state.js';
-
-function getSearch(): string {
-  if (typeof window !== 'undefined') return window.location.search;
-  const data = getSsrData();
-  if (!data) return '';
-  const sp = new URLSearchParams(data.searchParams);
-  const str = sp.toString();
-  return str ? `?${str}` : '';
-}
-
-function getServerSearch(): string {
-  const data = getSsrData();
-  if (!data) return '';
-  const sp = new URLSearchParams(data.searchParams);
-  const str = sp.toString();
-  return str ? `?${str}` : '';
-}
+import { getSsrData } from './ssr-data.ts';
+import { useNavigationContext } from './navigation-context.ts';
+import { cachedSearch, cachedSearchParams, _setCachedSearch } from './state.ts';
 
-function subscribe(callback: () => void): () => void {
-  window.addEventListener('popstate', callback);
-  return () => window.removeEventListener('popstate', callback);
-}
-
-// Cache the last search string and its parsed URLSearchParams to avoid
-// creating a new object on every render when the URL hasn't changed.
-// State lives in client/state.ts for singleton guarantees.
-
-function getSearchParams(): URLSearchParams {
-  const search = getSearch();
+function getSearchParams(search: string): URLSearchParams {
   if (search !== cachedSearch) {
     const params = new URLSearchParams(search);
     _setCachedSearch(search, params);
@@ -59,20 +37,31 @@ function getSearchParams(): URLSearchParams {
   return cachedSearchParams;
 }
 
-function getServerSearchParams(): URLSearchParams {
-  const data = getSsrData();
-  return data ? new URLSearchParams(data.searchParams) : new URLSearchParams();
-}
-
 /**
  * Read the current URL search params.
  *
+ * Throws when no NavigationProvider is above the caller.
+ *
  * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
  */
 export function useSearchParams(): URLSearchParams {
-  // useSyncExternalStore needs a primitive snapshot for comparison.
-  // We use the raw search string as the snapshot, then return the
-  // parsed URLSearchParams.
-  useSyncExternalStore(subscribe, getSearch, getServerSearch);
-  return typeof window !== 'undefined' ? getSearchParams() : getServerSearchParams();
+  const nav = useNavigationContext();
+  if (nav === null) {
+    throw new Error(
+      '[timber] useSearchParams() was called outside the timber app tree ' +
+        '(no NavigationProvider found). In tests, render the component ' +
+        'inside the timber providers.'
+    );
+  }
+  // On the server, return a fresh instance per call. The module-level cache
+  // below exists to give client code stable identity for effect deps; on the
+  // server it would be shared mutable state across concurrent requests
+  // (design/13-security.md, "no global fallback state"). Both halves of the
+  // check matter: `window` is absent in a plain Node SSR render, and
+  // getSsrData() catches SSR environments that do define `window` (handleSsr
+  // always runs inside the ALS scope). Pinned by tests/ssr-provider-hooks.test.ts.
+  if (typeof window === 'undefined' || getSsrData()) {
+    return new URLSearchParams(nav.search);
+  }
+  return getSearchParams(nav.search);
 }

package/src/client/use-segment-params.ts

@@ -0,0 +1,69 @@
+/**
+ * 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';
+import { resolveSegmentParams } from '../shared/slot-params.ts';
+import { useParamsContext } from './params-context.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 function useSegmentParams<R extends keyof Routes>(
+  segmentPath: R
+): Routes[R] extends { segmentParams: infer P } ? P : CoercedParams;
+export function useSegmentParams(segmentPath?: string): CoercedParams;
+export function useSegmentParams(segmentPath?: string): CoercedParams {
+  const paramsContext = useParamsContext();
+  if (paramsContext === null) {
+    throw new Error(
+      '[timber] useSegmentParams() was called outside the timber app tree ' +
+        '(no params provider found). In tests, render the component inside ' +
+        'the timber providers.'
+    );
+  }
+  return resolveSegmentParams(paramsContext.params, paramsContext.slotParams, segmentPath);
+}

package/src/client/use-selected-layout-segment.ts

@@ -22,8 +22,8 @@
 
 'use client';
 
-import { useSegmentContext } from './segment-context.js';
-import { usePathname } from './use-pathname.js';
+import { useSegmentContext } from './segment-context.ts';
+import { usePathname } from './use-pathname.ts';
 
 /**
  * Split a pathname into URL segments.

package/src/codec.ts

@@ -0,0 +1,149 @@
+/**
+ * @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"
+ */
+
+// ─── Codec protocol ──────────────────────────────────────────────────────
+
+/**
+ * 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 };
+
+// ─── Standard Schema bridge ──────────────────────────────────────────────
+
+export {
+  // fromSchema,
+  fromArraySchema,
+  // validateSync,
+  // isStandardSchema,
+  // isCodec,
+} from './schema-bridge.ts';
+export type { StandardSchemaV1, StandardSchemaResult } from './schema-bridge.ts';
+
+// ─── Built-in segment param codecs ───────────────────────────────────────
+
+export const codec = {
+  string: {
+    parse(value: string | string[] | undefined): string {
+      return Array.isArray(value) ? value.join('/') : (value ?? '');
+    },
+    serialize(value: string): string | null {
+      return value;
+    },
+  } satisfies Codec<string>,
+
+  integer: {
+    parse(value: string | string[] | undefined): number {
+      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: number): string | null {
+      return String(value);
+    },
+  } satisfies Codec<number>,
+
+  slug: {
+    parse(value: string | string[] | undefined): string {
+      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: string): string | null {
+      return value;
+    },
+  } satisfies Codec<string>,
+
+  stringArray: {
+    __catchAll: true as const,
+    parse(value: string | string[] | undefined): string[] {
+      if (Array.isArray(value)) return value;
+      return value ? [value] : [];
+    },
+    serialize(value: string[]): string | null {
+      return value.join('/');
+    },
+  } satisfies CatchAllCodec<string[]>,
+
+  catchAll<T>(inner: Codec<T>): CatchAllCodec<T[]> {
+    return {
+      __catchAll: true as const,
+      parse(value: string | string[] | undefined): T[] {
+        const arr = Array.isArray(value) ? value : value !== undefined ? [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: T[]): string | null {
+        return value.map((item) => inner.serialize(item)).join('/');
+      },
+    };
+  },
+
+  optionalCatchAll<T>(inner: Codec<T>): OptionalCatchAllCodec<T[] | undefined> {
+    return {
+      __catchAll: true as const,
+      __optional: true as const,
+      parse(value: string | string[] | undefined): T[] | undefined {
+        const arr = Array.isArray(value) ? value : value !== undefined ? [value] : [];
+        if (arr.length === 0) return undefined;
+        return arr.map((item) => inner.parse(item));
+      },
+      serialize(value: T[] | undefined): string | null {
+        if (!value || value.length === 0) return null;
+        return value.map((item) => inner.serialize(item)).join('/');
+      },
+    };
+  },
+} as const;

package/src/config-types.ts

@@ -0,0 +1,322 @@
+/**
+ * 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: `'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;
+  /**
+   * 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;
+  };
+}