@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/shims/font-google.ts

@@ -17,7 +17,7 @@
  * Design doc: 24-fonts.md, "Next.js Font Compatibility"
  */
 
-import type { GoogleFontConfig, FontResult } from '#/fonts/types.js';
+import type { GoogleFontConfig, FontResult } from '../fonts/types.js';
 
 export type { GoogleFontConfig, FontResult };
 

package/src/shims/font-local.ts

@@ -0,0 +1,34 @@
+/**
+ * Fallback shim for `next/font/local` → `@timber/fonts/local`.
+ *
+ * At build time, the timber-fonts plugin's transform hook replaces
+ * `localFont()` calls with static FontResult objects containing real
+ * class names and font stacks. This file serves two purposes:
+ *
+ * 1. **TypeScript resolution** — provides types for IDEs and `tsc` outside
+ *    of Vite's module graph (where the virtual module handles it).
+ * 2. **Runtime fallback** — returns empty className/fontFamily values when
+ *    the plugin hasn't processed a call (e.g. in tests or non-Vite environments).
+ *
+ * Design doc: 24-fonts.md, "Next.js Font Compatibility"
+ */
+
+import type { LocalFontConfig, FontResult } from '../fonts/types.js';
+
+export type { LocalFontConfig, FontResult };
+
+/**
+ * Create a local font.
+ *
+ * The timber-fonts plugin replaces these calls at build time with real
+ * class names and font stacks. This stub ensures code that imports
+ * `localFont` outside of the build pipeline (tests, type-checking)
+ * gets a valid FontResult shape without runtime errors.
+ */
+export default function localFont(config?: LocalFontConfig): FontResult {
+  return {
+    className: '',
+    style: { fontFamily: '' },
+    variable: config?.variable,
+  };
+}

package/src/shims/headers.ts

@@ -4,6 +4,127 @@
  * Imports from @timber-js/app/server which Vite resolves to dist/server/index.js
  * via native package.json exports. This ensures the same ALS singleton as the
  * pipeline (both import from the same shared request-context chunk in dist/).
+ *
+ * `cookies()` is NOT a bare alias of `getCookieJar()`: Next.js's
+ * RequestCookies returns `{ name, value }` RequestCookie objects from
+ * `.get()`/`.getAll()`, while timber's native jar returns bare strings from
+ * `.get()`. Ecosystem libraries written against the real API use
+ * `(await cookies()).get('session')?.value` — with the bare-string shape
+ * that silently reads `undefined` off a string. The adapter below presents
+ * the Next shape while delegating every operation to the timber jar, so the
+ * encoding contract, cookie-octet validation, and mutable-context checks
+ * (design/29-cookies.md, ONGOING_SECURITY.md H-3) apply unchanged.
+ * See TIM-1042 and design/14-ecosystem.md §next/headers.
+ */
+
+import { getCookieJar } from '@timber-js/app/server';
+import type { CookieOptions, SetCookieOptions } from '@timber-js/app/server';
+
+// Re-export timber's primary API
+export { getHeaders, getCookieJar } from '@timber-js/app/server';
+
+// Next.js compat alias — libraries importing from 'next/headers' expect this name.
+export { getHeaders as headers } from '@timber-js/app/server';
+
+/** Next.js's request cookie shape: `cookies().get(name)` → `{ name, value }`. */
+export interface RequestCookie {
+  name: string;
+  value: string;
+}
+
+/** Next.js's `cookies().set()` options — `expires` may be a ms timestamp. */
+export interface NextCookieOptions extends Omit<SetCookieOptions, 'expires'> {
+  expires?: Date | number;
+}
+
+/** Next.js's object overload for `cookies().set({ name, value, ...options })`. */
+export interface NextCookieListItem extends NextCookieOptions {
+  name: string;
+  value: string;
+}
+
+/** Next.js's RequestCookies surface, backed by timber's cookie jar. */
+export interface NextRequestCookies {
+  get(name: string): RequestCookie | undefined;
+  get(cookie: RequestCookie): RequestCookie | undefined;
+  getAll(name?: string): RequestCookie[];
+  getAll(cookie: RequestCookie): RequestCookie[];
+  has(name: string): boolean;
+  readonly size: number;
+  set(name: string, value: string, options?: NextCookieOptions): void;
+  set(cookie: NextCookieListItem): void;
+  delete(name: string): void;
+  delete(cookie: { name: string } & Pick<CookieOptions, 'path' | 'domain'>): void;
+  [Symbol.iterator](): IterableIterator<[string, RequestCookie]>;
+  toString(): string;
+}
+
+/** Normalize Next's `expires?: Date | number` (ms timestamp) to timber's `Date`. */
+function normalizeOptions(options?: NextCookieOptions): SetCookieOptions | undefined {
+  if (!options) return undefined;
+  const { expires, ...rest } = options;
+  if (typeof expires === 'number') return { ...rest, expires: new Date(expires) };
+  return options as SetCookieOptions;
+}
+
+/**
+ * Next.js compat: `cookies()` returning the RequestCookies shape.
+ *
+ * Next.js 15 makes `cookies()` async; awaiting this sync return value works
+ * for both the `(await cookies()).get()` and legacy `cookies().get()` call
+ * styles, so libraries targeting either Next version resolve correctly.
  */
