@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.99

package/dist/cache/index.js

@@ -1,4 +1,6 @@
-import { f as getCacheHandler, n as addSpanEventSync, p as setCacheHandler } from "../_chunks/tracing-CCYbKn5n.js";
+import { n as addSpanEventSync } from "../_chunks/tracing-C8V-YGsP.js";
+import { d as logSwrRefetchFailed } from "../_chunks/logger-0m8MsKdc.js";
+import { n as setCacheHandler, t as getCacheHandler } from "../_chunks/handler-store-B-lqaGyh.js";
 //#region src/cache/sizeof.ts
 /**
 * Lightweight byte-size estimation for cache entries.
@@ -250,7 +252,12 @@ function createCache(fn, opts, handler) {
 						ttl: opts.ttl,
 						tags
 					});
-				} catch {}
+				} catch (err) {
+					logSwrRefetchFailed({
+						cacheKey: key,
+						error: err
+					});
+				}
 			}).catch(() => {});
 			return cached.value;
 		}

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/cache/sizeof.ts","../../src/cache/redis-handler.ts","../../src/cache/stable-stringify.ts","../../src/cache/singleflight.ts","../../src/cache/fast-hash.ts","../../src/cache/timber-cache.ts","../../src/cache/cache-api.ts","../../src/cache/index.ts"],"sourcesContent":["/**\n * Lightweight byte-size estimation for cache entries.\n *\n * Estimates the in-memory byte cost of a JavaScript value using\n * JSON.stringify().length * 2 (UTF-16 char width). This is a rough\n * approximation — it doesn't account for V8 object overhead, Map\n * metadata, or non-serializable values — but it's fast and good\n * enough for cache budget enforcement.\n *\n * Values that fail JSON serialization (circular references, BigInt,\n * etc.) return 0, allowing the entry to be cached without counting\n * toward the byte budget. This is a conservative choice: it's better\n * to cache and undercount than to reject the entry.\n */\n\n/**\n * Estimate the byte size of a value.\n *\n * Uses `JSON.stringify(value).length * 2` to approximate UTF-16\n * in-memory size. Returns 0 if the value is not serializable.\n */\nexport function estimateByteSize(value: unknown): number {\n  try {\n    const json = JSON.stringify(value);\n    if (json === undefined) return 0;\n    // Each JS string character is 2 bytes (UTF-16)\n    return json.length * 2;\n  } catch {\n    return 0;\n  }\n}\n","import type { CacheHandler } from './index';\n\n/**\n * Minimal Redis client interface — compatible with ioredis, node-redis, and\n * Cloudflare Workers Redis bindings. We depend on the interface, not the\n * implementation, so users bring their own Redis client.\n */\nexport interface RedisClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;\n  del(key: string | string[]): Promise<number>;\n  sadd(key: string, ...members: string[]): Promise<number>;\n  smembers(key: string): Promise<string[]>;\n}\n\nconst KEY_PREFIX = 'timber:cache:';\nconst TAG_PREFIX = 'timber:tag:';\n\n/**\n * Redis-backed CacheHandler for distributed caching.\n *\n * All instances sharing the same Redis see each other's cache entries and\n * invalidations. Tag-based invalidation uses Redis Sets to track which keys\n * belong to which tags.\n *\n * Bring your own Redis client — any client implementing the RedisClient\n * interface works (ioredis, node-redis, @upstash/redis, etc.).\n */\nexport class RedisCacheHandler implements CacheHandler {\n  private client: RedisClient;\n  private prefix: string;\n\n  constructor(client: RedisClient, opts?: { prefix?: string }) {\n    this.client = client;\n    this.prefix = opts?.prefix ?? '';\n  }\n\n  private cacheKey(key: string): string {\n    return `${this.prefix}${KEY_PREFIX}${key}`;\n  }\n\n  private tagKey(tag: string): string {\n    return `${this.prefix}${TAG_PREFIX}${tag}`;\n  }\n\n  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {\n    const raw = await this.client.get(this.cacheKey(key));\n    if (raw === null) return null;\n\n    const entry = JSON.parse(raw) as { value: unknown; expiresAt: number };\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {\n    const ck = this.cacheKey(key);\n    const expiresAt = Date.now() + opts.ttl * 1000;\n    const payload = JSON.stringify({ value, expiresAt });\n\n    // Redis TTL with generous margin beyond the logical TTL to allow SWR reads\n    // on stale entries. The logical staleness is determined by expiresAt.\n    // We use 2x TTL + 60s as the Redis expiry so stale entries remain\n    // available for SWR background refetches.\n    const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);\n    await this.client.set(ck, payload, 'EX', redisTtlSeconds);\n\n    // Track key membership in each tag set\n    for (const tag of opts.tags) {\n      await this.client.sadd(this.tagKey(tag), key);\n    }\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n    if (opts.key) {\n      await this.client.del(this.cacheKey(opts.key));\n    }\n\n    if (opts.tag) {\n      const tk = this.tagKey(opts.tag);\n      const keys = await this.client.smembers(tk);\n\n      if (keys.length > 0) {\n        const cacheKeys = keys.map((k) => this.cacheKey(k));\n        await this.client.del(cacheKeys);\n      }\n\n      // Clean up the tag set itself\n      await this.client.del(tk);\n    }\n  }\n}\n","/**\n * Deterministic JSON serialization with sorted object keys.\n * Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }\n * produce the same string.\n */\nexport function stableStringify(value: unknown): string {\n  if (value === null || value === undefined) return JSON.stringify(value);\n  if (typeof value !== 'object') return JSON.stringify(value);\n  if (Array.isArray(value)) {\n    return '[' + value.map((item) => stableStringify(item)).join(',') + ']';\n  }\n\n  const obj = value as Record<string, unknown>;\n  const keys = Object.keys(obj).sort();\n  const pairs: string[] = [];\n  for (const key of keys) {\n    if (obj[key] === undefined) continue;\n    pairs.push(JSON.stringify(key) + ':' + stableStringify(obj[key]));\n  }\n  return '{' + pairs.join(',') + '}';\n}\n","/**\n * Singleflight coalesces concurrent calls with the same key into a single\n * execution. All callers receive the same result (or error).\n *\n * Per-process, in-memory. Each process coalesces independently.\n *\n * An optional `timeoutMs` prevents hung `fn()` calls from permanently\n * blocking all future callers for that key. When set, `fn()` is raced\n * against a timeout — if the timeout fires first, the promise rejects\n * with `SingleflightTimeoutError`, `finally` cleans up the key, and\n * subsequent callers can retry. See TIM-518.\n */\n\nexport interface SingleflightOptions {\n  /** Maximum time (ms) a coalesced call may run before being rejected. */\n  timeoutMs?: number;\n}\n\nexport interface Singleflight {\n  do<T>(key: string, fn: () => Promise<T>): Promise<T>;\n}\n\n/**\n * Error thrown when a singleflight call exceeds `timeoutMs`.\n * Exported so callers can distinguish timeout from other errors.\n */\nexport class SingleflightTimeoutError extends Error {\n  constructor(key: string, timeoutMs: number) {\n    super(`Singleflight timeout: key \"${key}\" exceeded ${timeoutMs}ms`);\n    this.name = 'SingleflightTimeoutError';\n  }\n}\n\nexport function createSingleflight(opts?: SingleflightOptions): Singleflight {\n  const inflight = new Map<string, Promise<unknown>>();\n  const timeoutMs = opts?.timeoutMs;\n\n  return {\n    do<T>(key: string, fn: () => Promise<T>): Promise<T> {\n      const existing = inflight.get(key);\n      if (existing) return existing as Promise<T>;\n\n      let promise: Promise<T>;\n\n      if (timeoutMs != null && timeoutMs > 0) {\n        // Race fn() against a timeout to prevent hung calls from\n        // permanently blocking the key. See TIM-518.\n        promise = new Promise<T>((resolve, reject) => {\n          const timer = setTimeout(\n            () => reject(new SingleflightTimeoutError(key, timeoutMs)),\n            timeoutMs\n          );\n          // Wrap in try/catch so a synchronous throw from fn()\n          // (e.g. argument validation) still clears the timer.\n          // Without this, the timer leaks until expiry.\n          try {\n            fn().then(\n              (value) => {\n                clearTimeout(timer);\n                resolve(value);\n              },\n              (err) => {\n                clearTimeout(timer);\n                reject(err);\n              }\n            );\n          } catch (err) {\n            clearTimeout(timer);\n            reject(err);\n          }\n        });\n      } else {\n        promise = fn();\n      }\n\n      const tracked = promise.finally(() => {\n        inflight.delete(key);\n      });\n\n      inflight.set(key, tracked);\n      return tracked as Promise<T>;\n    },\n  };\n}\n","/**\n * Fast non-cryptographic hash for cache keys.\n *\n * FNV-1a 64-bit produces a well-distributed hash with a collision\n * probability of ~1 in 5 billion at 77k keys (birthday paradox).\n * Not suitable for security, but ideal for cache key generation\n * where we need speed over crypto strength.\n *\n * Uses BigInt for 64-bit arithmetic — supported in all modern runtimes\n * including Cloudflare Workers. No node:crypto dependency.\n *\n * See TIM-370.\n */\n\n// FNV-1a constants for 64-bit hash\nconst FNV_OFFSET_BASIS = 0xcbf29ce484222325n;\nconst FNV_PRIME = 0x100000001b3n;\nconst MASK_64 = 0xffffffffffffffffn;\n\n/**\n * Compute a 64-bit FNV-1a hash of a string, returned as a 16-char hex string.\n *\n * 64 bits gives ~5 billion keys before a 50% collision probability\n * (birthday paradox), making accidental collisions effectively impossible\n * for cache key use cases.\n */\nexport function fnv1aHash(input: string): string {\n  let hash = FNV_OFFSET_BASIS;\n  for (let i = 0; i < input.length; i++) {\n    hash ^= BigInt(input.charCodeAt(i));\n    hash = (hash * FNV_PRIME) & MASK_64;\n  }\n  return hash.toString(16).padStart(16, '0');\n}\n","import type { CacheHandler, CacheOptions } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\nimport { addSpanEventSync } from '../server/tracing.js';\nimport { fnv1aHash } from './fast-hash.js';\n\nconst defaultSingleflight = createSingleflight();\n\n/**\n * Generate a cache key from function identity and serialized args.\n *\n * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't\n * need collision resistance — they need speed. The fnId prefix provides\n * namespace isolation; the hash covers the args.\n *\n * See TIM-370 for perf motivation.\n */\nfunction defaultKeyGenerator(fnId: string, args: unknown[]): string {\n  const raw = fnId + ':' + stableStringify(args);\n  return fnId + ':' + fnv1aHash(raw);\n}\n\n/**\n * Resolve tags from the options — supports static array or function form.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction resolveTags<Fn extends (...args: any[]) => any>(\n  opts: CacheOptions<Fn>,\n  args: Parameters<Fn>\n): string[] {\n  if (!opts.tags) return [];\n  if (Array.isArray(opts.tags)) return opts.tags;\n  return opts.tags(...args);\n}\n\n// Counter for generating unique function IDs when no explicit key is provided.\nlet fnIdCounter = 0;\n\n/**\n * Creates a cached wrapper around an async function.\n *\n * - SHA-256 default keys with normalized JSON args\n * - Singleflight: concurrent misses → single execution\n * - SWR: serve stale immediately, background refetch\n * - Tags as string[] or function of args\n * - No ALS dependency\n *\n * Cache hits/misses are recorded as OTEL span events on the enclosing\n * span (not child spans). The DevSpanProcessor reads these for dev log output.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function createCache<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: CacheOptions<Fn>,\n  handler: CacheHandler\n): Fn {\n  const fnId = `timber-cache:${fnIdCounter++}`;\n  const sf = opts.timeoutMs\n    ? createSingleflight({ timeoutMs: opts.timeoutMs })\n    : defaultSingleflight;\n\n  // Cast to Fn to preserve the original function's generic call signature.\n  // Without this, generic type parameters (e.g. <T> in apiFetch<T>) are\n  // erased and callers lose type safety on the return type.\n  return (async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);\n\n    const cacheStart = performance.now();\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      // Record as OTEL span event on enclosing span (not a child span).\n      // Fire-and-forget — no microtask overhead on the cache hot path.\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    if (cached && cached.stale && opts.staleWhileRevalidate) {\n      // Record stale cache hit as OTEL span event (fire-and-forget).\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n        stale: true,\n      });\n      // Serve stale immediately, trigger background refetch\n      sf.do(`swr:${key}`, async () => {\n        try {\n          const fresh = await fn(...args);\n          const tags = resolveTags(opts, args);\n          await handler.set(key, fresh, { ttl: opts.ttl, tags });\n        } catch {\n          // Failed refetch — stale entry continues to be served.\n          // Error is swallowed per design doc: \"Error is logged.\"\n        }\n      }).catch(() => {\n        // Singleflight promise rejection handled — stale continues.\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss (or stale without SWR) — execute with singleflight\n    const result = await sf.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n\n    // Record cache miss as OTEL span event (fire-and-forget).\n    addSpanEventSync('timber.cache.miss', {\n      key,\n      duration_ms: Math.round(performance.now() - cacheStart),\n    });\n\n    return result as Awaited<ReturnType<Fn>>;\n  }) as unknown as Fn;\n}\n\n/**\n * Invalidate cache entries by tag or key.\n */\ncreateCache.invalidate = async function invalidate(\n  handler: CacheHandler,\n  opts: { key?: string; tag?: string }\n): Promise<void> {\n  await handler.invalidate(opts);\n};\n","import type { CacheOptions } from './index';\nimport { createCache } from './timber-cache';\nimport { getCacheHandler } from './handler-store';\n\n/**\n * Public caching API: `cache(fn, opts)`.\n *\n * Wraps an async function with cross-request caching. Uses the configured\n * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).\n *\n * ```ts\n * import { cache } from '@timber-js/app/cache';\n *\n * const getUser = cache(\n *   async (id: string) => db.users.findUnique({ where: { id } }),\n *   { ttl: 60, tags: (id) => [`user:${id}`] }\n * );\n * ```\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function cache<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: CacheOptions<Fn>\n): Fn {\n  return createCache(fn, opts, getCacheHandler());\n}\n\n/**\n * Invalidate cache entries by tag or key.\n *\n * ```ts\n * cache.invalidate({ tag: 'products' });\n * cache.invalidate({ key: 'user:abc' });\n * ```\n */\ncache.invalidate = async function invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n  await getCacheHandler().invalidate(opts);\n};\n","// @timber-js/app/cache — Caching primitives\n\nimport { estimateByteSize } from './sizeof.js';\n\nexport interface CacheHandler {\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\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface CacheOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  key?: (...args: Parameters<Fn>) => string;\n  staleWhileRevalidate?: boolean;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n  /** Timeout (ms) for singleflight-coalesced calls. Prevents hung fn() from\n   *  permanently blocking all future callers for the same cache key. See TIM-518. */\n  timeoutMs?: number;\n}\n\nexport interface MemoryCacheHandlerOptions {\n  /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */\n  maxEntries?: number;\n  /**\n   * @deprecated Use `maxEntries` instead. Will be removed in a future release.\n   * Alias for `maxEntries` — maximum number of entries (not bytes).\n   */\n  maxSize?: number;\n  /** Maximum total byte budget for all cached values. Oldest entries are evicted when exceeded. Default: no limit. */\n  maxBytes?: number;\n  /** Maximum byte size for a single cache entry. Entries exceeding this are silently dropped. Default: no limit. */\n  maxEntryBytes?: number;\n}\n\nexport class MemoryCacheHandler implements CacheHandler {\n  private store = new Map<\n    string,\n    { value: unknown; expiresAt: number; tags: string[]; byteSize: number }\n  >();\n  private maxEntries: number;\n  private maxBytes: number | undefined;\n  private maxEntryBytes: number | undefined;\n  private currentBytes = 0;\n\n  constructor(opts?: MemoryCacheHandlerOptions) {\n    // maxEntries takes precedence over deprecated maxSize\n    this.maxEntries = opts?.maxEntries ?? opts?.maxSize ?? 1000;\n    this.maxBytes = opts?.maxBytes;\n    this.maxEntryBytes = opts?.maxEntryBytes;\n  }\n\n  async get(key: string) {\n    const entry = this.store.get(key);\n    if (!entry) return null;\n\n    // Move to end of Map (most recently used) for LRU ordering\n    this.store.delete(key);\n    this.store.set(key, entry);\n\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {\n    const byteSize = estimateByteSize(value);\n\n    // Reject entries exceeding per-entry byte limit\n    if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) {\n      return;\n    }\n\n    // If key already exists, delete first to refresh insertion order and reclaim bytes\n    if (this.store.has(key)) {\n      const existing = this.store.get(key)!;\n      this.currentBytes -= existing.byteSize;\n      this.store.delete(key);\n    }\n\n    // Evict oldest entries (front of Map) if at entry count capacity\n    while (this.store.size >= this.maxEntries) {\n      this.evictOldest();\n    }\n\n    // Evict oldest entries if byte budget would be exceeded\n    if (this.maxBytes !== undefined) {\n      while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) {\n        this.evictOldest();\n      }\n      // If the single entry exceeds the total byte budget, don't store it\n      if (this.currentBytes + byteSize > this.maxBytes) {\n        return;\n      }\n    }\n\n    this.store.set(key, {\n      value,\n      expiresAt: Date.now() + opts.ttl * 1000,\n      tags: opts.tags,\n      byteSize,\n    });\n    this.currentBytes += byteSize;\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }) {\n    if (opts.key) {\n      const entry = this.store.get(opts.key);\n      if (entry) {\n        this.currentBytes -= entry.byteSize;\n        this.store.delete(opts.key);\n      }\n    }\n    if (opts.tag) {\n      for (const [key, entry] of this.store) {\n        if (entry.tags.includes(opts.tag)) {\n          this.currentBytes -= entry.byteSize;\n          this.store.delete(key);\n        }\n      }\n    }\n  }\n\n  /** Number of entries currently in the cache. */\n  get size(): number {\n    return this.store.size;\n  }\n\n  /** Estimated total byte size of all cached values. */\n  get bytes(): number {\n    return this.currentBytes;\n  }\n\n  /** Evict the oldest entry (front of Map). */\n  private evictOldest(): void {\n    const oldest = this.store.keys().next().value;\n    if (oldest !== undefined) {\n      const entry = this.store.get(oldest)!;\n      this.currentBytes -= entry.byteSize;\n      this.store.delete(oldest);\n    }\n  }\n}\n\nexport { RedisCacheHandler } from './redis-handler';\nexport type { RedisClient } from './redis-handler';\nexport { cache } from './cache-api';\nexport { setCacheHandler, getCacheHandler } from './handler-store';\n// NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.\n// Future feature pending design doc. See design/06-caching.md.\nexport { estimateByteSize } from './sizeof';\n// stableStringify, createSingleflight, and SingleflightTimeoutError are\n// internal utilities used by the cache implementation. They are not\n// re-exported here — import directly from the source files if needed\n// within the package. See TIM-720.\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/cache/sizeof.ts","../../src/cache/redis-handler.ts","../../src/cache/stable-stringify.ts","../../src/cache/singleflight.ts","../../src/cache/fast-hash.ts","../../src/cache/timber-cache.ts","../../src/cache/cache-api.ts","../../src/cache/index.ts"],"sourcesContent":["/**\n * Lightweight byte-size estimation for cache entries.\n *\n * Estimates the in-memory byte cost of a JavaScript value using\n * JSON.stringify().length * 2 (UTF-16 char width). This is a rough\n * approximation — it doesn't account for V8 object overhead, Map\n * metadata, or non-serializable values — but it's fast and good\n * enough for cache budget enforcement.\n *\n * Values that fail JSON serialization (circular references, BigInt,\n * etc.) return 0, allowing the entry to be cached without counting\n * toward the byte budget. This is a conservative choice: it's better\n * to cache and undercount than to reject the entry.\n */\n\n/**\n * Estimate the byte size of a value.\n *\n * Uses `JSON.stringify(value).length * 2` to approximate UTF-16\n * in-memory size. Returns 0 if the value is not serializable.\n */\nexport function estimateByteSize(value: unknown): number {\n  try {\n    const json = JSON.stringify(value);\n    if (json === undefined) return 0;\n    // Each JS string character is 2 bytes (UTF-16)\n    return json.length * 2;\n  } catch {\n    return 0;\n  }\n}\n","import type { CacheHandler } from './index';\n\n/**\n * Minimal Redis client interface — compatible with ioredis, node-redis, and\n * Cloudflare Workers Redis bindings. We depend on the interface, not the\n * implementation, so users bring their own Redis client.\n */\nexport interface RedisClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;\n  del(key: string | string[]): Promise<number>;\n  sadd(key: string, ...members: string[]): Promise<number>;\n  smembers(key: string): Promise<string[]>;\n}\n\nconst KEY_PREFIX = 'timber:cache:';\nconst TAG_PREFIX = 'timber:tag:';\n\n/**\n * Redis-backed CacheHandler for distributed caching.\n *\n * All instances sharing the same Redis see each other's cache entries and\n * invalidations. Tag-based invalidation uses Redis Sets to track which keys\n * belong to which tags.\n *\n * Bring your own Redis client — any client implementing the RedisClient\n * interface works (ioredis, node-redis, @upstash/redis, etc.).\n */\nexport class RedisCacheHandler implements CacheHandler {\n  private client: RedisClient;\n  private prefix: string;\n\n  constructor(client: RedisClient, opts?: { prefix?: string }) {\n    this.client = client;\n    this.prefix = opts?.prefix ?? '';\n  }\n\n  private cacheKey(key: string): string {\n    return `${this.prefix}${KEY_PREFIX}${key}`;\n  }\n\n  private tagKey(tag: string): string {\n    return `${this.prefix}${TAG_PREFIX}${tag}`;\n  }\n\n  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {\n    const raw = await this.client.get(this.cacheKey(key));\n    if (raw === null) return null;\n\n    const entry = JSON.parse(raw) as { value: unknown; expiresAt: number };\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {\n    const ck = this.cacheKey(key);\n    const expiresAt = Date.now() + opts.ttl * 1000;\n    const payload = JSON.stringify({ value, expiresAt });\n\n    // Redis TTL with generous margin beyond the logical TTL to allow SWR reads\n    // on stale entries. The logical staleness is determined by expiresAt.\n    // We use 2x TTL + 60s as the Redis expiry so stale entries remain\n    // available for SWR background refetches.\n    const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);\n    await this.client.set(ck, payload, 'EX', redisTtlSeconds);\n\n    // Track key membership in each tag set\n    for (const tag of opts.tags) {\n      await this.client.sadd(this.tagKey(tag), key);\n    }\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n    if (opts.key) {\n      await this.client.del(this.cacheKey(opts.key));\n    }\n\n    if (opts.tag) {\n      const tk = this.tagKey(opts.tag);\n      const keys = await this.client.smembers(tk);\n\n      if (keys.length > 0) {\n        const cacheKeys = keys.map((k) => this.cacheKey(k));\n        await this.client.del(cacheKeys);\n      }\n\n      // Clean up the tag set itself\n      await this.client.del(tk);\n    }\n  }\n}\n","/**\n * Deterministic JSON serialization with sorted object keys.\n * Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }\n * produce the same string.\n */\nexport function stableStringify(value: unknown): string {\n  if (value === null || value === undefined) return JSON.stringify(value);\n  if (typeof value !== 'object') return JSON.stringify(value);\n  if (Array.isArray(value)) {\n    return '[' + value.map((item) => stableStringify(item)).join(',') + ']';\n  }\n\n  const obj = value as Record<string, unknown>;\n  const keys = Object.keys(obj).sort();\n  const pairs: string[] = [];\n  for (const key of keys) {\n    if (obj[key] === undefined) continue;\n    pairs.push(JSON.stringify(key) + ':' + stableStringify(obj[key]));\n  }\n  return '{' + pairs.join(',') + '}';\n}\n","/**\n * Singleflight coalesces concurrent calls with the same key into a single\n * execution. All callers receive the same result (or error).\n *\n * Per-process, in-memory. Each process coalesces independently.\n *\n * An optional `timeoutMs` prevents hung `fn()` calls from permanently\n * blocking all future callers for that key. When set, `fn()` is raced\n * against a timeout — if the timeout fires first, the promise rejects\n * with `SingleflightTimeoutError`, `finally` cleans up the key, and\n * subsequent callers can retry. See TIM-518.\n */\n\nexport interface SingleflightOptions {\n  /** Maximum time (ms) a coalesced call may run before being rejected. */\n  timeoutMs?: number;\n}\n\nexport interface Singleflight {\n  do<T>(key: string, fn: () => Promise<T>): Promise<T>;\n}\n\n/**\n * Error thrown when a singleflight call exceeds `timeoutMs`.\n * Exported so callers can distinguish timeout from other errors.\n */\nexport class SingleflightTimeoutError extends Error {\n  constructor(key: string, timeoutMs: number) {\n    super(`Singleflight timeout: key \"${key}\" exceeded ${timeoutMs}ms`);\n    this.name = 'SingleflightTimeoutError';\n  }\n}\n\nexport function createSingleflight(opts?: SingleflightOptions): Singleflight {\n  const inflight = new Map<string, Promise<unknown>>();\n  const timeoutMs = opts?.timeoutMs;\n\n  return {\n    do<T>(key: string, fn: () => Promise<T>): Promise<T> {\n      const existing = inflight.get(key);\n      if (existing) return existing as Promise<T>;\n\n      let promise: Promise<T>;\n\n      if (timeoutMs != null && timeoutMs > 0) {\n        // Race fn() against a timeout to prevent hung calls from\n        // permanently blocking the key. See TIM-518.\n        promise = new Promise<T>((resolve, reject) => {\n          const timer = setTimeout(\n            () => reject(new SingleflightTimeoutError(key, timeoutMs)),\n            timeoutMs\n          );\n          // Wrap in try/catch so a synchronous throw from fn()\n          // (e.g. argument validation) still clears the timer.\n          // Without this, the timer leaks until expiry.\n          try {\n            fn().then(\n              (value) => {\n                clearTimeout(timer);\n                resolve(value);\n              },\n              (err) => {\n                clearTimeout(timer);\n                reject(err);\n              }\n            );\n          } catch (err) {\n            clearTimeout(timer);\n            reject(err);\n          }\n        });\n      } else {\n        promise = fn();\n      }\n\n      const tracked = promise.finally(() => {\n        inflight.delete(key);\n      });\n\n      inflight.set(key, tracked);\n      return tracked as Promise<T>;\n    },\n  };\n}\n","/**\n * Fast non-cryptographic hash for cache keys.\n *\n * FNV-1a 64-bit produces a well-distributed hash with a collision\n * probability of ~1 in 5 billion at 77k keys (birthday paradox).\n * Not suitable for security, but ideal for cache key generation\n * where we need speed over crypto strength.\n *\n * Uses BigInt for 64-bit arithmetic — supported in all modern runtimes\n * including Cloudflare Workers. No node:crypto dependency.\n *\n * See TIM-370.\n */\n\n// FNV-1a constants for 64-bit hash\nconst FNV_OFFSET_BASIS = 0xcbf29ce484222325n;\nconst FNV_PRIME = 0x100000001b3n;\nconst MASK_64 = 0xffffffffffffffffn;\n\n/**\n * Compute a 64-bit FNV-1a hash of a string, returned as a 16-char hex string.\n *\n * 64 bits gives ~5 billion keys before a 50% collision probability\n * (birthday paradox), making accidental collisions effectively impossible\n * for cache key use cases.\n */\nexport function fnv1aHash(input: string): string {\n  let hash = FNV_OFFSET_BASIS;\n  for (let i = 0; i < input.length; i++) {\n    hash ^= BigInt(input.charCodeAt(i));\n    hash = (hash * FNV_PRIME) & MASK_64;\n  }\n  return hash.toString(16).padStart(16, '0');\n}\n","import type { CacheHandler, CacheOptions } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\nimport { addSpanEventSync } from '../server/tracing.js';\nimport { logSwrRefetchFailed } from '../server/logger.js';\nimport { fnv1aHash } from './fast-hash.js';\n\nconst defaultSingleflight = createSingleflight();\n\n/**\n * Generate a cache key from function identity and serialized args.\n *\n * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't\n * need collision resistance — they need speed. The fnId prefix provides\n * namespace isolation; the hash covers the args.\n *\n * See TIM-370 for perf motivation.\n */\nfunction defaultKeyGenerator(fnId: string, args: unknown[]): string {\n  const raw = fnId + ':' + stableStringify(args);\n  return fnId + ':' + fnv1aHash(raw);\n}\n\n/**\n * Resolve tags from the options — supports static array or function form.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction resolveTags<Fn extends (...args: any[]) => any>(\n  opts: CacheOptions<Fn>,\n  args: Parameters<Fn>\n): string[] {\n  if (!opts.tags) return [];\n  if (Array.isArray(opts.tags)) return opts.tags;\n  return opts.tags(...args);\n}\n\n// Counter for generating unique function IDs when no explicit key is provided.\nlet fnIdCounter = 0;\n\n/**\n * Creates a cached wrapper around an async function.\n *\n * - SHA-256 default keys with normalized JSON args\n * - Singleflight: concurrent misses → single execution\n * - SWR: serve stale immediately, background refetch\n * - Tags as string[] or function of args\n * - No ALS dependency\n *\n * Cache hits/misses are recorded as OTEL span events on the enclosing\n * span (not child spans). The DevSpanProcessor reads these for dev log output.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function createCache<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: CacheOptions<Fn>,\n  handler: CacheHandler\n): Fn {\n  const fnId = `timber-cache:${fnIdCounter++}`;\n  const sf = opts.timeoutMs\n    ? createSingleflight({ timeoutMs: opts.timeoutMs })\n    : defaultSingleflight;\n\n  // Cast to Fn to preserve the original function's generic call signature.\n  // Without this, generic type parameters (e.g. <T> in apiFetch<T>) are\n  // erased and callers lose type safety on the return type.\n  return (async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);\n\n    const cacheStart = performance.now();\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      // Record as OTEL span event on enclosing span (not a child span).\n      // Fire-and-forget — no microtask overhead on the cache hot path.\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    if (cached && cached.stale && opts.staleWhileRevalidate) {\n      // Record stale cache hit as OTEL span event (fire-and-forget).\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n        stale: true,\n      });\n      // Serve stale immediately, trigger background refetch\n      sf.do(`swr:${key}`, async () => {\n        try {\n          const fresh = await fn(...args);\n          const tags = resolveTags(opts, args);\n          await handler.set(key, fresh, { ttl: opts.ttl, tags });\n        } catch (err) {\n          // Failed refetch — stale entry continues to be served.\n          logSwrRefetchFailed({ cacheKey: key, error: err });\n        }\n      }).catch(() => {\n        // Singleflight promise rejection handled — stale continues.\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss (or stale without SWR) — execute with singleflight\n    const result = await sf.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n\n    // Record cache miss as OTEL span event (fire-and-forget).\n    addSpanEventSync('timber.cache.miss', {\n      key,\n      duration_ms: Math.round(performance.now() - cacheStart),\n    });\n\n    return result as Awaited<ReturnType<Fn>>;\n  }) as unknown as Fn;\n}\n\n/**\n * Invalidate cache entries by tag or key.\n */\ncreateCache.invalidate = async function invalidate(\n  handler: CacheHandler,\n  opts: { key?: string; tag?: string }\n): Promise<void> {\n  await handler.invalidate(opts);\n};\n","import type { CacheOptions } from './index';\nimport { createCache } from './timber-cache';\nimport { getCacheHandler } from './handler-store';\n\n/**\n * Public caching API: `cache(fn, opts)`.\n *\n * Wraps an async function with cross-request caching. Uses the configured\n * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).\n *\n * ```ts\n * import { cache } from '@timber-js/app/cache';\n *\n * const getUser = cache(\n *   async (id: string) => db.users.findUnique({ where: { id } }),\n *   { ttl: 60, tags: (id) => [`user:${id}`] }\n * );\n * ```\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function cache<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: CacheOptions<Fn>\n): Fn {\n  return createCache(fn, opts, getCacheHandler());\n}\n\n/**\n * Invalidate cache entries by tag or key.\n *\n * ```ts\n * cache.invalidate({ tag: 'products' });\n * cache.invalidate({ key: 'user:abc' });\n * ```\n */\ncache.invalidate = async function invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n  await getCacheHandler().invalidate(opts);\n};\n","// @timber-js/app/cache — Caching primitives\n\nimport { estimateByteSize } from './sizeof.js';\n\nexport interface CacheHandler {\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\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface CacheOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  key?: (...args: Parameters<Fn>) => string;\n  staleWhileRevalidate?: boolean;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n  /** Timeout (ms) for singleflight-coalesced calls. Prevents hung fn() from\n   *  permanently blocking all future callers for the same cache key. See TIM-518. */\n  timeoutMs?: number;\n}\n\nexport interface MemoryCacheHandlerOptions {\n  /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */\n  maxEntries?: number;\n  /**\n   * @deprecated Use `maxEntries` instead. Will be removed in a future release.\n   * Alias for `maxEntries` — maximum number of entries (not bytes).\n   */\n  maxSize?: number;\n  /** Maximum total byte budget for all cached values. Oldest entries are evicted when exceeded. Default: no limit. */\n  maxBytes?: number;\n  /** Maximum byte size for a single cache entry. Entries exceeding this are silently dropped. Default: no limit. */\n  maxEntryBytes?: number;\n}\n\nexport class MemoryCacheHandler implements CacheHandler {\n  private store = new Map<\n    string,\n    { value: unknown; expiresAt: number; tags: string[]; byteSize: number }\n  >();\n  private maxEntries: number;\n  private maxBytes: number | undefined;\n  private maxEntryBytes: number | undefined;\n  private currentBytes = 0;\n\n  constructor(opts?: MemoryCacheHandlerOptions) {\n    // maxEntries takes precedence over deprecated maxSize\n    this.maxEntries = opts?.maxEntries ?? opts?.maxSize ?? 1000;\n    this.maxBytes = opts?.maxBytes;\n    this.maxEntryBytes = opts?.maxEntryBytes;\n  }\n\n  async get(key: string) {\n    const entry = this.store.get(key);\n    if (!entry) return null;\n\n    // Move to end of Map (most recently used) for LRU ordering\n    this.store.delete(key);\n    this.store.set(key, entry);\n\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {\n    const byteSize = estimateByteSize(value);\n\n    // Reject entries exceeding per-entry byte limit\n    if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) {\n      return;\n    }\n\n    // If key already exists, delete first to refresh insertion order and reclaim bytes\n    if (this.store.has(key)) {\n      const existing = this.store.get(key)!;\n      this.currentBytes -= existing.byteSize;\n      this.store.delete(key);\n    }\n\n    // Evict oldest entries (front of Map) if at entry count capacity\n    while (this.store.size >= this.maxEntries) {\n      this.evictOldest();\n    }\n\n    // Evict oldest entries if byte budget would be exceeded\n    if (this.maxBytes !== undefined) {\n      while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) {\n        this.evictOldest();\n      }\n      // If the single entry exceeds the total byte budget, don't store it\n      if (this.currentBytes + byteSize > this.maxBytes) {\n        return;\n      }\n    }\n\n    this.store.set(key, {\n      value,\n      expiresAt: Date.now() + opts.ttl * 1000,\n      tags: opts.tags,\n      byteSize,\n    });\n    this.currentBytes += byteSize;\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }) {\n    if (opts.key) {\n      const entry = this.store.get(opts.key);\n      if (entry) {\n        this.currentBytes -= entry.byteSize;\n        this.store.delete(opts.key);\n      }\n    }\n    if (opts.tag) {\n      for (const [key, entry] of this.store) {\n        if (entry.tags.includes(opts.tag)) {\n          this.currentBytes -= entry.byteSize;\n          this.store.delete(key);\n        }\n      }\n    }\n  }\n\n  /** Number of entries currently in the cache. */\n  get size(): number {\n    return this.store.size;\n  }\n\n  /** Estimated total byte size of all cached values. */\n  get bytes(): number {\n    return this.currentBytes;\n  }\n\n  /** Evict the oldest entry (front of Map). */\n  private evictOldest(): void {\n    const oldest = this.store.keys().next().value;\n    if (oldest !== undefined) {\n      const entry = this.store.get(oldest)!;\n      this.currentBytes -= entry.byteSize;\n      this.store.delete(oldest);\n    }\n  }\n}\n\nexport { RedisCacheHandler } from './redis-handler';\nexport type { RedisClient } from './redis-handler';\nexport { cache } from './cache-api';\nexport { setCacheHandler, getCacheHandler } from './handler-store';\n// NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.\n// Future feature pending design doc. See design/06-caching.md.\nexport { estimateByteSize } from './sizeof';\n// stableStringify, createSingleflight, and SingleflightTimeoutError are\n// internal utilities used by the cache implementation. They are not\n// re-exported here — import directly from the source files if needed\n// within the package. See TIM-720.\n"],"mappings":"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"}

package/dist/cache/timber-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timber-cache.d.ts","sourceRoot":"","sources":["../../src/cache/timber-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAsC1D;;;;;;;;;;;GAWG;AAEH,wBAAgB,WAAW,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACrE,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,EACtB,OAAO,EAAE,YAAY,GACpB,EAAE,CA6DJ;yBAjEe,WAAW;8BAuEhB,YAAY,QACf;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC"}
+{"version":3,"file":"timber-cache.d.ts","sourceRoot":"","sources":["../../src/cache/timber-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAuC1D;;;;;;;;;;;GAWG;AAEH,wBAAgB,WAAW,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACrE,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,EACtB,OAAO,EAAE,YAAY,GACpB,EAAE,CA6DJ;yBAjEe,WAAW;8BAuEhB,YAAY,QACf;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC"}

package/dist/client/error-boundary.js

@@ -1,6 +1,7 @@
 "use client";
 "use client";
-import { a as getSsrData, n as getRouterOrNull } from "../_chunks/router-ref-C8OCm7g7.js";
+import { n as getSsrData } from "../_chunks/ssr-data-B4CdH7rE.js";
+import { n as getRouterOrNull } from "../_chunks/router-ref-h3-UaCQv.js";
 import { Component, createElement } from "react";
 //#region src/client/error-boundary.tsx
 /**

package/dist/client/error-boundary.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-boundary.js","names":[],"sources":["../../src/client/error-boundary.tsx"],"sourcesContent":["'use client';\n\n/**\n * Framework-injected React error boundary.\n *\n * Catches errors thrown by children and renders a fallback component\n * with the appropriate props based on error type:\n *   - DenySignal (4xx) → { status, dangerouslyPassData }\n *   - RenderError (5xx) → { error, digest, reset }\n *   - Unhandled error → { error, digest: null, reset }\n *\n * The `status` prop controls which errors this boundary catches:\n *   - Specific code (e.g. 403) → only that status\n *   - Category (400) → any 4xx\n *   - Category (500) → any 5xx\n *   - Omitted → catches everything (error.tsx behavior)\n *\n * See design/10-error-handling.md §\"Status-Code Files\"\n */\n\nimport { Component, createElement, type ReactNode } from 'react';\nimport { getSsrData } from './ssr-data.js';\nimport { getRouterOrNull } from './router-ref.js';\n\n// ─── Page Unload Detection ───────────────────────────────────────────────────\n// Track whether the page is being unloaded (user refreshed or navigated away).\n// When this is true, error boundaries suppress activation — the error is from\n// the aborted connection, not an application error.\nlet _isUnloading = false;\nif (typeof window !== 'undefined') {\n  window.addEventListener('beforeunload', () => {\n    _isUnloading = true;\n  });\n  window.addEventListener('pagehide', () => {\n    _isUnloading = true;\n  });\n}\n\n// ─── Digest Types ────────────────────────────────────────────────────────────\n\n/** Structured digest returned by RSC onError for DenySignal. */\ninterface DenyDigest {\n  type: 'deny';\n  status: number;\n  data: unknown;\n}\n\n/** Structured digest returned by RSC onError for RenderError. */\ninterface RenderErrorDigest {\n  type: 'render-error';\n  code: string;\n  data: unknown;\n  status: number;\n}\n\n/** Structured digest returned by RSC onError for RedirectSignal. */\ninterface RedirectDigest {\n  type: 'redirect';\n  location: string;\n  status: number;\n}\n\ntype ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;\n\n// ─── Props & State ───────────────────────────────────────────────────────────\n\nexport interface TimberErrorBoundaryProps {\n  /** The component to render when an error is caught. */\n  fallbackComponent?: (...args: unknown[]) => ReactNode;\n  /**\n   * Pre-rendered fallback element. Used for MDX status files which are server\n   * components and cannot be passed as function props across the RSC→client\n   * boundary. When set, rendered directly instead of calling fallbackComponent.\n   *\n   * See design/10-error-handling.md §\"Status-Code File Variants\" — MDX status\n   * files are server components by default (zero client JS).\n   */\n  fallbackElement?: ReactNode;\n  /**\n   * Status code filter. If set, only catches errors matching this status.\n   * 400 = any 4xx, 500 = any 5xx, specific number = exact match.\n   */\n  status?: number;\n  /**\n   * When true, this boundary wraps a parallel slot. Slot denials are\n   * graceful degradation — they must NOT change the HTTP status code.\n   */\n  isSlotBoundary?: boolean;\n  children: ReactNode;\n}\n\ninterface TimberErrorBoundaryState {\n  hasError: boolean;\n  error: Error | null;\n}\n\n// Module-level guard: the first boundary to catch a given redirect digest\n// schedules the navigation and marks it handled here. Subsequent renders\n// (React retries the error-boundary render path multiple times in dev, and\n// outer boundaries that also see the error) become no-ops, preventing\n// duplicate router.navigate() calls.\nconst _handledRedirects = new WeakSet<object>();\n\n// ─── Component ───────────────────────────────────────────────────────────────\n\nexport class TimberErrorBoundary extends Component<\n  TimberErrorBoundaryProps,\n  TimberErrorBoundaryState\n> {\n  constructor(props: TimberErrorBoundaryProps) {\n    super(props);\n    this.state = { hasError: false, error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): TimberErrorBoundaryState {\n    // Suppress error boundaries during page unload (refresh/navigate away).\n    // The aborted connection causes React's streaming hydration to error,\n    // but the page is about to be replaced — showing an error boundary\n    // would be a jarring flash for the user.\n    if (_isUnloading) {\n      return { hasError: false, error: null };\n    }\n\n    return { hasError: true, error };\n  }\n\n  componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {\n    // Reset error state when children change (e.g. client-side navigation).\n    // Without this, navigating from one error page to another keeps the\n    // stale error — getDerivedStateFromError doesn't re-fire for new children.\n    if (this.state.hasError && prevProps.children !== this.props.children) {\n      this.setState({ hasError: false, error: null });\n    }\n  }\n\n  /** Reset the error state so children re-render. */\n  private reset = () => {\n    this.setState({ hasError: false, error: null });\n  };\n\n  render(): ReactNode {\n    if (!this.state.hasError || !this.state.error) {\n      return this.props.children;\n    }\n\n    const error = this.state.error;\n    const parsed = parseDigest(error);\n\n    // RedirectSignal handling splits by environment:\n    //\n    // - SSR (no window): re-throw so the Fizz shell fails and the server\n    //   pipeline catch block can produce a proper HTTP 3xx response. See\n    //   design/04-authorization.md.\n    //\n    // - Client (window exists): a RedirectSignal that leaked into the RSC\n    //   Flight payload during client navigation would otherwise bubble past\n    //   every error boundary to `window.onerror`, which in dev triggers the\n    //   Vite error overlay (false positive — navigation itself works).\n    //   Instead, ask the router to perform an SPA navigation to the target\n    //   and render nothing while it takes over. The router's own catch path\n    //   handles cross-origin / hard navigations. See TIM-838.\n    if (parsed?.type === 'redirect') {\n      if (typeof window === 'undefined') {\n        throw error;\n      }\n      // Dedupe: React may render the error-boundary fallback path more\n      // than once for a single caught error (dev-mode double render, and\n      // additional boundaries above us in the tree). Only schedule the\n      // navigation on the first render that sees this error instance.\n      const alreadyHandled = _handledRedirects.has(error);\n      if (!alreadyHandled) {\n        _handledRedirects.add(error);\n        const router = getRouterOrNull();\n        if (router) {\n          // Schedule the navigation outside the render phase to avoid\n          // setState-during-render warnings from router state updates.\n          queueMicrotask(() => {\n            router.navigate(parsed.location, { replace: true }).catch(() => {\n              // Fall back to a hard navigation if the soft navigation fails.\n              window.location.href = parsed.location;\n            });\n          });\n        } else {\n          // No router available (shouldn't happen post-bootstrap) — fall\n          // back to a hard navigation so the user still ends up at the\n          // target.\n          window.location.href = parsed.location;\n        }\n      }\n      return null;\n    }\n\n    // If this boundary has a status filter, check whether the error matches.\n    // Non-matching errors re-throw so an outer boundary can catch them.\n    if (this.props.status != null) {\n      const errorStatus = getErrorStatus(parsed, error);\n      if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) {\n        // Re-throw: this boundary doesn't handle this error.\n        throw error;\n      }\n    }\n\n    // Report DenySignal handling so the pipeline skips the redundant\n    // renderDenyPage() re-render — but ONLY when this boundary can fully\n    // handle the deny in-tree:\n    //\n    // ✅ TSX boundaries (fallbackComponent) — can receive runtime props\n    //    (status, dangerouslyPassData) dynamically in render()\n    // ❌ MDX boundaries (fallbackElement) — pre-rendered at tree-build time,\n    //    cannot receive runtime deny props. Must fall through to re-render.\n    //\n    // For qualifying segment boundaries: also set the HTTP status code from\n    // the DenySignal so the Response has the correct 4xx status. This runs\n    // synchronously during Fizz rendering, BEFORE onShellReady.\n    //\n    // For slot boundaries: set _denyHandledByBoundary but do NOT change\n    // statusCode — slot denials are graceful degradation.\n    //\n    // See TIM-664, LOCAL-298.\n    if (parsed?.type === 'deny') {\n      const canHandleInTree = this.props.fallbackElement == null;\n\n      if (canHandleInTree || this.props.isSlotBoundary) {\n        const ssrData = getSsrData();\n        if (ssrData?._navContext) {\n          ssrData._navContext._denyHandledByBoundary = true;\n          if (!this.props.isSlotBoundary) {\n            ssrData._navContext.statusCode = parsed.status;\n          }\n        }\n      }\n    }\n\n    // Pre-rendered fallback element (MDX status files) — render directly.\n    // MDX components are server components that cannot be passed as function\n    // props across the RSC→client boundary. Instead, they are pre-rendered\n    // as elements in the RSC environment and passed here as fallbackElement.\n    if (this.props.fallbackElement != null) {\n      return this.props.fallbackElement;\n    }\n\n    // Render the fallback component with the right props shape.\n    if (parsed?.type === 'deny') {\n      return createElement(this.props.fallbackComponent as never, {\n        status: parsed.status,\n        dangerouslyPassData: parsed.data,\n      });\n    }\n\n    // 5xx / RenderError / unhandled error\n    const digest =\n      parsed?.type === 'render-error' ? { code: parsed.code, data: parsed.data } : null;\n\n    return createElement(this.props.fallbackComponent as never, {\n      error,\n      digest,\n      reset: this.reset,\n    });\n  }\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\n/**\n * Parse the structured digest from the error.\n * React sets `error.digest` from the string returned by RSC's onError.\n */\nfunction parseDigest(error: Error): ParsedDigest | null {\n  const raw = (error as { digest?: string }).digest;\n  if (typeof raw !== 'string') return null;\n  try {\n    const parsed = JSON.parse(raw);\n    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {\n      return parsed as ParsedDigest;\n    }\n  } catch {\n    // Not JSON — legacy or unknown digest format\n  }\n  return null;\n}\n\n/**\n * Extract the HTTP status code from a parsed digest or error message.\n * Falls back to message pattern matching for errors without a digest.\n */\nfunction getErrorStatus(parsed: ParsedDigest | null, error: Error): number | null {\n  if (parsed?.type === 'deny') return parsed.status;\n  if (parsed?.type === 'render-error') return parsed.status;\n  if (parsed?.type === 'redirect') return parsed.status;\n\n  // Fallback: parse DenySignal message pattern for errors that lost their digest\n  const match = error.message.match(/^Access denied with status (\\d+)$/);\n  if (match) return parseInt(match[1], 10);\n\n  // Unhandled errors are implicitly 500\n  return 500;\n}\n\n/**\n * Check whether an error's status matches the boundary's status filter.\n * Category markers (400, 500) match any status in that range.\n */\nfunction statusMatches(boundaryStatus: number, errorStatus: number): boolean {\n  // Category catch-all: 400 matches any 4xx, 500 matches any 5xx\n  if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;\n  if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;\n  // Exact match\n  return boundaryStatus === errorStatus;\n}\n"],"mappings":"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"}
+{"version":3,"file":"error-boundary.js","names":[],"sources":["../../src/client/error-boundary.tsx"],"sourcesContent":["'use client';\n\n/**\n * Framework-injected React error boundary.\n *\n * Catches errors thrown by children and renders a fallback component\n * with the appropriate props based on error type:\n *   - DenySignal (4xx) → { status, dangerouslyPassData }\n *   - RenderError (5xx) → { error, digest, reset }\n *   - Unhandled error → { error, digest: null, reset }\n *\n * The `status` prop controls which errors this boundary catches:\n *   - Specific code (e.g. 403) → only that status\n *   - Category (400) → any 4xx\n *   - Category (500) → any 5xx\n *   - Omitted → catches everything (error.tsx behavior)\n *\n * See design/10-error-handling.md §\"Status-Code Files\"\n */\n\nimport { Component, createElement, type ReactNode } from 'react';\nimport { getSsrData } from './ssr-data.js';\nimport { getRouterOrNull } from './router-ref.js';\n\n// ─── Page Unload Detection ───────────────────────────────────────────────────\n// Track whether the page is being unloaded (user refreshed or navigated away).\n// When this is true, error boundaries suppress activation — the error is from\n// the aborted connection, not an application error.\nlet _isUnloading = false;\nif (typeof window !== 'undefined') {\n  window.addEventListener('beforeunload', () => {\n    _isUnloading = true;\n  });\n  window.addEventListener('pagehide', () => {\n    _isUnloading = true;\n  });\n}\n\n// ─── Digest Types ────────────────────────────────────────────────────────────\n\n/** Structured digest returned by RSC onError for DenySignal. */\ninterface DenyDigest {\n  type: 'deny';\n  status: number;\n  data: unknown;\n}\n\n/** Structured digest returned by RSC onError for RenderError. */\ninterface RenderErrorDigest {\n  type: 'render-error';\n  code: string;\n  data: unknown;\n  status: number;\n}\n\n/** Structured digest returned by RSC onError for RedirectSignal. */\ninterface RedirectDigest {\n  type: 'redirect';\n  location: string;\n  status: number;\n}\n\ntype ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;\n\n// ─── Props & State ───────────────────────────────────────────────────────────\n\nexport interface TimberErrorBoundaryProps {\n  /** The component to render when an error is caught. */\n  fallbackComponent?: (...args: unknown[]) => ReactNode;\n  /**\n   * Pre-rendered fallback element. Used for MDX status files which are server\n   * components and cannot be passed as function props across the RSC→client\n   * boundary. When set, rendered directly instead of calling fallbackComponent.\n   *\n   * See design/10-error-handling.md §\"Status-Code File Variants\" — MDX status\n   * files are server components by default (zero client JS).\n   */\n  fallbackElement?: ReactNode;\n  /**\n   * Status code filter. If set, only catches errors matching this status.\n   * 400 = any 4xx, 500 = any 5xx, specific number = exact match.\n   */\n  status?: number;\n  /**\n   * When true, this boundary wraps a parallel slot. Slot denials are\n   * graceful degradation — they must NOT change the HTTP status code.\n   */\n  isSlotBoundary?: boolean;\n  children: ReactNode;\n}\n\ninterface TimberErrorBoundaryState {\n  hasError: boolean;\n  error: Error | null;\n}\n\n// Module-level guard: the first boundary to catch a given redirect digest\n// schedules the navigation and marks it handled here. Subsequent renders\n// (React retries the error-boundary render path multiple times in dev, and\n// outer boundaries that also see the error) become no-ops, preventing\n// duplicate router.navigate() calls.\nconst _handledRedirects = new WeakSet<object>();\n\n// ─── Component ───────────────────────────────────────────────────────────────\n\nexport class TimberErrorBoundary extends Component<\n  TimberErrorBoundaryProps,\n  TimberErrorBoundaryState\n> {\n  constructor(props: TimberErrorBoundaryProps) {\n    super(props);\n    this.state = { hasError: false, error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): TimberErrorBoundaryState {\n    // Suppress error boundaries during page unload (refresh/navigate away).\n    // The aborted connection causes React's streaming hydration to error,\n    // but the page is about to be replaced — showing an error boundary\n    // would be a jarring flash for the user.\n    if (_isUnloading) {\n      return { hasError: false, error: null };\n    }\n\n    return { hasError: true, error };\n  }\n\n  componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {\n    // Reset error state when children change (e.g. client-side navigation).\n    // Without this, navigating from one error page to another keeps the\n    // stale error — getDerivedStateFromError doesn't re-fire for new children.\n    if (this.state.hasError && prevProps.children !== this.props.children) {\n      this.setState({ hasError: false, error: null });\n    }\n  }\n\n  /** Reset the error state so children re-render. */\n  private reset = () => {\n    this.setState({ hasError: false, error: null });\n  };\n\n  render(): ReactNode {\n    if (!this.state.hasError || !this.state.error) {\n      return this.props.children;\n    }\n\n    const error = this.state.error;\n    const parsed = parseDigest(error);\n\n    // RedirectSignal handling splits by environment:\n    //\n    // - SSR (no window): re-throw so the Fizz shell fails and the server\n    //   pipeline catch block can produce a proper HTTP 3xx response. See\n    //   design/04-authorization.md.\n    //\n    // - Client (window exists): a RedirectSignal that leaked into the RSC\n    //   Flight payload during client navigation would otherwise bubble past\n    //   every error boundary to `window.onerror`, which in dev triggers the\n    //   Vite error overlay (false positive — navigation itself works).\n    //   Instead, ask the router to perform an SPA navigation to the target\n    //   and render nothing while it takes over. The router's own catch path\n    //   handles cross-origin / hard navigations. See TIM-838.\n    if (parsed?.type === 'redirect') {\n      if (typeof window === 'undefined') {\n        throw error;\n      }\n      // Dedupe: React may render the error-boundary fallback path more\n      // than once for a single caught error (dev-mode double render, and\n      // additional boundaries above us in the tree). Only schedule the\n      // navigation on the first render that sees this error instance.\n      const alreadyHandled = _handledRedirects.has(error);\n      if (!alreadyHandled) {\n        _handledRedirects.add(error);\n        const router = getRouterOrNull();\n        if (router) {\n          // Schedule the navigation outside the render phase to avoid\n          // setState-during-render warnings from router state updates.\n          queueMicrotask(() => {\n            router.navigate(parsed.location, { replace: true }).catch(() => {\n              // Fall back to a hard navigation if the soft navigation fails.\n              window.location.href = parsed.location;\n            });\n          });\n        } else {\n          // No router available (shouldn't happen post-bootstrap) — fall\n          // back to a hard navigation so the user still ends up at the\n          // target.\n          window.location.href = parsed.location;\n        }\n      }\n      return null;\n    }\n\n    // If this boundary has a status filter, check whether the error matches.\n    // Non-matching errors re-throw so an outer boundary can catch them.\n    if (this.props.status != null) {\n      const errorStatus = getErrorStatus(parsed, error);\n      if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) {\n        // Re-throw: this boundary doesn't handle this error.\n        throw error;\n      }\n    }\n\n    // Report DenySignal handling so the pipeline skips the redundant\n    // renderDenyPage() re-render — but ONLY when this boundary can fully\n    // handle the deny in-tree:\n    //\n    // ✅ TSX boundaries (fallbackComponent) — can receive runtime props\n    //    (status, dangerouslyPassData) dynamically in render()\n    // ❌ MDX boundaries (fallbackElement) — pre-rendered at tree-build time,\n    //    cannot receive runtime deny props. Must fall through to re-render.\n    //\n    // For qualifying segment boundaries: also set the HTTP status code from\n    // the DenySignal so the Response has the correct 4xx status. This runs\n    // synchronously during Fizz rendering, BEFORE onShellReady.\n    //\n    // For slot boundaries: set _denyHandledByBoundary but do NOT change\n    // statusCode — slot denials are graceful degradation.\n    //\n    // See TIM-664, LOCAL-298.\n    if (parsed?.type === 'deny') {\n      const canHandleInTree = this.props.fallbackElement == null;\n\n      if (canHandleInTree || this.props.isSlotBoundary) {\n        const ssrData = getSsrData();\n        if (ssrData?._navContext) {\n          ssrData._navContext._denyHandledByBoundary = true;\n          if (!this.props.isSlotBoundary) {\n            ssrData._navContext.statusCode = parsed.status;\n          }\n        }\n      }\n    }\n\n    // Pre-rendered fallback element (MDX status files) — render directly.\n    // MDX components are server components that cannot be passed as function\n    // props across the RSC→client boundary. Instead, they are pre-rendered\n    // as elements in the RSC environment and passed here as fallbackElement.\n    if (this.props.fallbackElement != null) {\n      return this.props.fallbackElement;\n    }\n\n    // Render the fallback component with the right props shape.\n    if (parsed?.type === 'deny') {\n      return createElement(this.props.fallbackComponent as never, {\n        status: parsed.status,\n        dangerouslyPassData: parsed.data,\n      });\n    }\n\n    // 5xx / RenderError / unhandled error\n    const digest =\n      parsed?.type === 'render-error' ? { code: parsed.code, data: parsed.data } : null;\n\n    return createElement(this.props.fallbackComponent as never, {\n      error,\n      digest,\n      reset: this.reset,\n    });\n  }\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\n/**\n * Parse the structured digest from the error.\n * React sets `error.digest` from the string returned by RSC's onError.\n */\nfunction parseDigest(error: Error): ParsedDigest | null {\n  const raw = (error as { digest?: string }).digest;\n  if (typeof raw !== 'string') return null;\n  try {\n    const parsed = JSON.parse(raw);\n    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {\n      return parsed as ParsedDigest;\n    }\n  } catch {\n    // Not JSON — legacy or unknown digest format\n  }\n  return null;\n}\n\n/**\n * Extract the HTTP status code from a parsed digest or error message.\n * Falls back to message pattern matching for errors without a digest.\n */\nfunction getErrorStatus(parsed: ParsedDigest | null, error: Error): number | null {\n  if (parsed?.type === 'deny') return parsed.status;\n  if (parsed?.type === 'render-error') return parsed.status;\n  if (parsed?.type === 'redirect') return parsed.status;\n\n  // Fallback: parse DenySignal message pattern for errors that lost their digest\n  const match = error.message.match(/^Access denied with status (\\d+)$/);\n  if (match) return parseInt(match[1], 10);\n\n  // Unhandled errors are implicitly 500\n  return 500;\n}\n\n/**\n * Check whether an error's status matches the boundary's status filter.\n * Category markers (400, 500) match any status in that range.\n */\nfunction statusMatches(boundaryStatus: number, errorStatus: number): boolean {\n  // Category catch-all: 400 matches any 4xx, 500 matches any 5xx\n  if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;\n  if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;\n  // Exact match\n  return boundaryStatus === errorStatus;\n}\n"],"mappings":"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"}

package/dist/client/form.d.ts

@@ -18,13 +18,15 @@ import type { FormFlashData } from '../server/form-flash';
  */
 export type UseActionStateFn<TData> = (prevState: ActionResult<TData> | null, formData: FormData) => Promise<ActionResult<TData>>;
 /**
- * Return type of useActionState — matches React 19's useActionState return.
- * [result, formAction, isPending]
+ * Return type of useActionState.
+ * [result, formAction, isPending, errors]
+ * The 4th element is auto-derived from result via useFormErrors logic.
  */
 export type UseActionStateReturn<TData> = [
     result: ActionResult<TData> | null,
     formAction: (formData: FormData) => void,
-    isPending: boolean
+    isPending: boolean,
+    errors: FormErrorsResult
 ];
 /**
  * Typed wrapper around React 19's `useActionState` that understands
@@ -71,7 +73,7 @@ export declare function useFormAction<TData = unknown, TInput = unknown>(action:
     (...args: undefined extends TInput ? [input?: InputHint<TInput>] : [input: InputHint<TInput>]) => Promise<ActionResult<TData>>,
     boolean
 ];
-/** Return type of useFormErrors(). */
+/** Return type of the errors element in useActionState. */
 export interface FormErrorsResult {
     /** Per-field validation errors keyed by field name. */
     fieldErrors: Record<string, string[]>;
@@ -88,27 +90,11 @@ export interface FormErrorsResult {
     getFieldError: (field: string) => string | null;
 }
 /**
- * Extract per-field and form-level errors from an ActionResult.
- *
- * Pure function (no internal hooks) — follows React naming convention
- * since it's used in render. Accepts the result from `useActionState`
- * or flash data from `getFormFlash()`.
- *
- * @example
- * ```tsx
- * const [result, action, isPending] = useActionState(createTodo, null)
- * const errors = useFormErrors(result)
- *
- * return (
- *   <form action={action}>
- *     <input name="title" />
- *     {errors.getFieldError('title') && <p>{errors.getFieldError('title')}</p>}
- *     {errors.formErrors.map(e => <p key={e}>{e}</p>)}
- *   </form>
- * )
- * ```
+ * Derive FormErrorsResult from an action result.
+ * Used internally by useActionState 4th tuple element.
+ * @internal — exported for test access only.
  */
-export declare function useFormErrors<TData>(result: ActionResult<TData> | {
+export declare function deriveFormErrors<TData>(result: ActionResult<TData> | {
     validationErrors?: ValidationErrors;
     serverError?: {
         code: string;

package/dist/client/form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../src/client/form.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,KAAK,IAAI,CACpC,SAAS,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,EACrC,QAAQ,EAAE,QAAQ,KACf,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAElC;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,KAAK,IAAI;IACxC,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI;IAClC,UAAU,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI;IACxC,SAAS,EAAE,OAAO;CACnB,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAClC,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAC/B,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,aAAa,GAAG,IAAI,EACxD,SAAS,CAAC,EAAE,MAAM,GACjB,oBAAoB,CAAC,KAAK,CAAC,CAI7B;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,EAC7D,MAAM,EAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,GAClF;IACD,CACE,GAAG,IAAI,EAAE,SAAS,SAAS,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,KACzF,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,OAAO;CACR,CAeA;AAID,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,4CAA4C;IAC5C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,uDAAuD;IACvD,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IACrE,sCAAsC;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EACjC,MAAM,EACF,YAAY,CAAC,KAAK,CAAC,GACnB;IACE,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CAChE,GACD,IAAI,GACP,gBAAgB,CA6ClB"}
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../src/client/form.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,KAAK,IAAI,CACpC,SAAS,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,EACrC,QAAQ,EAAE,QAAQ,KACf,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAElC;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,KAAK,IAAI;IACxC,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI;IAClC,UAAU,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI;IACxC,SAAS,EAAE,OAAO;IAClB,MAAM,EAAE,gBAAgB;CACzB,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAClC,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAC/B,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,aAAa,GAAG,IAAI,EACxD,SAAS,CAAC,EAAE,MAAM,GACjB,oBAAoB,CAAC,KAAK,CAAC,CAU7B;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,EAC7D,MAAM,EAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,GAClF;IACD,CACE,GAAG,IAAI,EAAE,SAAS,SAAS,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,KACzF,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,OAAO;CACR,CAeA;AAID,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,4CAA4C;IAC5C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,uDAAuD;IACvD,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IACrE,sCAAsC;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACjD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EACpC,MAAM,EACF,YAAY,CAAC,KAAK,CAAC,GACnB;IACE,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CAChE,GACD,IAAI,GACP,gBAAgB,CA6ClB"}

package/dist/client/index.d.ts

@@ -11,12 +11,8 @@ export type { LinkStatus } from './use-link-status';
 export { useRouter } from './use-router';
 export type { AppRouterInstance } from './use-router';
 export { usePathname } from './use-pathname';
-export { useSearchParams } from './use-search-params';
 export { useSelectedLayoutSegment, useSelectedLayoutSegments } from './use-selected-layout-segment';
-export { useActionState, useFormAction, useFormErrors } from './form';
+export { useActionState, useFormAction } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
-export { useSegmentParams } from './use-params';
-export { useQueryStates } from './use-query-states';
-export { useCookie } from './use-cookie';
 export type { ClientCookieOptions, CookieSetter } from './use-cookie';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AASA,YAAY,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGjD,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAChG,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC/F,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AA2CpF,MAAM,WAAW,YAAY;CAG5B;AACD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAGpG,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACtE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGpD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AASA,YAAY,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGjD,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAChG,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC/F,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AA2CpF,MAAM,WAAW,YAAY;CAG5B;AACD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAGpG,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAUvF,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/client/index.js

@@ -1,12 +1,16 @@
 "use client";
 import { r as __exportAll } from "../_chunks/chunk-BYIpzuS7.js";
-import { t as classifyUrlSegment } from "../_chunks/segment-classify-BDNn6EzD.js";
-import { n as useQueryStates, r as getSearchParamsDefinition } from "../_chunks/use-query-states-BiV5GJgm.js";
-import { t as mergePreservedSearchParams } from "../_chunks/merge-search-params-Cm_KIWDX.js";
-import { a as getSsrData, l as cachedSearch, n as getRouterOrNull, s as _setCachedSearch, u as cachedSearchParams } from "../_chunks/router-ref-C8OCm7g7.js";
-import { n as useSegmentContext } from "../_chunks/segment-context-fHFLF1PE.js";
-import { c as usePendingNavigationUrl, d as unmountLinkForCurrentNavigation, l as LINK_IDLE, n as useSegmentParams, s as useNavigationContext, u as setLinkForCurrentNavigation } from "../_chunks/use-params-IOPu7E8t.js";
-import { t as _registerUseCookieModule } from "../_chunks/define-cookie-BowvzoP0.js";
+import { n as classifyUrlSegment } from "../_chunks/segment-classify-BjfuctV2.js";
+import { t as getSearchParamsDefinition } from "../_chunks/registry-I2ss-lvy.js";
+import { n as fromSchema } from "../_chunks/schema-bridge-Cxu4l-7p.js";
+import { t as _registerUseSegmentParams } from "../_chunks/define-CfBPoJb0.js";
+import { n as assertValidCookieName, t as mergePreservedSearchParams } from "../_chunks/merge-search-params-BphMdht_.js";
+import { r as _registerUseCookieModule, t as _registerFromSchema } from "../_chunks/define-cookie-BjpIt4UC.js";
+import { n as getSsrData } from "../_chunks/ssr-data-B4CdH7rE.js";
+import { n as getRouterOrNull } from "../_chunks/router-ref-h3-UaCQv.js";
+import { n as useSegmentContext } from "../_chunks/segment-context-Dx_OizxD.js";
+import { i as unmountLinkForCurrentNavigation, n as LINK_IDLE, r as setLinkForCurrentNavigation } from "../_chunks/navigation-root-BCYczjml.js";
+import { c as usePendingNavigationUrl, n as useSegmentParams, s as useNavigationContext } from "../_chunks/use-segment-params-BkpKAQ7D.js";
 import { createContext, useActionState as useActionState$1, useContext, useEffect, useOptimistic, useRef, useSyncExternalStore, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/client/use-link-status.ts
@@ -444,67 +448,6 @@ function usePathname() {
 	return "/";
 }
 //#endregion
-//#region src/client/use-search-params.ts
-/**
-* useSearchParams() — client-side hook for reading URL search params.
-*
-* Returns a read-only URLSearchParams instance reflecting the current
-* URL's query string. Updates when client-side navigation changes the URL.
-*
-* This is a thin wrapper over window.location.search, provided for
-* Next.js API compatibility (libraries like nuqs import useSearchParams
-* from next/navigation).
-*
-* Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
-* URLSearchParams. Mutation methods (set, delete, append) work on the
-* local copy but do NOT affect the URL — use the router or nuqs for that.
-*
-* During SSR, reads the request search params from the SSR ALS context
-* (populated by ssr-entry.ts) instead of window.location.
-*
-* All mutable state is delegated to client/state.ts for singleton guarantees.
-* See design/18-build-system.md §"Singleton State Registry"
-*/
-function getSearch() {
-	if (typeof window !== "undefined") return window.location.search;
-	const data = getSsrData();
-	if (!data) return "";
-	const str = new URLSearchParams(data.searchParams).toString();
-	return str ? `?${str}` : "";
-}
-function getServerSearch() {
-	const data = getSsrData();
-	if (!data) return "";
-	const str = new URLSearchParams(data.searchParams).toString();
-	return str ? `?${str}` : "";
-}
-function subscribe(callback) {
-	window.addEventListener("popstate", callback);
-	return () => window.removeEventListener("popstate", callback);
-}
-function getSearchParams() {
-	const search = getSearch();
-	if (search !== cachedSearch) {
-		const params = new URLSearchParams(search);
-		_setCachedSearch(search, params);
-		return params;
-	}
-	return cachedSearchParams;
-}
-function getServerSearchParams() {
-	const data = getSsrData();
-	return data ? new URLSearchParams(data.searchParams) : new URLSearchParams();
-}
-/**
-* Read the current URL search params.
-*
-* Compatible with Next.js's `useSearchParams()` from `next/navigation`.
-*/
-function useSearchParams() {
-	useSyncExternalStore(subscribe, getSearch, getServerSearch);
-	return typeof window !== "undefined" ? getSearchParams() : getServerSearchParams();
-}
-//#endregion
 //#region src/client/use-selected-layout-segment.ts
 /**
 * useSelectedLayoutSegment / useSelectedLayoutSegments — client-side hooks
@@ -635,7 +578,13 @@ function useSelectedLayoutSegments(parallelRouteKey) {
 * ```
 */
 function useActionState(action, initialState, permalink) {
-	return useActionState$1(action, initialState, permalink);
+	const [result, formAction, isPending] = useActionState$1(action, initialState, permalink);
+	return [
+		result,
+		formAction,
+		isPending,
+		deriveFormErrors(result)
+	];
 }
 /**
 * Hook for calling a server action imperatively (not via a form).
@@ -661,27 +610,11 @@ function useFormAction(action) {
 	return [execute, isPending];
 }
 /**
-* Extract per-field and form-level errors from an ActionResult.
-*
-* Pure function (no internal hooks) — follows React naming convention
-* since it's used in render. Accepts the result from `useActionState`
-* or flash data from `getFormFlash()`.
-*
-* @example
-* ```tsx
-* const [result, action, isPending] = useActionState(createTodo, null)
-* const errors = useFormErrors(result)
-*
-* return (
-*   <form action={action}>
-*     <input name="title" />
-*     {errors.getFieldError('title') && <p>{errors.getFieldError('title')}</p>}
-*     {errors.formErrors.map(e => <p key={e}>{e}</p>)}
-*   </form>
-* )
-* ```
+* Derive FormErrorsResult from an action result.
+* Used internally by useActionState 4th tuple element.
+* @internal — exported for test access only.
 */
-function useFormErrors(result) {
+function deriveFormErrors(result) {
 	const empty = {
 		fieldErrors: {},
 		formErrors: [],
@@ -720,7 +653,10 @@ function useFormErrors(result) {
 *
 * See design/29-cookies.md §"useCookie(name) Hook"
 */
-var use_cookie_exports = /* @__PURE__ */ __exportAll({ useCookie: () => useCookie });
+var use_cookie_exports = /* @__PURE__ */ __exportAll({
+	notifyCookieChange: () => notifyCookieChange,
+	useCookie: () => useCookie
+});
 /** Per-name subscriber sets. */
 var listeners = /* @__PURE__ */ new Map();
 /** Parse a cookie name from document.cookie. */
@@ -748,6 +684,16 @@ function notify(name) {
 	if (subs) for (const fn of subs) fn();
 }
 /**
+* Notify useCookie subscribers that a cookie value changed.
+* Called by defineCookie's imperative client .set()/.delete() methods
+* so mounted useCookie() consumers re-render.
+*
+* @internal — framework use only
+*/
+function notifyCookieChange(name) {
+	notify(name);
+}
+/**
 * Reactive hook for reading/writing a client-side cookie.
 *
 * Returns `[value, setCookie, deleteCookie]`:
@@ -774,7 +720,9 @@ function useCookie(name, defaultOptions) {
 	const getSnapshot = () => getCookieValue(name);
 	const getServerSnapshot = () => getSsrData()?.cookies.get(name);
 	const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+	assertValidCookieName(name);
 	const setCookie = (newValue, options) => {
+		if (typeof newValue !== "string") throw new Error(`[timber] useCookie(${JSON.stringify(name)}): value must be a string, got ${typeof newValue}.\n  To store a JSON-serializable value, use defineCookie + jsonCookieCodec from\n  '@timber-js/app/cookies' and call its useCookie() hook instead.`);
 		const merged = {
 			...defaultOptions,
 			...options
@@ -799,7 +747,9 @@ function useCookie(name, defaultOptions) {
 //#endregion
 //#region src/client/index.ts
 _registerUseCookieModule(use_cookie_exports);
+_registerFromSchema(fromSchema);
+_registerUseSegmentParams(useSegmentParams);
 //#endregion
-export { Link, LinkStatusContext, buildLinkProps, interpolateParams, mergePreservedSearchParams, resolveHref, useActionState, useCookie, useFormAction, useFormErrors, useLinkStatus, usePathname, usePendingNavigation, useQueryStates, useRouter, useSearchParams, useSegmentParams, useSelectedLayoutSegment, useSelectedLayoutSegments, validateLinkHref };
+export { Link, LinkStatusContext, buildLinkProps, interpolateParams, mergePreservedSearchParams, resolveHref, useActionState, useFormAction, useLinkStatus, usePathname, usePendingNavigation, useRouter, useSelectedLayoutSegment, useSelectedLayoutSegments, validateLinkHref };
 
 //# sourceMappingURL=index.js.map