@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.151

package/dist/cookies/index.js

@@ -1,69 +1,238 @@
-import "../_chunks/als-registry-B7DbZ2hS.js";
-import { n as cookies } from "../_chunks/request-context-BQUC8PHn.js";
-import "../_chunks/ssr-data-MjmprTmO.js";
-import { t as useCookie } from "../_chunks/use-cookie-DX-l1_5E.js";
-//#region src/cookies/define-cookie.ts
+import { a as resolveCodecOrSchema } from "../_chunks/schema-bridge-BY3QLBL7.js";
+import { n as getSsrData } from "../_chunks/ssr-data-BOWsq18U.js";
+import { t as assertValidCookieName } from "../_chunks/validation-taUkvA4Q.js";
+import { useSyncExternalStore } from "react";
+import { getCookieJar } from "@timber-js/app/server";
+//#region src/client/use-cookie.ts
+/**
+* useCookie — reactive client-side cookie hook.
+*
+* Uses useSyncExternalStore for SSR-safe, reactive cookie access.
+* All components reading the same cookie name re-render on change.
+* No cross-tab sync (intentional — see design/29-cookies.md).
+*
+* See design/29-cookies.md §"useCookie(name) Hook"
+*/
+/** Per-name subscriber sets. */
+var listeners = /* @__PURE__ */ new Map();
+/** Parse a cookie name from document.cookie. */
+function getCookieValue(name) {
+	if (typeof document === "undefined") return void 0;
+	const match = document.cookie.match(new RegExp("(?:^|;\\s*)" + name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "\\s*=\\s*([^;]*)"));
+	return match ? decodeURIComponent(match[1]) : void 0;
+}
+/** Serialize options into a cookie string suffix. */
+function serializeOptions(options) {
+	if (!options) return "; Path=/; SameSite=Lax";
+	const parts = [];
+	parts.push(`Path=${options.path ?? "/"}`);
+	if (options.domain) parts.push(`Domain=${options.domain}`);
+	if (options.maxAge !== void 0) parts.push(`Max-Age=${options.maxAge}`);
+	if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
+	const sameSite = options.sameSite ?? "lax";
+	parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);
+	if (options.secure) parts.push("Secure");
+	return "; " + parts.join("; ");
+}
+/** Notify all subscribers for a given cookie name. */
+function notify(name) {
+	const subs = listeners.get(name);
+	if (subs) for (const fn of subs) fn();
+}
 /**
-* defineCookie — typed cookie definitions.
+* Notify useCookie subscribers that a cookie value changed.
+* Called by defineCookie's imperative client .set()/.delete() methods
+* so mounted useCookie() consumers re-render.
 *
-* Bundles name + codec + options into a reusable CookieDefinition<T>
-* with .get(), .set(), .delete() server methods and a .useCookie() client hook.
+* @internal — framework use only
+*/
+function notifyCookieChange(name) {
+	notify(name);
+}
+/**
+* Reactive hook for reading/writing a client-side cookie.
 *
-* Reuses the SearchParamCodec protocol via fromSchema() bridge.
-* Validation on read returns the codec default (never throws).
+* Returns `[value, setCookie, deleteCookie]`:
+* - `value`: current cookie value (string | undefined)
+* - `setCookie`: sets the cookie and triggers re-renders
+* - `deleteCookie`: deletes the cookie and triggers re-renders
 *
-* See design/29-cookies.md §"Typed Cookies with Schema Validation"
+* @param name - Cookie name.
+* @param defaultOptions - Default options for setCookie calls.
 */
