@timber-js/app 0.1.0

package/dist/server/csrf.d.ts

@@ -0,0 +1,34 @@
+/**
+ * CSRF protection — Origin header validation.
+ *
+ * Auto-derived from the Host header for single-origin deployments.
+ * Configurable via allowedOrigins for multi-origin setups.
+ * Disable with csrf: false (not recommended outside local dev).
+ *
+ * See design/08-forms-and-actions.md §"CSRF Protection"
+ * See design/13-security.md §"Security Testing Checklist" #6
+ */
+export interface CsrfConfig {
+    /** Explicit list of allowed origins. Replaces Host-based auto-derivation. */
+    allowedOrigins?: string[];
+    /** Set to false to disable CSRF validation entirely. */
+    csrf?: boolean;
+}
+export type CsrfResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: 403;
+};
+/**
+ * Validate the Origin header against the request's Host.
+ *
+ * For mutation methods (POST, PUT, PATCH, DELETE):
+ * - If `csrf: false`, skip validation.
+ * - If `allowedOrigins` is set, Origin must match one exactly (no wildcards).
+ * - Otherwise, Origin's host must match the request's Host header.
+ *
+ * Safe methods (GET, HEAD, OPTIONS) always pass.
+ */
+export declare function validateCsrf(req: Request, config: CsrfConfig): CsrfResult;
+//# sourceMappingURL=csrf.d.ts.map

package/dist/server/csrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.d.ts","sourceRoot":"","sources":["../../src/server/csrf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,wDAAwD;IACxD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC;AASnE;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,UAAU,CAuCzE"}

package/dist/server/deny-renderer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Deny page rendering — renders status-code pages for DenySignal errors.
+ *
+ * Extracted from rsc-entry.ts to keep file sizes under 500 lines.
+ * Handles three rendering paths:
+ * 1. Component (TSX/MDX) with shell — full RSC→SSR through layout chain
+ * 2. Component (TSX/MDX) without shell — RSC→SSR standalone (no layouts)
+ * 3. JSON — raw file contents returned verbatim, no React pipeline
+ *
+ * Format selection:
+ * - Route handlers (route.ts) prefer JSON variants
+ * - Page routes prefer component variants
+ * - Accept: application/json on page routes falls back to JSON if no component exists
+ *
+ * See design/10-error-handling.md §"Status-Code Files"
+ */
+import { DenySignal } from './primitives.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+import type { RouteMatch } from './pipeline.js';
+import type { NavContext } from './ssr-entry.js';
+import type { ClientBootstrapConfig } from './html-injectors.js';
+/** Layout component entry for deny page wrapping. */
+export interface LayoutEntry {
+    component: (...args: unknown[]) => unknown;
+    segment: ManifestSegmentNode;
+}
+/** Callback to create a debug channel sink for RSC rendering. */
+export type DebugChannelFactory = () => {
+    readable: ReadableStream;
+    writable: WritableStream;
+};
+/** Callback to pass RSC stream to SSR for HTML rendering. */
+export type CallSsrFn = (rscStream: ReadableStream<Uint8Array>, navContext: NavContext) => Promise<Response>;
+/**
+ * Render a status-code error page for a DenySignal.
+ *
+ * Resolves the appropriate status-code file from the segment chain based
+ * on format preference. Returns an HTML Response (component), JSON Response,
+ * or bare fallback Response.
+ */
+export declare function renderDenyPage(deny: DenySignal, segments: ManifestSegmentNode[], layoutComponents: LayoutEntry[], req: Request, match: RouteMatch, responseHeaders: Headers, clientBootstrap: ClientBootstrapConfig, createDebugChannelSink: DebugChannelFactory, callSsr: CallSsrFn): Promise<Response>;
+/**
+ * Render a status-code error page as a raw RSC Flight stream for client navigation.
+ *
+ * Same as renderDenyPage but skips SSR — returns the RSC stream directly
+ * so the client can reconcile the error page into the existing DOM.
+ */
+export declare function renderDenyPageAsRsc(deny: DenySignal, segments: ManifestSegmentNode[], layoutComponents: LayoutEntry[], responseHeaders: Headers, createDebugChannelSink: DebugChannelFactory): Promise<Response>;
+//# sourceMappingURL=deny-renderer.d.ts.map

