@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

package/LICENSE

@@ -0,0 +1,8 @@
+DONTFUCKINGUSE LICENSE
+
+Copyright (c) 2025 Daniel Saewitz
+
+This software may not be used, copied, modified, merged, published,
+distributed, sublicensed, or sold by anyone other than the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/dist/_chunks/{als-registry-B7DbZ2hS.js → als-registry-BJARkOcu.js}

@@ -38,4 +38,4 @@ var waitUntilAls = new AsyncLocalStorage();
 //#endregion
 export { timingAls as a, revalidationAls as i, formFlashAls as n, traceAls as o, requestContextAls as r, waitUntilAls as s, earlyHintsSenderAls as t };
 
-//# sourceMappingURL=als-registry-B7DbZ2hS.js.map
+//# sourceMappingURL=als-registry-BJARkOcu.js.map

package/dist/_chunks/als-registry-BJARkOcu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"als-registry-BJARkOcu.js","names":[],"sources":["../../src/server/als-registry.ts"],"sourcesContent":["/**\n * Centralized AsyncLocalStorage registry for server-side per-request state.\n *\n * ALL ALS instances used by the server framework live here. Individual\n * modules (request-context.ts, tracing.ts, actions.ts, etc.) import from\n * this registry and re-export public accessor functions.\n *\n * Why: ALS instances require singleton semantics — if two copies of the\n * same ALS exist (one from a relative import, one from a barrel import),\n * one module writes to its copy and another reads from an empty copy.\n * Centralizing ALS creation in a single module eliminates this class of bug.\n *\n * The `timber-shims` plugin ensures `@timber-js/app/server` resolves to\n * src/ in RSC and SSR environments, so all import paths converge here.\n *\n * DO NOT create ALS instances outside this file. If you need a new ALS,\n * add it here and import from `./als-registry.js` in the consuming module.\n *\n * See design/18-build-system.md §\"Module Singleton Strategy\" and\n * §\"Singleton State Registry\".\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport type { DebugComponentEntry } from './rsc-entry/helpers.js';\n\n// ─── Request Context ──────────────────────────────────────────────────────\n// Used by: request-context.ts (headers(), cookies(), searchParams())\n// Design doc: design/04-authorization.md\n\n/** @internal — import via request-context.ts public API */\nexport const requestContextAls = new AsyncLocalStorage<RequestContextStore>();\n\nexport interface RequestContextStore {\n  /** Incoming request headers (read-only view). */\n  headers: Headers;\n  /** Raw cookie header string, parsed lazily into a Map on first access. */\n  cookieHeader: string;\n  /** Lazily-parsed cookie map (mutable — reflects write-overlay from set()). */\n  parsedCookies?: Map<string, string>;\n  /** Original (pre-overlay) frozen headers, kept for overlay merging. */\n  originalHeaders: Headers;\n  /**\n   * Promise resolving to the raw URLSearchParams for the current request.\n   * To get typed parsed params, import a search params definition and\n   * call `.parse(searchParams())`.\n   */\n  searchParamsPromise: Promise<URLSearchParams>;\n  /**\n   * Raw search string from the request URL (e.g. \"?foo=bar&baz=1\").\n   * Available synchronously for use in `redirect()` with `preserveSearchParams`.\n   */\n  searchString: string;\n  /**\n   * Promise resolving to the coerced segment params for the current request.\n   * Set by the pipeline after route matching and param coercion, before\n   * middleware and rendering. Pages and layouts read params via\n   * `rawSegmentParams()` instead of receiving them as a prop.\n   *\n   * See design/07-routing.md §\"params.ts — Convention File for Typed Params\"\n   */\n  segmentParamsPromise?: Promise<Record<string, string | string[]>>;\n  /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */\n  cookieJar: Map<string, CookieEntry>;\n  /** Whether the response has flushed (headers committed). */\n  flushed: boolean;\n  /** Whether the current context allows cookie mutation. */\n  mutableContext: boolean;\n  /**\n   * Set by AccessGate or PageDenyBoundary when a DenySignal is caught\n   * server-side (inside the React tree, before React Flight sees it).\n   * The pipeline reads this after render to set the HTTP status code.\n   * See TIM-666.\n   */\n  denyStatus?: number;\n  /**\n   * Dev-only: getter for the current request's RSC debug components.\n   * Set by renderRoute() so onPipelineError can include component tree\n   * context for render-phase errors without module-level shared state.\n   */\n  debugComponentsGetter?: () => DebugComponentEntry[];\n}\n\n/** A single outgoing cookie entry in the cookie jar. */\nexport interface CookieEntry {\n  name: string;\n  value: string;\n  options: import('./request-context.js').CookieOptions;\n}\n\n// ─── Tracing ──────────────────────────────────────────────────────────────\n// Used by: tracing.ts (traceId(), spanId())\n// Design doc: design/17-logging.md\n\nexport interface TraceStore {\n  /** 32-char lowercase hex trace ID (OTEL or UUID fallback). */\n  traceId: string;\n  /** OTEL span ID if available, undefined otherwise. */\n  spanId?: string;\n}\n\n/** @internal — import via tracing.ts public API */\nexport const traceAls = new AsyncLocalStorage<TraceStore>();\n\n// ─── Server-Timing ────────────────────────────────────────────────────────\n// Used by: server-timing.ts (recordTiming(), withTiming())\n// Design doc: (dev-only performance instrumentation)\n\nexport interface TimingStore {\n  entries: import('./server-timing.js').TimingEntry[];\n}\n\n/** @internal — import via server-timing.ts public API */\nexport const timingAls = new AsyncLocalStorage<TimingStore>();\n\n// ─── Revalidation ─────────────────────────────────────────────────────────\n// Used by: actions.ts (revalidatePath(), revalidateTag())\n// Design doc: design/08-forms-and-actions.md\n\nexport interface RevalidationState {\n  /** Paths to re-render (populated by revalidatePath calls). */\n  paths: string[];\n  /** Tags to invalidate (populated by revalidateTag calls). */\n  tags: string[];\n}\n\n/** @internal — import via actions.ts public API */\nexport const revalidationAls = new AsyncLocalStorage<RevalidationState>();\n\n// ─── Form Flash ───────────────────────────────────────────────────────────\n// Used by: form-flash.ts (getFormFlash())\n// Design doc: design/08-forms-and-actions.md §\"No-JS Error Round-Trip\"\n\n/** @internal — import via form-flash.ts public API */\nexport const formFlashAls = new AsyncLocalStorage<import('./form-flash.js').FormFlashData>();\n\n// ─── Early Hints Sender ──────────────────────────────────────────────────\n// Used by: early-hints-sender.ts (sendEarlyHints103())\n// Design doc: design/02-rendering-pipeline.md §\"Early Hints (103)\"\n\n/** Function that sends Link header values as a 103 Early Hints response. */\nexport type EarlyHintsSenderFn = (links: string[]) => void;\n\n/** @internal — import via early-hints-sender.ts public API */\nexport const earlyHintsSenderAls = new AsyncLocalStorage<EarlyHintsSenderFn>();\n\n// ─── waitUntil Bridge ────────────────────────────────────────────────────\n// Used by: waituntil-bridge.ts (waitUntil())\n// Design doc: design/11-platform.md §\"waitUntil()\"\n\n/** Function that extends the request lifecycle with a background promise. */\nexport type WaitUntilFn = (promise: Promise<unknown>) => void;\n\n/** @internal — import via waituntil-bridge.ts public API */\nexport const waitUntilAls = new AsyncLocalStorage<WaitUntilFn>();\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA8BA,IAAa,oBAAoB,IAAI,mBAAwC;;AAuE7E,IAAa,WAAW,IAAI,mBAA+B;;AAW3D,IAAa,YAAY,IAAI,mBAAgC;;AAc7D,IAAa,kBAAkB,IAAI,mBAAsC;;AAOzE,IAAa,eAAe,IAAI,mBAA4D;;AAU5F,IAAa,sBAAsB,IAAI,mBAAuC;;AAU9E,IAAa,eAAe,IAAI,mBAAgC"}

package/dist/_chunks/chunk-DYhsFzuS.js

@@ -0,0 +1,33 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+export { __exportAll as n, __toESM as r, __commonJSMin as t };

package/dist/_chunks/{debug-gwlJkDuf.js → debug-ECi_61pb.js}

@@ -46,7 +46,7 @@
 *
 * This is the ONLY function that should gate client-visible dev behavior:
 * - Dev error pages with stack traces
-* - Detailed Server-Timing response headers
+* - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
 * - Error messages in action `INTERNAL_ERROR` payloads
 * - Pipeline error handler wiring (Vite overlay)
 *
