@timber-js/app 0.1.0

package/dist/server/instrumentation.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Instrumentation — loads and runs the user's instrumentation.ts file.
+ *
+ * instrumentation.ts is a file convention at the project root that exports:
+ * - register() — called once at server startup, before the first request
+ * - onRequestError() — called for every unhandled server error
+ * - logger — any object with info/warn/error/debug methods
+ *
+ * See design/17-logging.md §"instrumentation.ts — The Entry Point"
+ */
+import { type TimberLogger } from './logger.js';
+export type InstrumentationOnRequestError = (error: unknown, request: InstrumentationRequestInfo, context: InstrumentationErrorContext) => void | Promise<void>;
+export interface InstrumentationRequestInfo {
+    /** HTTP method: 'GET', 'POST', etc. */
+    method: string;
+    /** Request path: '/dashboard/projects/123' */
+    path: string;
+    /** Request headers as a plain object. */
+    headers: Record<string, string>;
+}
+export interface InstrumentationErrorContext {
+    /** Which pipeline phase the error occurred in. */
+    phase: 'proxy' | 'handler' | 'render' | 'action' | 'route';
+    /** The route pattern: '/dashboard/projects/[id]' */
+    routePath: string;
+    /** Type of route that was matched. */
+    routeType: 'page' | 'route' | 'action';
+    /** Always set — OTEL trace ID or UUID fallback. */
+    traceId: string;
+}
+interface InstrumentationModule {
+    register?: () => void | Promise<void>;
+    onRequestError?: InstrumentationOnRequestError;
+    logger?: TimberLogger;
+}
+/**
+ * Load and initialize the user's instrumentation.ts module.
+ *
+ * - Awaits register() before returning (server blocks on this).
+ * - Picks up the logger export and wires it into the framework logger.
+ * - Stores onRequestError for later invocation.
+ *
+ * @param loader - Function that dynamically imports the user's instrumentation module.
+ *                 Returns null if no instrumentation.ts exists.
+ */
+export declare function loadInstrumentation(loader: () => Promise<InstrumentationModule | null>): Promise<void>;
+/**
+ * Call the user's onRequestError hook. Catches and logs any errors thrown
+ * by the hook itself — it must not affect the response.
+ */
+export declare function callOnRequestError(error: unknown, request: InstrumentationRequestInfo, context: InstrumentationErrorContext): Promise<void>;
+/**
+ * Check if onRequestError is registered.
+ */
+export declare function hasOnRequestError(): boolean;
+/**
+ * Reset instrumentation state. Test-only.
+ */
+export declare function resetInstrumentation(): void;
+export {};
+//# sourceMappingURL=instrumentation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/server/instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3D,MAAM,MAAM,6BAA6B,GAAG,CAC1C,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,0BAA0B,EACnC,OAAO,EAAE,2BAA2B,KACjC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,MAAM,WAAW,0BAA0B;IACzC,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,2BAA2B;IAC1C,kDAAkD;IAClD,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3D,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,cAAc,CAAC,EAAE,6BAA6B,CAAC;IAC/C,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAWD;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,GAClD,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,0BAA0B,EACnC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C"}

