@timber-js/app 0.2.0-alpha.83 → 0.2.0-alpha.85

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/server/form-data.ts","../../src/server/action-client.ts","../../src/server/form-flash.ts"],"sourcesContent":["/**\n * FormData preprocessing — schema-agnostic conversion of FormData to typed objects.\n *\n * FormData is all strings. Schema validation expects typed values. This module\n * bridges the gap with intelligent coercion that runs *before* schema validation.\n *\n * Inspired by zod-form-data, but schema-agnostic — works with any Standard Schema\n * library (Zod, Valibot, ArkType).\n *\n * See design/08-forms-and-actions.md §\"parseFormData() and coerce helpers\"\n */\n\n// ─── parseFormData ───────────────────────────────────────────────────────\n\n/**\n * Convert FormData into a plain object with intelligent coercion.\n *\n * Handles:\n * - **Duplicate keys → arrays**: `tags=js&tags=ts` → `{ tags: [\"js\", \"ts\"] }`\n * - **Nested dot-paths**: `user.name=Alice` → `{ user: { name: \"Alice\" } }`\n * - **Empty strings → undefined**: Enables `.optional()` semantics in schemas\n * - **Empty Files → undefined**: File inputs with no selection become `undefined`\n * - **Strips `$ACTION_*` fields**: React's internal hidden fields are excluded\n */\nexport function parseFormData(formData: FormData): Record<string, unknown> {\n  const flat: Record<string, unknown> = {};\n\n  for (const key of new Set(formData.keys())) {\n    // Skip React internal fields\n    if (key.startsWith('$ACTION_')) continue;\n\n    const values = formData.getAll(key);\n    const processed = values.map(normalizeValue);\n\n    if (processed.length === 1) {\n      flat[key] = processed[0];\n    } else {\n      // Filter out undefined entries from multi-value fields\n      flat[key] = processed.filter((v) => v !== undefined);\n    }\n  }\n\n  // Expand dot-notation paths into nested objects\n  return expandDotPaths(flat);\n}\n\n/**\n * Normalize a single FormData entry value.\n * - Empty strings → undefined (enables .optional() semantics)\n * - Empty File objects (no selection) → undefined\n * - Everything else passes through as-is\n */\nfunction normalizeValue(value: FormDataEntryValue): unknown {\n  if (typeof value === 'string') {\n    return value === '' ? undefined : value;\n  }\n\n  // File input with no selection: browsers submit a File with name=\"\" and size=0\n  if (value instanceof File && value.size === 0 && value.name === '') {\n    return undefined;\n  }\n\n  return value;\n}\n\n/**\n * Expand dot-notation keys into nested objects.\n * `{ \"user.name\": \"Alice\", \"user.age\": \"30\" }` → `{ user: { name: \"Alice\", age: \"30\" } }`\n *\n * Keys without dots are left as-is. Bracket notation (e.g. `items[0]`) is NOT\n * supported — use dot notation (`items.0`) instead.\n */\nfunction expandDotPaths(flat: Record<string, unknown>): Record<string, unknown> {\n  const result: Record<string, unknown> = {};\n  let hasDotPaths = false;\n\n  // First pass: check if any keys have dots\n  for (const key of Object.keys(flat)) {\n    if (key.includes('.')) {\n      hasDotPaths = true;\n      break;\n    }\n  }\n\n  // Fast path: no dot-notation keys, return as-is\n  if (!hasDotPaths) return flat;\n\n  for (const [key, value] of Object.entries(flat)) {\n    if (!key.includes('.')) {\n      result[key] = value;\n      continue;\n    }\n\n    const parts = key.split('.');\n    let current: Record<string, unknown> = result;\n\n    for (let i = 0; i < parts.length - 1; i++) {\n      const part = parts[i];\n      if (current[part] === undefined || current[part] === null) {\n        current[part] = {};\n      }\n      // If current[part] is not an object (e.g., a string from a non-dotted key),\n      // the dot-path takes precedence\n      if (typeof current[part] !== 'object' || current[part] instanceof File) {\n        current[part] = {};\n      }\n      current = current[part] as Record<string, unknown>;\n    }\n\n    current[parts[parts.length - 1]] = value;\n  }\n\n  return result;\n}\n\n// ─── Coercion Helpers ────────────────────────────────────────────────────\n\n/**\n * Schema-agnostic coercion primitives for common FormData patterns.\n *\n * These are plain transform functions — they compose with any schema library's\n * `transform`/`preprocess` pipeline:\n *\n * ```ts\n * // Zod\n * z.preprocess(coerce.number, z.number())\n * // Valibot\n * v.pipe(v.unknown(), v.transform(coerce.number), v.number())\n * ```\n */\nexport const coerce = {\n  /**\n   * Coerce a string to a number.\n   * - `\"42\"` → `42`\n   * - `\"3.14\"` → `3.14`\n   * - `\"\"` / `undefined` / `null` → `undefined`\n   * - Non-numeric strings → `undefined` (schema validation will catch this)\n   */\n  number(value: unknown): number | undefined {\n    if (value === undefined || value === null || value === '') return undefined;\n    if (typeof value === 'number') return value;\n    if (typeof value !== 'string') return undefined;\n    const num = Number(value);\n    if (Number.isNaN(num)) return undefined;\n    return num;\n  },\n\n  /**\n   * Coerce a checkbox value to a boolean.\n   * HTML checkboxes submit \"on\" when checked and are absent when unchecked.\n   * - `\"on\"` / any truthy string → `true`\n   * - `undefined` / `null` / `\"\"` → `false`\n   */\n  checkbox(value: unknown): boolean {\n    if (value === undefined || value === null || value === '') return false;\n    if (typeof value === 'boolean') return value;\n    // Any non-empty string (typically \"on\") is true\n    return typeof value === 'string' && value.length > 0;\n  },\n\n  /**\n   * Parse a JSON string into an object.\n   * - Valid JSON string → parsed object\n   * - `\"\"` / `undefined` / `null` → `undefined`\n   * - Invalid JSON → `undefined` (schema validation will catch this)\n   */\n  json(value: unknown): unknown {\n    if (value === undefined || value === null || value === '') return undefined;\n    if (typeof value !== 'string') return value;\n    try {\n      return JSON.parse(value);\n    } catch {\n      return undefined;\n    }\n  },\n\n  /**\n   * Coerce a date string to a Date object.\n   * Handles `<input type=\"date\">` (`\"2024-01-15\"`), `<input type=\"datetime-local\">`\n   * (`\"2024-01-15T10:30\"`), and full ISO 8601 strings.\n   * - Valid date string → `Date`\n   * - `\"\"` / `undefined` / `null` → `undefined`\n   * - Invalid date strings → `undefined` (schema validation will catch this)\n   * - Impossible dates that `new Date()` silently normalizes (e.g. Feb 31) → `undefined`\n   */\n  date(value: unknown): Date | undefined {\n    if (value === undefined || value === null || value === '') return undefined;\n    if (value instanceof Date) return value;\n    if (typeof value !== 'string') return undefined;\n    const date = new Date(value);\n    if (Number.isNaN(date.getTime())) return undefined;\n\n    // Overflow detection: extract Y/M/D from the input string and verify\n    // they match the parsed Date components. new Date('2024-02-31') silently\n    // normalizes to March 2nd — we reject such inputs.\n    const ymdMatch = value.match(/^(\\d{4})-(\\d{2})-(\\d{2})/);\n    if (ymdMatch) {\n      const inputYear = Number(ymdMatch[1]);\n      const inputMonth = Number(ymdMatch[2]);\n      const inputDay = Number(ymdMatch[3]);\n\n      // Use UTC methods for date-only and Z-suffixed strings to avoid\n      // timezone offset shifting the day. For datetime-local (no Z suffix),\n      // the Date constructor parses in local time, so use local methods.\n      const isUTC = value.length === 10 || value.endsWith('Z');\n      const parsedYear = isUTC ? date.getUTCFullYear() : date.getFullYear();\n      const parsedMonth = isUTC ? date.getUTCMonth() + 1 : date.getMonth() + 1;\n      const parsedDay = isUTC ? date.getUTCDate() : date.getDate();\n\n      if (inputYear !== parsedYear || inputMonth !== parsedMonth || inputDay !== parsedDay) {\n        return undefined;\n      }\n    }\n\n    return date;\n  },\n\n  /**\n   * Create a File coercion function with optional size and mime type validation.\n   * Returns the File if valid, `undefined` otherwise.\n   *\n   * ```ts\n   * // Basic — just checks it's a real File\n   * z.preprocess(coerce.file(), z.instanceof(File))\n   *\n   * // With constraints\n   * z.preprocess(\n   *   coerce.file({ maxSize: 5 * 1024 * 1024, accept: ['image/png', 'image/jpeg'] }),\n   *   z.instanceof(File)\n   * )\n   * ```\n   */\n  file(options?: { maxSize?: number; accept?: string[] }): (value: unknown) => File | undefined {\n    return (value: unknown): File | undefined => {\n      if (value === undefined || value === null || value === '') return undefined;\n      if (!(value instanceof File)) return undefined;\n\n      // Empty file input (no selection): browsers submit File with name=\"\" and size=0\n      if (value.size === 0 && value.name === '') return undefined;\n\n      if (options?.maxSize !== undefined && value.size > options.maxSize) {\n        return undefined;\n      }\n\n      if (options?.accept !== undefined && !options.accept.includes(value.type)) {\n        return undefined;\n      }\n\n      return value;\n    };\n  },\n};\n","/**\n * createActionClient — typed middleware and schema validation for server actions.\n *\n * Inspired by next-safe-action. Provides a builder API:\n *   createActionClient({ middleware }) → .schema(z.object(...)) → .action(fn)\n *\n * The resulting action function satisfies both:\n *   1. Direct call: action(input) → Promise<ActionResult>\n *   2. React useActionState: (prevState, formData) => Promise<ActionResult>\n *\n * See design/08-forms-and-actions.md §\"Middleware for Server Actions\"\n */\n\n// ─── ActionError ─────────────────────────────────────────────────────────\n\n/**\n * Typed error class for server actions. Carries a string code and optional data.\n * When thrown from middleware or the action body, the action short-circuits and\n * the client receives `result.serverError`.\n *\n * In production, unexpected errors (non-ActionError) return `{ code: 'INTERNAL_ERROR' }`\n * with no message. In dev, `data.message` is included.\n */\nexport class ActionError<TCode extends string = string> extends Error {\n  readonly code: TCode;\n  readonly data: Record<string, unknown> | undefined;\n\n  constructor(code: TCode, data?: Record<string, unknown>) {\n    super(`ActionError: ${code}`);\n    this.name = 'ActionError';\n    this.code = code;\n    this.data = data;\n  }\n}\n\n// ─── Standard Schema ──────────────────────────────────────────────────────\n\n/**\n * Standard Schema v1 interface (subset).\n * Zod ≥3.24, Valibot ≥1.0, and ArkType all implement this.\n * See https://github.com/standard-schema/standard-schema\n *\n * We use permissive types here to accept all compliant libraries without\n * requiring exact structural matches on issues/path shapes.\n */\ninterface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;\n  };\n}\n\ntype StandardSchemaResult<Output> =\n  | { value: Output; issues?: undefined }\n  | { value?: undefined; issues: ReadonlyArray<StandardSchemaIssue> };\n\ninterface StandardSchemaIssue {\n  message: string;\n  path?: ReadonlyArray<PropertyKey | { key: PropertyKey }>;\n}\n\n/** Check if a schema implements the Standard Schema protocol. */\nfunction isStandardSchema(schema: unknown): schema is StandardSchemaV1 {\n  return (\n    typeof schema === 'object' &&\n    schema !== null &&\n    '~standard' in schema &&\n    typeof (schema as StandardSchemaV1)['~standard'].validate === 'function'\n  );\n}\n\n// ─── Types ───────────────────────────────────────────────────────────────\n\n/**\n * Minimal schema interface — compatible with Zod, Valibot, ArkType, etc.\n *\n * Accepts either:\n * - Standard Schema (preferred): any object with `~standard.validate()`\n * - Legacy parse interface: objects with `.parse()` / `.safeParse()`\n *\n * At runtime, Standard Schema is detected via `~standard` property and\n * takes priority over the legacy interface.\n */\nexport type ActionSchema<T = unknown> = StandardSchemaV1<T> | LegacyActionSchema<T>;\n\n/** Legacy schema interface with .parse() / .safeParse(). */\ninterface LegacyActionSchema<T = unknown> {\n  'parse'(data: unknown): T;\n  'safeParse'?(data: unknown): { success: true; data: T } | { success: false; error: SchemaError };\n  // Exclude Standard Schema objects from matching this interface\n  '~standard'?: never;\n}\n\n/** Schema validation error shape (for legacy .safeParse()/.parse() interface). */\nexport interface SchemaError {\n  issues?: Array<{ path?: Array<string | number>; message: string }>;\n  flatten?(): { fieldErrors: Record<string, string[]> };\n}\n\n/** Flattened validation errors keyed by field name. */\nexport type ValidationErrors = Record<string, string[]>;\n\n/** Middleware function: returns context to merge into the action body's ctx. */\nexport type ActionMiddleware<TCtx = Record<string, unknown>> = () => Promise<TCtx> | TCtx;\n\n/** The result type returned to the client. */\nexport type ActionResult<TData = unknown> =\n  | { data: TData; validationErrors?: never; serverError?: never; submittedValues?: never }\n  | {\n      data?: never;\n      validationErrors: ValidationErrors;\n      serverError?: never;\n      /** Raw input values on validation failure — for repopulating form fields. */\n      submittedValues?: Record<string, unknown>;\n    }\n  | {\n      data?: never;\n      validationErrors?: never;\n      serverError: { code: string; data?: Record<string, unknown> };\n      submittedValues?: never;\n    };\n\n/** Context passed to the action body. */\nexport interface ActionContext<TCtx, TInput> {\n  ctx: TCtx;\n  input: TInput;\n}\n\n// ─── Builder ─────────────────────────────────────────────────────────────\n\ninterface ActionClientConfig<TCtx> {\n  middleware?: ActionMiddleware<TCtx> | ActionMiddleware<Record<string, unknown>>[];\n  /** Max file size in bytes. Files exceeding this are rejected with validation errors. */\n  fileSizeLimit?: number;\n}\n\n/** Intermediate builder returned by createActionClient(). */\nexport interface ActionBuilder<TCtx> {\n  /** Declare the input schema. Validation errors are returned typed. */\n  schema<TInput>(schema: ActionSchema<TInput>): ActionBuilderWithSchema<TCtx, TInput>;\n  /** Define the action body without input validation. */\n  action<TData>(\n    fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>\n  ): ActionFn<undefined, TData>;\n}\n\n/** Builder after .schema() has been called. */\nexport interface ActionBuilderWithSchema<TCtx, TInput> {\n  /** Define the action body with validated input. */\n  action<TData>(fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>): ActionFn<TInput, TData>;\n}\n\n/**\n * The final action function. Callable three ways:\n * - Direct: action(input) → Promise<ActionResult<TData>>\n * - React useActionState: action(prevState, formData) → Promise<ActionResult<TData>>\n * - React <form action={fn}>: action(formData) → void  (return value ignored by React)\n *\n * The third overload exists purely for type compatibility with React's\n * `<form action>` prop, which expects `(formData: FormData) => void`.\n * At runtime the function still returns Promise<ActionResult>, but React\n * discards it. This lets validated actions be passed directly to forms\n * without casts.\n */\n/**\n * Map schema output keys to `string | undefined` for form-facing APIs.\n * HTML form values are always strings, and fields can be absent.\n * Gives autocomplete for field names without lying about value types.\n */\nexport type InputHint<T> =\n  T extends Record<string, unknown> ? { [K in keyof T]: string | undefined } : T;\n\nexport type ActionFn<TInput = unknown, TData = unknown> = {\n  /** <form action={fn}> compatibility — React discards the return value. */\n  (formData: FormData): void;\n  /** Direct call: action(input) — optional when TInput is undefined (no-schema actions). */\n  (\n    ...args: undefined extends TInput ? [input?: TInput] : [input: TInput]\n  ): Promise<ActionResult<TData>>;\n  /** React useActionState: action(prevState, formData) */\n  (prevState: ActionResult<TData> | null, formData: FormData): Promise<ActionResult<TData>>;\n};\n\n// ─── Implementation ──────────────────────────────────────────────────────\n\n/**\n * Run middleware array or single function. Returns merged context.\n */\nasync function runActionMiddleware<TCtx>(\n  middleware: ActionMiddleware<TCtx> | ActionMiddleware<Record<string, unknown>>[] | undefined\n): Promise<TCtx> {\n  if (!middleware) {\n    return {} as TCtx;\n  }\n\n  if (Array.isArray(middleware)) {\n    let merged = {} as Record<string, unknown>;\n    for (const mw of middleware) {\n      const result = await mw();\n      merged = { ...merged, ...result };\n    }\n    return merged as TCtx;\n  }\n\n  return await middleware();\n}\n\n// Re-export parseFormData for use throughout the framework\nimport { parseFormData } from './form-data.js';\nimport { formatSize } from '../utils/format.js';\nimport { isDebug, isDevMode } from './debug.js';\nimport { RedirectSignal, DenySignal } from './primitives.js';\n\n/**\n * Extract validation errors from a schema error.\n * Supports Zod's flatten() and generic issues array.\n */\nfunction extractValidationErrors(error: SchemaError): ValidationErrors {\n  // Zod-style flatten\n  if (typeof error.flatten === 'function') {\n    return error.flatten().fieldErrors;\n  }\n\n  // Generic issues array\n  if (error.issues) {\n    const errors: ValidationErrors = {};\n    for (const issue of error.issues) {\n      const path = issue.path?.join('.') ?? '_root';\n      if (!errors[path]) errors[path] = [];\n      errors[path].push(issue.message);\n    }\n    return errors;\n  }\n\n  return { _root: ['Validation failed'] };\n}\n\n/**\n * Extract validation errors from Standard Schema issues.\n */\nfunction extractStandardSchemaErrors(issues: ReadonlyArray<StandardSchemaIssue>): ValidationErrors {\n  const errors: ValidationErrors = {};\n  for (const issue of issues) {\n    const path =\n      issue.path\n        ?.map((p) => {\n          // Standard Schema path items can be { key: ... } objects or bare PropertyKey values\n          if (typeof p === 'object' && p !== null && 'key' in p) return String(p.key);\n          return String(p);\n        })\n        .join('.') ?? '_root';\n    if (!errors[path]) errors[path] = [];\n    errors[path].push(issue.message);\n  }\n  return Object.keys(errors).length > 0 ? errors : { _root: ['Validation failed'] };\n}\n\n/**\n * Wrap unexpected errors into a safe server error result.\n * ActionError → typed result. Other errors → INTERNAL_ERROR (no leak).\n *\n * Exported for use by action-handler.ts to catch errors from raw 'use server'\n * functions that don't use createActionClient.\n */\nexport function handleActionError(error: unknown): ActionResult<never> {\n  if (error instanceof ActionError) {\n    return {\n      serverError: {\n        code: error.code,\n        ...(error.data ? { data: error.data } : {}),\n      },\n    };\n  }\n\n  // In dev, include the message for debugging.\n  // Uses isDevMode() — NOT isDebug() — because this data is sent to the\n  // browser. TIMBER_DEBUG must never cause error messages to leak to clients.\n  // See design/13-security.md principle 4: \"Errors don't leak.\"\n  const devMode = isDevMode();\n  return {\n    serverError: {\n      code: 'INTERNAL_ERROR',\n      ...(devMode && error instanceof Error ? { data: { message: error.message } } : {}),\n    },\n  };\n}\n\n/**\n * Create a typed action client with middleware and schema validation.\n *\n * @example\n * ```ts\n * const action = createActionClient({\n *   middleware: async () => {\n *     const user = await getUser()\n *     if (!user) throw new ActionError('UNAUTHORIZED')\n *     return { user }\n *   },\n * })\n *\n * export const createTodo = action\n *   .schema(z.object({ title: z.string().min(1) }))\n *   .action(async ({ input, ctx }) => {\n *     await db.todos.create({ ...input, userId: ctx.user.id })\n *   })\n * ```\n */\nexport function createActionClient<TCtx = Record<string, never>>(\n  config: ActionClientConfig<TCtx> = {}\n): ActionBuilder<TCtx> {\n  function buildAction<TInput, TData>(\n    schema: ActionSchema<TInput> | undefined,\n    fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>\n  ): ActionFn<TInput, TData> {\n    async function actionHandler(...args: unknown[]): Promise<ActionResult<TData>> {\n      try {\n        // Run middleware\n        const ctx = await runActionMiddleware(config.middleware);\n\n        // Determine input — either FormData (from useActionState) or direct arg\n        let rawInput: unknown;\n        if (args.length === 2 && args[1] instanceof FormData) {\n          // Called as (prevState, formData) by React useActionState (with-JS path)\n          rawInput = schema ? parseFormData(args[1]) : args[1];\n        } else if (args.length === 1 && args[0] instanceof FormData) {\n          // No-JS path: React's decodeAction binds FormData as the sole argument.\n          // The form POSTs without JavaScript, decodeAction resolves the server\n          // reference and binds the FormData, then executeAction calls fn() with\n          // no additional args — so the bound FormData arrives as args[0].\n          rawInput = schema ? parseFormData(args[0]) : args[0];\n        } else {\n          // Direct call: action(input)\n          rawInput = args[0];\n        }\n\n        // Validate file sizes before schema validation.\n        if (config.fileSizeLimit !== undefined && rawInput && typeof rawInput === 'object') {\n          const fileSizeErrors = validateFileSizes(\n            rawInput as Record<string, unknown>,\n            config.fileSizeLimit\n          );\n          if (fileSizeErrors) {\n            const submittedValues = stripFiles(rawInput);\n            return { validationErrors: fileSizeErrors, submittedValues };\n          }\n        }\n\n        // Capture submitted values for repopulation on validation failure.\n        // Exclude File objects (can't serialize, shouldn't echo back).\n        const submittedValues = schema ? stripFiles(rawInput) : undefined;\n\n        // Validate with schema if provided\n        let input: TInput;\n        if (schema) {\n          if (isStandardSchema(schema)) {\n            // Standard Schema protocol (Zod ≥3.24, Valibot ≥1.0, ArkType)\n            const result = schema['~standard'].validate(rawInput);\n            if (result instanceof Promise) {\n              throw new Error(\n                '[timber] createActionClient: schema returned a Promise — only sync schemas are supported.'\n              );\n            }\n            if (result.issues) {\n              const validationErrors = extractStandardSchemaErrors(result.issues);\n              logValidationFailure(validationErrors);\n              return { validationErrors, submittedValues };\n            }\n            input = result.value;\n          } else if (typeof schema.safeParse === 'function') {\n            const result = schema.safeParse(rawInput);\n            if (!result.success) {\n              const validationErrors = extractValidationErrors(result.error);\n              logValidationFailure(validationErrors);\n              return { validationErrors, submittedValues };\n            }\n            input = result.data;\n          } else {\n            try {\n              input = schema.parse(rawInput);\n            } catch (parseError) {\n              const validationErrors = extractValidationErrors(parseError as SchemaError);\n              logValidationFailure(validationErrors);\n              return { validationErrors, submittedValues };\n            }\n          }\n        } else {\n          input = rawInput as TInput;\n        }\n\n        // Execute the action body\n        const data = await fn({ ctx, input });\n        return { data };\n      } catch (error) {\n        // Re-throw redirect/deny signals — these are control flow, not errors.\n        // They must propagate to executeAction() which converts them to proper\n        // HTTP responses (302 redirect, 4xx deny). Catching them here would\n        // wrap them as INTERNAL_ERROR and break redirect()/redirectExternal()/deny().\n        if (error instanceof RedirectSignal || error instanceof DenySignal) {\n          throw error;\n        }\n        return handleActionError(error);\n      }\n    }\n\n    return actionHandler as ActionFn<TInput, TData>;\n  }\n\n  return {\n    schema<TInput>(schema: ActionSchema<TInput>) {\n      return {\n        action<TData>(\n          fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>\n        ): ActionFn<TInput, TData> {\n          return buildAction(schema, fn);\n        },\n      };\n    },\n    action<TData>(\n      fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>\n    ): ActionFn<undefined, TData> {\n      return buildAction(undefined, fn as (ctx: ActionContext<TCtx, unknown>) => Promise<TData>);\n    },\n  };\n}\n\n// ─── validated() ────────────────────────────────────────────────────────\n\n/**\n * Convenience wrapper for the common case: validate input, run handler.\n * No middleware needed.\n *\n * @example\n * ```ts\n * 'use server'\n * import { validated } from '@timber-js/app/server'\n * import { z } from 'zod'\n *\n * export const createTodo = validated(\n *   z.object({ title: z.string().min(1) }),\n *   async (input) => {\n *     await db.todos.create(input)\n *   }\n * )\n * ```\n */\nexport function validated<TInput, TData>(\n  schema: ActionSchema<TInput>,\n  handler: (input: TInput) => Promise<TData>\n): ActionFn<TInput, TData> {\n  return createActionClient()\n    .schema(schema)\n    .action(async ({ input }) => handler(input));\n}\n\n// ─── Helpers ────────────────────────────────────────────────────────────\n\n/**\n * Log validation failures in dev mode so developers can see what went wrong.\n * In production, validation errors are only returned to the client.\n */\nfunction logValidationFailure(errors: ValidationErrors): void {\n  const isDev = isDebug();\n  if (!isDev) return;\n\n  const fields = Object.entries(errors)\n    .map(([field, messages]) => `  ${field}: ${messages.join(', ')}`)\n    .join('\\n');\n  console.warn(`[timber] action schema validation failed:\\n${fields}`);\n}\n\n/**\n * Validate that all File objects in the input are within the size limit.\n * Returns validation errors keyed by field name, or null if all files are ok.\n */\nfunction validateFileSizes(input: Record<string, unknown>, limit: number): ValidationErrors | null {\n  const errors: ValidationErrors = {};\n  const limitKb = Math.round(limit / 1024);\n  const limitLabel =\n    limit >= 1024 * 1024 ? `${Math.round(limit / (1024 * 1024))}MB` : `${limitKb}KB`;\n\n  for (const [key, value] of Object.entries(input)) {\n    if (value instanceof File && value.size > limit) {\n      errors[key] = [\n        `File \"${value.name}\" (${formatSize(value.size)}) exceeds the ${limitLabel} limit`,\n      ];\n    } else if (Array.isArray(value)) {\n      const oversized = value.filter((item) => item instanceof File && item.size > limit);\n      if (oversized.length > 0) {\n        errors[key] = oversized.map(\n          (f: File) => `File \"${f.name}\" (${formatSize(f.size)}) exceeds the ${limitLabel} limit`\n        );\n      }\n    }\n  }\n\n  return Object.keys(errors).length > 0 ? errors : null;\n}\n\n/**\n * Strip File objects from a value, returning a plain object safe for\n * serialization. File objects can't be serialized and shouldn't be echoed back.\n */\nfunction stripFiles(value: unknown): Record<string, unknown> | undefined {\n  if (value === null || value === undefined) return undefined;\n  if (typeof value !== 'object') return undefined;\n\n  const result: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n    if (v instanceof File) continue;\n    if (Array.isArray(v)) {\n      result[k] = v.filter((item) => !(item instanceof File));\n    } else if (typeof v === 'object' && v !== null && !(v instanceof File)) {\n      result[k] = stripFiles(v) ?? {};\n    } else {\n      result[k] = v;\n    }\n  }\n  return result;\n}\n","/**\n * Form Flash — ALS-based store for no-JS form action results.\n *\n * When a no-JS form action completes, the server re-renders the page with\n * the action result injected via AsyncLocalStorage instead of redirecting\n * (which would discard the result). Server components read the flash and\n * pass it to client form components as the initial `useActionState` value.\n *\n * This follows the Remix/Rails pattern — the form component becomes the\n * single source of truth for both with-JS (React state) and no-JS (flash).\n *\n * The flash data is server-side only — never serialized to cookies or headers.\n *\n * See design/08-forms-and-actions.md §\"No-JS Error Round-Trip\"\n */\n\nimport type { ValidationErrors } from './action-client.js';\nimport { formFlashAls } from './als-registry.js';\n\n// ─── Types ───────────────────────────────────────────────────────────────\n\n/**\n * Flash data injected into the re-render after a no-JS form submission.\n *\n * This is the action result from the server action, stored in ALS so server\n * components can read it and pass it to client form components as the initial\n * state for `useActionState`. This makes the form component a single source\n * of truth for both with-JS and no-JS paths.\n *\n * The shape matches `ActionResult<unknown>` — it's one of:\n * - `{ data: ... }` — success\n * - `{ validationErrors, submittedValues }` — validation failure\n * - `{ serverError }` — server error\n */\nexport interface FormFlashData {\n  /** Success data from the action. */\n  data?: unknown;\n  /** Validation errors keyed by field name. `_root` for form-level errors. */\n  validationErrors?: ValidationErrors;\n  /** Raw submitted values for repopulating form fields. File objects are excluded. */\n  submittedValues?: Record<string, unknown>;\n  /** Server error if the action threw an ActionError. */\n  serverError?: { code: string; data?: Record<string, unknown> };\n}\n\n// ─── Public API ──────────────────────────────────────────────────────────\n\n/**\n * Read the form flash data for the current request.\n *\n * Returns `null` if no flash data is present (i.e., this is a normal page\n * render, not a re-render after a no-JS form submission).\n *\n * Pass the flash as the initial state to `useActionState` so the form\n * component has a single source of truth for both with-JS and no-JS paths:\n *\n * ```tsx\n * // app/contact/page.tsx (server component)\n * import { getFormFlash } from '@timber-js/app/server'\n *\n * export default function ContactPage() {\n *   const flash = getFormFlash()\n *   return <ContactForm flash={flash} />\n * }\n *\n * // app/contact/form.tsx (client component)\n * export function ContactForm({ flash }) {\n *   const [result, action, isPending] = useActionState(submitContact, flash)\n *   // result is the single source of truth — flash seeds it on no-JS\n * }\n * ```\n */\nexport function getFormFlash(): FormFlashData | null {\n  return formFlashAls.getStore() ?? null;\n}\n\n// ─── Framework-Internal ──────────────────────────────────────────────────\n\n/**\n * Run a callback with form flash data in scope.\n *\n * Used by the action handler to re-render the page with validation errors\n * available via `getFormFlash()`. Not part of the public API.\n *\n * @internal\n */\nexport function runWithFormFlash<T>(data: FormFlashData, fn: () => T): T {\n  return formFlashAls.run(data, fn);\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/server/form-data.ts","../../src/server/action-client.ts","../../src/server/form-flash.ts"],"sourcesContent":["/**\n * FormData preprocessing — schema-agnostic conversion of FormData to typed objects.\n *\n * FormData is all strings. Schema validation expects typed values. This module\n * bridges the gap with intelligent coercion that runs *before* schema validation.\n *\n * Inspired by zod-form-data, but schema-agnostic — works with any Standard Schema\n * library (Zod, Valibot, ArkType).\n *\n * See design/08-forms-and-actions.md §\"parseFormData() and coerce helpers\"\n */\n\n// ─── parseFormData ───────────────────────────────────────────────────────\n\n/**\n * Convert FormData into a plain object with intelligent coercion.\n *\n * Handles:\n * - **Duplicate keys → arrays**: `tags=js&tags=ts` → `{ tags: [\"js\", \"ts\"] }`\n * - **Nested dot-paths**: `user.name=Alice` → `{ user: { name: \"Alice\" } }`\n * - **Empty strings → undefined**: Enables `.optional()` semantics in schemas\n * - **Empty Files → undefined**: File inputs with no selection become `undefined`\n * - **Strips `$ACTION_*` fields**: React's internal hidden fields are excluded\n */\nexport function parseFormData(formData: FormData): Record<string, unknown> {\n  const flat: Record<string, unknown> = {};\n\n  for (const key of new Set(formData.keys())) {\n    // Skip React internal fields\n    if (key.startsWith('$ACTION_')) continue;\n\n    const values = formData.getAll(key);\n    const processed = values.map(normalizeValue);\n\n    if (processed.length === 1) {\n      flat[key] = processed[0];\n    } else {\n      // Filter out undefined entries from multi-value fields\n      flat[key] = processed.filter((v) => v !== undefined);\n    }\n  }\n\n  // Expand dot-notation paths into nested objects\n  return expandDotPaths(flat);\n}\n\n/**\n * Normalize a single FormData entry value.\n * - Empty strings → undefined (enables .optional() semantics)\n * - Empty File objects (no selection) → undefined\n * - Everything else passes through as-is\n */\nfunction normalizeValue(value: FormDataEntryValue): unknown {\n  if (typeof value === 'string') {\n    return value === '' ? undefined : value;\n  }\n\n  // File input with no selection: browsers submit a File with name=\"\" and size=0\n  if (value instanceof File && value.size === 0 && value.name === '') {\n    return undefined;\n  }\n\n  return value;\n}\n\n/**\n * Expand dot-notation keys into nested objects.\n * `{ \"user.name\": \"Alice\", \"user.age\": \"30\" }` → `{ user: { name: \"Alice\", age: \"30\" } }`\n *\n * Keys without dots are left as-is. Bracket notation (e.g. `items[0]`) is NOT\n * supported — use dot notation (`items.0`) instead.\n */\nfunction expandDotPaths(flat: Record<string, unknown>): Record<string, unknown> {\n  const result: Record<string, unknown> = {};\n  let hasDotPaths = false;\n\n  // First pass: check if any keys have dots\n  for (const key of Object.keys(flat)) {\n    if (key.includes('.')) {\n      hasDotPaths = true;\n      break;\n    }\n  }\n\n  // Fast path: no dot-notation keys, return as-is\n  if (!hasDotPaths) return flat;\n\n  for (const [key, value] of Object.entries(flat)) {\n    if (!key.includes('.')) {\n      result[key] = value;\n      continue;\n    }\n\n    const parts = key.split('.');\n    let current: Record<string, unknown> = result;\n\n    for (let i = 0; i < parts.length - 1; i++) {\n      const part = parts[i];\n      if (current[part] === undefined || current[part] === null) {\n        current[part] = {};\n      }\n      // If current[part] is not an object (e.g., a string from a non-dotted key),\n      // the dot-path takes precedence\n      if (typeof current[part] !== 'object' || current[part] instanceof File) {\n        current[part] = {};\n      }\n      current = current[part] as Record<string, unknown>;\n    }\n\n    current[parts[parts.length - 1]] = value;\n  }\n\n  return result;\n}\n\n// ─── Coercion Helpers ────────────────────────────────────────────────────\n\n/**\n * Schema-agnostic coercion primitives for common FormData patterns.\n *\n * These are plain transform functions — they compose with any schema library's\n * `transform`/`preprocess` pipeline:\n *\n * ```ts\n * // Zod\n * z.preprocess(coerce.number, z.number())\n * // Valibot\n * v.pipe(v.unknown(), v.transform(coerce.number), v.number())\n * ```\n */\nexport const coerce = {\n  /**\n   * Coerce a string to a number.\n   * - `\"42\"` → `42`\n   * - `\"3.14\"` → `3.14`\n   * - `\"\"` / `undefined` / `null` → `undefined`\n   * - Non-numeric strings → `undefined` (schema validation will catch this)\n   */\n  number(value: unknown): number | undefined {\n    if (value === undefined || value === null || value === '') return undefined;\n    if (typeof value === 'number') return value;\n    if (typeof value !== 'string') return undefined;\n    const num = Number(value);\n    if (Number.isNaN(num)) return undefined;\n    return num;\n  },\n\n  /**\n   * Coerce a checkbox value to a boolean.\n   * HTML checkboxes submit \"on\" when checked and are absent when unchecked.\n   * - `\"on\"` / any truthy string → `true`\n   * - `undefined` / `null` / `\"\"` → `false`\n   */\n  checkbox(value: unknown): boolean {\n    if (value === undefined || value === null || value === '') return false;\n    if (typeof value === 'boolean') return value;\n    // Any non-empty string (typically \"on\") is true\n    return typeof value === 'string' && value.length > 0;\n  },\n\n  /**\n   * Parse a JSON string into an object.\n   * - Valid JSON string → parsed object\n   * - `\"\"` / `undefined` / `null` → `undefined`\n   * - Invalid JSON → `undefined` (schema validation will catch this)\n   */\n  json(value: unknown): unknown {\n    if (value === undefined || value === null || value === '') return undefined;\n    if (typeof value !== 'string') return value;\n    try {\n      return JSON.parse(value);\n    } catch {\n      return undefined;\n    }\n  },\n\n  /**\n   * Coerce a date string to a Date object.\n   * Handles `<input type=\"date\">` (`\"2024-01-15\"`), `<input type=\"datetime-local\">`\n   * (`\"2024-01-15T10:30\"`), and full ISO 8601 strings.\n   * - Valid date string → `Date`\n   * - `\"\"` / `undefined` / `null` → `undefined`\n   * - Invalid date strings → `undefined` (schema validation will catch this)\n   * - Impossible dates that `new Date()` silently normalizes (e.g. Feb 31) → `undefined`\n   */\n  date(value: unknown): Date | undefined {\n    if (value === undefined || value === null || value === '') return undefined;\n    if (value instanceof Date) return value;\n    if (typeof value !== 'string') return undefined;\n    const date = new Date(value);\n    if (Number.isNaN(date.getTime())) return undefined;\n\n    // Overflow detection: extract Y/M/D from the input string and verify\n    // they match the parsed Date components. new Date('2024-02-31') silently\n    // normalizes to March 2nd — we reject such inputs.\n    const ymdMatch = value.match(/^(\\d{4})-(\\d{2})-(\\d{2})/);\n    if (ymdMatch) {\n      const inputYear = Number(ymdMatch[1]);\n      const inputMonth = Number(ymdMatch[2]);\n      const inputDay = Number(ymdMatch[3]);\n\n      // Use UTC methods for date-only and Z-suffixed strings to avoid\n      // timezone offset shifting the day. For datetime-local (no Z suffix),\n      // the Date constructor parses in local time, so use local methods.\n      const isUTC = value.length === 10 || value.endsWith('Z');\n      const parsedYear = isUTC ? date.getUTCFullYear() : date.getFullYear();\n      const parsedMonth = isUTC ? date.getUTCMonth() + 1 : date.getMonth() + 1;\n      const parsedDay = isUTC ? date.getUTCDate() : date.getDate();\n\n      if (inputYear !== parsedYear || inputMonth !== parsedMonth || inputDay !== parsedDay) {\n        return undefined;\n      }\n    }\n\n    return date;\n  },\n\n  /**\n   * Create a File coercion function with optional size and mime type validation.\n   * Returns the File if valid, `undefined` otherwise.\n   *\n   * ```ts\n   * // Basic — just checks it's a real File\n   * z.preprocess(coerce.file(), z.instanceof(File))\n   *\n   * // With constraints\n   * z.preprocess(\n   *   coerce.file({ maxSize: 5 * 1024 * 1024, accept: ['image/png', 'image/jpeg'] }),\n   *   z.instanceof(File)\n   * )\n   * ```\n   */\n  file(options?: { maxSize?: number; accept?: string[] }): (value: unknown) => File | undefined {\n    return (value: unknown): File | undefined => {\n      if (value === undefined || value === null || value === '') return undefined;\n      if (!(value instanceof File)) return undefined;\n\n      // Empty file input (no selection): browsers submit File with name=\"\" and size=0\n      if (value.size === 0 && value.name === '') return undefined;\n\n      if (options?.maxSize !== undefined && value.size > options.maxSize) {\n        return undefined;\n      }\n\n      if (options?.accept !== undefined && !options.accept.includes(value.type)) {\n        return undefined;\n      }\n\n      return value;\n    };\n  },\n};\n","/**\n * createActionClient — typed middleware and schema validation for server actions.\n *\n * Inspired by next-safe-action. Provides a builder API:\n *   createActionClient({ middleware }) → .schema(z.object(...)) → .action(fn)\n *\n * The resulting action function satisfies both:\n *   1. Direct call: action(input) → Promise<ActionResult>\n *   2. React useActionState: (prevState, formData) => Promise<ActionResult>\n *\n * See design/08-forms-and-actions.md §\"Middleware for Server Actions\"\n */\n\n// ─── ActionError ─────────────────────────────────────────────────────────\n\n/**\n * Typed error class for server actions. Carries a string code and optional data.\n * When thrown from middleware or the action body, the action short-circuits and\n * the client receives `result.serverError`.\n *\n * In production, unexpected errors (non-ActionError) return `{ code: 'INTERNAL_ERROR' }`\n * with no message. In dev, `data.message` is included.\n */\nexport class ActionError<TCode extends string = string> extends Error {\n  readonly code: TCode;\n  readonly data: Record<string, unknown> | undefined;\n\n  constructor(code: TCode, data?: Record<string, unknown>) {\n    super(`ActionError: ${code}`);\n    this.name = 'ActionError';\n    this.code = code;\n    this.data = data;\n  }\n}\n\n// ─── Standard Schema ──────────────────────────────────────────────────────\n\n/**\n * Standard Schema v1 interface (subset).\n * Zod ≥3.24, Valibot ≥1.0, and ArkType all implement this.\n * See https://github.com/standard-schema/standard-schema\n *\n * We use permissive types here to accept all compliant libraries without\n * requiring exact structural matches on issues/path shapes.\n */\ninterface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;\n  };\n}\n\ntype StandardSchemaResult<Output> =\n  | { value: Output; issues?: undefined }\n  | { value?: undefined; issues: ReadonlyArray<StandardSchemaIssue> };\n\ninterface StandardSchemaIssue {\n  message: string;\n  path?: ReadonlyArray<PropertyKey | { key: PropertyKey }>;\n}\n\n/** Check if a schema implements the Standard Schema protocol. */\nfunction isStandardSchema(schema: unknown): schema is StandardSchemaV1 {\n  return (\n    typeof schema === 'object' &&\n    schema !== null &&\n    '~standard' in schema &&\n    typeof (schema as StandardSchemaV1)['~standard'].validate === 'function'\n  );\n}\n\n// ─── Types ───────────────────────────────────────────────────────────────\n\n/**\n * Minimal schema interface — compatible with Zod, Valibot, ArkType, etc.\n *\n * Accepts either:\n * - Standard Schema (preferred): any object with `~standard.validate()`\n * - Legacy parse interface: objects with `.parse()` / `.safeParse()`\n *\n * At runtime, Standard Schema is detected via `~standard` property and\n * takes priority over the legacy interface.\n */\nexport type ActionSchema<T = unknown> = StandardSchemaV1<T> | LegacyActionSchema<T>;\n\n/** Legacy schema interface with .parse() / .safeParse(). */\ninterface LegacyActionSchema<T = unknown> {\n  'parse'(data: unknown): T;\n  'safeParse'?(data: unknown): { success: true; data: T } | { success: false; error: SchemaError };\n  // Exclude Standard Schema objects from matching this interface\n  '~standard'?: never;\n}\n\n/** Schema validation error shape (for legacy .safeParse()/.parse() interface). */\nexport interface SchemaError {\n  issues?: Array<{ path?: Array<string | number>; message: string }>;\n  flatten?(): { fieldErrors: Record<string, string[]> };\n}\n\n/** Flattened validation errors keyed by field name. */\nexport type ValidationErrors = Record<string, string[]>;\n\n/** Middleware function: returns context to merge into the action body's ctx. */\nexport type ActionMiddleware<TCtx = Record<string, unknown>> = () => Promise<TCtx> | TCtx;\n\n/** The result type returned to the client. */\nexport type ActionResult<TData = unknown> =\n  | { data: TData; validationErrors?: never; serverError?: never; submittedValues?: never }\n  | {\n      data?: never;\n      validationErrors: ValidationErrors;\n      serverError?: never;\n      /** Raw input values on validation failure — for repopulating form fields. */\n      submittedValues?: Record<string, unknown>;\n    }\n  | {\n      data?: never;\n      validationErrors?: never;\n      serverError: { code: string; data?: Record<string, unknown> };\n      submittedValues?: never;\n    };\n\n/** Context passed to the action body. */\nexport interface ActionContext<TCtx, TInput> {\n  ctx: TCtx;\n  input: TInput;\n}\n\n// ─── Builder ─────────────────────────────────────────────────────────────\n\ninterface ActionClientConfig<TCtx> {\n  middleware?: ActionMiddleware<TCtx> | ActionMiddleware<Record<string, unknown>>[];\n  /** Max file size in bytes. Files exceeding this are rejected with validation errors. */\n  fileSizeLimit?: number;\n}\n\n/** Intermediate builder returned by createActionClient(). */\nexport interface ActionBuilder<TCtx> {\n  /** Declare the input schema. Validation errors are returned typed. */\n  schema<TInput>(schema: ActionSchema<TInput>): ActionBuilderWithSchema<TCtx, TInput>;\n  /** Define the action body without input validation. */\n  action<TData>(\n    fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>\n  ): ActionFn<TData, undefined>;\n}\n\n/** Builder after .schema() has been called. */\nexport interface ActionBuilderWithSchema<TCtx, TInput> {\n  /** Define the action body with validated input. */\n  action<TData>(fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>): ActionFn<TData, TInput>;\n}\n\n/**\n * The final action function. Callable three ways:\n * - Direct: action(input) → Promise<ActionResult<TData>>\n * - React useActionState: action(prevState, formData) → Promise<ActionResult<TData>>\n * - React <form action={fn}>: action(formData) → void  (return value ignored by React)\n *\n * The third overload exists purely for type compatibility with React's\n * `<form action>` prop, which expects `(formData: FormData) => void`.\n * At runtime the function still returns Promise<ActionResult>, but React\n * discards it. This lets validated actions be passed directly to forms\n * without casts.\n */\n/**\n * Map schema output keys to `string | undefined` for form-facing APIs.\n * HTML form values are always strings, and fields can be absent.\n * Gives autocomplete for field names without lying about value types.\n */\nexport type InputHint<T> =\n  T extends Record<string, unknown> ? { [K in keyof T]: string | undefined } : T;\n\n/**\n * ActionFn — the callable returned by `createActionClient().action()`.\n *\n * Generic order: `<TData, TInput>` — TData first for backward compatibility.\n * Previously ActionFn had a single `<TData>` generic, so existing code like\n * `ActionFn<MyResult>` must still work with TData in the first position.\n * See TIM-797.\n */\nexport type ActionFn<TData = unknown, TInput = unknown> = {\n  /** <form action={fn}> compatibility — React discards the return value. */\n  (formData: FormData): void;\n  /** Direct call: action(input) — optional when TInput is undefined/unknown (no-schema actions). */\n  (\n    ...args: undefined extends TInput ? [input?: TInput] : [input: TInput]\n  ): Promise<ActionResult<TData>>;\n  /** React useActionState: action(prevState, formData) */\n  (prevState: ActionResult<TData> | null, formData: FormData): Promise<ActionResult<TData>>;\n};\n\n// ─── Implementation ──────────────────────────────────────────────────────\n\n/**\n * Run middleware array or single function. Returns merged context.\n */\nasync function runActionMiddleware<TCtx>(\n  middleware: ActionMiddleware<TCtx> | ActionMiddleware<Record<string, unknown>>[] | undefined\n): Promise<TCtx> {\n  if (!middleware) {\n    return {} as TCtx;\n  }\n\n  if (Array.isArray(middleware)) {\n    let merged = {} as Record<string, unknown>;\n    for (const mw of middleware) {\n      const result = await mw();\n      merged = { ...merged, ...result };\n    }\n    return merged as TCtx;\n  }\n\n  return await middleware();\n}\n\n// Re-export parseFormData for use throughout the framework\nimport { parseFormData } from './form-data.js';\nimport { formatSize } from '../utils/format.js';\nimport { isDebug, isDevMode } from './debug.js';\nimport { RedirectSignal, DenySignal } from './primitives.js';\n\n/**\n * Extract validation errors from a schema error.\n * Supports Zod's flatten() and generic issues array.\n */\nfunction extractValidationErrors(error: SchemaError): ValidationErrors {\n  // Zod-style flatten\n  if (typeof error.flatten === 'function') {\n    return error.flatten().fieldErrors;\n  }\n\n  // Generic issues array\n  if (error.issues) {\n    const errors: ValidationErrors = {};\n    for (const issue of error.issues) {\n      const path = issue.path?.join('.') ?? '_root';\n      if (!errors[path]) errors[path] = [];\n      errors[path].push(issue.message);\n    }\n    return errors;\n  }\n\n  return { _root: ['Validation failed'] };\n}\n\n/**\n * Extract validation errors from Standard Schema issues.\n */\nfunction extractStandardSchemaErrors(issues: ReadonlyArray<StandardSchemaIssue>): ValidationErrors {\n  const errors: ValidationErrors = {};\n  for (const issue of issues) {\n    const path =\n      issue.path\n        ?.map((p) => {\n          // Standard Schema path items can be { key: ... } objects or bare PropertyKey values\n          if (typeof p === 'object' && p !== null && 'key' in p) return String(p.key);\n          return String(p);\n        })\n        .join('.') ?? '_root';\n    if (!errors[path]) errors[path] = [];\n    errors[path].push(issue.message);\n  }\n  return Object.keys(errors).length > 0 ? errors : { _root: ['Validation failed'] };\n}\n\n/**\n * Wrap unexpected errors into a safe server error result.\n * ActionError → typed result. Other errors → INTERNAL_ERROR (no leak).\n *\n * Exported for use by action-handler.ts to catch errors from raw 'use server'\n * functions that don't use createActionClient.\n */\nexport function handleActionError(error: unknown): ActionResult<never> {\n  if (error instanceof ActionError) {\n    return {\n      serverError: {\n        code: error.code,\n        ...(error.data ? { data: error.data } : {}),\n      },\n    };\n  }\n\n  // In dev, include the message for debugging.\n  // Uses isDevMode() — NOT isDebug() — because this data is sent to the\n  // browser. TIMBER_DEBUG must never cause error messages to leak to clients.\n  // See design/13-security.md principle 4: \"Errors don't leak.\"\n  const devMode = isDevMode();\n  return {\n    serverError: {\n      code: 'INTERNAL_ERROR',\n      ...(devMode && error instanceof Error ? { data: { message: error.message } } : {}),\n    },\n  };\n}\n\n/**\n * Create a typed action client with middleware and schema validation.\n *\n * @example\n * ```ts\n * const action = createActionClient({\n *   middleware: async () => {\n *     const user = await getUser()\n *     if (!user) throw new ActionError('UNAUTHORIZED')\n *     return { user }\n *   },\n * })\n *\n * export const createTodo = action\n *   .schema(z.object({ title: z.string().min(1) }))\n *   .action(async ({ input, ctx }) => {\n *     await db.todos.create({ ...input, userId: ctx.user.id })\n *   })\n * ```\n */\nexport function createActionClient<TCtx = Record<string, never>>(\n  config: ActionClientConfig<TCtx> = {}\n): ActionBuilder<TCtx> {\n  function buildAction<TInput, TData>(\n    schema: ActionSchema<TInput> | undefined,\n    fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>\n  ): ActionFn<TData, TInput> {\n    async function actionHandler(...args: unknown[]): Promise<ActionResult<TData>> {\n      try {\n        // Run middleware\n        const ctx = await runActionMiddleware(config.middleware);\n\n        // Determine input — either FormData (from useActionState) or direct arg\n        let rawInput: unknown;\n        if (args.length === 2 && args[1] instanceof FormData) {\n          // Called as (prevState, formData) by React useActionState (with-JS path)\n          rawInput = schema ? parseFormData(args[1]) : args[1];\n        } else if (args.length === 1 && args[0] instanceof FormData) {\n          // No-JS path: React's decodeAction binds FormData as the sole argument.\n          // The form POSTs without JavaScript, decodeAction resolves the server\n          // reference and binds the FormData, then executeAction calls fn() with\n          // no additional args — so the bound FormData arrives as args[0].\n          rawInput = schema ? parseFormData(args[0]) : args[0];\n        } else {\n          // Direct call: action(input)\n          rawInput = args[0];\n        }\n\n        // Validate file sizes before schema validation.\n        if (config.fileSizeLimit !== undefined && rawInput && typeof rawInput === 'object') {\n          const fileSizeErrors = validateFileSizes(\n            rawInput as Record<string, unknown>,\n            config.fileSizeLimit\n          );\n          if (fileSizeErrors) {\n            const submittedValues = stripFiles(rawInput);\n            return { validationErrors: fileSizeErrors, submittedValues };\n          }\n        }\n\n        // Capture submitted values for repopulation on validation failure.\n        // Exclude File objects (can't serialize, shouldn't echo back).\n        const submittedValues = schema ? stripFiles(rawInput) : undefined;\n\n        // Validate with schema if provided\n        let input: TInput;\n        if (schema) {\n          if (isStandardSchema(schema)) {\n            // Standard Schema protocol (Zod ≥3.24, Valibot ≥1.0, ArkType)\n            const result = schema['~standard'].validate(rawInput);\n            if (result instanceof Promise) {\n              throw new Error(\n                '[timber] createActionClient: schema returned a Promise — only sync schemas are supported.'\n              );\n            }\n            if (result.issues) {\n              const validationErrors = extractStandardSchemaErrors(result.issues);\n              logValidationFailure(validationErrors);\n              return { validationErrors, submittedValues };\n            }\n            input = result.value;\n          } else if (typeof schema.safeParse === 'function') {\n            const result = schema.safeParse(rawInput);\n            if (!result.success) {\n              const validationErrors = extractValidationErrors(result.error);\n              logValidationFailure(validationErrors);\n              return { validationErrors, submittedValues };\n            }\n            input = result.data;\n          } else {\n            try {\n              input = schema.parse(rawInput);\n            } catch (parseError) {\n              const validationErrors = extractValidationErrors(parseError as SchemaError);\n              logValidationFailure(validationErrors);\n              return { validationErrors, submittedValues };\n            }\n          }\n        } else {\n          input = rawInput as TInput;\n        }\n\n        // Execute the action body\n        const data = await fn({ ctx, input });\n        return { data };\n      } catch (error) {\n        // Re-throw redirect/deny signals — these are control flow, not errors.\n        // They must propagate to executeAction() which converts them to proper\n        // HTTP responses (302 redirect, 4xx deny). Catching them here would\n        // wrap them as INTERNAL_ERROR and break redirect()/redirectExternal()/deny().\n        if (error instanceof RedirectSignal || error instanceof DenySignal) {\n          throw error;\n        }\n        return handleActionError(error);\n      }\n    }\n\n    return actionHandler as ActionFn<TData, TInput>;\n  }\n\n  return {\n    schema<TInput>(schema: ActionSchema<TInput>) {\n      return {\n        action<TData>(\n          fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>\n        ): ActionFn<TData, TInput> {\n          return buildAction(schema, fn);\n        },\n      };\n    },\n    action<TData>(\n      fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>\n    ): ActionFn<TData, undefined> {\n      return buildAction(undefined, fn as (ctx: ActionContext<TCtx, unknown>) => Promise<TData>);\n    },\n  };\n}\n\n// ─── validated() ────────────────────────────────────────────────────────\n\n/**\n * Convenience wrapper for the common case: validate input, run handler.\n * No middleware needed.\n *\n * @example\n * ```ts\n * 'use server'\n * import { validated } from '@timber-js/app/server'\n * import { z } from 'zod'\n *\n * export const createTodo = validated(\n *   z.object({ title: z.string().min(1) }),\n *   async (input) => {\n *     await db.todos.create(input)\n *   }\n * )\n * ```\n */\nexport function validated<TInput, TData>(\n  schema: ActionSchema<TInput>,\n  handler: (input: TInput) => Promise<TData>\n): ActionFn<TData, TInput> {\n  return createActionClient()\n    .schema(schema)\n    .action(async ({ input }) => handler(input));\n}\n\n// ─── Helpers ────────────────────────────────────────────────────────────\n\n/**\n * Log validation failures in dev mode so developers can see what went wrong.\n * In production, validation errors are only returned to the client.\n */\nfunction logValidationFailure(errors: ValidationErrors): void {\n  const isDev = isDebug();\n  if (!isDev) return;\n\n  const fields = Object.entries(errors)\n    .map(([field, messages]) => `  ${field}: ${messages.join(', ')}`)\n    .join('\\n');\n  console.warn(`[timber] action schema validation failed:\\n${fields}`);\n}\n\n/**\n * Validate that all File objects in the input are within the size limit.\n * Returns validation errors keyed by field name, or null if all files are ok.\n */\nfunction validateFileSizes(input: Record<string, unknown>, limit: number): ValidationErrors | null {\n  const errors: ValidationErrors = {};\n  const limitKb = Math.round(limit / 1024);\n  const limitLabel =\n    limit >= 1024 * 1024 ? `${Math.round(limit / (1024 * 1024))}MB` : `${limitKb}KB`;\n\n  for (const [key, value] of Object.entries(input)) {\n    if (value instanceof File && value.size > limit) {\n      errors[key] = [\n        `File \"${value.name}\" (${formatSize(value.size)}) exceeds the ${limitLabel} limit`,\n      ];\n    } else if (Array.isArray(value)) {\n      const oversized = value.filter((item) => item instanceof File && item.size > limit);\n      if (oversized.length > 0) {\n        errors[key] = oversized.map(\n          (f: File) => `File \"${f.name}\" (${formatSize(f.size)}) exceeds the ${limitLabel} limit`\n        );\n      }\n    }\n  }\n\n  return Object.keys(errors).length > 0 ? errors : null;\n}\n\n/**\n * Strip File objects from a value, returning a plain object safe for\n * serialization. File objects can't be serialized and shouldn't be echoed back.\n */\nfunction stripFiles(value: unknown): Record<string, unknown> | undefined {\n  if (value === null || value === undefined) return undefined;\n  if (typeof value !== 'object') return undefined;\n\n  const result: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n    if (v instanceof File) continue;\n    if (Array.isArray(v)) {\n      result[k] = v.filter((item) => !(item instanceof File));\n    } else if (typeof v === 'object' && v !== null && !(v instanceof File)) {\n      result[k] = stripFiles(v) ?? {};\n    } else {\n      result[k] = v;\n    }\n  }\n  return result;\n}\n","/**\n * Form Flash — ALS-based store for no-JS form action results.\n *\n * When a no-JS form action completes, the server re-renders the page with\n * the action result injected via AsyncLocalStorage instead of redirecting\n * (which would discard the result). Server components read the flash and\n * pass it to client form components as the initial `useActionState` value.\n *\n * This follows the Remix/Rails pattern — the form component becomes the\n * single source of truth for both with-JS (React state) and no-JS (flash).\n *\n * The flash data is server-side only — never serialized to cookies or headers.\n *\n * See design/08-forms-and-actions.md §\"No-JS Error Round-Trip\"\n */\n\nimport type { ValidationErrors } from './action-client.js';\nimport { formFlashAls } from './als-registry.js';\n\n// ─── Types ───────────────────────────────────────────────────────────────\n\n/**\n * Flash data injected into the re-render after a no-JS form submission.\n *\n * This is the action result from the server action, stored in ALS so server\n * components can read it and pass it to client form components as the initial\n * state for `useActionState`. This makes the form component a single source\n * of truth for both with-JS and no-JS paths.\n *\n * The shape matches `ActionResult<unknown>` — it's one of:\n * - `{ data: ... }` — success\n * - `{ validationErrors, submittedValues }` — validation failure\n * - `{ serverError }` — server error\n */\nexport interface FormFlashData {\n  /** Success data from the action. */\n  data?: unknown;\n  /** Validation errors keyed by field name. `_root` for form-level errors. */\n  validationErrors?: ValidationErrors;\n  /** Raw submitted values for repopulating form fields. File objects are excluded. */\n  submittedValues?: Record<string, unknown>;\n  /** Server error if the action threw an ActionError. */\n  serverError?: { code: string; data?: Record<string, unknown> };\n}\n\n// ─── Public API ──────────────────────────────────────────────────────────\n\n/**\n * Read the form flash data for the current request.\n *\n * Returns `null` if no flash data is present (i.e., this is a normal page\n * render, not a re-render after a no-JS form submission).\n *\n * Pass the flash as the initial state to `useActionState` so the form\n * component has a single source of truth for both with-JS and no-JS paths:\n *\n * ```tsx\n * // app/contact/page.tsx (server component)\n * import { getFormFlash } from '@timber-js/app/server'\n *\n * export default function ContactPage() {\n *   const flash = getFormFlash()\n *   return <ContactForm flash={flash} />\n * }\n *\n * // app/contact/form.tsx (client component)\n * export function ContactForm({ flash }) {\n *   const [result, action, isPending] = useActionState(submitContact, flash)\n *   // result is the single source of truth — flash seeds it on no-JS\n * }\n * ```\n */\nexport function getFormFlash(): FormFlashData | null {\n  return formFlashAls.getStore() ?? null;\n}\n\n// ─── Framework-Internal ──────────────────────────────────────────────────\n\n/**\n * Run a callback with form flash data in scope.\n *\n * Used by the action handler to re-render the page with validation errors\n * available via `getFormFlash()`. Not part of the public API.\n *\n * @internal\n */\nexport function runWithFormFlash<T>(data: FormFlashData, fn: () => T): T {\n  return formFlashAls.run(data, fn);\n}\n"],"mappings":"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"}