+export function cookies(): NextRequestCookies {
+  const jar = getCookieJar();
+
+  const toCookie = (name: string): RequestCookie | undefined => {
+    const value = jar.get(name);
+    return value === undefined ? undefined : { name, value };
+  };
 
-export { headers, cookies } from '@timber-js/app/server';
+  return {
+    get(nameOrCookie: string | RequestCookie): RequestCookie | undefined {
+      return toCookie(typeof nameOrCookie === 'string' ? nameOrCookie : nameOrCookie.name);
+    },
+    getAll(nameOrCookie?: string | RequestCookie): RequestCookie[] {
+      const all = jar.getAll();
+      if (nameOrCookie === undefined) return all;
+      const name = typeof nameOrCookie === 'string' ? nameOrCookie : nameOrCookie.name;
+      return all.filter((cookie) => cookie.name === name);
+    },
+    has(name: string): boolean {
+      return jar.has(name);
+    },
+    get size(): number {
+      return jar.size;
+    },
+    set(
+      nameOrCookie: string | NextCookieListItem,
+      value?: string,
+      options?: NextCookieOptions
+    ): void {
+      if (typeof nameOrCookie === 'string') {
+        jar.set(nameOrCookie, value as string, normalizeOptions(options));
+      } else {
+        const { name, value: cookieValue, ...objectOptions } = nameOrCookie;
+        jar.set(name, cookieValue, normalizeOptions(objectOptions));
+      }
+    },
+    delete(nameOrCookie: string | ({ name: string } & Pick<CookieOptions, 'path' | 'domain'>)) {
+      if (typeof nameOrCookie === 'string') {
+        jar.delete(nameOrCookie);
+      } else {
+        const { name, ...options } = nameOrCookie;
+        jar.delete(name, options);
+      }
+    },
+    *[Symbol.iterator](): IterableIterator<[string, RequestCookie]> {
+      for (const cookie of jar.getAll()) {
+        yield [cookie.name, cookie];
+      }
+    },
+    toString(): string {
+      return jar.toString();
+    },
+  };
+}

package/src/shims/navigation-client.ts

@@ -1,12 +1,19 @@
 /**
  * Shim: next/navigation (client environment only)
  *
- * Re-exports only the client-side hooks from timber's client API.
- * Server-only functions (redirect, notFound, etc.) are excluded to prevent
- * server/primitives.ts from being pulled into the browser bundle.
+ * Re-exports the client-side hooks from timber's client API, and implements
+ * client-render `redirect()` without pulling server/primitives.ts into the
+ * browser bundle.
+ *
+ * Next.js supports calling redirect() during client component render.
+ * timber matches that by throwing a plain Error carrying the same JSON
+ * digest the server pipeline attaches to RedirectSignal. TimberErrorBoundary
+ * recognizes the digest and converts it to an SPA navigation (replace
+ * semantics), and browser-dev's isFrameworkSignalError() keeps it out of
+ * the dev overlay.
  *
  * The full shim (navigation.ts) is still used in the RSC and SSR environments
- * where both client hooks and server functions are needed.
+ * where the real server primitives produce proper HTTP responses.
  *
  * Imports use @timber-js/app/client (not #/ subpath imports) so they resolve
  * to the same module instances as user code in Vite dev — preventing module
@@ -16,42 +23,39 @@
  * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
  */
 
