@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.40

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-Ba7URUIn.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-Ba7URUIn.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"als-registry-Ba7URUIn.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';\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\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":";;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAa,oBAAoB,IAAI,mBAAwC;;AA0D7E,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-ECi_61pb.js

@@ -0,0 +1,108 @@
+//#region src/server/debug.ts
+/**
+* Runtime debug flag for timber.js.
+*
+* Two distinct functions for two distinct security levels:
+*
+* ## `isDebug()` — server-side logging only
+*
+* Returns true when timber's debug/warning messages should be written to
+* stderr / the server console. This NEVER affects what is sent to the
+* client (no error details, no timing headers, no stack traces).
+*
+* Active when any of:
+* - `NODE_ENV !== 'production'` (standard dev mode)
+* - `TIMBER_DEBUG` env var is set to a truthy value at runtime
+* - `timber.config.ts` has `debug: true`
+*
+* ## `isDevMode()` — client-visible dev behavior
+*
+* Returns true ONLY when `NODE_ENV !== 'production'`. This gates anything
+* that changes what clients can observe:
+* - Dev error pages with stack traces (fallback-error.ts)
+* - Detailed Server-Timing headers (pipeline.ts)
+* - Error messages in action INTERNAL_ERROR payloads (action-client.ts)
+* - Pipeline error handler wiring (Vite overlay)
+*
+* `isDevMode()` is statically replaced in production builds → the guarded
+* code is tree-shaken to zero bytes. TIMBER_DEBUG cannot enable it.
+*
+* Usage:
+*   In Cloudflare Workers wrangler.toml:
+*     [vars]
+*     TIMBER_DEBUG = "1"
+*
+*   In Node.js:
+*     TIMBER_DEBUG=1 node server.js
+*
+*   In timber.config.ts:
+*     export default { debug: true }
+*
+* See design/13-security.md for the security taxonomy.
+* See design/18-build-system.md for build pipeline details.
+*/
+/**
+* Check if the application is running in development mode.
+*
+* This is the ONLY function that should gate client-visible dev behavior:
+* - Dev error pages with stack traces
+* - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
+* - Error messages in action `INTERNAL_ERROR` payloads
+* - Pipeline error handler wiring (Vite overlay)
+*
+* Returns `process.env.NODE_ENV !== 'production'`, which is statically
+* replaced by the bundler in production builds. Code guarded by this
+* function is tree-shaken to zero bytes in production.
+*
+* TIMBER_DEBUG does NOT enable this — that would leak server internals
+* to clients. Use `isDebug()` for server-side-only logging.
+*/
+function isDevMode() {
+	return process.env.NODE_ENV !== "production";
+}
+/**
+* Config-level debug override. Set via `setDebugFromConfig()` during
+* initialization when timber.config.ts has `debug: true`.
+*/
+var _configDebug = false;
+/**
+* Check if timber debug logging is active (server-side only).
+*
+* Returns true if ANY of these conditions hold:
+* - NODE_ENV is not 'production' (standard dev mode)
+* - TIMBER_DEBUG environment variable is set to a truthy value at runtime
+* - timber.config.ts has `debug: true`
+*
+* This function controls ONLY server-side logging — messages written to
+* stderr or the server console. It NEVER affects client-visible behavior
+* (error pages, response headers, action payloads). For client-visible
+* behavior, use `isDevMode()`.
+*
+* The TIMBER_DEBUG check is deliberately written as a dynamic property
+* access so bundlers cannot statically replace it.
+*/
+function isDebug() {
+	if (process.env.NODE_ENV !== "production") return true;
+	if (_configDebug) return true;
+	return _readTimberDebugEnv();
+}
+/**
+* Read TIMBER_DEBUG from the environment at runtime.
+*
+* Extracted to a separate function to:
+* 1. Prevent bundler inlining (cross-module function calls are not inlined)
+* 2. Handle platforms where `process` may not exist (Cloudflare Workers)
+* 3. Support globalThis.__TIMBER_DEBUG for programmatic control
+*/
+function _readTimberDebugEnv() {
+	if (globalThis.__TIMBER_DEBUG) return true;
+	try {
+		const val = typeof process !== "undefined" && process.env ? process.env["TIMBER_DEBUG"] : void 0;
+		if (val && val !== "0" && val !== "false") return true;
+	} catch {}
+	return false;
+}
+//#endregion
+export { isDevMode as n, isDebug as t };
+
+//# 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-cookie-BmKbSyp0.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/search-params';
+* 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-BxYIJM24.js").then((n) => n.l);
+			const raw = cookies().get(name);
+			return codec.parse(raw);
+		},
+		async setCookie(value) {
+			const { cookies } = await import("./request-context-BxYIJM24.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-BxYIJM24.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-BmKbSyp0.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-cookie-BmKbSyp0.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/search-params';\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,qBAA8D;AACrE,KAAI,CAAC,iBAKH,OAAM,IAAI,MACR,oIAED;AAEH,QAAO;;;;;;;;AAST,SAAgB,yBAAyB,KAAoD;AAC3F,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"}

package/dist/_chunks/error-boundary-BAN3751q.js

@@ -0,0 +1,211 @@
+import { Component, createElement } from "react";
+//#region src/client/state.ts
+/** The global router singleton — set once during bootstrap. */
+var globalRouter = null;
+function _setGlobalRouter(router) {
+	globalRouter = router;
+}
+/**
+* ALS-backed SSR data provider. When registered, getSsrData() reads from
+* this function (ALS store) instead of module-level currentSsrData.
+*/
+var ssrDataProvider;
+/** Fallback SSR data for tests and environments without ALS. */
+var currentSsrData;
+function _setCurrentSsrData(data) {
+	currentSsrData = data;
+}
+/** Current route params snapshot — replaced (not mutated) on each navigation. */
+var currentParams = {};
+function _setCurrentParams(params) {
+	currentParams = params;
+}
+/** Cached search string — avoids reparsing when URL hasn't changed. */
+var cachedSearch = "";
+var cachedSearchParams = new URLSearchParams();
+function _setCachedSearch(search, params) {
+	cachedSearch = search;
+	cachedSearchParams = params;
+}
+//#endregion
+//#region src/client/ssr-data.ts
+/**
+* SSR Data — per-request state for client hooks during server-side rendering.
+*
+* RSC and SSR are separate Vite module graphs (see design/18-build-system.md),
+* so the RSC environment's request-context ALS is not visible to SSR modules.
+* This module provides getter/setter functions that ssr-entry.ts uses to
+* populate per-request data for React's render.
+*
+* Request isolation: On the server, ssr-entry.ts registers an ALS-backed
+* provider via registerSsrDataProvider(). getSsrData() reads from the ALS
+* store, ensuring correct per-request data even when Suspense boundaries
+* resolve asynchronously across concurrent requests. The module-level
+* setSsrData/clearSsrData functions are kept as a fallback for tests
+* and environments without ALS.
+*
+* IMPORTANT: This module must NOT import node:async_hooks or any Node.js-only
+* APIs, as it's imported by 'use client' hooks that are bundled for the browser.
+* The ALS instance lives in ssr-entry.ts (server-only); this module only holds
+* a reference to the provider function.
+*
+* All mutable state is delegated to client/state.ts for singleton guarantees.
+* See design/18-build-system.md §"Singleton State Registry"
+*/
+/**
+* Set the SSR data for the current request via module-level state.
+*
+* In production, ssr-entry.ts uses ALS (runWithSsrData) instead.
+* This function is retained for tests and as a fallback.
+*/
+function setSsrData(data) {
+	_setCurrentSsrData(data);
+}
+/**
+* Clear the SSR data after rendering completes.
+*
+* In production, ALS scope handles cleanup automatically.
+* This function is retained for tests and as a fallback.
+*/
+function clearSsrData() {
+	_setCurrentSsrData(void 0);
+}
+/**
+* Read the current request's SSR data. Returns undefined when called
+* outside an SSR render (i.e. on the client after hydration).
+*
+* Prefers the ALS-backed provider when registered (server-side),
+* falling back to module-level state (tests, legacy).
+*
+* Used by client hooks' server snapshot functions.
+*/
+function getSsrData() {
+	if (ssrDataProvider) return ssrDataProvider();
+	return currentSsrData;
+}
+//#endregion
+//#region src/client/error-boundary.tsx
+/**
+* Framework-injected React error boundary.
+*
+* Catches errors thrown by children and renders a fallback component
+* with the appropriate props based on error type:
+*   - DenySignal (4xx) → { status, dangerouslyPassData }
+*   - RenderError (5xx) → { error, digest, reset }
+*   - Unhandled error → { error, digest: null, reset }
+*
+* The `status` prop controls which errors this boundary catches:
+*   - Specific code (e.g. 403) → only that status
+*   - Category (400) → any 4xx
+*   - Category (500) → any 5xx
+*   - Omitted → catches everything (error.tsx behavior)
+*
+* See design/10-error-handling.md §"Status-Code Files"
+*/
+var _isUnloading = false;
+if (typeof window !== "undefined") {
+	window.addEventListener("beforeunload", () => {
+		_isUnloading = true;
+	});
+	window.addEventListener("pagehide", () => {
+		_isUnloading = true;
+	});
+}
+var TimberErrorBoundary = class extends Component {
+	constructor(props) {
+		super(props);
+		this.state = {
+			hasError: false,
+			error: null
+		};
+	}
+	static getDerivedStateFromError(error) {
+		if (_isUnloading) return {
+			hasError: false,
+			error: null
+		};
+		return {
+			hasError: true,
+			error
+		};
+	}
+	componentDidUpdate(prevProps) {
+		if (this.state.hasError && prevProps.children !== this.props.children) this.setState({
+			hasError: false,
+			error: null
+		});
+	}
+	/** Reset the error state so children re-render. */
+	reset = () => {
+		this.setState({
+			hasError: false,
+			error: null
+		});
+	};
+	render() {
+		if (!this.state.hasError || !this.state.error) return this.props.children;
+		const error = this.state.error;
+		const parsed = parseDigest(error);
+		if (parsed?.type === "redirect") throw error;
+		if (this.props.status != null) {
+			const errorStatus = getErrorStatus(parsed, error);
+			if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) throw error;
+		}
+		if (parsed?.type === "deny" && this.props.isSlotBoundary) {
+			const ssrData = getSsrData();
+			if (ssrData?._navContext) ssrData._navContext._denyHandledByBoundary = true;
+		}
+		if (this.props.fallbackElement != null) return this.props.fallbackElement;
+		if (parsed?.type === "deny") return createElement(this.props.fallbackComponent, {
+			status: parsed.status,
+			dangerouslyPassData: parsed.data
+		});
+		const digest = parsed?.type === "render-error" ? {
+			code: parsed.code,
+			data: parsed.data
+		} : null;
+		return createElement(this.props.fallbackComponent, {
+			error,
+			digest,
+			reset: this.reset
+		});
+	}
+};
+/**
+* Parse the structured digest from the error.
+* React sets `error.digest` from the string returned by RSC's onError.
+*/
+function parseDigest(error) {
+	const raw = error.digest;
+	if (typeof raw !== "string") return null;
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === "object" && typeof parsed.type === "string") return parsed;
+	} catch {}
+	return null;
+}
+/**
+* Extract the HTTP status code from a parsed digest or error message.
+* Falls back to message pattern matching for errors without a digest.
+*/
+function getErrorStatus(parsed, error) {
+	if (parsed?.type === "deny") return parsed.status;
+	if (parsed?.type === "render-error") return parsed.status;
+	if (parsed?.type === "redirect") return parsed.status;
+	const match = error.message.match(/^Access denied with status (\d+)$/);
+	if (match) return parseInt(match[1], 10);
+	return 500;
+}
+/**
+* Check whether an error's status matches the boundary's status filter.
+* Category markers (400, 500) match any status in that range.
+*/
+function statusMatches(boundaryStatus, errorStatus) {
+	if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;
+	if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;
+	return boundaryStatus === errorStatus;
+}
+//#endregion
+export { _setCachedSearch as a, cachedSearch as c, globalRouter as d, setSsrData as i, cachedSearchParams as l, clearSsrData as n, _setCurrentParams as o, getSsrData as r, _setGlobalRouter as s, TimberErrorBoundary as t, currentParams as u };
+
+//# sourceMappingURL=error-boundary-BAN3751q.js.map