package/dist/server/deny-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deny-renderer.d.ts","sourceRoot":"","sources":["../../src/server/deny-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAI7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAMjE,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,iEAAiE;AACjE,MAAM,MAAM,mBAAmB,GAAG,MAAM;IACtC,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,cAAc,CAAC;CAC1B,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,CACtB,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,KACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;AAUvB;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,WAAW,EAAE,EAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,qBAAqB,EACtC,sBAAsB,EAAE,mBAAmB,EAC3C,OAAO,EAAE,SAAS,GACjB,OAAO,CAAC,QAAQ,CAAC,CA6GnB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,WAAW,EAAE,EAC/B,eAAe,EAAE,OAAO,EACxB,sBAAsB,EAAE,mBAAmB,GAC1C,OAAO,CAAC,QAAQ,CAAC,CAgDnB"}

package/dist/server/dev-logger.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Dev logger — structured console output for every request in dev mode.
+ *
+ * Formats OTEL span trees into indented tree output for stderr. Spans are
+ * the single source of truth — no separate event system needed.
+ *
+ * Supports five modes:
+ * - tree (default) — indented tree per request
+ * - verbose — detailed tree showing every component render
+ * - summary — one line per request
+ * - json — chronological NDJSON dump of all spans
+ * - quiet — no output
+ *
+ * Design doc: 21-dev-server.md §"Dev Logging", 17-logging.md §"Dev Logging"
+ */
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+export type DevLogMode = 'tree' | 'verbose' | 'summary' | 'json' | 'quiet';
+export interface DevLoggerConfig {
+    /** Logging mode. Default: 'tree'. */
+    mode?: DevLogMode;
+    /** Threshold in ms to highlight slow phases. Default: 200. */
+    slowPhaseMs?: number;
+}
+/**
+ * Resolve the effective log mode from environment variables and config.
+ * Environment variables override config file values per 21-dev-server.md.
+ */
+export declare function resolveLogMode(config?: DevLoggerConfig): DevLogMode;
+/**
+ * Format spans as a full indented tree string for stderr.
+ */
+export declare function formatSpanTree(spans: ReadableSpan[], config?: DevLoggerConfig): string;
+/**
+ * Format spans as a one-line summary.
+ */
+export declare function formatSpanSummary(spans: ReadableSpan[], _config?: DevLoggerConfig): string;
+/**
+ * Format spans as chronological NDJSON for json mode.
+ *
+ * Each span is one JSON line, ordered by start time. Useful for piping
+ * to jq or feeding into external trace analysis tools.
+ */
+export declare function formatJson(spans: ReadableSpan[]): string;
+//# sourceMappingURL=dev-logger.d.ts.map

package/dist/server/dev-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-logger.d.ts","sourceRoot":"","sources":["../../src/server/dev-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAIlE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3E,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA8LD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,UAAU,CAMnE;AAID;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,CAgDtF;AA6DD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAc1F;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,MAAM,CA6BxD"}