-// Hooks — imported from the public barrel for module singleton consistency.
+import { assertRelativeRedirectPath } from '../shared/href-validation.js';
+import type { RedirectTypeValue } from '../shared/redirect-type.js';
+
+// Hooks — useSegmentParams and useSearchParams import from direct modules
+// since they're no longer in @timber-js/app/client public exports.
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.js';
+export { useSearchParams } from '../client/use-search-params.js';
 export {
-  useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,
 } from '@timber-js/app/client';
 
-// RedirectType enum is safe (no server code dependency) and used by some
-// client-side libraries for type checking.
-export const RedirectType = {
-  push: 'push',
-  replace: 'replace',
-} as const;
-
-// Server-only stubs — throw at runtime if called from the client.
-// These exist for type compatibility with libraries that import the types
-// but should never execute in the browser.
-export function redirect(): never {
-  throw new Error(
-    'redirect() is a server-only function and cannot be called from client components. ' +
-      'Use useRouter().push() or useRouter().replace() for client-side navigation.'
-  );
-}
+// Single source of truth shared with server/primitives.ts.
+export { RedirectType } from '../shared/redirect-type.js';
 
-export function permanentRedirect(): never {
-  throw new Error(
-    'permanentRedirect() is a server-only function and cannot be called from client components. ' +
-      'Use useRouter().push() or useRouter().replace() for client-side navigation.'
-  );
+/** Throw a plain Error carrying a framework signal digest. */
+function throwSignal(message: string, digest: Record<string, unknown>): never {
+  const err = new Error(message);
+  (err as Error & { digest?: string }).digest = JSON.stringify(digest);
+  throw err;
 }
 
-export function notFound(): never {
-  throw new Error(
-    'notFound() is a server-only function and cannot be called from client components.'
-  );
+/**
+ * Client-render redirect. Throws a redirect-digest error that the nearest
+ * TimberErrorBoundary converts into an SPA navigation (replace semantics).
+ *
+ * The optional RedirectType argument is accepted for Next.js API
+ * compatibility but ignored — timber always uses replace semantics,
+ * matching the server-side redirect().
+ */
+export function redirect(path: string, _type?: RedirectTypeValue): never {
+  assertRelativeRedirectPath(path);
+  throwSignal(`Redirect to ${path}`, { type: 'redirect', location: path, status: 302 });
 }

package/src/shims/navigation.ts

@@ -1,20 +1,23 @@
 /**
  * Shim: next/navigation → timber navigation primitives
  *
- * Client hooks import from @timber-js/app/client (the public barrel) so they
- * resolve to the same module instances as user code in Vite dev. Server
- * functions import from @timber-js/app/server for ALS singleton consistency.
+ * Client hooks import from their direct modules since useSegmentParams,
+ * useSearchParams, and useQueryStates are no longer part of
+ * @timber-js/app/client public exports (they live on define* factories).
+ * The shim re-exports them for next/navigation library compat (nuqs etc).
+ *
+ * Server functions import from @timber-js/app/server for ALS singleton consistency.
  */
 
-// Hooks (client-side — imported from public barrel for module singleton)
+// Hooks re-exported for next/navigation compat
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.js';
+export { useSearchParams } from '../client/use-search-params.js';
 export {
-  useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,
 } from '@timber-js/app/client';
 
 // Functions (server-side)
-export { redirect, permanentRedirect, notFound, RedirectType } from '@timber-js/app/server';
+export { redirect, redirectExternal, RedirectType } from '@timber-js/app/server';

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"}