@timber-js/app 0.1.0

package/dist/server/rsc-entry/helpers.d.ts

@@ -0,0 +1,73 @@
+/**
+ * RSC Entry Helpers — shared utilities for the RSC request handler.
+ *
+ * Small, stateless functions used across the RSC entry modules.
+ */
+import type { ManifestSegmentNode } from '#/server/route-matcher.js';
+import { RedirectSignal } from '#/server/primitives.js';
+/** RSC content type for client navigation payload requests. */
+export declare const RSC_CONTENT_TYPE = "text/x-component";
+/**
+ * Create a debug channel sink that discards all debug data.
+ *
+ * React Flight's dev mode serializes server component source code as `$E`
+ * entries for DevTools. Without a separate debugChannel, this data is
+ * embedded inline in the main RSC stream — leaking source code to the
+ * browser. By providing a debug channel, debug data goes to a separate
+ * stream that we drain and discard.
+ *
+ * See design/13-security.md §"Server component source leak"
+ *
+ * TODO: In the future, expose this debug data to the browser in dev mode
+ * for inline error overlays (e.g. component stack traces).
+ */
+export declare function createDebugChannelSink(): {
+    readable: ReadableStream;
+    writable: WritableStream;
+};
+/**
+ * Build segment metadata for the X-Timber-Segments response header.
+ * Describes the rendered segment chain with async status, enabling
+ * the client to populate its segment cache for state tree diffing.
+ *
+ * Async detection: server components defined as `async function` have
+ * constructor.name === 'AsyncFunction'. These layouts always re-render
+ * on navigation (they may depend on request context like cookies/params).
+ * See design/07-routing.md §"Server Diffing Rules".
+ */
+export declare function buildSegmentInfo(segments: ManifestSegmentNode[], layoutComponents: Array<{
+    component: (...args: unknown[]) => unknown;
+    segment: ManifestSegmentNode;
+}>): Array<{
+    path: string;
+    isAsync: boolean;
+}>;
+/**
+ * Check if a request is asking for an RSC payload (client navigation)
+ * rather than full HTML. Client-side navigation sends Accept: text/x-component.
+ */
+export declare function isRscPayloadRequest(req: Request): boolean;
+/**
+ * Build a redirect Response. For RSC payload requests (client navigation),
+ * return 204 + X-Timber-Redirect header instead of a raw 302. The browser's
+ * fetch with redirect: "manual" turns a 302 into an opaque redirect (status 0,
+ * null body, inaccessible headers), which crashes createFromFetch when it
+ * tries to call .body.getReader(). The X-Timber-Redirect header lets the
+ * client detect the redirect and perform a soft SPA navigation.
+ */
+export declare function buildRedirectResponse(req: Request, signal: RedirectSignal, responseHeaders: Headers): Response;
+/**
+ * Check if an error is an abort error (connection closed by client).
+ *
+ * When the browser aborts a request (page refresh, navigation away),
+ * the AbortSignal fires and React/streams throw an AbortError. This
+ * is not an application error — suppress it from error boundaries and logs.
+ */
+export declare function isAbortError(error: unknown): boolean;
+export declare function escapeHtml(str: string): string;
+/**
+ * Parse a Cookie header string into a name→value Map.
+ * Used to populate NavContext.cookies for SSR hooks (useCookie).
+ */
+export declare function parseCookiesFromHeader(header: string): Map<string, string>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/server/rsc-entry/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,IAAI;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,CAQ/F;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,KAAK,CAAC;IACtB,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B,CAAC,GACD,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CA0B3C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGzD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,cAAc,EACtB,eAAe,EAAE,OAAO,GACvB,QAAQ,CAOV;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAIpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAW1E"}