package/dist/server/logger.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Logger — structured logging with environment-aware formatting.
+ *
+ * timber.js does not ship a logger. Users export any object with
+ * info/warn/error/debug methods from instrumentation.ts and the framework
+ * picks it up. Silent if no logger export is present.
+ *
+ * See design/17-logging.md §"Production Logging"
+ */
+/** Any object with standard log methods satisfies this — pino, winston, consola, console. */
+export interface TimberLogger {
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+    debug(msg: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Set the user-provided logger. Called by the instrumentation loader
+ * when it finds a `logger` export in instrumentation.ts.
+ */
+export declare function setLogger(logger: TimberLogger): void;
+/**
+ * Get the current logger, or null if none configured.
+ * Framework-internal — used at framework event points to emit structured logs.
+ */
+export declare function getLogger(): TimberLogger | null;
+/** Log a completed request. Level: info. */
+export declare function logRequestCompleted(data: {
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+}): void;
+/** Log request received. Level: debug. */
+export declare function logRequestReceived(data: {
+    method: string;
+    path: string;
+}): void;
+/** Log a slow request warning. Level: warn. */
+export declare function logSlowRequest(data: {
+    method: string;
+    path: string;
+    durationMs: number;
+    threshold: number;
+}): void;
+/** Log middleware short-circuit. Level: debug. */
+export declare function logMiddlewareShortCircuit(data: {
+    method: string;
+    path: string;
+    status: number;
+}): void;
+/** Log unhandled error in middleware phase. Level: error. */
+export declare function logMiddlewareError(data: {
+    method: string;
+    path: string;
+    error: unknown;
+}): void;
+/** Log unhandled render-phase error. Level: error. */
+export declare function logRenderError(data: {
+    method: string;
+    path: string;
+    error: unknown;
+}): void;
+/** Log proxy.ts uncaught error. Level: error. */
+export declare function logProxyError(data: {
+    error: unknown;
+}): void;
+/** Log waitUntil() adapter missing (once at startup). Level: warn. */
+export declare function logWaitUntilUnsupported(): void;
+/** Log waitUntil() promise rejection. Level: warn. */
+export declare function logWaitUntilRejected(data: {
+    error: unknown;
+}): void;
+/** Log staleWhileRevalidate refetch failure. Level: warn. */
+export declare function logSwrRefetchFailed(data: {
+    cacheKey: string;
+    error: unknown;
+}): void;
+/** Log cache miss. Level: debug. */
+export declare function logCacheMiss(data: {
+    cacheKey: string;
+}): void;
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/server/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,6FAA6F;AAC7F,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAMD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAEpD;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,YAAY,GAAG,IAAI,CAE/C;AAsBD,4CAA4C;AAC5C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,CAEP;AAED,0CAA0C;AAC1C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAE/E;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CAEP;AAED,kDAAkD;AAClD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,IAAI,CAEP;AAED,6DAA6D;AAC7D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAM/F;AAED,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAQ3F;AAED,iDAAiD;AACjD,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAM5D;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED,sDAAsD;AACtD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEnE;AAED,6DAA6D;AAC7D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEpF;AAED,oCAAoC;AACpC,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAE7D"}

package/dist/server/manifest-status-resolver.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Manifest-compatible status-code file resolver.
+ *
+ * The existing status-code-resolver.ts works with SegmentNode (Map-based).
+ * This module works with ManifestSegmentNode (object-based) for use at
+ * runtime in the RSC/SSR entries, where the route manifest provides
+ * plain objects instead of Maps.
+ *
+ * Supports two format families:
+ * - 'component' (default): .tsx/.jsx/.mdx status files → React rendering pipeline
+ * - 'json': .json status files → raw JSON response, no React
+ *
+ * Follows the same fallback chains as status-code-resolver.ts:
+ *
+ * **Component chain (4xx):**
+ *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
+ *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
+ *   Pass 3 — error.tsx (leaf → root)
+ *   Pass 4 — framework default (returns null)
+ *
+ * **JSON chain (4xx):**
+ *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
+ *   Pass 2 — framework default JSON (returns null, caller provides bare JSON)
+ *
+ * See design/10-error-handling.md §"Status-Code Files"
+ */
+import type { ManifestSegmentNode } from './route-matcher.js';
+/** A file reference in the manifest (lazy import + path). */
+interface ManifestFile {
+    load: () => Promise<unknown>;
+    filePath: string;
+}
+/** How the status-code file was matched. */
+export type ManifestStatusFileKind = 'exact' | 'category' | 'legacy' | 'error';
+/** Response format family for status-code resolution. */
+export type ManifestStatusFileFormat = 'component' | 'json';
+/** Result of resolving a status-code file from manifest segments. */
+export interface ManifestStatusFileResolution {
+    /** The matched manifest file (has load() and filePath). */
+    file: ManifestFile;
+    /** The HTTP status code (always the original status, not the file's code). */
+    status: number;
+    /** How the file was matched. */
+    kind: ManifestStatusFileKind;
+    /** Index into the segments array where the file was found. */
+    segmentIndex: number;
+}
+/**
+ * Resolve the status-code file to render for a given HTTP status code,
+ * using manifest segment nodes (plain objects, not Maps).
+ *
+ * @param status - The HTTP status code (4xx or 5xx).
+ * @param segments - The matched segment chain from root (index 0) to leaf (last).
+ * @param format - The response format family ('component' or 'json'). Defaults to 'component'.
+ */
+export declare function resolveManifestStatusFile(status: number, segments: ReadonlyArray<ManifestSegmentNode>, format?: ManifestStatusFileFormat): ManifestStatusFileResolution | null;
+export {};
+//# sourceMappingURL=manifest-status-resolver.d.ts.map

package/dist/server/manifest-status-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-status-resolver.d.ts","sourceRoot":"","sources":["../../src/server/manifest-status-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAI9D,6DAA6D;AAC7D,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,MAAM,sBAAsB,GAC9B,OAAO,GACP,UAAU,GACV,QAAQ,GACR,OAAO,CAAC;AAEZ,yDAAyD;AACzD,MAAM,MAAM,wBAAwB,GAAG,WAAW,GAAG,MAAM,CAAC;AAE5D,qEAAqE;AACrE,MAAM,WAAW,4BAA4B;IAC3C,2DAA2D;IAC3D,IAAI,EAAE,YAAY,CAAC;IACnB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;CACtB;AAYD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,CAAC,mBAAmB,CAAC,EAC5C,MAAM,GAAE,wBAAsC,GAC7C,4BAA4B,GAAG,IAAI,CAcrC"}

package/dist/server/metadata-render.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Metadata rendering — converts resolved Metadata into HeadElement descriptors.
+ *
+ * Extracted from metadata.ts to keep files under 500 lines.
+ *
+ * See design/16-metadata.md
+ */
+import type { Metadata } from './types.js';
+import type { HeadElement } from './metadata.js';
+/**
+ * Convert resolved metadata into an array of head element descriptors.
+ *
+ * Each descriptor has a `tag` ('title', 'meta', 'link') and either
+ * `content` (for <title>) or `attrs` (for <meta>/<link>).
+ *
+ * The framework's MetadataResolver component consumes these descriptors
+ * and renders them into the <head>.
+ */
+export declare function renderMetadataToElements(metadata: Metadata): HeadElement[];
+//# sourceMappingURL=metadata-render.d.ts.map

package/dist/server/metadata-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-render.d.ts","sourceRoot":"","sources":["../../src/server/metadata-render.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAIjD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,EAAE,CAkI1E"}

package/dist/server/metadata-routes.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Metadata route classification for timber.js.
+ *
+ * Metadata routes are file-based endpoints that generate well-known URLs for
+ * crawlers and browsers (sitemap.xml, robots.txt, OG images, etc.).
+ *
+ * These routes run through proxy.ts but NOT through middleware.ts or access.ts —
+ * they are public endpoints by nature.
+ *
+ * See design/16-metadata.md §"Metadata Routes"
+ */
+/** Classification of a metadata route file. */
+export interface MetadataRouteInfo {
+    /** The metadata route type. */
+    type: MetadataRouteType;
+    /** The content type to serve this route with. */
+    contentType: string;
+    /** Whether this route can appear in nested segments (not just app root). */
+    nestable: boolean;
+}
+export type MetadataRouteType = 'sitemap' | 'robots' | 'manifest' | 'favicon' | 'icon' | 'opengraph-image' | 'twitter-image' | 'apple-icon';
+/**
+ * All recognized metadata route file conventions.
+ *
+ * Each entry maps a base file name (without extension) to its route info.
+ * The extensions determine whether the file is static or dynamic.
+ *
+ * Static extensions: .xml, .txt, .json, .png, .jpg, .ico, .svg
+ * Dynamic extensions: .ts, .tsx
+ */
+export declare const METADATA_ROUTE_CONVENTIONS: Record<string, {
+    type: MetadataRouteType;
+    contentType: string;
+    nestable: boolean;
+    staticExtensions: string[];
+    dynamicExtensions: string[];
+    /** The URL path this file serves at (relative to segment). */
+    servePath: string;
+}>;
+/**
+ * Classify a file name as a metadata route, or return null if it's not one.
+ *
+ * @param fileName - The full file name including extension (e.g. "sitemap.xml", "icon.tsx")
+ * @returns Classification info, or null if not a metadata route
+ */
+export declare function classifyMetadataRoute(fileName: string): MetadataRouteInfo | null;
+/**
+ * Get the serve path for a metadata route type.
+ *
+ * @param type - The metadata route type
+ * @returns The URL path fragment this route serves at
+ */
+export declare function getMetadataRouteServePath(type: MetadataRouteType): string;
+/**
+ * Get the auto-link tags to inject into <head> for metadata route files
+ * discovered in a segment.
+ *
+ * @param type - The metadata route type
+ * @param href - The resolved URL path to the metadata route
+ * @returns An object with tag/attrs for the <head>, or null if no auto-link
+ */
+export declare function getMetadataRouteAutoLink(type: MetadataRouteType, href: string): {
+    rel: string;
+    href: string;
+    type?: string;
+} | null;
+//# sourceMappingURL=metadata-routes.d.ts.map

package/dist/server/metadata-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-routes.d.ts","sourceRoot":"","sources":["../../src/server/metadata-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,IAAI,EAAE,iBAAiB,CAAC;IACxB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,QAAQ,GACR,UAAU,GACV,SAAS,GACT,MAAM,GACN,iBAAiB,GACjB,eAAe,GACf,YAAY,CAAC;AAIjB;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAC7C,MAAM,EACN;IACE,IAAI,EAAE,iBAAiB,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;CACnB,CAkEF,CAAC;AAIF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAoBhF;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAKzE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,MAAM,GACX;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAWrD"}

package/dist/server/metadata.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Metadata resolution for timber.js.
+ *
+ * Resolves metadata from a segment chain (layouts + page), applies title
+ * templates, shallow-merges entries, and produces head element descriptors.
+ *
+ * Resolution happens inside the render pass — React.cache is active,
+ * metadata is outside Suspense, and the flush point guarantees completeness.
+ *
+ * Rendering (Metadata → HeadElement[]) is in metadata-render.ts.
+ *
+ * See design/16-metadata.md
+ */
+import type { Metadata } from './types.js';
+export { renderMetadataToElements } from './metadata-render.js';
+/** A single metadata entry from a layout or page module. */
+export interface SegmentMetadataEntry {
+    /** The resolved metadata object (from static or async `metadata` export). */
+    metadata: Metadata;
+    /** Whether this entry is from the page (leaf) module. */
+    isPage: boolean;
+}
+/** Options for resolveMetadata. */
+export interface ResolveMetadataOptions {
+    /**
+     * When true, the page's metadata is discarded (simulating a render error)
+     * and `<meta name="robots" content="noindex">` is injected.
+     */
+    errorState?: boolean;
+}
+/** A rendered head element descriptor. */
+export interface HeadElement {
+    tag: 'title' | 'meta' | 'link';
+    content?: string;
+    attrs?: Record<string, string>;
+}
+/**
+ * Resolve a title value with an optional template.
+ *
+ * - string → apply template if present
+ * - { absolute: '...' } → use as-is, skip template
+ * - { default: '...' } → use as fallback (no template applied)
+ * - undefined → undefined
+ */
+export declare function resolveTitle(title: Metadata['title'], template: string | undefined): string | undefined;
+/**
+ * Resolve metadata from a segment chain.
+ *
+ * Processes entries from root layout to page (in segment order).
+ * The merge algorithm:
+ *   1. Shallow-merge all keys except title (later wins)
+ *   2. Track the most recent title template
+ *   3. Resolve the final title using the template
+ *
+ * In error state, the page entry is dropped and noindex is injected.
+ *
+ * See design/16-metadata.md §"Merge Algorithm"
+ */
+export declare function resolveMetadata(entries: SegmentMetadataEntry[], options?: ResolveMetadataOptions): Metadata;
+/**
+ * Resolve relative URLs in metadata fields against metadataBase.
+ *
+ * Returns a new metadata object with URLs resolved. Absolute URLs are not modified.
+ * If metadataBase is not set, returns the metadata unchanged.
+ */
+export declare function resolveMetadataUrls(metadata: Metadata): Metadata;
+//# sourceMappingURL=metadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/server/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAIhE,4DAA4D;AAC5D,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,QAAQ,EAAE,QAAQ,CAAC;IACnB,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,mCAAmC;AACnC,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,EACxB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,GAAG,SAAS,CAmBpB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,oBAAoB,EAAE,EAC/B,OAAO,GAAE,sBAA2B,GACnC,QAAQ,CAwDV;AAmBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAmFhE"}

package/dist/server/middleware-runner.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Middleware runner — executes a route's middleware.ts before rendering.
+ *
+ * Only the leaf route's middleware runs. There is no middleware chain.
+ * Middleware does NOT have next() — it either short-circuits with a Response
+ * or returns void to continue to access checks + render.
+ *
+ * See design/07-routing.md §"middleware.ts"
+ */
+import type { MiddlewareContext } from './types.js';
+/** Signature of a middleware.ts default export. */
+export type MiddlewareFn = (ctx: MiddlewareContext) => Response | void | Promise<Response | void>;
+/**
+ * Run a route's middleware function.
+ *
+ * @param middlewareFn - The default export from the route's middleware.ts
+ * @param ctx - The middleware context (req, params, headers, requestHeaders, searchParams)
+ * @returns A Response if middleware short-circuited, or undefined to continue
+ */
+export declare function runMiddleware(middlewareFn: MiddlewareFn, ctx: MiddlewareContext): Promise<Response | undefined>;
+//# sourceMappingURL=middleware-runner.d.ts.map

package/dist/server/middleware-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware-runner.d.ts","sourceRoot":"","sources":["../../src/server/middleware-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,mDAAmD;AACnD,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,iBAAiB,KAAK,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;AAElG;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,YAAY,EAC1B,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAM/B"}

package/dist/server/nuqs-ssr-provider.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Server-side nuqs adapter provider for SSR rendering.
+ *
+ * During SSR, `'use client'` components that call nuqs hooks (useQueryStates,
+ * useQueryState) need the nuqs adapter context. The client adapter
+ * (TimberNuqsAdapter) relies on `window` and React hooks that are
+ * client-only. This provider supplies a static, SSR-safe adapter
+ * that feeds the current request's search params into the nuqs context.
+ *
+ * The returned component wraps the React tree so that nuqs hooks render
+ * the correct initial values during server-side rendering. On the client,
+ * TimberNuqsAdapter (injected by browser-entry.ts) takes over.
+ *
+ * Design doc: design/23-search-params.md §"Custom Adapter"
+ */
+import { type ReactNode } from 'react';
+/**
+ * Wrap the SSR element tree with a nuqs adapter context.
+ *
+ * Called by ssr-entry.ts before passing the element to renderSsrStream.
+ * Takes the NavContext search params and provides them to nuqs hooks
+ * running during SSR so they render with the correct initial values.
+ *
+ * @param searchParamsRecord - The request's search params as a plain record
+ * @param children - The React element tree to wrap
+ */
+export declare function withNuqsSsrAdapter(searchParamsRecord: Record<string, string>, children: ReactNode): ReactNode;
+//# sourceMappingURL=nuqs-ssr-provider.d.ts.map

package/dist/server/nuqs-ssr-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nuqs-ssr-provider.d.ts","sourceRoot":"","sources":["../../src/server/nuqs-ssr-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AA2BtD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1C,QAAQ,EAAE,SAAS,GAClB,SAAS,CAMX"}

package/dist/server/pipeline.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Request pipeline — the central dispatch for all timber.js requests.
+ *
+ * Pipeline stages (in order):
+ *   proxy.ts → canonicalize → route match → 103 Early Hints → middleware.ts → render
+ *
+ * Each stage is a pure function or returns a Response to short-circuit.
+ * Each request gets a trace ID, structured logging, and OTEL spans.
+ *
+ * See design/07-routing.md §"Request Lifecycle", design/02-rendering-pipeline.md §"Request Flow",
+ * and design/17-logging.md §"Production Logging"
+ */
+import { type ProxyExport } from './proxy.js';
+import { type MiddlewareFn } from './middleware-runner.js';
+import type { SegmentNode } from '#/routing/types.js';
+/** Result of matching a canonical pathname against the route tree. */
+export interface RouteMatch {
+    /** The matched segment chain from root to leaf. */
+    segments: SegmentNode[];
+    /** Extracted route params (catch-all segments produce string[]). */
+    params: Record<string, string | string[]>;
+    /** The leaf segment's middleware.ts export, if any. */
+    middleware?: MiddlewareFn;
+}
+/** Function that matches a canonical pathname to a route. */
+export type RouteMatcher = (pathname: string) => RouteMatch | null;
+/** Function that matches a canonical pathname to a metadata route. */
+export type MetadataRouteMatcher = (pathname: string) => import('./route-matcher.js').MetadataRouteMatch | null;
+/** Context for intercepting route resolution (modal pattern). */
+export interface InterceptionContext {
+    /** The URL the user is navigating TO (the intercepted route). */
+    targetPathname: string;
+}
+/** Function that renders a matched route into a Response. */
+export type RouteRenderer = (req: Request, match: RouteMatch, responseHeaders: Headers, requestHeaderOverlay: Headers, interception?: InterceptionContext) => Response | Promise<Response>;
+/** Function that sends 103 Early Hints for a matched route. */
+export type EarlyHintsEmitter = (match: RouteMatch, req: Request, responseHeaders: Headers) => void | Promise<void>;
+export interface PipelineConfig {
+    /** The proxy.ts default export (function or array). Undefined if no proxy.ts. */
+    proxy?: ProxyExport;
+    /** Lazy loader for proxy.ts — called per-request so HMR updates take effect. */
+    proxyLoader?: () => Promise<{
+        default: ProxyExport;
+    }>;
+    /** Route matcher — resolves a canonical pathname to a RouteMatch. */
+    matchRoute: RouteMatcher;
+    /** Metadata route matcher — resolves metadata route pathnames (sitemap.xml, robots.txt, etc.) */
+    matchMetadataRoute?: MetadataRouteMatcher;
+    /** Renderer — produces the final Response for a matched route. */
+    render: RouteRenderer;
+    /** Renderer for no-match 404 — renders 404.tsx in root layout. */
+    renderNoMatch?: (req: Request, responseHeaders: Headers) => Response | Promise<Response>;
+    /** Early hints emitter — fires 103 hints after route match, before middleware. */
+    earlyHints?: EarlyHintsEmitter;
+    /** Whether to strip trailing slashes during canonicalization. Default: true. */
+    stripTrailingSlash?: boolean;
+    /** Slow request threshold in ms. Requests exceeding this emit a warning. 0 to disable. Default: 3000. */
+    slowRequestMs?: number;
+    /**
+     * Interception rewrites — conditional routes for the modal pattern.
+     * Generated at build time from intercepting route directories.
+     * See design/07-routing.md §"Intercepting Routes"
+     */
+    interceptionRewrites?: import('#/routing/interception.js').InterceptionRewrite[];
+    /**
+     * Dev pipeline error callback — called when a pipeline phase (proxy,
+     * middleware, render) catches an unhandled error. Used to wire the error
+     * into the Vite browser error overlay in dev mode.
+     *
+     * Undefined in production — zero overhead.
+     */
+    onPipelineError?: (error: Error, phase: string) => void;
+}
+/**
+ * Create the request handler from a pipeline configuration.
+ *
+ * Returns a function that processes an incoming Request through all pipeline stages
+ * and produces a Response. This is the top-level entry point for the server.
+ */
+export declare function createPipeline(config: PipelineConfig): (req: Request) => Promise<Response>;
+//# sourceMappingURL=pipeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/server/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAY,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AA6B1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAItD,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,uDAAuD;IACvD,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B;AAED,6DAA6D;AAC7D,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,CAAC;AAEnE,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,CACjC,QAAQ,EAAE,MAAM,KACb,OAAO,oBAAoB,EAAE,kBAAkB,GAAG,IAAI,CAAC;AAE5D,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,YAAY,CAAC,EAAE,mBAAmB,KAC/B,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GAAG,CAC9B,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,OAAO,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAI1B,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IACtD,qEAAqE;IACrE,UAAU,EAAE,YAAY,CAAC;IACzB,iGAAiG;IACjG,kBAAkB,CAAC,EAAE,oBAAoB,CAAC;IAC1C,kEAAkE;IAClE,MAAM,EAAE,aAAa,CAAC;IACtB,kEAAkE;IAClE,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzF,kFAAkF;IAClF,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,yGAAyG;IACzG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,2BAA2B,EAAE,mBAAmB,EAAE,CAAC;IACjF;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzD;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAmR1F"}

package/dist/server/prerender.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Pre-rendering types and utilities.
+ *
+ * A `prerender.ts` file in a route segment signals the framework to
+ * pre-render the route's shell at build time. This module defines the
+ * types that a user exports from `prerender.ts` and utilities for
+ * loading and validating those exports.
+ *
+ * Design doc: design/15-future-prerendering.md
+ */
+/**
+ * The shape of a prerender.ts module's exports.
+ *
+ * ```ts
+ * // app/docs/[slug]/prerender.ts
+ * export async function generateParams() {
+ *   return docs.map(d => ({ slug: d.slug }))
+ * }
+ * export const ttl = '1h'
+ * export const tags = ['docs']
+ * ```
+ */
+export interface PrerenderConfig {
+    /**
+     * Generate the set of params to pre-render at build time.
+     * Required for dynamic segments (`[param]`).
+     * Optional for static segments (the single URL is pre-rendered automatically).
+     */
+    generateParams?: () => Promise<Record<string, string>[]> | Record<string, string>[];
+    /**
+     * How long the pre-rendered shell is considered fresh.
+     * Accepts duration strings ('30s', '5m', '1h', '2d', '1w') or seconds as a number.
+     * Default: Infinity (cache until explicit invalidation).
+     */
+    ttl?: string | number;
+    /**
+     * Invalidation tags. Calling `revalidateTag('docs')` purges all
+     * pre-rendered shells with that tag.
+     */
+    tags?: string[];
+    /**
+     * Fallback strategy for dynamic routes without `generateParams`.
+     * Only valid in `output: 'static'` mode.
+     * - `'shell'`: emit a single pre-rendered shell that serves as client-side fallback
+     */
+    fallback?: 'shell';
+}
+export interface ResolvedPrerenderConfig {
+    /** TTL in seconds. Infinity if not set. */
+    ttlSeconds: number;
+    /** Invalidation tags */
+    tags: string[];
+    /** The generateParams function, if provided */
+    generateParams?: () => Promise<Record<string, string>[]> | Record<string, string>[];
+    /** Fallback strategy */
+    fallback?: 'shell';
+}
+/**
+ * Resolve raw prerender.ts exports into a normalized config.
+ *
+ * Validates:
+ * - `ttl` is a valid duration string or number
+ * - `tags` is an array of strings
+ * - `fallback` is 'shell' or undefined
+ */
+export declare function resolvePrerenderConfig(raw: PrerenderConfig): ResolvedPrerenderConfig;
+export interface PrerenderDiagnostic {
+    type: 'DYNAMIC_SEGMENT_NO_PARAMS';
+    segmentPath: string;
+    message: string;
+}
+/**
+ * Check if a dynamic segment has `generateParams` when prerender.ts is present.
+ * If not, emit a diagnostic — the route falls back to SSR.
+ */
+export declare function checkDynamicSegmentParams(segmentPath: string, isDynamic: boolean, hasGenerateParams: boolean, fallback?: 'shell'): PrerenderDiagnostic | null;
+//# sourceMappingURL=prerender.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prerender.d.ts","sourceRoot":"","sources":["../../src/server/prerender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAEpF;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEtB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAMD,MAAM,WAAW,uBAAuB;IACtC,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACpF,wBAAwB;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,GAAG,uBAAuB,CAsBpF;AAMD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,2BAA2B,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,EAClB,iBAAiB,EAAE,OAAO,EAC1B,QAAQ,CAAC,EAAE,OAAO,GACjB,mBAAmB,GAAG,IAAI,CAc5B"}