@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.140

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../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/register-cached-function.ts","../../src/cache/index.ts"],"sourcesContent":["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 */\nexport interface Singleflight {\n  do<T>(key: string, fn: () => Promise<T>): Promise<T>;\n}\n\nexport function createSingleflight(): Singleflight {\n  const inflight = new Map<string, Promise<unknown>>();\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      const promise = fn().finally(() => {\n        inflight.delete(key);\n      });\n      inflight.set(key, promise);\n      return promise;\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 singleflight = 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): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {\n  const fnId = `timber-cache:${fnIdCounter++}`;\n\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      singleflight\n        .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        })\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 singleflight.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  };\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 { CacheHandler } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\nimport { fnv1aHash } from './fast-hash.js';\n\nconst singleflight = createSingleflight();\n\n// Prop names that suggest request-specific data — triggers dev warning for \"use cache\" components.\nconst REQUEST_SPECIFIC_PROPS = new Set([\n  'cookies',\n  'cookie',\n  'session',\n  'sessionId',\n  'token',\n  'authorization',\n  'auth',\n  'headers',\n]);\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface RegisterCachedFunctionOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  id: string;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n  /** True when the cached function is a React component (PascalCase name). */\n  isComponent?: boolean;\n}\n\n/**\n * Generate a cache key from a stable function ID and serialized args.\n *\n * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. The id prefix\n * provides namespace isolation; the hash covers the args.\n * See TIM-370.\n */\nfunction generateKey(id: string, args: unknown[]): string {\n  const raw = id + ':' + stableStringify(args);\n  return id + ':' + fnv1aHash(raw);\n}\n\n/**\n * Resolve tags from 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: RegisterCachedFunctionOptions<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/**\n * Checks if component props contain request-specific keys and emits a dev warning.\n * Only runs when process.env.NODE_ENV !== 'production'.\n */\nfunction warnRequestSpecificProps(id: string, props: unknown): void {\n  if (typeof props !== 'object' || props === null) return;\n  const keys = Object.keys(props);\n  const suspicious = keys.filter((k) => REQUEST_SPECIFIC_PROPS.has(k.toLowerCase()));\n  if (suspicious.length > 0) {\n    console.warn(\n      `[timber] \"use cache\" component ${id} received request-specific props: ${suspicious.join(', ')}. ` +\n        `This may serve one user's cached render to another user. ` +\n        `Remove request-specific data from props or remove \"use cache\".`\n    );\n  }\n}\n\n/**\n * Runtime for the \"use cache\" directive transform. Wraps an async function\n * with caching using the same cache handler as timber.cache.\n *\n * The stable `id` (file path + function name) ensures cache keys are consistent\n * across builds. Args/props are hashed with SHA-256 for the per-call key.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function registerCachedFunction<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: RegisterCachedFunctionOptions<Fn>,\n  handler: CacheHandler\n): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {\n  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    // Dev-mode warning for components with request-specific props\n    if (opts.isComponent && process.env.NODE_ENV !== 'production' && args.length > 0) {\n      warnRequestSpecificProps(opts.id, args[0]);\n    }\n\n    const key = generateKey(opts.id, args);\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss or stale — execute with singleflight\n    const result = await singleflight.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n    return result as Awaited<ReturnType<Fn>>;\n  };\n}\n","// @timber-js/app/cache — Caching primitives\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}\n\nexport interface MemoryCacheHandlerOptions {\n  /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */\n  maxSize?: number;\n}\n\nexport class MemoryCacheHandler implements CacheHandler {\n  private store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();\n  private maxSize: number;\n\n  constructor(opts?: MemoryCacheHandlerOptions) {\n    this.maxSize = opts?.maxSize ?? 1000;\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    // If key already exists, delete first to refresh insertion order\n    if (this.store.has(key)) {\n      this.store.delete(key);\n    }\n\n    // Evict oldest entries (front of Map) if at capacity\n    while (this.store.size >= this.maxSize) {\n      const oldest = this.store.keys().next().value;\n      if (oldest !== undefined) {\n        this.store.delete(oldest);\n      } else {\n        break;\n      }\n    }\n\n    this.store.set(key, {\n      value,\n      expiresAt: Date.now() + opts.ttl * 1000,\n      tags: opts.tags,\n    });\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }) {\n    if (opts.key) {\n      this.store.delete(opts.key);\n    }\n    if (opts.tag) {\n      for (const [key, entry] of this.store) {\n        if (entry.tags.includes(opts.tag)) {\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\nexport { RedisCacheHandler } from './redis-handler';\nexport type { RedisClient } from './redis-handler';\nexport { createCache } from './timber-cache';\nexport { registerCachedFunction } from './register-cached-function';\nexport type { RegisterCachedFunctionOptions } from './register-cached-function';\nexport { stableStringify } from './stable-stringify';\nexport { createSingleflight } from './singleflight';\nexport type { Singleflight } from './singleflight';\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/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 (e) {\n    // Circular reference or non-serializable value\n    console.debug('[timber] sizeof estimation failed:', e instanceof Error ? e.message : e);\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","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\nlet unstableIdCounter = 0;\nlet hasWarnedUnstableId = false;\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  stableId?: string\n): Fn {\n  let fnId: string;\n  if (stableId) {\n    fnId = stableId;\n  } else if (opts.key) {\n    // Explicit key function — fnId is only used for singleflight, not for\n    // cache keys, so a counter is acceptable here.\n    fnId = `timber-cache:${unstableIdCounter++}`;\n  } else {\n    fnId = `timber-cache:unstable:${unstableIdCounter++}`;\n    if (\n      !hasWarnedUnstableId &&\n      typeof process !== 'undefined' &&\n      process.env?.NODE_ENV !== 'test'\n    ) {\n      hasWarnedUnstableId = true;\n      console.warn(\n        '[timber] cache() called without a stable ID or explicit key function. ' +\n          'Cache keys will use a process-local counter which is unstable across ' +\n          'cold starts. Run through the timber Vite plugin or provide an explicit ' +\n          '`key` option to fix this.'\n      );\n    }\n  }\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  stableId?: string\n): Fn {\n  return createCache(fn, opts, getCacheHandler(), stableId);\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/singleflight.d.ts