@@ -105,4 +105,4 @@ function _readTimberDebugEnv() {
 //#endregion
 export { isDevMode as n, isDebug as t };
 
-//# sourceMappingURL=debug-gwlJkDuf.js.map
+//# sourceMappingURL=debug-ECi_61pb.js.map

package/dist/_chunks/debug-ECi_61pb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-ECi_61pb.js","names":[],"sources":["../../src/server/debug.ts"],"sourcesContent":["/**\n * Runtime debug flag for timber.js.\n *\n * Two distinct functions for two distinct security levels:\n *\n * ## `isDebug()` — server-side logging only\n *\n * Returns true when timber's debug/warning messages should be written to\n * stderr / the server console. This NEVER affects what is sent to the\n * client (no error details, no timing headers, no stack traces).\n *\n * Active when any of:\n * - `NODE_ENV !== 'production'` (standard dev mode)\n * - `TIMBER_DEBUG` env var is set to a truthy value at runtime\n * - `timber.config.ts` has `debug: true`\n *\n * ## `isDevMode()` — client-visible dev behavior\n *\n * Returns true ONLY when `NODE_ENV !== 'production'`. This gates anything\n * that changes what clients can observe:\n * - Dev error pages with stack traces (fallback-error.ts)\n * - Detailed Server-Timing headers (pipeline.ts)\n * - Error messages in action INTERNAL_ERROR payloads (action-client.ts)\n * - Pipeline error handler wiring (Vite overlay)\n *\n * `isDevMode()` is statically replaced in production builds → the guarded\n * code is tree-shaken to zero bytes. TIMBER_DEBUG cannot enable it.\n *\n * Usage:\n *   In Cloudflare Workers wrangler.toml:\n *     [vars]\n *     TIMBER_DEBUG = \"1\"\n *\n *   In Node.js:\n *     TIMBER_DEBUG=1 node server.js\n *\n *   In timber.config.ts:\n *     export default { debug: true }\n *\n * See design/13-security.md for the security taxonomy.\n * See design/18-build-system.md for build pipeline details.\n */\n\n// ─── Dev Mode (client-visible) ──────────────────────────────────────────────\n\n/**\n * Check if the application is running in development mode.\n *\n * This is the ONLY function that should gate client-visible dev behavior:\n * - Dev error pages with stack traces\n * - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)\n * - Error messages in action `INTERNAL_ERROR` payloads\n * - Pipeline error handler wiring (Vite overlay)\n *\n * Returns `process.env.NODE_ENV !== 'production'`, which is statically\n * replaced by the bundler in production builds. Code guarded by this\n * function is tree-shaken to zero bytes in production.\n *\n * TIMBER_DEBUG does NOT enable this — that would leak server internals\n * to clients. Use `isDebug()` for server-side-only logging.\n */\nexport function isDevMode(): boolean {\n  return process.env.NODE_ENV !== 'production';\n}\n\n// ─── Debug Flag (server-side logging only) ──────────────────────────────────\n\n/**\n * Config-level debug override. Set via `setDebugFromConfig()` during\n * initialization when timber.config.ts has `debug: true`.\n */\nlet _configDebug = false;\n\n/**\n * Set the debug flag from timber.config.ts.\n * Called during handler initialization.\n */\nexport function setDebugFromConfig(debug: boolean): void {\n  _configDebug = debug;\n}\n\n/**\n * Check if timber debug logging is active (server-side only).\n *\n * Returns true if ANY of these conditions hold:\n * - NODE_ENV is not 'production' (standard dev mode)\n * - TIMBER_DEBUG environment variable is set to a truthy value at runtime\n * - timber.config.ts has `debug: true`\n *\n * This function controls ONLY server-side logging — messages written to\n * stderr or the server console. It NEVER affects client-visible behavior\n * (error pages, response headers, action payloads). For client-visible\n * behavior, use `isDevMode()`.\n *\n * The TIMBER_DEBUG check is deliberately written as a dynamic property\n * access so bundlers cannot statically replace it.\n */\nexport function isDebug(): boolean {\n  // Fast path: dev mode (statically replaced to `true` in dev, `false` in prod)\n  if (process.env.NODE_ENV !== 'production') return true;\n\n  // Config override\n  if (_configDebug) return true;\n\n  // Runtime env var check — uses dynamic access to prevent static replacement.\n  // In production builds, process.env.NODE_ENV is statically replaced, but\n  // TIMBER_DEBUG must survive as a runtime check. The dynamic key access\n  // pattern ensures the bundler treats this as opaque.\n  return _readTimberDebugEnv();\n}\n\n/**\n * Read TIMBER_DEBUG from the environment at runtime.\n *\n * Extracted to a separate function to:\n * 1. Prevent bundler inlining (cross-module function calls are not inlined)\n * 2. Handle platforms where `process` may not exist (Cloudflare Workers)\n * 3. Support globalThis.__TIMBER_DEBUG for programmatic control\n */\nfunction _readTimberDebugEnv(): boolean {\n  // globalThis override — useful for programmatic control and testing\n  if ((globalThis as Record<string, unknown>).__TIMBER_DEBUG) return true;\n\n  // process.env — works in Node.js and platforms that polyfill process\n  try {\n    const key = 'TIMBER_DEBUG';\n    const val =\n      typeof process !== 'undefined' && process.env\n        ? (process.env as Record<string, string | undefined>)[key]\n        : undefined;\n    if (val && val !== '0' && val !== 'false') return true;\n  } catch {\n    // process may not exist or env may throw — safe to ignore\n  }\n\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,SAAgB,YAAqB;AACnC,QAAA,QAAA,IAAA,aAAgC;;;;;;AASlC,IAAI,eAAe;;;;;;;;;;;;;;;;;AA0BnB,SAAgB,UAAmB;AAEjC,KAAA,QAAA,IAAA,aAA6B,aAAc,QAAO;AAGlD,KAAI,aAAc,QAAO;AAMzB,QAAO,qBAAqB;;;;;;;;;;AAW9B,SAAS,sBAA+B;AAEtC,KAAK,WAAuC,eAAgB,QAAO;AAGnE,KAAI;EAEF,MAAM,MACJ,OAAO,YAAY,eAAe,QAAQ,MACrC,QAAQ,IAHH,kBAIN,KAAA;AACN,MAAI,OAAO,QAAQ,OAAO,QAAQ,QAAS,QAAO;SAC5C;AAIR,QAAO"}

package/dist/_chunks/define-CGuYoRHU.js

@@ -0,0 +1,199 @@
+import { n as useQueryStates } from "./use-query-states-DAhgj8Gx.js";
+import { i as isStandardSchema, n as fromSchema, r as isCodec } from "./schema-bridge-C4SwjCQD.js";
+//#region src/search-params/define.ts
+/**
+* defineSearchParams — factory for SearchParamsDefinition<T>.
+*
+* Creates a typed, composable definition for a route's search parameters.
+* Accepts both SearchParamCodec values and Standard Schema objects (Zod,
+* Valibot, ArkType) with auto-detection. Supports URL key aliasing via
+* withUrlKey(), default-omission serialization, and composition via
+* .extend() / .pick().
+*
+* Design doc: design/23-search-params.md §"defineSearchParams — The Factory"
+*/
+var _rawSearchParams;
+/**
+* Register the rawSearchParams function. Called once at module load time
+* from request-context.ts to avoid dynamic import at call time.
+* @internal
+*/
+function _setRawSearchParamsFn(fn) {
+	_rawSearchParams = fn;
+}
+function getRawSearchParams() {
+	if (!_rawSearchParams) throw new Error("[timber] searchParams.load() is only available on the server. Use searchParams.useQueryStates() on the client.");
+	return _rawSearchParams();
+}
+/**
+* Convert URLSearchParams or a plain record to a normalized record
+* where repeated keys produce arrays.
+*/
+function normalizeRaw(raw) {
+	if (raw instanceof URLSearchParams) {
+		const result = {};
+		for (const key of new Set(raw.keys())) {
+			const values = raw.getAll(key);
+			result[key] = values.length === 1 ? values[0] : values;
+		}
+		return result;
+	}
+	return raw;
+}
+/**
+* Compute the serialized default value for a codec. Used for
+* default-omission: when serialize(value) === serialize(parse(undefined)),
+* the field is omitted from the URL.
+*/
+function getDefaultSerialized(codec) {
+	return codec.serialize(codec.parse(void 0));
+}
+/**
+* Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema
+* objects and wraps them with fromSchema. Reads .urlKey from codecs.
+*/
+function resolveField(fieldName, value) {
+	if (isCodec(value)) return {
+		codec: value,
+		urlKey: value.urlKey
+	};
+	if (isStandardSchema(value)) return { codec: fromSchema(value) };
+	throw new Error(`[timber] defineSearchParams: field '${fieldName}' is not a valid codec or Standard Schema. Expected an object with { parse, serialize } methods, or a Standard Schema object (Zod, Valibot, ArkType).`);
+}
+/**
+* Validate that all codecs handle absent params (parse(undefined) doesn't throw).
+* Catches schemas that throw on missing input. `undefined` and `null` are both
+* valid defaults — `undefined` is correct for optional fields (e.g., `z.string().optional()`).
+*/
+function validateDefaults(codecMap) {
+	for (const [key, codec] of Object.entries(codecMap)) try {
+		codec.parse(void 0);
+	} catch {
+		throw new Error(`[timber] defineSearchParams: field '${key}' throws when the param is absent.\n  Search params are optional — the URL might not contain ?${key}=anything.\n  Add .default() or .optional() to your schema, or wrap with withDefault().`);
+	}
+}
+/**
+* Create a SearchParamsDefinition from a map of codecs and/or Standard Schema
+* objects. Accepts both SearchParamCodec values and raw Zod/Valibot/ArkType
+* schemas with auto-detection.
+*
+* ```ts
+* import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'
+* import { parseAsString, parseAsStringEnum } from 'nuqs'
+* import { z } from 'zod/v4'
+*
+* export const searchParams = defineSearchParams({
+*   page: z.coerce.number().int().min(1).default(1),     // Standard Schema — auto-wrapped
+*   q: withUrlKey(parseAsString, 'search'),                // nuqs codec with URL alias
+*   sort: withDefault(parseAsStringEnum(['price', 'name']), 'price'),
+* })
+* ```
+*/
+function defineSearchParams(codecs) {
+	const resolvedCodecs = {};
+	const urlKeys = {};
+	for (const [key, value] of Object.entries(codecs)) {
+		const resolved = resolveField(key, value);
+		resolvedCodecs[key] = resolved.codec;
+		if (resolved.urlKey) urlKeys[key] = resolved.urlKey;
+	}
+	validateDefaults(resolvedCodecs);
+	return buildDefinition(resolvedCodecs, urlKeys);
+}
+/**
+* Internal: build a SearchParamsDefinition from a typed codec map and url keys.
+*/
+function buildDefinition(codecMap, urlKeys) {
+	const defaultSerialized = {};
+	for (const key of Object.keys(codecMap)) defaultSerialized[key] = getDefaultSerialized(codecMap[key]);
+	function getUrlKey(prop) {
+		return urlKeys[prop] ?? prop;
+	}
+	function parseSync(raw) {
+		const normalized = normalizeRaw(raw);
+		const result = {};
+		for (const prop of Object.keys(codecMap)) {
+			const rawValue = normalized[getUrlKey(prop)];
+			result[prop] = codecMap[prop].parse(rawValue);
+		}
+		return result;
+	}
+	function parse(raw) {
+		if (raw instanceof Promise) return raw.then(parseSync);
+		return parseSync(raw);
+	}
+	function serialize(values) {
+		const parts = [];
+		for (const prop of Object.keys(codecMap)) {
+			if (!(prop in values)) continue;
+			const serialized = codecMap[prop].serialize(values[prop]);
+			if (serialized === defaultSerialized[prop]) continue;
+			if (serialized === null) continue;
+			parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);
+		}
+		return parts.join("&");
+	}
+	function href(pathname, values) {
+		const qs = serialize(values);
+		return qs ? `${pathname}?${qs}` : pathname;
+	}
+	function toSearchParams(values) {
+		const usp = new URLSearchParams();
+		for (const prop of Object.keys(codecMap)) {
+			if (!(prop in values)) continue;
+			const serialized = codecMap[prop].serialize(values[prop]);
+			if (serialized === defaultSerialized[prop]) continue;
+			if (serialized === null) continue;
+			usp.set(getUrlKey(prop), serialized);
+		}
+		return usp;
+	}
+	function extend(newCodecs) {
+		const resolvedNewCodecs = {};
+		const newUrlKeys = {};
+		for (const [key, value] of Object.entries(newCodecs)) {
+			const resolved = resolveField(key, value);
+			resolvedNewCodecs[key] = resolved.codec;
+			if (resolved.urlKey) newUrlKeys[key] = resolved.urlKey;
+		}
+		return buildDefinition({
+			...codecMap,
+			...resolvedNewCodecs
+		}, {
+			...urlKeys,
+			...newUrlKeys
+		});
+	}
+	function pick(...keys) {
+		const pickedCodecs = {};
+		const pickedUrlKeys = {};
+		for (const key of keys) {
+			pickedCodecs[key] = codecMap[key];
+			if (key in urlKeys) pickedUrlKeys[key] = urlKeys[key];
+		}
+		return buildDefinition(pickedCodecs, pickedUrlKeys);
+	}
+	function useQueryStates$1(options) {
+		return useQueryStates(codecMap, options, Object.freeze({ ...urlKeys }));
+	}
+	async function load() {
+		if (typeof window !== "undefined") throw new Error("[timber] searchParams.load() is server-only. Use searchParams.useQueryStates() on the client.");
+		return parseSync(await getRawSearchParams());
+	}
+	return {
+		parse,
+		load,
+		useQueryStates: useQueryStates$1,
+		extend,
+		pick,
+		serialize,
+		href,
+		toSearchParams,
+		codecs: codecMap,
+		urlKeys: Object.freeze({ ...urlKeys })
+	};
+}
+//#endregion
+export { defineSearchParams as n, _setRawSearchParamsFn as t };
+
+//# sourceMappingURL=define-CGuYoRHU.js.map