package/dist/_chunks/error-boundary-BAN3751q.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-boundary-BAN3751q.js","names":[],"sources":["../../src/client/state.ts","../../src/client/ssr-data.ts","../../src/client/error-boundary.tsx"],"sourcesContent":["/**\n * Centralized client singleton state registry.\n *\n * ALL mutable module-level state that must have singleton semantics across\n * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,\n * use-params.ts, use-search-params.ts, unload-guard.ts) import from this file\n * and re-export thin wrapper functions.\n *\n * Why: In Vite dev, a module is instantiated separately if reached via different\n * import paths (e.g., relative `./foo.js` vs barrel `@timber-js/app/client`).\n * By centralizing all mutable state in a single module that is always reached\n * through the same dependency chain (barrel → wrapper → state.ts), we guarantee\n * a single instance of every piece of shared state.\n *\n * DO NOT import this file from outside client/. Server code must never depend\n * on client state. The barrel (client/index.ts) is the public entry point.\n *\n * See design/18-build-system.md §\"Module Singleton Strategy\" and\n * §\"Singleton State Registry\".\n */\n\nimport type { RouterInstance } from './router.js';\nimport type { SsrData } from './ssr-data.js';\n\n// ─── Router (from router-ref.ts) ──────────────────────────────────────────\n\n/** The global router singleton — set once during bootstrap. */\nexport let globalRouter: RouterInstance | null = null;\n\nexport function _setGlobalRouter(router: RouterInstance | null): void {\n  globalRouter = router;\n}\n\n// ─── SSR Data Provider (from ssr-data.ts) ──────────────────────────────────\n\n/**\n * ALS-backed SSR data provider. When registered, getSsrData() reads from\n * this function (ALS store) instead of module-level currentSsrData.\n */\nexport let ssrDataProvider: (() => SsrData | undefined) | undefined;\n\nexport function _setSsrDataProvider(provider: (() => SsrData | undefined) | undefined): void {\n  ssrDataProvider = provider;\n}\n\n/** Fallback SSR data for tests and environments without ALS. */\nexport let currentSsrData: SsrData | undefined;\n\nexport function _setCurrentSsrData(data: SsrData | undefined): void {\n  currentSsrData = data;\n}\n\n// ─── Route Params (from use-params.ts) ──────────────────────────────────────\n\n/** Current route params snapshot — replaced (not mutated) on each navigation. */\nexport let currentParams: Record<string, string | string[]> = {};\n\nexport function _setCurrentParams(params: Record<string, string | string[]>): void {\n  currentParams = params;\n}\n\n/** Listeners notified when currentParams changes. */\nexport const paramsListeners = new Set<() => void>();\n\n// ─── Search Params Cache (from use-search-params.ts) ────────────────────────\n\n/** Cached search string — avoids reparsing when URL hasn't changed. */\nexport let cachedSearch = '';\nexport let cachedSearchParams = new URLSearchParams();\n\nexport function _setCachedSearch(search: string, params: URLSearchParams): void {\n  cachedSearch = search;\n  cachedSearchParams = params;\n}\n\n// ─── Unload Guard (from unload-guard.ts) ─────────────────────────────────────\n\n/** Whether the page is currently being unloaded. */\nexport let unloading = false;\n\nexport function _setUnloading(value: boolean): void {\n  unloading = value;\n}\n","/**\n * SSR Data — per-request state for client hooks during server-side rendering.\n *\n * RSC and SSR are separate Vite module graphs (see design/18-build-system.md),\n * so the RSC environment's request-context ALS is not visible to SSR modules.\n * This module provides getter/setter functions that ssr-entry.ts uses to\n * populate per-request data for React's render.\n *\n * Request isolation: On the server, ssr-entry.ts registers an ALS-backed\n * provider via registerSsrDataProvider(). getSsrData() reads from the ALS\n * store, ensuring correct per-request data even when Suspense boundaries\n * resolve asynchronously across concurrent requests. The module-level\n * setSsrData/clearSsrData functions are kept as a fallback for tests\n * and environments without ALS.\n *\n * IMPORTANT: This module must NOT import node:async_hooks or any Node.js-only\n * APIs, as it's imported by 'use client' hooks that are bundled for the browser.\n * The ALS instance lives in ssr-entry.ts (server-only); this module only holds\n * a reference to the provider function.\n *\n * All mutable state is delegated to client/state.ts for singleton guarantees.\n * See design/18-build-system.md §\"Singleton State Registry\"\n */\n\nimport {\n  ssrDataProvider,\n  currentSsrData,\n  _setSsrDataProvider,\n  _setCurrentSsrData,\n} from './state.js';\n\n// ─── Types ────────────────────────────────────────────────────────\n\nexport interface SsrData {\n  /** The request's URL pathname (e.g. '/dashboard/settings') */\n  pathname: string;\n  /** The request's search params as a plain record */\n  searchParams: Record<string, string>;\n  /** The request's cookies as name→value pairs */\n  cookies: Map<string, string>;\n  /** The request's route params (e.g. { id: '123' }) */\n  params: Record<string, string | string[]>;\n  /**\n   * Mutable reference to NavContext for error boundary → RSC communication.\n   * When TimberErrorBoundary catches a DenySignal, it sets\n   * `_navContext._denyHandledByBoundary = true` to prevent the RSC entry\n   * from promoting the denial to page-level. See LOCAL-298.\n   */\n  _navContext?: { _denyHandledByBoundary?: boolean };\n}\n\n// ─── ALS-Backed Provider ─────────────────────────────────────────\n//\n// Server-side code (ssr-entry.ts) registers a provider that reads\n// from AsyncLocalStorage. This avoids importing node:async_hooks\n// in this browser-bundled module.\n//\n// Module singleton guarantee: In Vite's SSR environment, both\n// ssr-entry.ts (via #/client/ssr-data.js) and client component hooks\n// (via @timber-js/app/client) must resolve to the SAME module instance\n// of this file. The timber-shims plugin ensures this by remapping\n// @timber-js/app/client → src/client/index.ts in the SSR environment.\n// Without this remap, @timber-js/app/client resolves to dist/ (via\n// package.json exports), creating a split where registerSsrDataProvider\n// writes to one instance but getSsrData reads from another.\n// See timber-shims plugin resolveId for details.\n\n/**\n * Register an ALS-backed SSR data provider. Called once at module load\n * by ssr-entry.ts to wire up per-request data via AsyncLocalStorage.\n *\n * When registered, getSsrData() reads from the provider (ALS store)\n * instead of module-level state, ensuring correct isolation for\n * concurrent requests with streaming Suspense.\n */\nexport function registerSsrDataProvider(provider: () => SsrData | undefined): void {\n  _setSsrDataProvider(provider);\n}\n\n// ─── Module-Level Fallback ────────────────────────────────────────\n//\n// Used by tests and as a fallback when no ALS provider is registered.\n\n/**\n * Set the SSR data for the current request via module-level state.\n *\n * In production, ssr-entry.ts uses ALS (runWithSsrData) instead.\n * This function is retained for tests and as a fallback.\n */\nexport function setSsrData(data: SsrData): void {\n  _setCurrentSsrData(data);\n}\n\n/**\n * Clear the SSR data after rendering completes.\n *\n * In production, ALS scope handles cleanup automatically.\n * This function is retained for tests and as a fallback.\n */\nexport function clearSsrData(): void {\n  _setCurrentSsrData(undefined);\n}\n\n/**\n * Read the current request's SSR data. Returns undefined when called\n * outside an SSR render (i.e. on the client after hydration).\n *\n * Prefers the ALS-backed provider when registered (server-side),\n * falling back to module-level state (tests, legacy).\n *\n * Used by client hooks' server snapshot functions.\n */\nexport function getSsrData(): SsrData | undefined {\n  if (ssrDataProvider) {\n    return ssrDataProvider();\n  }\n  return currentSsrData;\n}\n","'use client';\n\n/**\n * Framework-injected React error boundary.\n *\n * Catches errors thrown by children and renders a fallback component\n * with the appropriate props based on error type:\n *   - DenySignal (4xx) → { status, dangerouslyPassData }\n *   - RenderError (5xx) → { error, digest, reset }\n *   - Unhandled error → { error, digest: null, reset }\n *\n * The `status` prop controls which errors this boundary catches:\n *   - Specific code (e.g. 403) → only that status\n *   - Category (400) → any 4xx\n *   - Category (500) → any 5xx\n *   - Omitted → catches everything (error.tsx behavior)\n *\n * See design/10-error-handling.md §\"Status-Code Files\"\n */\n\nimport { Component, createElement, type ReactNode } from 'react';\nimport { getSsrData } from './ssr-data.js';\n\n// ─── Page Unload Detection ───────────────────────────────────────────────────\n// Track whether the page is being unloaded (user refreshed or navigated away).\n// When this is true, error boundaries suppress activation — the error is from\n// the aborted connection, not an application error.\nlet _isUnloading = false;\nif (typeof window !== 'undefined') {\n  window.addEventListener('beforeunload', () => {\n    _isUnloading = true;\n  });\n  window.addEventListener('pagehide', () => {\n    _isUnloading = true;\n  });\n}\n\n// ─── Digest Types ────────────────────────────────────────────────────────────\n\n/** Structured digest returned by RSC onError for DenySignal. */\ninterface DenyDigest {\n  type: 'deny';\n  status: number;\n  data: unknown;\n}\n\n/** Structured digest returned by RSC onError for RenderError. */\ninterface RenderErrorDigest {\n  type: 'render-error';\n  code: string;\n  data: unknown;\n  status: number;\n}\n\n/** Structured digest returned by RSC onError for RedirectSignal. */\ninterface RedirectDigest {\n  type: 'redirect';\n  location: string;\n  status: number;\n}\n\ntype ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;\n\n// ─── Props & State ───────────────────────────────────────────────────────────\n\nexport interface TimberErrorBoundaryProps {\n  /** The component to render when an error is caught. */\n  fallbackComponent?: (...args: unknown[]) => ReactNode;\n  /**\n   * Pre-rendered fallback element. Used for MDX status files which are server\n   * components and cannot be passed as function props across the RSC→client\n   * boundary. When set, rendered directly instead of calling fallbackComponent.\n   *\n   * See design/10-error-handling.md §\"Status-Code File Variants\" — MDX status\n   * files are server components by default (zero client JS).\n   */\n  fallbackElement?: ReactNode;\n  /**\n   * Status code filter. If set, only catches errors matching this status.\n   * 400 = any 4xx, 500 = any 5xx, specific number = exact match.\n   */\n  status?: number;\n  /**\n   * When true, catching a DenySignal sets _denyHandledByBoundary on the\n   * nav context to prevent page-level deny promotion. Only slot catch-all\n   * boundaries should set this — segment boundaries (403.tsx, 4xx.tsx,\n   * error.tsx) must NOT, otherwise normal page denies get swallowed.\n   */\n  isSlotBoundary?: boolean;\n  children: ReactNode;\n}\n\ninterface TimberErrorBoundaryState {\n  hasError: boolean;\n  error: Error | null;\n}\n\n// ─── Component ───────────────────────────────────────────────────────────────\n\nexport class TimberErrorBoundary extends Component<\n  TimberErrorBoundaryProps,\n  TimberErrorBoundaryState\n> {\n  constructor(props: TimberErrorBoundaryProps) {\n    super(props);\n    this.state = { hasError: false, error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): TimberErrorBoundaryState {\n    // Suppress error boundaries during page unload (refresh/navigate away).\n    // The aborted connection causes React's streaming hydration to error,\n    // but the page is about to be replaced — showing an error boundary\n    // would be a jarring flash for the user.\n    if (_isUnloading) {\n      return { hasError: false, error: null };\n    }\n\n    return { hasError: true, error };\n  }\n\n  componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {\n    // Reset error state when children change (e.g. client-side navigation).\n    // Without this, navigating from one error page to another keeps the\n    // stale error — getDerivedStateFromError doesn't re-fire for new children.\n    if (this.state.hasError && prevProps.children !== this.props.children) {\n      this.setState({ hasError: false, error: null });\n    }\n  }\n\n  /** Reset the error state so children re-render. */\n  private reset = () => {\n    this.setState({ hasError: false, error: null });\n  };\n\n  render(): ReactNode {\n    if (!this.state.hasError || !this.state.error) {\n      return this.props.children;\n    }\n\n    const error = this.state.error;\n    const parsed = parseDigest(error);\n\n    // RedirectSignal errors must propagate through all error boundaries\n    // so the SSR shell fails and the pipeline catch block can produce a\n    // proper HTTP redirect response. See design/04-authorization.md.\n    if (parsed?.type === 'redirect') {\n      throw error;\n    }\n\n    // If this boundary has a status filter, check whether the error matches.\n    // Non-matching errors re-throw so an outer boundary can catch them.\n    if (this.props.status != null) {\n      const errorStatus = getErrorStatus(parsed, error);\n      if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) {\n        // Re-throw: this boundary doesn't handle this error.\n        throw error;\n      }\n    }\n\n    // Report DenySignal handling to prevent page-level promotion — but only\n    // for slot boundaries. Segment boundaries (403.tsx, 4xx.tsx, error.tsx)\n    // must NOT set this flag, otherwise normal page/hold-window denies get\n    // swallowed as 200 with boundary HTML instead of the intended 4xx.\n    // Runs here in render() (not getDerivedStateFromError) so the status\n    // filter has already been applied — non-matching boundaries re-threw above.\n    // See LOCAL-298.\n    if (parsed?.type === 'deny' && this.props.isSlotBoundary) {\n      const ssrData = getSsrData();\n      if (ssrData?._navContext) {\n        ssrData._navContext._denyHandledByBoundary = true;\n      }\n    }\n\n    // Pre-rendered fallback element (MDX status files) — render directly.\n    // MDX components are server components that cannot be passed as function\n    // props across the RSC→client boundary. Instead, they are pre-rendered\n    // as elements in the RSC environment and passed here as fallbackElement.\n    if (this.props.fallbackElement != null) {\n      return this.props.fallbackElement;\n    }\n\n    // Render the fallback component with the right props shape.\n    if (parsed?.type === 'deny') {\n      return createElement(this.props.fallbackComponent as never, {\n        status: parsed.status,\n        dangerouslyPassData: parsed.data,\n      });\n    }\n\n    // 5xx / RenderError / unhandled error\n    const digest =\n      parsed?.type === 'render-error' ? { code: parsed.code, data: parsed.data } : null;\n\n    return createElement(this.props.fallbackComponent as never, {\n      error,\n      digest,\n      reset: this.reset,\n    });\n  }\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\n/**\n * Parse the structured digest from the error.\n * React sets `error.digest` from the string returned by RSC's onError.\n */\nfunction parseDigest(error: Error): ParsedDigest | null {\n  const raw = (error as { digest?: string }).digest;\n  if (typeof raw !== 'string') return null;\n  try {\n    const parsed = JSON.parse(raw);\n    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {\n      return parsed as ParsedDigest;\n    }\n  } catch {\n    // Not JSON — legacy or unknown digest format\n  }\n  return null;\n}\n\n/**\n * Extract the HTTP status code from a parsed digest or error message.\n * Falls back to message pattern matching for errors without a digest.\n */\nfunction getErrorStatus(parsed: ParsedDigest | null, error: Error): number | null {\n  if (parsed?.type === 'deny') return parsed.status;\n  if (parsed?.type === 'render-error') return parsed.status;\n  if (parsed?.type === 'redirect') return parsed.status;\n\n  // Fallback: parse DenySignal message pattern for errors that lost their digest\n  const match = error.message.match(/^Access denied with status (\\d+)$/);\n  if (match) return parseInt(match[1], 10);\n\n  // Unhandled errors are implicitly 500\n  return 500;\n}\n\n/**\n * Check whether an error's status matches the boundary's status filter.\n * Category markers (400, 500) match any status in that range.\n */\nfunction statusMatches(boundaryStatus: number, errorStatus: number): boolean {\n  // Category catch-all: 400 matches any 4xx, 500 matches any 5xx\n  if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;\n  if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;\n  // Exact match\n  return boundaryStatus === errorStatus;\n}\n"],"mappings":";;;AA2BA,IAAW,eAAsC;AAEjD,SAAgB,iBAAiB,QAAqC;AACpE,gBAAe;;;;;;AASjB,IAAW;;AAOX,IAAW;AAEX,SAAgB,mBAAmB,MAAiC;AAClE,kBAAiB;;;AAMnB,IAAW,gBAAmD,EAAE;AAEhE,SAAgB,kBAAkB,QAAiD;AACjF,iBAAgB;;;AASlB,IAAW,eAAe;AAC1B,IAAW,qBAAqB,IAAI,iBAAiB;AAErD,SAAgB,iBAAiB,QAAgB,QAA+B;AAC9E,gBAAe;AACf,sBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACiBvB,SAAgB,WAAW,MAAqB;AAC9C,oBAAmB,KAAK;;;;;;;;AAS1B,SAAgB,eAAqB;AACnC,oBAAmB,KAAA,EAAU;;;;;;;;;;;AAY/B,SAAgB,aAAkC;AAChD,KAAI,gBACF,QAAO,iBAAiB;AAE1B,QAAO;;;;;;;;;;;;;;;;;;;;;ACzFT,IAAI,eAAe;AACnB,IAAI,OAAO,WAAW,aAAa;AACjC,QAAO,iBAAiB,sBAAsB;AAC5C,iBAAe;GACf;AACF,QAAO,iBAAiB,kBAAkB;AACxC,iBAAe;GACf;;AAiEJ,IAAa,sBAAb,cAAyC,UAGvC;CACA,YAAY,OAAiC;AAC3C,QAAM,MAAM;AACZ,OAAK,QAAQ;GAAE,UAAU;GAAO,OAAO;GAAM;;CAG/C,OAAO,yBAAyB,OAAwC;AAKtE,MAAI,aACF,QAAO;GAAE,UAAU;GAAO,OAAO;GAAM;AAGzC,SAAO;GAAE,UAAU;GAAM;GAAO;;CAGlC,mBAAmB,WAA2C;AAI5D,MAAI,KAAK,MAAM,YAAY,UAAU,aAAa,KAAK,MAAM,SAC3D,MAAK,SAAS;GAAE,UAAU;GAAO,OAAO;GAAM,CAAC;;;CAKnD,cAAsB;AACpB,OAAK,SAAS;GAAE,UAAU;GAAO,OAAO;GAAM,CAAC;;CAGjD,SAAoB;AAClB,MAAI,CAAC,KAAK,MAAM,YAAY,CAAC,KAAK,MAAM,MACtC,QAAO,KAAK,MAAM;EAGpB,MAAM,QAAQ,KAAK,MAAM;EACzB,MAAM,SAAS,YAAY,MAAM;AAKjC,MAAI,QAAQ,SAAS,WACnB,OAAM;AAKR,MAAI,KAAK,MAAM,UAAU,MAAM;GAC7B,MAAM,cAAc,eAAe,QAAQ,MAAM;AACjD,OAAI,eAAe,QAAQ,CAAC,cAAc,KAAK,MAAM,QAAQ,YAAY,CAEvE,OAAM;;AAWV,MAAI,QAAQ,SAAS,UAAU,KAAK,MAAM,gBAAgB;GACxD,MAAM,UAAU,YAAY;AAC5B,OAAI,SAAS,YACX,SAAQ,YAAY,yBAAyB;;AAQjD,MAAI,KAAK,MAAM,mBAAmB,KAChC,QAAO,KAAK,MAAM;AAIpB,MAAI,QAAQ,SAAS,OACnB,QAAO,cAAc,KAAK,MAAM,mBAA4B;GAC1D,QAAQ,OAAO;GACf,qBAAqB,OAAO;GAC7B,CAAC;EAIJ,MAAM,SACJ,QAAQ,SAAS,iBAAiB;GAAE,MAAM,OAAO;GAAM,MAAM,OAAO;GAAM,GAAG;AAE/E,SAAO,cAAc,KAAK,MAAM,mBAA4B;GAC1D;GACA;GACA,OAAO,KAAK;GACb,CAAC;;;;;;;AAUN,SAAS,YAAY,OAAmC;CACtD,MAAM,MAAO,MAA8B;AAC3C,KAAI,OAAO,QAAQ,SAAU,QAAO;AACpC,KAAI;EACF,MAAM,SAAS,KAAK,MAAM,IAAI;AAC9B,MAAI,UAAU,OAAO,WAAW,YAAY,OAAO,OAAO,SAAS,SACjE,QAAO;SAEH;AAGR,QAAO;;;;;;AAOT,SAAS,eAAe,QAA6B,OAA6B;AAChF,KAAI,QAAQ,SAAS,OAAQ,QAAO,OAAO;AAC3C,KAAI,QAAQ,SAAS,eAAgB,QAAO,OAAO;AACnD,KAAI,QAAQ,SAAS,WAAY,QAAO,OAAO;CAG/C,MAAM,QAAQ,MAAM,QAAQ,MAAM,oCAAoC;AACtE,KAAI,MAAO,QAAO,SAAS,MAAM,IAAI,GAAG;AAGxC,QAAO;;;;;;AAOT,SAAS,cAAc,gBAAwB,aAA8B;AAE3E,KAAI,mBAAmB,IAAK,QAAO,eAAe,OAAO,eAAe;AACxE,KAAI,mBAAmB,IAAK,QAAO,eAAe,OAAO,eAAe;AAExE,QAAO,mBAAmB"}

