@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.200

package/src/utils/state-machine.ts

@@ -0,0 +1,111 @@
+/**
+ * Tiny typed state machine utility.
+ *
+ * Enforces discriminated-union states, typed transitions with runtime
+ * guards, subscribe for external store integration, and assertPhase
+ * for function entry guards.
+ *
+ * Designed for 3–5 state consumers (stream transforms, client navigation,
+ * build phase sequencing). No async, no hierarchy, no history.
+ *
+ * Performance: send() is one object lookup + one function call.
+ * Equivalent cost to a boolean check after V8 inlining.
+ */
+
+/** A state machine instance with typed state and events. */
+export interface Machine<TState extends { phase: string }, TEvent extends { type: string }> {
+  /** Current state (discriminated union — narrowed by phase). */
+  readonly state: TState;
+
+  /** Transition with runtime guard. Throws on invalid source+event pair. */
+  send(event: TEvent): void;
+
+  /** Subscribe to state changes. Returns unsubscribe function. */
+  subscribe(listener: (state: TState) => void): () => void;
+
+  /** Throw if not in the expected phase. Entry guard for functions. */
+  assertPhase<P extends TState['phase']>(phase: P): void;
+}
+
+/**
+ * Transition map: `transitions[phase][eventType]` returns the next state.
+ *
+ * Each handler receives the current state (narrowed by phase context)
+ * and the event, returning the new state.
+ */
+export type TransitionMap<TState extends { phase: string }, TEvent extends { type: string }> = {
+  [P in TState['phase']]?: {
+    [E in TEvent['type']]?: (
+      state: Extract<TState, { phase: P }>,
+      event: Extract<TEvent, { type: E }>
+    ) => TState;
+  };
+};
+
+export interface MachineConfig<TState extends { phase: string }, TEvent extends { type: string }> {
+  initial: TState;
+  transitions: TransitionMap<TState, TEvent>;
+  /** Fires after every valid transition. Use for side effects. */
+  onTransition?: (prev: TState, next: TState, event: TEvent) => void;
+}
+
+/**
+ * Create a state machine from a config.
+ *
+ * @example
+ * ```ts
+ * type State = { phase: 'idle' } | { phase: 'running'; pid: number };
+ * type Event = { type: 'START'; pid: number } | { type: 'STOP' };
+ *
+ * const m = createMachine<State, Event>({
+ *   initial: { phase: 'idle' },
+ *   transitions: {
+ *     idle: { START: (_s, e) => ({ phase: 'running', pid: e.pid }) },
+ *     running: { STOP: () => ({ phase: 'idle' }) },
+ *   },
+ * });
+ * ```
+ */
+export function createMachine<TState extends { phase: string }, TEvent extends { type: string }>(
+  config: MachineConfig<TState, TEvent>
+): Machine<TState, TEvent> {
+  let current: TState = config.initial;
+  const listeners = new Set<(state: TState) => void>();
+
+  return {
+    get state() {
+      return current;
+    },
+
+    send(event: TEvent): void {
+      const phaseHandlers = config.transitions[current.phase as TState['phase']];
+      const handler = phaseHandlers?.[event.type as TEvent['type']] as
+        | ((state: TState, event: TEvent) => TState)
+        | undefined;
+
+      if (!handler) {
+        throw new Error(`[state-machine] Invalid transition: ${current.phase} + ${event.type}`);
+      }
+
+      const prev = current;
+      current = handler(prev, event);
+
+      config.onTransition?.(prev, current, event);
+
+      for (const listener of listeners) {
+        listener(current);
+      }
+    },
+
+    subscribe(listener: (state: TState) => void): () => void {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    assertPhase<P extends TState['phase']>(phase: P): void {
+      if (current.phase !== phase) {
+        throw new Error(`[state-machine] Expected phase "${phase}", got "${current.phase}"`);
+      }
+    },
+  };
+}

package/dist/_chunks/als-registry-B7DbZ2hS.js

@@ -1,41 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-//#region src/server/als-registry.ts
-/**
-* Centralized AsyncLocalStorage registry for server-side per-request state.
-*
-* ALL ALS instances used by the server framework live here. Individual
-* modules (request-context.ts, tracing.ts, actions.ts, etc.) import from
-* this registry and re-export public accessor functions.
-*
-* Why: ALS instances require singleton semantics — if two copies of the
-* same ALS exist (one from a relative import, one from a barrel import),
-* one module writes to its copy and another reads from an empty copy.
-* Centralizing ALS creation in a single module eliminates this class of bug.
-*
-* The `timber-shims` plugin ensures `@timber-js/app/server` resolves to
-* src/ in RSC and SSR environments, so all import paths converge here.
-*
-* DO NOT create ALS instances outside this file. If you need a new ALS,
-* add it here and import from `./als-registry.js` in the consuming module.
-*
-* See design/18-build-system.md §"Module Singleton Strategy" and
-* §"Singleton State Registry".
-*/
-/** @internal — import via request-context.ts public API */
-var requestContextAls = new AsyncLocalStorage();
-/** @internal — import via tracing.ts public API */
-var traceAls = new AsyncLocalStorage();
-/** @internal — import via server-timing.ts public API */
-var timingAls = new AsyncLocalStorage();
-/** @internal — import via actions.ts public API */
-var revalidationAls = new AsyncLocalStorage();
-/** @internal — import via form-flash.ts public API */
-var formFlashAls = new AsyncLocalStorage();
-/** @internal — import via early-hints-sender.ts public API */
-var earlyHintsSenderAls = new AsyncLocalStorage();
-/** @internal — import via waituntil-bridge.ts public API */
-var waitUntilAls = new AsyncLocalStorage();
-//#endregion
-export { timingAls as a, revalidationAls as i, formFlashAls as n, traceAls as o, requestContextAls as r, waitUntilAls as s, earlyHintsSenderAls as t };
-
-//# sourceMappingURL=als-registry-B7DbZ2hS.js.map

package/dist/_chunks/als-registry-B7DbZ2hS.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"als-registry-B7DbZ2hS.js","names":[],"sources":["../../src/server/als-registry.ts"],"sourcesContent":["/**\n * Centralized AsyncLocalStorage registry for server-side per-request state.\n *\n * ALL ALS instances used by the server framework live here. Individual\n * modules (request-context.ts, tracing.ts, actions.ts, etc.) import from\n * this registry and re-export public accessor functions.\n *\n * Why: ALS instances require singleton semantics — if two copies of the\n * same ALS exist (one from a relative import, one from a barrel import),\n * one module writes to its copy and another reads from an empty copy.\n * Centralizing ALS creation in a single module eliminates this class of bug.\n *\n * The `timber-shims` plugin ensures `@timber-js/app/server` resolves to\n * src/ in RSC and SSR environments, so all import paths converge here.\n *\n * DO NOT create ALS instances outside this file. If you need a new ALS,\n * add it here and import from `./als-registry.js` in the consuming module.\n *\n * See design/18-build-system.md §\"Module Singleton Strategy\" and\n * §\"Singleton State Registry\".\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\n// ─── Request Context ──────────────────────────────────────────────────────\n// Used by: request-context.ts (headers(), cookies(), searchParams())\n// Design doc: design/04-authorization.md\n\n/** @internal — import via request-context.ts public API */\nexport const requestContextAls = new AsyncLocalStorage<RequestContextStore>();\n\nexport interface RequestContextStore {\n  /** Incoming request headers (read-only view). */\n  headers: Headers;\n  /** Raw cookie header string, parsed lazily into a Map on first access. */\n  cookieHeader: string;\n  /** Lazily-parsed cookie map (mutable — reflects write-overlay from set()). */\n  parsedCookies?: Map<string, string>;\n  /** Original (pre-overlay) frozen headers, kept for overlay merging. */\n  originalHeaders: Headers;\n  /**\n   * Promise resolving to the route's typed search params (when search-params.ts\n   * exists) or to the raw URLSearchParams. Stored as a Promise so the framework\n   * can later support partial pre-rendering where param resolution is deferred.\n   */\n  searchParamsPromise: Promise<URLSearchParams | Record<string, unknown>>;\n  /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */\n  cookieJar: Map<string, CookieEntry>;\n  /** Whether the response has flushed (headers committed). */\n  flushed: boolean;\n  /** Whether the current context allows cookie mutation. */\n  mutableContext: boolean;\n}\n\n/** A single outgoing cookie entry in the cookie jar. */\nexport interface CookieEntry {\n  name: string;\n  value: string;\n  options: import('./request-context.js').CookieOptions;\n}\n\n// ─── Tracing ──────────────────────────────────────────────────────────────\n// Used by: tracing.ts (traceId(), spanId())\n// Design doc: design/17-logging.md\n\nexport interface TraceStore {\n  /** 32-char lowercase hex trace ID (OTEL or UUID fallback). */\n  traceId: string;\n  /** OTEL span ID if available, undefined otherwise. */\n  spanId?: string;\n}\n\n/** @internal — import via tracing.ts public API */\nexport const traceAls = new AsyncLocalStorage<TraceStore>();\n\n// ─── Server-Timing ────────────────────────────────────────────────────────\n// Used by: server-timing.ts (recordTiming(), withTiming())\n// Design doc: (dev-only performance instrumentation)\n\nexport interface TimingStore {\n  entries: import('./server-timing.js').TimingEntry[];\n}\n\n/** @internal — import via server-timing.ts public API */\nexport const timingAls = new AsyncLocalStorage<TimingStore>();\n\n// ─── Revalidation ─────────────────────────────────────────────────────────\n// Used by: actions.ts (revalidatePath(), revalidateTag())\n// Design doc: design/08-forms-and-actions.md\n\nexport interface RevalidationState {\n  /** Paths to re-render (populated by revalidatePath calls). */\n  paths: string[];\n  /** Tags to invalidate (populated by revalidateTag calls). */\n  tags: string[];\n}\n\n/** @internal — import via actions.ts public API */\nexport const revalidationAls = new AsyncLocalStorage<RevalidationState>();\n\n// ─── Form Flash ───────────────────────────────────────────────────────────\n// Used by: form-flash.ts (getFormFlash())\n// Design doc: design/08-forms-and-actions.md §\"No-JS Error Round-Trip\"\n\n/** @internal — import via form-flash.ts public API */\nexport const formFlashAls = new AsyncLocalStorage<import('./form-flash.js').FormFlashData>();\n\n// ─── Early Hints Sender ──────────────────────────────────────────────────\n// Used by: early-hints-sender.ts (sendEarlyHints103())\n// Design doc: design/02-rendering-pipeline.md §\"Early Hints (103)\"\n\n/** Function that sends Link header values as a 103 Early Hints response. */\nexport type EarlyHintsSenderFn = (links: string[]) => void;\n\n/** @internal — import via early-hints-sender.ts public API */\nexport const earlyHintsSenderAls = new AsyncLocalStorage<EarlyHintsSenderFn>();\n\n// ─── waitUntil Bridge ────────────────────────────────────────────────────\n// Used by: waituntil-bridge.ts (waitUntil())\n// Design doc: design/11-platform.md §\"waitUntil()\"\n\n/** Function that extends the request lifecycle with a background promise. */\nexport type WaitUntilFn = (promise: Promise<unknown>) => void;\n\n/** @internal — import via waituntil-bridge.ts public API */\nexport const waitUntilAls = new AsyncLocalStorage<WaitUntilFn>();\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAa,oBAAoB,IAAI,mBAAwC;;AA4C7E,IAAa,WAAW,IAAI,mBAA+B;;AAW3D,IAAa,YAAY,IAAI,mBAAgC;;AAc7D,IAAa,kBAAkB,IAAI,mBAAsC;;AAOzE,IAAa,eAAe,IAAI,mBAA4D;;AAU5F,IAAa,sBAAsB,IAAI,mBAAuC;;AAU9E,IAAa,eAAe,IAAI,mBAAgC"}

package/dist/_chunks/debug-B3Gypr3D.js

@@ -1,108 +0,0 @@
-//#region src/server/debug.ts
-/**
-* Runtime debug flag for timber.js.
-*
-* Two distinct functions for two distinct security levels:
-*
-* ## `isDebug()` — server-side logging only
-*
-* Returns true when timber's debug/warning messages should be written to
-* stderr / the server console. This NEVER affects what is sent to the
-* client (no error details, no timing headers, no stack traces).
-*
-* Active when any of:
-* - `NODE_ENV !== 'production'` (standard dev mode)
-* - `TIMBER_DEBUG` env var is set to a truthy value at runtime
-* - `timber.config.ts` has `debug: true`
-*
-* ## `isDevMode()` — client-visible dev behavior
-*
-* Returns true ONLY when `NODE_ENV !== 'production'`. This gates anything
-* that changes what clients can observe:
-* - Dev error pages with stack traces (fallback-error.ts)
-* - Detailed Server-Timing headers (pipeline.ts)
-* - Error messages in action INTERNAL_ERROR payloads (action-client.ts)
-* - Pipeline error handler wiring (Vite overlay)
-*
-* `isDevMode()` is statically replaced in production builds → the guarded
-* code is tree-shaken to zero bytes. TIMBER_DEBUG cannot enable it.
-*
-* Usage:
-*   In Cloudflare Workers wrangler.toml:
-*     [vars]
-*     TIMBER_DEBUG = "1"
-*
-*   In Node.js:
-*     TIMBER_DEBUG=1 node server.js
-*
-*   In timber.config.ts:
-*     export default { debug: true }
-*
-* See design/13-security.md for the security taxonomy.
-* See design/18-build-system.md for build pipeline details.
-*/
-/**
-* Check if the application is running in development mode.
-*
-* This is the ONLY function that should gate client-visible dev behavior:
-* - Dev error pages with stack traces
-* - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
-* - Error messages in action `INTERNAL_ERROR` payloads
-* - Pipeline error handler wiring (Vite overlay)
-*
-* Returns `process.env.NODE_ENV !== 'production'`, which is statically
-* replaced by the bundler in production builds. Code guarded by this
-* function is tree-shaken to zero bytes in production.
-*
-* TIMBER_DEBUG does NOT enable this — that would leak server internals
-* to clients. Use `isDebug()` for server-side-only logging.
-*/
-function isDevMode() {
-	return process.env.NODE_ENV !== "production";
-}
-/**
-* Config-level debug override. Set via `setDebugFromConfig()` during
-* initialization when timber.config.ts has `debug: true`.
-*/
-var _configDebug = false;
-/**
-* Check if timber debug logging is active (server-side only).
-*
-* Returns true if ANY of these conditions hold:
-* - NODE_ENV is not 'production' (standard dev mode)
-* - TIMBER_DEBUG environment variable is set to a truthy value at runtime
-* - timber.config.ts has `debug: true`
-*
-* This function controls ONLY server-side logging — messages written to
-* stderr or the server console. It NEVER affects client-visible behavior
-* (error pages, response headers, action payloads). For client-visible
-* behavior, use `isDevMode()`.
-*
-* The TIMBER_DEBUG check is deliberately written as a dynamic property
-* access so bundlers cannot statically replace it.
-*/
-function isDebug() {
-	if (process.env.NODE_ENV !== "production") return true;
-	if (_configDebug) return true;
-	return _readTimberDebugEnv();
-}
-/**
-* Read TIMBER_DEBUG from the environment at runtime.
-*
-* Extracted to a separate function to:
-* 1. Prevent bundler inlining (cross-module function calls are not inlined)
-* 2. Handle platforms where `process` may not exist (Cloudflare Workers)
-* 3. Support globalThis.__TIMBER_DEBUG for programmatic control
-*/
-function _readTimberDebugEnv() {
-	if (globalThis.__TIMBER_DEBUG) return true;
-	try {
-		const val = typeof process !== "undefined" && process.env ? process.env["TIMBER_DEBUG"] : void 0;
-		if (val && val !== "0" && val !== "false") return true;
-	} catch {}
-	return false;
-}
-//#endregion
-export { isDevMode as n, isDebug as t };
-
-//# sourceMappingURL=debug-B3Gypr3D.js.map

package/dist/_chunks/debug-B3Gypr3D.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"debug-B3Gypr3D.js","names":[],"sources":["../../src/server/debug.ts"],"sourcesContent":["/**\n * Runtime debug flag for timber.js.\n *\n * Two distinct functions for two distinct security levels:\n *\n * ## `isDebug()` — server-side logging only\n *\n * Returns true when timber's debug/warning messages should be written to\n * stderr / the server console. This NEVER affects what is sent to the\n * client (no error details, no timing headers, no stack traces).\n *\n * Active when any of:\n * - `NODE_ENV !== 'production'` (standard dev mode)\n * - `TIMBER_DEBUG` env var is set to a truthy value at runtime\n * - `timber.config.ts` has `debug: true`\n *\n * ## `isDevMode()` — client-visible dev behavior\n *\n * Returns true ONLY when `NODE_ENV !== 'production'`. This gates anything\n * that changes what clients can observe:\n * - Dev error pages with stack traces (fallback-error.ts)\n * - Detailed Server-Timing headers (pipeline.ts)\n * - Error messages in action INTERNAL_ERROR payloads (action-client.ts)\n * - Pipeline error handler wiring (Vite overlay)\n *\n * `isDevMode()` is statically replaced in production builds → the guarded\n * code is tree-shaken to zero bytes. TIMBER_DEBUG cannot enable it.\n *\n * Usage:\n *   In Cloudflare Workers wrangler.toml:\n *     [vars]\n *     TIMBER_DEBUG = \"1\"\n *\n *   In Node.js:\n *     TIMBER_DEBUG=1 node server.js\n *\n *   In timber.config.ts:\n *     export default { debug: true }\n *\n * See design/13-security.md for the security taxonomy.\n * See design/18-build-system.md for build pipeline details.\n */\n\n// ─── Dev Mode (client-visible) ──────────────────────────────────────────────\n\n/**\n * Check if the application is running in development mode.\n *\n * This is the ONLY function that should gate client-visible dev behavior:\n * - Dev error pages with stack traces\n * - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)\n * - Error messages in action `INTERNAL_ERROR` payloads\n * - Pipeline error handler wiring (Vite overlay)\n *\n * Returns `process.env.NODE_ENV !== 'production'`, which is statically\n * replaced by the bundler in production builds. Code guarded by this\n * function is tree-shaken to zero bytes in production.\n *\n * TIMBER_DEBUG does NOT enable this — that would leak server internals\n * to clients. Use `isDebug()` for server-side-only logging.\n */\nexport function isDevMode(): boolean {\n  return process.env.NODE_ENV !== 'production';\n}\n\n// ─── Debug Flag (server-side logging only) ──────────────────────────────────\n\n/**\n * Config-level debug override. Set via `setDebugFromConfig()` during\n * initialization when timber.config.ts has `debug: true`.\n */\nlet _configDebug = false;\n\n/**\n * Set the debug flag from timber.config.ts.\n * Called during handler initialization.\n */\nexport function setDebugFromConfig(debug: boolean): void {\n  _configDebug = debug;\n}\n\n/**\n * Check if timber debug logging is active (server-side only).\n *\n * Returns true if ANY of these conditions hold:\n * - NODE_ENV is not 'production' (standard dev mode)\n * - TIMBER_DEBUG environment variable is set to a truthy value at runtime\n * - timber.config.ts has `debug: true`\n *\n * This function controls ONLY server-side logging — messages written to\n * stderr or the server console. It NEVER affects client-visible behavior\n * (error pages, response headers, action payloads). For client-visible\n * behavior, use `isDevMode()`.\n *\n * The TIMBER_DEBUG check is deliberately written as a dynamic property\n * access so bundlers cannot statically replace it.\n */\nexport function isDebug(): boolean {\n  // Fast path: dev mode (statically replaced to `true` in dev, `false` in prod)\n  if (process.env.NODE_ENV !== 'production') return true;\n\n  // Config override\n  if (_configDebug) return true;\n\n  // Runtime env var check — uses dynamic access to prevent static replacement.\n  // In production builds, process.env.NODE_ENV is statically replaced, but\n  // TIMBER_DEBUG must survive as a runtime check. The dynamic key access\n  // pattern ensures the bundler treats this as opaque.\n  return _readTimberDebugEnv();\n}\n\n/**\n * Read TIMBER_DEBUG from the environment at runtime.\n *\n * Extracted to a separate function to:\n * 1. Prevent bundler inlining (cross-module function calls are not inlined)\n * 2. Handle platforms where `process` may not exist (Cloudflare Workers)\n * 3. Support globalThis.__TIMBER_DEBUG for programmatic control\n */\nfunction _readTimberDebugEnv(): boolean {\n  // globalThis override — useful for programmatic control and testing\n  if ((globalThis as Record<string, unknown>).__TIMBER_DEBUG) return true;\n\n  // process.env — works in Node.js and platforms that polyfill process\n  try {\n    const key = 'TIMBER_DEBUG';\n    const val =\n      typeof process !== 'undefined' && process.env\n        ? (process.env as Record<string, string | undefined>)[key]\n        : undefined;\n    if (val && val !== '0' && val !== 'false') return true;\n  } catch {\n    // process may not exist or env may throw — safe to ignore\n  }\n\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,SAAgB,YAAqB;AACnC,QAAA,QAAA,IAAA,aAAgC;;;;;;AASlC,IAAI,eAAe;;;;;;;;;;;;;;;;;AA0BnB,SAAgB,UAAmB;AAEjC,KAAA,QAAA,IAAA,aAA6B,aAAc,QAAO;AAGlD,KAAI,aAAc,QAAO;AAMzB,QAAO,qBAAqB;;;;;;;;;;AAW9B,SAAS,sBAA+B;AAEtC,KAAK,WAAuC,eAAgB,QAAO;AAGnE,KAAI;EAEF,MAAM,MACJ,OAAO,YAAY,eAAe,QAAQ,MACrC,QAAQ,IAHH,kBAIN,KAAA;AACN,MAAI,OAAO,QAAQ,OAAO,QAAQ,QAAS,QAAO;SAC5C;AAIR,QAAO"}

package/dist/_chunks/format-RyoGQL74.js

@@ -1,164 +0,0 @@
-import { t as isDebug } from "./debug-B3Gypr3D.js";
-//#region src/server/dev-warnings.ts
-var WarningId = {
-	SUSPENSE_WRAPS_CHILDREN: "SUSPENSE_WRAPS_CHILDREN",
-	DENY_IN_SUSPENSE: "DENY_IN_SUSPENSE",
-	REDIRECT_IN_SUSPENSE: "REDIRECT_IN_SUSPENSE",
-	REDIRECT_IN_ACCESS: "REDIRECT_IN_ACCESS",
-	STATIC_REQUEST_API: "STATIC_REQUEST_API",
-	CACHE_REQUEST_PROPS: "CACHE_REQUEST_PROPS",
-	SLOW_SLOT_NO_SUSPENSE: "SLOW_SLOT_NO_SUSPENSE"
-};
-var _emitted = /* @__PURE__ */ new Set();
-/** Vite dev server for forwarding warnings to browser console. */
-var _viteServer = null;
-/**
-* Register the Vite dev server for browser console forwarding.
-* Called by timber-dev-server during configureServer.
-*/
-function setViteServer(server) {
-	_viteServer = server;
-}
-function isDev() {
-	return isDebug();
-}
-/**
-* Emit a warning only once per dedup key.
-*
-* Writes to stderr and forwards to browser console via Vite WebSocket.
-* Returns true if emitted (not deduplicated).
-*/
-function emitOnce(warningId, location, level, message) {
-	if (!isDev()) return false;
-	const dedupKey = `${warningId}:${location}`;
-	if (_emitted.has(dedupKey)) return false;
-	_emitted.add(dedupKey);
-	const prefix = level === "error" ? "\x1B[31m[timber]\x1B[0m" : "\x1B[33m[timber]\x1B[0m";
-	process.stderr.write(`${prefix} ${message}\n`);
-	if (_viteServer?.hot) _viteServer.hot.send("timber:dev-warning", {
-		warningId,
-		level,
-		message: `[timber] ${message}`
-	});
-	return true;
-}
-/**
-* Warn when a layout wraps {children} in <Suspense>.
-*
-* This defers the page content — the primary resource — behind a fallback.
-* The page's data fetches won't affect the HTTP status code because they
-* resolve after onShellReady. If the page calls deny(404), the status code
-* is already committed as 200.
-*
-* @param layoutFile - Relative path to the layout file (e.g., "app/(dashboard)/layout.tsx")
-*/
-function warnSuspenseWrappingChildren(layoutFile) {
-	emitOnce(WarningId.SUSPENSE_WRAPS_CHILDREN, layoutFile, "warn", `Layout at ${layoutFile} wraps {children} in <Suspense>. This prevents child pages from setting HTTP status codes. Use useNavigationPending() for loading states instead.`);
-}
-/**
-* Warn when deny() is called inside a Suspense boundary.
-*
-* After the shell has flushed and the status code is committed, deny()
-* cannot change the HTTP response. The signal will be caught by the nearest
-* error boundary instead of producing a correct status code.
-*
-* @param file - Relative path to the file
-* @param line - Line number where deny() was called
-*/
-function warnDenyInSuspense(file, line) {
-	const location = line ? `${file}:${line}` : file;
-	emitOnce(WarningId.DENY_IN_SUSPENSE, location, "error", `deny() called inside <Suspense> at ${location}. The HTTP status is already committed — this will trigger an error boundary with a 200 status. Move deny() outside <Suspense> for correct HTTP semantics.`);
-}
-/**
-* Warn when redirect() is called inside a Suspense boundary.
-*
-* This will perform a client-side navigation instead of an HTTP redirect.
-*
-* @param file - Relative path to the file
-* @param line - Line number where redirect() was called
-*/
-function warnRedirectInSuspense(file, line) {
-	const location = line ? `${file}:${line}` : file;
-	emitOnce(WarningId.REDIRECT_IN_SUSPENSE, location, "error", `redirect() called inside <Suspense> at ${location}. This will perform a client-side navigation instead of an HTTP redirect.`);
-}
-/**
-* Warn when redirect() is called in a slot's access.ts.
-*
-* Slots use deny() for graceful degradation. Redirecting from a slot would
-* redirect the entire page, breaking the contract that slot failure is
-* isolated to the slot.
-*
-* @param accessFile - Relative path to the access.ts file
-* @param line - Line number where redirect() was called
-*/
-function warnRedirectInAccess(accessFile, line) {
-	const location = line ? `${accessFile}:${line}` : accessFile;
-	emitOnce(WarningId.REDIRECT_IN_ACCESS, location, "error", `redirect() called in access.ts at ${location}. Only deny() is valid in slot access checks. Use deny() to block access or move redirect() to middleware.ts.`);
-}
-/**
-* Warn when cookies() or headers() is called during a static build.
-*
-* In output: 'static' mode, there is no per-request context — these APIs
-* read build-time values only. This is almost always a mistake.
-*
-* @param api - The dynamic API name ("cookies" or "headers")
-* @param file - Relative path to the file calling the API
-*/
-function warnStaticRequestApi(api, file) {
-	emitOnce(WarningId.STATIC_REQUEST_API, `${api}:${file}`, "error", `${api}() called during static generation of ${file}. Dynamic request APIs are not available during prerendering.`);
-}
-/**
-* Warn when a "use cache" component receives request-specific props.
-*
-* Cached components should not depend on per-request data — a userId or
-* sessionId in the props means the cache will either be ineffective
-* (key per user) or dangerous (serve one user's data to another).
-*
-* @param componentName - Name of the cached component
-* @param propName - Name of the suspicious prop
-* @param file - Relative path to the component file
-* @param line - Line number
-*/
-function warnCacheRequestProps(componentName, propName, file, line) {
-	const location = line ? `${file}:${line}` : file;
-	emitOnce(WarningId.CACHE_REQUEST_PROPS, `${componentName}:${propName}:${location}`, "warn", `Cached component ${componentName} receives prop "${propName}" which appears request-specific. Cached components should not depend on per-request data.`);
-}
-/**
-* Warn when a parallel slot resolves slowly without a <Suspense> wrapper.
-*
-* A slow slot without Suspense blocks onShellReady — and therefore the
-* status code commit — for the entire page. Wrapping it in <Suspense>
-* lets the shell flush without waiting for the slot.
-*
-* @param slotName - The slot name (e.g., "@admin")
-* @param durationMs - How long the slot took to resolve
-*/
-function warnSlowSlotWithoutSuspense(slotName, durationMs) {
-	emitOnce(WarningId.SLOW_SLOT_NO_SUSPENSE, slotName, "warn", `Slot ${slotName} resolved in ${durationMs}ms and is not wrapped in <Suspense>. Consider wrapping to avoid blocking the flush.`);
-}
-/** @deprecated Use warnStaticRequestApi instead */
-var warnDynamicApiInStaticBuild = warnStaticRequestApi;
-/** @deprecated Use warnRedirectInAccess instead */
-function warnRedirectInSlotAccess(slotName) {
-	warnRedirectInAccess(`${slotName}/access.ts`);
-}
-/** @deprecated Use warnDenyInSuspense / warnRedirectInSuspense instead */
-function warnDenyAfterFlush(signal) {
-	if (signal === "deny") warnDenyInSuspense("unknown");
-	else warnRedirectInSuspense("unknown");
-}
-//#endregion
-//#region src/utils/format.ts
-/**
-* Shared formatting utilities.
-*/
-/** Format a byte count as a human-readable string (e.g. "1.50 kB"). */
-function formatSize(bytes) {
-	if (bytes < 1024) return `${bytes} B`;
-	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} kB`;
-	return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
-}
-//#endregion
-export { warnDenyAfterFlush as a, warnRedirectInAccess as c, warnSlowSlotWithoutSuspense as d, warnStaticRequestApi as f, warnCacheRequestProps as i, warnRedirectInSlotAccess as l, WarningId as n, warnDenyInSuspense as o, warnSuspenseWrappingChildren as p, setViteServer as r, warnDynamicApiInStaticBuild as s, formatSize as t, warnRedirectInSuspense as u };
-
-//# sourceMappingURL=format-RyoGQL74.js.map

package/dist/_chunks/format-RyoGQL74.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"format-RyoGQL74.js","names":[],"sources":["../../src/server/dev-warnings.ts","../../src/utils/format.ts"],"sourcesContent":["/**\n * Dev-mode warnings for common timber.js misuse patterns.\n *\n * These fire in development only and are stripped from production builds.\n * Each warning targets a specific misuse identified during design review.\n *\n * Warnings are deduplicated by warningId:filePath:line so the same warning\n * is only emitted once per dev session (per unique source location).\n *\n * Warnings are written to stderr and, when a Vite dev server is available,\n * forwarded to the browser console via Vite's WebSocket.\n *\n * See design/21-dev-server.md §\"Dev-Mode Warnings\"\n * See design/11-platform.md §\"Dev Mode\"\n */\n\nimport type { ViteDevServer } from 'vite';\nimport { isDebug } from './debug.js';\n\n// ─── Warning IDs ───────────────────────────────────────────────────────────\n\nexport const WarningId = {\n  SUSPENSE_WRAPS_CHILDREN: 'SUSPENSE_WRAPS_CHILDREN',\n  DENY_IN_SUSPENSE: 'DENY_IN_SUSPENSE',\n  REDIRECT_IN_SUSPENSE: 'REDIRECT_IN_SUSPENSE',\n  REDIRECT_IN_ACCESS: 'REDIRECT_IN_ACCESS',\n  STATIC_REQUEST_API: 'STATIC_REQUEST_API',\n  CACHE_REQUEST_PROPS: 'CACHE_REQUEST_PROPS',\n  SLOW_SLOT_NO_SUSPENSE: 'SLOW_SLOT_NO_SUSPENSE',\n} as const;\n\nexport type WarningId = (typeof WarningId)[keyof typeof WarningId];\n\n// ─── Configuration ──────────────────────────────────────────────────────────\n\n/** Configuration for dev warning behavior. */\nexport interface DevWarningConfig {\n  /** Threshold in ms for \"slow slot\" warnings. Default: 200. */\n  slowSlotThresholdMs?: number;\n}\n\n// ─── Deduplication & Server ─────────────────────────────────────────────────\n\nconst _emitted = new Set<string>();\n\n/** Vite dev server for forwarding warnings to browser console. */\nlet _viteServer: ViteDevServer | null = null;\n\n/**\n * Register the Vite dev server for browser console forwarding.\n * Called by timber-dev-server during configureServer.\n */\nexport function setViteServer(server: ViteDevServer | null): void {\n  _viteServer = server;\n}\n\nfunction isDev(): boolean {\n  return isDebug();\n}\n\n/**\n * Emit a warning only once per dedup key.\n *\n * Writes to stderr and forwards to browser console via Vite WebSocket.\n * Returns true if emitted (not deduplicated).\n */\nfunction emitOnce(\n  warningId: WarningId,\n  location: string,\n  level: 'warn' | 'error',\n  message: string\n): boolean {\n  if (!isDev()) return false;\n\n  const dedupKey = `${warningId}:${location}`;\n  if (_emitted.has(dedupKey)) return false;\n  _emitted.add(dedupKey);\n\n  // Write to stderr\n  const prefix = level === 'error' ? '\\x1b[31m[timber]\\x1b[0m' : '\\x1b[33m[timber]\\x1b[0m';\n  process.stderr.write(`${prefix} ${message}\\n`);\n\n  // Forward to browser console via Vite WebSocket\n  if (_viteServer?.hot) {\n    _viteServer.hot.send('timber:dev-warning', {\n      warningId,\n      level,\n      message: `[timber] ${message}`,\n    });\n  }\n\n  return true;\n}\n\n// ─── Warning Functions ──────────────────────────────────────────────────────\n\n/**\n * Warn when a layout wraps {children} in <Suspense>.\n *\n * This defers the page content — the primary resource — behind a fallback.\n * The page's data fetches won't affect the HTTP status code because they\n * resolve after onShellReady. If the page calls deny(404), the status code\n * is already committed as 200.\n *\n * @param layoutFile - Relative path to the layout file (e.g., \"app/(dashboard)/layout.tsx\")\n */\nexport function warnSuspenseWrappingChildren(layoutFile: string): void {\n  emitOnce(\n    WarningId.SUSPENSE_WRAPS_CHILDREN,\n    layoutFile,\n    'warn',\n    `Layout at ${layoutFile} wraps {children} in <Suspense>. ` +\n      'This prevents child pages from setting HTTP status codes. ' +\n      'Use useNavigationPending() for loading states instead.'\n  );\n}\n\n/**\n * Warn when deny() is called inside a Suspense boundary.\n *\n * After the shell has flushed and the status code is committed, deny()\n * cannot change the HTTP response. The signal will be caught by the nearest\n * error boundary instead of producing a correct status code.\n *\n * @param file - Relative path to the file\n * @param line - Line number where deny() was called\n */\nexport function warnDenyInSuspense(file: string, line?: number): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.DENY_IN_SUSPENSE,\n    location,\n    'error',\n    `deny() called inside <Suspense> at ${location}. ` +\n      'The HTTP status is already committed — this will trigger an error boundary with a 200 status. ' +\n      'Move deny() outside <Suspense> for correct HTTP semantics.'\n  );\n}\n\n/**\n * Warn when redirect() is called inside a Suspense boundary.\n *\n * This will perform a client-side navigation instead of an HTTP redirect.\n *\n * @param file - Relative path to the file\n * @param line - Line number where redirect() was called\n */\nexport function warnRedirectInSuspense(file: string, line?: number): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.REDIRECT_IN_SUSPENSE,\n    location,\n    'error',\n    `redirect() called inside <Suspense> at ${location}. ` +\n      'This will perform a client-side navigation instead of an HTTP redirect.'\n  );\n}\n\n/**\n * Warn when redirect() is called in a slot's access.ts.\n *\n * Slots use deny() for graceful degradation. Redirecting from a slot would\n * redirect the entire page, breaking the contract that slot failure is\n * isolated to the slot.\n *\n * @param accessFile - Relative path to the access.ts file\n * @param line - Line number where redirect() was called\n */\nexport function warnRedirectInAccess(accessFile: string, line?: number): void {\n  const location = line ? `${accessFile}:${line}` : accessFile;\n  emitOnce(\n    WarningId.REDIRECT_IN_ACCESS,\n    location,\n    'error',\n    `redirect() called in access.ts at ${location}. ` +\n      'Only deny() is valid in slot access checks. ' +\n      'Use deny() to block access or move redirect() to middleware.ts.'\n  );\n}\n\n/**\n * Warn when cookies() or headers() is called during a static build.\n *\n * In output: 'static' mode, there is no per-request context — these APIs\n * read build-time values only. This is almost always a mistake.\n *\n * @param api - The dynamic API name (\"cookies\" or \"headers\")\n * @param file - Relative path to the file calling the API\n */\nexport function warnStaticRequestApi(api: 'cookies' | 'headers', file: string): void {\n  emitOnce(\n    WarningId.STATIC_REQUEST_API,\n    `${api}:${file}`,\n    'error',\n    `${api}() called during static generation of ${file}. ` +\n      'Dynamic request APIs are not available during prerendering.'\n  );\n}\n\n/**\n * Warn when a \"use cache\" component receives request-specific props.\n *\n * Cached components should not depend on per-request data — a userId or\n * sessionId in the props means the cache will either be ineffective\n * (key per user) or dangerous (serve one user's data to another).\n *\n * @param componentName - Name of the cached component\n * @param propName - Name of the suspicious prop\n * @param file - Relative path to the component file\n * @param line - Line number\n */\nexport function warnCacheRequestProps(\n  componentName: string,\n  propName: string,\n  file: string,\n  line?: number\n): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.CACHE_REQUEST_PROPS,\n    `${componentName}:${propName}:${location}`,\n    'warn',\n    `Cached component ${componentName} receives prop \"${propName}\" which appears request-specific. ` +\n      'Cached components should not depend on per-request data.'\n  );\n}\n\n/**\n * Warn when a parallel slot resolves slowly without a <Suspense> wrapper.\n *\n * A slow slot without Suspense blocks onShellReady — and therefore the\n * status code commit — for the entire page. Wrapping it in <Suspense>\n * lets the shell flush without waiting for the slot.\n *\n * @param slotName - The slot name (e.g., \"@admin\")\n * @param durationMs - How long the slot took to resolve\n */\nexport function warnSlowSlotWithoutSuspense(slotName: string, durationMs: number): void {\n  emitOnce(\n    WarningId.SLOW_SLOT_NO_SUSPENSE,\n    slotName,\n    'warn',\n    `Slot ${slotName} resolved in ${durationMs}ms and is not wrapped in <Suspense>. ` +\n      'Consider wrapping to avoid blocking the flush.'\n  );\n}\n\n// ─── Legacy aliases ─────────────────────────────────────────────────────────\n\n/** @deprecated Use warnStaticRequestApi instead */\nexport const warnDynamicApiInStaticBuild = warnStaticRequestApi;\n\n/** @deprecated Use warnRedirectInAccess instead */\nexport function warnRedirectInSlotAccess(slotName: string): void {\n  warnRedirectInAccess(`${slotName}/access.ts`);\n}\n\n/** @deprecated Use warnDenyInSuspense / warnRedirectInSuspense instead */\nexport function warnDenyAfterFlush(signal: 'deny' | 'redirect'): void {\n  if (signal === 'deny') {\n    warnDenyInSuspense('unknown');\n  } else {\n    warnRedirectInSuspense('unknown');\n  }\n}\n\n// ─── Testing ────────────────────────────────────────────────────────────────\n\n/**\n * Reset emitted warnings. For testing only.\n * @internal\n */\nexport function _resetWarnings(): void {\n  _emitted.clear();\n}\n\n/**\n * Get the set of emitted dedup keys. For testing only.\n * @internal\n */\nexport function _getEmitted(): ReadonlySet<string> {\n  return _emitted;\n}\n","/**\n * Shared formatting utilities.\n */\n\n/** Format a byte count as a human-readable string (e.g. \"1.50 kB\"). */\nexport function formatSize(bytes: number): string {\n  if (bytes < 1024) return `${bytes} B`;\n  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} kB`;\n  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;\n}\n"],"mappings":";;AAqBA,IAAa,YAAY;CACvB,yBAAyB;CACzB,kBAAkB;CAClB,sBAAsB;CACtB,oBAAoB;CACpB,oBAAoB;CACpB,qBAAqB;CACrB,uBAAuB;CACxB;AAcD,IAAM,2BAAW,IAAI,KAAa;;AAGlC,IAAI,cAAoC;;;;;AAMxC,SAAgB,cAAc,QAAoC;AAChE,eAAc;;AAGhB,SAAS,QAAiB;AACxB,QAAO,SAAS;;;;;;;;AASlB,SAAS,SACP,WACA,UACA,OACA,SACS;AACT,KAAI,CAAC,OAAO,CAAE,QAAO;CAErB,MAAM,WAAW,GAAG,UAAU,GAAG;AACjC,KAAI,SAAS,IAAI,SAAS,CAAE,QAAO;AACnC,UAAS,IAAI,SAAS;CAGtB,MAAM,SAAS,UAAU,UAAU,4BAA4B;AAC/D,SAAQ,OAAO,MAAM,GAAG,OAAO,GAAG,QAAQ,IAAI;AAG9C,KAAI,aAAa,IACf,aAAY,IAAI,KAAK,sBAAsB;EACzC;EACA;EACA,SAAS,YAAY;EACtB,CAAC;AAGJ,QAAO;;;;;;;;;;;;AAeT,SAAgB,6BAA6B,YAA0B;AACrE,UACE,UAAU,yBACV,YACA,QACA,aAAa,WAAW,mJAGzB;;;;;;;;;;;;AAaH,SAAgB,mBAAmB,MAAc,MAAqB;CACpE,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,kBACV,UACA,SACA,sCAAsC,SAAS,4JAGhD;;;;;;;;;;AAWH,SAAgB,uBAAuB,MAAc,MAAqB;CACxE,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,sBACV,UACA,SACA,0CAA0C,SAAS,2EAEpD;;;;;;;;;;;;AAaH,SAAgB,qBAAqB,YAAoB,MAAqB;CAC5E,MAAM,WAAW,OAAO,GAAG,WAAW,GAAG,SAAS;AAClD,UACE,UAAU,oBACV,UACA,SACA,qCAAqC,SAAS,+GAG/C;;;;;;;;;;;AAYH,SAAgB,qBAAqB,KAA4B,MAAoB;AACnF,UACE,UAAU,oBACV,GAAG,IAAI,GAAG,QACV,SACA,GAAG,IAAI,wCAAwC,KAAK,+DAErD;;;;;;;;;;;;;;AAeH,SAAgB,sBACd,eACA,UACA,MACA,MACM;CACN,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,qBACV,GAAG,cAAc,GAAG,SAAS,GAAG,YAChC,QACA,oBAAoB,cAAc,kBAAkB,SAAS,4FAE9D;;;;;;;;;;;;AAaH,SAAgB,4BAA4B,UAAkB,YAA0B;AACtF,UACE,UAAU,uBACV,UACA,QACA,QAAQ,SAAS,eAAe,WAAW,qFAE5C;;;AAMH,IAAa,8BAA8B;;AAG3C,SAAgB,yBAAyB,UAAwB;AAC/D,sBAAqB,GAAG,SAAS,YAAY;;;AAI/C,SAAgB,mBAAmB,QAAmC;AACpE,KAAI,WAAW,OACb,oBAAmB,UAAU;KAE7B,wBAAuB,UAAU;;;;;;;;ACjQrC,SAAgB,WAAW,OAAuB;AAChD,KAAI,QAAQ,KAAM,QAAO,GAAG,MAAM;AAClC,KAAI,QAAQ,OAAO,KAAM,QAAO,IAAI,QAAQ,MAAM,QAAQ,EAAE,CAAC;AAC7D,QAAO,IAAI,SAAS,OAAO,OAAO,QAAQ,EAAE,CAAC"}