package/dist/_chunks/define-CGuYoRHU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-CGuYoRHU.js","names":[],"sources":["../../src/search-params/define.ts"],"sourcesContent":["/**\n * defineSearchParams — factory for SearchParamsDefinition<T>.\n *\n * Creates a typed, composable definition for a route's search parameters.\n * Accepts both SearchParamCodec values and Standard Schema objects (Zod,\n * Valibot, ArkType) with auto-detection. Supports URL key aliasing via\n * withUrlKey(), default-omission serialization, and composition via\n * .extend() / .pick().\n *\n * Design doc: design/23-search-params.md §\"defineSearchParams — The Factory\"\n */\n\nimport { useQueryStates as clientUseQueryStates } from '../client/use-query-states.js';\nimport { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.js';\nimport type { StandardSchemaV1 } from '../schema-bridge.js';\nimport type { Codec } from '../codec.js';\n\n// Server-only reference for .load() — avoids pulling server ALS into client bundles.\n// In client environments, .load() throws before reaching this code path.\n//\n// IMPORTANT: This is set eagerly via _setRawSearchParamsFn() at server startup\n// (called from request-context.ts module initialization). It must NOT use\n// dynamic `await import()` at call time because the async microtask from the\n// dynamic import loses AsyncLocalStorage context in React's RSC Flight renderer,\n// breaking rawSearchParams() in parallel slot pages. See TIM-523.\nlet _rawSearchParams: (() => Promise<URLSearchParams>) | undefined;\n\n/**\n * Register the rawSearchParams function. Called once at module load time\n * from request-context.ts to avoid dynamic import at call time.\n * @internal\n */\nexport function _setRawSearchParamsFn(fn: () => Promise<URLSearchParams>): void {\n  _rawSearchParams = fn;\n}\n\nfunction getRawSearchParams(): Promise<URLSearchParams> {\n  if (!_rawSearchParams) {\n    throw new Error(\n      '[timber] searchParams.load() is only available on the server. ' +\n        'Use searchParams.useQueryStates() on the client.'\n    );\n  }\n  return _rawSearchParams();\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A codec that converts between URL string values and typed values.\n *\n * nuqs parsers implement this interface natively — no adapter needed.\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected\n * by defineSearchParams and wrapped via fromSchema.\n */\nexport interface SearchParamCodec<T> extends Codec<T> {\n  /** Optional URL key alias, set by withUrlKey(). */\n  urlKey?: string;\n}\n\n/** A codec with a URL key alias attached via withUrlKey(). */\nexport interface SearchParamCodecWithUrlKey<T> extends SearchParamCodec<T> {\n  urlKey: string;\n}\n\n/** Infer the output type of a codec. */\nexport type InferCodec<C> = C extends SearchParamCodec<infer T> ? T : never;\n\n/** Map of property names to codecs. */\nexport type CodecMap<T extends Record<string, unknown>> = {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n};\n\n/** Options for useQueryStates setter. */\nexport interface SetParamsOptions {\n  /** Update URL without server roundtrip (default: false). */\n  shallow?: boolean;\n  /** Scroll to top after update (default: true). */\n  scroll?: boolean;\n  /** 'push' (default) or 'replace' for history state. */\n  history?: 'push' | 'replace';\n}\n\n/** Setter function returned by useQueryStates. */\nexport type SetParams<T> = (values: Partial<T>, options?: SetParamsOptions) => void;\n\n/** Options for useQueryStates hook. */\nexport interface QueryStatesOptions {\n  /** Update URL without server roundtrip (default: false). */\n  shallow?: boolean;\n  /** Scroll to top after update (default: true). */\n  scroll?: boolean;\n  /** 'push' (default) or 'replace' for history state. */\n  history?: 'push' | 'replace';\n}\n\n/**\n * A fully typed, composable search params definition.\n *\n * Returned by defineSearchParams(). Carries a phantom _type property\n * for build-time type extraction.\n */\nexport interface SearchParamsDefinition<T extends Record<string, unknown>> {\n  /** Parse raw URL search params into typed values. */\n  parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n  /** Parse a Promise of URLSearchParams (e.g., from the ALS `searchParams()` API). */\n  parse(raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>): Promise<T>;\n\n  /**\n   * Load typed search params from the current request context (ALS-backed).\n   *\n   * Server-only — reads rawSearchParams() from ALS and parses through codecs.\n   * Throws on client. Eliminates the naming conflict between the definition\n   * export and the server helper.\n   *\n   * ```tsx\n   * // app/products/page.tsx\n   * import { searchParams } from './params'\n   * export default async function Page() {\n   *   const { page, category } = await searchParams.load()\n   * }\n   * ```\n   */\n  load(): Promise<T>;\n\n  /** Client hook — reads current URL params and returns typed values + setter. */\n  useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];\n\n  /** Extend with additional codecs or Standard Schema objects. */\n  extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(\n    codecs: U\n  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }>;\n\n  /** Pick a subset of keys. Preserves codecs and aliases. */\n  pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;\n\n  /** Serialize values to a query string (no leading '?'), omitting defaults. */\n  serialize(values: Partial<T>): string;\n\n  /** Build a full path with query string, omitting defaults. */\n  href(pathname: string, values: Partial<T>): string;\n\n  /** Build a URLSearchParams instance, omitting defaults. */\n  toSearchParams(values: Partial<T>): URLSearchParams;\n\n  /** Read-only codec map for spreading into .extend(). */\n  codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n\n  /** Read-only URL key alias map. Maps property names to URL query parameter keys. */\n  readonly urlKeys: Readonly<Record<string, string>>;\n\n  /**\n   * Phantom property for build-time type extraction.\n   * Never set at runtime — exists only in the type system.\n   */\n  readonly _type?: T;\n}\n\n// StandardSchemaV1 is imported from schema-bridge.ts — single source of truth.\n// Re-export for consumers that import it from this module.\nexport type { StandardSchemaV1 } from '../schema-bridge.js';\n\n// ---------------------------------------------------------------------------\n// Type-level helpers\n// ---------------------------------------------------------------------------\n\n/** Infer the output type from either a SearchParamCodec or a StandardSchemaV1. */\nexport type InferField<V> =\n  V extends SearchParamCodec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;\n\n/** Acceptable field value for defineSearchParams: a codec or a Standard Schema. */\nexport type SearchParamField<T = unknown> = SearchParamCodec<T> | StandardSchemaV1<T>;\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Convert URLSearchParams or a plain record to a normalized record\n * where repeated keys produce arrays.\n */\nfunction normalizeRaw(\n  raw: URLSearchParams | Record<string, string | string[] | undefined>\n): Record<string, string | string[] | undefined> {\n  if (raw instanceof URLSearchParams) {\n    const result: Record<string, string | string[] | undefined> = {};\n    for (const key of new Set(raw.keys())) {\n      const values = raw.getAll(key);\n      result[key] = values.length === 1 ? values[0] : values;\n    }\n    return result;\n  }\n  return raw;\n}\n\n/**\n * Compute the serialized default value for a codec. Used for\n * default-omission: when serialize(value) === serialize(parse(undefined)),\n * the field is omitted from the URL.\n */\nfunction getDefaultSerialized<T>(codec: SearchParamCodec<T>): string | null {\n  return codec.serialize(codec.parse(undefined));\n}\n\n// isStandardSchema and isCodec are imported from schema-bridge.ts.\n\n/**\n * Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema\n * objects and wraps them with fromSchema. Reads .urlKey from codecs.\n */\nfunction resolveField(\n  fieldName: string,\n  value: SearchParamField\n): { codec: SearchParamCodec<unknown>; urlKey?: string } {\n  // Check for codec first (codecs may also have '~standard' if they're nuqs parsers)\n  if (isCodec(value)) {\n    return { codec: value, urlKey: value.urlKey };\n  }\n\n  // Auto-detect Standard Schema\n  if (isStandardSchema(value)) {\n    return { codec: fromSchema(value) };\n  }\n\n  throw new Error(\n    `[timber] defineSearchParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +\n      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n      `(Zod, Valibot, ArkType).`\n  );\n}\n\n/**\n * Validate that all codecs handle absent params (parse(undefined) doesn't throw).\n * Catches schemas that throw on missing input. `undefined` and `null` are both\n * valid defaults — `undefined` is correct for optional fields (e.g., `z.string().optional()`).\n */\nfunction validateDefaults(codecMap: Record<string, SearchParamCodec<unknown>>): void {\n  for (const [key, codec] of Object.entries(codecMap)) {\n    try {\n      codec.parse(undefined);\n    } catch {\n      throw new Error(\n        `[timber] defineSearchParams: field '${key}' throws when the param is absent.\\n` +\n          `  Search params are optional — the URL might not contain ?${key}=anything.\\n` +\n          `  Add .default() or .optional() to your schema, or wrap with withDefault().`\n      );\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a SearchParamsDefinition from a map of codecs and/or Standard Schema\n * objects. Accepts both SearchParamCodec values and raw Zod/Valibot/ArkType\n * schemas with auto-detection.\n *\n * ```ts\n * import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'\n * import { parseAsString, parseAsStringEnum } from 'nuqs'\n * import { z } from 'zod/v4'\n *\n * export const searchParams = defineSearchParams({\n *   page: z.coerce.number().int().min(1).default(1),     // Standard Schema — auto-wrapped\n *   q: withUrlKey(parseAsString, 'search'),                // nuqs codec with URL alias\n *   sort: withDefault(parseAsStringEnum(['price', 'name']), 'price'),\n * })\n * ```\n */\nexport function defineSearchParams<C extends Record<string, SearchParamField>>(\n  codecs: C\n): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }> {\n  type T = { [K in keyof C]: InferField<C[K]> };\n\n  const resolvedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n  const urlKeys: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(codecs)) {\n    const resolved = resolveField(key, value as SearchParamField);\n    resolvedCodecs[key] = resolved.codec;\n    if (resolved.urlKey) {\n      urlKeys[key] = resolved.urlKey;\n    }\n  }\n\n  // Validate that all codecs handle absent params\n  validateDefaults(resolvedCodecs);\n\n  return buildDefinition<T>(resolvedCodecs as unknown as CodecMap<T>, urlKeys);\n}\n\n// ---------------------------------------------------------------------------\n// Internal: build the definition object\n// ---------------------------------------------------------------------------\n\n/**\n * Internal: build a SearchParamsDefinition from a typed codec map and url keys.\n */\nfunction buildDefinition<T extends Record<string, unknown>>(\n  codecMap: CodecMap<T>,\n  urlKeys: Record<string, string>\n): SearchParamsDefinition<T> {\n  // Pre-compute default serialized values for omission check\n  const defaultSerialized: Record<string, string | null> = {};\n  for (const key of Object.keys(codecMap)) {\n    defaultSerialized[key] = getDefaultSerialized(codecMap[key as keyof T]);\n  }\n\n  function getUrlKey(prop: string): string {\n    return urlKeys[prop] ?? prop;\n  }\n\n  // ---- parse ----\n  function parseSync(raw: URLSearchParams | Record<string, string | string[] | undefined>): T {\n    const normalized = normalizeRaw(raw);\n    const result: Record<string, unknown> = {};\n\n    for (const prop of Object.keys(codecMap)) {\n      const urlKey = getUrlKey(prop);\n      const rawValue = normalized[urlKey];\n      result[prop] = (codecMap[prop as keyof T] as SearchParamCodec<unknown>).parse(rawValue);\n    }\n\n    return result as T;\n  }\n\n  // Overloaded parse: sync when given raw params, async when given a Promise.\n  // This enables the ergonomic pattern: await def.parse(searchParams())\n  function parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n  function parse(\n    raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n  ): Promise<T>;\n  function parse(\n    raw:\n      | URLSearchParams\n      | Record<string, string | string[] | undefined>\n      | Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n  ): T | Promise<T> {\n    if (raw instanceof Promise) {\n      return raw.then(parseSync);\n    }\n    return parseSync(raw);\n  }\n\n  // ---- serialize ----\n  function serialize(values: Partial<T>): string {\n    const parts: string[] = [];\n\n    for (const prop of Object.keys(codecMap)) {\n      if (!(prop in values)) continue;\n      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n      const serialized = codec.serialize(values[prop as keyof T] as unknown);\n\n      // Omit if serialized value matches the default\n      if (serialized === defaultSerialized[prop]) continue;\n      if (serialized === null) continue;\n\n      parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);\n    }\n\n    return parts.join('&');\n  }\n\n  // ---- href ----\n  function href(pathname: string, values: Partial<T>): string {\n    const qs = serialize(values);\n    return qs ? `${pathname}?${qs}` : pathname;\n  }\n\n  // ---- toSearchParams ----\n  function toSearchParams(values: Partial<T>): URLSearchParams {\n    const usp = new URLSearchParams();\n\n    for (const prop of Object.keys(codecMap)) {\n      if (!(prop in values)) continue;\n      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n      const serialized = codec.serialize(values[prop as keyof T] as unknown);\n\n      if (serialized === defaultSerialized[prop]) continue;\n      if (serialized === null) continue;\n\n      usp.set(getUrlKey(prop), serialized);\n    }\n\n    return usp;\n  }\n\n  // ---- extend ----\n  function extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(\n    newCodecs: U\n  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }> {\n    type Combined = T & { [K in keyof U]: InferField<U[K]> };\n\n    // Resolve any Standard Schema objects in the extension\n    const resolvedNewCodecs: Record<string, SearchParamCodec<unknown>> = {};\n    const newUrlKeys: Record<string, string> = {};\n    for (const [key, value] of Object.entries(newCodecs)) {\n      const resolved = resolveField(key, value as SearchParamField);\n      resolvedNewCodecs[key] = resolved.codec;\n      if (resolved.urlKey) {\n        newUrlKeys[key] = resolved.urlKey;\n      }\n    }\n\n    const combinedCodecs = {\n      ...codecMap,\n      ...resolvedNewCodecs,\n    } as unknown as CodecMap<Combined>;\n\n    // Merge URL keys: base keys + new codec urlKeys from withUrlKey\n    const combinedUrlKeys: Record<string, string> = { ...urlKeys, ...newUrlKeys };\n\n    return buildDefinition<Combined>(combinedCodecs, combinedUrlKeys);\n  }\n\n  // ---- pick ----\n  function pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>> {\n    const pickedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n    const pickedUrlKeys: Record<string, string> = {};\n\n    for (const key of keys) {\n      pickedCodecs[key] = codecMap[key] as SearchParamCodec<unknown>;\n      if (key in urlKeys) {\n        pickedUrlKeys[key] = urlKeys[key];\n      }\n    }\n\n    return buildDefinition<Pick<T, K>>(\n      pickedCodecs as unknown as CodecMap<Pick<T, K>>,\n      pickedUrlKeys\n    );\n  }\n\n  // ---- useQueryStates ----\n  // Delegates to the 'use client' implementation from use-query-states.ts.\n  //\n  // In the RSC environment: use-query-states.ts is transformed by the RSC\n  //   plugin into a client reference proxy. Calling it throws — correct,\n  //   because hooks can't run during server component rendering.\n  // In SSR: use-query-states.ts is the real nuqs-backed function. Hooks\n  //   work during SSR's renderToReadableStream, so this works correctly.\n  // On the client: same as SSR — the real function is available.\n  function useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>] {\n    return clientUseQueryStates(codecMap, options, Object.freeze({ ...urlKeys })) as [\n      T,\n      SetParams<T>,\n    ];\n  }\n\n  // ---- load ----\n  // ALS-backed: reads rawSearchParams() from the current request context\n  // and parses through codecs. Server-only — throws on client.\n  async function load(): Promise<T> {\n    if (typeof window !== 'undefined') {\n      throw new Error(\n        '[timber] searchParams.load() is server-only. ' +\n          'Use searchParams.useQueryStates() on the client.'\n      );\n    }\n    const raw = await getRawSearchParams();\n    return parseSync(raw);\n  }\n\n  const definition: SearchParamsDefinition<T> = {\n    parse,\n    load,\n    useQueryStates,\n    extend,\n    pick,\n    serialize,\n    href,\n    toSearchParams,\n    codecs: codecMap,\n    urlKeys: Object.freeze({ ...urlKeys }),\n  };\n\n  return definition;\n}\n"],"mappings":";;;;;;;;;;;;;;AAyBA,IAAI;;;;;;AAOJ,SAAgB,sBAAsB,IAA0C;AAC9E,oBAAmB;;AAGrB,SAAS,qBAA+C;AACtD,KAAI,CAAC,iBACH,OAAM,IAAI,MACR,iHAED;AAEH,QAAO,kBAAkB;;;;;;AA4I3B,SAAS,aACP,KAC+C;AAC/C,KAAI,eAAe,iBAAiB;EAClC,MAAM,SAAwD,EAAE;AAChE,OAAK,MAAM,OAAO,IAAI,IAAI,IAAI,MAAM,CAAC,EAAE;GACrC,MAAM,SAAS,IAAI,OAAO,IAAI;AAC9B,UAAO,OAAO,OAAO,WAAW,IAAI,OAAO,KAAK;;AAElD,SAAO;;AAET,QAAO;;;;;;;AAQT,SAAS,qBAAwB,OAA2C;AAC1E,QAAO,MAAM,UAAU,MAAM,MAAM,KAAA,EAAU,CAAC;;;;;;AAShD,SAAS,aACP,WACA,OACuD;AAEvD,KAAI,QAAQ,MAAM,CAChB,QAAO;EAAE,OAAO;EAAO,QAAQ,MAAM;EAAQ;AAI/C,KAAI,iBAAiB,MAAM,CACzB,QAAO,EAAE,OAAO,WAAW,MAAM,EAAE;AAGrC,OAAM,IAAI,MACR,uCAAuC,UAAU,uJAGlD;;;;;;;AAQH,SAAS,iBAAiB,UAA2D;AACnF,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,CACjD,KAAI;AACF,QAAM,MAAM,KAAA,EAAU;SAChB;AACN,QAAM,IAAI,MACR,uCAAuC,IAAI,gGACoB,IAAI,yFAEpE;;;;;;;;;;;;;;;;;;;;AA0BP,SAAgB,mBACd,QAC8D;CAG9D,MAAM,iBAA4D,EAAE;CACpE,MAAM,UAAkC,EAAE;AAE1C,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,EAAE;EACjD,MAAM,WAAW,aAAa,KAAK,MAA0B;AAC7D,iBAAe,OAAO,SAAS;AAC/B,MAAI,SAAS,OACX,SAAQ,OAAO,SAAS;;AAK5B,kBAAiB,eAAe;AAEhC,QAAO,gBAAmB,gBAA0C,QAAQ;;;;;AAU9E,SAAS,gBACP,UACA,SAC2B;CAE3B,MAAM,oBAAmD,EAAE;AAC3D,MAAK,MAAM,OAAO,OAAO,KAAK,SAAS,CACrC,mBAAkB,OAAO,qBAAqB,SAAS,KAAgB;CAGzE,SAAS,UAAU,MAAsB;AACvC,SAAO,QAAQ,SAAS;;CAI1B,SAAS,UAAU,KAAyE;EAC1F,MAAM,aAAa,aAAa,IAAI;EACpC,MAAM,SAAkC,EAAE;AAE1C,OAAK,MAAM,QAAQ,OAAO,KAAK,SAAS,EAAE;GAExC,MAAM,WAAW,WADF,UAAU,KAAK;AAE9B,UAAO,QAAS,SAAS,MAA+C,MAAM,SAAS;;AAGzF,SAAO;;CAST,SAAS,MACP,KAIgB;AAChB,MAAI,eAAe,QACjB,QAAO,IAAI,KAAK,UAAU;AAE5B,SAAO,UAAU,IAAI;;CAIvB,SAAS,UAAU,QAA4B;EAC7C,MAAM,QAAkB,EAAE;AAE1B,OAAK,MAAM,QAAQ,OAAO,KAAK,SAAS,EAAE;AACxC,OAAI,EAAE,QAAQ,QAAS;GAEvB,MAAM,aADQ,SAAS,MACE,UAAU,OAAO,MAA4B;AAGtE,OAAI,eAAe,kBAAkB,MAAO;AAC5C,OAAI,eAAe,KAAM;AAEzB,SAAM,KAAK,GAAG,mBAAmB,UAAU,KAAK,CAAC,CAAC,GAAG,mBAAmB,WAAW,GAAG;;AAGxF,SAAO,MAAM,KAAK,IAAI;;CAIxB,SAAS,KAAK,UAAkB,QAA4B;EAC1D,MAAM,KAAK,UAAU,OAAO;AAC5B,SAAO,KAAK,GAAG,SAAS,GAAG,OAAO;;CAIpC,SAAS,eAAe,QAAqC;EAC3D,MAAM,MAAM,IAAI,iBAAiB;AAEjC,OAAK,MAAM,QAAQ,OAAO,KAAK,SAAS,EAAE;AACxC,OAAI,EAAE,QAAQ,QAAS;GAEvB,MAAM,aADQ,SAAS,MACE,UAAU,OAAO,MAA4B;AAEtE,OAAI,eAAe,kBAAkB,MAAO;AAC5C,OAAI,eAAe,KAAM;AAEzB,OAAI,IAAI,UAAU,KAAK,EAAE,WAAW;;AAGtC,SAAO;;CAIT,SAAS,OACP,WACkE;EAIlE,MAAM,oBAA+D,EAAE;EACvE,MAAM,aAAqC,EAAE;AAC7C,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,UAAU,EAAE;GACpD,MAAM,WAAW,aAAa,KAAK,MAA0B;AAC7D,qBAAkB,OAAO,SAAS;AAClC,OAAI,SAAS,OACX,YAAW,OAAO,SAAS;;AAY/B,SAAO,gBARgB;GACrB,GAAG;GACH,GAAG;GACJ,EAG+C;GAAE,GAAG;GAAS,GAAG;GAAY,CAEZ;;CAInE,SAAS,KAAiC,GAAG,MAA+C;EAC1F,MAAM,eAA0D,EAAE;EAClE,MAAM,gBAAwC,EAAE;AAEhD,OAAK,MAAM,OAAO,MAAM;AACtB,gBAAa,OAAO,SAAS;AAC7B,OAAI,OAAO,QACT,eAAc,OAAO,QAAQ;;AAIjC,SAAO,gBACL,cACA,cACD;;CAYH,SAAS,iBAAe,SAAiD;AACvE,SAAO,eAAqB,UAAU,SAAS,OAAO,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC;;CAS/E,eAAe,OAAmB;AAChC,MAAI,OAAO,WAAW,YACpB,OAAM,IAAI,MACR,gGAED;AAGH,SAAO,UADK,MAAM,oBAAoB,CACjB;;AAgBvB,QAb8C;EAC5C;EACA;EACA,gBAAA;EACA;EACA;EACA;EACA;EACA;EACA,QAAQ;EACR,SAAS,OAAO,OAAO,EAAE,GAAG,SAAS,CAAC;EACvC"}

package/dist/_chunks/define-Dz1bqwaS.js

@@ -0,0 +1,106 @@
+import { a as validateSync, i as isStandardSchema, r as isCodec } from "./schema-bridge-C4SwjCQD.js";
+//#region src/segment-params/define.ts
+var _rawSegmentParams;
+/**
+* Register the rawSegmentParams function. Called once at module load time
+* from request-context.ts to avoid dynamic import at call time.
+* @internal
+*/
+function _setRawSegmentParamsFn(fn) {
+	_rawSegmentParams = fn;
+}
+function getRawSegmentParams() {
+	if (!_rawSegmentParams) throw new Error("[timber] segmentParams.load() is only available on the server. Use useSegmentParams() on the client.");
+	return _rawSegmentParams();
+}
+/**
+* Wrap a Standard Schema into a Codec for route params.
+*
+* Unlike fromSchema for search params:
+* - Parse throws on failure (no fallback to default)
+* - Serialize returns string (not null)
+*/
+function fromParamSchema(fieldName, schema) {
+	return {
+		parse(value) {
+			const result = validateSync(schema, Array.isArray(value) ? value : value);
+			if (!result.issues) return result.value;
+			const messages = result.issues.map((i) => i.message).join(", ");
+			throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);
+		},
+		serialize(value) {
+			if (value === null || value === void 0) return null;
+			if (Array.isArray(value)) return value.join("/");
+			return String(value);
+		}
+	};
+}
+/**
+* Resolve a field value to a Codec. Auto-detects Standard Schema objects.
+*/
+function resolveField(fieldName, value) {
+	if (isCodec(value)) return value;
+	if (isStandardSchema(value)) return fromParamSchema(fieldName, value);
+	throw new Error(`[timber] defineSegmentParams: field '${fieldName}' is not a valid codec or Standard Schema. Expected an object with { parse, serialize } methods, or a Standard Schema object (Zod, Valibot, ArkType).`);
+}
+/**
+* Validate that no codec's serialize returns null.
+* Route params are structural — they must produce a valid path segment.
+*/
+function validateSerialize(codecMap) {
+	for (const [key, codec] of Object.entries(codecMap)) try {
+		const testValue = codec.parse("test");
+		if (codec.serialize(testValue) === null) throw new Error(`[timber] defineSegmentParams: field '${key}' codec.serialize() returned null.\n  Route params are path segments — they cannot be omitted.\n  Ensure serialize() always returns a string.`);
+	} catch (e) {
+		if (e instanceof Error && e.message.includes("returned null")) throw e;
+	}
+}
+/**
+* Create a ParamsDefinition from a map of codecs and/or Standard Schema objects.
+*
+* ```ts
+* // app/products/[id]/layout.tsx
+* import { defineSegmentParams } from '@timber-js/app/segment-params'
+* import { z } from 'zod/v4'
+*
+* export const segmentParams = defineSegmentParams({
+*   id: z.coerce.number().int().positive(),
+* })
+* ```
+*/
+function defineSegmentParams(codecs) {
+	const resolvedCodecs = {};
+	for (const [key, value] of Object.entries(codecs)) resolvedCodecs[key] = resolveField(key, value);
+	validateSerialize(resolvedCodecs);
+	function parse(raw) {
+		const result = {};
+		for (const [key, codec] of Object.entries(resolvedCodecs)) {
+			const rawValue = raw[key];
+			result[key] = codec.parse(rawValue);
+		}
+		return result;
+	}
+	function serialize(values) {
+		const result = {};
+		for (const [key, codec] of Object.entries(resolvedCodecs)) {
+			const serialized = codec.serialize(values[key]);
+			if (serialized === null) throw new Error(`[timber] params.serialize: field '${key}' serialized to null. Route params must produce a valid path segment.`);
+			result[key] = serialized;
+		}
+		return result;
+	}
+	async function load() {
+		if (typeof window !== "undefined") throw new Error("[timber] segmentParams.load() is server-only. Use useSegmentParams() on the client.");
+		return await getRawSegmentParams();
+	}
+	return {
+		parse,
+		serialize,
+		load,
+		codecs: resolvedCodecs
+	};
+}
+//#endregion
+export { defineSegmentParams as n, _setRawSegmentParamsFn as t };
+
+//# sourceMappingURL=define-Dz1bqwaS.js.map