package/dist/_chunks/{format-CwdaB0_2.js → format-cX7wzEp2.js}

@@ -1,4 +1,4 @@
-import { t as isDebug } from "./debug-B4WUeqJ-.js";
+import { t as isDebug } from "./debug-ECi_61pb.js";
 //#region src/server/dev-warnings.ts
 var WarningId = {
 	SUSPENSE_WRAPS_CHILDREN: "SUSPENSE_WRAPS_CHILDREN",
@@ -161,4 +161,4 @@ function formatSize(bytes) {
 //#endregion
 export { warnDenyAfterFlush as a, warnRedirectInAccess as c, warnSlowSlotWithoutSuspense as d, warnStaticRequestApi as f, warnCacheRequestProps as i, warnRedirectInSlotAccess as l, WarningId as n, warnDenyInSuspense as o, warnSuspenseWrappingChildren as p, setViteServer as r, warnDynamicApiInStaticBuild as s, formatSize as t, warnRedirectInSuspense as u };
 
-//# sourceMappingURL=format-CwdaB0_2.js.map
+//# sourceMappingURL=format-cX7wzEp2.js.map

package/dist/_chunks/{format-CwdaB0_2.js.map → format-cX7wzEp2.js.map}

@@ -1 +1 @@
-{"version":3,"file":"format-CwdaB0_2.js","names":[],"sources":["../../src/server/dev-warnings.ts","../../src/utils/format.ts"],"sourcesContent":["/**\n * Dev-mode warnings for common timber.js misuse patterns.\n *\n * These fire in development only and are stripped from production builds.\n * Each warning targets a specific misuse identified during design review.\n *\n * Warnings are deduplicated by warningId:filePath:line so the same warning\n * is only emitted once per dev session (per unique source location).\n *\n * Warnings are written to stderr and, when a Vite dev server is available,\n * forwarded to the browser console via Vite's WebSocket.\n *\n * See design/21-dev-server.md §\"Dev-Mode Warnings\"\n * See design/11-platform.md §\"Dev Mode\"\n */\n\nimport type { ViteDevServer } from 'vite';\nimport { isDebug } from './debug.js';\n\n// ─── Warning IDs ───────────────────────────────────────────────────────────\n\nexport const WarningId = {\n  SUSPENSE_WRAPS_CHILDREN: 'SUSPENSE_WRAPS_CHILDREN',\n  DENY_IN_SUSPENSE: 'DENY_IN_SUSPENSE',\n  REDIRECT_IN_SUSPENSE: 'REDIRECT_IN_SUSPENSE',\n  REDIRECT_IN_ACCESS: 'REDIRECT_IN_ACCESS',\n  STATIC_REQUEST_API: 'STATIC_REQUEST_API',\n  CACHE_REQUEST_PROPS: 'CACHE_REQUEST_PROPS',\n  SLOW_SLOT_NO_SUSPENSE: 'SLOW_SLOT_NO_SUSPENSE',\n} as const;\n\nexport type WarningId = (typeof WarningId)[keyof typeof WarningId];\n\n// ─── Configuration ──────────────────────────────────────────────────────────\n\n/** Configuration for dev warning behavior. */\nexport interface DevWarningConfig {\n  /** Threshold in ms for \"slow slot\" warnings. Default: 200. */\n  slowSlotThresholdMs?: number;\n}\n\n// ─── Deduplication & Server ─────────────────────────────────────────────────\n\nconst _emitted = new Set<string>();\n\n/** Vite dev server for forwarding warnings to browser console. */\nlet _viteServer: ViteDevServer | null = null;\n\n/**\n * Register the Vite dev server for browser console forwarding.\n * Called by timber-dev-server during configureServer.\n */\nexport function setViteServer(server: ViteDevServer | null): void {\n  _viteServer = server;\n}\n\nfunction isDev(): boolean {\n  return isDebug();\n}\n\n/**\n * Emit a warning only once per dedup key.\n *\n * Writes to stderr and forwards to browser console via Vite WebSocket.\n * Returns true if emitted (not deduplicated).\n */\nfunction emitOnce(\n  warningId: WarningId,\n  location: string,\n  level: 'warn' | 'error',\n  message: string\n): boolean {\n  if (!isDev()) return false;\n\n  const dedupKey = `${warningId}:${location}`;\n  if (_emitted.has(dedupKey)) return false;\n  _emitted.add(dedupKey);\n\n  // Write to stderr\n  const prefix = level === 'error' ? '\\x1b[31m[timber]\\x1b[0m' : '\\x1b[33m[timber]\\x1b[0m';\n  process.stderr.write(`${prefix} ${message}\\n`);\n\n  // Forward to browser console via Vite WebSocket\n  if (_viteServer?.hot) {\n    _viteServer.hot.send('timber:dev-warning', {\n      warningId,\n      level,\n      message: `[timber] ${message}`,\n    });\n  }\n\n  return true;\n}\n\n// ─── Warning Functions ──────────────────────────────────────────────────────\n\n/**\n * Warn when a layout wraps {children} in <Suspense>.\n *\n * This defers the page content — the primary resource — behind a fallback.\n * The page's data fetches won't affect the HTTP status code because they\n * resolve after onShellReady. If the page calls deny(404), the status code\n * is already committed as 200.\n *\n * @param layoutFile - Relative path to the layout file (e.g., \"app/(dashboard)/layout.tsx\")\n */\nexport function warnSuspenseWrappingChildren(layoutFile: string): void {\n  emitOnce(\n    WarningId.SUSPENSE_WRAPS_CHILDREN,\n    layoutFile,\n    'warn',\n    `Layout at ${layoutFile} wraps {children} in <Suspense>. ` +\n      'This prevents child pages from setting HTTP status codes. ' +\n      'Use useNavigationPending() for loading states instead.'\n  );\n}\n\n/**\n * Warn when deny() is called inside a Suspense boundary.\n *\n * After the shell has flushed and the status code is committed, deny()\n * cannot change the HTTP response. The signal will be caught by the nearest\n * error boundary instead of producing a correct status code.\n *\n * @param file - Relative path to the file\n * @param line - Line number where deny() was called\n */\nexport function warnDenyInSuspense(file: string, line?: number): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.DENY_IN_SUSPENSE,\n    location,\n    'error',\n    `deny() called inside <Suspense> at ${location}. ` +\n      'The HTTP status is already committed — this will trigger an error boundary with a 200 status. ' +\n      'Move deny() outside <Suspense> for correct HTTP semantics.'\n  );\n}\n\n/**\n * Warn when redirect() is called inside a Suspense boundary.\n *\n * This will perform a client-side navigation instead of an HTTP redirect.\n *\n * @param file - Relative path to the file\n * @param line - Line number where redirect() was called\n */\nexport function warnRedirectInSuspense(file: string, line?: number): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.REDIRECT_IN_SUSPENSE,\n    location,\n    'error',\n    `redirect() called inside <Suspense> at ${location}. ` +\n      'This will perform a client-side navigation instead of an HTTP redirect.'\n  );\n}\n\n/**\n * Warn when redirect() is called in a slot's access.ts.\n *\n * Slots use deny() for graceful degradation. Redirecting from a slot would\n * redirect the entire page, breaking the contract that slot failure is\n * isolated to the slot.\n *\n * @param accessFile - Relative path to the access.ts file\n * @param line - Line number where redirect() was called\n */\nexport function warnRedirectInAccess(accessFile: string, line?: number): void {\n  const location = line ? `${accessFile}:${line}` : accessFile;\n  emitOnce(\n    WarningId.REDIRECT_IN_ACCESS,\n    location,\n    'error',\n    `redirect() called in access.ts at ${location}. ` +\n      'Only deny() is valid in slot access checks. ' +\n      'Use deny() to block access or move redirect() to middleware.ts.'\n  );\n}\n\n/**\n * Warn when cookies() or headers() is called during a static build.\n *\n * In output: 'static' mode, there is no per-request context — these APIs\n * read build-time values only. This is almost always a mistake.\n *\n * @param api - The dynamic API name (\"cookies\" or \"headers\")\n * @param file - Relative path to the file calling the API\n */\nexport function warnStaticRequestApi(api: 'cookies' | 'headers', file: string): void {\n  emitOnce(\n    WarningId.STATIC_REQUEST_API,\n    `${api}:${file}`,\n    'error',\n    `${api}() called during static generation of ${file}. ` +\n      'Dynamic request APIs are not available during prerendering.'\n  );\n}\n\n/**\n * Warn when a \"use cache\" component receives request-specific props.\n *\n * Cached components should not depend on per-request data — a userId or\n * sessionId in the props means the cache will either be ineffective\n * (key per user) or dangerous (serve one user's data to another).\n *\n * @param componentName - Name of the cached component\n * @param propName - Name of the suspicious prop\n * @param file - Relative path to the component file\n * @param line - Line number\n */\nexport function warnCacheRequestProps(\n  componentName: string,\n  propName: string,\n  file: string,\n  line?: number\n): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.CACHE_REQUEST_PROPS,\n    `${componentName}:${propName}:${location}`,\n    'warn',\n    `Cached component ${componentName} receives prop \"${propName}\" which appears request-specific. ` +\n      'Cached components should not depend on per-request data.'\n  );\n}\n\n/**\n * Warn when a parallel slot resolves slowly without a <Suspense> wrapper.\n *\n * A slow slot without Suspense blocks onShellReady — and therefore the\n * status code commit — for the entire page. Wrapping it in <Suspense>\n * lets the shell flush without waiting for the slot.\n *\n * @param slotName - The slot name (e.g., \"@admin\")\n * @param durationMs - How long the slot took to resolve\n */\nexport function warnSlowSlotWithoutSuspense(slotName: string, durationMs: number): void {\n  emitOnce(\n    WarningId.SLOW_SLOT_NO_SUSPENSE,\n    slotName,\n    'warn',\n    `Slot ${slotName} resolved in ${durationMs}ms and is not wrapped in <Suspense>. ` +\n      'Consider wrapping to avoid blocking the flush.'\n  );\n}\n\n// ─── Legacy aliases ─────────────────────────────────────────────────────────\n\n/** @deprecated Use warnStaticRequestApi instead */\nexport const warnDynamicApiInStaticBuild = warnStaticRequestApi;\n\n/** @deprecated Use warnRedirectInAccess instead */\nexport function warnRedirectInSlotAccess(slotName: string): void {\n  warnRedirectInAccess(`${slotName}/access.ts`);\n}\n\n/** @deprecated Use warnDenyInSuspense / warnRedirectInSuspense instead */\nexport function warnDenyAfterFlush(signal: 'deny' | 'redirect'): void {\n  if (signal === 'deny') {\n    warnDenyInSuspense('unknown');\n  } else {\n    warnRedirectInSuspense('unknown');\n  }\n}\n\n// ─── Testing ────────────────────────────────────────────────────────────────\n\n/**\n * Reset emitted warnings. For testing only.\n * @internal\n */\nexport function _resetWarnings(): void {\n  _emitted.clear();\n}\n\n/**\n * Get the set of emitted dedup keys. For testing only.\n * @internal\n */\nexport function _getEmitted(): ReadonlySet<string> {\n  return _emitted;\n}\n","/**\n * Shared formatting utilities.\n */\n\n/** Format a byte count as a human-readable string (e.g. \"1.50 kB\"). */\nexport function formatSize(bytes: number): string {\n  if (bytes < 1024) return `${bytes} B`;\n  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} kB`;\n  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;\n}\n"],"mappings":";;AAqBA,IAAa,YAAY;CACvB,yBAAyB;CACzB,kBAAkB;CAClB,sBAAsB;CACtB,oBAAoB;CACpB,oBAAoB;CACpB,qBAAqB;CACrB,uBAAuB;CACxB;AAcD,IAAM,2BAAW,IAAI,KAAa;;AAGlC,IAAI,cAAoC;;;;;AAMxC,SAAgB,cAAc,QAAoC;AAChE,eAAc;;AAGhB,SAAS,QAAiB;AACxB,QAAO,SAAS;;;;;;;;AASlB,SAAS,SACP,WACA,UACA,OACA,SACS;AACT,KAAI,CAAC,OAAO,CAAE,QAAO;CAErB,MAAM,WAAW,GAAG,UAAU,GAAG;AACjC,KAAI,SAAS,IAAI,SAAS,CAAE,QAAO;AACnC,UAAS,IAAI,SAAS;CAGtB,MAAM,SAAS,UAAU,UAAU,4BAA4B;AAC/D,SAAQ,OAAO,MAAM,GAAG,OAAO,GAAG,QAAQ,IAAI;AAG9C,KAAI,aAAa,IACf,aAAY,IAAI,KAAK,sBAAsB;EACzC;EACA;EACA,SAAS,YAAY;EACtB,CAAC;AAGJ,QAAO;;;;;;;;;;;;AAeT,SAAgB,6BAA6B,YAA0B;AACrE,UACE,UAAU,yBACV,YACA,QACA,aAAa,WAAW,mJAGzB;;;;;;;;;;;;AAaH,SAAgB,mBAAmB,MAAc,MAAqB;CACpE,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,kBACV,UACA,SACA,sCAAsC,SAAS,4JAGhD;;;;;;;;;;AAWH,SAAgB,uBAAuB,MAAc,MAAqB;CACxE,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,sBACV,UACA,SACA,0CAA0C,SAAS,2EAEpD;;;;;;;;;;;;AAaH,SAAgB,qBAAqB,YAAoB,MAAqB;CAC5E,MAAM,WAAW,OAAO,GAAG,WAAW,GAAG,SAAS;AAClD,UACE,UAAU,oBACV,UACA,SACA,qCAAqC,SAAS,+GAG/C;;;;;;;;;;;AAYH,SAAgB,qBAAqB,KAA4B,MAAoB;AACnF,UACE,UAAU,oBACV,GAAG,IAAI,GAAG,QACV,SACA,GAAG,IAAI,wCAAwC,KAAK,+DAErD;;;;;;;;;;;;;;AAeH,SAAgB,sBACd,eACA,UACA,MACA,MACM;CACN,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,qBACV,GAAG,cAAc,GAAG,SAAS,GAAG,YAChC,QACA,oBAAoB,cAAc,kBAAkB,SAAS,4FAE9D;;;;;;;;;;;;AAaH,SAAgB,4BAA4B,UAAkB,YAA0B;AACtF,UACE,UAAU,uBACV,UACA,QACA,QAAQ,SAAS,eAAe,WAAW,qFAE5C;;;AAMH,IAAa,8BAA8B;;AAG3C,SAAgB,yBAAyB,UAAwB;AAC/D,sBAAqB,GAAG,SAAS,YAAY;;;AAI/C,SAAgB,mBAAmB,QAAmC;AACpE,KAAI,WAAW,OACb,oBAAmB,UAAU;KAE7B,wBAAuB,UAAU;;;;;;;;ACjQrC,SAAgB,WAAW,OAAuB;AAChD,KAAI,QAAQ,KAAM,QAAO,GAAG,MAAM;AAClC,KAAI,QAAQ,OAAO,KAAM,QAAO,IAAI,QAAQ,MAAM,QAAQ,EAAE,CAAC;AAC7D,QAAO,IAAI,SAAS,OAAO,OAAO,QAAQ,EAAE,CAAC"}
+{"version":3,"file":"format-cX7wzEp2.js","names":[],"sources":["../../src/server/dev-warnings.ts","../../src/utils/format.ts"],"sourcesContent":["/**\n * Dev-mode warnings for common timber.js misuse patterns.\n *\n * These fire in development only and are stripped from production builds.\n * Each warning targets a specific misuse identified during design review.\n *\n * Warnings are deduplicated by warningId:filePath:line so the same warning\n * is only emitted once per dev session (per unique source location).\n *\n * Warnings are written to stderr and, when a Vite dev server is available,\n * forwarded to the browser console via Vite's WebSocket.\n *\n * See design/21-dev-server.md §\"Dev-Mode Warnings\"\n * See design/11-platform.md §\"Dev Mode\"\n */\n\nimport type { ViteDevServer } from 'vite';\nimport { isDebug } from './debug.js';\n\n// ─── Warning IDs ───────────────────────────────────────────────────────────\n\nexport const WarningId = {\n  SUSPENSE_WRAPS_CHILDREN: 'SUSPENSE_WRAPS_CHILDREN',\n  DENY_IN_SUSPENSE: 'DENY_IN_SUSPENSE',\n  REDIRECT_IN_SUSPENSE: 'REDIRECT_IN_SUSPENSE',\n  REDIRECT_IN_ACCESS: 'REDIRECT_IN_ACCESS',\n  STATIC_REQUEST_API: 'STATIC_REQUEST_API',\n  CACHE_REQUEST_PROPS: 'CACHE_REQUEST_PROPS',\n  SLOW_SLOT_NO_SUSPENSE: 'SLOW_SLOT_NO_SUSPENSE',\n} as const;\n\nexport type WarningId = (typeof WarningId)[keyof typeof WarningId];\n\n// ─── Configuration ──────────────────────────────────────────────────────────\n\n/** Configuration for dev warning behavior. */\nexport interface DevWarningConfig {\n  /** Threshold in ms for \"slow slot\" warnings. Default: 200. */\n  slowSlotThresholdMs?: number;\n}\n\n// ─── Deduplication & Server ─────────────────────────────────────────────────\n\nconst _emitted = new Set<string>();\n\n/** Vite dev server for forwarding warnings to browser console. */\nlet _viteServer: ViteDevServer | null = null;\n\n/**\n * Register the Vite dev server for browser console forwarding.\n * Called by timber-dev-server during configureServer.\n */\nexport function setViteServer(server: ViteDevServer | null): void {\n  _viteServer = server;\n}\n\nfunction isDev(): boolean {\n  return isDebug();\n}\n\n/**\n * Emit a warning only once per dedup key.\n *\n * Writes to stderr and forwards to browser console via Vite WebSocket.\n * Returns true if emitted (not deduplicated).\n */\nfunction emitOnce(\n  warningId: WarningId,\n  location: string,\n  level: 'warn' | 'error',\n  message: string\n): boolean {\n  if (!isDev()) return false;\n\n  const dedupKey = `${warningId}:${location}`;\n  if (_emitted.has(dedupKey)) return false;\n  _emitted.add(dedupKey);\n\n  // Write to stderr\n  const prefix = level === 'error' ? '\\x1b[31m[timber]\\x1b[0m' : '\\x1b[33m[timber]\\x1b[0m';\n  process.stderr.write(`${prefix} ${message}\\n`);\n\n  // Forward to browser console via Vite WebSocket\n  if (_viteServer?.hot) {\n    _viteServer.hot.send('timber:dev-warning', {\n      warningId,\n      level,\n      message: `[timber] ${message}`,\n    });\n  }\n\n  return true;\n}\n\n// ─── Warning Functions ──────────────────────────────────────────────────────\n\n/**\n * Warn when a layout wraps {children} in <Suspense>.\n *\n * This defers the page content — the primary resource — behind a fallback.\n * The page's data fetches won't affect the HTTP status code because they\n * resolve after onShellReady. If the page calls deny(404), the status code\n * is already committed as 200.\n *\n * @param layoutFile - Relative path to the layout file (e.g., \"app/(dashboard)/layout.tsx\")\n */\nexport function warnSuspenseWrappingChildren(layoutFile: string): void {\n  emitOnce(\n    WarningId.SUSPENSE_WRAPS_CHILDREN,\n    layoutFile,\n    'warn',\n    `Layout at ${layoutFile} wraps {children} in <Suspense>. ` +\n      'This prevents child pages from setting HTTP status codes. ' +\n      'Use useNavigationPending() for loading states instead.'\n  );\n}\n\n/**\n * Warn when deny() is called inside a Suspense boundary.\n *\n * After the shell has flushed and the status code is committed, deny()\n * cannot change the HTTP response. The signal will be caught by the nearest\n * error boundary instead of producing a correct status code.\n *\n * @param file - Relative path to the file\n * @param line - Line number where deny() was called\n */\nexport function warnDenyInSuspense(file: string, line?: number): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.DENY_IN_SUSPENSE,\n    location,\n    'error',\n    `deny() called inside <Suspense> at ${location}. ` +\n      'The HTTP status is already committed — this will trigger an error boundary with a 200 status. ' +\n      'Move deny() outside <Suspense> for correct HTTP semantics.'\n  );\n}\n\n/**\n * Warn when redirect() is called inside a Suspense boundary.\n *\n * This will perform a client-side navigation instead of an HTTP redirect.\n *\n * @param file - Relative path to the file\n * @param line - Line number where redirect() was called\n */\nexport function warnRedirectInSuspense(file: string, line?: number): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.REDIRECT_IN_SUSPENSE,\n    location,\n    'error',\n    `redirect() called inside <Suspense> at ${location}. ` +\n      'This will perform a client-side navigation instead of an HTTP redirect.'\n  );\n}\n\n/**\n * Warn when redirect() is called in a slot's access.ts.\n *\n * Slots use deny() for graceful degradation. Redirecting from a slot would\n * redirect the entire page, breaking the contract that slot failure is\n * isolated to the slot.\n *\n * @param accessFile - Relative path to the access.ts file\n * @param line - Line number where redirect() was called\n */\nexport function warnRedirectInAccess(accessFile: string, line?: number): void {\n  const location = line ? `${accessFile}:${line}` : accessFile;\n  emitOnce(\n    WarningId.REDIRECT_IN_ACCESS,\n    location,\n    'error',\n    `redirect() called in access.ts at ${location}. ` +\n      'Only deny() is valid in slot access checks. ' +\n      'Use deny() to block access or move redirect() to middleware.ts.'\n  );\n}\n\n/**\n * Warn when cookies() or headers() is called during a static build.\n *\n * In output: 'static' mode, there is no per-request context — these APIs\n * read build-time values only. This is almost always a mistake.\n *\n * @param api - The dynamic API name (\"cookies\" or \"headers\")\n * @param file - Relative path to the file calling the API\n */\nexport function warnStaticRequestApi(api: 'cookies' | 'headers', file: string): void {\n  emitOnce(\n    WarningId.STATIC_REQUEST_API,\n    `${api}:${file}`,\n    'error',\n    `${api}() called during static generation of ${file}. ` +\n      'Dynamic request APIs are not available during prerendering.'\n  );\n}\n\n/**\n * Warn when a \"use cache\" component receives request-specific props.\n *\n * Cached components should not depend on per-request data — a userId or\n * sessionId in the props means the cache will either be ineffective\n * (key per user) or dangerous (serve one user's data to another).\n *\n * @param componentName - Name of the cached component\n * @param propName - Name of the suspicious prop\n * @param file - Relative path to the component file\n * @param line - Line number\n */\nexport function warnCacheRequestProps(\n  componentName: string,\n  propName: string,\n  file: string,\n  line?: number\n): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.CACHE_REQUEST_PROPS,\n    `${componentName}:${propName}:${location}`,\n    'warn',\n    `Cached component ${componentName} receives prop \"${propName}\" which appears request-specific. ` +\n      'Cached components should not depend on per-request data.'\n  );\n}\n\n/**\n * Warn when a parallel slot resolves slowly without a <Suspense> wrapper.\n *\n * A slow slot without Suspense blocks onShellReady — and therefore the\n * status code commit — for the entire page. Wrapping it in <Suspense>\n * lets the shell flush without waiting for the slot.\n *\n * @param slotName - The slot name (e.g., \"@admin\")\n * @param durationMs - How long the slot took to resolve\n */\nexport function warnSlowSlotWithoutSuspense(slotName: string, durationMs: number): void {\n  emitOnce(\n    WarningId.SLOW_SLOT_NO_SUSPENSE,\n    slotName,\n    'warn',\n    `Slot ${slotName} resolved in ${durationMs}ms and is not wrapped in <Suspense>. ` +\n      'Consider wrapping to avoid blocking the flush.'\n  );\n}\n\n// ─── Legacy aliases ─────────────────────────────────────────────────────────\n\n/** @deprecated Use warnStaticRequestApi instead */\nexport const warnDynamicApiInStaticBuild = warnStaticRequestApi;\n\n/** @deprecated Use warnRedirectInAccess instead */\nexport function warnRedirectInSlotAccess(slotName: string): void {\n  warnRedirectInAccess(`${slotName}/access.ts`);\n}\n\n/** @deprecated Use warnDenyInSuspense / warnRedirectInSuspense instead */\nexport function warnDenyAfterFlush(signal: 'deny' | 'redirect'): void {\n  if (signal === 'deny') {\n    warnDenyInSuspense('unknown');\n  } else {\n    warnRedirectInSuspense('unknown');\n  }\n}\n\n// ─── Testing ────────────────────────────────────────────────────────────────\n\n/**\n * Reset emitted warnings. For testing only.\n * @internal\n */\nexport function _resetWarnings(): void {\n  _emitted.clear();\n}\n\n/**\n * Get the set of emitted dedup keys. For testing only.\n * @internal\n */\nexport function _getEmitted(): ReadonlySet<string> {\n  return _emitted;\n}\n","/**\n * Shared formatting utilities.\n */\n\n/** Format a byte count as a human-readable string (e.g. \"1.50 kB\"). */\nexport function formatSize(bytes: number): string {\n  if (bytes < 1024) return `${bytes} B`;\n  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} kB`;\n  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;\n}\n"],"mappings":";;AAqBA,IAAa,YAAY;CACvB,yBAAyB;CACzB,kBAAkB;CAClB,sBAAsB;CACtB,oBAAoB;CACpB,oBAAoB;CACpB,qBAAqB;CACrB,uBAAuB;CACxB;AAcD,IAAM,2BAAW,IAAI,KAAa;;AAGlC,IAAI,cAAoC;;;;;AAMxC,SAAgB,cAAc,QAAoC;AAChE,eAAc;;AAGhB,SAAS,QAAiB;AACxB,QAAO,SAAS;;;;;;;;AASlB,SAAS,SACP,WACA,UACA,OACA,SACS;AACT,KAAI,CAAC,OAAO,CAAE,QAAO;CAErB,MAAM,WAAW,GAAG,UAAU,GAAG;AACjC,KAAI,SAAS,IAAI,SAAS,CAAE,QAAO;AACnC,UAAS,IAAI,SAAS;CAGtB,MAAM,SAAS,UAAU,UAAU,4BAA4B;AAC/D,SAAQ,OAAO,MAAM,GAAG,OAAO,GAAG,QAAQ,IAAI;AAG9C,KAAI,aAAa,IACf,aAAY,IAAI,KAAK,sBAAsB;EACzC;EACA;EACA,SAAS,YAAY;EACtB,CAAC;AAGJ,QAAO;;;;;;;;;;;;AAeT,SAAgB,6BAA6B,YAA0B;AACrE,UACE,UAAU,yBACV,YACA,QACA,aAAa,WAAW,mJAGzB;;;;;;;;;;;;AAaH,SAAgB,mBAAmB,MAAc,MAAqB;CACpE,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,kBACV,UACA,SACA,sCAAsC,SAAS,4JAGhD;;;;;;;;;;AAWH,SAAgB,uBAAuB,MAAc,MAAqB;CACxE,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,sBACV,UACA,SACA,0CAA0C,SAAS,2EAEpD;;;;;;;;;;;;AAaH,SAAgB,qBAAqB,YAAoB,MAAqB;CAC5E,MAAM,WAAW,OAAO,GAAG,WAAW,GAAG,SAAS;AAClD,UACE,UAAU,oBACV,UACA,SACA,qCAAqC,SAAS,+GAG/C;;;;;;;;;;;AAYH,SAAgB,qBAAqB,KAA4B,MAAoB;AACnF,UACE,UAAU,oBACV,GAAG,IAAI,GAAG,QACV,SACA,GAAG,IAAI,wCAAwC,KAAK,+DAErD;;;;;;;;;;;;;;AAeH,SAAgB,sBACd,eACA,UACA,MACA,MACM;CACN,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,qBACV,GAAG,cAAc,GAAG,SAAS,GAAG,YAChC,QACA,oBAAoB,cAAc,kBAAkB,SAAS,4FAE9D;;;;;;;;;;;;AAaH,SAAgB,4BAA4B,UAAkB,YAA0B;AACtF,UACE,UAAU,uBACV,UACA,QACA,QAAQ,SAAS,eAAe,WAAW,qFAE5C;;;AAMH,IAAa,8BAA8B;;AAG3C,SAAgB,yBAAyB,UAAwB;AAC/D,sBAAqB,GAAG,SAAS,YAAY;;;AAI/C,SAAgB,mBAAmB,QAAmC;AACpE,KAAI,WAAW,OACb,oBAAmB,UAAU;KAE7B,wBAAuB,UAAU;;;;;;;;ACjQrC,SAAgB,WAAW,OAAuB;AAChD,KAAI,QAAQ,KAAM,QAAO,GAAG,MAAM;AAClC,KAAI,QAAQ,OAAO,KAAM,QAAO,IAAI,QAAQ,MAAM,QAAQ,EAAE,CAAC;AAC7D,QAAO,IAAI,SAAS,OAAO,OAAO,QAAQ,EAAE,CAAC"}