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

package/src/client/use-cookie.ts

@@ -10,6 +10,7 @@
 
 import { useSyncExternalStore } from 'react';
 import { getSsrData } from './ssr-data.js';
+import { assertValidCookieName } from '../cookies/validation.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -68,6 +69,17 @@ function notify(name: string): 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 function notifyCookieChange(name: string): void {
+  notify(name);
+}
+
 // ─── Hook ─────────────────────────────────────────────────────────────────
 
 /**
@@ -103,8 +115,25 @@ export function useCookie(
 
   const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 
+  // Validate the name once per hook instance — names are typically
+  // stable string literals, so this catches the bug at first render
+  // rather than on every write. Throws via `assertValidCookieName` with
+  // a precise error if the name violates RFC 7230 token rules.
+  assertValidCookieName(name);
+
   const setCookie: CookieSetter = (newValue: string, options?: ClientCookieOptions) => {
+    if (typeof newValue !== 'string') {
+      throw new Error(
+        `[timber] useCookie(${JSON.stringify(name)}): value must be a string, got ${typeof newValue}.\n` +
+          `  To store a JSON-serializable value, use defineCookie + jsonCookieCodec from\n` +
+          `  '@timber-js/app/cookies' and call its useCookie() hook instead.`
+      );
+    }
     const merged = { ...defaultOptions, ...options };
+    // Auto-encode mirrors the server's `cookies().set()` contract:
+    // values are URL-encoded on write, URL-decoded on read, so the
+    // logical bytes round-trip losslessly. See design/29-cookies.md
+    // §"Encoding Contract".
     document.cookie = `${name}=${encodeURIComponent(newValue)}${serializeOptions(merged)}`;
     notify(name);
   };

package/src/client/use-link-status.ts

@@ -1,26 +1,26 @@
 'use client';
 
-// useLinkStatus — returns { pending: true } while the nearest parent <Link>'s
+// useLinkStatus — returns { isPending: true } while the nearest parent <Link>'s
 // navigation is in flight. No arguments — scoped via React context.
 // See design/19-client-navigation.md §"useLinkStatus()"
 
 import { useContext, createContext } from 'react';
 
 export interface LinkStatus {
-  pending: boolean;
+  isPending: boolean;
 }
 
 /**
  * React context provided by <Link>. Holds the pending status
  * for that specific link's navigation.
  */
-export const LinkStatusContext = createContext<LinkStatus>({ pending: false });
+export const LinkStatusContext = createContext<LinkStatus>({ isPending: false });
 
 /**
- * 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
@@ -28,8 +28,8 @@ export const LinkStatusContext = createContext<LinkStatus>({ pending: false });
  * 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/src/client/{use-navigation-pending.ts → use-pending-navigation.ts}

@@ -1,7 +1,7 @@
-// useNavigationPending — returns true while an RSC navigation is in flight.
-// See design/19-client-navigation.md §"useNavigationPending()"
+// usePendingNavigation — returns true while an RSC navigation is in flight.
+// See design/19-client-navigation.md §"usePendingNavigation()"
 //
-// Reads from PendingNavigationContext (provided by TransitionRoot) so the
+// Reads from PendingNavigationContext (provided by NavigationRoot) so the
 // pending state shows immediately (urgent update) and clears atomically
 // with the new tree (same startTransition commit).
 
@@ -19,10 +19,10 @@ import { usePendingNavigationUrl } from './navigation-context.js';
  *
  * ```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>
@@ -31,7 +31,7 @@ import { usePendingNavigationUrl } from './navigation-context.js';
  * }
  * ```
  */
-export function useNavigationPending(): boolean {
+export function usePendingNavigation(): boolean {
   const pendingUrl = usePendingNavigationUrl();
   // During SSR or outside PendingNavigationProvider, no navigation is pending
   return pendingUrl !== null;

package/src/client/use-query-states.ts

@@ -17,8 +17,8 @@ import type {
   SearchParamsDefinition,
   SetParams,
   QueryStatesOptions,
-} from '#/search-params/create.js';
-import { getSearchParams } from '#/search-params/registry.js';
+} from '../search-params/define.js';
+import { getSearchParamsDefinition } from '../search-params/registry.js';
 
 // ─── Codec Bridge ─────────────────────────────────────────────────
 
@@ -79,7 +79,7 @@ export function useQueryStates<T extends Record<string, unknown>>(
   let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };
   let resolvedUrlKeys = urlKeys;
   if (typeof codecsOrRoute === 'string') {
-    const definition = getSearchParams(codecsOrRoute);
+    const definition = getSearchParamsDefinition(codecsOrRoute);
     if (!definition) {
       throw new Error(
         `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +
@@ -95,8 +95,14 @@ export function useQueryStates<T extends Record<string, unknown>>(
 
   const bridged = bridgeCodecs(codecs);
 
+  // Forward hook-level options (shallow, scroll, history) to nuqs.
+  // These become the default for all setter calls from this hook instance.
+  // Per-call options in setParams(values, opts) override these defaults.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const nuqsOptions: any = {};
+  if (_options?.shallow !== undefined) nuqsOptions.shallow = _options.shallow;
+  if (_options?.scroll !== undefined) nuqsOptions.scroll = _options.scroll;
+  if (_options?.history !== undefined) nuqsOptions.history = _options.history;
   if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) {
     nuqsOptions.urlKeys = resolvedUrlKeys;
   }

package/src/client/use-router.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
  */
 
 import { getRouterOrNull } from './router-ref.js';

package/src/client/{use-params.ts → use-segment-params.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).
  *
@@ -30,7 +30,7 @@
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
 
-import type { Routes } from '#/index.js';
+import type { Routes } from '../index.js';
 import { getSsrData } from './ssr-data.js';
 import { currentParams, _setCurrentParams, paramsListeners } from './state.js';
 import { useNavigationContext } from './navigation-context.js';
@@ -119,9 +119,11 @@ export function notifyParamsListeners(): void {
  *   exact params shape from the generated Routes interface.
  * @overload Fallback — returns the generic params record.
  */
-export function useParams<R extends keyof Routes>(route: R): Routes[R]['params'];
-export function useParams(route?: string): Record<string, string | string[]>;
-export function useParams(_route?: string): Record<string, string | string[]> {
+export function useSegmentParams<R extends keyof Routes>(
+  route: R
+): Routes[R] extends { segmentParams: infer P } ? P : Record<string, string | string[]>;
+export function useSegmentParams(route?: string): Record<string, string | string[]>;
+export function useSegmentParams(_route?: string): Record<string, string | string[]> {
   // Try reading from NavigationContext (client-side, inside React tree).
   // During SSR, no NavigationProvider is mounted, so this returns null.
   // When called outside a React component, useContext throws — caught below.

package/src/codec.ts

@@ -0,0 +1,45 @@
+/**
+ * @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;
+}
+
+/**
+ * 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 ──────────────────────────────────────────────
+
+// fromSchema is internal — defineSearchParams and defineCookie auto-detect
+// Standard Schema objects. Users should pass raw schemas directly.
+export { fromArraySchema, validateSync, isStandardSchema, isCodec } from './schema-bridge.js';
+export type { StandardSchemaV1, StandardSchemaResult } from './schema-bridge.js';

package/src/config-types.ts

@@ -0,0 +1,292 @@
+/**
+ * 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;
+  };
+}