package/dist/server/internal.js

@@ -3,8 +3,8 @@ import { a as warnRedirectInSuspense, c as warnSuspenseWrappingChildren, i as wa
 import { t as classifyUrlSegment } from "../_chunks/segment-classify-BDNn6EzD.js";
 import { i as getMetadataRouteServePath, n as classifyMetadataRoute, r as getMetadataRouteAutoLink, t as METADATA_ROUTE_CONVENTIONS } from "../_chunks/metadata-routes-DS3eKNmf.js";
 import { a as timingAls, r as requestContextAls, t as earlyHintsSenderAls } from "../_chunks/als-registry-HS0LGUl2.js";
-import { f as runWithRequestContext, l as getSetCookieHeaders, m as setSegmentParams, p as setMutableCookieContext, t as applyRequestHeaderOverlay, u as markResponseFlushed } from "../_chunks/request-context-qMsWgy9C.js";
-import { l as RenderError, n as executeAction, o as DenySignal, r as isRscActionRequest, s as RedirectSignal, t as buildNoJsResponse } from "../_chunks/actions-Dg-ANYHb.js";
+import { f as runWithRequestContext, l as getSetCookieHeaders, m as setSegmentParams, p as setMutableCookieContext, t as applyRequestHeaderOverlay, u as markResponseFlushed } from "../_chunks/request-context-CK5tZqIP.js";
+import { l as RenderError, n as executeAction, o as DenySignal, r as isRscActionRequest, s as RedirectSignal, t as buildNoJsResponse } from "../_chunks/actions-DLnUaR65.js";
 import { c as replaceTraceId, d as withSpan, i as getOtelTraceId, l as runWithTraceId, o as getTraceId, r as generateTraceId, s as getTraceStore, u as setSpanAttribute } from "../_chunks/tracing-CCYbKn5n.js";
 import "../client/error-boundary.js";
 import "../_chunks/segment-context-fHFLF1PE.js";

package/dist/server/rsc-entry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA0DA,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAmCtB;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,mBAAmB,EAAE,KAAK,IAAI,GACtF,IAAI,CAEN;AAgeD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAInE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;8BA3SrC,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AA6ShD,wBAAiE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA0DA,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAmCtB;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,mBAAmB,EAAE,KAAK,IAAI,GACtF,IAAI,CAEN;AAggBD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAInE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;8BA3SrC,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AA6ShD,wBAAiE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.83",
+  "version": "0.2.0-alpha.85",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/form.tsx

@@ -90,16 +90,21 @@ export function useActionState<TData>(
  * </button>
  * ```
  */
-export function useFormAction<TInput = unknown, TData = unknown>(
-  action: ActionFn<TInput, TData> | ((input: TInput) => Promise<ActionResult<TData>>)
-): [(input: InputHint<TInput>) => Promise<ActionResult<TData>>, boolean] {
+export function useFormAction<TData = unknown, TInput = unknown>(
+  action: ActionFn<TData, TInput> | ((input: TInput) => Promise<ActionResult<TData>>)
+): [
+  (
+    ...args: undefined extends TInput ? [input?: InputHint<TInput>] : [input: InputHint<TInput>]
+  ) => Promise<ActionResult<TData>>,
+  boolean,
+] {
   const [isPending, startTransition] = useTransition();
 
-  const execute = (input: InputHint<TInput>): Promise<ActionResult<TData>> => {
+  const execute = (input?: InputHint<TInput>): Promise<ActionResult<TData>> => {
     return new Promise((resolve) => {
       startTransition(async () => {
         const result = await (action as (input: InputHint<TInput>) => Promise<ActionResult<TData>>)(
-          input
+          input as InputHint<TInput>
         );
         resolve(result);
       });

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

@@ -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/config-validation.ts

@@ -0,0 +1,299 @@
+/**
+ * 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';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ConfigError {
+  field: string;
+  message: string;
+  value?: unknown;
+  suggestion?: string;
+}
+
+// ─── Validation ─────────────────────────────────────────────────────────────
+
+/**
+ * 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 function validateConfig(config: TimberUserConfig): ConfigError[] {
+  const errors: ConfigError[] = [];
+
+  // output
+  if (config.output !== undefined && config.output !== 'server' && config.output !== 'static') {
+    errors.push({
+      field: 'output',
+      message: `Invalid output mode: "${String(config.output)}". Must be "server" or "static".`,
+      value: config.output,
+      suggestion: 'Use output: "server" (default) or output: "static" for static site generation.',
+    });
+  }
+
+  // pageExtensions
+  if (config.pageExtensions !== undefined) {
+    if (!Array.isArray(config.pageExtensions)) {
+      errors.push({
+        field: 'pageExtensions',
+        message: 'pageExtensions must be an array of strings.',
+        value: config.pageExtensions,
+        suggestion: 'Example: pageExtensions: ["tsx", "ts", "jsx", "js", "mdx"]',
+      });
+    } else {
+      for (const ext of config.pageExtensions) {
+        if (typeof ext !== 'string') {
+          errors.push({
+            field: 'pageExtensions',
+            message: `pageExtensions contains a non-string value: ${JSON.stringify(ext)}`,
+            value: ext,
+          });
+          break;
+        }
+        if (ext.startsWith('.')) {
+          errors.push({
+            field: 'pageExtensions',
+            message: `pageExtensions should not include the leading dot: "${ext}"`,
+            value: ext,
+            suggestion: `Use "${ext.slice(1)}" instead of "${ext}".`,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  // slowRequestMs
+  if (config.slowRequestMs !== undefined) {
+    if (typeof config.slowRequestMs !== 'number' || config.slowRequestMs < 0) {
+      errors.push({
+        field: 'slowRequestMs',
+        message: `slowRequestMs must be a non-negative number (got ${JSON.stringify(config.slowRequestMs)}).`,
+        value: config.slowRequestMs,
+        suggestion: 'Use slowRequestMs: 3000 (default) or slowRequestMs: 0 to disable.',
+      });
+    }
+  }
+
+  // renderTimeoutMs
+  if (config.renderTimeoutMs !== undefined) {
+    if (typeof config.renderTimeoutMs !== 'number' || config.renderTimeoutMs < 0) {
+      errors.push({
+        field: 'renderTimeoutMs',
+        message: `renderTimeoutMs must be a non-negative number (got ${JSON.stringify(config.renderTimeoutMs)}).`,
+        value: config.renderTimeoutMs,
+        suggestion: 'Use renderTimeoutMs: 30000 (default) or renderTimeoutMs: 0 to disable.',
+      });
+    }
+  }
+
+  // serverTiming
+  if (config.serverTiming !== undefined) {
+    if (
+      config.serverTiming !== 'detailed' &&
+      config.serverTiming !== 'total' &&
+      config.serverTiming !== false
+    ) {
+      errors.push({
+        field: 'serverTiming',
+        message: `Invalid serverTiming value: ${JSON.stringify(config.serverTiming)}.`,
+        value: config.serverTiming,
+        suggestion: 'Use "detailed", "total", or false.',
+      });
+    }
+  }
+
+  // devBrowserLogs
+  if (config.devBrowserLogs !== undefined) {
+    const valid = ['error', 'warn', 'info', 'none'];
+    if (!valid.includes(config.devBrowserLogs)) {
+      errors.push({
+        field: 'devBrowserLogs',
+        message: `Invalid devBrowserLogs value: ${JSON.stringify(config.devBrowserLogs)}.`,
+        value: config.devBrowserLogs,
+        suggestion: `Use one of: ${valid.map((v) => `"${v}"`).join(', ')}.`,
+      });
+    }
+  }
+
+  // sitemap
+  if (config.sitemap != null && typeof config.sitemap === 'object') {
+    if (config.sitemap.enabled && !config.sitemap.baseUrl) {
+      errors.push({
+        field: 'sitemap.baseUrl',
+        message: 'sitemap.baseUrl is required when sitemap is enabled.',
+        suggestion: 'Add sitemap: { enabled: true, baseUrl: "https://example.com" }.',
+      });
+    }
+    if (
+      config.sitemap.defaultPriority !== undefined &&
+      (config.sitemap.defaultPriority < 0 || config.sitemap.defaultPriority > 1)
+    ) {
+      errors.push({
+        field: 'sitemap.defaultPriority',
+        message: `sitemap.defaultPriority must be between 0.0 and 1.0 (got ${config.sitemap.defaultPriority}).`,
+        value: config.sitemap.defaultPriority,
+      });
+    }
+  }
+
+  // Unknown top-level keys
+  const knownKeys = new Set([
+    'output',
+    'debug',
+    'clientJavascript',
+    'adapter',
+    'cacheHandler',
+    'allowedOrigins',
+    'csrf',
+    'limits',
+    'pageExtensions',
+    'slowRequestMs',
+    'renderTimeoutMs',
+    'devBrowserLogs',
+    'dev',
+    'serverTiming',
+    'appDir',
+    'mdx',
+    'actionEncryption',
+    'reactCompiler',
+    'sitemap',
+    'buildDir',
+    'topLoader',
+  ]);
+
+  for (const key of Object.keys(config)) {
+    if (!knownKeys.has(key)) {
+      errors.push({
+        field: key,
+        message: `Unknown config option: "${key}".`,
+        suggestion: `Check for typos. Known options: ${[...knownKeys].sort().join(', ')}.`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+// ─── Formatting ─────────────────────────────────────────────────────────────
+
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * Format config errors for terminal output.
+ */
+export function formatConfigErrors(errors: ConfigError[]): string {
+  if (errors.length === 0) return '';
+
+  const lines: string[] = [];
+  lines.push(
+    `${RED}${BOLD}[timber]${RESET} ${RED}${errors.length} config error${errors.length !== 1 ? 's' : ''} in timber.config.ts:${RESET}`
+  );
+
+  for (const err of errors) {
+    lines.push('');
+    lines.push(`  ${RED}✗${RESET} ${BOLD}${err.field}${RESET}: ${err.message}`);
+    if (err.suggestion) {
+      lines.push(`    ${DIM}${err.suggestion}${RESET}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Virtual Module Name Mapping ────────────────────────────────────────────
+
+const VIRTUAL_MODULE_NAMES: Record<string, string> = {
+  'virtual:timber-rsc-entry': 'RSC entry (server component handler)',
+  'virtual:timber-ssr-entry': 'SSR entry (HTML renderer)',
+  'virtual:timber-browser-entry': 'Browser entry (client hydration)',
+  'virtual:timber-config': 'Runtime config (timber.config.ts)',
+  'virtual:timber-route-manifest': 'Route manifest (app/ file tree)',
+  'virtual:timber-instrumentation': 'Instrumentation (instrumentation.ts)',
+  'virtual:timber-cache-handler': 'Cache handler (cacheHandler config)',
+  'virtual:timber-build-manifest': 'Build manifest (asset mapping)',
+};
+
+/**
+ * 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 function addVirtualModuleContext(errorMessage: string): string {
+  for (const [id, name] of Object.entries(VIRTUAL_MODULE_NAMES)) {
+    if (errorMessage.includes(id)) {
+      return `${errorMessage}\n\n  [timber] This error references "${id}" — timber's ${name}.\n  This is an internal module. The issue is likely in your app code or timber configuration.`;
+    }
+  }
+  return errorMessage;
+}
+
+// ─── Peer Dependency Check ──────────────────────────────────────────────────
+
+interface PeerDepResult {
+  name: string;
+  status: 'ok' | 'missing';
+}
+
+/**
+ * Required (non-optional) peer dependencies that must be installed.
+ */
+const REQUIRED_PEERS = ['react', 'react-dom', '@vitejs/plugin-react', '@vitejs/plugin-rsc'];
+
+/**
+ * Check that required peer dependencies are installed.
+ *
+ * Uses require.resolve with a try/catch — no fs scanning.
+ * Returns only the missing packages.
+ */
+export function checkPeerDependencies(projectRoot: string): PeerDepResult[] {
+  const results: PeerDepResult[] = [];
+
+  for (const name of REQUIRED_PEERS) {
+    try {
+      // Use createRequire from the project root to resolve as the user would
+      const { createRequire } = require('node:module');
+      const userRequire = createRequire(`${projectRoot}/package.json`);
+      userRequire.resolve(name);
+      results.push({ name, status: 'ok' });
+    } catch {
+      results.push({ name, status: 'missing' });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Format missing peer dependencies as an actionable warning.
+ */
+export function formatMissingPeers(results: PeerDepResult[]): string {
+  const missing = results.filter((r) => r.status === 'missing');
+  if (missing.length === 0) return '';
+
+  const names = missing.map((r) => r.name);
+  const lines: string[] = [];
+  lines.push(`${RED}${BOLD}[timber]${RESET} ${RED}Missing required dependencies:${RESET}`);
+  lines.push('');
+  for (const name of names) {
+    lines.push(`  ${RED}✗${RESET} ${name}`);
+  }
+  lines.push('');
+  lines.push(`  ${DIM}Install with:${RESET}`);
+  lines.push(`  ${BOLD}pnpm add ${names.join(' ')}${RESET}`);
+
+  return lines.join('\n');
+}

package/src/index.ts

@@ -366,6 +366,23 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
         // Start the overall dev server setup timer — ends in timber-dev-server
         ctx.timer.start('dev-server-setup');
       }
+
+      // Validate config and check peer dependencies at startup.
+      // Errors are logged to stderr but don't block startup — Vite may
+      // still work partially, and the errors guide the user to fix things.
+      const { validateConfig, formatConfigErrors, checkPeerDependencies, formatMissingPeers } =
+        require('./config-validation.js') as typeof import('./config-validation.js');
+
+      const configErrors = validateConfig(ctx.config);
+      if (configErrors.length > 0) {
+        process.stderr.write(`${formatConfigErrors(configErrors)}\n\n`);
+      }
+
+      const peerResults = checkPeerDependencies(ctx.root);
+      const peerWarning = formatMissingPeers(peerResults);
+      if (peerWarning) {
+        process.stderr.write(`${peerWarning}\n\n`);
+      }
     },
   };