@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.80

package/src/config-types.ts

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

package/src/content/index.ts

@@ -1,13 +1,5 @@
-/**
- * @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"
- */
-
-// Re-export defineCollection and defineConfig for convenience.
-// Users can also import these directly from @content-collections/core.
-export { defineCollection, defineConfig } from '@content-collections/core';
+// @timber-js/app/content entry point removed per TIM-722.
+//
+// Import defineCollection and defineConfig directly from @content-collections/core.
+// This file is kept for the content plugin which uses other files in this directory.
+export {};

package/src/cookies/define-cookie.ts

@@ -2,36 +2,42 @@
  * defineCookie — typed cookie definitions.
  *
  * Bundles name + codec + options into a reusable CookieDefinition<T>
- * with .get(), .set(), .delete() server methods and a .useCookie() client hook.
+ * with async .getCookie(), .setCookie(), .deleteCookie() server methods
+ * and a sync .useCookie() client hook.
+ *
+ * Server methods are async to future-proof the API for v2 features
+ * (signed cookies via crypto.subtle, encrypted cookies, external stores).
  *
  * Reuses the SearchParamCodec protocol via fromSchema() bridge.
  * Validation on read returns the codec default (never throws).
  *
+ * IMPORTANT: This module must NOT have top-level value imports from either
+ * server or client modules. Server methods lazy-import request-context;
+ * useCookie() lazy-imports use-cookie. This ensures:
+ * - Client bundles don't pull in ALS/server code
+ * - RSC bundles don't pull in useSyncExternalStore/client code
+ * - Tree-shaking is not required for correctness
+ *
  * See design/29-cookies.md §"Typed Cookies with Schema Validation"
  */
 
-import { cookies } from '#/server/request-context.js';
-import type { CookieOptions } from '#/server/request-context.js';
-import { useCookie as useRawCookie } from '#/client/use-cookie.js';
-import type { ClientCookieOptions } from '#/client/use-cookie.js';
+import type { CookieOptions } from '../server/request-context.js';
+import type { ClientCookieOptions } from '../client/use-cookie.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
+import type { Codec } from '../codec.js';
+
 /**
  * A codec that converts between string cookie values and typed values.
- * Intentionally identical to SearchParamCodec<T>.
+ * Type alias for the shared Codec<T> protocol.
  */
-export interface CookieCodec<T> {
-  parse(value: string | string[] | undefined): T;
-  serialize(value: T): string | null;
-}
+export type CookieCodec<T> = Codec<T>;
 
 /** Options for defineCookie: codec + CookieOptions merged. */
