@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.120

package/src/server/types.ts

@@ -22,8 +22,7 @@ export interface MiddlewareContext {
   req: Request;
   requestHeaders: Headers;
   headers: Headers;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
+  segmentParams: Record<string, string | string[]>;
   /** Declare early hints for critical resources. Appends Link headers. */
   earlyHints: (hints: EarlyHint[]) => void;
 }
@@ -35,10 +34,8 @@ export interface RouteContext {
   headers: Headers;
 }
 
-export interface AccessContext {
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
-}
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface AccessContext {}
 
 export interface Metadata {
   title?: string | { default?: string; template?: string; absolute?: string };
@@ -163,4 +160,56 @@ export namespace MetadataRoute {
     sitemap?: string | string[];
     host?: string;
   }
+  /**
+   * PWA Web App Manifest — serialized as `application/manifest+json`.
+   *
+   * Intentionally permissive: the manifest spec is large and evolving
+   * (W3C + browser-specific extensions). Users that want stricter typing
+   * can augment the return type with a library like `web-app-manifest`.
+   */
+  export type Manifest = Record<string, unknown>;
 }
+
+/**
+ * The value a dynamic metadata route handler may return.
+ *
+ * This is a structural union — the pipeline dispatches on the shape at
+ * request time (see `pipeline-phases.ts`):
+ *   - `Response` → returned as-is (e.g. `ImageResponse`, `Response.redirect()`).
+ *     Used by `icon.tsx`, `opengraph-image.tsx`, `twitter-image.tsx`,
+ *     `apple-icon.tsx`.
+ *   - `string` → written as the response body verbatim. Used by `robots.ts`
+ *     and by any handler that wants to emit a pre-serialized payload.
+ *   - `MetadataRoute.Sitemap` → serialized via the sitemap XML writer. Used
+ *     by `sitemap.ts`.
+ *   - `MetadataRoute.Manifest` → serialized via `JSON.stringify`. Used by
+ *     `manifest.ts`.
+ *
+ * See design/16-metadata.md §"Metadata Routes".
+ */
+export type MetadataResult = Response | string | MetadataRoute.Sitemap | MetadataRoute.Manifest;
+
+/**
+ * Default export signature for a dynamic metadata route file
+ * (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.tsx`,
+ * `opengraph-image.tsx`, `twitter-image.tsx`, `apple-icon.tsx`).
+ *
+ * Parameterize `TResult` to narrow the return type for a specific route:
+ *
+ * ```ts
+ * // app/sitemap.ts
+ * import type { MetadataHandler, MetadataRoute } from '@timber-js/app/server';
+ *
+ * const sitemap: MetadataHandler<MetadataRoute.Sitemap> = async () => [
+ *   { url: 'https://example.com/', changeFrequency: 'weekly', priority: 1 },
+ * ];
+ * export default sitemap;
+ * ```
+ *
+ * The handler is currently invoked with no arguments. Per-request context
+ * (`params`, `searchParams`, `Request`) is not yet wired through to metadata
+ * route handlers; when it is, this signature will grow a context parameter.
+ */
+export type MetadataHandler<TResult extends MetadataResult = MetadataResult> = () =>
+  | TResult
+  | Promise<TResult>;

package/src/server/utils/escape-html.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared HTML escaping utility.
+ *
+ * Used by both dev-only paths (error pages, 404 page) and production
+ * paths (deny-renderer, RSC helpers). Lives in server/utils/ because
+ * it's not dev-only.
+ */
+
+/**
+ * Escape a string for safe embedding in HTML content or attributes.
+ *
+ * Replaces `&`, `<`, `>`, and `"` with their HTML entity equivalents.
+ */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/src/server/version-skew.ts

