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

package/dist/_chunks/request-context-qMsWgy9C.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context-qMsWgy9C.js","names":[],"sources":["../../src/server/request-context.ts"],"sourcesContent":["/**\n * Request Context — per-request ALS store for getHeaders() and getCookies().\n *\n * Follows the same pattern as tracing.ts: a module-level AsyncLocalStorage\n * instance, public accessor functions that throw outside request scope,\n * and a framework-internal `runWithRequestContext()` to establish scope.\n *\n * See design/04-authorization.md §\"AccessContext does not include cookies or headers\"\n * and design/11-platform.md §\"AsyncLocalStorage\".\n * See design/29-cookies.md for cookie mutation semantics.\n */\n\nimport { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';\nimport { isDebug } from './debug.js';\nimport { _setGetSearchParamsFn } from '../search-params/define.js';\nimport { _setGetSegmentParamsFn } from '../segment-params/define.js';\n\n// Re-export the ALS for framework-internal consumers that need direct access.\nexport { requestContextAls };\n\n// No fallback needed — we use enterWith() instead of run() to ensure\n// the ALS context persists for the entire request lifecycle including\n// async stream consumption by React's renderToReadableStream.\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Returns a read-only view of the current request's headers.\n *\n * Available in middleware, access checks, server components, and server actions.\n * Throws if called outside a request context (security principle #2: no global fallback).\n */\nexport function getHeaders(): Promise<ReadonlyHeaders> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] getHeaders() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  return Promise.resolve(store.headers);\n}\n\n/**\n * Returns the value of a single request header, or undefined if absent.\n *\n * Thin wrapper over `(await getHeaders()).get(name)` for the common\n * case where you need exactly one header.\n *\n * ```ts\n * import { getHeader } from '@timber-js/app/server'\n *\n * export default async function Page() {\n *   const auth = await getHeader('authorization');\n * }\n * ```\n */\nexport async function getHeader(name: string): Promise<string | undefined> {\n  const headers = await getHeaders();\n  return headers.get(name) ?? undefined;\n}\n\n/**\n * Returns a cookie accessor for the current request.\n *\n * Available in middleware, access checks, server components, and server actions.\n * Throws if called outside a request context (security principle #2: no global fallback).\n *\n * Read methods (.get, .has, .getAll) are always available and reflect\n * read-your-own-writes from .set() calls in the same request.\n *\n * Mutation methods (.set, .delete, .clear) are only available in mutable\n * contexts (middleware.ts, server actions, route.ts handlers). Calling them\n * in read-only contexts (access.ts, server components) throws.\n *\n * See design/29-cookies.md\n */\nexport function getCookies(): Promise<RequestCookies> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] getCookies() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n\n  // Parse cookies lazily on first access\n  if (!store.parsedCookies) {\n    store.parsedCookies = parseCookieHeader(store.cookieHeader);\n  }\n\n  const map = store.parsedCookies;\n  return Promise.resolve({\n    get(name: string): string | undefined {\n      return map.get(name);\n    },\n    has(name: string): boolean {\n      return map.has(name);\n    },\n    getAll(): Array<{ name: string; value: string }> {\n      return Array.from(map.entries()).map(([name, value]) => ({ name, value }));\n    },\n    get size(): number {\n      return map.size;\n    },\n\n    set(name: string, value: string, options?: CookieOptions): void {\n      assertMutable(store, 'set');\n      if (store.flushed) {\n        if (isDebug()) {\n          console.warn(\n            `[timber] warn: getCookies().set('${name}') called after response headers were committed.\\n` +\n              `  The cookie will NOT be sent. Move cookie mutations to middleware.ts, a server action,\\n` +\n              `  or a route.ts handler.`\n          );\n        }\n        return;\n      }\n      const opts = { ...DEFAULT_COOKIE_OPTIONS, ...options };\n      store.cookieJar.set(name, { name, value, options: opts });\n      // Read-your-own-writes: update the parsed cookies map\n      map.set(name, value);\n    },\n\n    setFromHeaders(headers: Headers): void {\n      assertMutable(store, 'setFromHeaders');\n      if (store.flushed) {\n        console.warn(\n          `[timber] warn: getCookies().setFromHeaders() called after response headers were committed.\\n` +\n            `  The cookies will NOT be sent. Move cookie mutations to middleware.ts, a server action,\\n` +\n            `  or a route.ts handler.`\n        );\n        return;\n      }\n      // Headers.getSetCookie() returns individual Set-Cookie strings,\n      // avoiding the fragile comma-splitting that raw .get() requires.\n      for (const raw of headers.getSetCookie()) {\n        const parsed = parseSetCookie(raw);\n        if (parsed) {\n          // Use setRaw to preserve the original header's attributes without\n          // merging DEFAULT_COOKIE_OPTIONS (parseSetCookie intentionally\n          // does not apply defaults — see its doc comment).\n          setRaw(store, map, parsed.name, parsed.value, parsed.options);\n        }\n      }\n    },\n\n    delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {\n      assertMutable(store, 'delete');\n      if (store.flushed) {\n        if (isDebug()) {\n          console.warn(\n            `[timber] warn: getCookies().delete('${name}') called after response headers were committed.\\n` +\n              `  The cookie will NOT be deleted. Move cookie mutations to middleware.ts, a server action,\\n` +\n              `  or a route.ts handler.`\n          );\n        }\n        return;\n      }\n      const opts: CookieOptions = {\n        ...DEFAULT_COOKIE_OPTIONS,\n        ...options,\n        maxAge: 0,\n        expires: new Date(0),\n      };\n      store.cookieJar.set(name, { name, value: '', options: opts });\n      // Remove from read view\n      map.delete(name);\n    },\n\n    clear(): void {\n      assertMutable(store, 'clear');\n      if (store.flushed) return;\n      // Delete every incoming cookie\n      for (const name of Array.from(map.keys())) {\n        store.cookieJar.set(name, {\n          name,\n          value: '',\n          options: { ...DEFAULT_COOKIE_OPTIONS, maxAge: 0, expires: new Date(0) },\n        });\n      }\n      map.clear();\n    },\n\n    toString(): string {\n      return Array.from(map.entries())\n        .map(([name, value]) => `${name}=${value}`)\n        .join('; ');\n    },\n  });\n}\n\n/**\n * Returns the value of a single cookie, or undefined if absent.\n *\n * Thin wrapper over `(await getCookies()).get(name)` for the common\n * case where you need exactly one cookie.\n *\n * ```ts\n * import { getCookie } from '@timber-js/app/server'\n *\n * export default async function Page() {\n *   const session = await getCookie('session_id');\n * }\n * ```\n */\nexport async function getCookie(name: string): Promise<string | undefined> {\n  const cookies = await getCookies();\n  return cookies.get(name);\n}\n\n/**\n * Returns a Promise resolving to the current request's raw URLSearchParams.\n *\n * For typed, parsed search params, import the definition from params.ts\n * and call `.load()` or `.parse()`:\n *\n * ```ts\n * import { searchParams } from './params'\n * const parsed = await searchParams.get()\n * ```\n *\n * Or explicitly:\n *\n * ```ts\n * import { getSearchParams } from '@timber-js/app/server'\n * import { searchParams } from './params'\n * const parsed = searchParams.parse(await getSearchParams())\n * ```\n *\n * Throws if called outside a request context.\n */\nexport function getSearchParams(): Promise<URLSearchParams> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] getSearchParams() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  return store.searchParamsPromise;\n}\n\n// Eagerly register getSearchParams with the search-params module so\n// searchParams.get() can call it synchronously without a dynamic import.\n// Dynamic imports lose ALS context in React's RSC Flight renderer,\n// breaking getSearchParams() in parallel slot pages. See TIM-523.\n_setGetSearchParamsFn(getSearchParams);\n\n// Eagerly register getSegmentParams with the segment-params module so\n// segmentParams.get() can call it synchronously without a dynamic import.\n// Same pattern as search params — dynamic imports lose ALS context. See TIM-523.\n_setGetSegmentParamsFn(getSegmentParams);\n\n/**\n * Returns a Promise resolving to the current request's coerced segment params.\n *\n * Segment params are set by the pipeline after route matching and param\n * coercion (via params.ts codecs). When no params.ts exists, values are\n * raw strings. When codecs are defined, values are already coerced\n * (e.g., `id` is a `number` if `defineSegmentParams({ id: z.coerce.number() })`).\n *\n * This is the primary way page and layout components access route params:\n *\n * ```ts\n * import { getSegmentParams } from '@timber-js/app/server'\n *\n * export default async function Page() {\n *   const { slug } = await getSegmentParams()\n *   // ...\n * }\n * ```\n *\n * Throws if called outside a request context.\n */\nexport function getSegmentParams(): Promise<Record<string, string | string[]>> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] getSegmentParams() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  if (!store.segmentParamsPromise) {\n    throw new Error(\n      '[timber] getSegmentParams() called before route matching completed. ' +\n        'Segment params are not available until after the route is matched.'\n    );\n  }\n  return store.segmentParamsPromise;\n}\n\n/**\n * Set the segment params promise on the current request context.\n * Called by the pipeline after route matching and param coercion.\n *\n * @internal — framework use only\n */\nexport function setSegmentParams(params: Record<string, string | string[]>): void {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error('[timber] setSegmentParams() called outside of a request context.');\n  }\n  store.segmentParamsPromise = Promise.resolve(params);\n}\n\n/**\n * Returns the raw search string from the current request URL (e.g. \"?foo=bar\").\n * Synchronous — safe for use in `redirect()` which throws synchronously.\n *\n * Returns empty string if called outside a request context (non-throwing for\n * use in redirect's optional preserveSearchParams path).\n *\n * @internal — used by redirect() for preserveSearchParams support.\n */\nexport function getRequestSearchString(): string {\n  const store = requestContextAls.getStore();\n  return store?.searchString ?? '';\n}\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\n/**\n * Read-only Headers interface. The standard Headers class is mutable;\n * this type narrows it to read-only methods. The underlying object is\n * still a Headers instance, but user code should not mutate it.\n */\nexport type ReadonlyHeaders = Pick<\n  Headers,\n  'get' | 'has' | 'entries' | 'keys' | 'values' | 'forEach' | typeof Symbol.iterator\n>;\n\n/** Options for setting a cookie. See design/29-cookies.md. */\nexport interface CookieOptions {\n  /** Domain scope. Default: omitted (current domain only). */\n  domain?: string;\n  /** URL path scope. Default: '/'. */\n  path?: string;\n  /** Expiration date. Mutually exclusive with maxAge. */\n  expires?: Date;\n  /** Max age in seconds. Mutually exclusive with expires. */\n  maxAge?: number;\n  /** Prevent client-side JS access. Default: true. */\n  httpOnly?: boolean;\n  /** Only send over HTTPS. Default: true. */\n  secure?: boolean;\n  /** Cross-site request policy. Default: 'lax'. */\n  sameSite?: 'strict' | 'lax' | 'none';\n  /** Partitioned (CHIPS) — isolate cookie per top-level site. Default: false. */\n  partitioned?: boolean;\n}\n\nconst DEFAULT_COOKIE_OPTIONS: CookieOptions = {\n  path: '/',\n  httpOnly: true,\n  secure: true,\n  sameSite: 'lax',\n};\n\n/**\n * Write a cookie to the jar WITHOUT merging DEFAULT_COOKIE_OPTIONS.\n * Used by setFromHeaders to preserve the original header's attributes exactly.\n *\n * For deletion cookies (maxAge=0), the jar entry is still created so the\n * Set-Cookie header is emitted, but the cookie is NOT added to the read map\n * (it would be misleading — the cookie is being deleted).\n */\nfunction setRaw(\n  store: RequestContextStore,\n  readMap: Map<string, string>,\n  name: string,\n  value: string,\n  options: CookieOptions\n): void {\n  store.cookieJar.set(name, { name, value, options });\n  // Deletion cookies (Max-Age=0) should not appear in the read map\n  if (options.maxAge === 0) {\n    readMap.delete(name);\n  } else {\n    readMap.set(name, value);\n  }\n}\n\n/**\n * Parse a raw `Set-Cookie` header string into name, value, and options.\n * Handles all standard attributes: Path, Domain, Max-Age, Expires,\n * SameSite, Secure, HttpOnly, Partitioned.\n *\n * Does NOT apply DEFAULT_COOKIE_OPTIONS — the caller decides whether\n * to merge defaults (e.g. `set()` does, but `setRaw()` should preserve\n * the original header's intent).\n */\nfunction parseSetCookie(\n  header: string\n): { name: string; value: string; options: CookieOptions } | null {\n  const segments = header.split(';');\n  const nameValue = segments[0];\n  const eqIdx = nameValue.indexOf('=');\n  if (eqIdx <= 0) return null;\n\n  const name = nameValue.slice(0, eqIdx).trim();\n  const value = nameValue.slice(eqIdx + 1).trim();\n  const options: CookieOptions = {};\n\n  for (let i = 1; i < segments.length; i++) {\n    const seg = segments[i].trim();\n    if (!seg) continue;\n    const [attrName, ...rest] = seg.split('=');\n    const key = attrName.trim().toLowerCase();\n    const val = rest.join('=').trim();\n    switch (key) {\n      case 'path':\n        options.path = val || '/';\n        break;\n      case 'domain':\n        options.domain = val;\n        break;\n      case 'max-age':\n        options.maxAge = Number(val);\n        break;\n      case 'expires':\n        options.expires = new Date(val);\n        break;\n      case 'samesite':\n        options.sameSite = val.toLowerCase() as 'strict' | 'lax' | 'none';\n        break;\n      case 'secure':\n        options.secure = true;\n        break;\n      case 'httponly':\n        options.httpOnly = true;\n        break;\n      case 'partitioned':\n        options.partitioned = true;\n        break;\n    }\n  }\n\n  return { name, value, options };\n}\n\n/**\n * Cookie accessor returned by `getCookies()`.\n *\n * Read methods are always available. Mutation methods throw in read-only\n * contexts (access.ts, server components).\n */\nexport interface RequestCookies {\n  /** Get a cookie value by name. Returns undefined if not present. */\n  get(name: string): string | undefined;\n  /** Check if a cookie exists. */\n  has(name: string): boolean;\n  /** Get all cookies as an array of { name, value } pairs. */\n  getAll(): Array<{ name: string; value: string }>;\n  /** Number of cookies. */\n  readonly size: number;\n  /** Set a cookie. Only available in mutable contexts (middleware, actions, route handlers). */\n  set(name: string, value: string, options?: CookieOptions): void;\n  /**\n   * Copy all `Set-Cookie` headers from a `Headers` object.\n   * Parses each header and forwards name, value, and all attributes\n   * (path, domain, max-age, expires, sameSite, secure, httpOnly, partitioned).\n   *\n   * Useful when forwarding cookies from an internal `fetch()` or auth handler:\n   * ```ts\n   * const response = await auth.handler(req);\n   * getCookies().then(c => c.setFromHeaders(response.headers));\n   * ```\n   */\n  setFromHeaders(headers: Headers): void;\n  /** Delete a cookie. Only available in mutable contexts. */\n  delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;\n  /** Delete all cookies. Only available in mutable contexts. */\n  clear(): void;\n  /** Serialize cookies as a Cookie header string. */\n  toString(): string;\n}\n\n// ─── Framework-Internal Helpers ───────────────────────────────────────────\n\n/**\n * Run a callback within a request context. Used by the pipeline to establish\n * per-request ALS scope so that `getHeaders()` and `getCookies()` work.\n *\n * @param req - The incoming Request object.\n * @param fn - The function to run within the request context.\n */\nexport function runWithRequestContext<T>(req: Request, fn: () => T): T {\n  const originalCopy = new Headers(req.headers);\n  const parsedUrl = new URL(req.url);\n  const store: RequestContextStore = {\n    headers: freezeHeaders(req.headers),\n    originalHeaders: originalCopy,\n    cookieHeader: req.headers.get('cookie') ?? '',\n    searchParamsPromise: Promise.resolve(parsedUrl.searchParams),\n    searchString: parsedUrl.search,\n    cookieJar: new Map(),\n    flushed: false,\n    mutableContext: false,\n  };\n  return requestContextAls.run(store, fn);\n}\n\n/**\n * Enable cookie mutation for the current context. Called by the framework\n * when entering middleware.ts, server actions, or route.ts handlers.\n *\n * See design/29-cookies.md §\"Context Tracking\"\n */\nexport function setMutableCookieContext(mutable: boolean): void {\n  const store = requestContextAls.getStore();\n  if (store) {\n    store.mutableContext = mutable;\n  }\n}\n\n/**\n * Mark the response as flushed (headers committed). After this point,\n * cookie mutations log a warning instead of throwing.\n *\n * See design/29-cookies.md §\"Streaming Constraint: Post-Flush Cookie Warning\"\n */\nexport function markResponseFlushed(): void {\n  const store = requestContextAls.getStore();\n  if (store) {\n    store.flushed = true;\n  }\n}\n\n/**\n * Build a Map of cookie name → value reflecting the current request's\n * read-your-own-writes state. Includes incoming cookies plus any\n * mutations from getCookies().set() / getCookies().delete() in the same request.\n *\n * Used by SSR renderers to populate NavContext.cookies so that\n * useCookie()'s server snapshot matches the actual response state.\n *\n * See design/29-cookies.md §\"Read-Your-Own-Writes\"\n * See design/triage/TIM-441-cookie-api-triage.md §4\n */\nexport function getCookiesForSsr(): Map<string, string> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error('[timber] getCookiesForSsr() called outside of a request context.');\n  }\n\n  // Trigger lazy parsing if not yet done\n  if (!store.parsedCookies) {\n    store.parsedCookies = parseCookieHeader(store.cookieHeader);\n  }\n\n  // The parsedCookies map already reflects read-your-own-writes:\n  // - getCookies().set() updates the map via map.set(name, value)\n  // - getCookies().delete() removes from the map via map.delete(name)\n  // Return a copy so callers can't mutate the internal map.\n  return new Map(store.parsedCookies);\n}\n\n/**\n * Collect all Set-Cookie headers from the cookie jar.\n * Called by the framework at flush time to apply cookies to the response.\n *\n * Returns an array of serialized Set-Cookie header values.\n */\nexport function getSetCookieHeaders(): string[] {\n  const store = requestContextAls.getStore();\n  if (!store) return [];\n  return Array.from(store.cookieJar.values()).map(serializeCookieEntry);\n}\n\n/**\n * Apply middleware-injected request headers to the current request context.\n *\n * Called by the pipeline after middleware.ts runs. Merges overlay headers\n * on top of the original request headers so downstream code (access.ts,\n * server components, server actions) sees them via `getHeaders()`.\n *\n * The original request headers are never mutated — a new frozen Headers\n * object is created with the overlay applied on top.\n *\n * See design/07-routing.md §\"Request Header Injection\"\n */\nexport function applyRequestHeaderOverlay(overlay: Headers): void {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error('[timber] applyRequestHeaderOverlay() called outside of a request context.');\n  }\n\n  // Check if the overlay has any headers — skip if empty\n  let hasOverlay = false;\n  overlay.forEach(() => {\n    hasOverlay = true;\n  });\n  if (!hasOverlay) return;\n\n  // Merge: start with original headers, overlay on top\n  const merged = new Headers(store.originalHeaders);\n  overlay.forEach((value, key) => {\n    merged.set(key, value);\n  });\n  store.headers = freezeHeaders(merged);\n}\n\n// ─── Read-Only Headers ────────────────────────────────────────────────────\n\nconst MUTATING_METHODS = new Set(['set', 'append', 'delete']);\n\n/**\n * Wrap a Headers object in a Proxy that throws on mutating methods.\n * Object.freeze doesn't work on Headers (native internal slots), so we\n * intercept property access and reject set/append/delete at runtime.\n *\n * Read methods (get, has, entries, etc.) must be bound to the underlying\n * Headers instance because they access private #headersList slots.\n */\nfunction freezeHeaders(source: Headers): Headers {\n  const copy = new Headers(source);\n  return new Proxy(copy, {\n    get(target, prop) {\n      if (typeof prop === 'string' && MUTATING_METHODS.has(prop)) {\n        return () => {\n          throw new Error(\n            `[timber] getHeaders() returns a read-only Headers object. ` +\n              `Calling .${prop}() is not allowed. ` +\n              `Use ctx.requestHeaders in middleware to inject headers for downstream components.`\n          );\n        };\n      }\n      const value = Reflect.get(target, prop);\n      // Bind methods to the real Headers instance so private slot access works\n      if (typeof value === 'function') {\n        return value.bind(target);\n      }\n      return value;\n    },\n  });\n}\n\n// ─── Cookie Helpers ───────────────────────────────────────────────────────\n\n/** Throw if cookie mutation is attempted in a read-only context. */\nfunction assertMutable(store: RequestContextStore, method: string): void {\n  if (!store.mutableContext) {\n    throw new Error(\n      `(timber] getCookies().${method}() cannot be called in this context.\\n` +\n        `  Set cookies in middleware.ts, server actions, or route.ts handlers.`\n    );\n  }\n}\n\n/**\n * Parse a Cookie header string into a Map of name → value pairs.\n * Follows RFC 6265 §4.2.1: cookies are semicolon-separated key=value pairs.\n */\nfunction parseCookieHeader(header: string): Map<string, string> {\n  const map = new Map<string, string>();\n  if (!header) return map;\n\n  for (const pair of header.split(';')) {\n    const eqIndex = pair.indexOf('=');\n    if (eqIndex === -1) continue;\n    const name = pair.slice(0, eqIndex).trim();\n    const value = pair.slice(eqIndex + 1).trim();\n    if (name) {\n      map.set(name, value);\n    }\n  }\n\n  return map;\n}\n\n/** Serialize a CookieEntry into a Set-Cookie header value. */\nfunction serializeCookieEntry(entry: CookieEntry): string {\n  const parts = [`${entry.name}=${entry.value}`];\n  const opts = entry.options;\n\n  if (opts.domain) parts.push(`Domain=${opts.domain}`);\n  if (opts.path) parts.push(`Path=${opts.path}`);\n  if (opts.expires) parts.push(`Expires=${opts.expires.toUTCString()}`);\n  if (opts.maxAge !== undefined) parts.push(`Max-Age=${opts.maxAge}`);\n  if (opts.httpOnly) parts.push('HttpOnly');\n  if (opts.secure) parts.push('Secure');\n  if (opts.sameSite) {\n    parts.push(`SameSite=${opts.sameSite.charAt(0).toUpperCase()}${opts.sameSite.slice(1)}`);\n  }\n  if (opts.partitioned) parts.push('Partitioned');\n\n  return parts.join('; ');\n}\n"],"mappings":"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"}

package/dist/_chunks/{schema-bridge-C4SwjCQD.js → schema-bridge-C3xl_vfb.js}

@@ -83,4 +83,4 @@ function fromArraySchema(schema) {
 //#endregion
 export { validateSync as a, isStandardSchema as i, fromSchema as n, isCodec as r, fromArraySchema as t };
 
-//# sourceMappingURL=schema-bridge-C4SwjCQD.js.map
+//# sourceMappingURL=schema-bridge-C3xl_vfb.js.map

package/dist/_chunks/{schema-bridge-C4SwjCQD.js.map → schema-bridge-C3xl_vfb.js.map}

@@ -1 +1 @@
-{"version":3,"file":"schema-bridge-C4SwjCQD.js","names":[],"sources":["../../src/schema-bridge.ts"],"sourcesContent":["/**\n * Standard Schema bridge — shared helpers for bridging Standard Schema-compatible\n * validation libraries (Zod, Valibot, ArkType) to the Codec<T> protocol.\n *\n * This module is the single source of truth for:\n * - StandardSchemaV1 interface (subset of the Standard Schema spec)\n * - validateSync() helper\n * - fromSchema() — bridge from Standard Schema to Codec<T>\n * - fromArraySchema() — bridge for array-valued codecs\n *\n * These are re-exported from @timber-js/app/search-params, @timber-js/app/segment-params,\n * and @timber-js/app/cookies for convenience. The canonical import is\n * @timber-js/app/codec.\n *\n * Design doc: design/23a-search-params-triage.md §\"Unify Codec<T> type\"\n */\n\nimport type { Codec } from './codec.js';\n\n// ---------------------------------------------------------------------------\n// Standard Schema interface (subset)\n//\n// Standard Schema (https://github.com/standard-schema/standard-schema) defines\n// a minimal interface that Zod ≥3.24, Valibot ≥1.0, and ArkType all implement.\n// We depend only on `~standard.validate` to avoid coupling to any specific lib.\n// ---------------------------------------------------------------------------\n\n/** Minimal Standard Schema interface for auto-detection. */\nexport interface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;\n  };\n}\n\nexport type StandardSchemaResult<Output> =\n  | { value: Output; issues?: undefined }\n  | { value?: undefined; issues: ReadonlyArray<{ message: string }> };\n\n// ---------------------------------------------------------------------------\n// Sync validate helper\n// ---------------------------------------------------------------------------\n\n/**\n * Run a Standard Schema's `~standard.validate()` synchronously.\n *\n * Zod v4's signature includes `Promise` in the return union to satisfy the\n * Standard Schema spec, but in practice Zod always validates synchronously\n * for the schema types we use. We assert the result is sync and throw if\n * it isn't — codec parsing must be synchronous.\n */\nexport function validateSync<Output>(\n  schema: StandardSchemaV1<Output>,\n  value: unknown\n): StandardSchemaResult<Output> {\n  const result = schema['~standard'].validate(value);\n  if (result instanceof Promise) {\n    throw new Error(\n      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported.'\n    );\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// Type guards\n// ---------------------------------------------------------------------------\n\n/** Check if a value is a Standard Schema object. */\nexport function isStandardSchema(value: unknown): value is StandardSchemaV1 {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    '~standard' in value &&\n    typeof (value as StandardSchemaV1)['~standard']?.validate === 'function'\n  );\n}\n\n/** Check if a value is a Codec (has parse + serialize methods). */\nexport function isCodec(value: unknown): value is Codec<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as Codec<unknown>).parse === 'function' &&\n    typeof (value as Codec<unknown>).serialize === 'function'\n  );\n}\n\n// ---------------------------------------------------------------------------\n// fromSchema — bridge from Standard Schema to Codec<T>\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a\n * Codec<T>.\n *\n * Parse: coerces the raw string through the schema. On validation failure,\n * parses `undefined` to get the schema's default value (the schema should have\n * a `.default()` call). If that also fails, returns `undefined`.\n *\n * Serialize: uses `String()` for primitives, `null` for null/undefined.\n *\n * ```ts\n * import { fromSchema } from '@timber-js/app/codec'\n * import { z } from 'zod/v4'\n *\n * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))\n * ```\n */\nexport function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // For array inputs, take the last value (consistent with URLSearchParams.get())\n      const input = Array.isArray(value) ? value[value.length - 1] : value;\n\n      // Try parsing the raw value\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try parsing undefined to get the default\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      // No default available — return undefined (codec design choice)\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      return String(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// fromArraySchema — bridge for array-valued codecs\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema for array values. Handles both single strings\n * and repeated query keys (`?tag=a&tag=b`).\n *\n * ```ts\n * import { fromArraySchema } from '@timber-js/app/codec'\n * import { z } from 'zod/v4'\n *\n * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))\n * ```\n */\nexport function fromArraySchema<T>(schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // Coerce single string to array for array schemas\n      let input: unknown = value;\n      if (typeof value === 'string') {\n        input = [value];\n      } else if (value === undefined) {\n        input = undefined;\n      }\n\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try undefined for default\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      if (Array.isArray(value)) {\n        return value.length === 0 ? null : value.join(',');\n      }\n      return String(value);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;AAkDA,SAAgB,aACd,QACA,OAC8B;CAC9B,MAAM,SAAS,OAAO,aAAa,SAAS,MAAM;AAClD,KAAI,kBAAkB,QACpB,OAAM,IAAI,MACR,oFACD;AAEH,QAAO;;;AAQT,SAAgB,iBAAiB,OAA2C;AAC1E,QACE,OAAO,UAAU,YACjB,UAAU,QACV,eAAe,SACf,OAAQ,MAA2B,cAAc,aAAa;;;AAKlE,SAAgB,QAAQ,OAAyC;AAC/D,QACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAAyB,UAAU,cAC3C,OAAQ,MAAyB,cAAc;;;;;;;;;;;;;;;;;;;AAyBnD,SAAgB,WAAc,QAAuC;AACnE,QAAO;EACL,MAAM,OAAyC;GAK7C,MAAM,SAAS,aAAa,QAHd,MAAM,QAAQ,MAAM,GAAG,MAAM,MAAM,SAAS,KAAK,MAGrB;AAC1C,OAAI,CAAC,OAAO,OACV,QAAO,OAAO;GAIhB,MAAM,gBAAgB,aAAa,QAAQ,KAAA,EAAU;AACrD,OAAI,CAAC,cAAc,OACjB,QAAO,cAAc;;EAOzB,UAAU,OAAyB;AACjC,OAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B,QAAO;AAET,UAAO,OAAO,MAAM;;EAEvB;;;;;;;;;;;;;AAkBH,SAAgB,gBAAmB,QAAuC;AACxE,QAAO;EACL,MAAM,OAAyC;GAE7C,IAAI,QAAiB;AACrB,OAAI,OAAO,UAAU,SACnB,SAAQ,CAAC,MAAM;YACN,UAAU,KAAA,EACnB,SAAQ,KAAA;GAGV,MAAM,SAAS,aAAa,QAAQ,MAAM;AAC1C,OAAI,CAAC,OAAO,OACV,QAAO,OAAO;GAIhB,MAAM,gBAAgB,aAAa,QAAQ,KAAA,EAAU;AACrD,OAAI,CAAC,cAAc,OACjB,QAAO,cAAc;;EAMzB,UAAU,OAAyB;AACjC,OAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B,QAAO;AAET,OAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,MAAM,WAAW,IAAI,OAAO,MAAM,KAAK,IAAI;AAEpD,UAAO,OAAO,MAAM;;EAEvB"}
+{"version":3,"file":"schema-bridge-C3xl_vfb.js","names":[],"sources":["../../src/schema-bridge.ts"],"sourcesContent":["/**\n * Standard Schema bridge — shared helpers for bridging Standard Schema-compatible\n * validation libraries (Zod, Valibot, ArkType) to the Codec<T> protocol.\n *\n * This module is the single source of truth for:\n * - StandardSchemaV1 interface (subset of the Standard Schema spec)\n * - validateSync() helper\n * - fromSchema() — bridge from Standard Schema to Codec<T>\n * - fromArraySchema() — bridge for array-valued codecs\n *\n * These are re-exported from @timber-js/app/search-params, @timber-js/app/segment-params,\n * and @timber-js/app/cookies for convenience. The canonical import is\n * @timber-js/app/codec.\n *\n * Design doc: design/23a-search-params-triage.md §\"Unify Codec<T> type\"\n */\n\nimport type { Codec } from './codec.js';\n\n// ---------------------------------------------------------------------------\n// Standard Schema interface (subset)\n//\n// Standard Schema (https://github.com/standard-schema/standard-schema) defines\n// a minimal interface that Zod ≥3.24, Valibot ≥1.0, and ArkType all implement.\n// We depend only on `~standard.validate` to avoid coupling to any specific lib.\n// ---------------------------------------------------------------------------\n\n/** Minimal Standard Schema interface for auto-detection. */\nexport interface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;\n  };\n}\n\nexport type StandardSchemaResult<Output> =\n  | { value: Output; issues?: undefined }\n  | { value?: undefined; issues: ReadonlyArray<{ message: string }> };\n\n// ---------------------------------------------------------------------------\n// Sync validate helper\n// ---------------------------------------------------------------------------\n\n/**\n * Run a Standard Schema's `~standard.validate()` synchronously.\n *\n * Zod v4's signature includes `Promise` in the return union to satisfy the\n * Standard Schema spec, but in practice Zod always validates synchronously\n * for the schema types we use. We assert the result is sync and throw if\n * it isn't — codec parsing must be synchronous.\n */\nexport function validateSync<Output>(\n  schema: StandardSchemaV1<Output>,\n  value: unknown\n): StandardSchemaResult<Output> {\n  const result = schema['~standard'].validate(value);\n  if (result instanceof Promise) {\n    throw new Error(\n      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported.'\n    );\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// Type guards\n// ---------------------------------------------------------------------------\n\n/** Check if a value is a Standard Schema object. */\nexport function isStandardSchema(value: unknown): value is StandardSchemaV1 {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    '~standard' in value &&\n    typeof (value as StandardSchemaV1)['~standard']?.validate === 'function'\n  );\n}\n\n/** Check if a value is a Codec (has parse + serialize methods). */\nexport function isCodec(value: unknown): value is Codec<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as Codec<unknown>).parse === 'function' &&\n    typeof (value as Codec<unknown>).serialize === 'function'\n  );\n}\n\n// ---------------------------------------------------------------------------\n// fromSchema — bridge from Standard Schema to Codec<T>\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a\n * Codec<T>.\n *\n * Parse: coerces the raw string through the schema. On validation failure,\n * parses `undefined` to get the schema's default value (the schema should have\n * a `.default()` call). If that also fails, returns `undefined`.\n *\n * Serialize: uses `String()` for primitives, `null` for null/undefined.\n *\n * ```ts\n * import { fromSchema } from '@timber-js/app/codec'\n * import { z } from 'zod/v4'\n *\n * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))\n * ```\n */\nexport function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // For array inputs, take the last value (consistent with URLSearchParams.get())\n      const input = Array.isArray(value) ? value[value.length - 1] : value;\n\n      // Try parsing the raw value\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try parsing undefined to get the default\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      // No default available — return undefined (codec design choice)\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      return String(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// fromArraySchema — bridge for array-valued codecs\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema for array values. Handles both single strings\n * and repeated query keys (`?tag=a&tag=b`).\n *\n * ```ts\n * import { fromArraySchema } from '@timber-js/app/codec'\n * import { z } from 'zod/v4'\n *\n * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))\n * ```\n */\nexport function fromArraySchema<T>(schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // Coerce single string to array for array schemas\n      let input: unknown = value;\n      if (typeof value === 'string') {\n        input = [value];\n      } else if (value === undefined) {\n        input = undefined;\n      }\n\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try undefined for default\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      if (Array.isArray(value)) {\n        return value.length === 0 ? null : value.join(',');\n      }\n      return String(value);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;AAkDA,SAAgB,aACd,QACA,OAC8B;CAC9B,MAAM,SAAS,OAAO,aAAa,SAAS,MAAM;AAClD,KAAI,kBAAkB,QACpB,OAAM,IAAI,MACR,oFACD;AAEH,QAAO;;;AAQT,SAAgB,iBAAiB,OAA2C;AAC1E,QACE,OAAO,UAAU,YACjB,UAAU,QACV,eAAe,SACf,OAAQ,MAA2B,cAAc,aAAa;;;AAKlE,SAAgB,QAAQ,OAAyC;AAC/D,QACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAAyB,UAAU,cAC3C,OAAQ,MAAyB,cAAc;;;;;;;;;;;;;;;;;;;AAyBnD,SAAgB,WAAc,QAAuC;AACnE,QAAO;EACL,MAAM,OAAyC;GAK7C,MAAM,SAAS,aAAa,QAHd,MAAM,QAAQ,MAAM,GAAG,MAAM,MAAM,SAAS,KAAK,MAGrB;AAC1C,OAAI,CAAC,OAAO,OACV,QAAO,OAAO;GAIhB,MAAM,gBAAgB,aAAa,QAAQ,KAAA,EAAU;AACrD,OAAI,CAAC,cAAc,OACjB,QAAO,cAAc;;EAOzB,UAAU,OAAyB;AACjC,OAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B,QAAO;AAET,UAAO,OAAO,MAAM;;EAEvB;;;;;;;;;;;;;AAkBH,SAAgB,gBAAmB,QAAuC;AACxE,QAAO;EACL,MAAM,OAAyC;GAE7C,IAAI,QAAiB;AACrB,OAAI,OAAO,UAAU,SACnB,SAAQ,CAAC,MAAM;YACN,UAAU,KAAA,EACnB,SAAQ,KAAA;GAGV,MAAM,SAAS,aAAa,QAAQ,MAAM;AAC1C,OAAI,CAAC,OAAO,OACV,QAAO,OAAO;GAIhB,MAAM,gBAAgB,aAAa,QAAQ,KAAA,EAAU;AACrD,OAAI,CAAC,cAAc,OACjB,QAAO,cAAc;;EAMzB,UAAU,OAAyB;AACjC,OAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B,QAAO;AAET,OAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,MAAM,WAAW,IAAI,OAAO,MAAM,KAAK,IAAI;AAEpD,UAAO,OAAO,MAAM;;EAEvB"}

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

@@ -0,0 +1,34 @@
+import { createContext, createElement, useContext, useMemo } from "react";
+//#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, SegmentProvider as t };
+
+//# sourceMappingURL=segment-context-fHFLF1PE.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"segment-context-fHFLF1PE.js","names":[],"sources":["../../src/client/segment-context.ts"],"sourcesContent":["/**\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":";;;;;;;;;;;;;;AA4BA,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/ssr-data-DzuI0bIV.js

@@ -0,0 +1,88 @@
+//#region src/client/state.ts
+/** The global router singleton — set once during bootstrap. */
+var globalRouter = null;
+function _setGlobalRouter(router) {
+	globalRouter = router;
+}
+/**
+* ALS-backed SSR data provider. When registered, getSsrData() reads from
+* this function (ALS store) instead of module-level currentSsrData.
+*/
+var ssrDataProvider;
+/** Fallback SSR data for tests and environments without ALS. */
+var currentSsrData;
+function _setCurrentSsrData(data) {
+	currentSsrData = data;
+}
+/** Current route params snapshot — replaced (not mutated) on each navigation. */
+var currentParams = {};
+function _setCurrentParams(params) {
+	currentParams = params;
+}
+/** Cached search string — avoids reparsing when URL hasn't changed. */
+var cachedSearch = "";
+var cachedSearchParams = new URLSearchParams();
+function _setCachedSearch(search, params) {
+	cachedSearch = search;
+	cachedSearchParams = params;
+}
+//#endregion
+//#region src/client/ssr-data.ts
+/**
+* SSR Data — per-request state for client hooks during server-side rendering.
+*
+* RSC and SSR are separate Vite module graphs (see design/18-build-system.md),
+* so the RSC environment's request-context ALS is not visible to SSR modules.
+* This module provides getter/setter functions that ssr-entry.ts uses to
+* populate per-request data for React's render.
+*
+* Request isolation: On the server, ssr-entry.ts registers an ALS-backed
+* provider via registerSsrDataProvider(). getSsrData() reads from the ALS
+* store, ensuring correct per-request data even when Suspense boundaries
+* resolve asynchronously across concurrent requests. The module-level
+* setSsrData/clearSsrData functions are kept as a fallback for tests
+* and environments without ALS.
+*
+* IMPORTANT: This module must NOT import node:async_hooks or any Node.js-only
+* APIs, as it's imported by 'use client' hooks that are bundled for the browser.
+* The ALS instance lives in ssr-entry.ts (server-only); this module only holds
+* a reference to the provider function.
+*
+* All mutable state is delegated to client/state.ts for singleton guarantees.
+* See design/18-build-system.md §"Singleton State Registry"
+*/
+/**
+* Set the SSR data for the current request via module-level state.
+*
+* In production, ssr-entry.ts uses ALS (runWithSsrData) instead.
+* This function is retained for tests and as a fallback.
+*/
+function setSsrData(data) {
+	_setCurrentSsrData(data);
+}
+/**
+* Clear the SSR data after rendering completes.
+*
+* In production, ALS scope handles cleanup automatically.
+* This function is retained for tests and as a fallback.
+*/
+function clearSsrData() {
+	_setCurrentSsrData(void 0);
+}
+/**
+* Read the current request's SSR data. Returns undefined when called
+* outside an SSR render (i.e. on the client after hydration).
+*
+* Prefers the ALS-backed provider when registered (server-side),
+* falling back to module-level state (tests, legacy).
+*
+* Used by client hooks' server snapshot functions.
+*/
+function getSsrData() {
+	if (ssrDataProvider) return ssrDataProvider();
+	return currentSsrData;
+}
+//#endregion
+export { _setCurrentParams as a, cachedSearchParams as c, _setCachedSearch as i, currentParams as l, getSsrData as n, _setGlobalRouter as o, setSsrData as r, cachedSearch as s, clearSsrData as t, globalRouter as u };
+
+//# sourceMappingURL=ssr-data-DzuI0bIV.js.map

package/dist/_chunks/ssr-data-DzuI0bIV.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-data-DzuI0bIV.js","names":[],"sources":["../../src/client/state.ts","../../src/client/ssr-data.ts"],"sourcesContent":["/**\n * Centralized client singleton state registry.\n *\n * ALL mutable module-level state that must have singleton semantics across\n * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,\n * use-params.ts, use-search-params.ts, unload-guard.ts) import from this file\n * and re-export thin wrapper functions.\n *\n * Why: In Vite dev, a module is instantiated separately if reached via different\n * import paths (e.g., relative `./foo.js` vs barrel `@timber-js/app/client`).\n * By centralizing all mutable state in a single module that is always reached\n * through the same dependency chain (barrel → wrapper → state.ts), we guarantee\n * a single instance of every piece of shared state.\n *\n * DO NOT import this file from outside client/. Server code must never depend\n * on client state. The barrel (client/index.ts) is the public entry point.\n *\n * See design/18-build-system.md §\"Module Singleton Strategy\" and\n * §\"Singleton State Registry\".\n */\n\nimport type { RouterInstance } from './router.js';\nimport type { SsrData } from './ssr-data.js';\n\n// ─── Router (from router-ref.ts) ──────────────────────────────────────────\n\n/** The global router singleton — set once during bootstrap. */\nexport let globalRouter: RouterInstance | null = null;\n\nexport function _setGlobalRouter(router: RouterInstance | null): void {\n  globalRouter = router;\n}\n\n// ─── SSR Data Provider (from ssr-data.ts) ──────────────────────────────────\n\n/**\n * ALS-backed SSR data provider. When registered, getSsrData() reads from\n * this function (ALS store) instead of module-level currentSsrData.\n */\nexport let ssrDataProvider: (() => SsrData | undefined) | undefined;\n\nexport function _setSsrDataProvider(provider: (() => SsrData | undefined) | undefined): void {\n  ssrDataProvider = provider;\n}\n\n/** Fallback SSR data for tests and environments without ALS. */\nexport let currentSsrData: SsrData | undefined;\n\nexport function _setCurrentSsrData(data: SsrData | undefined): void {\n  currentSsrData = data;\n}\n\n// ─── Route Params (from use-params.ts) ──────────────────────────────────────\n\n/** Current route params snapshot — replaced (not mutated) on each navigation. */\nexport let currentParams: Record<string, string | string[]> = {};\n\nexport function _setCurrentParams(params: Record<string, string | string[]>): void {\n  currentParams = params;\n}\n\n/** Listeners notified when currentParams changes. */\nexport const paramsListeners = new Set<() => void>();\n\n// ─── Search Params Cache (from use-search-params.ts) ────────────────────────\n\n/** Cached search string — avoids reparsing when URL hasn't changed. */\nexport let cachedSearch = '';\nexport let cachedSearchParams = new URLSearchParams();\n\nexport function _setCachedSearch(search: string, params: URLSearchParams): void {\n  cachedSearch = search;\n  cachedSearchParams = params;\n}\n\n// ─── Unload Guard (from unload-guard.ts) ─────────────────────────────────────\n\n/** Whether the page is currently being unloaded. */\nexport let unloading = false;\n\nexport function _setUnloading(value: boolean): void {\n  unloading = value;\n}\n","/**\n * SSR Data — per-request state for client hooks during server-side rendering.\n *\n * RSC and SSR are separate Vite module graphs (see design/18-build-system.md),\n * so the RSC environment's request-context ALS is not visible to SSR modules.\n * This module provides getter/setter functions that ssr-entry.ts uses to\n * populate per-request data for React's render.\n *\n * Request isolation: On the server, ssr-entry.ts registers an ALS-backed\n * provider via registerSsrDataProvider(). getSsrData() reads from the ALS\n * store, ensuring correct per-request data even when Suspense boundaries\n * resolve asynchronously across concurrent requests. The module-level\n * setSsrData/clearSsrData functions are kept as a fallback for tests\n * and environments without ALS.\n *\n * IMPORTANT: This module must NOT import node:async_hooks or any Node.js-only\n * APIs, as it's imported by 'use client' hooks that are bundled for the browser.\n * The ALS instance lives in ssr-entry.ts (server-only); this module only holds\n * a reference to the provider function.\n *\n * All mutable state is delegated to client/state.ts for singleton guarantees.\n * See design/18-build-system.md §\"Singleton State Registry\"\n */\n\nimport {\n  ssrDataProvider,\n  currentSsrData,\n  _setSsrDataProvider,\n  _setCurrentSsrData,\n} from './state.js';\n\n// ─── Types ────────────────────────────────────────────────────────\n\nexport interface SsrData {\n  /** The request's URL pathname (e.g. '/dashboard/settings') */\n  pathname: string;\n  /** The request's search params as a plain record */\n  searchParams: Record<string, string>;\n  /** The request's cookies as name→value pairs */\n  cookies: Map<string, string>;\n  /** The request's route params (e.g. { id: '123' }) */\n  params: Record<string, string | string[]>;\n  /**\n   * Mutable reference to NavContext for error boundary → pipeline communication.\n   *\n   * When TimberErrorBoundary catches a DenySignal during SSR, it:\n   * 1. Sets `statusCode` to the deny status (e.g., 403) — so the HTTP\n   *    Response has the correct status code without a re-render.\n   * 2. Sets `_denyHandledByBoundary = true` — so the pipeline skips\n   *    the redundant renderDenyPage() re-render.\n   *\n   * This runs synchronously during Fizz rendering, BEFORE onShellReady,\n   * so the status code is committed before any bytes are sent.\n   *\n   * See TIM-664, design/04-authorization.md §\"React.cache Scope in Deny/Error Re-renders\"\n   */\n  _navContext?: { statusCode?: number; _denyHandledByBoundary?: boolean };\n}\n\n// ─── ALS-Backed Provider ─────────────────────────────────────────\n//\n// Server-side code (ssr-entry.ts) registers a provider that reads\n// from AsyncLocalStorage. This avoids importing node:async_hooks\n// in this browser-bundled module.\n//\n// Module singleton guarantee: In Vite's SSR environment, both\n// ssr-entry.ts (via #/client/ssr-data.js) and client component hooks\n// (via @timber-js/app/client) must resolve to the SAME module instance\n// of this file. The timber-shims plugin ensures this by remapping\n// @timber-js/app/client → src/client/index.ts in the SSR environment.\n// Without this remap, @timber-js/app/client resolves to dist/ (via\n// package.json exports), creating a split where registerSsrDataProvider\n// writes to one instance but getSsrData reads from another.\n// See timber-shims plugin resolveId for details.\n\n/**\n * Register an ALS-backed SSR data provider. Called once at module load\n * by ssr-entry.ts to wire up per-request data via AsyncLocalStorage.\n *\n * When registered, getSsrData() reads from the provider (ALS store)\n * instead of module-level state, ensuring correct isolation for\n * concurrent requests with streaming Suspense.\n */\nexport function registerSsrDataProvider(provider: () => SsrData | undefined): void {\n  _setSsrDataProvider(provider);\n}\n\n// ─── Module-Level Fallback ────────────────────────────────────────\n//\n// Used by tests and as a fallback when no ALS provider is registered.\n\n/**\n * Set the SSR data for the current request via module-level state.\n *\n * In production, ssr-entry.ts uses ALS (runWithSsrData) instead.\n * This function is retained for tests and as a fallback.\n */\nexport function setSsrData(data: SsrData): void {\n  _setCurrentSsrData(data);\n}\n\n/**\n * Clear the SSR data after rendering completes.\n *\n * In production, ALS scope handles cleanup automatically.\n * This function is retained for tests and as a fallback.\n */\nexport function clearSsrData(): void {\n  _setCurrentSsrData(undefined);\n}\n\n/**\n * Read the current request's SSR data. Returns undefined when called\n * outside an SSR render (i.e. on the client after hydration).\n *\n * Prefers the ALS-backed provider when registered (server-side),\n * falling back to module-level state (tests, legacy).\n *\n * Used by client hooks' server snapshot functions.\n */\nexport function getSsrData(): SsrData | undefined {\n  if (ssrDataProvider) {\n    return ssrDataProvider();\n  }\n  return currentSsrData;\n}\n"],"mappings":";;AA2BA,IAAW,eAAsC;AAEjD,SAAgB,iBAAiB,QAAqC;AACpE,gBAAe;;;;;;AASjB,IAAW;;AAOX,IAAW;AAEX,SAAgB,mBAAmB,MAAiC;AAClE,kBAAiB;;;AAMnB,IAAW,gBAAmD,EAAE;AAEhE,SAAgB,kBAAkB,QAAiD;AACjF,iBAAgB;;;AASlB,IAAW,eAAe;AAC1B,IAAW,qBAAqB,IAAI,iBAAiB;AAErD,SAAgB,iBAAiB,QAAgB,QAA+B;AAC9E,gBAAe;AACf,sBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACyBvB,SAAgB,WAAW,MAAqB;AAC9C,oBAAmB,KAAK;;;;;;;;AAS1B,SAAgB,eAAqB;AACnC,oBAAmB,KAAA,EAAU;;;;;;;;;;;AAY/B,SAAgB,aAAkC;AAChD,KAAI,gBACF,QAAO,iBAAiB;AAE1B,QAAO"}

package/dist/_chunks/{stale-reload-BLUC_Pl_.js → stale-reload-C2plcNtG.js}

@@ -61,4 +61,4 @@ function triggerStaleReload() {
 //#endregion
 export { triggerStaleReload };
 
-//# sourceMappingURL=stale-reload-BLUC_Pl_.js.map
+//# sourceMappingURL=stale-reload-C2plcNtG.js.map

package/dist/_chunks/{stale-reload-BLUC_Pl_.js.map → stale-reload-C2plcNtG.js.map}

@@ -1 +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"}
+{"version":3,"file":"stale-reload-C2plcNtG.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/{handler-store-BVePM7hp.js → tracing-CCYbKn5n.js}

@@ -1,10 +1,61 @@
-import { o as traceAls } from "./als-registry-BJARkOcu.js";
+import { o as traceAls } from "./als-registry-HS0LGUl2.js";
 import { randomUUID } from "node:crypto";
+//#region src/cache/handler-store.ts
+var handler = null;
+/** Replace the active cache handler. Called by the framework at boot. */
+function setCacheHandler(h) {
+	handler = h;
+}
+/**
+* Get the active cache handler. Creates a default MemoryCacheHandler on
+* first access if none has been set via setCacheHandler().
+*/
+function getCacheHandler() {
+	if (!handler) handler = createDefaultHandler();
+	return handler;
+}
+function createDefaultHandler() {
+	const store = /* @__PURE__ */ new Map();
+	const maxEntries = 1e3;
+	return {
+		async get(key) {
+			const entry = store.get(key);
+			if (!entry) return null;
+			store.delete(key);
+			store.set(key, entry);
+			const stale = Date.now() > entry.expiresAt;
+			return {
+				value: entry.value,
+				stale
+			};
+		},
+		async set(key, value, opts) {
+			if (store.has(key)) store.delete(key);
+			while (store.size >= maxEntries) {
+				const oldest = store.keys().next().value;
+				if (oldest !== void 0) store.delete(oldest);
+				else break;
+			}
+			store.set(key, {
+				value,
+				expiresAt: Date.now() + opts.ttl * 1e3,
+				tags: opts.tags
+			});
+		},
+		async invalidate(opts) {
+			if (opts.key) store.delete(opts.key);
+			if (opts.tag) {
+				for (const [key, entry] of store) if (entry.tags.includes(opts.tag)) store.delete(key);
+			}
+		}
+	};
+}
+//#endregion
 //#region src/server/tracing.ts
 /**
 * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.
 *
-* traceId() is always available in server code (middleware, access, components, actions).
+* getTraceId() is always available in server code (middleware, access, components, actions).
 * Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,
 * or a crypto.randomUUID()-derived fallback otherwise.
 *
@@ -18,15 +69,15 @@ import { randomUUID } from "node:crypto";
 *
 * Throws if called outside a request context (no ALS store).
 */
-function traceId() {
+function getTraceId() {
 	const store = traceAls.getStore();
-	if (!store) throw new Error("[timber] traceId() called outside of a request context. It can only be used in middleware, access checks, server components, and server actions.");
+	if (!store) throw new Error("[timber] getTraceId() called outside of a request context. It can only be used in middleware, access checks, server components, and server actions.");
 	return store.traceId;
 }
 /**
 * Returns the current OTEL span ID if available, undefined otherwise.
 */
-function spanId() {
+function getSpanId() {
 	return traceAls.getStore()?.spanId;
 }
 /**
@@ -65,7 +116,7 @@ function updateSpanId(newSpanId) {
 }
 /**
 * Get the current trace store, or undefined if outside a request context.
-* Framework-internal — use traceId()/spanId() in user code.
+* Framework-internal — use getTraceId()/getSpanId() in user code.
 */
 function getTraceStore() {
 	return traceAls.getStore();
@@ -115,7 +166,7 @@ async function withSpan(name, attributes, fn) {
 	if (!tracer) return fn();
 	const api = await getOtelApi();
 	return tracer.startActiveSpan(name, { attributes }, async (span) => {
-		const prevSpanId = spanId();
+		const prevSpanId = getSpanId();
 		updateSpanId(span.spanContext().spanId);
 		try {
 			const result = await fn();
@@ -182,57 +233,6 @@ async function getOtelTraceId() {
 	};
 }
 //#endregion
-//#region src/cache/handler-store.ts
-var handler = null;
-/** Replace the active cache handler. Called by the framework at boot. */
-function setCacheHandler(h) {
-	handler = h;
-}
-/**
-* Get the active cache handler. Creates a default MemoryCacheHandler on
-* first access if none has been set via setCacheHandler().
-*/
-function getCacheHandler() {
-	if (!handler) handler = createDefaultHandler();
-	return handler;
-}
-function createDefaultHandler() {
-	const store = /* @__PURE__ */ new Map();
-	const maxSize = 1e3;
-	return {
-		async get(key) {
-			const entry = store.get(key);
-			if (!entry) return null;
-			store.delete(key);
-			store.set(key, entry);
-			const stale = Date.now() > entry.expiresAt;
-			return {
-				value: entry.value,
-				stale
-			};
-		},
-		async set(key, value, opts) {
-			if (store.has(key)) store.delete(key);
-			while (store.size >= maxSize) {
-				const oldest = store.keys().next().value;
-				if (oldest !== void 0) store.delete(oldest);
-				else break;
-			}
-			store.set(key, {
-				value,
-				expiresAt: Date.now() + opts.ttl * 1e3,
-				tags: opts.tags
-			});
-		},
-		async invalidate(opts) {
-			if (opts.key) store.delete(opts.key);
-			if (opts.tag) {
-				for (const [key, entry] of store) if (entry.tags.includes(opts.tag)) store.delete(key);
-			}
-		}
-	};
-}
-//#endregion
-export { generateTraceId as a, replaceTraceId as c, spanId as d, traceId as f, addSpanEventSync as i, runWithTraceId as l, setCacheHandler as n, getOtelTraceId as o, withSpan as p, addSpanEvent as r, getTraceStore as s, getCacheHandler as t, setSpanAttribute as u };
+export { getSpanId as a, replaceTraceId as c, withSpan as d, getCacheHandler as f, getOtelTraceId as i, runWithTraceId as l, addSpanEventSync as n, getTraceId as o, setCacheHandler as p, generateTraceId as r, getTraceStore as s, addSpanEvent as t, setSpanAttribute as u };
 
-//# sourceMappingURL=handler-store-BVePM7hp.js.map
+//# sourceMappingURL=tracing-CCYbKn5n.js.map

package/dist/_chunks/tracing-CCYbKn5n.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing-CCYbKn5n.js","names":[],"sources":["../../src/cache/handler-store.ts","../../src/server/tracing.ts"],"sourcesContent":["/**\n * Module-level cache handler singleton.\n *\n * Lazily initialized to MemoryCacheHandler on first access. The framework\n * replaces this at boot from timber.config.ts via setCacheHandler().\n *\n * This module avoids importing from ./index to prevent circular dependencies.\n */\n\n// Inline the interface to avoid circular import with index.ts\ninterface CacheHandlerLike {\n  get(key: string): Promise<{ value: unknown; stale: boolean } | null>;\n  set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;\n  invalidate(opts: { key?: string; tag?: string }): Promise<void>;\n}\n\nlet handler: CacheHandlerLike | null = null;\n\n/** Replace the active cache handler. Called by the framework at boot. */\nexport function setCacheHandler(h: CacheHandlerLike): void {\n  handler = h;\n}\n\n/**\n * Get the active cache handler. Creates a default MemoryCacheHandler on\n * first access if none has been set via setCacheHandler().\n */\nexport function getCacheHandler(): CacheHandlerLike {\n  if (!handler) {\n    // Inline a minimal LRU cache to avoid circular dep with index.ts.\n    // In production, the framework always calls setCacheHandler() at boot.\n    handler = createDefaultHandler();\n  }\n  return handler;\n}\n\nfunction createDefaultHandler(): CacheHandlerLike {\n  const store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();\n  const maxEntries = 1000;\n\n  return {\n    async get(key) {\n      const entry = store.get(key);\n      if (!entry) return null;\n      store.delete(key);\n      store.set(key, entry);\n      const stale = Date.now() > entry.expiresAt;\n      return { value: entry.value, stale };\n    },\n    async set(key, value, opts) {\n      if (store.has(key)) store.delete(key);\n      while (store.size >= maxEntries) {\n        const oldest = store.keys().next().value;\n        if (oldest !== undefined) store.delete(oldest);\n        else break;\n      }\n      store.set(key, { value, expiresAt: Date.now() + opts.ttl * 1000, tags: opts.tags });\n    },\n    async invalidate(opts) {\n      if (opts.key) store.delete(opts.key);\n      if (opts.tag) {\n        for (const [key, entry] of store) {\n          if (entry.tags.includes(opts.tag)) store.delete(key);\n        }\n      }\n    },\n  };\n}\n","/**\n * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.\n *\n * getTraceId() is always available in server code (middleware, access, components, actions).\n * Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,\n * or a crypto.randomUUID()-derived fallback otherwise.\n *\n * See design/17-logging.md §\"trace_id is Always Set\"\n */\n\nimport { randomUUID } from 'node:crypto';\nimport { traceAls, type TraceStore } from './als-registry.js';\n\n// Re-export the TraceStore type for public API consumers.\nexport type { TraceStore } from './als-registry.js';\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Returns the current request's trace ID — always a 32-char lowercase hex string.\n *\n * With OTEL: the real OTEL trace ID (matches Jaeger/Honeycomb/Datadog).\n * Without OTEL: crypto.randomUUID() with hyphens stripped.\n *\n * Throws if called outside a request context (no ALS store).\n */\nexport function getTraceId(): string {\n  const store = traceAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] getTraceId() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  return store.traceId;\n}\n\n/**\n * Returns the current OTEL span ID if available, undefined otherwise.\n */\nexport function getSpanId(): string | undefined {\n  return traceAls.getStore()?.spanId;\n}\n\n// ─── Framework-Internal Helpers ───────────────────────────────────────────\n\n/**\n * Generate a 32-char lowercase hex ID from crypto.randomUUID().\n * Same format as OTEL trace IDs — zero-friction upgrade path.\n */\nexport function generateTraceId(): string {\n  return randomUUID().replace(/-/g, '');\n}\n\n/**\n * Run a callback within a trace context. Used by the pipeline to establish\n * per-request ALS scope.\n */\nexport function runWithTraceId<T>(id: string, fn: () => T): T {\n  return traceAls.run({ traceId: id }, fn);\n}\n\n/**\n * Replace the trace ID in the current ALS store. Used when OTEL creates\n * a root span and we want to switch from the UUID fallback to the real\n * OTEL trace ID.\n */\nexport function replaceTraceId(newTraceId: string, newSpanId?: string): void {\n  const store = traceAls.getStore();\n  if (store) {\n    store.traceId = newTraceId;\n    store.spanId = newSpanId;\n  }\n}\n\n/**\n * Update the span ID in the current ALS store. Used when entering a new\n * OTEL span to keep log–trace correlation accurate.\n */\nexport function updateSpanId(newSpanId: string | undefined): void {\n  const store = traceAls.getStore();\n  if (store) {\n    store.spanId = newSpanId;\n  }\n}\n\n/**\n * Get the current trace store, or undefined if outside a request context.\n * Framework-internal — use getTraceId()/getSpanId() in user code.\n */\nexport function getTraceStore(): TraceStore | undefined {\n  return traceAls.getStore();\n}\n\n// ─── Dev-Mode OTEL Auto-Init ─────────────────────────────────────────────\n\n/**\n * Initialize a minimal OTEL SDK in dev mode so spans are recorded and\n * fed to the DevSpanProcessor for dev log output.\n *\n * If the user already configured an OTEL SDK in register(), we add\n * our DevSpanProcessor alongside theirs. If no SDK is configured,\n * we create a BasicTracerProvider with our processor.\n *\n * Only called in dev mode — zero overhead in production.\n */\nexport async function initDevTracing(\n  config: import('./dev-logger.js').DevLoggerConfig\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  let DevSpanProcessor: typeof import('./dev-span-processor.js').DevSpanProcessor;\n  let BasicTracerProvider: typeof import('@opentelemetry/sdk-trace-base').BasicTracerProvider;\n  let AsyncLocalStorageContextManager: typeof import('@opentelemetry/context-async-hooks').AsyncLocalStorageContextManager;\n\n  try {\n    ({ DevSpanProcessor } = await import('./dev-span-processor.js'));\n    ({ BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base'));\n    ({ AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks'));\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n    console.warn(`[timber] Dev tracing disabled — failed to load OTEL packages:\\n  ${msg}`);\n    return;\n  }\n\n  const processor = new DevSpanProcessor(config);\n\n  // Register a context manager so OTEL can propagate the active span\n  // across async boundaries. Without this, startActiveSpan can't make\n  // spans \"active\" — child spans get random trace IDs and getActiveSpan()\n  // returns undefined.\n  const contextManager = new AsyncLocalStorageContextManager();\n  contextManager.enable();\n  api.context.setGlobalContextManager(contextManager);\n\n  // Create a minimal TracerProvider with our DevSpanProcessor.\n  // If the user also configures an SDK in register(), their provider\n  // will coexist — the global provider set last wins for new tracers,\n  // but our processor captures all spans from the timber.js tracer.\n  const provider = new BasicTracerProvider({\n    spanProcessors: [processor],\n  });\n  api.trace.setGlobalTracerProvider(provider);\n\n  // Reset cached tracer so next getTracer() picks up the new provider\n  _tracer = undefined;\n}\n\n// ─── OTEL Span Helpers ───────────────────────────────────────────────────\n\n/**\n * Attempt to get the @opentelemetry/api tracer. Returns undefined if the\n * package is not installed or no SDK is registered.\n *\n * timber.js depends on @opentelemetry/api as the vendor-neutral interface.\n * The API is a no-op by default — spans are only emitted when the developer\n * initializes an SDK in register().\n */\nlet _otelApi: typeof import('@opentelemetry/api') | null | undefined;\n\nasync function getOtelApi(): Promise<typeof import('@opentelemetry/api') | null> {\n  if (_otelApi === undefined) {\n    try {\n      _otelApi = await import('@opentelemetry/api');\n    } catch {\n      _otelApi = null;\n    }\n  }\n  return _otelApi;\n}\n\n/** OTEL tracer instance, lazily created. */\nlet _tracer: import('@opentelemetry/api').Tracer | null | undefined;\n\n/**\n * Get the timber.js OTEL tracer. Returns null if @opentelemetry/api is not available.\n */\nexport async function getTracer(): Promise<import('@opentelemetry/api').Tracer | null> {\n  if (_tracer === undefined) {\n    const api = await getOtelApi();\n    if (api) {\n      _tracer = api.trace.getTracer('timber.js');\n    } else {\n      _tracer = null;\n    }\n  }\n  return _tracer;\n}\n\n/**\n * Run a function within an OTEL span. If OTEL is not available, runs the function\n * directly without any span overhead.\n *\n * Automatically:\n * - Creates the span as a child of the current context\n * - Updates the ALS span ID for log–trace correlation\n * - Ends the span when the function completes\n * - Records exceptions on error\n */\nexport async function withSpan<T>(\n  name: string,\n  attributes: Record<string, string | number | boolean>,\n  fn: () => T | Promise<T>\n): Promise<T> {\n  const tracer = await getTracer();\n  if (!tracer) {\n    return fn();\n  }\n\n  const api = (await getOtelApi())!;\n  return tracer.startActiveSpan(name, { attributes }, async (span) => {\n    const prevSpanId = getSpanId();\n    updateSpanId(span.spanContext().spanId);\n    try {\n      const result = await fn();\n      span.setStatus({ code: api.SpanStatusCode.OK });\n      return result;\n    } catch (error) {\n      span.setStatus({ code: api.SpanStatusCode.ERROR });\n      if (error instanceof Error) {\n        span.recordException(error);\n      }\n      throw error;\n    } finally {\n      span.end();\n      updateSpanId(prevSpanId);\n    }\n  });\n}\n\n/**\n * Set an attribute on the current active span (if any).\n * Used for setting span attributes after span creation (e.g. timber.result on access spans).\n */\nexport async function setSpanAttribute(\n  key: string,\n  value: string | number | boolean\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.setAttribute(key, value);\n  }\n}\n\n/**\n * Add a span event to the current active span (if any).\n * Used for timber.cache HIT/MISS events — recorded as span events, not child spans.\n */\nexport async function addSpanEvent(\n  name: string,\n  attributes?: Record<string, string | number | boolean>\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.addEvent(name, attributes);\n  }\n}\n\n/**\n * Fire-and-forget span event — no await, no microtask overhead.\n *\n * Used on the cache hot path where awaiting addSpanEvent creates an\n * unnecessary microtask per cache operation. If OTEL is not loaded yet,\n * the event is silently dropped (acceptable for diagnostics).\n *\n * See TIM-370 for perf motivation.\n */\nexport function addSpanEventSync(\n  name: string,\n  attributes?: Record<string, string | number | boolean>\n): void {\n  // Fast path: if OTEL API hasn't been loaded yet, skip entirely.\n  // _otelApi is undefined (not yet loaded), null (failed to load), or the module.\n  if (!_otelApi) return;\n\n  const activeSpan = _otelApi.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.addEvent(name, attributes);\n  }\n}\n\n/**\n * Try to extract the OTEL trace ID from the current active span context.\n * Returns undefined if OTEL is not active or no span exists.\n */\nexport async function getOtelTraceId(): Promise<{ traceId: string; spanId: string } | undefined> {\n  const api = await getOtelApi();\n  if (!api) return undefined;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (!activeSpan) return undefined;\n\n  const ctx = activeSpan.spanContext();\n  // OTEL uses \"0000000000000000\" as invalid trace IDs\n  if (!ctx.traceId || ctx.traceId === '00000000000000000000000000000000') {\n    return undefined;\n  }\n\n  return { traceId: ctx.traceId, spanId: ctx.spanId };\n}\n"],"mappings":"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"}