@@ -3,9 +3,26 @@
  * execution. All callers receive the same result (or error).
  *
  * Per-process, in-memory. Each process coalesces independently.
+ *
+ * An optional `timeoutMs` prevents hung `fn()` calls from permanently
+ * blocking all future callers for that key. When set, `fn()` is raced
+ * against a timeout — if the timeout fires first, the promise rejects
+ * with `SingleflightTimeoutError`, `finally` cleans up the key, and
+ * subsequent callers can retry. See TIM-518.
  */
+export interface SingleflightOptions {
+    /** Maximum time (ms) a coalesced call may run before being rejected. */
+    timeoutMs?: number;
+}
 export interface Singleflight {
     do<T>(key: string, fn: () => Promise<T>): Promise<T>;
 }
-export declare function createSingleflight(): Singleflight;
+/**
+ * Error thrown when a singleflight call exceeds `timeoutMs`.
+ * Exported so callers can distinguish timeout from other errors.
+ */
+export declare class SingleflightTimeoutError extends Error {
+    constructor(key: string, timeoutMs: number);
+}
+export declare function createSingleflight(opts?: SingleflightOptions): Singleflight;
 //# sourceMappingURL=singleflight.d.ts.map

package/dist/cache/singleflight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"singleflight.d.ts","sourceRoot":"","sources":["../../src/cache/singleflight.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACtD;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAejD"}
+{"version":3,"file":"singleflight.d.ts","sourceRoot":"","sources":["../../src/cache/singleflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACtD;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAI3C;AAED,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAkD3E"}

package/dist/cache/sizeof.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Lightweight byte-size estimation for cache entries.
+ *
+ * Estimates the in-memory byte cost of a JavaScript value using
+ * JSON.stringify().length * 2 (UTF-16 char width). This is a rough
+ * approximation — it doesn't account for V8 object overhead, Map
+ * metadata, or non-serializable values — but it's fast and good
+ * enough for cache budget enforcement.
+ *
+ * Values that fail JSON serialization (circular references, BigInt,
+ * etc.) return 0, allowing the entry to be cached without counting
+ * toward the byte budget. This is a conservative choice: it's better
+ * to cache and undercount than to reject the entry.
+ */
+/**
+ * Estimate the byte size of a value.
+ *
+ * Uses `JSON.stringify(value).length * 2` to approximate UTF-16
+ * in-memory size. Returns 0 if the value is not serializable.
+ */
+export declare function estimateByteSize(value: unknown): number;
+//# sourceMappingURL=sizeof.d.ts.map

package/dist/cache/sizeof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sizeof.d.ts","sourceRoot":"","sources":["../../src/cache/sizeof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWvD"}

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

@@ -11,7 +11,7 @@ import type { CacheHandler, CacheOptions } from './index';
  * Cache hits/misses are recorded as OTEL span events on the enclosing
  * span (not child spans). The DevSpanProcessor reads these for dev log output.
  */
-export declare function createCache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, handler: CacheHandler): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>>;
+export declare function createCache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, handler: CacheHandler, stableId?: string): Fn;
 export declare namespace createCache {
     var invalidate: (handler: CacheHandler, opts: {
         key?: string;

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,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAyD/D;yBA7De,WAAW;8BAmEhB,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,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,EAAE,CAmFJ;yBAxFe,WAAW;8BA8FhB,YAAY,QACf;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC"}

package/dist/cli-schema-sync.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `timber schema sync` — scan filesystem for dynamic segments, append
+ * missing entries with `codec.string` defaults, and remove stale entries
+ * whose segments no longer exist in the filesystem.
+ *
+ * Design doc: design/41-global-params.md §Auto-Scaffolding
+ */
+/**
+ * Collect all unique bracket-keyed dynamic segment names from the route tree.
+ * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+ */
+export declare function collectDynamicSegments(appDir: string): string[];
+/**
+ * Parse existing bracket keys from an app/schema.ts file.
+ * Uses regex to find keys in segmentParams: { '[key]': ... } blocks.
+ */
+export declare function parseExistingSchemaKeys(content: string): string[];
+/**
+ * Find the schema file path if it exists.
+ */
+export declare function findSchemaFile(appDir: string): string | undefined;
+export declare function defaultCodecForSegment(seg: string): string;
+export interface SchemaSyncResult {
+    /** Segments found in the filesystem. */
+    filesystemSegments: string[];
+    /** Segments already defined in app/schema.ts. */
+    existingSegments: string[];
+    /** Segments that were added. */
+    addedSegments: string[];
+    /** Segments that were removed (no longer in filesystem). */
+    removedSegments: string[];
+    /** Whether a new schema file was created. */
+    created: boolean;
+}
+/**
+ * Run the schema sync: scan filesystem, diff against schema, append missing.
+ */
+export declare function runSchemaSync(projectRoot: string): SchemaSyncResult;
+//# sourceMappingURL=cli-schema-sync.d.ts.map

package/dist/cli-schema-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-schema-sync.d.ts","sourceRoot":"","sources":["../src/cli-schema-sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAK/D;AAeD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CASjE;AAKD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMjE;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAiJD,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gCAAgC;IAChC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,4DAA4D;IAC5D,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CA8DnE"}

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-declare const COMMANDS: readonly ["dev", "build", "preview", "check"];
+declare const COMMANDS: readonly ["dev", "build", "preview", "check", "schema"];
 type Command = (typeof COMMANDS)[number];
 export interface ParsedArgs {
     command: Command;
@@ -21,7 +21,12 @@ export interface ViteDeps {
 }
 /**
  * Start the Vite dev server.
- * Middleware re-runs on file change via HMR wiring in timber-routing.
+ *
+ * The timber plugin binds the port immediately with a holding page
+ * (in rootSync's config hook) so browsers see a "starting..." page
+ * instead of ERR_CONNECTION_REFUSED during initialization.
+ *
+ * See design/21-dev-server.md, TIM-665.
  */
 export declare function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void>;
 /**
@@ -46,5 +51,12 @@ export declare function runPreview(options: CommandOptions, _deps?: ViteDeps): P
  * Runs tsgo --noEmit for type checking.
  */
 export declare function runCheck(options: CommandOptions): Promise<void>;
+/**
+ * `timber schema sync` — scan filesystem for dynamic segments, diff against
+ * app/schema.ts, and append missing entries with type-appropriate codec defaults.
+ *
+ * See design/41-global-params.md §Auto-Scaffolding
+ */
+export declare function runSchema(args: string[]): Promise<void>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAaA,QAAA,MAAM,QAAQ,+CAAgD,CAAC;AAC/D,KAAK,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuBpD;AAID,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,YAAY,CAAC,EAAE,cAAc,MAAM,EAAE,YAAY,CAAC;IAClD,aAAa,CAAC,EAAE,cAAc,MAAM,EAAE,aAAa,CAAC;IACpD,OAAO,CAAC,EAAE,cAAc,MAAM,EAAE,OAAO,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,kBAAkB,EAAE,qBAAqB,GAAG,SAAS,GACpE,SAAS,GAAG,MAAM,CAKpB;AA2BD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBzF;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAaA,QAAA,MAAM,QAAQ,yDAA0D,CAAC;AACzE,KAAK,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuBpD;AAID,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,YAAY,CAAC,EAAE,cAAc,MAAM,EAAE,YAAY,CAAC;IAClD,aAAa,CAAC,EAAE,cAAc,MAAM,EAAE,aAAa,CAAC;IACpD,OAAO,CAAC,EAAE,cAAc,MAAM,EAAE,OAAO,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,kBAAkB,EAAE,qBAAqB,GAAG,SAAS,GACpE,SAAS,GAAG,MAAM,CAKpB;AA6BD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBzF;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE;AAID;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA6C7D"}

package/dist/cli.js

@@ -4,14 +4,15 @@ var COMMANDS = [
 	"dev",
 	"build",
 	"preview",
-	"check"
+	"check",
+	"schema"
 ];
 /**
 * Parse CLI arguments into a structured command + options.
 * Accepts: timber <command> [--config|-c <path>]
 */
 function parseArgs(args) {
-	if (args.length === 0) throw new Error("No command provided. Usage: timber <dev|build|preview|check> [--config <path>]");
+	if (args.length === 0) throw new Error("No command provided. Usage: timber <dev|build|preview|check|schema> [--config <path>]");
 	const command = args[0];
 	if (!COMMANDS.includes(command)) throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(", ")}`);
 	let config;
@@ -26,7 +27,12 @@ function parseArgs(args) {
 }
 /**
 * Start the Vite dev server.
-* Middleware re-runs on file change via HMR wiring in timber-routing.
+*
+* The timber plugin binds the port immediately with a holding page
+* (in rootSync's config hook) so browsers see a "starting..." page
+* instead of ERR_CONNECTION_REFUSED during initialization.
+*
+* See design/21-dev-server.md, TIM-665.
 */
 async function runDev(options, _deps) {
 	const server = await (_deps?.createServer ?? (await import("vite")).createServer)({ configFile: options.config });
@@ -77,12 +83,12 @@ async function loadTimberConfig(root) {
 * Otherwise falls back to Vite's built-in preview server.
 */
 async function runPreview(options, _deps) {
-	const { join } = await import("node:path");
+	const { join, resolve } = await import("node:path");
 	const root = process.cwd();
 	const config = await loadTimberConfig(root).catch(() => null);
 	const adapter = config?.adapter;
 	if (resolvePreviewStrategy(adapter) === "adapter") {
-		const buildDir = join(root, "dist");
+		const buildDir = config?.buildDir ? resolve(root, config.buildDir) : join(root, ".timber", "dist");
 		const timberConfig = { output: config?.output ?? "server" };
 		await adapter.preview(timberConfig, buildDir);
 		return;
@@ -104,6 +110,39 @@ async function runCheck(options) {
 		});
 	});
 }
+/**
+* `timber schema sync` — scan filesystem for dynamic segments, diff against
+* app/schema.ts, and append missing entries with type-appropriate codec defaults.
+*
+* See design/41-global-params.md §Auto-Scaffolding
+*/
+async function runSchema(args) {
+	const subcommand = args[0];
+	if (subcommand !== "sync") throw new Error(`Unknown schema subcommand: ${subcommand ?? "(none)"}. Usage: timber schema sync`);
+	const { runSchemaSync, defaultCodecForSegment } = await import("./_chunks/cli-schema-sync-DH-M8Poy.js");
+	const result = runSchemaSync(process.cwd());
+	if (result.filesystemSegments.length === 0) {
+		console.log("[timber] No dynamic segments found in app/.");
+		return;
+	}
+	if (result.created) {
+		console.log(`[timber] Created app/schema.ts with ${result.addedSegments.length} segment(s):`);
+		for (const seg of result.addedSegments) console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);
+		return;
+	}
+	if (result.addedSegments.length === 0 && result.removedSegments.length === 0) {
+		console.log("[timber] Schema is up to date — all segments are registered.");
+		return;
+	}
+	if (result.addedSegments.length > 0) {
+		console.log(`[timber] Added ${result.addedSegments.length} segment(s) to app/schema.ts:`);
+		for (const seg of result.addedSegments) console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);
+	}
+	if (result.removedSegments.length > 0) {
+		console.log(`[timber] Removed ${result.removedSegments.length} stale segment(s) from app/schema.ts:`);
+		for (const seg of result.removedSegments) console.log(`  - ${seg}`);
+	}
+}
 async function main() {
 	const parsed = parseArgs(process.argv.slice(2));
 	const options = { config: parsed.config };
@@ -120,6 +159,9 @@ async function main() {
 		case "check":
 			await runCheck(options);
 			break;
+		case "schema":
+			await runSchema(process.argv.slice(3));
+			break;
 	}
 }
 if (typeof process !== "undefined" && process.argv[1] && (import.meta.url.endsWith(process.argv[1]) || process.argv[1].endsWith("bin/timber.mjs") || process.argv[1].endsWith("bin/timber"))) main().catch((err) => {
@@ -127,6 +169,6 @@ if (typeof process !== "undefined" && process.argv[1] && (import.meta.url.endsWi
 	process.exit(1);
 });
 //#endregion
-export { parseArgs, resolvePreviewStrategy, runBuild, runCheck, runDev, runPreview };
+export { parseArgs, resolvePreviewStrategy, runBuild, runCheck, runDev, runPreview, runSchema };
 
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n// timber.js CLI\n//\n// Wraps Vite commands with timber-specific behavior.\n// See design/18-build-system.md §\"CLI\".\n//\n// Commands:\n//   timber dev      — Start Vite dev server with HMR\n//   timber build    — Run multi-environment build via createBuilder/buildApp\n//   timber preview  — Serve the production build\n//   timber check    — Validate types + routes without building\n\nconst COMMANDS = ['dev', 'build', 'preview', 'check'] as const;\ntype Command = (typeof COMMANDS)[number];\n\nexport interface ParsedArgs {\n  command: Command;\n  config: string | undefined;\n}\n\nexport interface CommandOptions {\n  config?: string;\n}\n\n/**\n * Parse CLI arguments into a structured command + options.\n * Accepts: timber <command> [--config|-c <path>]\n */\nexport function parseArgs(args: string[]): ParsedArgs {\n  if (args.length === 0) {\n    throw new Error(\n      'No command provided. Usage: timber <dev|build|preview|check> [--config <path>]'\n    );\n  }\n\n  const command = args[0];\n  if (!COMMANDS.includes(command as Command)) {\n    throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(', ')}`);\n  }\n\n  let config: string | undefined;\n  for (let i = 1; i < args.length; i++) {\n    if (args[i] === '--config' || args[i] === '-c') {\n      config = args[++i];\n      if (!config) {\n        throw new Error('--config requires a path argument');\n      }\n    }\n  }\n\n  return { command: command as Command, config };\n}\n\n// ─── Command Implementations ─────────────────────────────────────────────────\n\n/** @internal Dependency injection for testing. */\nexport interface ViteDeps {\n  createServer?: typeof import('vite').createServer;\n  createBuilder?: typeof import('vite').createBuilder;\n  preview?: typeof import('vite').preview;\n}\n\n/**\n * Start the Vite dev server.\n * Middleware re-runs on file change via HMR wiring in timber-routing.\n */\nexport async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createServer = _deps?.createServer ?? (await import('vite')).createServer;\n  const server = await createServer({\n    configFile: options.config,\n  });\n  await server.listen();\n  server.printUrls();\n}\n\n/**\n * Run the production build using createBuilder + buildApp.\n * Direct build() calls do NOT trigger the RSC plugin's multi-environment\n * pipeline — createBuilder/buildApp is required.\n */\nexport async function runBuild(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createBuilder = _deps?.createBuilder ?? (await import('vite')).createBuilder;\n  const builder = await createBuilder({\n    configFile: options.config,\n  });\n  await builder.buildApp();\n}\n\n/**\n * Determine whether to use the adapter's preview or Vite's built-in preview.\n * Exported for testing — the actual runPreview function uses this internally.\n */\nexport function resolvePreviewStrategy(\n  adapter: import('./adapters/types').TimberPlatformAdapter | undefined\n): 'adapter' | 'vite' {\n  if (adapter && typeof adapter.preview === 'function') {\n    return 'adapter';\n  }\n  return 'vite';\n}\n\n/**\n * Load timber.config.ts from the project root.\n * Returns the config object with adapter, output, etc.\n * Returns null if no config file is found.\n */\nasync function loadTimberConfig(\n  root: string\n): Promise<{ adapter?: import('./adapters/types').TimberPlatformAdapter; output?: string } | null> {\n  const { existsSync } = await import('node:fs');\n  const { join } = await import('node:path');\n  const { pathToFileURL } = await import('node:url');\n\n  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];\n\n  for (const name of configNames) {\n    const configPath = join(root, name);\n    if (existsSync(configPath)) {\n      // Use Vite's built-in config loading to handle TypeScript\n      const mod = await import(pathToFileURL(configPath).href);\n      return mod.default ?? mod;\n    }\n  }\n  return null;\n}\n\n/**\n * Serve the production build for local testing.\n * If the adapter provides a preview() method, it takes priority.\n * Otherwise falls back to Vite's built-in preview server.\n */\nexport async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const { join } = await import('node:path');\n\n  // Try to load timber config for adapter-specific preview\n  const root = process.cwd();\n  const config = await loadTimberConfig(root).catch(() => null);\n  const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;\n\n  if (resolvePreviewStrategy(adapter) === 'adapter') {\n    const buildDir = join(root, 'dist');\n    const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };\n    await adapter!.preview!(timberConfig, buildDir);\n    return;\n  }\n\n  // Fallback: Vite's built-in preview server\n  const preview = _deps?.preview ?? (await import('vite')).preview;\n  const server = await preview({\n    configFile: options.config,\n  });\n  server.printUrls();\n}\n\n/**\n * Validate types and routes without producing build output.\n * Runs tsgo --noEmit for type checking.\n */\nexport async function runCheck(options: CommandOptions): Promise<void> {\n  const { execFile } = await import('node:child_process');\n\n  await new Promise<void>((resolve, reject) => {\n    const configArgs = options.config ? ['--project', options.config] : [];\n    execFile('tsgo', ['--noEmit', ...configArgs], (err, stdout, stderr) => {\n      if (stdout) process.stdout.write(stdout);\n      if (stderr) process.stderr.write(stderr);\n      if (err) {\n        reject(new Error(`Type check failed with exit code ${err.code}`));\n      } else {\n        resolve();\n      }\n    });\n  });\n}\n\n// ─── Main Entry Point ────────────────────────────────────────────────────────\n\nasync function main(): Promise<void> {\n  const parsed = parseArgs(process.argv.slice(2));\n  const options: CommandOptions = { config: parsed.config };\n\n  switch (parsed.command) {\n    case 'dev':\n      await runDev(options);\n      break;\n    case 'build':\n      await runBuild(options);\n      break;\n    case 'preview':\n      await runPreview(options);\n      break;\n    case 'check':\n      await runCheck(options);\n      break;\n  }\n}\n\n// Run main when executed as a CLI (not imported in tests).\n// The bin shim (bin/timber.mjs) does `import '../dist/cli.js'`, so\n// process.argv[1] points to the shim, not this file. We check both:\n// direct execution AND being imported by the timber bin shim.\nconst isDirectExecution =\n  typeof process !== 'undefined' &&\n  process.argv[1] &&\n  (import.meta.url.endsWith(process.argv[1]) ||\n    process.argv[1].endsWith('bin/timber.mjs') ||\n    process.argv[1].endsWith('bin/timber'));\n\nif (isDirectExecution) {\n  main().catch((err) => {\n    console.error(err.message);\n    process.exit(1);\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n// timber.js CLI\n//\n// Wraps Vite commands with timber-specific behavior.\n// See design/18-build-system.md §\"CLI\".\n//\n// Commands:\n//   timber dev      — Start Vite dev server with HMR\n//   timber build    — Run multi-environment build via createBuilder/buildApp\n//   timber preview  — Serve the production build\n//   timber check    — Validate types + routes without building\n\nconst COMMANDS = ['dev', 'build', 'preview', 'check', 'schema'] as const;\ntype Command = (typeof COMMANDS)[number];\n\nexport interface ParsedArgs {\n  command: Command;\n  config: string | undefined;\n}\n\nexport interface CommandOptions {\n  config?: string;\n}\n\n/**\n * Parse CLI arguments into a structured command + options.\n * Accepts: timber <command> [--config|-c <path>]\n */\nexport function parseArgs(args: string[]): ParsedArgs {\n  if (args.length === 0) {\n    throw new Error(\n      'No command provided. Usage: timber <dev|build|preview|check|schema> [--config <path>]'\n    );\n  }\n\n  const command = args[0];\n  if (!COMMANDS.includes(command as Command)) {\n    throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(', ')}`);\n  }\n\n  let config: string | undefined;\n  for (let i = 1; i < args.length; i++) {\n    if (args[i] === '--config' || args[i] === '-c') {\n      config = args[++i];\n      if (!config) {\n        throw new Error('--config requires a path argument');\n      }\n    }\n  }\n\n  return { command: command as Command, config };\n}\n\n// ─── Command Implementations ─────────────────────────────────────────────────\n\n/** @internal Dependency injection for testing. */\nexport interface ViteDeps {\n  createServer?: typeof import('vite').createServer;\n  createBuilder?: typeof import('vite').createBuilder;\n  preview?: typeof import('vite').preview;\n}\n\n/**\n * Start the Vite dev server.\n *\n * The timber plugin binds the port immediately with a holding page\n * (in rootSync's config hook) so browsers see a \"starting...\" page\n * instead of ERR_CONNECTION_REFUSED during initialization.\n *\n * See design/21-dev-server.md, TIM-665.\n */\nexport async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createServer = _deps?.createServer ?? (await import('vite')).createServer;\n  const server = await createServer({\n    configFile: options.config,\n  });\n  await server.listen();\n  server.printUrls();\n}\n\n/**\n * Run the production build using createBuilder + buildApp.\n * Direct build() calls do NOT trigger the RSC plugin's multi-environment\n * pipeline — createBuilder/buildApp is required.\n */\nexport async function runBuild(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createBuilder = _deps?.createBuilder ?? (await import('vite')).createBuilder;\n  const builder = await createBuilder({\n    configFile: options.config,\n  });\n  await builder.buildApp();\n}\n\n/**\n * Determine whether to use the adapter's preview or Vite's built-in preview.\n * Exported for testing — the actual runPreview function uses this internally.\n */\nexport function resolvePreviewStrategy(\n  adapter: import('./adapters/types').TimberPlatformAdapter | undefined\n): 'adapter' | 'vite' {\n  if (adapter && typeof adapter.preview === 'function') {\n    return 'adapter';\n  }\n  return 'vite';\n}\n\n/**\n * Load timber.config.ts from the project root.\n * Returns the config object with adapter, output, etc.\n * Returns null if no config file is found.\n */\nasync function loadTimberConfig(root: string): Promise<{\n  adapter?: import('./adapters/types').TimberPlatformAdapter;\n  output?: string;\n  buildDir?: string;\n} | null> {\n  const { existsSync } = await import('node:fs');\n  const { join } = await import('node:path');\n  const { pathToFileURL } = await import('node:url');\n\n  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];\n\n  for (const name of configNames) {\n    const configPath = join(root, name);\n    if (existsSync(configPath)) {\n      // Use Vite's built-in config loading to handle TypeScript\n      const mod = await import(pathToFileURL(configPath).href);\n      return mod.default ?? mod;\n    }\n  }\n  return null;\n}\n\n/**\n * Serve the production build for local testing.\n * If the adapter provides a preview() method, it takes priority.\n * Otherwise falls back to Vite's built-in preview server.\n */\nexport async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const { join, resolve } = await import('node:path');\n\n  // Try to load timber config for adapter-specific preview\n  const root = process.cwd();\n  const config = await loadTimberConfig(root).catch(() => null);\n  const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;\n\n  if (resolvePreviewStrategy(adapter) === 'adapter') {\n    // Resolve build directory: timber config > default .timber/dist\n    const buildDir = config?.buildDir\n      ? resolve(root, config.buildDir)\n      : join(root, '.timber', 'dist');\n    const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };\n    await adapter!.preview!(timberConfig, buildDir);\n    return;\n  }\n\n  // Fallback: Vite's built-in preview server\n  const preview = _deps?.preview ?? (await import('vite')).preview;\n  const server = await preview({\n    configFile: options.config,\n  });\n  server.printUrls();\n}\n\n/**\n * Validate types and routes without producing build output.\n * Runs tsgo --noEmit for type checking.\n */\nexport async function runCheck(options: CommandOptions): Promise<void> {\n  const { execFile } = await import('node:child_process');\n\n  await new Promise<void>((resolve, reject) => {\n    const configArgs = options.config ? ['--project', options.config] : [];\n    execFile('tsgo', ['--noEmit', ...configArgs], (err, stdout, stderr) => {\n      if (stdout) process.stdout.write(stdout);\n      if (stderr) process.stderr.write(stderr);\n      if (err) {\n        reject(new Error(`Type check failed with exit code ${err.code}`));\n      } else {\n        resolve();\n      }\n    });\n  });\n}\n\n// ─── Schema Subcommand ───────────────────────────────────────────────────────\n\n/**\n * `timber schema sync` — scan filesystem for dynamic segments, diff against\n * app/schema.ts, and append missing entries with type-appropriate codec defaults.\n *\n * See design/41-global-params.md §Auto-Scaffolding\n */\nexport async function runSchema(args: string[]): Promise<void> {\n  const subcommand = args[0];\n\n  if (subcommand !== 'sync') {\n    throw new Error(\n      `Unknown schema subcommand: ${subcommand ?? '(none)'}. Usage: timber schema sync`\n    );\n  }\n\n  const { runSchemaSync, defaultCodecForSegment } = await import('./cli-schema-sync.js');\n  const result = runSchemaSync(process.cwd());\n\n  if (result.filesystemSegments.length === 0) {\n    console.log('[timber] No dynamic segments found in app/.');\n    return;\n  }\n\n  if (result.created) {\n    console.log(`[timber] Created app/schema.ts with ${result.addedSegments.length} segment(s):`);\n    for (const seg of result.addedSegments) {\n      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);\n    }\n    return;\n  }\n\n  if (result.addedSegments.length === 0 && result.removedSegments.length === 0) {\n    console.log('[timber] Schema is up to date — all segments are registered.');\n    return;\n  }\n\n  if (result.addedSegments.length > 0) {\n    console.log(`[timber] Added ${result.addedSegments.length} segment(s) to app/schema.ts:`);\n    for (const seg of result.addedSegments) {\n      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);\n    }\n  }\n\n  if (result.removedSegments.length > 0) {\n    console.log(\n      `[timber] Removed ${result.removedSegments.length} stale segment(s) from app/schema.ts:`\n    );\n    for (const seg of result.removedSegments) {\n      console.log(`  - ${seg}`);\n    }\n  }\n}\n\n// ─── Main Entry Point ────────────────────────────────────────────────────────\n\nasync function main(): Promise<void> {\n  const parsed = parseArgs(process.argv.slice(2));\n  const options: CommandOptions = { config: parsed.config };\n\n  switch (parsed.command) {\n    case 'dev':\n      await runDev(options);\n      break;\n    case 'build':\n      await runBuild(options);\n      break;\n    case 'preview':\n      await runPreview(options);\n      break;\n    case 'check':\n      await runCheck(options);\n      break;\n    case 'schema':\n      await runSchema(process.argv.slice(3));\n      break;\n  }\n}\n\n// Run main when executed as a CLI (not imported in tests).\n// The bin shim (bin/timber.mjs) does `import '../dist/cli.js'`, so\n// process.argv[1] points to the shim, not this file. We check both:\n// direct execution AND being imported by the timber bin shim.\nconst isDirectExecution =\n  typeof process !== 'undefined' &&\n  process.argv[1] &&\n  (import.meta.url.endsWith(process.argv[1]) ||\n    process.argv[1].endsWith('bin/timber.mjs') ||\n    process.argv[1].endsWith('bin/timber'));\n\nif (isDirectExecution) {\n  main().catch((err) => {\n    console.error(err.message);\n    process.exit(1);\n  });\n}\n"],"mappings":"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"}

package/dist/client/browser-dev.d.ts

@@ -1,5 +1,6 @@
 /**
- * Dev-only browser helpers — server log replay and client error forwarding.
+ * Dev-only browser helpers — server log replay, client error forwarding,
+ * and compiling overlay.
  *
  * These are only active when import.meta.hot is available (Vite dev mode).
  * Extracted from browser-entry.ts to keep files under 500 lines.
@@ -18,6 +19,31 @@ export interface HotInterface {
  * a styled "[SERVER]" badge and call the matching console method.
  */
 export declare function setupServerLogReplay(hot: Pick<HotInterface, 'on'>): void;
+/**
+ * Signal that an HMR/module update has started.
+ *
+ * If an update is already tracked, this increments the counter.
+ * The overlay is shown after SHOW_DELAY_MS to avoid flashing
+ * for fast updates.
+ *
+ * When the delay is 0 (E2E test override), the overlay is shown
+ * synchronously to eliminate the race where hideCompilingOverlay()
+ * clears the show timeout before it fires.
+ */
+export declare function showCompilingOverlay(): void;
+/**
+ * Signal that an HMR/module update has completed.
+ *
+ * When all pending updates are resolved, the overlay is hidden.
+ * If the overlay was never shown (update completed within the
+ * debounce window), the timeout is cleared — no visual flash.
+ *
+ * Test hook: if `window.__timber_hold_compiling_overlay` is true,
+ * the overlay stays visible. E2E tests use this to avoid a race
+ * where the RSC refresh completes between polling intervals,
+ * making the overlay impossible to observe.
+ */
+export declare function hideCompilingOverlay(): void;
 /**
  * Set up global error handlers that forward uncaught client-side
  * errors to the dev server via Vite's HMR channel.
@@ -26,4 +52,11 @@ export declare function setupServerLogReplay(hot: Pick<HotInterface, 'on'>): voi
  * back as Vite '{ type: "error" }' payloads to trigger the overlay.
  */
 export declare function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): void;