@@ -0,0 +1,104 @@
+/**
+ * Version Skew Detection — graceful recovery when stale clients hit new deployments.
+ *
+ * When a new version of the app is deployed, clients with open tabs still have
+ * the old JavaScript bundle. Without version skew handling, these stale clients
+ * will experience:
+ *
+ * 1. Server action calls that crash (action IDs are content-hashed)
+ * 2. Chunk load failures (old filenames gone from CDN)
+ * 3. RSC payload mismatches (component references differ between builds)
+ *
+ * This module implements deployment ID comparison:
+ * - A per-build deployment ID is generated at build time (see build-manifest.ts)
+ * - The client sends it via `X-Timber-Deployment-Id` header on every RSC/action request
+ * - The server compares it against the current build's ID
+ * - On mismatch: signal the client to reload (not crash)
+ *
+ * The deployment ID is always-on in production. Dev mode skips the check
+ * (HMR handles code updates without full reloads).
+ *
+ * See design/25-production-deployments.md, TIM-446
+ */
+
+// ─── Constants ───────────────────────────────────────────────────
+
+/** Header sent by the client with every RSC/action request. */
+export const DEPLOYMENT_ID_HEADER = 'X-Timber-Deployment-Id';
+
+/** Response header that signals the client to do a full page reload. */
+export const RELOAD_HEADER = 'X-Timber-Reload';
+
+// ─── Deployment ID ───────────────────────────────────────────────
+
+/**
+ * The current build's deployment ID. Set at startup from the manifest init
+ * module (globalThis.__TIMBER_DEPLOYMENT_ID__). Null in dev mode.
+ */
+let currentDeploymentId: string | null = null;
+
+/**
+ * Set the current deployment ID. Called once at server startup from the
+ * manifest init module. In dev mode this is never called (deployment ID
+ * checks are skipped).
+ */
+export function setDeploymentId(id: string): void {
+  currentDeploymentId = id;
+}
+
+/**
+ * Get the current deployment ID. Returns null in dev mode.
+ */
+export function getDeploymentId(): string | null {
+  return currentDeploymentId;
+}
+
+// ─── Skew Detection ──────────────────────────────────────────────
+
+/** Result of a version skew check. */
+export interface SkewCheckResult {
+  /** Whether the client's deployment ID matches the server's. */
+  ok: boolean;
+  /** The client's deployment ID (null if header not sent — e.g., initial page load). */
+  clientId: string | null;
+}
+
+/**
+ * Check if a request's deployment ID matches the current build.
+ *
+ * Returns `{ ok: true }` when:
+ * - Dev mode (no deployment ID set — HMR handles updates)
+ * - No deployment ID header (initial page load, non-RSC request)
+ * - Deployment IDs match
+ *
+ * Returns `{ ok: false }` when:
+ * - Client sends a deployment ID that differs from the current build
+ */
+export function checkVersionSkew(req: Request): SkewCheckResult {
+  // Dev mode — no deployment ID checks (HMR handles updates)
+  if (!currentDeploymentId) {
+    return { ok: true, clientId: null };
+  }
+
+  const clientId = req.headers.get(DEPLOYMENT_ID_HEADER);
+
+  // No header — initial page load or non-RSC request. Always OK.
+  if (!clientId) {
+    return { ok: true, clientId: null };
+  }
+
+  // Compare deployment IDs
+  if (clientId === currentDeploymentId) {
+    return { ok: true, clientId };
+  }
+
+  return { ok: false, clientId };
+}
+
+/**
+ * Apply version skew reload headers to a response.
+ * Sets X-Timber-Reload: 1 to signal the client to do a full page reload.
+ */
+export function applyReloadHeaders(headers: Headers): void {
+  headers.set(RELOAD_HEADER, '1');
+}

package/src/shared/merge-search-params.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared utility for merging preserved search params into a target URL.
+ *
+ * Used by both <Link> (client) and redirect() (server). Extracted to a shared
+ * module to avoid importing client code ('use client') from server modules.
+ */
+
+/**
+ * Merge preserved search params from the current URL into a target href.
+ *
+ * When `preserve` is `true`, all current search params are merged.
+ * When `preserve` is a `string[]`, only the named params are merged.
+ *
+ * The target href's own search params take precedence — preserved params
+ * are only added if the target doesn't already define them.
+ *
+ * @param targetHref - The resolved target href (may already contain query string)
+ * @param currentSearch - The current URL's search string (e.g. "?private=access&page=2")
+ * @param preserve - `true` to preserve all, or `string[]` to preserve specific params
+ * @returns The target href with preserved search params merged in
+ */
+export function mergePreservedSearchParams(
+  targetHref: string,
+  currentSearch: string,
+  preserve: true | string[]
+): string {
+  const currentParams = new URLSearchParams(currentSearch);
+  if (currentParams.size === 0) return targetHref;
+
+  // Split hash fragment from target before processing query params.
+  // Hash must come after query string: /path?query=value#hash
+  const hashIdx = targetHref.indexOf('#');
+  const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;
+  const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : '';
+
+  // Split target into path and existing query
+  const qIdx = hrefWithoutHash.indexOf('?');
+  const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;
+  const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : '');
+
+  // Collect params to preserve (that aren't already in the target)
+  const merged = new URLSearchParams(targetParams);
+  for (const [key, value] of currentParams) {
+    // Only preserve if: (a) not already in target, and (b) included in preserve list
+    if (!targetParams.has(key)) {
+      if (preserve === true || preserve.includes(key)) {
+        merged.append(key, value);
+      }
+    }
+  }
+
+  const qs = merged.toString();
+  const pathWithQuery = qs ? `${targetPath}?${qs}` : targetPath;
+  return pathWithQuery + hash;
+}

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

@@ -6,4 +6,8 @@
  * pipeline (both import from the same shared request-context chunk in dist/).
  */
 
-export { headers, cookies } from '@timber-js/app/server';
+// Re-export timber's primary API
+export { getHeaders, getCookieJar } from '@timber-js/app/server';
+
+// Next.js compat aliases — libraries importing from 'next/headers' expect these names.
+export { getHeaders as headers, getCookieJar as cookies } from '@timber-js/app/server';

package/src/shims/navigation-client.ts

@@ -16,11 +16,12 @@
  * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
  */
 
-// Hooks — imported from the public barrel for module singleton consistency.
+// Hooks — useSegmentParams and useSearchParams import from direct modules
+// since they're no longer in @timber-js/app/client public exports.
+export { useSegmentParams } from '../client/use-segment-params.js';
+export { useSearchParams } from '../client/use-search-params.js';
 export {
-  useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,

package/src/shims/navigation.ts

@@ -1,20 +1,27 @@
 /**
  * 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';
+
+// Next.js compat aliases — these are not part of timber's primary API.
+// They exist so that libraries importing from 'next/navigation' still work.
+export { permanentRedirect, notFound } from '../server/primitives.js';

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-gwlJkDuf.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
-* - Detailed Server-Timing response headers
-* - 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-gwlJkDuf.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"debug-gwlJkDuf.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 * - Detailed Server-Timing response headers\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"}