package/dist/_chunks/define-Dz1bqwaS.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-Dz1bqwaS.js","names":[],"sources":["../../src/segment-params/define.ts"],"sourcesContent":["/**\n * defineSegmentParams — factory for typed route param coercion.\n *\n * Creates a ParamsDefinition that coerces raw string params from the\n * URL into typed values. Used by exporting from params.ts (segment-level)\n * convention file.\n *\n * Reuses the shared Codec<T> protocol with Standard Schema auto-detection,\n * same pattern as defineSearchParams. Runtime constraints are stricter:\n * - serialize must return string (not null — path segments can't be omitted)\n * - parse throwing → 404 (invalid param value)\n *\n * Design doc: design/07a-route-params-triage.md\n */\n\nimport type { Codec } from '../codec.js';\nimport {\n  type StandardSchemaV1,\n  validateSync,\n  isStandardSchema,\n  isCodec,\n} from '../schema-bridge.js';\n\n// ---------------------------------------------------------------------------\n// Server-only ALS reference for .load()\n// ---------------------------------------------------------------------------\n\n// Same pattern as search-params: eagerly registered at server startup\n// to avoid dynamic imports that lose ALS context. See TIM-523.\nlet _rawSegmentParams: (() => Promise<Record<string, string | string[]>>) | undefined;\n\n/**\n * Register the rawSegmentParams function. Called once at module load time\n * from request-context.ts to avoid dynamic import at call time.\n * @internal\n */\nexport function _setRawSegmentParamsFn(fn: () => Promise<Record<string, string | string[]>>): void {\n  _rawSegmentParams = fn;\n}\n\nfunction getRawSegmentParams(): Promise<Record<string, string | string[]>> {\n  if (!_rawSegmentParams) {\n    throw new Error(\n      '[timber] segmentParams.load() is only available on the server. ' +\n        'Use useSegmentParams() on the client.'\n    );\n  }\n  return _rawSegmentParams();\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Infer the output type from a Codec or StandardSchemaV1. */\nexport type InferParamField<V> =\n  V extends Codec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;\n\n/** Acceptable field value for defineParams: a Codec or a Standard Schema. */\nexport type ParamField<T = unknown> = Codec<T> | StandardSchemaV1<T>;\n\nexport type { StandardSchemaV1 };\n\n/**\n * A typed route params definition.\n *\n * Returned by defineParams(). Provides parse (string → typed) and\n * serialize (typed → string) for each declared param.\n */\nexport interface ParamsDefinition<T extends Record<string, unknown>> {\n  /** Parse raw string params into typed values. Throws on invalid values. */\n  parse(raw: Record<string, string | string[]>): T;\n\n  /** Serialize typed values back to strings for URL construction. */\n  serialize(values: T): Record<string, string>;\n\n  /**\n   * Load typed segment params from the current request context (ALS).\n   *\n   * Server-only. Reads rawSegmentParams() from ALS and coerces through\n   * this definition's codecs, returning fully typed params.\n   *\n   * ```ts\n   * // app/products/[id]/params.ts\n   * export const segmentParams = defineSegmentParams({ id: z.coerce.number() })\n   *\n   * // app/products/[id]/page.tsx\n   * import { segmentParams } from './params'\n   * export default async function Page() {\n   *   const { id } = await segmentParams.load() // id: number\n   * }\n   * ```\n   */\n  load(): Promise<T>;\n\n  /** Read-only codec map. */\n  codecs: { [K in keyof T]: Codec<T[K]> };\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a Standard Schema into a Codec for route params.\n *\n * Unlike fromSchema for search params:\n * - Parse throws on failure (no fallback to default)\n * - Serialize returns string (not null)\n */\nfunction fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // Route params are always strings (single segment) or string[] (catch-all)\n      const input = Array.isArray(value) ? value : value;\n\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // For route params, parse failure means the param is invalid → throw\n      const messages = result.issues.map((i) => i.message).join(', ');\n      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      // Catch-all segments produce arrays — join with '/' for path reconstruction\n      if (Array.isArray(value)) {\n        return value.join('/');\n      }\n      return String(value);\n    },\n  };\n}\n\n/**\n * Resolve a field value to a Codec. Auto-detects Standard Schema objects.\n */\nfunction resolveField(fieldName: string, value: ParamField): Codec<unknown> {\n  if (isCodec(value)) {\n    return value;\n  }\n\n  if (isStandardSchema(value)) {\n    return fromParamSchema(fieldName, value);\n  }\n\n  throw new Error(\n    `[timber] defineSegmentParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +\n      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n      `(Zod, Valibot, ArkType).`\n  );\n}\n\n/**\n * Validate that no codec's serialize returns null.\n * Route params are structural — they must produce a valid path segment.\n */\nfunction validateSerialize(codecMap: Record<string, Codec<unknown>>): void {\n  for (const [key, codec] of Object.entries(codecMap)) {\n    // Test serialize with a sample parsed value to check for null\n    // We can't exhaustively test, but we can check that serialize(parse(\"test\"))\n    // doesn't return null for a basic input.\n    try {\n      const testValue = codec.parse('test');\n      const serialized = codec.serialize(testValue);\n      if (serialized === null) {\n        throw new Error(\n          `[timber] defineSegmentParams: field '${key}' codec.serialize() returned null.\\n` +\n            `  Route params are path segments — they cannot be omitted.\\n` +\n            `  Ensure serialize() always returns a string.`\n        );\n      }\n    } catch (e) {\n      // parse('test') may throw for strict codecs (e.g., number-only).\n      // That's fine — it means the codec validates. We only care about\n      // serialize returning null, which we can't test without a valid value.\n      if (e instanceof Error && e.message.includes('returned null')) {\n        throw e;\n      }\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a ParamsDefinition from a map of codecs and/or Standard Schema objects.\n *\n * ```ts\n * // app/products/[id]/layout.tsx\n * import { defineSegmentParams } from '@timber-js/app/segment-params'\n * import { z } from 'zod/v4'\n *\n * export const segmentParams = defineSegmentParams({\n *   id: z.coerce.number().int().positive(),\n * })\n * ```\n */\nexport function defineSegmentParams<C extends Record<string, ParamField>>(\n  codecs: C\n): ParamsDefinition<{ [K in keyof C]: InferParamField<C[K]> }> {\n  type T = { [K in keyof C]: InferParamField<C[K]> };\n\n  const resolvedCodecs: Record<string, Codec<unknown>> = {};\n\n  for (const [key, value] of Object.entries(codecs)) {\n    resolvedCodecs[key] = resolveField(key, value as ParamField);\n  }\n\n  // Validate that serialize doesn't return null\n  validateSerialize(resolvedCodecs);\n\n  // ---- parse ----\n  function parse(raw: Record<string, string | string[]>): T {\n    const result: Record<string, unknown> = {};\n\n    for (const [key, codec] of Object.entries(resolvedCodecs)) {\n      const rawValue = raw[key];\n      // Route params are always present (the route matched)\n      result[key] = codec.parse(rawValue);\n    }\n\n    return result as T;\n  }\n\n  // ---- serialize ----\n  function serialize(values: T): Record<string, string> {\n    const result: Record<string, string> = {};\n\n    for (const [key, codec] of Object.entries(resolvedCodecs)) {\n      const serialized = codec.serialize(values[key as keyof T] as unknown);\n      if (serialized === null) {\n        throw new Error(\n          `[timber] params.serialize: field '${key}' serialized to null. ` +\n            `Route params must produce a valid path segment.`\n        );\n      }\n      result[key] = serialized;\n    }\n\n    return result;\n  }\n\n  // ---- load ----\n  // ALS-backed: reads segment params from the current request context.\n  // Server-only — throws on client.\n  //\n  // The pipeline already coerces params via coerceSegmentParams() which\n  // calls parse() and stores typed values in ALS via setSegmentParams().\n  // We return those directly instead of re-parsing, because codecs may\n  // not be idempotent (e.g., a codec that only accepts raw strings would\n  // throw if given an already-parsed value). See TIM-574.\n  async function load(): Promise<T> {\n    if (typeof window !== 'undefined') {\n      throw new Error(\n        '[timber] segmentParams.load() is server-only. ' + 'Use useSegmentParams() on the client.'\n      );\n    }\n    const params = await getRawSegmentParams();\n    // params are already coerced by the pipeline — return as-is.\n    return params as unknown as T;\n  }\n\n  const definition: ParamsDefinition<T> = {\n    parse,\n    serialize,\n    load,\n    codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },\n  };\n\n  return definition;\n}\n"],"mappings":";;AA6BA,IAAI;;;;;;AAOJ,SAAgB,uBAAuB,IAA4D;AACjG,qBAAoB;;AAGtB,SAAS,sBAAkE;AACzE,KAAI,CAAC,kBACH,OAAM,IAAI,MACR,uGAED;AAEH,QAAO,mBAAmB;;;;;;;;;AA+D5B,SAAS,gBAAmB,WAAmB,QAAuC;AACpF,QAAO;EACL,MAAM,OAAyC;GAI7C,MAAM,SAAS,aAAa,QAFd,MAAM,QAAQ,MAAM,GAAG,QAAQ,MAEH;AAC1C,OAAI,CAAC,OAAO,OACV,QAAO,OAAO;GAIhB,MAAM,WAAW,OAAO,OAAO,KAAK,MAAM,EAAE,QAAQ,CAAC,KAAK,KAAK;AAC/D,SAAM,IAAI,MAAM,mBAAmB,UAAU,qBAAqB,WAAW;;EAG/E,UAAU,OAAyB;AACjC,OAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B,QAAO;AAGT,OAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,MAAM,KAAK,IAAI;AAExB,UAAO,OAAO,MAAM;;EAEvB;;;;;AAMH,SAAS,aAAa,WAAmB,OAAmC;AAC1E,KAAI,QAAQ,MAAM,CAChB,QAAO;AAGT,KAAI,iBAAiB,MAAM,CACzB,QAAO,gBAAgB,WAAW,MAAM;AAG1C,OAAM,IAAI,MACR,wCAAwC,UAAU,uJAGnD;;;;;;AAOH,SAAS,kBAAkB,UAAgD;AACzE,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,CAIjD,KAAI;EACF,MAAM,YAAY,MAAM,MAAM,OAAO;AAErC,MADmB,MAAM,UAAU,UAAU,KAC1B,KACjB,OAAM,IAAI,MACR,wCAAwC,IAAI,+IAG7C;UAEI,GAAG;AAIV,MAAI,aAAa,SAAS,EAAE,QAAQ,SAAS,gBAAgB,CAC3D,OAAM;;;;;;;;;;;;;;;;AAuBd,SAAgB,oBACd,QAC6D;CAG7D,MAAM,iBAAiD,EAAE;AAEzD,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,CAC/C,gBAAe,OAAO,aAAa,KAAK,MAAoB;AAI9D,mBAAkB,eAAe;CAGjC,SAAS,MAAM,KAA2C;EACxD,MAAM,SAAkC,EAAE;AAE1C,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,eAAe,EAAE;GACzD,MAAM,WAAW,IAAI;AAErB,UAAO,OAAO,MAAM,MAAM,SAAS;;AAGrC,SAAO;;CAIT,SAAS,UAAU,QAAmC;EACpD,MAAM,SAAiC,EAAE;AAEzC,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,eAAe,EAAE;GACzD,MAAM,aAAa,MAAM,UAAU,OAAO,KAA2B;AACrE,OAAI,eAAe,KACjB,OAAM,IAAI,MACR,qCAAqC,IAAI,uEAE1C;AAEH,UAAO,OAAO;;AAGhB,SAAO;;CAYT,eAAe,OAAmB;AAChC,MAAI,OAAO,WAAW,YACpB,OAAM,IAAI,MACR,sFACD;AAIH,SAFe,MAAM,qBAAqB;;AAY5C,QAPwC;EACtC;EACA;EACA;EACA,QAAQ;EACT"}