+/**
+ * Detect errors whose `digest` marks them as a framework control-flow signal
+ * (RedirectSignal, DenySignal). These must never surface as dev overlays —
+ * they are expected during navigation and are handled by the error boundary
+ * and router. Exported for tests.
+ */
+export declare function isFrameworkSignalError(error: unknown): boolean;
 //# sourceMappingURL=browser-dev.d.ts.map

package/dist/client/browser-dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-dev.d.ts","sourceRoot":"","sources":["../../src/client/browser-dev.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAqDD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,GAAG,IAAI,CAwBxE;AAID;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,IAAI,CA8BhF"}
+{"version":3,"file":"browser-dev.d.ts","sourceRoot":"","sources":["../../src/client/browser-dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAqDD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,GAAG,IAAI,CAwBxE;AAoED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAmB3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAc3C;AAID;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,IAAI,CAoChF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAW9D"}

package/dist/client/browser-entry/action-dispatch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Server Action Dispatch — registers the callServer callback.
+ *
+ * When React encounters a server reference (from `'use server'` modules),
+ * it calls `callServer(id, args)` to dispatch the action to the server.
+ * The RSC plugin delegates to `globalThis.__viteRscCallServer` which is
+ * set by `setServerCallback`.
+ *
+ * The callback:
+ * 1. Serializes args via `encodeReply` (RSC wire format)
+ * 2. POSTs to the current URL with `Accept: text/x-component`
+ * 3. Decodes the RSC response stream
+ *
+ * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+ */
+export declare function setupServerActions(): void;
+//# sourceMappingURL=action-dispatch.d.ts.map

package/dist/client/browser-entry/action-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-dispatch.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/action-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,wBAAgB,kBAAkB,IAAI,IAAI,CAsGzC"}

package/dist/client/browser-entry/hmr.d.ts

@@ -0,0 +1,21 @@
+/**
+ * HMR & Dev Tooling — dev-only wiring for hot module replacement.
+ *
+ * Handles:
+ * - RSC module invalidation (rsc:update → router.refresh())
+ * - Dev warnings forwarded from server via WebSocket
+ * - Server console log replay in browser
+ * - Client error forwarding to Vite error overlay
+ *
+ * See design/21-dev-server.md §"HMR Wiring"
+ */
+import type { RouterInstance } from '#client-internal';
+/**
+ * Set up HMR and dev tool integration.
+ *
+ * Reads `import.meta.hot` to register dev-only event listeners.
+ * In production builds, `import.meta.hot` is undefined and this
+ * function is a no-op.
+ */
+export declare function setupHmr(router: RouterInstance): void;
+//# sourceMappingURL=hmr.d.ts.map

package/dist/client/browser-entry/hmr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmr.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/hmr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAavD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAgDrD"}

package/dist/client/browser-entry/hydrate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Hydration — pre-hydration sequence and React root creation.
+ *
+ * Handles two paths:
+ * 1. RSC payload available: hydrateRoot with NavigationProvider wrapping
+ * 2. No RSC payload: deferred root creation via installDeferredNavigation
+ *
+ * Pre-hydration ordering contract (MUST execute in this order):
+ *   1. initRouter()        — creates the global router so useRouter()
+ *                            works during render
+ *   2. setCurrentParams()  — populates params snapshot so
+ *      + setNavigationState()  useSegmentParams() and usePathname()
+ *                            return correct values during hydration
+ *   3. hydrateRoot()       — synchronously executes component render
+ *                            functions that depend on steps 1-2
+ *
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+import type { TopLoaderConfig } from '../top-loader.js';
+import type { RscStreamResult } from './rsc-stream.js';
+interface HydrateOptions {
+    /** RSC stream result (null if no inlined payload) */
+    rscResult: RscStreamResult | null;
+    /** Runtime config from virtual:timber-config */
+    config: {
+        topLoader?: TopLoaderConfig;
+    };
+}
+/**
+ * Run the pre-hydration sequence: read server-embedded params and
+ * set navigation state. Must be called AFTER initRouter().
+ */
+export declare function runPreHydration(): void;
+/**
+ * Hydrate the React tree or set up deferred root creation.
+ *
+ * When an RSC payload is available, wraps it with NavigationProvider +
+ * TimberNuqsAdapter + NavigationRoot and calls hydrateRoot on the
+ * document.
+ *
+ * When no RSC payload is available (JS-only client), sets up deferred
+ * navigation so the first client navigation creates the React root.
+ */
+export declare function hydrateApp({ rscResult, config }: HydrateOptions): void;
+export {};
+//# sourceMappingURL=hydrate.d.ts.map

package/dist/client/browser-entry/hydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAcH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,UAAU,cAAc;IACtB,qDAAqD;IACrD,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,gDAAgD;IAChD,MAAM,EAAE;QAAE,SAAS,CAAC,EAAE,eAAe,CAAA;KAAE,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAiBtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,IAAI,CA6EtE"}