package/dist/server/rsc-entry/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Set the dev pipeline error handler.
+ *
+ * Called by the dev server after importing this module to wire pipeline
+ * errors into the Vite browser error overlay. No-op in production.
+ */
+export declare function setDevPipelineErrorHandler(handler: (error: Error, phase: string) => void): void;
+export { runWithEarlyHintsSender } from '#/server/early-hints-sender.js';
+declare const _default: (req: Request) => Promise<Response>;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/server/rsc-entry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA0EA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AA2lBD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;8BA3epD,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AA6ehD,wBAAiE"}

package/dist/server/rsc-entry/ssr-bridge.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SSR Bridge — loads the SSR entry and passes the RSC stream for HTML rendering.
+ */
+import type { NavContext } from '#/server/ssr-entry.js';
+export declare function callSsr(rscStream: ReadableStream<Uint8Array>, navContext: NavContext): Promise<Response>;
+//# sourceMappingURL=ssr-bridge.d.ts.map

package/dist/server/rsc-entry/ssr-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-bridge.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/ssr-bridge.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,wBAAsB,OAAO,CAC3B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAMnB"}

package/dist/server/slot-resolver.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Parallel slot resolution for RSC rendering.
+ *
+ * Resolves slot elements for a layout's parallel routes (@slot directories).
+ * Each slot either matches the current URL (renders its page) or doesn't
+ * match (renders default.tsx fallback).
+ *
+ * Slots are rendered within the single renderToReadableStream call as
+ * named props to their parent layout — no separate render passes.
+ *
+ * Each slot gets its own error boundaries (from error.tsx / status files
+ * along the matched slot segment chain) and layouts (from layout.tsx files
+ * in the slot's sub-tree). This enables independent error handling and
+ * chrome per slot.
+ *
+ * See design/02-rendering-pipeline.md §"Parallel Slots"
+ */
+import type { ManifestSegmentNode } from './route-matcher.js';
+import type { RouteMatch, InterceptionContext } from './pipeline.js';
+type CreateElementFn = (...args: unknown[]) => React.ReactElement;
+/**
+ * Resolve the element for a parallel slot.
+ *
+ * Finds a matching page in the slot's sub-tree for the current route.
+ * Falls back to default.tsx if no match, or null if no default.
+ *
+ * When a match is found, the element is wrapped with:
+ * 1. Error boundaries from each segment in the slot's matched chain
+ * 2. Layouts from each segment in the slot's matched chain
+ * 3. SlotAccessGate if the slot root has access.ts
+ */
+export declare function resolveSlotElement(slotNode: ManifestSegmentNode, match: RouteMatch, paramsPromise: Promise<Record<string, string | string[]>>, h: CreateElementFn, interception?: InterceptionContext): Promise<React.ReactElement | null>;
+export {};
+//# sourceMappingURL=slot-resolver.d.ts.map

package/dist/server/slot-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-resolver.d.ts","sourceRoot":"","sources":["../../src/server/slot-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAIrE,KAAK,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,KAAK,CAAC,YAAY,CAAC;AAElE;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,UAAU,EACjB,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,EACzD,CAAC,EAAE,eAAe,EAClB,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAqHpC"}

package/dist/server/ssr-entry.d.ts

@@ -0,0 +1,73 @@
+/**
+ * SSR Entry — Receives RSC stream and renders HTML with hydration markers.
+ *
+ * This is a real TypeScript file, not codegen. The RSC environment calls
+ * handleSsr() to convert the RSC stream + navigation context into
+ * an HTML Response with React hydration support.
+ *
+ * The RSC and SSR environments are separate Vite module graphs with
+ * separate module instances. Per-request state is explicitly passed
+ * via NavContext.
+ *
+ * Design docs: 18-build-system.md §"Entry Files", 02-rendering-pipeline.md
+ */
+/**
+ * Navigation context passed from the RSC environment to SSR.
+ *
+ * Per-request state must be explicitly passed across the RSC→SSR
+ * environment boundary since they are separate Vite module graphs.
+ */
+export interface NavContext {
+    /** The requested pathname */
+    pathname: string;
+    /** Extracted route params (catch-all segments produce string[]) */
+    params: Record<string, string | string[]>;
+    /** Search params from the URL */
+    searchParams: Record<string, string>;
+    /** The committed HTTP status code */
+    statusCode: number;
+    /** Response headers from middleware/proxy */
+    responseHeaders: Headers;
+    /** Pre-rendered metadata HTML to inject before </head> */
+    headHtml: string;
+    /** Inline JS for React's bootstrapScriptContent — kicks off module loading */
+    bootstrapScriptContent: string;
+    /** Tee'd RSC stream for client-side hydration (inlined into HTML) */
+    rscStream?: ReadableStream<Uint8Array>;
+    /** Max Suspense hold window (ms). SSR delays the first flush by this
+     *  duration, racing allReady so that fast-resolving boundaries render inline
+     *  without ever showing a fallback. Derived from route `deferSuspenseFor` exports.
+     *  See design/05-streaming.md §"deferSuspenseFor". */
+    deferSuspenseFor?: number;
+    /** Request abort signal. When the client disconnects (page refresh,
+     *  navigation away), this signal fires. Passed to renderToReadableStream
+     *  so React stops rendering and doesn't fire error boundaries for aborts. */
+    signal?: AbortSignal;
+    /** Request cookies as name→value pairs. Used by useCookie() during SSR
+     *  to return correct cookie values before hydration. */
+    cookies?: Map<string, string>;
+}
+/**
+ * Handle SSR: decode an RSC stream and render it to hydration-ready HTML.
+ *
+ * Steps:
+ * 1. Decode the RSC stream into a React element tree via createFromReadableStream
+ *    (resolves "use client" references to actual component modules for SSR)
+ * 2. Render the decoded tree to HTML via renderToReadableStream (streaming)
+ * 3. Wait for onShellReady before flushing (handled by renderSsrStream)
+ * 4. Inject metadata into <head> and client scripts before </body>
+ * 5. Return Response with navContext.statusCode and navContext.responseHeaders
+ *
+ * The RSC stream is piped progressively — not buffered. For deny() outside
+ * Suspense, the RSC stream encodes an error in the shell region, causing
+ * renderToReadableStream to reject. The error propagates back to the RSC
+ * entry which renders the deny page. For deny() inside Suspense, the shell
+ * succeeds and the error streams as a React error boundary after flush.
+ *
+ * @param rscStream - The ReadableStream from the RSC environment
+ * @param navContext - Per-request state passed across RSC→SSR boundary
+ * @returns A Response containing the HTML stream with hydration markers
+ */
+export declare function handleSsr(rscStream: ReadableStream<Uint8Array>, navContext: NavContext): Promise<Response>;
+export default handleSsr;
+//# sourceMappingURL=ssr-entry.d.ts.map

package/dist/server/ssr-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA2BH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC;;;0DAGsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;4DACwD;IACxD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CA0DnB;AAED,eAAe,SAAS,CAAC"}

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

@@ -0,0 +1,67 @@
+/**
+ * SSR rendering utilities — testable core of the SSR entry.
+ *
+ * Extracted from ssr-entry.ts so the rendering logic can be tested
+ * independently of the Vite RSC plugin runtime (which provides
+ * createFromReadableStream for decoding RSC streams).
+ *
+ * Design docs: 02-rendering-pipeline.md §"Single-Pass Rendering",
+ *              18-build-system.md §"Entry Files"
+ */
+import type { ReactNode } from 'react';
+/**
+ * Render a React element tree to a ReadableStream of HTML.
+ *
+ * Uses renderToReadableStream (NOT renderToString) for streaming SSR.
+ * The returned stream begins yielding after onShellReady — everything
+ * outside <Suspense> boundaries is in the shell.
+ *
+ * With progressive streaming, the RSC stream is piped directly to SSR
+ * without buffering. If deny() was called outside a Suspense boundary,
+ * the RSC stream encodes an error in the shell — renderToReadableStream
+ * rejects, and the RSC entry catches this to render a deny page with
+ * the correct HTTP status code. If deny() was inside Suspense, the shell
+ * succeeds (200 committed) and the error streams as an error boundary.
+ *
+ * @param element - The React element tree decoded from the RSC stream
+ * @param options - Optional configuration
+ * @param options.bootstrapScriptContent - Inline JS injected by React as a
+ *   non-deferred `<script>` in the shell HTML. Executes immediately during
+ *   parsing — even while Suspense boundaries are still streaming. Used to
+ *   kick off module loading via dynamic `import()` so hydration can start
+ *   before the HTML stream closes.
+ * @returns A ReadableStream of HTML bytes with hydration markers
+ */
+export declare function renderSsrStream(element: ReactNode, options?: {
+    bootstrapScriptContent?: string;
+    deferSuspenseFor?: number;
+    signal?: AbortSignal;
+}): Promise<ReadableStream<Uint8Array>>;
+/**
+ * Wrap an HTML stream with error handling for the streaming phase.
+ *
+ * During progressive RSC→SSR streaming, errors in Suspense boundaries
+ * (e.g. deny() inside Suspense, throws in async components) cause
+ * React DOM's renderToReadableStream to error after the shell has been
+ * flushed. Without this wrapper, the stream error becomes an unhandled
+ * promise rejection that crashes the process.
+ *
+ * The wrapper catches streaming-phase errors, logs them, and closes
+ * the output stream cleanly. The shell (headers, status code, content
+ * outside Suspense) has already been sent to the client.
+ */
+/** @internal Exported for testing only. */
+export declare function wrapStreamWithErrorHandling(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): ReadableStream<Uint8Array>;
+/**
+ * Build a Response from the SSR HTML stream with the correct
+ * status code and headers from the navigation context.
+ *
+ * Sets content-type to text/html if not already set by middleware.
+ *
+ * @param htmlStream - The HTML stream from renderSsrStream
+ * @param statusCode - The committed HTTP status code from RSC
+ * @param responseHeaders - Response headers from middleware/proxy
+ * @returns A Response ready to send to the client
+ */
+export declare function buildSsrResponse(htmlStream: ReadableStream<Uint8Array>, statusCode: number, responseHeaders: Headers): Response;
+//# sourceMappingURL=ssr-render.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-render.d.ts","sourceRoot":"","sources":["../../src/server/ssr-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAmBvC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IAAE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAC7F,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAmDrC;AAED;;;;;;;;;;;;GAYG;AACH,2CAA2C;AAC3C,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,UAAU,CAAC,CAkC5B;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,OAAO,GACvB,QAAQ,CASV"}

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

@@ -0,0 +1,77 @@
+/**
+ * Status-code file resolver for timber.js error/denial rendering.
+ *
+ * Given an HTTP status code and a matched segment chain, resolves the
+ * correct file to render by walking the fallback chain described in
+ * design/10-error-handling.md §"Status-Code Files".
+ *
+ * Supports two format families:
+ * - 'component' (default): .tsx/.jsx/.mdx status files → React rendering pipeline
+ * - 'json': .json status files → raw JSON response, no React
+ *
+ * Fallback chains operate within the same format family (no cross-format fallback).
+ *
+ * **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)
+ *
+ * **5xx (component only):**
+ *   Per-segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
+ *   Then global-error.tsx (future)
+ *   Then framework default (returns null)
+ */
+import type { SegmentNode, RouteFile } from '#/routing/types.js';
+/** How the status-code file was matched. */
+export type StatusFileKind = 'exact' | 'category' | 'legacy' | 'error';
+/** Response format family for status-code resolution. */
+export type StatusFileFormat = 'component' | 'json';
+/** Result of resolving a status-code file for a segment chain. */
+export interface StatusFileResolution {
+    /** The matched route file. */
+    file: RouteFile;
+    /** The HTTP status code (always the original status, not the file's code). */
+    status: number;
+    /** How the file was matched. */
+    kind: StatusFileKind;
+    /** Index into the segments array where the file was found. */
+    segmentIndex: number;
+}
+/** How a slot denial file was matched. */
+export type SlotDeniedKind = 'denied' | 'default';
+/** Result of resolving a slot denied file. */
+export interface SlotDeniedResolution {
+    /** The matched route file (denied.tsx or default.tsx). */
+    file: RouteFile;
+    /** Slot name without @ prefix. */
+    slotName: string;
+    /** How the file was matched. */
+    kind: SlotDeniedKind;
+}
+/**
+ * Resolve the status-code file to render for a given HTTP status code.
+ *
+ * Walks the segment chain from leaf to root following the fallback chain
+ * defined in design/10-error-handling.md. Returns null if no file is found
+ * (caller should render the framework default).
+ *
+ * @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 resolveStatusFile(status: number, segments: ReadonlyArray<SegmentNode>, format?: StatusFileFormat): StatusFileResolution | null;
+/**
+ * Resolve the denial file for a parallel route slot.
+ *
+ * Slot denial is graceful degradation — no HTTP status on the wire.
+ * Fallback chain: denied.tsx → default.tsx → null.
+ *
+ * @param slotNode - The segment node for the slot (segmentType === 'slot').
+ */
+export declare function resolveSlotDenied(slotNode: SegmentNode): SlotDeniedResolution | null;
+//# sourceMappingURL=status-code-resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"status-code-resolver.d.ts","sourceRoot":"","sources":["../../src/server/status-code-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAIjE,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,UAAU,GACV,QAAQ,GACR,OAAO,CAAC;AAEZ,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,MAAM,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,8BAA8B;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,IAAI,EAAE,SAAS,CAAC;IAChB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;CACtB;AAgBD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,EACpC,MAAM,GAAE,gBAA8B,GACrC,oBAAoB,GAAG,IAAI,CAS7B;AA2JD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,WAAW,GAAG,oBAAoB,GAAG,IAAI,CAYpF"}

package/dist/server/tracing.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.
+ *
+ * traceId() is always available in server code (middleware, access, components, actions).
+ * Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,
+ * or a crypto.randomUUID()-derived fallback otherwise.
+ *
+ * See design/17-logging.md §"trace_id is Always Set"
+ */
+export interface TraceStore {
+    /** 32-char lowercase hex trace ID (OTEL or UUID fallback). */
+    traceId: string;
+    /** OTEL span ID if available, undefined otherwise. */
+    spanId?: string;
+}
+/**
+ * Returns the current request's trace ID — always a 32-char lowercase hex string.
+ *
+ * With OTEL: the real OTEL trace ID (matches Jaeger/Honeycomb/Datadog).
+ * Without OTEL: crypto.randomUUID() with hyphens stripped.
+ *
+ * Throws if called outside a request context (no ALS store).
+ */
+export declare function traceId(): string;
+/**
+ * Returns the current OTEL span ID if available, undefined otherwise.
+ */
+export declare function spanId(): string | undefined;
+/**
+ * Generate a 32-char lowercase hex ID from crypto.randomUUID().
+ * Same format as OTEL trace IDs — zero-friction upgrade path.
+ */
+export declare function generateTraceId(): string;
+/**
+ * Run a callback within a trace context. Used by the pipeline to establish
+ * per-request ALS scope.
+ */
+export declare function runWithTraceId<T>(id: string, fn: () => T): T;
+/**
+ * Replace the trace ID in the current ALS store. Used when OTEL creates
+ * a root span and we want to switch from the UUID fallback to the real
+ * OTEL trace ID.
+ */
+export declare function replaceTraceId(newTraceId: string, newSpanId?: string): void;
+/**
+ * Update the span ID in the current ALS store. Used when entering a new
+ * OTEL span to keep log–trace correlation accurate.
+ */
+export declare function updateSpanId(newSpanId: string | undefined): void;
+/**
+ * Get the current trace store, or undefined if outside a request context.
+ * Framework-internal — use traceId()/spanId() in user code.
+ */
+export declare function getTraceStore(): TraceStore | undefined;
+/**
+ * Initialize a minimal OTEL SDK in dev mode so spans are recorded and
+ * fed to the DevSpanProcessor for dev log output.
+ *
+ * If the user already configured an OTEL SDK in register(), we add
+ * our DevSpanProcessor alongside theirs. If no SDK is configured,
+ * we create a BasicTracerProvider with our processor.
+ *
+ * Only called in dev mode — zero overhead in production.
+ */
+export declare function initDevTracing(config: import('./dev-logger.js').DevLoggerConfig): Promise<void>;
+/**
+ * Get the timber.js OTEL tracer. Returns null if @opentelemetry/api is not available.
+ */
+export declare function getTracer(): Promise<import('@opentelemetry/api').Tracer | null>;
+/**
+ * Run a function within an OTEL span. If OTEL is not available, runs the function
+ * directly without any span overhead.
+ *
+ * Automatically:
+ * - Creates the span as a child of the current context
+ * - Updates the ALS span ID for log–trace correlation
+ * - Ends the span when the function completes
+ * - Records exceptions on error
+ */
+export declare function withSpan<T>(name: string, attributes: Record<string, string | number | boolean>, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Set an attribute on the current active span (if any).
+ * Used for setting span attributes after span creation (e.g. timber.result on access spans).
+ */
+export declare function setSpanAttribute(key: string, value: string | number | boolean): Promise<void>;
+/**
+ * Add a span event to the current active span (if any).
+ * Used for timber.cache HIT/MISS events — recorded as span events, not child spans.
+ */
+export declare function addSpanEvent(name: string, attributes?: Record<string, string | number | boolean>): Promise<void>;
+/**
+ * Try to extract the OTEL trace ID from the current active span context.
+ * Returns undefined if OTEL is not active or no span exists.
+ */
+export declare function getOtelTraceId(): Promise<{
+    traceId: string;
+    spanId: string;
+} | undefined>;
+//# sourceMappingURL=tracing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/server/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;GAOG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAShC;AAED;;GAEG;AACH,wBAAgB,MAAM,IAAI,MAAM,GAAG,SAAS,CAE3C;AAID;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAM3E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,SAAS,CAEtD;AAID;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,OAAO,iBAAiB,EAAE,eAAe,GAChD,OAAO,CAAC,IAAI,CAAC,CA4Bf;AA4BD;;GAEG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,OAAO,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC,CAUrF;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EACrD,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAC/B,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAc/F"}

package/dist/server/tree-builder.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Element tree construction for timber.js rendering.
+ *
+ * Builds a unified React element tree from a matched segment chain, bottom-up:
+ *   page → status-code error boundaries → access gates → layout → repeat up segment chain
+ *
+ * The tree is rendered via a single `renderToReadableStream` call,
+ * giving one `React.cache` scope for the entire route.
+ *
+ * See design/02-rendering-pipeline.md §"Element Tree Construction"
+ */
+import type { SegmentNode, RouteFile } from '#/routing/types.js';
+/** A loaded module for a route file convention. */
+export interface LoadedModule {
+    /** The default export (component, access function, etc.) */
+    default?: unknown;
+    /** Named exports (for route.ts method handlers, metadata, etc.) */
+    [key: string]: unknown;
+}
+/** Function that loads a route file's module. */
+export type ModuleLoader = (file: RouteFile) => LoadedModule | Promise<LoadedModule>;
+/** A React element — kept opaque to avoid a React dependency in this module. */
+export type ReactElement = any;
+/** Function that creates a React element. Matches React.createElement signature. */
+export type CreateElement = (type: unknown, props: Record<string, unknown> | null, ...children: unknown[]) => ReactElement;
+/**
+ * Resolved slot content for a layout.
+ * Key is slot name (without @), value is the element tree for that slot.
+ */
+export type SlotElements = Map<string, ReactElement>;
+/** Configuration for the tree builder. */
+export interface TreeBuilderConfig {
+    /** The matched segment chain from root to leaf. */
+    segments: SegmentNode[];
+    /** Route params extracted by the matcher (catch-all segments produce string[]). */
+    params: Record<string, string | string[]>;
+    /** Parsed search params (typed or URLSearchParams). */
+    searchParams: unknown;
+    /** Loads a route file's module. */
+    loadModule: ModuleLoader;
+    /** React.createElement or equivalent. */
+    createElement: CreateElement;
+}
+/**
+ * Framework-injected access gate component.
+ *
+ * When `verdict` is provided (from the pre-render pass), AccessGate replays
+ * the stored result synchronously — no re-execution, no async, immune to
+ * Suspense timing. When `verdict` is absent, falls back to calling `accessFn`
+ * (backward compat for tree-builder.ts which doesn't run a pre-render pass).
+ */
+export interface AccessGateProps {
+    accessFn: (ctx: {
+        params: Record<string, string | string[]>;
+        searchParams: unknown;
+    }) => unknown;
+    params: Record<string, string | string[]>;
+    searchParams: unknown;
+    /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
+    segmentName?: string;
+    /**
+     * Pre-computed verdict from the pre-render pass. When set, AccessGate
+     * replays this verdict synchronously instead of calling accessFn.
+     * - 'pass': render children
+     * - DenySignal/RedirectSignal: throw synchronously
+     */
+    verdict?: 'pass' | import('./primitives.js').DenySignal | import('./primitives.js').RedirectSignal;
+    children: ReactElement;
+}
+/**
+ * Framework-injected slot access gate component.
+ * On denial, renders denied.tsx → default.tsx → null instead of failing the page.
+ */
+export interface SlotAccessGateProps {
+    accessFn: (ctx: {
+        params: Record<string, string | string[]>;
+        searchParams: unknown;
+    }) => unknown;
+    params: Record<string, string | string[]>;
+    searchParams: unknown;
+    deniedFallback: ReactElement | null;
+    defaultFallback: ReactElement | null;
+    children: ReactElement;
+}
+/**
+ * Framework-injected error boundary wrapper.
+ * Wraps content with status-code error boundary handling.
+ */
+export interface ErrorBoundaryProps {
+    fallbackComponent: ReactElement | null;
+    status?: number;
+    children: ReactElement;
+}
+/**
+ * Result of building the element tree.
+ */
+export interface TreeBuildResult {
+    /** The root React element tree ready for renderToReadableStream. */
+    tree: ReactElement;
+    /** Whether the leaf segment is a route.ts (API endpoint) rather than a page. */
+    isApiRoute: boolean;
+}
+/**
+ * Build the unified element tree from a matched segment chain.
+ *
+ * Construction is bottom-up:
+ *   1. Start with the page component (leaf segment)
+ *   2. Wrap in status-code error boundaries (fallback chain)
+ *   3. Wrap in AccessGate (if segment has access.ts)
+ *   4. Pass as children to the segment's layout
+ *   5. Repeat up the segment chain to root
+ *
+ * Parallel slots are resolved at each layout level and composed as named props.
+ */
+export declare function buildElementTree(config: TreeBuilderConfig): Promise<TreeBuildResult>;
+//# sourceMappingURL=tree-builder.d.ts.map

package/dist/server/tree-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-builder.d.ts","sourceRoot":"","sources":["../../src/server/tree-builder.ts"],"names":[],"mappings":"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"}