package/dist/server/dev-span-processor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * DevSpanProcessor — Custom OTEL SpanProcessor that drives dev log output.
+ *
+ * Collects completed spans per-request (correlated by trace ID). When the
+ * root span (http.server.request) ends, all child spans are already collected
+ * (child spans end before parent in OTEL). The processor formats the span
+ * tree and writes it to stderr.
+ *
+ * This replaces the old DevLogEmitter/DevLogEvents system. OTEL spans are
+ * now the single source of truth for dev logging — no more parallel event
+ * systems that can drift.
+ *
+ * Design doc: 17-logging.md §"Dev Logging", 21-dev-server.md §"Dev Logging"
+ */
+import type { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import type { Span, Context } from '@opentelemetry/api';
+import { type DevLoggerConfig } from './dev-logger.js';
+export declare class DevSpanProcessor implements SpanProcessor {
+    private spansByTrace;
+    private mode;
+    private config;
+    constructor(config: DevLoggerConfig);
+    onStart(_span: Span, _context: Context): void;
+    onEnd(span: ReadableSpan): void;
+    private format;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+//# sourceMappingURL=dev-span-processor.d.ts.map

package/dist/server/dev-span-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-span-processor.d.ts","sourceRoot":"","sources":["../../src/server/dev-span-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AAEzB,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,YAAY,CAAqC;IACzD,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,EAAE,eAAe;IAKnC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAI7C,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAqB/B,OAAO,CAAC,MAAM;IAUR,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAIzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

package/dist/server/dev-warnings.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Dev-mode warnings for common timber.js misuse patterns.
+ *
+ * These fire in development only and are stripped from production builds.
+ * Each warning targets a specific misuse identified during design review.
+ *
+ * Warnings are deduplicated by warningId:filePath:line so the same warning
+ * is only emitted once per dev session (per unique source location).
+ *
+ * Warnings are written to stderr and, when a Vite dev server is available,
+ * forwarded to the browser console via Vite's WebSocket.
+ *
+ * See design/21-dev-server.md §"Dev-Mode Warnings"
+ * See design/11-platform.md §"Dev Mode"
+ */
+import type { ViteDevServer } from 'vite';
+export declare const WarningId: {
+    readonly SUSPENSE_WRAPS_CHILDREN: "SUSPENSE_WRAPS_CHILDREN";
+    readonly DENY_IN_SUSPENSE: "DENY_IN_SUSPENSE";
+    readonly REDIRECT_IN_SUSPENSE: "REDIRECT_IN_SUSPENSE";
+    readonly REDIRECT_IN_ACCESS: "REDIRECT_IN_ACCESS";
+    readonly STATIC_REQUEST_API: "STATIC_REQUEST_API";
+    readonly CACHE_REQUEST_PROPS: "CACHE_REQUEST_PROPS";
+    readonly SLOW_SLOT_NO_SUSPENSE: "SLOW_SLOT_NO_SUSPENSE";
+};
+export type WarningId = (typeof WarningId)[keyof typeof WarningId];
+/** Configuration for dev warning behavior. */
+export interface DevWarningConfig {
+    /** Threshold in ms for "slow slot" warnings. Default: 200. */
+    slowSlotThresholdMs?: number;
+}
+/**
+ * Register the Vite dev server for browser console forwarding.
+ * Called by timber-dev-server during configureServer.
+ */
+export declare function setViteServer(server: ViteDevServer | null): void;
+/**
+ * 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")
+ */
+export declare function warnSuspenseWrappingChildren(layoutFile: string): void;
+/**
+ * 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
+ */
+export declare function warnDenyInSuspense(file: string, line?: number): void;
+/**
+ * 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
+ */
+export declare function warnRedirectInSuspense(file: string, line?: number): void;
+/**
+ * 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
+ */
+export declare function warnRedirectInAccess(accessFile: string, line?: number): void;
+/**
+ * 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
+ */
+export declare function warnStaticRequestApi(api: 'cookies' | 'headers', file: string): void;
+/**
+ * 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
+ */
+export declare function warnCacheRequestProps(componentName: string, propName: string, file: string, line?: number): void;
+/**
+ * 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
+ */
+export declare function warnSlowSlotWithoutSuspense(slotName: string, durationMs: number): void;
+/** @deprecated Use warnStaticRequestApi instead */
+export declare const warnDynamicApiInStaticBuild: typeof warnStaticRequestApi;
+/** @deprecated Use warnRedirectInAccess instead */
+export declare function warnRedirectInSlotAccess(slotName: string): void;
+/** @deprecated Use warnDenyInSuspense / warnRedirectInSuspense instead */
+export declare function warnDenyAfterFlush(signal: 'deny' | 'redirect'): void;
+/**
+ * Reset emitted warnings. For testing only.
+ * @internal
+ */
+export declare function _resetWarnings(): void;
+/**
+ * Get the set of emitted dedup keys. For testing only.
+ * @internal
+ */
+export declare function _getEmitted(): ReadonlySet<string>;
+//# sourceMappingURL=dev-warnings.d.ts.map

package/dist/server/dev-warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-warnings.d.ts","sourceRoot":"","sources":["../../src/server/dev-warnings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAI1C,eAAO,MAAM,SAAS;;;;;;;;CAQZ,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAInE,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AASD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAEhE;AA0CD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CASrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAUpE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CASxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAU5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAQnF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CASN;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAQtF;AAID,mDAAmD;AACnD,eAAO,MAAM,2BAA2B,6BAAuB,CAAC;AAEhE,mDAAmD;AACnD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAMpE;AAID;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,WAAW,CAAC,MAAM,CAAC,CAEjD"}

package/dist/server/early-hints-sender.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Per-request 103 Early Hints sender — ALS bridge for platform adapters.
+ *
+ * The pipeline collects Link headers for CSS, fonts, and JS chunks at
+ * route-match time. On platforms that support it (Node.js v18.11+, Bun),
+ * the adapter can send these as a 103 Early Hints interim response before
+ * the final response is ready.
+ *
+ * This module provides an ALS-based bridge: the generated entry point
+ * (e.g., the Nitro entry) wraps the handler with `runWithEarlyHintsSender`,
+ * binding a per-request sender function. The pipeline calls
+ * `sendEarlyHints103()` to fire the 103 if a sender is available.
+ *
+ * On platforms where 103 is handled at the CDN level (e.g., Cloudflare
+ * converts Link headers into 103 automatically), no sender is installed
+ * and `sendEarlyHints103()` is a no-op.
+ *
+ * Design doc: 02-rendering-pipeline.md §"Early Hints (103)"
+ */
+/** Function that sends Link header values as a 103 Early Hints response. */
+export type EarlyHintsSenderFn = (links: string[]) => void;
+/**
+ * Run a function with a per-request early hints sender installed.
+ *
+ * Called by generated entry points (e.g., Nitro node-server/bun) to
+ * bind the platform's writeEarlyHints capability for the request duration.
+ */
+export declare function runWithEarlyHintsSender<T>(sender: EarlyHintsSenderFn, fn: () => T): T;
+/**
+ * Send collected Link headers as a 103 Early Hints response.
+ *
+ * No-op if no sender is installed for the current request (e.g., on
+ * Cloudflare where the CDN handles 103 automatically, or in dev mode).
+ *
+ * Non-fatal: errors from the sender are caught and silently ignored.
+ */
+export declare function sendEarlyHints103(links: string[]): void;
+//# sourceMappingURL=early-hints-sender.d.ts.map

package/dist/server/early-hints-sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"early-hints-sender.d.ts","sourceRoot":"","sources":["../../src/server/early-hints-sender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;AAI3D;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAErF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CASvD"}

package/dist/server/early-hints.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 103 Early Hints utilities.
+ *
+ * Early Hints are sent before the final response to let the browser
+ * start fetching critical resources (CSS, fonts, JS) while the server
+ * is still rendering.
+ *
+ * The framework collects hints from two sources:
+ * 1. Build manifest — CSS, fonts, and JS chunks known at route-match time
+ * 2. ctx.earlyHints() — explicit hints added by middleware or route handlers
+ *
+ * Both are emitted as Link headers. Cloudflare CDN automatically converts
+ * Link headers into 103 Early Hints responses.
+ *
+ * Design docs: 02-rendering-pipeline.md §"Early Hints (103)"
+ */
+import type { BuildManifest } from './build-manifest.js';
+/** Minimal segment shape needed for early hint collection. */
+interface SegmentWithFiles {
+    layout?: {
+        filePath: string;
+    };
+    page?: {
+        filePath: string;
+    };
+}
+/**
+ * A single Link header hint for 103 Early Hints.
+ *
+ * ```ts
+ * ctx.earlyHints([
+ *   { href: '/styles/critical.css', rel: 'preload', as: 'style' },
+ *   { href: 'https://fonts.googleapis.com', rel: 'preconnect' },
+ * ])
+ * ```
+ */
+export interface EarlyHint {
+    /** The resource URL (absolute or root-relative). */
+    href: string;
+    /** Link relation — `preload`, `modulepreload`, or `preconnect`. */
+    rel: 'preload' | 'modulepreload' | 'preconnect';
+    /** Resource type for `preload` hints (omit for `modulepreload` / `preconnect`). */
+    as?: 'style' | 'script' | 'font' | 'image' | 'fetch' | 'document';
+    /** Crossorigin attribute — required for font preloads per spec. */
+    crossOrigin?: 'anonymous' | 'use-credentials';
+    /** Fetch priority hint — `high`, `low`, or `auto`. */
+    fetchPriority?: 'high' | 'low' | 'auto';
+}
+/**
+ * Format a single EarlyHint as a Link header value.
+ *
+ * Examples:
+ *   `</styles/root.css>; rel=preload; as=style`
+ *   `</fonts/inter.woff2>; rel=preload; as=font; crossorigin=anonymous`
+ *   `</_timber/client.js>; rel=modulepreload`
+ *   `<https://fonts.googleapis.com>; rel=preconnect`
+ */
+export declare function formatLinkHeader(hint: EarlyHint): string;
+/** Options for early hint collection. */
+export interface EarlyHintOptions {
+    /** Skip JS modulepreload hints (e.g. when client JavaScript is disabled). */
+    skipJs?: boolean;
+}
+/**
+ * Collect all Link header strings for a matched route's segment chain.
+ *
+ * Walks the build manifest to emit hints for:
+ * - CSS stylesheets (rel=preload; as=style)
+ * - Font assets (rel=preload; as=font; crossorigin)
+ * - JS modulepreload hints (rel=modulepreload) — unless skipJs is set
+ *
+ * Also emits global CSS from the `_global` manifest key. Route files
+ * are server components that don't appear in the client bundle, so
+ * per-route CSS keying doesn't work with the RSC plugin. The `_global`
+ * key contains all CSS assets from the client build — fine for early
+ * hints since they're just prefetch signals.
+ *
+ * Returns formatted Link header strings, deduplicated, root → leaf order.
+ * Returns an empty array in dev mode (manifest is empty).
+ */
+export declare function collectEarlyHintHeaders(segments: SegmentWithFiles[], manifest: BuildManifest, options?: EarlyHintOptions): string[];
+export {};
+//# sourceMappingURL=early-hints.d.ts.map

package/dist/server/early-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"early-hints.d.ts","sourceRoot":"","sources":["../../src/server/early-hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,8DAA8D;AAC9D,UAAU,gBAAgB;IACxB,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,IAAI,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7B;AAID;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,GAAG,EAAE,SAAS,GAAG,eAAe,GAAG,YAAY,CAAC;IAChD,mFAAmF;IACnF,EAAE,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,CAAC;IAClE,mEAAmE;IACnE,WAAW,CAAC,EAAE,WAAW,GAAG,iBAAiB,CAAC;IAC9C,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;CACzC;AAID;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAMxD;AAID,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,EAAE,CAsCV"}

package/dist/server/error-boundary-wrapper.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Error boundary wrapper — wraps a React element in error boundaries from a route segment.
+ *
+ * Extracted to allow reuse by both rsc-entry.ts and route-element-builder.ts.
+ * See design/10-error-handling.md.
+ */
+import type { ManifestSegmentNode } from './route-matcher.js';
+/**
+ * Wrap an element in error boundaries defined by a route segment.
+ *
+ * Processing order (innermost to outermost):
+ * 1. Specific status files (e.g., 404.tsx, 500.tsx) — highest priority at runtime
+ * 2. Category catch-alls (4xx.tsx, 5xx.tsx)
+ * 3. error.tsx — catches anything not matched by status files
+ */
+export declare function wrapSegmentWithErrorBoundaries(segment: ManifestSegmentNode, element: React.ReactElement, h: (...args: unknown[]) => React.ReactElement): Promise<React.ReactElement>;
+//# sourceMappingURL=error-boundary-wrapper.d.ts.map

package/dist/server/error-boundary-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-boundary-wrapper.d.ts","sourceRoot":"","sources":["../../src/server/error-boundary-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,KAAK,CAAC,YAAY,EAC3B,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,KAAK,CAAC,YAAY,GAC5C,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CA8C7B"}

package/dist/server/error-formatter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Error Formatter — rewrites SSR/RSC error messages to surface user code.
+ *
+ * When React or Vite throw errors during SSR, stack traces reference
+ * vendored dependency paths (e.g. `.vite/deps_ssr/@vitejs_plugin-rsc_vendor_...`)
+ * and mangled export names (`__vite_ssr_export_default__`). This module
+ * rewrites error messages and stack traces to point at user code instead.
+ *
+ * Dev-only — in production, errors go through the structured logger
+ * without formatting.
+ */
+/**
+ * Rewrite an error's message and stack to replace internal Vite paths
+ * and mangled names with human-readable labels.
+ */
+export declare function formatSsrError(error: unknown): string;
+//# sourceMappingURL=error-formatter.d.ts.map

package/dist/server/error-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-formatter.d.ts","sourceRoot":"","sources":["../../src/server/error-formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAyCH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA6CrD"}

package/dist/server/flush.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Flush controller for timber.js rendering.
+ *
+ * Holds the response until `onShellReady` fires, then commits the HTTP status
+ * code and flushes the shell. Render-phase signals (deny, redirect, unhandled
+ * throws) caught before flush produce correct HTTP status codes.
+ *
+ * See design/02-rendering-pipeline.md §"The Flush Point" and §"The Hold Window"
+ */
+/** The readable stream from React's renderToReadableStream. */
+export interface ReactRenderStream {
+    /** The underlying ReadableStream of HTML bytes. */
+    readable: ReadableStream<Uint8Array>;
+    /** Resolves when the shell has finished rendering (all non-Suspense content). */
+    allReady?: Promise<void>;
+}
+/** Options for the flush controller. */
+export interface FlushOptions {
+    /** Response headers to include (from middleware.ts, proxy.ts, etc.). */
+    responseHeaders?: Headers;
+    /** Default status code when rendering succeeds. Default: 200. */
+    defaultStatus?: number;
+}
+/** Result of the flush process. */
+export interface FlushResult {
+    /** The final HTTP Response. */
+    response: Response;
+    /** The status code committed. */
+    status: number;
+    /** Whether the response was a redirect. */
+    isRedirect: boolean;
+    /** Whether the response was a denial. */
+    isDenial: boolean;
+}
+/**
+ * A function that performs the React render.
+ *
+ * The flush controller calls this, catches any signals thrown during the
+ * synchronous shell render (before onShellReady), and produces the
+ * correct HTTP response.
+ *
+ * Must return an object with:
+ * - `stream`: The ReadableStream from renderToReadableStream
+ * - `shellReady`: A Promise that resolves when onShellReady fires
+ */
+export interface RenderResult {
+    /** The HTML byte stream. */
+    stream: ReadableStream<Uint8Array>;
+    /** Resolves when the shell is ready (all non-Suspense content rendered). */
+    shellReady: Promise<void>;
+}
+export type RenderFn = () => RenderResult | Promise<RenderResult>;
+/**
+ * Execute a render and hold the response until the shell is ready.
+ *
+ * The flush controller:
+ * 1. Calls the render function to start renderToReadableStream
+ * 2. Waits for shellReady (onShellReady)
+ * 3. If a render-phase signal was thrown (deny, redirect, error), produces
+ *    the correct HTTP status code
+ * 4. If the shell rendered successfully, commits the status and streams
+ *
+ * Render-phase signals caught before flush:
+ * - `DenySignal` → HTTP 4xx with appropriate status code
+ * - `RedirectSignal` → HTTP 3xx with Location header
+ * - `RenderError` → HTTP status from error (default 500)
+ * - Unhandled error → HTTP 500
+ *
+ * @param renderFn - Function that starts the React render.
+ * @param options - Flush configuration.
+ * @returns The committed HTTP Response.
+ */
+export declare function flushResponse(renderFn: RenderFn, options?: FlushOptions): Promise<FlushResult>;
+//# sourceMappingURL=flush.d.ts.map

package/dist/server/flush.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush.d.ts","sourceRoot":"","sources":["../../src/server/flush.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACrC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,UAAU,EAAE,OAAO,CAAC;IACpB,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAID;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACnC,4EAA4E;IAC5E,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AAIlE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAiCtB"}

package/dist/server/form-data.d.ts

@@ -0,0 +1,60 @@
+/**
+ * FormData preprocessing — schema-agnostic conversion of FormData to typed objects.
+ *
+ * FormData is all strings. Schema validation expects typed values. This module
+ * bridges the gap with intelligent coercion that runs *before* schema validation.
+ *
+ * Inspired by zod-form-data, but schema-agnostic — works with any Standard Schema
+ * library (Zod, Valibot, ArkType).
+ *
+ * See design/08-forms-and-actions.md §"parseFormData() and coerce helpers"
+ */
+/**
+ * Convert FormData into a plain object with intelligent coercion.
+ *
+ * Handles:
+ * - **Duplicate keys → arrays**: `tags=js&tags=ts` → `{ tags: ["js", "ts"] }`
+ * - **Nested dot-paths**: `user.name=Alice` → `{ user: { name: "Alice" } }`
+ * - **Empty strings → undefined**: Enables `.optional()` semantics in schemas
+ * - **Empty Files → undefined**: File inputs with no selection become `undefined`
+ * - **Strips `$ACTION_*` fields**: React's internal hidden fields are excluded
+ */
+export declare function parseFormData(formData: FormData): Record<string, unknown>;
+/**
+ * Schema-agnostic coercion primitives for common FormData patterns.
+ *
+ * These are plain transform functions — they compose with any schema library's
+ * `transform`/`preprocess` pipeline:
+ *
+ * ```ts
+ * // Zod
+ * z.preprocess(coerce.number, z.number())
+ * // Valibot
+ * v.pipe(v.unknown(), v.transform(coerce.number), v.number())
+ * ```
+ */
+export declare const coerce: {
+    /**
+     * Coerce a string to a number.
+     * - `"42"` → `42`
+     * - `"3.14"` → `3.14`
+     * - `""` / `undefined` / `null` → `undefined`
+     * - Non-numeric strings → `undefined` (schema validation will catch this)
+     */
+    number(value: unknown): number | undefined;
+    /**
+     * Coerce a checkbox value to a boolean.
+     * HTML checkboxes submit "on" when checked and are absent when unchecked.
+     * - `"on"` / any truthy string → `true`
+     * - `undefined` / `null` / `""` → `false`
+     */
+    checkbox(value: unknown): boolean;
+    /**
+     * Parse a JSON string into an object.
+     * - Valid JSON string → parsed object
+     * - `""` / `undefined` / `null` → `undefined`
+     * - Invalid JSON → `undefined` (schema validation will catch this)
+     */
+    json(value: unknown): unknown;
+};
+//# sourceMappingURL=form-data.d.ts.map

package/dist/server/form-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-data.d.ts","sourceRoot":"","sources":["../../src/server/form-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzE;AAyED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM;IACjB;;;;;;OAMG;kBACW,OAAO,GAAG,MAAM,GAAG,SAAS;IAS1C;;;;;OAKG;oBACa,OAAO,GAAG,OAAO;IAOjC;;;;;OAKG;gBACS,OAAO,GAAG,OAAO;CAS9B,CAAC"}