package/dist/_chunks/define-cookie-B5mewxwM.js

@@ -0,0 +1,93 @@
+//#region src/cookies/define-cookie.ts
+var _useCookieModule;
+function getUseCookieModule() {
+	if (!_useCookieModule) 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
+*/
+function _registerUseCookieModule(mod) {
+	_useCookieModule = mod;
+}
+/**
+* Define a typed cookie.
+*
+* ```ts
+* import { defineCookie } from '@timber-js/app/cookies';
+* import { fromSchema } from '@timber-js/app/codec';
+* import { z } from 'zod/v4';
+*
+* export const themeCookie = defineCookie('theme', {
+*   codec: fromSchema(z.enum(['light', 'dark', 'system']).default('system')),
+*   httpOnly: false,
+*   maxAge: 60 * 60 * 24 * 365,
+* });
+*
+* // Server
+* const theme = await themeCookie.getCookie();
+* await themeCookie.setCookie('dark');
+*
+* // Client
+* const [theme, setTheme] = themeCookie.useCookie();
+* ```
+*/
+function defineCookie(name, options) {
+	const { codec, ...cookieOpts } = options;
+	const resolvedOptions = { ...cookieOpts };
+	return {
+		name,
+		options: resolvedOptions,
+		codec,
+		async getCookie() {
+			const { cookies } = await import("./request-context-CywiO4jV.js").then((n) => n.l);
+			const raw = cookies().get(name);
+			return codec.parse(raw);
+		},
+		async setCookie(value) {
+			const { cookies } = await import("./request-context-CywiO4jV.js").then((n) => n.l);
+			const serialized = codec.serialize(value);
+			if (serialized === null) cookies().delete(name, {
+				path: resolvedOptions.path,
+				domain: resolvedOptions.domain
+			});
+			else cookies().set(name, serialized, resolvedOptions);
+		},
+		async deleteCookie() {
+			const { cookies } = await import("./request-context-CywiO4jV.js").then((n) => n.l);
+			cookies().delete(name, {
+				path: resolvedOptions.path,
+				domain: resolvedOptions.domain
+			});
+		},
+		useCookie() {
+			const { useCookie: useRawCookie } = getUseCookieModule();
+			const [raw, setRaw, deleteRaw] = useRawCookie(name, {
+				path: resolvedOptions.path,
+				domain: resolvedOptions.domain,
+				maxAge: resolvedOptions.maxAge,
+				expires: resolvedOptions.expires,
+				sameSite: resolvedOptions.sameSite,
+				secure: resolvedOptions.secure
+			});
+			const parsed = codec.parse(raw);
+			const setTyped = (value) => {
+				const serialized = codec.serialize(value);
+				if (serialized === null) deleteRaw();
+				else setRaw(serialized);
+			};
+			return [
+				parsed,
+				setTyped,
+				deleteRaw
+			];
+		}
+	};
+}
+//#endregion
+export { defineCookie as n, _registerUseCookieModule as t };
+
+//# sourceMappingURL=define-cookie-B5mewxwM.js.map

package/dist/_chunks/define-cookie-B5mewxwM.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-cookie-B5mewxwM.js","names":[],"sources":["../../src/cookies/define-cookie.ts"],"sourcesContent":["/**\n * defineCookie — typed cookie definitions.\n *\n * Bundles name + codec + options into a reusable CookieDefinition<T>\n * with async .getCookie(), .setCookie(), .deleteCookie() server methods\n * and a sync .useCookie() client hook.\n *\n * Server methods are async to future-proof the API for v2 features\n * (signed cookies via crypto.subtle, encrypted cookies, external stores).\n *\n * Reuses the SearchParamCodec protocol via fromSchema() bridge.\n * Validation on read returns the codec default (never throws).\n *\n * IMPORTANT: This module must NOT have top-level value imports from either\n * server or client modules. Server methods lazy-import request-context;\n * useCookie() lazy-imports use-cookie. This ensures:\n * - Client bundles don't pull in ALS/server code\n * - RSC bundles don't pull in useSyncExternalStore/client code\n * - Tree-shaking is not required for correctness\n *\n * See design/29-cookies.md §\"Typed Cookies with Schema Validation\"\n */\n\nimport type { CookieOptions } from '../server/request-context.js';\nimport type { ClientCookieOptions } from '../client/use-cookie.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\nimport type { Codec } from '../codec.js';\n\n/**\n * A codec that converts between string cookie values and typed values.\n * Type alias for the shared Codec<T> protocol.\n */\nexport type CookieCodec<T> = Codec<T>;\n\n/** Options for defineCookie: codec + CookieOptions merged. */\nexport interface DefineCookieOptions<T> extends CookieOptions {\n  /** Codec for parsing/serializing the cookie value. */\n  codec: CookieCodec<T>;\n}\n\n/** A fully typed cookie definition with server and client methods. */\nexport interface CookieDefinition<T> {\n  /** The cookie name. */\n  readonly name: string;\n  /** The resolved cookie options (without codec). */\n  readonly options: CookieOptions;\n  /** The codec used for parsing/serializing. */\n  readonly codec: CookieCodec<T>;\n\n  /** Server: read the typed value from the current request. */\n  getCookie(): Promise<T>;\n  /** Server: set the typed value on the response. */\n  setCookie(value: T): Promise<void>;\n  /** Server: delete the cookie. */\n  deleteCookie(): Promise<void>;\n\n  /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */\n  useCookie(): [T, (value: T) => void, () => void];\n}\n\n// ─── Lazy Module References ───────────────────────────────────────────────\n//\n// These are resolved on first use, not at module load time. This prevents\n// the server module graph from pulling in client code and vice versa.\n// The dynamic import() in server methods is natural (they're async).\n// For useCookie() (sync), we cache the module reference after first load.\n\nlet _useCookieModule: typeof import('../client/use-cookie.js') | undefined;\n\nfunction getUseCookieModule(): typeof import('../client/use-cookie.js') {\n  if (!_useCookieModule) {\n    // In the client/SSR environment, this module is already in the module\n    // graph (imported by the client entry). The throw is a safeguard —\n    // if useCookie() is somehow called before the module is available,\n    // the developer gets a clear error instead of a silent failure.\n    throw new Error(\n      '[timber] defineCookie().useCookie() requires @timber-js/app/client to be loaded. ' +\n        'This hook can only be used in client components.'\n    );\n  }\n  return _useCookieModule;\n}\n\n/**\n * Register the client cookie module. Called by the client entry to wire\n * up the lazy reference without a top-level import.\n *\n * @internal — framework use only\n */\nexport function _registerUseCookieModule(mod: typeof import('../client/use-cookie.js')): void {\n  _useCookieModule = mod;\n}\n\n// ─── Factory ──────────────────────────────────────────────────────────────\n\n/**\n * Define a typed cookie.\n *\n * ```ts\n * import { defineCookie } from '@timber-js/app/cookies';\n * import { fromSchema } from '@timber-js/app/codec';\n * import { z } from 'zod/v4';\n *\n * export const themeCookie = defineCookie('theme', {\n *   codec: fromSchema(z.enum(['light', 'dark', 'system']).default('system')),\n *   httpOnly: false,\n *   maxAge: 60 * 60 * 24 * 365,\n * });\n *\n * // Server\n * const theme = await themeCookie.getCookie();\n * await themeCookie.setCookie('dark');\n *\n * // Client\n * const [theme, setTheme] = themeCookie.useCookie();\n * ```\n */\nexport function defineCookie<T>(\n  name: string,\n  options: DefineCookieOptions<T>\n): CookieDefinition<T> {\n  const { codec, ...cookieOpts } = options;\n  const resolvedOptions: CookieOptions = { ...cookieOpts };\n\n  return {\n    name,\n    options: resolvedOptions,\n    codec,\n\n    async getCookie(): Promise<T> {\n      const { cookies } = await import('../server/request-context.js');\n      const jar = cookies();\n      const raw = jar.get(name);\n      return codec.parse(raw);\n    },\n\n    async setCookie(value: T): Promise<void> {\n      const { cookies } = await import('../server/request-context.js');\n      const serialized = codec.serialize(value);\n      if (serialized === null) {\n        cookies().delete(name, {\n          path: resolvedOptions.path,\n          domain: resolvedOptions.domain,\n        });\n      } else {\n        cookies().set(name, serialized, resolvedOptions);\n      }\n    },\n\n    async deleteCookie(): Promise<void> {\n      const { cookies } = await import('../server/request-context.js');\n      cookies().delete(name, {\n        path: resolvedOptions.path,\n        domain: resolvedOptions.domain,\n      });\n    },\n\n    useCookie(): [T, (value: T) => void, () => void] {\n      const { useCookie: useRawCookie } = getUseCookieModule();\n\n      // Extract client-safe options (no httpOnly — client cookies can't be httpOnly)\n      const clientOpts: ClientCookieOptions = {\n        path: resolvedOptions.path,\n        domain: resolvedOptions.domain,\n        maxAge: resolvedOptions.maxAge,\n        expires: resolvedOptions.expires,\n        sameSite: resolvedOptions.sameSite,\n        secure: resolvedOptions.secure,\n      };\n\n      const [raw, setRaw, deleteRaw] = useRawCookie(name, clientOpts);\n      const parsed = codec.parse(raw);\n\n      const setTyped = (value: T): void => {\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          deleteRaw();\n        } else {\n          setRaw(serialized);\n        }\n      };\n\n      return [parsed, setTyped, deleteRaw];\n    },\n  };\n}\n"],"mappings":";AAqEA,IAAI;AAEJ,SAAS,qBAA+D;AACtE,KAAI,CAAC,iBAKH,OAAM,IAAI,MACR,oIAED;AAEH,QAAO;;;;;;;;AAST,SAAgB,yBAAyB,KAAqD;AAC5F,oBAAmB;;;;;;;;;;;;;;;;;;;;;;;;AA2BrB,SAAgB,aACd,MACA,SACqB;CACrB,MAAM,EAAE,OAAO,GAAG,eAAe;CACjC,MAAM,kBAAiC,EAAE,GAAG,YAAY;AAExD,QAAO;EACL;EACA,SAAS;EACT;EAEA,MAAM,YAAwB;GAC5B,MAAM,EAAE,YAAY,MAAM,OAAO,iCAAA,MAAA,MAAA,EAAA,EAAA;GAEjC,MAAM,MADM,SAAS,CACL,IAAI,KAAK;AACzB,UAAO,MAAM,MAAM,IAAI;;EAGzB,MAAM,UAAU,OAAyB;GACvC,MAAM,EAAE,YAAY,MAAM,OAAO,iCAAA,MAAA,MAAA,EAAA,EAAA;GACjC,MAAM,aAAa,MAAM,UAAU,MAAM;AACzC,OAAI,eAAe,KACjB,UAAS,CAAC,OAAO,MAAM;IACrB,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACzB,CAAC;OAEF,UAAS,CAAC,IAAI,MAAM,YAAY,gBAAgB;;EAIpD,MAAM,eAA8B;GAClC,MAAM,EAAE,YAAY,MAAM,OAAO,iCAAA,MAAA,MAAA,EAAA,EAAA;AACjC,YAAS,CAAC,OAAO,MAAM;IACrB,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACzB,CAAC;;EAGJ,YAAiD;GAC/C,MAAM,EAAE,WAAW,iBAAiB,oBAAoB;GAYxD,MAAM,CAAC,KAAK,QAAQ,aAAa,aAAa,MATN;IACtC,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACxB,QAAQ,gBAAgB;IACxB,SAAS,gBAAgB;IACzB,UAAU,gBAAgB;IAC1B,QAAQ,gBAAgB;IACzB,CAE8D;GAC/D,MAAM,SAAS,MAAM,MAAM,IAAI;GAE/B,MAAM,YAAY,UAAmB;IACnC,MAAM,aAAa,MAAM,UAAU,MAAM;AACzC,QAAI,eAAe,KACjB,YAAW;QAEX,QAAO,WAAW;;AAItB,UAAO;IAAC;IAAQ;IAAU;IAAU;;EAEvC"}