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

package/dist/_chunks/segment-context-hzuJ048X.js

@@ -0,0 +1,72 @@
+import { createContext, createElement, useContext, useMemo } from "react";
+//#region src/shared/merge-search-params.ts
+/**
+* Shared utility for merging preserved search params into a target URL.
+*
+* Used by both <Link> (client) and redirect() (server). Extracted to a shared
+* module to avoid importing client code ('use client') from server modules.
+*/
+/**
+* Merge preserved search params from the current URL into a target href.
+*
+* When `preserve` is `true`, all current search params are merged.
+* When `preserve` is a `string[]`, only the named params are merged.
+*
+* The target href's own search params take precedence — preserved params
+* are only added if the target doesn't already define them.
+*
+* @param targetHref - The resolved target href (may already contain query string)
+* @param currentSearch - The current URL's search string (e.g. "?private=access&page=2")
+* @param preserve - `true` to preserve all, or `string[]` to preserve specific params
+* @returns The target href with preserved search params merged in
+*/
+function mergePreservedSearchParams(targetHref, currentSearch, preserve) {
+	const currentParams = new URLSearchParams(currentSearch);
+	if (currentParams.size === 0) return targetHref;
+	const hashIdx = targetHref.indexOf("#");
+	const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;
+	const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : "";
+	const qIdx = hrefWithoutHash.indexOf("?");
+	const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;
+	const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : "");
+	const merged = new URLSearchParams(targetParams);
+	for (const [key, value] of currentParams) if (!targetParams.has(key)) {
+		if (preserve === true || preserve.includes(key)) merged.append(key, value);
+	}
+	const qs = merged.toString();
+	return (qs ? `${targetPath}?${qs}` : targetPath) + hash;
+}
+//#endregion
+//#region src/client/segment-context.ts
+/**
+* Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.
+*
+* Each layout in the segment tree is wrapped with a SegmentProvider that stores
+* the URL segments from root to the current layout level. The hooks read this
+* context to determine which child segments are active below the calling layout.
+*
+* The context value is intentionally minimal: just the segment path array and
+* parallel route keys. No internal cache details are exposed.
+*
+* Design docs: design/19-client-navigation.md, design/14-ecosystem.md
+*/
+var SegmentContext = createContext(null);
+/** Read the segment context. Returns null if no provider is above this component. */
+function useSegmentContext() {
+	return useContext(SegmentContext);
+}
+/**
+* Wraps each layout to provide segment position context.
+* Injected by rsc-entry.ts during element tree construction.
+*/
+function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, children }) {
+	const value = useMemo(() => ({
+		segments,
+		parallelRouteKeys
+	}), [segments.join("/"), parallelRouteKeys.join(",")]);
+	return createElement(SegmentContext.Provider, { value }, children);
+}
+//#endregion
+export { useSegmentContext as n, mergePreservedSearchParams as r, SegmentProvider as t };
+
+//# sourceMappingURL=segment-context-hzuJ048X.js.map