+function useCookie(name, defaultOptions) {
+	const subscribe = (callback) => {
+		let subs = listeners.get(name);
+		if (!subs) {
+			subs = /* @__PURE__ */ new Set();
+			listeners.set(name, subs);
+		}
+		subs.add(callback);
+		return () => {
+			subs.delete(callback);
+			if (subs.size === 0) listeners.delete(name);
+		};
+	};
+	const getSnapshot = () => getCookieValue(name);
+	const getServerSnapshot = () => getSsrData()?.cookies.get(name);
+	const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+	assertValidCookieName(name);
+	const setCookie = (newValue, options) => {
+		if (typeof newValue !== "string") throw new Error(`[timber] useCookie(${JSON.stringify(name)}): value must be a string, got ${typeof newValue}.\n  To store a JSON-serializable value, use defineCookie + jsonCookieCodec from\n  '@timber-js/app/cookies' and call its useCookie() hook instead.`);
+		const merged = {
+			...defaultOptions,
+			...options
+		};
+		document.cookie = `${name}=${encodeURIComponent(newValue)}${serializeOptions(merged)}`;
+		notify(name);
+	};
+	const deleteCookie = () => {
+		const path = defaultOptions?.path ?? "/";
+		const domain = defaultOptions?.domain;
+		let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;
+		if (domain) cookieStr += `; Domain=${domain}`;
+		document.cookie = cookieStr;
+		notify(name);
+	};
+	return [
+		value,
+		setCookie,
+		deleteCookie
+	];
+}
+//#endregion
+//#region src/cookies/define-cookie.ts
+/**
+* Try to get the server cookie jar. Returns null if we're in the client
+* environment (stub throws) or if there's no request context.
+*
+* On the server, getCookieJar() throws "outside of a request context" if
+* called without an ALS store — this is a real error and is re-thrown.
+* The client stub throws a different message — that's caught and returns null.
+*/
+function tryGetServerCookieJar() {
+	try {
+		return getCookieJar();
+	} catch (e) {
+		if (e instanceof Error && e.message.includes("outside of a request context")) throw e;
+		return null;
+	}
+}
+/** Write a cookie via document.cookie and notify useCookie subscribers. */
+function setClientCookie(name, value, options) {
+	const parts = [`${name}=${encodeURIComponent(value)}`];
+	const path = options?.path ?? "/";
+	parts.push(`Path=${path}`);
+	if (options?.domain) parts.push(`Domain=${options.domain}`);
+	if (options?.maxAge !== void 0) parts.push(`Max-Age=${options.maxAge}`);
+	if (options?.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
+	const sameSite = options?.sameSite ?? "lax";
+	parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);
+	if (options?.secure) parts.push("Secure");
+	document.cookie = parts.join("; ");
+	notifyCookieChange(name);
+}
+/** Delete a cookie via document.cookie and notify useCookie subscribers. */
+function deleteClientCookie(name, options) {
+	const path = options?.path ?? "/";
+	const domain = options?.domain;
+	let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;
+	if (domain) cookieStr += `; Domain=${domain}`;
+	document.cookie = cookieStr;
+	notifyCookieChange(name);
+}
+function resolveCodec(codecOrSchema) {
+	return resolveCodecOrSchema("codec", codecOrSchema, "search");
+}
 /**
 * 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';
 *
+* // httpOnly: false — client methods available
 * export const themeCookie = defineCookie('theme', {
-*   codec: fromSchema(z.enum(['light', 'dark', 'system']).default('system')),
+*   codec: z.enum(['light', 'dark', 'system']).default('system'),
 *   httpOnly: false,
 *   maxAge: 60 * 60 * 24 * 365,
 * });
+*
+* // Server or client
+* const theme = themeCookie.get();
+* themeCookie.set('dark');
+*
+* // Client hook
+* const [theme, setTheme] = themeCookie.useCookie();
+*
+* // httpOnly: true (default) — server-only, no client methods
+* export const sessionCookie = defineCookie('session', {
+*   codec: z.string(),
+* });
+* sessionCookie.get();       // works on server
+* sessionCookie.useCookie(); // TS error — httpOnly cookie
 * ```
 */
 function defineCookie(name, options) {
-	const { codec, ...cookieOpts } = options;
+	const { codec: codecOrSchema, ...cookieOpts } = options;
+	const codec = resolveCodec(codecOrSchema);
 	const resolvedOptions = { ...cookieOpts };
-	return {
+	const isHttpOnly = options.httpOnly !== false;
+	function getClientOpts() {
+		return {
+			path: resolvedOptions.path,
+			domain: resolvedOptions.domain,
+			maxAge: resolvedOptions.maxAge,
+			expires: resolvedOptions.expires,
+			sameSite: resolvedOptions.sameSite,
+			secure: resolvedOptions.secure
+		};
+	}
+	const base = {
 		name,
 		options: resolvedOptions,
 		codec,
 		get() {
-			const jar = cookies();
-			const raw = resolvedOptions.signed ? jar.getSigned(name) : jar.get(name);
+			const serverJar = tryGetServerCookieJar();
+			if (serverJar) return codec.parse(serverJar.get(name));
+			if (isHttpOnly) throw new Error(`[timber] defineCookie('${name}').get() cannot be used with httpOnly cookies — the browser cannot access them. Set httpOnly: false to enable client access.`);
+			const raw = getCookieValue(name);
 			return codec.parse(raw);
 		},
 		set(value) {
+			const serverJar = tryGetServerCookieJar();
+			if (serverJar) {
+				const serialized = codec.serialize(value);
+				if (serialized === null) serverJar.delete(name, {
+					path: resolvedOptions.path,
+					domain: resolvedOptions.domain
+				});
+				else serverJar.set(name, serialized, resolvedOptions);
+				return;
+			}
+			if (isHttpOnly) throw new Error(`[timber] defineCookie('${name}').set() cannot be used with httpOnly cookies — the browser cannot access them. Set httpOnly: false to enable client access.`);
 			const serialized = codec.serialize(value);
-			if (serialized === null) cookies().delete(name, {
-				path: resolvedOptions.path,
-				domain: resolvedOptions.domain
-			});
-			else cookies().set(name, serialized, resolvedOptions);
+			if (serialized === null) deleteClientCookie(name, getClientOpts());
+			else setClientCookie(name, serialized, getClientOpts());
 		},
 		delete() {
-			cookies().delete(name, {
-				path: resolvedOptions.path,
-				domain: resolvedOptions.domain
-			});
-		},
+			const serverJar = tryGetServerCookieJar();
+			if (serverJar) {
+				serverJar.delete(name, {
+					path: resolvedOptions.path,
+					domain: resolvedOptions.domain
+				});
+				return;
+			}
+			if (isHttpOnly) throw new Error(`[timber] defineCookie('${name}').delete() cannot be used with httpOnly cookies — the browser cannot access them. Set httpOnly: false to enable client access.`);
+			deleteClientCookie(name, getClientOpts());
+		}
+	};
+	if (isHttpOnly) return base;
+	return {
+		...base,
 		useCookie() {
-			const [raw, setRaw, deleteRaw] = useCookie(name, {
-				path: resolvedOptions.path,
-				domain: resolvedOptions.domain,
-				maxAge: resolvedOptions.maxAge,
-				expires: resolvedOptions.expires,
-				sameSite: resolvedOptions.sameSite,
-				secure: resolvedOptions.secure
-			});
+			const [raw, setRaw, deleteRaw] = useCookie(name, getClientOpts());
 			const parsed = codec.parse(raw);
 			const setTyped = (value) => {
 				const serialized = codec.serialize(value);
@@ -79,6 +248,50 @@ function defineCookie(name, options) {
 	};
 }
 //#endregion
-export { defineCookie };
+//#region src/cookies/json-cookie.ts
+/**
+* Build a CookieCodec that JSON-encodes the value. The framework's
+* cookie write path then URL-encodes the JSON string into a valid
+* `cookie-octet` form, and the read path reverses both transforms.
+*
+* @param defaultValue - Returned by `parse` when the cookie is missing
+*   or the stored value cannot be JSON-parsed. Optional — if omitted,
+*   `parse` returns `undefined` on missing/malformed input.
+*
+*   The default is **deep-cloned** on every fallback return via
+*   `structuredClone`, so mutating the parsed result in one request
+*   cannot leak into later requests that fall back to the same
+*   default. This matters for long-lived server processes where a
+*   codec is defined once at module load and shared across all
+*   requests — without the clone, a user doing
+*   `const prefs = prefsCookie.get(); prefs.lang = 'fr'` on a missing
+*   cookie would mutate the module-level default and poison every
+*   later fallback. See the "shared mutable default" regression test
+*   in `tests/define-cookie.test.ts`.
+*/
+function jsonCookieCodec(defaultValue) {
+	const cloneDefault = () => {
+		if (defaultValue === void 0 || defaultValue === null) return defaultValue;
+		return structuredClone(defaultValue);
+	};
+	return {
+		parse(value) {
+			if (value === void 0 || value === "") return cloneDefault();
+			const raw = Array.isArray(value) ? value[value.length - 1] : value;
+			if (raw === void 0 || raw === "") return cloneDefault();
+			try {
+				return JSON.parse(raw);
+			} catch {
+				return cloneDefault();
+			}
+		},
+		serialize(value) {
+			if (value === null || value === void 0) return null;
+			return JSON.stringify(value);
+		}
+	};
+}
+//#endregion
+export { defineCookie, jsonCookieCodec };
 
 //# sourceMappingURL=index.js.map

package/dist/cookies/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.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 .get(), .set(), .delete() server methods and a .useCookie() client hook.\n *\n * Reuses the SearchParamCodec protocol via fromSchema() bridge.\n * Validation on read returns the codec default (never throws).\n *\n * See design/29-cookies.md §\"Typed Cookies with Schema Validation\"\n */\n\nimport { cookies } from '#/server/request-context.js';\nimport type { CookieOptions } from '#/server/request-context.js';\nimport { useCookie as useRawCookie } from '#/client/use-cookie.js';\nimport type { ClientCookieOptions } from '#/client/use-cookie.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\n/**\n * A codec that converts between string cookie values and typed values.\n * Intentionally identical to SearchParamCodec<T>.\n */\nexport interface CookieCodec<T> {\n  parse(value: string | string[] | undefined): T;\n  serialize(value: T): string | null;\n}\n\n/** Options for defineCookie: codec + CookieOptions merged. */\nexport interface DefineCookieOptions<T> extends Omit<CookieOptions, 'signed'> {\n  /** Codec for parsing/serializing the cookie value. */\n  codec: CookieCodec<T>;\n  /** Sign the cookie with HMAC-SHA256. */\n  signed?: boolean;\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  get(): T;\n  /** Server: set the typed value on the response. */\n  set(value: T): void;\n  /** Server: delete the cookie. */\n  delete(): 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// ─── 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 */\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    get(): T {\n      const jar = cookies();\n      const raw = resolvedOptions.signed ? jar.getSigned(name) : jar.get(name);\n      return codec.parse(raw);\n    },\n\n    set(value: T): void {\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    delete(): void {\n      cookies().delete(name, {\n        path: resolvedOptions.path,\n        domain: resolvedOptions.domain,\n      });\n    },\n\n    useCookie(): [T, (value: T) => void, () => void] {\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyEA,SAAgB,aACd,MACA,SACqB;CACrB,MAAM,EAAE,OAAO,GAAG,eAAe;CACjC,MAAM,kBAAiC,EAAE,GAAG,YAAY;AAExD,QAAO;EACL;EACA,SAAS;EACT;EAEA,MAAS;GACP,MAAM,MAAM,SAAS;GACrB,MAAM,MAAM,gBAAgB,SAAS,IAAI,UAAU,KAAK,GAAG,IAAI,IAAI,KAAK;AACxE,UAAO,MAAM,MAAM,IAAI;;EAGzB,IAAI,OAAgB;GAClB,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,SAAe;AACb,YAAS,CAAC,OAAO,MAAM;IACrB,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACzB,CAAC;;EAGJ,YAAiD;GAW/C,MAAM,CAAC,KAAK,QAAQ,aAAa,UAAa,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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/client/use-cookie.ts","../../src/cookies/define-cookie.ts","../../src/cookies/json-cookie.ts"],"sourcesContent":["/**\n * useCookie — reactive client-side cookie hook.\n *\n * Uses useSyncExternalStore for SSR-safe, reactive cookie access.\n * All components reading the same cookie name re-render on change.\n * No cross-tab sync (intentional — see design/29-cookies.md).\n *\n * See design/29-cookies.md §\"useCookie(name) Hook\"\n */\n\nimport { useSyncExternalStore } from 'react';\nimport { getSsrData } from './ssr-data.js';\nimport { assertValidCookieName } from '../cookies/validation.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\nexport interface ClientCookieOptions {\n  /** URL path scope. Default: '/'. */\n  path?: string;\n  /** Domain scope. Default: omitted (current domain). */\n  domain?: string;\n  /** Max age in seconds. */\n  maxAge?: number;\n  /** Expiration date. */\n  expires?: Date;\n  /** Cross-site policy. Default: 'lax'. */\n  sameSite?: 'strict' | 'lax' | 'none';\n  /** Only send over HTTPS. Default: true in production. */\n  secure?: boolean;\n}\n\nexport type CookieSetter = (value: string, options?: ClientCookieOptions) => void;\n\n// ─── Module-Level Cookie Store ────────────────────────────────────────────\n\ntype Listener = () => void;\n\n/** Per-name subscriber sets. */\nconst listeners = new Map<string, Set<Listener>>();\n\n/** Parse a cookie name from document.cookie. */\nexport function getCookieValue(name: string): string | undefined {\n  if (typeof document === 'undefined') return undefined;\n  const match = document.cookie.match(\n    new RegExp('(?:^|;\\\\s*)' + name.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&') + '\\\\s*=\\\\s*([^;]*)')\n  );\n  return match ? decodeURIComponent(match[1]) : undefined;\n}\n\n/** Serialize options into a cookie string suffix. */\nexport function serializeOptions(options?: ClientCookieOptions): string {\n  if (!options) return '; Path=/; SameSite=Lax';\n  const parts: string[] = [];\n  parts.push(`Path=${options.path ?? '/'}`);\n  if (options.domain) parts.push(`Domain=${options.domain}`);\n  if (options.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);\n  if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`);\n  const sameSite = options.sameSite ?? 'lax';\n  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);\n  if (options.secure) parts.push('Secure');\n  return '; ' + parts.join('; ');\n}\n\n/** Notify all subscribers for a given cookie name. */\nfunction notify(name: string): void {\n  const subs = listeners.get(name);\n  if (subs) {\n    for (const fn of subs) fn();\n  }\n}\n\n/**\n * Notify useCookie subscribers that a cookie value changed.\n * Called by defineCookie's imperative client .set()/.delete() methods\n * so mounted useCookie() consumers re-render.\n *\n * @internal — framework use only\n */\nexport function notifyCookieChange(name: string): void {\n  notify(name);\n}\n\n// ─── Hook ─────────────────────────────────────────────────────────────────\n\n/**\n * Reactive hook for reading/writing a client-side cookie.\n *\n * Returns `[value, setCookie, deleteCookie]`:\n * - `value`: current cookie value (string | undefined)\n * - `setCookie`: sets the cookie and triggers re-renders\n * - `deleteCookie`: deletes the cookie and triggers re-renders\n *\n * @param name - Cookie name.\n * @param defaultOptions - Default options for setCookie calls.\n */\nexport function useCookie(\n  name: string,\n  defaultOptions?: ClientCookieOptions\n): [value: string | undefined, setCookie: CookieSetter, deleteCookie: () => void] {\n  const subscribe = (callback: Listener): (() => void) => {\n    let subs = listeners.get(name);\n    if (!subs) {\n      subs = new Set();\n      listeners.set(name, subs);\n    }\n    subs.add(callback);\n    return () => {\n      subs!.delete(callback);\n      if (subs!.size === 0) listeners.delete(name);\n    };\n  };\n\n  const getSnapshot = (): string | undefined => getCookieValue(name);\n  const getServerSnapshot = (): string | undefined => getSsrData()?.cookies.get(name);\n\n  const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n\n  // Validate the name once per hook instance — names are typically\n  // stable string literals, so this catches the bug at first render\n  // rather than on every write. Throws via `assertValidCookieName` with\n  // a precise error if the name violates RFC 7230 token rules.\n  assertValidCookieName(name);\n\n  const setCookie: CookieSetter = (newValue: string, options?: ClientCookieOptions) => {\n    if (typeof newValue !== 'string') {\n      throw new Error(\n        `[timber] useCookie(${JSON.stringify(name)}): value must be a string, got ${typeof newValue}.\\n` +\n          `  To store a JSON-serializable value, use defineCookie + jsonCookieCodec from\\n` +\n          `  '@timber-js/app/cookies' and call its useCookie() hook instead.`\n      );\n    }\n    const merged = { ...defaultOptions, ...options };\n    // Auto-encode mirrors the server's `cookies().set()` contract:\n    // values are URL-encoded on write, URL-decoded on read, so the\n    // logical bytes round-trip losslessly. See design/29-cookies.md\n    // §\"Encoding Contract\".\n    document.cookie = `${name}=${encodeURIComponent(newValue)}${serializeOptions(merged)}`;\n    notify(name);\n  };\n\n  const deleteCookie = (): void => {\n    const path = defaultOptions?.path ?? '/';\n    const domain = defaultOptions?.domain;\n    let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;\n    if (domain) cookieStr += `; Domain=${domain}`;\n    document.cookie = cookieStr;\n    notify(name);\n  };\n\n  return [value, setCookie, deleteCookie];\n}\n","/**\n * defineCookie — typed cookie definitions.\n *\n * Bundles name + codec + options into a reusable CookieDefinition<T>\n * with sync .get(), .set(), .delete() isomorphic methods (server + client)\n * and a .useCookie() client hook.\n *\n * Environment detection is call-time: on the server, getCookieJar() is\n * used directly (ALS-backed). On the client, document.cookie helpers\n * and the useCookie hook are used. No registration pattern — imports\n * resolve via the shims plugin (client bundle gets a stub for\n * @timber-js/app/server).\n *\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected in\n * the codec option — no explicit fromSchema() wrapper needed.\n *\n * See design/29-cookies.md §\"Typed Cookies with Schema Validation\"\n */\n\nimport type { CookieOptions } from '../server/cookie-context.js';\nimport type { ClientCookieOptions } from '../client/use-cookie.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\nimport type { Codec } from '../codec.js';\nimport type { StandardSchemaV1 } from '../schema-bridge.js';\nimport { resolveCodecOrSchema } from '../schema-bridge.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, HttpOnly extends boolean = boolean> extends CookieOptions {\n  /**\n   * Codec for parsing/serializing the cookie value.\n   * Accepts a Codec<T> or a Standard Schema object (Zod, Valibot, ArkType)\n   * which is auto-wrapped via fromSchema.\n   */\n  codec: CookieCodec<T> | StandardSchemaV1<T>;\n  /**\n   * Prevent client-side JS access. Default: true.\n   * When true (or omitted), client methods (useCookie, get/set/delete on\n   * client) are omitted from the return type and throw at runtime.\n   */\n  httpOnly?: HttpOnly;\n}\n\n/**\n * Server-only cookie definition. Returned when httpOnly is true or omitted.\n * Client methods are absent from the type — accessing them is a TS error.\n */\nexport interface ServerOnlyCookieDefinition<T> {\n  readonly name: string;\n  readonly options: CookieOptions;\n  readonly codec: CookieCodec<T>;\n\n  /** Read the typed value. Sync, isomorphic (server + client). */\n  get(): T;\n  /** Set the typed value. Sync, isomorphic (server + client). */\n  set(value: T): void;\n  /** Delete the cookie. Sync, isomorphic (server + client). */\n  delete(): void;\n}\n\n/**\n * Full cookie definition with client methods. Returned when httpOnly: false.\n */\nexport interface CookieDefinition<T> extends ServerOnlyCookieDefinition<T> {\n  /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */\n  useCookie(): [T, (value: T) => void, () => void];\n}\n\n// ─── Direct Imports (no registration) ─────────────────────────────────────\n//\n// Server: getCookieJar is imported from @timber-js/app/server. In the client\n// bundle, the shims plugin replaces @timber-js/app/server with a stub module\n// where getCookieJar throws on call. We detect the environment at call time\n// by trying getCookieJar() — if it throws the stub error, we fall through\n// to the client path.\n//\n// Client: useCookie, getCookieValue, notifyCookieChange\n// are imported from use-cookie.ts. These are safe in all environments (no\n// node:async_hooks dependency).\n//\n// Schema: fromSchema is a pure function — safe in all environments.\n\nimport { getCookieJar } from '@timber-js/app/server';\nimport {\n  useCookie as useRawCookie,\n  notifyCookieChange,\n  getCookieValue,\n} from '../client/use-cookie.js';\n\n// ─── Environment Detection ────────────────────────────────────────────────\n\n/**\n * Try to get the server cookie jar. Returns null if we're in the client\n * environment (stub throws) or if there's no request context.\n *\n * On the server, getCookieJar() throws \"outside of a request context\" if\n * called without an ALS store — this is a real error and is re-thrown.\n * The client stub throws a different message — that's caught and returns null.\n */\nfunction tryGetServerCookieJar(): ReturnType<typeof getCookieJar> | null {\n  try {\n    return getCookieJar();\n  } catch (e) {\n    // Server-side \"no request context\" error — re-throw as a real bug.\n    if (e instanceof Error && e.message.includes('outside of a request context')) {\n      throw e;\n    }\n    // Client stub error or other — fall through to client path.\n    return null;\n  }\n}\n\n// ─── Client Cookie Helpers ────────────────────────────────────────────────\n\n/** Write a cookie via document.cookie and notify useCookie subscribers. */\nfunction setClientCookie(name: string, value: string, options?: ClientCookieOptions): void {\n  const parts: string[] = [`${name}=${encodeURIComponent(value)}`];\n  const path = options?.path ?? '/';\n  parts.push(`Path=${path}`);\n  if (options?.domain) parts.push(`Domain=${options.domain}`);\n  if (options?.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);\n  if (options?.expires) parts.push(`Expires=${options.expires.toUTCString()}`);\n  const sameSite = options?.sameSite ?? 'lax';\n  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);\n  if (options?.secure) parts.push('Secure');\n  document.cookie = parts.join('; ');\n  notifyCookieChange(name);\n}\n\n/** Delete a cookie via document.cookie and notify useCookie subscribers. */\nfunction deleteClientCookie(name: string, options?: ClientCookieOptions): void {\n  const path = options?.path ?? '/';\n  const domain = options?.domain;\n  let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;\n  if (domain) cookieStr += `; Domain=${domain}`;\n  document.cookie = cookieStr;\n  notifyCookieChange(name);\n}\n\n// ─── Standard Schema Auto-Detection ───────────────────────────────────────\n\nfunction resolveCodec<T>(codecOrSchema: CookieCodec<T> | StandardSchemaV1<T>): CookieCodec<T> {\n  return resolveCodecOrSchema('codec', codecOrSchema, 'search') as CookieCodec<T>;\n}\n\n// ─── Factory ──────────────────────────────────────────────────────────────\n\n/**\n * Define a typed cookie.\n *\n * ```ts\n * import { defineCookie } from '@timber-js/app/cookies';\n * import { z } from 'zod/v4';\n *\n * // httpOnly: false — client methods available\n * export const themeCookie = defineCookie('theme', {\n *   codec: z.enum(['light', 'dark', 'system']).default('system'),\n *   httpOnly: false,\n *   maxAge: 60 * 60 * 24 * 365,\n * });\n *\n * // Server or client\n * const theme = themeCookie.get();\n * themeCookie.set('dark');\n *\n * // Client hook\n * const [theme, setTheme] = themeCookie.useCookie();\n *\n * // httpOnly: true (default) — server-only, no client methods\n * export const sessionCookie = defineCookie('session', {\n *   codec: z.string(),\n * });\n * sessionCookie.get();       // works on server\n * sessionCookie.useCookie(); // TS error — httpOnly cookie\n * ```\n */\nexport function defineCookie<T, HttpOnly extends boolean = true>(\n  name: string,\n  options: DefineCookieOptions<T, HttpOnly>\n): HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T> {\n  const { codec: codecOrSchema, ...cookieOpts } = options;\n  const codec = resolveCodec(codecOrSchema);\n  const resolvedOptions: CookieOptions = { ...cookieOpts };\n  const isHttpOnly = options.httpOnly !== false; // default true\n\n  function getClientOpts(): ClientCookieOptions {\n    return {\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\n  const base: ServerOnlyCookieDefinition<T> = {\n    name,\n    options: resolvedOptions,\n    codec,\n\n    get(): T {\n      const serverJar = tryGetServerCookieJar();\n      if (serverJar) {\n        return codec.parse(serverJar.get(name));\n      }\n      // Client path\n      if (isHttpOnly) {\n        throw new Error(\n          `[timber] defineCookie('${name}').get() cannot be used with httpOnly cookies — ` +\n            `the browser cannot access them. Set httpOnly: false to enable client access.`\n        );\n      }\n      const raw = getCookieValue(name);\n      return codec.parse(raw);\n    },\n\n    set(value: T): void {\n      const serverJar = tryGetServerCookieJar();\n      if (serverJar) {\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          serverJar.delete(name, {\n            path: resolvedOptions.path,\n            domain: resolvedOptions.domain,\n          });\n        } else {\n          serverJar.set(name, serialized, resolvedOptions);\n        }\n        return;\n      }\n      // Client path\n      if (isHttpOnly) {\n        throw new Error(\n          `[timber] defineCookie('${name}').set() cannot be used with httpOnly cookies — ` +\n            `the browser cannot access them. Set httpOnly: false to enable client access.`\n        );\n      }\n      const serialized = codec.serialize(value);\n      if (serialized === null) {\n        deleteClientCookie(name, getClientOpts());\n      } else {\n        setClientCookie(name, serialized, getClientOpts());\n      }\n    },\n\n    delete(): void {\n      const serverJar = tryGetServerCookieJar();\n      if (serverJar) {\n        serverJar.delete(name, {\n          path: resolvedOptions.path,\n          domain: resolvedOptions.domain,\n        });\n        return;\n      }\n      // Client path\n      if (isHttpOnly) {\n        throw new Error(\n          `[timber] defineCookie('${name}').delete() cannot be used with httpOnly cookies — ` +\n            `the browser cannot access them. Set httpOnly: false to enable client access.`\n        );\n      }\n      deleteClientCookie(name, getClientOpts());\n    },\n  };\n\n  if (isHttpOnly) {\n    return base as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;\n  }\n\n  // httpOnly: false — add useCookie client hook\n  const full: CookieDefinition<T> = {\n    ...base,\n\n    useCookie(): [T, (value: T) => void, () => void] {\n      const clientOpts = getClientOpts();\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  return full as HttpOnly extends false ? CookieDefinition<T> : ServerOnlyCookieDefinition<T>;\n}\n","/**\n * jsonCookieCodec — Codec helper for storing JSON-serializable values in\n * cookies.\n *\n * The codec is intentionally minimal: `JSON.stringify` on serialize,\n * `JSON.parse` on parse. The framework handles the URL encoding /\n * decoding around it (see design/29-cookies.md §\"Encoding Contract\"):\n *\n *     defineCookie.setCookie(value)\n *       → codec.serialize: JSON.stringify       → '{\"a\":1}'\n *       → cookies().set: encodeURIComponent     → '%7B%22a%22%3A1%7D'\n *       → wire: Set-Cookie: prefs=%7B%22a%22%3A1%7D\n *\n *     defineCookie.getCookie()\n *       → wire: Cookie: prefs=%7B%22a%22%3A1%7D\n *       → parseCookieHeader: decodeURIComponent → '{\"a\":1}'\n *       → codec.parse: JSON.parse               → { a: 1 }\n *\n * The same chain works on the client: `useCookie` auto-encodes on writes\n * and auto-decodes on reads, so `jsonCookieCodec` composes with both the\n * server `defineCookie` methods and the client `useCookie` hook with no\n * environment-specific branches.\n *\n * Parsing is total: any non-JSON value (or `undefined`) returns the\n * supplied default. This matches the \"never crash on user-controlled\n * cookie input\" semantics that `fromSchema` uses for typed search params.\n *\n * ```ts\n * import { defineCookie, jsonCookieCodec } from '@timber-js/app/cookies';\n *\n * interface Prefs { lang: string; fontSize: number }\n *\n * export const prefsCookie = defineCookie('prefs', {\n *   codec: jsonCookieCodec<Prefs>({ lang: 'en', fontSize: 16 }),\n *   httpOnly: false,\n *   maxAge: 60 * 60 * 24 * 365,\n * });\n *\n * await prefsCookie.setCookie({ lang: 'fr', fontSize: 18 });\n * ```\n */\n\nimport type { Codec } from '../codec.js';\n\n/**\n * Build a CookieCodec that JSON-encodes the value. The framework's\n * cookie write path then URL-encodes the JSON string into a valid\n * `cookie-octet` form, and the read path reverses both transforms.\n *\n * @param defaultValue - Returned by `parse` when the cookie is missing\n *   or the stored value cannot be JSON-parsed. Optional — if omitted,\n *   `parse` returns `undefined` on missing/malformed input.\n *\n *   The default is **deep-cloned** on every fallback return via\n *   `structuredClone`, so mutating the parsed result in one request\n *   cannot leak into later requests that fall back to the same\n *   default. This matters for long-lived server processes where a\n *   codec is defined once at module load and shared across all\n *   requests — without the clone, a user doing\n *   `const prefs = prefsCookie.get(); prefs.lang = 'fr'` on a missing\n *   cookie would mutate the module-level default and poison every\n *   later fallback. See the \"shared mutable default\" regression test\n *   in `tests/define-cookie.test.ts`.\n */\nexport function jsonCookieCodec<T>(defaultValue?: T): Codec<T> {\n  // Resolve the fallback at call time, not capture time, so every\n  // fallback return produces a fresh deep copy. structuredClone handles\n  // nested objects, arrays, dates, maps, sets — everything\n  // JSON-serializable plus more. For primitives and undefined,\n  // structuredClone is effectively a no-op.\n  const cloneDefault = (): T => {\n    if (defaultValue === undefined || defaultValue === null) {\n      return defaultValue as T;\n    }\n    // structuredClone is a Node built-in since Node 17, available in\n    // all supported runtimes.\n    return structuredClone(defaultValue);\n  };\n\n  return {\n    parse(value: string | string[] | undefined): T {\n      if (value === undefined || value === '') {\n        return cloneDefault();\n      }\n      // Cookies are single-valued by name; defensively pick the last\n      // entry if a Codec consumer somehow passes an array.\n      const raw = Array.isArray(value) ? value[value.length - 1] : value;\n      if (raw === undefined || raw === '') {\n        return cloneDefault();\n      }\n      try {\n        return JSON.parse(raw) as T;\n      } catch {\n        return cloneDefault();\n      }\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      return JSON.stringify(value);\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/cookies/json-cookie.d.ts

@@ -0,0 +1,64 @@
+/**
+ * jsonCookieCodec — Codec helper for storing JSON-serializable values in
+ * cookies.
+ *
+ * The codec is intentionally minimal: `JSON.stringify` on serialize,
+ * `JSON.parse` on parse. The framework handles the URL encoding /
+ * decoding around it (see design/29-cookies.md §"Encoding Contract"):
+ *
+ *     defineCookie.setCookie(value)
+ *       → codec.serialize: JSON.stringify       → '{"a":1}'
+ *       → cookies().set: encodeURIComponent     → '%7B%22a%22%3A1%7D'
+ *       → wire: Set-Cookie: prefs=%7B%22a%22%3A1%7D
+ *
+ *     defineCookie.getCookie()
+ *       → wire: Cookie: prefs=%7B%22a%22%3A1%7D
+ *       → parseCookieHeader: decodeURIComponent → '{"a":1}'
+ *       → codec.parse: JSON.parse               → { a: 1 }
+ *
+ * The same chain works on the client: `useCookie` auto-encodes on writes
+ * and auto-decodes on reads, so `jsonCookieCodec` composes with both the
+ * server `defineCookie` methods and the client `useCookie` hook with no
+ * environment-specific branches.
+ *
+ * Parsing is total: any non-JSON value (or `undefined`) returns the
+ * supplied default. This matches the "never crash on user-controlled
+ * cookie input" semantics that `fromSchema` uses for typed search params.
+ *
+ * ```ts
+ * import { defineCookie, jsonCookieCodec } from '@timber-js/app/cookies';
+ *
+ * interface Prefs { lang: string; fontSize: number }
+ *
+ * export const prefsCookie = defineCookie('prefs', {
+ *   codec: jsonCookieCodec<Prefs>({ lang: 'en', fontSize: 16 }),
+ *   httpOnly: false,
+ *   maxAge: 60 * 60 * 24 * 365,
+ * });
+ *
+ * await prefsCookie.setCookie({ lang: 'fr', fontSize: 18 });
+ * ```
+ */
+import type { Codec } from '../codec.js';
+/**
+ * Build a CookieCodec that JSON-encodes the value. The framework's
+ * cookie write path then URL-encodes the JSON string into a valid
+ * `cookie-octet` form, and the read path reverses both transforms.
+ *
+ * @param defaultValue - Returned by `parse` when the cookie is missing
+ *   or the stored value cannot be JSON-parsed. Optional — if omitted,
+ *   `parse` returns `undefined` on missing/malformed input.
+ *
+ *   The default is **deep-cloned** on every fallback return via
+ *   `structuredClone`, so mutating the parsed result in one request
+ *   cannot leak into later requests that fall back to the same
+ *   default. This matters for long-lived server processes where a
+ *   codec is defined once at module load and shared across all
+ *   requests — without the clone, a user doing
+ *   `const prefs = prefsCookie.get(); prefs.lang = 'fr'` on a missing
+ *   cookie would mutate the module-level default and poison every
+ *   later fallback. See the "shared mutable default" regression test
+ *   in `tests/define-cookie.test.ts`.
+ */
+export declare function jsonCookieCodec<T>(defaultValue?: T): Codec<T>;
+//# sourceMappingURL=json-cookie.d.ts.map

package/dist/cookies/json-cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-cookie.d.ts","sourceRoot":"","sources":["../../src/cookies/json-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAwC7D"}

package/dist/cookies/validation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cookie name and value validation per RFC 6265 §4.1.1.
+ *
+ * This module is pure — no server or client imports — so it can be loaded
+ * by both `server/request-context.ts` (which guards `getCookies().set()`)
+ * and `client/use-cookie.ts` (which guards `useCookie()`'s setter). The
+ * shared validator gives both sides identical encoding contracts:
+ * **the framework never silently encodes — callers emit `cookie-octet`
+ * bytes or get a developer-facing error.**
+ *
+ * Why this matters: see ONGOING_SECURITY.md H-3 (TIM-868) and
+ * design/29-cookies.md §"Cookie Name and Value Validation".
+ */
+/**
+ * Validate a cookie name against RFC 6265 §4.1.1 / RFC 7230 token rules.
+ * Throws a developer-facing error naming the offending byte and its index.
+ */
+export declare function assertValidCookieName(name: string): void;
+/**
+ * Validate cookie option attributes at runtime to prevent Set-Cookie
+ * header injection through unsanitized option values.
+ *
+ * TypeScript types enforce correct shapes at compile time, but at runtime
+ * (e.g. from untyped libraries or user-controlled config) invalid values
+ * could inject additional Set-Cookie attributes.
+ */
+export declare function assertValidCookieOptions(options: {
+    sameSite?: string;
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+}): void;
+export declare function assertValidCookieValue(name: string, value: string): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/cookies/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/cookies/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA+BH;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAoBxD;AAmDD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CA+BP;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA2BxE"}

package/dist/dev-tools/404-page.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Dev 404 page — self-contained HTML page for dev-mode route misses.
+ *
+ * When no route matches and the user has no 404.tsx, this page shows:
+ * - The requested path
+ * - All registered routes in the app
+ * - "Did you mean?" suggestions based on string similarity
+ * - Setup instructions for new projects with no routes
+ *
+ * Dev-only: this module is only imported in dev mode. It is never
+ * included in production builds.
+ *
+ * Design doc: 21-dev-server.md, 07-routing.md
+ */
+import type { SegmentNode } from '../routing/types.js';
+import { type DevErrorHmrOptions } from './dev-page-shell.js';
+interface RouteInfo {
+    /** URL path pattern (e.g., "/dashboard/[id]") */
+    path: string;
+    /** Whether this is a page route or API route handler */
+    type: 'page' | 'route';
+}
+/**
+ * Collect all routable paths from a route tree (build-time scanner output
+ * or runtime route manifest).
+ *
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Includes parallel
+ * slots so the dev 404 page can list slot pages too — they aren't
+ * separately addressable, but they're still useful to know about when
+ * debugging a missing route.
+ */
+export declare function collectRoutes<TFile>(root: SegmentNode<TFile>): RouteInfo[];
+/**
+ * Find routes similar to the requested path.
+ *
+ * Returns up to 3 suggestions, sorted by similarity.
+ * Only includes routes with distance ≤ 40% of the longer string.
+ */
+export declare function findSimilarRoutes(requestedPath: string, routes: RouteInfo[]): RouteInfo[];
+/**
+ * Generate a dev-mode 404 page with route listing and suggestions.
+ *
+ * Returns an HTML string for a self-contained error page. `hmrOptions`
+ * carries the resolved Vite HMR connection options (including the WS token
+ * Vite 8 requires on browser upgrades) so the auto-reload script can
+ * actually connect (TIM-1067, B33).
+ */
+export declare function generateDev404Page(requestedPath: string, routes: RouteInfo[], hmrOptions?: DevErrorHmrOptions): string;
+export {};
+//# sourceMappingURL=404-page.d.ts.map

package/dist/dev-tools/404-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"404-page.d.ts","sourceRoot":"","sources":["../../src/dev-tools/404-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAIlF,UAAU,SAAS;IACjB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAID;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,SAAS,EAAE,CAQ1E;AAmCD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAezF;AAQD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,SAAS,EAAE,EACnB,UAAU,CAAC,EAAE,kBAAkB,GAC9B,MAAM,CAsDR"}

package/dist/dev-tools/browser-logs.d.ts

@@ -0,0 +1,84 @@
+/**
+ * timber-dev-browser-logs — Forwards browser console output to the server terminal.
+ *
+ * Injects a small inline script in dev mode that intercepts browser
+ * `console.error`, `console.warn`, and `console.info`, then forwards
+ * messages to the server via Vite's HMR WebSocket.
+ *
+ * The server-side listener formats and prints the messages with color-coded
+ * prefixes: [browser:error], [browser:warn], [browser:info].
+ *
+ * Dev-only: this plugin only runs during `vite dev`.
+ * No runtime overhead in production.
+ *
+ * See TIM-513 for design context.
+ * See design/18-build-system.md §"Dev Server" for sub-plugin architecture.
+ */
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+/** Log levels forwarded from the browser. */
+export type BrowserLogLevel = 'error' | 'warn' | 'info';
+/** Configuration value for devBrowserLogs in timber.config.ts. */
+export type DevBrowserLogsConfig = BrowserLogLevel | 'none' | undefined;
+/**
+ * Payload sent from browser to server via Vite's HMR WebSocket.
+ * Kept small — truncated before sending.
+ */
+export interface BrowserLogPayload {
+    level: BrowserLogLevel;
+    /** Serialized message string. */
+    message: string;
+    /** Error stack trace, if the first argument was an Error. */
+    stack: string | null;
+    /** Source URL and line number, if available. */
+    source: string | null;
+    /** Timestamp in ms (Date.now()) from the browser. */
+    timestamp: number;
+}
+/**
+ * Format a browser log payload for server terminal output.
+ *
+ * Produces color-coded output like:
+ *   [browser:error] Uncaught TypeError: x is not a function
+ *     at App (app.tsx:10:5)
+ *   [browser:warn] Deprecation warning (app/page.tsx:42:12)
+ */
+export declare function formatBrowserLog(payload: BrowserLogPayload): string;
+/**
+ * Check if a log at `level` should be forwarded given the configured threshold.
+ *
+ * The threshold acts as a minimum severity:
+ * - 'error' → only errors
+ * - 'warn' → errors + warnings
+ * - 'info' → errors + warnings + info
+ * - 'none' → nothing
+ */
+export declare function shouldForwardLevel(level: BrowserLogLevel, threshold: BrowserLogLevel | 'none'): boolean;
+/**
+ * Truncate a message to `maxBytes` to avoid flooding the terminal.
+ * Appends a suffix indicating how many bytes were dropped.
+ */
+export declare function truncateMessage(message: string, maxBytes: number): string;
+/**
+ * Generate the inline script injected into the browser in dev mode.
+ *
+ * This script:
+ * 1. Saves references to the original console methods
+ * 2. Wraps `console.error`, `console.warn`, `console.info`
+ * 3. Calls the original first (browser devtools still work)
+ * 4. Serializes and forwards via `import.meta.hot.send()`
+ * 5. Truncates messages to MAX_MESSAGE_BYTES
+ *
+ * The script is minimal and self-contained — no imports, no dependencies.
+ */
+export declare function generateClientScript(threshold: BrowserLogLevel | 'none'): string;
+/**
+ * Create the timber-dev-browser-logs Vite plugin.
+ *
+ * - `configureServer`: Listens for HMR messages and prints them to the terminal
+ * - `transformIndexHtml`: Injects the client-side interception script
+ *
+ * Only active during `vite dev` (apply: 'serve').
+ */
+export declare function timberDevBrowserLogs(ctx: PluginContext): Plugin;
+//# sourceMappingURL=browser-logs.d.ts.map

package/dist/dev-tools/browser-logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-logs.d.ts","sourceRoot":"","sources":["../../src/dev-tools/browser-logs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,6CAA6C;AAC7C,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAExD,kEAAkE;AAClE,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,MAAM,GAAG,SAAS,CAAC;AAExE;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,eAAe,CAAC;IACvB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gDAAgD;IAChD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB;AA6BD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAsBnE;AAID;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,eAAe,GAAG,MAAM,GAClC,OAAO,CAGT;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMzE;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,eAAe,GAAG,MAAM,GAAG,MAAM,CAgEhF;AAID;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAgE/D"}