-export interface DefineCookieOptions<T> extends Omit<CookieOptions, 'signed'> {
+export interface DefineCookieOptions<T> extends CookieOptions {
   /** Codec for parsing/serializing the cookie value. */
   codec: CookieCodec<T>;
-  /** Sign the cookie with HMAC-SHA256. */
-  signed?: boolean;
 }
 
 /** A fully typed cookie definition with server and client methods. */
@@ -44,16 +50,49 @@ export interface CookieDefinition<T> {
   readonly codec: CookieCodec<T>;
 
   /** Server: read the typed value from the current request. */
-  get(): T;
+  getCookie(): Promise<T>;
   /** Server: set the typed value on the response. */
-  set(value: T): void;
+  setCookie(value: T): Promise<void>;
   /** Server: delete the cookie. */
-  delete(): void;
+  deleteCookie(): Promise<void>;
 
   /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */
   useCookie(): [T, (value: T) => void, () => void];
 }
 
+// ─── Lazy Module References ───────────────────────────────────────────────
+//
+// These are resolved on first use, not at module load time. This prevents
+// the server module graph from pulling in client code and vice versa.
+// The dynamic import() in server methods is natural (they're async).
+// For useCookie() (sync), we cache the module reference after first load.
+
+let _useCookieModule: typeof import('../client/use-cookie.js') | undefined;
+
+function getUseCookieModule(): typeof import('../client/use-cookie.js') {
+  if (!_useCookieModule) {
+    // In the client/SSR environment, this module is already in the module
+    // graph (imported by the client entry). The throw is a safeguard —
+    // if useCookie() is somehow called before the module is available,
+    // the developer gets a clear error instead of a silent failure.
+    throw new Error(
+      '[timber] defineCookie().useCookie() requires @timber-js/app/client to be loaded. ' +
+        'This hook can only be used in client components.'
+    );
+  }
+  return _useCookieModule;
+}
+
+/**
+ * Register the client cookie module. Called by the client entry to wire
+ * up the lazy reference without a top-level import.
+ *
+ * @internal — framework use only
+ */
+export function _registerUseCookieModule(mod: typeof import('../client/use-cookie.js')): void {
+  _useCookieModule = mod;
+}
+
 // ─── Factory ──────────────────────────────────────────────────────────────
 
 /**
@@ -61,7 +100,7 @@ export interface CookieDefinition<T> {
  *
  * ```ts
  * import { defineCookie } from '@timber-js/app/cookies';
- * import { fromSchema } from '@timber-js/app/search-params';
+ * import { fromSchema } from '@timber-js/app/codec';
  * import { z } from 'zod/v4';
  *
  * export const themeCookie = defineCookie('theme', {
@@ -69,6 +108,13 @@ export interface CookieDefinition<T> {
  *   httpOnly: false,
  *   maxAge: 60 * 60 * 24 * 365,
  * });
+ *
+ * // Server
+ * const theme = await themeCookie.getCookie();
+ * await themeCookie.setCookie('dark');
+ *
+ * // Client
+ * const [theme, setTheme] = themeCookie.useCookie();
  * ```
  */
 export function defineCookie<T>(
@@ -83,32 +129,39 @@ export function defineCookie<T>(
     options: resolvedOptions,
     codec,
 
-    get(): T {
-      const jar = cookies();
-      const raw = resolvedOptions.signed ? jar.getSigned(name) : jar.get(name);
+    async getCookie(): Promise<T> {
+      const { getCookies } = await import('../server/request-context.js');
+      const jar = await getCookies();
+      const raw = jar.get(name);
       return codec.parse(raw);
     },
 
-    set(value: T): void {
+    async setCookie(value: T): Promise<void> {
+      const { getCookies } = await import('../server/request-context.js');
+      const jar = await getCookies();
       const serialized = codec.serialize(value);
       if (serialized === null) {
-        cookies().delete(name, {
+        jar.delete(name, {
           path: resolvedOptions.path,
           domain: resolvedOptions.domain,
         });
       } else {
-        cookies().set(name, serialized, resolvedOptions);
+        jar.set(name, serialized, resolvedOptions);
       }
     },
 
-    delete(): void {
-      cookies().delete(name, {
+    async deleteCookie(): Promise<void> {
+      const { getCookies } = await import('../server/request-context.js');
+      const jar = await getCookies();
+      jar.delete(name, {
         path: resolvedOptions.path,
         domain: resolvedOptions.domain,
       });
     },
 
     useCookie(): [T, (value: T) => void, () => void] {
+      const { useCookie: useRawCookie } = getUseCookieModule();
+
       // Extract client-safe options (no httpOnly — client cookies can't be httpOnly)
       const clientOpts: ClientCookieOptions = {
         path: resolvedOptions.path,

package/src/cookies/index.ts

@@ -3,3 +3,11 @@
 
 export { defineCookie } from './define-cookie.js';
 export type { CookieDefinition, CookieCodec, DefineCookieOptions } from './define-cookie.js';
+
+// Codec is the canonical home for the Codec type — import from
+// @timber-js/app/codec. Re-export removed per TIM-721.
+
+// cookies() is a server-only function (requires AsyncLocalStorage) and is
+// exported from @timber-js/app/server. It is intentionally NOT re-exported
+// here so that client-side code importing defineCookie doesn't pull in
+// server ALS code. See TIM-704.

package/src/fonts/css.ts

@@ -39,6 +39,7 @@ export function generateFontFaces(descriptors: FontFaceDescriptor[]): string {
  * ```css
  * .timber-font-inter {
  *   --font-sans: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+ *   font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;
  * }
  * ```
  */
@@ -47,7 +48,7 @@ export function generateVariableClass(
   variable: string,
   fontFamily: string
 ): string {
-  return `.${className} {\n  ${variable}: ${fontFamily};\n}`;
+  return `.${className} {\n  ${variable}: ${fontFamily};\n  font-family: ${fontFamily};\n}`;
 }
 
 /**