package/dist/_chunks/segment-context-hzuJ048X.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-context-hzuJ048X.js","names":[],"sources":["../../src/shared/merge-search-params.ts","../../src/client/segment-context.ts"],"sourcesContent":["/**\n * Shared utility for merging preserved search params into a target URL.\n *\n * Used by both <Link> (client) and redirect() (server). Extracted to a shared\n * module to avoid importing client code ('use client') from server modules.\n */\n\n/**\n * Merge preserved search params from the current URL into a target href.\n *\n * When `preserve` is `true`, all current search params are merged.\n * When `preserve` is a `string[]`, only the named params are merged.\n *\n * The target href's own search params take precedence — preserved params\n * are only added if the target doesn't already define them.\n *\n * @param targetHref - The resolved target href (may already contain query string)\n * @param currentSearch - The current URL's search string (e.g. \"?private=access&page=2\")\n * @param preserve - `true` to preserve all, or `string[]` to preserve specific params\n * @returns The target href with preserved search params merged in\n */\nexport function mergePreservedSearchParams(\n  targetHref: string,\n  currentSearch: string,\n  preserve: true | string[]\n): string {\n  const currentParams = new URLSearchParams(currentSearch);\n  if (currentParams.size === 0) return targetHref;\n\n  // Split hash fragment from target before processing query params.\n  // Hash must come after query string: /path?query=value#hash\n  const hashIdx = targetHref.indexOf('#');\n  const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;\n  const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : '';\n\n  // Split target into path and existing query\n  const qIdx = hrefWithoutHash.indexOf('?');\n  const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;\n  const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : '');\n\n  // Collect params to preserve (that aren't already in the target)\n  const merged = new URLSearchParams(targetParams);\n  for (const [key, value] of currentParams) {\n    // Only preserve if: (a) not already in target, and (b) included in preserve list\n    if (!targetParams.has(key)) {\n      if (preserve === true || preserve.includes(key)) {\n        merged.append(key, value);\n      }\n    }\n  }\n\n  const qs = merged.toString();\n  const pathWithQuery = qs ? `${targetPath}?${qs}` : targetPath;\n  return pathWithQuery + hash;\n}\n","/**\n * Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.\n *\n * Each layout in the segment tree is wrapped with a SegmentProvider that stores\n * the URL segments from root to the current layout level. The hooks read this\n * context to determine which child segments are active below the calling layout.\n *\n * The context value is intentionally minimal: just the segment path array and\n * parallel route keys. No internal cache details are exposed.\n *\n * Design docs: design/19-client-navigation.md, design/14-ecosystem.md\n */\n\n'use client';\n\nimport { createContext, useContext, createElement, useMemo } from 'react';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface SegmentContextValue {\n  /** URL segments from root to this layout (e.g. ['', 'dashboard', 'settings']) */\n  segments: string[];\n  /** Parallel route slot keys available at this layout level (e.g. ['sidebar', 'modal']) */\n  parallelRouteKeys: string[];\n}\n\n// ─── Context ─────────────────────────────────────────────────────\n\nconst SegmentContext = createContext<SegmentContextValue | null>(null);\n\n/** Read the segment context. Returns null if no provider is above this component. */\nexport function useSegmentContext(): SegmentContextValue | null {\n  return useContext(SegmentContext);\n}\n\n// ─── Provider ────────────────────────────────────────────────────\n\ninterface SegmentProviderProps {\n  segments: string[];\n  /**\n   * Unique identifier for this segment, used by the client-side segment\n   * merger for element caching. For route groups this includes the group\n   * name (e.g., \"/(marketing)\") since groups share their parent's urlPath.\n   * Falls back to the reconstructed path from `segments` if not provided.\n   */\n  segmentId?: string;\n  parallelRouteKeys: string[];\n  children: React.ReactNode;\n}\n\n/**\n * Wraps each layout to provide segment position context.\n * Injected by rsc-entry.ts during element tree construction.\n */\nexport function SegmentProvider({\n  segments,\n  segmentId: _segmentId,\n  parallelRouteKeys,\n  children,\n}: SegmentProviderProps) {\n  const value = useMemo(\n    () => ({ segments, parallelRouteKeys }),\n    // segments and parallelRouteKeys are static per layout — they don't change\n    // across navigations. The layout's position in the tree is fixed.\n    // Intentionally using derived keys — segments/parallelRouteKeys are static per layout\n    [segments.join('/'), parallelRouteKeys.join(',')]\n  );\n  return createElement(SegmentContext.Provider, { value }, children);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,2BACd,YACA,eACA,UACQ;CACR,MAAM,gBAAgB,IAAI,gBAAgB,cAAc;AACxD,KAAI,cAAc,SAAS,EAAG,QAAO;CAIrC,MAAM,UAAU,WAAW,QAAQ,IAAI;CACvC,MAAM,kBAAkB,WAAW,IAAI,WAAW,MAAM,GAAG,QAAQ,GAAG;CACtE,MAAM,OAAO,WAAW,IAAI,WAAW,MAAM,QAAQ,GAAG;CAGxD,MAAM,OAAO,gBAAgB,QAAQ,IAAI;CACzC,MAAM,aAAa,QAAQ,IAAI,gBAAgB,MAAM,GAAG,KAAK,GAAG;CAChE,MAAM,eAAe,IAAI,gBAAgB,QAAQ,IAAI,gBAAgB,MAAM,OAAO,EAAE,GAAG,GAAG;CAG1F,MAAM,SAAS,IAAI,gBAAgB,aAAa;AAChD,MAAK,MAAM,CAAC,KAAK,UAAU,cAEzB,KAAI,CAAC,aAAa,IAAI,IAAI;MACpB,aAAa,QAAQ,SAAS,SAAS,IAAI,CAC7C,QAAO,OAAO,KAAK,MAAM;;CAK/B,MAAM,KAAK,OAAO,UAAU;AAE5B,SADsB,KAAK,GAAG,WAAW,GAAG,OAAO,cAC5B;;;;;;;;;;;;;;;;ACzBzB,IAAM,iBAAiB,cAA0C,KAAK;;AAGtE,SAAgB,oBAAgD;AAC9D,QAAO,WAAW,eAAe;;;;;;AAsBnC,SAAgB,gBAAgB,EAC9B,UACA,WAAW,YACX,mBACA,YACuB;CACvB,MAAM,QAAQ,eACL;EAAE;EAAU;EAAmB,GAItC,CAAC,SAAS,KAAK,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC,CAClD;AACD,QAAO,cAAc,eAAe,UAAU,EAAE,OAAO,EAAE,SAAS"}

package/dist/_chunks/stale-reload-BLUC_Pl_.js

@@ -0,0 +1,64 @@
+//#region src/client/stale-reload.ts
+/**
+* Stale Client Reference Reload
+*
+* When a new deployment ships updated bundles, clients running stale
+* JavaScript may encounter "Could not find the module" errors during
+* RSC Flight stream decoding. This happens because the RSC payload
+* references module IDs from the new bundle that don't exist in the
+* old client bundle.
+*
+* This module detects these specific errors and triggers a full page
+* reload so the browser fetches the new bundle. A sessionStorage flag
+* guards against infinite reload loops.
+*
+* See: LOCAL-332
+*/
+var RELOAD_FLAG_KEY = "__timber_stale_reload";
+/**
+* In-memory fallback counter for environments where sessionStorage is
+* unavailable (private browsing, storage full, extension interference).
+* Incremented each time triggerStaleReload() falls into the catch path.
+* If the counter exceeds 0 on a subsequent call, the reload is suppressed
+* to prevent an infinite loop. Resets naturally on page load (module
+* re-evaluates) and can be manually reset via clearStaleReloadFlag().
+*/
+var memoryReloadCount = 0;
+/**
+* Trigger a full page reload to pick up new bundles.
+*
+* Sets a sessionStorage flag before reloading. If the flag is already
+* set (meaning we already reloaded once for this reason), we don't
+* reload again — this prevents infinite reload loops if the error
+* persists after reload (e.g., a genuine bug rather than a stale bundle).
+*
+* @returns true if a reload was triggered, false if suppressed (loop guard)
+*/
+function triggerStaleReload() {
+	try {
+		if (sessionStorage.getItem(RELOAD_FLAG_KEY)) {
+			console.warn("[timber] Stale client reference detected again after reload. Not reloading to prevent infinite loop. This may indicate a deployment issue — try a hard refresh.");
+			return false;
+		}
+		sessionStorage.setItem(RELOAD_FLAG_KEY, "1");
+		console.warn("[timber] Stale client reference detected — the server has been redeployed with new bundles. Reloading to pick up the new version.");
+		window.location.reload();
+		return true;
+	} catch {
+		if (document.cookie.includes(RELOAD_FLAG_KEY + "=1") || memoryReloadCount > 0) {
+			console.warn("[timber] Stale client reference detected again after reload. Not reloading to prevent infinite loop. This may indicate a deployment issue — try a hard refresh.");
+			return false;
+		}
+		memoryReloadCount++;
+		try {
+			document.cookie = `${RELOAD_FLAG_KEY}=1; max-age=60; path=/; SameSite=Lax`;
+		} catch {}
+		console.warn("[timber] Stale client reference detected — the server has been redeployed with new bundles. Reloading to pick up the new version.");
+		window.location.reload();
+		return true;
+	}
+}
+//#endregion
+export { triggerStaleReload };
+
+//# sourceMappingURL=stale-reload-BLUC_Pl_.js.map

package/dist/_chunks/stale-reload-BLUC_Pl_.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-reload-BLUC_Pl_.js","names":[],"sources":["../../src/client/stale-reload.ts"],"sourcesContent":["/**\n * Stale Client Reference Reload\n *\n * When a new deployment ships updated bundles, clients running stale\n * JavaScript may encounter \"Could not find the module\" errors during\n * RSC Flight stream decoding. This happens because the RSC payload\n * references module IDs from the new bundle that don't exist in the\n * old client bundle.\n *\n * This module detects these specific errors and triggers a full page\n * reload so the browser fetches the new bundle. A sessionStorage flag\n * guards against infinite reload loops.\n *\n * See: LOCAL-332\n */\n\nconst RELOAD_FLAG_KEY = '__timber_stale_reload';\n\n/**\n * In-memory fallback counter for environments where sessionStorage is\n * unavailable (private browsing, storage full, extension interference).\n * Incremented each time triggerStaleReload() falls into the catch path.\n * If the counter exceeds 0 on a subsequent call, the reload is suppressed\n * to prevent an infinite loop. Resets naturally on page load (module\n * re-evaluates) and can be manually reset via clearStaleReloadFlag().\n */\nlet memoryReloadCount = 0;\n\n/**\n * Check if an error is a stale client reference error from React's\n * Flight client. These errors have the message pattern:\n *   \"Could not find the module \\\"<id>\\\"\"\n *\n * This is thrown by react-server-dom-webpack's client when the RSC\n * payload references a module ID that doesn't exist in the client's\n * module map — typically because the server has been redeployed with\n * new bundle hashes while the client is still running old JavaScript.\n */\nexport function isStaleClientReference(error: unknown): boolean {\n  if (!(error instanceof Error)) return false;\n  const msg = error.message;\n  return msg.includes('Could not find the module') || msg.includes('client reference not found');\n}\n\n/**\n * Check if an error is a chunk load failure from a dynamic import.\n *\n * After a deployment, old chunk filenames no longer exist. When the client\n * tries to dynamically import a chunk that's been replaced, the browser\n * throws one of these errors:\n *\n * - Chromium: \"Failed to fetch dynamically imported module: <url>\"\n * - Firefox: \"error loading dynamically imported module: <url>\"\n * - Safari: \"Importing a module script failed.\"\n * - Vite/Rollup: \"Unable to preload CSS for <url>\"\n *\n * See TIM-446\n */\nexport function isChunkLoadError(error: unknown): boolean {\n  if (!(error instanceof Error)) return false;\n  const msg = error.message.toLowerCase();\n  return (\n    msg.includes('failed to fetch dynamically imported module') ||\n    msg.includes('error loading dynamically imported module') ||\n    msg.includes('importing a module script failed') ||\n    msg.includes('unable to preload css') ||\n    // Webpack-style chunk load errors (unlikely in Vite but defensive)\n    msg.includes('loading chunk') ||\n    msg.includes('loading css chunk')\n  );\n}\n\n/**\n * Trigger a full page reload to pick up new bundles.\n *\n * Sets a sessionStorage flag before reloading. If the flag is already\n * set (meaning we already reloaded once for this reason), we don't\n * reload again — this prevents infinite reload loops if the error\n * persists after reload (e.g., a genuine bug rather than a stale bundle).\n *\n * @returns true if a reload was triggered, false if suppressed (loop guard)\n */\nexport function triggerStaleReload(): boolean {\n  try {\n    // Check if we already reloaded — prevent infinite loop\n    if (sessionStorage.getItem(RELOAD_FLAG_KEY)) {\n      console.warn(\n        '[timber] Stale client reference detected again after reload. ' +\n          'Not reloading to prevent infinite loop. ' +\n          'This may indicate a deployment issue — try a hard refresh.'\n      );\n      return false;\n    }\n\n    // Set the flag before reloading\n    sessionStorage.setItem(RELOAD_FLAG_KEY, '1');\n\n    console.warn(\n      '[timber] Stale client reference detected — the server has been ' +\n        'redeployed with new bundles. Reloading to pick up the new version.'\n    );\n\n    window.location.reload();\n    return true;\n  } catch {\n    // sessionStorage unavailable (private browsing, storage full, etc.)\n    // Use document.cookie as a reload-persistent fallback loop guard.\n    // Module-level memoryReloadCount resets on every reload, so it can't\n    // detect cross-reload loops. Cookies persist across reloads and are\n    // available even when sessionStorage is blocked (TIM-576).\n    const cookieFlag = document.cookie.includes(RELOAD_FLAG_KEY + '=1');\n    if (cookieFlag || memoryReloadCount > 0) {\n      console.warn(\n        '[timber] Stale client reference detected again after reload. ' +\n          'Not reloading to prevent infinite loop. ' +\n          'This may indicate a deployment issue — try a hard refresh.'\n      );\n      return false;\n    }\n\n    memoryReloadCount++;\n    // Set a short-lived cookie (60s) as the persistent loop guard.\n    // It auto-expires so it won't block future legitimate reloads.\n    try {\n      document.cookie = `${RELOAD_FLAG_KEY}=1; max-age=60; path=/; SameSite=Lax`;\n    } catch {\n      // Cookie API unavailable — proceed anyway, memoryReloadCount guards same-page loops\n    }\n    console.warn(\n      '[timber] Stale client reference detected — the server has been ' +\n        'redeployed with new bundles. Reloading to pick up the new version.'\n    );\n    window.location.reload();\n    return true;\n  }\n}\n\n/**\n * Clear the stale reload flag. Called on successful bootstrap to reset\n * the loop guard — if the page loaded successfully, the next stale\n * reference error should trigger a fresh reload attempt.\n */\nexport function clearStaleReloadFlag(): void {\n  memoryReloadCount = 0;\n  try {\n    sessionStorage.removeItem(RELOAD_FLAG_KEY);\n  } catch {\n    // sessionStorage unavailable — nothing to clear\n  }\n  // Also clear the cookie fallback\n  try {\n    document.cookie = `${RELOAD_FLAG_KEY}=; max-age=0; path=/; SameSite=Lax`;\n  } catch {\n    // Cookie API unavailable\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,IAAM,kBAAkB;;;;;;;;;AAUxB,IAAI,oBAAoB;;;;;;;;;;;AAwDxB,SAAgB,qBAA8B;AAC5C,KAAI;AAEF,MAAI,eAAe,QAAQ,gBAAgB,EAAE;AAC3C,WAAQ,KACN,kKAGD;AACD,UAAO;;AAIT,iBAAe,QAAQ,iBAAiB,IAAI;AAE5C,UAAQ,KACN,oIAED;AAED,SAAO,SAAS,QAAQ;AACxB,SAAO;SACD;AAON,MADmB,SAAS,OAAO,SAAS,kBAAkB,KAAK,IACjD,oBAAoB,GAAG;AACvC,WAAQ,KACN,kKAGD;AACD,UAAO;;AAGT;AAGA,MAAI;AACF,YAAS,SAAS,GAAG,gBAAgB;UAC/B;AAGR,UAAQ,KACN,oIAED;AACD,SAAO,SAAS,QAAQ;AACxB,SAAO"}

package/dist/_chunks/{use-query-states-D5KaffOK.js → use-query-states-DAhgj8Gx.js}

@@ -106,4 +106,4 @@ function bindUseQueryStates(definition) {
 //#endregion
 export { registerSearchParams as i, useQueryStates$1 as n, getSearchParams as r, bindUseQueryStates as t };
 
-//# sourceMappingURL=use-query-states-D5KaffOK.js.map
+//# sourceMappingURL=use-query-states-DAhgj8Gx.js.map

package/dist/_chunks/use-query-states-DAhgj8Gx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-query-states-DAhgj8Gx.js","names":[],"sources":["../../src/search-params/registry.ts","../../src/client/use-query-states.ts"],"sourcesContent":["/**\n * Runtime registry for route-scoped search params definitions.\n *\n * When a route's modules load, the framework registers its search-params\n * definition here. useQueryStates('/route') resolves codecs from this map.\n *\n * Design doc: design/23-search-params.md §\"Runtime: Registration at Route Load\"\n */\n\nimport type { SearchParamsDefinition } from './define.js';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst registry = new Map<string, SearchParamsDefinition<any>>();\n\n/**\n * Register a route's search params definition.\n * Called by the generated route manifest loader when a route's modules load.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function registerSearchParams(route: string, definition: SearchParamsDefinition<any>): void {\n  registry.set(route, definition);\n}\n\n/**\n * Look up a route's search params definition.\n * Returns undefined if the route hasn't been loaded yet.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function getSearchParams(route: string): SearchParamsDefinition<any> | undefined {\n  return registry.get(route);\n}\n","/**\n * useQueryStates — client-side hook for URL-synced search params.\n *\n * Delegates to nuqs for URL synchronization, batching, React 19 transitions,\n * and throttled URL writes. Bridges timber's SearchParamCodec protocol to\n * nuqs-compatible parsers.\n *\n * Design doc: design/23-search-params.md §\"Codec Bridge\"\n */\n\n'use client';\n\nimport { useQueryStates as nuqsUseQueryStates } from 'nuqs';\nimport type { SingleParser } from 'nuqs';\nimport type {\n  SearchParamCodec,\n  SearchParamsDefinition,\n  SetParams,\n  QueryStatesOptions,\n} from '../search-params/define.js';\nimport { getSearchParams } from '../search-params/registry.js';\n\n// ─── Codec Bridge ─────────────────────────────────────────────────\n\n/**\n * Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.\n *\n * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }\n * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }\n */\nfunction bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { defaultValue: T } {\n  return {\n    parse: (v: string) => codec.parse(v),\n    serialize: (v: T) => codec.serialize(v) ?? '',\n    defaultValue: codec.parse(undefined) as T,\n    eq: (a: T, b: T) => codec.serialize(a) === codec.serialize(b),\n  };\n}\n\n/**\n * Bridge an entire codec map to nuqs-compatible parsers.\n */\nfunction bridgeCodecs<T extends Record<string, unknown>>(codecs: {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n}) {\n  const result: Record<string, SingleParser<unknown> & { defaultValue: unknown }> = {};\n  for (const key of Object.keys(codecs)) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    result[key] = bridgeCodec(codecs[key as keyof T]) as any;\n  }\n  return result as { [K in keyof T]: SingleParser<T[K]> & { defaultValue: T[K] } };\n}\n\n// ─── Hook ─────────────────────────────────────────────────────────\n\n/**\n * Read and write typed search params from/to the URL.\n *\n * Delegates to nuqs internally. The timber nuqs adapter (auto-injected in\n * browser-entry.ts) handles RSC navigation on non-shallow updates.\n *\n * Usage:\n * ```ts\n * // Via a SearchParamsDefinition\n * const [params, setParams] = definition.useQueryStates()\n *\n * // Standalone with inline codecs\n * const [params, setParams] = useQueryStates({\n *   page: fromSchema(z.coerce.number().int().min(1).default(1)),\n * })\n * ```\n */\nexport function useQueryStates<T extends Record<string, unknown>>(\n  codecsOrRoute: { [K in keyof T]: SearchParamCodec<T[K]> } | string,\n  _options?: QueryStatesOptions,\n  urlKeys?: Readonly<Record<string, string>>\n): [T, SetParams<T>] {\n  // Route-string overload: resolve codecs from the registry\n  let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n  let resolvedUrlKeys = urlKeys;\n  if (typeof codecsOrRoute === 'string') {\n    const definition = getSearchParams(codecsOrRoute);\n    if (!definition) {\n      throw new Error(\n        `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +\n          `Either the route has no search-params.ts file, or it hasn't been loaded yet. ` +\n          `For cross-route usage, import the definition explicitly.`\n      );\n    }\n    codecs = definition.codecs as { [K in keyof T]: SearchParamCodec<T[K]> };\n    resolvedUrlKeys = definition.urlKeys;\n  } else {\n    codecs = codecsOrRoute;\n  }\n\n  const bridged = bridgeCodecs(codecs);\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const nuqsOptions: any = {};\n  if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) {\n    nuqsOptions.urlKeys = resolvedUrlKeys;\n  }\n\n  let values: Record<string, unknown>;\n  let setValues: Function;\n  try {\n    [values, setValues] = nuqsUseQueryStates(bridged, nuqsOptions);\n  } catch (err) {\n    if (\n      err instanceof Error &&\n      /Invalid hook call|cannot be called|Cannot read properties of null/i.test(err.message)\n    ) {\n      throw new Error(\n        'useQueryStates is a client component hook and cannot be called outside a React component. ' +\n          'Use definition.parse(searchParams) in server components instead.'\n      );\n    }\n    throw err;\n  }\n\n  // Wrap the nuqs setter to match timber's SetParams<T> signature.\n  // nuqs's setter accepts Partial<Nullable<Values>> | UpdaterFn | null.\n  // timber's setter accepts Partial<T> with optional SetParamsOptions.\n  const setParams: SetParams<T> = (partial, setOptions?) => {\n    const nuqsSetOptions: Record<string, unknown> = {};\n    if (setOptions?.shallow !== undefined) nuqsSetOptions.shallow = setOptions.shallow;\n    if (setOptions?.scroll !== undefined) nuqsSetOptions.scroll = setOptions.scroll;\n    if (setOptions?.history !== undefined) nuqsSetOptions.history = setOptions.history;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    void setValues(partial as any, nuqsSetOptions);\n  };\n\n  return [values as T, setParams];\n}\n\n// ─── Definition binding ───────────────────────────────────────────\n\n/**\n * Create a useQueryStates binding for a SearchParamsDefinition.\n * This is used internally by SearchParamsDefinition.useQueryStates().\n */\nexport function bindUseQueryStates<T extends Record<string, unknown>>(\n  definition: SearchParamsDefinition<T>\n): (options?: QueryStatesOptions) => [T, SetParams<T>] {\n  return (options?: QueryStatesOptions) => {\n    return useQueryStates<T>(definition.codecs, options, definition.urlKeys);\n  };\n}\n"],"mappings":";;AAYA,IAAM,2BAAW,IAAI,KAA0C;;;;;AAO/D,SAAgB,qBAAqB,OAAe,YAA+C;AACjG,UAAS,IAAI,OAAO,WAAW;;;;;;AAQjC,SAAgB,gBAAgB,OAAwD;AACtF,QAAO,SAAS,IAAI,MAAM;;;;;;;;;;;;;;;;;;;ACC5B,SAAS,YAAe,OAAmE;AACzF,QAAO;EACL,QAAQ,MAAc,MAAM,MAAM,EAAE;EACpC,YAAY,MAAS,MAAM,UAAU,EAAE,IAAI;EAC3C,cAAc,MAAM,MAAM,KAAA,EAAU;EACpC,KAAK,GAAM,MAAS,MAAM,UAAU,EAAE,KAAK,MAAM,UAAU,EAAE;EAC9D;;;;;AAMH,SAAS,aAAgD,QAEtD;CACD,MAAM,SAA4E,EAAE;AACpF,MAAK,MAAM,OAAO,OAAO,KAAK,OAAO,CAEnC,QAAO,OAAO,YAAY,OAAO,KAAgB;AAEnD,QAAO;;;;;;;;;;;;;;;;;;;AAsBT,SAAgB,iBACd,eACA,UACA,SACmB;CAEnB,IAAI;CACJ,IAAI,kBAAkB;AACtB,KAAI,OAAO,kBAAkB,UAAU;EACrC,MAAM,aAAa,gBAAgB,cAAc;AACjD,MAAI,CAAC,WACH,OAAM,IAAI,MACR,mBAAmB,cAAc,uLAGlC;AAEH,WAAS,WAAW;AACpB,oBAAkB,WAAW;OAE7B,UAAS;CAGX,MAAM,UAAU,aAAa,OAAO;CAGpC,MAAM,cAAmB,EAAE;AAC3B,KAAI,mBAAmB,OAAO,KAAK,gBAAgB,CAAC,SAAS,EAC3D,aAAY,UAAU;CAGxB,IAAI;CACJ,IAAI;AACJ,KAAI;AACF,GAAC,QAAQ,aAAa,eAAmB,SAAS,YAAY;UACvD,KAAK;AACZ,MACE,eAAe,SACf,qEAAqE,KAAK,IAAI,QAAQ,CAEtF,OAAM,IAAI,MACR,6JAED;AAEH,QAAM;;CAMR,MAAM,aAA2B,SAAS,eAAgB;EACxD,MAAM,iBAA0C,EAAE;AAClD,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAC3E,MAAI,YAAY,WAAW,KAAA,EAAW,gBAAe,SAAS,WAAW;AACzE,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAEtE,YAAU,SAAgB,eAAe;;AAGhD,QAAO,CAAC,QAAa,UAAU;;;;;;AASjC,SAAgB,mBACd,YACqD;AACrD,SAAQ,YAAiC;AACvC,SAAO,iBAAkB,WAAW,QAAQ,SAAS,WAAW,QAAQ"}

package/dist/_chunks/wrappers-LZbghvn0.js

@@ -0,0 +1,63 @@
+//#region src/search-params/wrappers.ts
+/**
+* Wrap a nullable codec with a default value. When the inner codec returns
+* null, the default is used instead. The output type becomes non-nullable.
+*
+* Works with any codec — nuqs parsers, custom codecs, fromSchema results.
+*
+* ```ts
+* import { parseAsInteger } from 'nuqs'
+* import { withDefault } from '@timber-js/app/search-params'
+*
+* const page = withDefault(parseAsInteger, 1)
+* // page.parse(undefined) → 1 (not null)
+* // page.parse('5') → 5
+* ```
+*/
+function withDefault(codec, defaultValue) {
+	return {
+		parse(value) {
+			const result = codec.parse(value);
+			return result === null ? defaultValue : result;
+		},
+		serialize(value) {
+			return codec.serialize(value);
+		}
+	};
+}
+/**
+* Attach a URL key alias to a codec. The alias determines what query
+* parameter key is used in the URL, while the TypeScript property name
+* stays descriptive.
+*
+* Aliases travel with codecs through object spread composition — when
+* you spread a bundle containing aliased codecs into defineSearchParams,
+* the aliases come along automatically.
+*
+* ```ts
+* import { parseAsString } from 'nuqs'
+* import { withUrlKey } from '@timber-js/app/search-params'
+*
+* export const searchable = {
+*   q: withUrlKey(parseAsString, 'search'),
+*   // ?search=shoes → { q: 'shoes' }
+* }
+* ```
+*
+* Composes with withDefault:
+* ```ts
+* import { parseAsInteger } from 'nuqs'
+* withUrlKey(withDefault(parseAsInteger, 1), 'p')
+* ```
+*/
+function withUrlKey(codec, urlKey) {
+	return {
+		parse: codec.parse.bind(codec),
+		serialize: codec.serialize.bind(codec),
+		urlKey
+	};
+}
+//#endregion
+export { withUrlKey as n, withDefault as t };
+
+//# sourceMappingURL=wrappers-LZbghvn0.js.map

package/dist/_chunks/wrappers-LZbghvn0.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrappers-LZbghvn0.js","names":[],"sources":["../../src/search-params/wrappers.ts"],"sourcesContent":["/**\n * Codec wrappers — withDefault and withUrlKey.\n *\n * These are timber-specific utilities that work with any SearchParamCodec.\n * For actual codecs (string, integer, boolean, etc.), use nuqs parsers\n * or Standard Schema objects (Zod, Valibot, ArkType) with auto-detection.\n *\n * Design doc: design/23-search-params.md\n */\n\nimport type { SearchParamCodec, SearchParamCodecWithUrlKey } from './define.js';\n\n// ---------------------------------------------------------------------------\n// withDefault\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a nullable codec with a default value. When the inner codec returns\n * null, the default is used instead. The output type becomes non-nullable.\n *\n * Works with any codec — nuqs parsers, custom codecs, fromSchema results.\n *\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * import { withDefault } from '@timber-js/app/search-params'\n *\n * const page = withDefault(parseAsInteger, 1)\n * // page.parse(undefined) → 1 (not null)\n * // page.parse('5') → 5\n * ```\n */\nexport function withDefault<T>(\n  codec: SearchParamCodec<T | null>,\n  defaultValue: T\n): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      const result = codec.parse(value);\n      return result === null ? defaultValue : result;\n    },\n    serialize(value: T): string | null {\n      return codec.serialize(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// withUrlKey\n// ---------------------------------------------------------------------------\n\n/**\n * Attach a URL key alias to a codec. The alias determines what query\n * parameter key is used in the URL, while the TypeScript property name\n * stays descriptive.\n *\n * Aliases travel with codecs through object spread composition — when\n * you spread a bundle containing aliased codecs into defineSearchParams,\n * the aliases come along automatically.\n *\n * ```ts\n * import { parseAsString } from 'nuqs'\n * import { withUrlKey } from '@timber-js/app/search-params'\n *\n * export const searchable = {\n *   q: withUrlKey(parseAsString, 'search'),\n *   // ?search=shoes → { q: 'shoes' }\n * }\n * ```\n *\n * Composes with withDefault:\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * withUrlKey(withDefault(parseAsInteger, 1), 'p')\n * ```\n */\nexport function withUrlKey<T>(\n  codec: SearchParamCodec<T>,\n  urlKey: string\n): SearchParamCodecWithUrlKey<T> {\n  return {\n    parse: codec.parse.bind(codec),\n    serialize: codec.serialize.bind(codec),\n    urlKey,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA+BA,SAAgB,YACd,OACA,cACqB;AACrB,QAAO;EACL,MAAM,OAAyC;GAC7C,MAAM,SAAS,MAAM,MAAM,MAAM;AACjC,UAAO,WAAW,OAAO,eAAe;;EAE1C,UAAU,OAAyB;AACjC,UAAO,MAAM,UAAU,MAAM;;EAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCH,SAAgB,WACd,OACA,QAC+B;AAC/B,QAAO;EACL,OAAO,MAAM,MAAM,KAAK,MAAM;EAC9B,WAAW,MAAM,UAAU,KAAK,MAAM;EACtC;EACD"}

package/dist/adapters/cloudflare-dev.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Cloudflare dev-mode bindings via wrangler's getPlatformProxy().
+ *
+ * This Vite plugin starts a local workerd process (via Miniflare) that
+ * emulates Cloudflare bindings (KV, D1, R2, Queues, Durable Objects, etc.)
+ * during development. The proxy env is injected into the request ALS so
+ * `getCloudflareBindings()` works identically in dev and production.
+ *
+ * Design doc: design/35-cloudflare-primitives.md §"Dev Experience"
+ *
+ * Usage:
+ * ```ts
+ * // vite.config.ts
+ * import { timber } from '@timber-js/app'
+ * import { cloudflare } from '@timber-js/app/adapters/cloudflare'
+ * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     timber({ adapter: cloudflare() }),
+ *     cloudflareDevBindings(),
+ *   ],
+ * })
+ * ```
+ *
+ * Requires `wrangler` as a dev dependency. Install it:
+ * ```bash
+ * pnpm add -D wrangler
+ * ```
+ */
+import type { Plugin } from 'vite';
+/**
+ * Dynamically import wrangler. Extracted as a named export so tests
+ * can mock it without needing wrangler installed.
+ * @internal
+ */
+export declare function loadWrangler(): Promise<{
+    getPlatformProxy: (opts: any) => Promise<any>;
+}>;
+/**
+ * Symbol key used to store the dev request wrapper on ViteDevServer.
+ *
+ * @internal Exported for testing. The dev-server plugin uses
+ * `Symbol.for('timber:dev-request-wrapper')` directly to avoid
+ * importing from this module.
+ */
+export declare const DEV_REQUEST_WRAPPER_KEY: unique symbol;
+/** Options for the Cloudflare dev bindings plugin. */
+export interface CloudflareDevBindingsOptions {
+    /**
+     * Path to the wrangler configuration file.
+     * @default Auto-detected by wrangler (wrangler.jsonc, wrangler.json, wrangler.toml)
+     */
+    configPath?: string;
+    /**
+     * Whether to persist binding data (KV, D1, R2) between dev server restarts.
+     *
+     * - `true` — persist in wrangler's default location (`.wrangler/state/`)
+     * - `{ path: string }` — persist in a custom directory
+     * - `false` — start fresh on every restart
+     *
+     * @default true
+     */
+    persist?: boolean | {
+        path: string;
+    };
+    /**
+     * Wrangler environment to use (for multi-environment configs).
+     * Maps to `[env.<name>]` sections in wrangler.toml / wrangler.jsonc.
+     */
+    environment?: string;
+    /**
+     * @internal Override the wrangler loader for testing.
+     * Not part of the public API — may change without notice.
+     */
+    _loadWrangler?: () => Promise<{
+        getPlatformProxy: (opts: any) => Promise<any>;
+    }>;
+}
+/**
+ * Vite plugin that provides Cloudflare bindings in dev mode via
+ * wrangler's `getPlatformProxy()`.
+ *
+ * Starts a local workerd process on dev server startup and injects
+ * the proxy env into the per-request ALS. This makes
+ * `getCloudflareBindings()` return real (emulated) bindings during
+ * development — KV, D1, R2, Queues, Durable Objects, and all other
+ * bindings declared in wrangler.jsonc.
+ *
+ * The proxy is automatically disposed when the dev server closes.
+ *
+ * **Requirements:**
+ * - `wrangler` installed as a dev dependency
+ * - A `wrangler.jsonc` (or `wrangler.toml`) with binding declarations
+ *
+ * @example
+ * ```ts
+ * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     timber({ adapter: cloudflare() }),
+ *     cloudflareDevBindings(),
+ *   ],
+ * })
+ * ```
+ */
+export declare function cloudflareDevBindings(options?: CloudflareDevBindingsOptions): Plugin;
+//# sourceMappingURL=cloudflare-dev.d.ts.map

package/dist/adapters/cloudflare-dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-dev.d.ts","sourceRoot":"","sources":["../../src/adapters/cloudflare-dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAGlD;;;;GAIG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC;IAAE,gBAAgB,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;CAAE,CAAC,CAU/F;AAaD;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,eAA2C,CAAC;AAEhF,sDAAsD;AACtD,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAErC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,gBAAgB,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,CAAC,CAAC;CAClF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,4BAAiC,GAAG,MAAM,CA6CxF"}

package/dist/adapters/cloudflare-dev.js

@@ -0,0 +1,73 @@
+import { runWithBindings } from "./cloudflare.js";
+//#region src/adapters/cloudflare-dev.ts
+/**
+* Dynamically import wrangler. Extracted as a named export so tests
+* can mock it without needing wrangler installed.
+* @internal
+*/
+async function loadWrangler() {
+	try {
+		return await import("wrangler");
+	} catch {
+		throw new Error("[timber] Could not import wrangler. cloudflareDevBindings() requires wrangler as a dev dependency.\nInstall it: pnpm add -D wrangler");
+	}
+}
+/**
+* Symbol key used to store the dev request wrapper on ViteDevServer.
+*
+* @internal Exported for testing. The dev-server plugin uses
+* `Symbol.for('timber:dev-request-wrapper')` directly to avoid
+* importing from this module.
+*/
+var DEV_REQUEST_WRAPPER_KEY = Symbol.for("timber:dev-request-wrapper");
+/**
+* Vite plugin that provides Cloudflare bindings in dev mode via
+* wrangler's `getPlatformProxy()`.
+*
+* Starts a local workerd process on dev server startup and injects
+* the proxy env into the per-request ALS. This makes
+* `getCloudflareBindings()` return real (emulated) bindings during
+* development — KV, D1, R2, Queues, Durable Objects, and all other
+* bindings declared in wrangler.jsonc.
+*
+* The proxy is automatically disposed when the dev server closes.
+*
+* **Requirements:**
+* - `wrangler` installed as a dev dependency
+* - A `wrangler.jsonc` (or `wrangler.toml`) with binding declarations
+*
+* @example
+* ```ts
+* import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+*
+* export default defineConfig({
+*   plugins: [
+*     timber({ adapter: cloudflare() }),
+*     cloudflareDevBindings(),
+*   ],
+* })
+* ```
+*/
+function cloudflareDevBindings(options = {}) {
+	return {
+		name: "timber-cloudflare-dev-bindings",
+		apply: "serve",
+		async configureServer(server) {
+			const { getPlatformProxy } = await (options._loadWrangler ?? loadWrangler)();
+			const proxyOptions = { persist: options.persist ?? true };
+			if (options.configPath) proxyOptions.configPath = options.configPath;
+			if (options.environment) proxyOptions.environment = options.environment;
+			const proxy = await getPlatformProxy(proxyOptions);
+			server[DEV_REQUEST_WRAPPER_KEY] = (fn) => {
+				return runWithBindings(proxy.env, fn);
+			};
+			server.httpServer?.on("close", () => {
+				proxy.dispose().catch(() => {});
+			});
+		}
+	};
+}
+//#endregion
+export { DEV_REQUEST_WRAPPER_KEY, cloudflareDevBindings, loadWrangler };
+
+//# sourceMappingURL=cloudflare-dev.js.map

package/dist/adapters/cloudflare-dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-dev.js","names":[],"sources":["../../src/adapters/cloudflare-dev.ts"],"sourcesContent":["/**\n * Cloudflare dev-mode bindings via wrangler's getPlatformProxy().\n *\n * This Vite plugin starts a local workerd process (via Miniflare) that\n * emulates Cloudflare bindings (KV, D1, R2, Queues, Durable Objects, etc.)\n * during development. The proxy env is injected into the request ALS so\n * `getCloudflareBindings()` works identically in dev and production.\n *\n * Design doc: design/35-cloudflare-primitives.md §\"Dev Experience\"\n *\n * Usage:\n * ```ts\n * // vite.config.ts\n * import { timber } from '@timber-js/app'\n * import { cloudflare } from '@timber-js/app/adapters/cloudflare'\n * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'\n *\n * export default defineConfig({\n *   plugins: [\n *     timber({ adapter: cloudflare() }),\n *     cloudflareDevBindings(),\n *   ],\n * })\n * ```\n *\n * Requires `wrangler` as a dev dependency. Install it:\n * ```bash\n * pnpm add -D wrangler\n * ```\n */\n\nimport type { Plugin, ViteDevServer } from 'vite';\nimport { runWithBindings } from './cloudflare.js';\n\n/**\n * Dynamically import wrangler. Extracted as a named export so tests\n * can mock it without needing wrangler installed.\n * @internal\n */\nexport async function loadWrangler(): Promise<{ getPlatformProxy: (opts: any) => Promise<any> }> {\n  try {\n    return await import('wrangler');\n  } catch {\n    throw new Error(\n      '[timber] Could not import wrangler. ' +\n        'cloudflareDevBindings() requires wrangler as a dev dependency.\\n' +\n        'Install it: pnpm add -D wrangler'\n    );\n  }\n}\n\n// ─── Contract ─────────────────────────────────────────────────────────────\n//\n// The dev request wrapper is stored on the ViteDevServer instance using a\n// well-known Symbol. This allows cross-plugin communication without import\n// dependencies — the dev-server plugin checks for this Symbol per-request\n// and wraps the handler call when present.\n//\n// The wrapper type is: <T>(fn: () => T) => T\n// It runs `fn` inside the Cloudflare bindings ALS so getCloudflareBindings()\n// works throughout the request lifecycle.\n\n/**\n * Symbol key used to store the dev request wrapper on ViteDevServer.\n *\n * @internal Exported for testing. The dev-server plugin uses\n * `Symbol.for('timber:dev-request-wrapper')` directly to avoid\n * importing from this module.\n */\nexport const DEV_REQUEST_WRAPPER_KEY = Symbol.for('timber:dev-request-wrapper');\n\n/** Options for the Cloudflare dev bindings plugin. */\nexport interface CloudflareDevBindingsOptions {\n  /**\n   * Path to the wrangler configuration file.\n   * @default Auto-detected by wrangler (wrangler.jsonc, wrangler.json, wrangler.toml)\n   */\n  configPath?: string;\n\n  /**\n   * Whether to persist binding data (KV, D1, R2) between dev server restarts.\n   *\n   * - `true` — persist in wrangler's default location (`.wrangler/state/`)\n   * - `{ path: string }` — persist in a custom directory\n   * - `false` — start fresh on every restart\n   *\n   * @default true\n   */\n  persist?: boolean | { path: string };\n\n  /**\n   * Wrangler environment to use (for multi-environment configs).\n   * Maps to `[env.<name>]` sections in wrangler.toml / wrangler.jsonc.\n   */\n  environment?: string;\n\n  /**\n   * @internal Override the wrangler loader for testing.\n   * Not part of the public API — may change without notice.\n   */\n  _loadWrangler?: () => Promise<{ getPlatformProxy: (opts: any) => Promise<any> }>;\n}\n\n/**\n * Vite plugin that provides Cloudflare bindings in dev mode via\n * wrangler's `getPlatformProxy()`.\n *\n * Starts a local workerd process on dev server startup and injects\n * the proxy env into the per-request ALS. This makes\n * `getCloudflareBindings()` return real (emulated) bindings during\n * development — KV, D1, R2, Queues, Durable Objects, and all other\n * bindings declared in wrangler.jsonc.\n *\n * The proxy is automatically disposed when the dev server closes.\n *\n * **Requirements:**\n * - `wrangler` installed as a dev dependency\n * - A `wrangler.jsonc` (or `wrangler.toml`) with binding declarations\n *\n * @example\n * ```ts\n * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'\n *\n * export default defineConfig({\n *   plugins: [\n *     timber({ adapter: cloudflare() }),\n *     cloudflareDevBindings(),\n *   ],\n * })\n * ```\n */\nexport function cloudflareDevBindings(options: CloudflareDevBindingsOptions = {}): Plugin {\n  return {\n    name: 'timber-cloudflare-dev-bindings',\n\n    // Dev mode only — never active during production builds.\n    // See design/35-cloudflare-primitives.md §\"Security Considerations\":\n    // \"Dev bindings are dev-only. apply: 'serve' ensures it never runs\n    //  in production builds.\"\n    apply: 'serve',\n\n    async configureServer(server: ViteDevServer) {\n      // Dynamic import — wrangler is an optional peer dependency.\n      // Users must install it themselves: `pnpm add -D wrangler`\n      const { getPlatformProxy } = await (options._loadWrangler ?? loadWrangler)();\n\n      // Build getPlatformProxy options from our public API.\n      const proxyOptions: Record<string, unknown> = {\n        persist: options.persist ?? true,\n      };\n      if (options.configPath) {\n        proxyOptions.configPath = options.configPath;\n      }\n      if (options.environment) {\n        proxyOptions.environment = options.environment;\n      }\n\n      const proxy = await getPlatformProxy(proxyOptions);\n\n      // Store a request wrapper on the server instance. The dev-server\n      // plugin checks for this Symbol per-request and wraps the RSC\n      // handler call so getCloudflareBindings() works throughout the\n      // request lifecycle (server components, middleware, server actions).\n      (server as any)[DEV_REQUEST_WRAPPER_KEY] = <T>(fn: () => T): T => {\n        return runWithBindings(proxy.env as Record<string, unknown>, fn);\n      };\n\n      // Dispose the proxy when the dev server closes. This shuts down\n      // the local workerd process started by getPlatformProxy().\n      server.httpServer?.on('close', () => {\n        proxy.dispose().catch(() => {\n          // Disposal errors are non-fatal — the process is shutting down.\n        });\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;;AAuCA,eAAsB,eAA2E;AAC/F,KAAI;AACF,SAAO,MAAM,OAAO;SACd;AACN,QAAM,IAAI,MACR,uIAGD;;;;;;;;;;AAsBL,IAAa,0BAA0B,OAAO,IAAI,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8D/E,SAAgB,sBAAsB,UAAwC,EAAE,EAAU;AACxF,QAAO;EACL,MAAM;EAMN,OAAO;EAEP,MAAM,gBAAgB,QAAuB;GAG3C,MAAM,EAAE,qBAAqB,OAAO,QAAQ,iBAAiB,eAAe;GAG5E,MAAM,eAAwC,EAC5C,SAAS,QAAQ,WAAW,MAC7B;AACD,OAAI,QAAQ,WACV,cAAa,aAAa,QAAQ;AAEpC,OAAI,QAAQ,YACV,cAAa,cAAc,QAAQ;GAGrC,MAAM,QAAQ,MAAM,iBAAiB,aAAa;AAMjD,UAAe,4BAA+B,OAAmB;AAChE,WAAO,gBAAgB,MAAM,KAAgC,GAAG;;AAKlE,UAAO,YAAY,GAAG,eAAe;AACnC,UAAM,SAAS,CAAC,YAAY,GAE1B;KACF;;EAEL"}