@timber-js/app 0.2.0-alpha.160 → 0.2.0-alpha.163

package/dist/cookies/index.js.map

@@ -1 +1 @@
-{"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 { parseCookie, stringifySetCookie } from 'cookie';\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 cookies = parseCookie(document.cookie);\n  return cookies[name];\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 sameSite = options.sameSite ?? 'lax';\n  // Build a Set-Cookie string via the cookie package, then strip the\n  // `__placeholder__=` name=value prefix to get just the attributes.\n  const full = stringifySetCookie({\n    name: '__placeholder__',\n    value: '',\n    path: options.path ?? '/',\n    domain: options.domain,\n    maxAge: options.maxAge,\n    expires: options.expires,\n    sameSite,\n    secure: options.secure,\n  });\n  // Strip everything up to and including the first \"; \"\n  const idx = full.indexOf('; ');\n  return idx >= 0 ? full.slice(idx) : '';\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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"}
+{"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 { parseCookie, stringifySetCookie } from 'cookie';\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 cookies = parseCookie(document.cookie);\n  return cookies[name];\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 sameSite = options.sameSite ?? 'lax';\n  // Build a Set-Cookie string via the cookie package, then strip the\n  // `__placeholder__=` name=value prefix to get just the attributes.\n  const full = stringifySetCookie({\n    name: '__placeholder__',\n    value: '',\n    path: options.path ?? '/',\n    domain: options.domain,\n    maxAge: options.maxAge,\n    expires: options.expires,\n    sameSite,\n    secure: options.secure,\n  });\n  // Strip everything up to and including the first \"; \"\n  const idx = full.indexOf('; ');\n  return idx >= 0 ? full.slice(idx) : '';\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 => {\n    // During SSR, read the ALS-backed request cookies.\n    const ssrData = getSsrData();\n    if (ssrData) return ssrData.cookies.get(name);\n    // During client hydration there is no SSR data (it lives in the server's\n    // module graph), but React still calls getServerSnapshot. document.cookie\n    // holds the same cookies the server rendered with, so reading it here\n    // keeps the hydration render consistent with the server HTML.\n    // See design/29-cookies.md §\"SSR Hydration\".\n    return getCookieValue(name);\n  };\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/index.js

@@ -1,9 +1,9 @@
 import { a as __esmMin, o as __exportAll, s as __toCommonJS } from "./_chunks/dist-BA3u1z3W.js";
 import { c as isDynamicMetadataExtension, l as isMetadataRouteServePath, r as canonicalize } from "./_chunks/canonicalize-P41GR6tY.js";
 import { t as matchUrlParts } from "./_chunks/tree-match-D2l830j2.js";
-import { h as swallow } from "./_chunks/logger-CPoQkGK6.js";
-import { i as scanRoutes } from "./_chunks/cli-schema-sync-BhYDz_-x.js";
-import { a as generateRouteMap, c as fileHasDirective, d as getPrerenderExport, i as validateSchemaAgainstRoutes, l as fileHasExport, n as collectInterceptionRewrites, o as fileHasAnyExport, s as fileHasDefaultExport, t as collectLeafRoutes, u as fileHasStarExport } from "./_chunks/walkers-c8aReVgo.js";
+import { h as swallow } from "./_chunks/logger-B_O6-mdJ.js";
+import { i as scanRoutes } from "./_chunks/cli-schema-sync-NfLbLnDw.js";
+import { a as generateRouteMap, c as fileHasDirective, d as getPrerenderExport, i as validateSchemaAgainstRoutes, l as fileHasExport, n as collectInterceptionRewrites, o as fileHasAnyExport, s as fileHasDefaultExport, t as collectLeafRoutes, u as fileHasStarExport } from "./_chunks/walkers-9mz9T7mb.js";
 import { a as resolveAppDir, c as createNoopTimer, n as loadTimberConfigFile, o as resolveBuildDir, r as mergeFileConfig, s as resolveClientJavascript, t as createPluginContext } from "./_chunks/plugin-context-DeAxFRMq.js";
 import { t as fnv1aHash } from "./_chunks/fast-hash-D6hIVt1Y.js";
 import { t as formatSize } from "./_chunks/format-CfwjgPz9.js";
@@ -3027,6 +3027,10 @@ function timberShims(_ctx) {
 				if (envName(this) === "client" && cleanId === "next/navigation") return resolve(SHIMS_DIR, "navigation-client.ts");
 				return SHIM_MAP[cleanId];
 			}
+			if (cleanId === "#server-only-guard") {
+				if (envName(this) === "client") return SERVER_ONLY_VIRTUAL;
+				return resolve(PKG_ROOT, "src", "server", "server-only-guard-noop.js");
+			}
 			if (cleanId === "#server-internal") {
 				if (envName(this) === "client") return "\0timber:server-empty";
 				return resolve(PKG_ROOT, "src", "server", "internal.ts");
@@ -3042,6 +3046,9 @@ function timberShims(_ctx) {
 				if (envName(this) === "client") return "\0timber:server-empty";
 				return resolve(PKG_ROOT, "src", "server", "index.ts");
 			}
+			if (cleanId === resolve(PKG_ROOT, "src", "server", "index.ts") || cleanId === resolve(PKG_ROOT, "src", "server", "internal.ts")) {
+				if (envName(this) === "client") return "\0timber:server-empty";
+			}
 			if (cleanId === "@timber-js/app/client") {
 				const env = envName(this);
 				if (env === "ssr" || env === "client") return resolve(PKG_ROOT, "src", "client", "index.ts");
@@ -5934,6 +5941,11 @@ function timberFonts(ctx) {
 		configResolved(config) {
 			resolvedBase = config.base;
 			pipeline.setBase(config.base);
+			const originalWarnOnce = config.logger.warnOnce.bind(config.logger);
+			config.logger.warnOnce = (msg, options) => {
+				if (msg.includes("_timber/fonts/") && msg.includes("didn't resolve at build time")) return;
+				originalWarnOnce(msg, options);
+			};
 		},
 		/**
 		* `enforce: 'pre'` is load-bearing for the font CSS pipeline (TIM-828).
@@ -6944,16 +6956,224 @@ function findImportBindings(program, sources, importedName) {
 		namespaces
 	};
 }
+/** Extract all bound identifier names from a parameter/binding pattern. */
+function collectPatternNames(node, out) {
+	switch (node.type) {
+		case "Identifier":
+			out.add(node.name);
+			break;
+		case "AssignmentPattern":
+			collectPatternNames(node.left, out);
+			break;
+		case "RestElement":
+			collectPatternNames(node.argument, out);
+			break;
+		case "ArrayPattern":
+			for (const el of node.elements ?? []) if (el) collectPatternNames(el, out);
+			break;
+		case "ObjectPattern":
+			for (const prop of node.properties ?? []) if (prop.type === "RestElement") collectPatternNames(prop, out);
+			else collectPatternNames(prop.value, out);
+			break;
+		case "TSParameterProperty":
+			if (node.parameter) collectPatternNames(node.parameter, out);
+			break;
+	}
+}
+/** Return the intersection of param names with `tracked`, or null if none. */
+function shadowedParamNames(params, tracked) {
+	if (!params) return null;
+	const names = /* @__PURE__ */ new Set();
+	for (const p of params) collectPatternNames(p, names);
+	const hit = /* @__PURE__ */ new Set();
+	for (const n of names) if (tracked.has(n)) hit.add(n);
+	return hit.size > 0 ? hit : null;
+}
+/**
+* Collect names declared by `VariableDeclaration`, `FunctionDeclaration`,
+* and `ClassDeclaration` in a statement list. Only scans direct children
+* (not nested blocks). For-loop bindings are NOT included — they are
+* scoped to the loop statement and handled separately in
+* `collectShadowRanges` (codex review round 4 on PR #876).
+*/
+function collectLexicalDeclNames(stmts, out) {
+	for (const stmt of stmts) if (stmt.type === "VariableDeclaration") {
+		for (const decl of stmt.declarations ?? []) if (decl.id) collectPatternNames(decl.id, out);
+	} else if (stmt.type === "FunctionDeclaration" || stmt.type === "ClassDeclaration") {
+		if (stmt.id && stmt.id.type === "Identifier") out.add(stmt.id.name);
+	}
+}
+/**
+* Extract binding names from a for-loop's init/left clause, but ONLY for
+* `const`/`let` (block-scoped). `var` bindings hoist to the enclosing
+* function and are handled by `collectVarDeclNames` instead (codex review
+* round 5 on PR #876).
+*/
+function collectForLoopBlockBindingNames(loop, out) {
+	const init = loop.init ?? loop.left;
+	if (init?.type === "VariableDeclaration" && init.kind !== "var") {
+		for (const decl of init.declarations ?? []) if (decl.id) collectPatternNames(decl.id, out);
+	}
+}
+/**
+* Recursively collect `var` declaration names from a statement tree.
+* `var` hoists to the enclosing function regardless of block nesting,
+* so we must scan nested blocks, loops, switch cases, etc.
+*/
+function collectVarDeclNames(stmts, out) {
+	for (const stmt of stmts) {
+		if (stmt.type === "VariableDeclaration" && stmt.kind === "var") {
+			for (const decl of stmt.declarations ?? []) if (decl.id) collectPatternNames(decl.id, out);
+		}
+		if (stmt.type === "BlockStatement" || stmt.type === "StaticBlock") collectVarDeclNames(stmt.body ?? [], out);
+		else if (stmt.type === "IfStatement") {
+			if (stmt.consequent) collectVarDeclNames([stmt.consequent], out);
+			if (stmt.alternate) collectVarDeclNames([stmt.alternate], out);
+		} else if (stmt.type === "SwitchStatement") for (const c of stmt.cases ?? []) collectVarDeclNames(c.consequent ?? [], out);
+		else if (stmt.type === "ForStatement" || stmt.type === "ForInStatement" || stmt.type === "ForOfStatement" || stmt.type === "WhileStatement" || stmt.type === "DoWhileStatement") {
+			const init = stmt.init ?? stmt.left;
+			if (init?.type === "VariableDeclaration" && init.kind === "var") {
+				for (const decl of init.declarations ?? []) if (decl.id) collectPatternNames(decl.id, out);
+			}
+			if (stmt.body) collectVarDeclNames([stmt.body], out);
+		} else if (stmt.type === "WithStatement" || stmt.type === "LabeledStatement") {
+			if (stmt.body) collectVarDeclNames([stmt.body], out);
+		} else if (stmt.type === "TryStatement") {
+			if (stmt.block) collectVarDeclNames([stmt.block], out);
+			const handler = stmt.handler;
+			if (handler?.body) collectVarDeclNames([handler.body], out);
+			if (stmt.finalizer) collectVarDeclNames([stmt.finalizer], out);
+		}
+	}
+}
+/**
+* Collect byte ranges where any name in `tracked` is shadowed by a
+* function/arrow parameter, catch clause binding, or lexical declaration
+* (`const`/`let`/`var`, `function`, `class`, for-loop binding). Calls
+* inside these ranges must NOT be rewritten — the name resolves to the
+* local binding, not the import (TIM-1141).
+*
+* Each range records WHICH names are shadowed so the consumer can skip
+* only calls to the shadowed name, not unrelated imports (codex review
+* on PR #876).
+*
+* When a scope shadows some-but-not-all tracked names, the walker
+* continues descending to find inner scopes that shadow remaining names
+* (codex review round 2 on PR #876).
+*/
+function collectShadowRanges(node, tracked, ranges) {
+	if (tracked.size === 0) return;
+	const isFn = node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression";
+	let remainingTracked = tracked;
+	if (isFn) {
+		const paramNames = /* @__PURE__ */ new Set();
+		for (const p of node.params ?? []) collectPatternNames(p, paramNames);
+		if (node.type === "FunctionExpression" && node.id) {
+			const fnId = node.id;
+			if (fnId.type === "Identifier") paramNames.add(fnId.name);
+		}
+		const shadowed = /* @__PURE__ */ new Set();
+		for (const n of paramNames) if (tracked.has(n)) shadowed.add(n);
+		if (shadowed.size > 0) {
+			ranges.push({
+				start: node.start,
+				end: node.end,
+				names: shadowed
+			});
+			if (shadowed.size === tracked.size) return;
+			remainingTracked = new Set([...tracked].filter((n) => !shadowed.has(n)));
+		}
+	}
+	if (node.type === "CatchClause") {
+		const param = node.param;
+		if (param) {
+			const shadowed = shadowedParamNames([param], tracked);
+			if (shadowed) {
+				ranges.push({
+					start: node.start,
+					end: node.end,
+					names: shadowed
+				});
+				if (shadowed.size === tracked.size) return;
+				remainingTracked = new Set([...tracked].filter((n) => !shadowed.has(n)));
+			}
+		}
+	}
+	if (node.type === "ClassExpression" && node.id) {
+		const clsId = node.id;
+		if (clsId.type === "Identifier" && remainingTracked.has(clsId.name)) {
+			const names = /* @__PURE__ */ new Set([clsId.name]);
+			ranges.push({
+				start: node.start,
+				end: node.end,
+				names
+			});
+			if (names.size === remainingTracked.size) return;
+			remainingTracked = new Set([...remainingTracked].filter((n) => !names.has(n)));
+		}
+	}
+	if (node.type === "ForStatement" || node.type === "ForInStatement" || node.type === "ForOfStatement") {
+		const loopNames = /* @__PURE__ */ new Set();
+		collectForLoopBlockBindingNames(node, loopNames);
+		const loopShadowed = /* @__PURE__ */ new Set();
+		for (const n of loopNames) if (remainingTracked.has(n)) loopShadowed.add(n);
+		if (loopShadowed.size > 0) {
+			ranges.push({
+				start: node.start,
+				end: node.end,
+				names: loopShadowed
+			});
+			if (loopShadowed.size === remainingTracked.size) return;
+			remainingTracked = new Set([...remainingTracked].filter((n) => !loopShadowed.has(n)));
+		}
+	}
+	if (isFn || node.type === "BlockStatement" || node.type === "SwitchStatement" || node.type === "StaticBlock") {
+		let bodyStmts = null;
+		if (isFn) {
+			const body = node.body;
+			if (body?.type === "BlockStatement") bodyStmts = body.body ?? null;
+		} else if (node.type === "SwitchStatement") {
+			const caseStmts = [];
+			for (const c of node.cases ?? []) for (const s of c.consequent ?? []) caseStmts.push(s);
+			bodyStmts = caseStmts;
+		} else bodyStmts = node.body ?? null;
+		if (bodyStmts) {
+			const declNames = /* @__PURE__ */ new Set();
+			collectLexicalDeclNames(bodyStmts, declNames);
+			if (isFn) collectVarDeclNames(bodyStmts, declNames);
+			const lexShadowed = /* @__PURE__ */ new Set();
+			for (const n of declNames) if (remainingTracked.has(n)) lexShadowed.add(n);
+			if (lexShadowed.size > 0) {
+				ranges.push({
+					start: node.start,
+					end: node.end,
+					names: lexShadowed
+				});
+				if (lexShadowed.size === remainingTracked.size) return;
+				remainingTracked = new Set([...remainingTracked].filter((n) => !lexShadowed.has(n)));
+			}
+		}
+	}
+	for (const key of Object.keys(node)) {
+		if (key === "type" || key === "start" || key === "end") continue;
+		const val = node[key];
+		if (val && typeof val === "object") {
+			if (Array.isArray(val)) {
+				for (const item of val) if (item && typeof item === "object" && typeof item.type === "string") collectShadowRanges(item, remainingTracked, ranges);
+			} else if (typeof val.type === "string") collectShadowRanges(val, remainingTracked, ranges);
+		}
+	}
+}
 /**
 * Recursively walk AST nodes collecting call expressions accepted by
 * `matches`. Calls are typically at module scope, but calls inside
 * functions/blocks are handled for completeness.
 *
-* NOTE: matching is by binding NAME, so nested scopes that shadow a tracked
-* import can produce false positives for consumers of this walker (see
-* TIM-1141 for the cache transform). The prebuilt transform avoids the
-* class entirely by not using this walker — it allowlists top-level
-* declarator positions instead (plugins/prebuilt.ts).
+* Consumers that match by binding NAME should pair this with
+* `collectShadowRanges` to filter out calls in scopes where the tracked
+* name is shadowed (TIM-1141). The prebuilt transform avoids the class
+* entirely by allowlisting top-level declarator positions
+* (plugins/prebuilt.ts).
 */
 function findCallSites(node, matches, results) {
 	if (node.type === "CallExpression") {
@@ -7064,6 +7284,24 @@ function isCacheCallee(callee, bindings) {
 	return false;
 }
 /**
+* Extract the local binding name that a cache callee resolves to — the
+* identifier for named imports, or the namespace object for `ns.cache()`.
+*/
+function calleeBindingName(callee, bindings) {
+	if (callee.type === "Identifier") {
+		const name = callee.name;
+		return bindings.named.has(name) ? name : null;
+	}
+	if (callee.type === "MemberExpression") {
+		const member = callee;
+		if (member.object.type === "Identifier") {
+			const name = member.object.name;
+			return bindings.namespaces.has(name) ? name : null;
+		}
+	}
+	return null;
+}
+/**
 * Generate a stable callsite ID for a cache() call. See callsite-ast.ts for
 * the derivation properties.
 */
@@ -7084,10 +7322,18 @@ function timberCacheTransform(ctx) {
 			}
 			const cacheBindings = findImportBindings(program, CACHE_MODULE_SOURCES, "cache");
 			if (cacheBindings.named.size === 0 && cacheBindings.namespaces.size === 0) return;
+			const trackedNames = /* @__PURE__ */ new Set([...cacheBindings.named, ...cacheBindings.namespaces]);
+			const shadowRanges = [];
+			collectShadowRanges(program, trackedNames, shadowRanges);
+			const isCalleeShadowed = (call) => {
+				const name = calleeBindingName(call.callee, cacheBindings);
+				if (!name) return false;
+				return shadowRanges.some((r) => call.start >= r.start && call.start < r.end && r.names.has(name));
+			};
 			const callSites = [];
 			for (const stmt of program.body) {
 				const calls = [];
-				findCallSites(stmt, (call) => call.arguments.length === 2 && isCacheCallee(call.callee, cacheBindings), calls);
+				findCallSites(stmt, (call) => call.arguments.length === 2 && isCacheCallee(call.callee, cacheBindings) && !isCalleeShadowed(call), calls);
 				for (const call of calls) callSites.push({
 					call,
 					stmt
@@ -7376,6 +7622,7 @@ async function runPrebuiltCapture(ctx) {
 	if (ctx.buildManifest) g.__TIMBER_BUILD_MANIFEST__ ??= ctx.buildManifest;
 	if (ctx.deploymentId) g.__TIMBER_DEPLOYMENT_ID__ ??= ctx.deploymentId;
 	console.log("[timber] cache.component: capturing prebuilt flight payloads…");
+	g.__TIMBER_CAPTURE_MODE__ = true;
 	let mod;
 	try {
 		mod = await import(