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

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

@@ -5,6 +5,17 @@
  * independently of the Vite RSC plugin runtime (which provides
  * createFromReadableStream for decoding RSC streams).
  *
+ * Uses a platform-adaptive rendering strategy:
+ * - **Node.js / Bun**: `renderToPipeableStream` — React pipes HTML chunks
+ *   through Node.js native streams (C++ implementation). Each chunk flows
+ *   through libuv buffers with zero Promise overhead.
+ * - **Cloudflare Workers / Edge**: `renderToReadableStream` — React outputs
+ *   to Web Streams which are V8-native C++ built-ins on these platforms.
+ *
+ * The detection is automatic at runtime. Both paths produce a Web
+ * `ReadableStream<Uint8Array>` so downstream transforms (injectHead,
+ * injectRscPayload, compression) work identically regardless of platform.
+ *
  * Design docs: 02-rendering-pipeline.md §"Single-Pass Rendering",
  *              18-build-system.md §"Entry Files"
  */
@@ -12,39 +23,73 @@ import type { ReactNode } from 'react';
 /**
  * Render a React element tree to a ReadableStream of HTML.
  *
- * Uses renderToReadableStream (NOT renderToString) for streaming SSR.
+ * Automatically selects the optimal rendering path for the platform:
+ * - Node.js/Bun: `renderToPipeableStream` → Node.js native streams → `Readable.toWeb()`
+ * - CF Workers/Edge: `renderToReadableStream` → native Web Streams
+ *
  * 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;
+    renderTimeoutMs?: number;
+    /** Request info threaded into render-error logs (method/path). */
+    requestInfo?: {
+        method: string;
+        path: string;
+    };
+    /**
+     * Fired synchronously when the render function is about to resolve
+     * (i.e. at hold-end / shell-ready). `resolved` reports whether Fizz's
+     * `stream.allReady` had already settled by that moment. Callers use
+     * this to decide whether signal promotion can be short-circuited.
+     * See NavContext._fizzAllReadyResolved.
+     */
+    onFizzAllReadyResolved?: (resolved: boolean) => void;
 }): Promise<ReadableStream<Uint8Array>>;
+/** Whether the current platform uses native Node.js streams for SSR. */
+export declare const useNodeStreams: boolean;
+/**
+ * Render via renderToPipeableStream, returning a Node.js Readable.
+ *
+ * The entire HTML rendering + post-processing pipeline stays in native
+ * Node.js streams (C++ backed). Only converted to Web ReadableStream
+ * at the very end for the Response body.
+ */
+export declare function renderSsrNodeStream(element: ReactNode, options?: {
+    bootstrapScriptContent?: string;
+    deferSuspenseFor?: number;
+    signal?: AbortSignal;
+    renderTimeoutMs?: number;
+    /** Request info threaded into render-error logs (method/path). */
+    requestInfo?: {
+        method: string;
+        path: string;
+    };
+    /**
+     * Fired synchronously at the moment `renderSsrNodeStream`'s returned
+     * Promise is about to resolve. `resolved` reports whether Fizz's
+     * `onAllReady` had already fired by then. See the twin callback on
+     * `renderSsrStream`.
+     */
+    onFizzAllReadyResolved?: (resolved: boolean) => void;
+}): Promise<import('node:stream').Readable>;
+/** Convert a Node.js Readable to a Web ReadableStream (zero-copy bridge). */
+export declare function nodeReadableToWeb(readable: import('node:stream').Readable): 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.
+ * React DOM's stream 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
@@ -56,12 +101,10 @@ export declare function wrapStreamWithErrorHandling(stream: ReadableStream<Uint8
  * 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.
+ * React 19.3+ automatically emits `<!DOCTYPE html>` when the root
+ * element is `<html>`, so no framework-level doctype prepending is needed.
  *
- * @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
+ * Sets content-type to text/html if not already set by middleware.
  */
 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

@@ -1 +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"}
+{"version":3,"file":"ssr-render.d.ts","sourceRoot":"","sources":["../../src/server/ssr-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAsFvC;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IACR,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,WAAW,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;CACtD,GACA,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAErC;AAED,wEAAwE;AACxE,eAAO,MAAM,cAAc,SAAkB,CAAC;AAU9C;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IACR,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,WAAW,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;CACtD,GACA,OAAO,CAAC,OAAO,aAAa,EAAE,QAAQ,CAAC,CAqGzC;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,OAAO,aAAa,EAAE,QAAQ,GACvC,cAAc,CAAC,UAAU,CAAC,CAE5B;AA2GD;;;;;;;;;;;;GAYG;AACH,2CAA2C;AAC3C,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,UAAU,CAAC,CA2B5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,OAAO,GACvB,QAAQ,CASV"}

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

@@ -0,0 +1,61 @@
+/**
+ * SSR wrapper components that match the client-side component tree depth.
+ *
+ * During hydration, React's useId() generates deterministic IDs based on
+ * the component's position in the fiber tree. If the SSR tree has fewer
+ * wrapper components than the client hydration tree, every useId() call
+ * produces different IDs — causing hydration mismatches in libraries like
+ * Radix UI that rely on useId() internally.
+ *
+ * The client tree (browser-entry.ts) wraps the RSC element with:
+ *   NavigationRoot → Fragment(TopLoader, ...) →
+ *     TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider → element
+ *
+ * The SSR tree must produce the same component boundaries. These wrappers
+ * are no-op components that render children directly but exist as fiber
+ * nodes to match the client's tree depth.
+ *
+ * **What actually shifts an id is a fork, not depth.** `useId` derives from
+ * React's tree context, which only changes where a fiber has more than one
+ * child — here, `Fragment(TopLoader, element)`. A single-child wrapper, plain
+ * component or context provider, leaves every id below it unchanged; that is
+ * verified, not assumed. So the client-only wrappers that take exactly one
+ * child — `SegmentUpdateContext.Provider`, and `PayloadRoot` with the params
+ * provider it renders (TIM-1297) — have no mirror here and need none. Mirror a
+ * new wrapper only if it branches.
+ *
+ * `PendingNavigationProvider` and its `SsrPendingProvider` mirror were both
+ * deleted with the dead pending context (TIM-1307). Removing them shifts no
+ * id: it was a single-child provider, the case the rule above covers.
+ *
+ * Related issues: facebook/react#24669, radix-ui/primitives#3700
+ * See design/02-rendering-pipeline.md §"RSC → SSR → Client Hydration"
+ */
+import { type ReactNode } from 'react';
+/**
+ * Wrap the SSR element tree with the same component boundaries as the
+ * client hydration tree. This ensures useId() generates matching IDs
+ * on both sides.
+ *
+ * Client tree (browser-entry.ts):
+ *   NavigationRoot
+ *     → Fragment(TopLoader, element)
+ *       → TimberNuqsAdapter
+ *         → NuqsAdapterProvider (from createAdapterProvider)
+ *           → NavigationProvider
+ *             → [RSC element]
+ *
+ * SSR tree (this function):
+ *   SsrNavigationRoot
+ *     → Fragment(SsrTopLoader, element)
+ *       → SsrNuqsWrapper
+ *         → NuqsAdapterProvider (from withNuqsSsrAdapter → createAdapterProvider)
+ *           → SsrNavigationProvider
+ *             → [RSC element]
+ *
+ * @param element - The decoded RSC element
+ * @param searchParams - Request search params for nuqs SSR adapter
+ * @param hasTopLoader - Whether the top loader is enabled (must match client config)
+ */
+export declare function wrapSsrElement(element: ReactNode, searchParams: Record<string, string>, hasTopLoader: boolean): ReactNode;
+//# sourceMappingURL=ssr-wrappers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-wrappers.d.ts","sourceRoot":"","sources":["../../src/server/ssr-wrappers.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAA2B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AA8DhE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,EAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,YAAY,EAAE,OAAO,GACpB,SAAS,CAgBX"}

package/dist/server/state-tree-diff.d.ts

@@ -13,31 +13,66 @@
  * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
  * See design/13-security.md §"State tree manipulation"
  */
+/** Parsed client state tree with segment paths and optional slot paths. */
+export interface ClientStateTree extends Set<string> {
+    slots?: Set<string> | null;
+    /**
+     * `app/` directory paths of the segments currently mounted on the client.
+     * Read only by interception scoping — never by the skip decisions.
+     * See design/07-routing.md §"Intercepting Routes" (TIM-1282).
+     */
+    treePaths?: Set<string> | null;
+}
 /**
  * Parse the X-Timber-State-Tree header from a request.
  *
- * Returns a Set of segment paths the client has cached, or null if
+ * Returns a Set of segment paths the client has cached (with an
+ * additional `slots` property for cached slot paths), or null if
  * the header is missing, malformed, or empty. Parsing happens before
  * renderToReadableStream — not inside the React render pass.
  *
- * @returns Set of sync segment paths, or null if no valid state tree
+ * @returns ClientStateTree with segments and slots, or null if no valid state tree
  */
-export declare function parseClientStateTree(req: Request): Set<string> | null;
+export declare function parseClientStateTree(req: Request): ClientStateTree | null;
 /**
  * Determine whether a segment's layout rendering can be skipped.
  *
  * A segment is skipped when ALL of the following are true:
- * 1. The client has the segment in its state tree (clientSegments contains urlPath)
- * 2. The layout is sync (not an async function — async layouts always re-render)
- * 3. The segment is NOT the leaf (pages are never cached across navigations)
+ * 1. The client sent a state tree (clientSegments is non-null)
+ * 2. The client has this segment cached (clientSegments contains urlPath)
+ * 3. The segment has a layout (otherwise nothing to skip)
+ * 4. The layout is sync (not an async function — async layouts may depend
+ *    on per-request data and must always re-render)
+ * 5. The segment is NOT the leaf (pages are never cached across navigations)
+ *
+ * Additional constraints enforced by the caller (buildRouteElement):
+ * - Must have a rendered layout below (so SegmentOutlet has content to show)
+ * - Skipped segments must form a contiguous prefix from root
  *
  * Access.ts still runs for skipped segments — this is enforced by the caller
- * (buildRouteElement) which runs all access checks before building the tree.
+ * which wraps with AccessGate regardless of skip status.
  *
- * @param urlPath - The segment's URL path (e.g., "/", "/dashboard")
+ * @param segmentKey - The segment's state-tree key from computeSegmentKeys()
  * @param layoutComponent - The loaded layout component function
  * @param isLeaf - Whether this is the leaf segment (page segment)
  * @param clientSegments - Set of paths from X-Timber-State-Tree, or null
  */
-export declare function shouldSkipSegment(_urlPath: string, _layoutComponent: ((...args: unknown[]) => unknown) | undefined, _isLeaf: boolean, _clientSegments: Set<string> | null): boolean;
+export declare function shouldSkipSegment(segmentKey: string, layoutComponent: ((...args: unknown[]) => unknown) | undefined, isLeaf: boolean, clientSegments: Set<string> | null): boolean;
+/**
+ * Determine whether a parallel route slot can be skipped.
+ *
+ * A slot is skipped when the destination content key — computed from the
+ * owning segment's URL parts, the slot name, the matched entry file, and
+ * the slot's extracted params — is in the set of keys the client advertised.
+ *
+ * This replaced URL-based departing/destination diffing in TIM-1370.
+ * The previous approach reconstructed the client's state by re-matching a
+ * departing URL against each slot's sub-tree, which was a recurring bug
+ * source because the reconstruction could drift from the client's actual
+ * mounted state. The key-based approach is a single set-membership check.
+ *
+ * This is a performance optimization only, NOT a security boundary.
+ * Slot access.ts always runs via SlotAccessGate regardless.
+ */
+export declare function shouldSkipSlot(contentKey: string, clientSlotKeys: Set<string> | null): boolean;
 //# sourceMappingURL=state-tree-diff.d.ts.map

package/dist/server/state-tree-diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-tree-diff.d.ts","sourceRoot":"","sources":["../../src/server/state-tree-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAarE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,EAC/D,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GAClC,OAAO,CAeT"}
+{"version":3,"file":"state-tree-diff.d.ts","sourceRoot":"","sources":["../../src/server/state-tree-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,2EAA2E;AAC3E,MAAM,WAAW,eAAgB,SAAQ,GAAG,CAAC,MAAM,CAAC;IAClD,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAwBzE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,EAC9D,MAAM,EAAE,OAAO,EACf,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACjC,OAAO,CAaT;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,OAAO,CAG9F"}

package/dist/server/static-generator.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Static site generator — enumerates routes and renders them to
+ * HTML + RSC flight payloads for `output: 'static'` mode.
+ *
+ * Runs INSIDE the built RSC bundle (same pattern as prebuilt-builder.ts)
+ * so it has access to the route manifest, page module loaders, and the
+ * request pipeline handler.
+ *
+ * For each page route:
+ *   - Renders HTML (Accept: text/html) for initial load
+ *   - Renders RSC flight (Accept: text/x-component) for client SPA nav
+ *
+ * For each API route (route.ts):
+ *   - Calls the GET handler and captures the response
+ *
+ * The caller (plugins/static-build.ts) handles file I/O — keeping
+ * node:fs out of the server bundle so it runs on Cloudflare Workers.
+ *
+ * Design docs: design/11-platform.md §"static output mode"
+ */
+import type { ManifestRoot, ManifestSegmentNode } from './route-matcher.js';
+/** A single rendered static page ready for the caller to write to disk. */
+export interface StaticPageEntry {
+    /** The URL path (e.g., "/about", "/blog/first-post"). */
+    urlPath: string;
+    /** HTTP status code from the response. */
+    status: number;
+    /** Response headers. */
+    headers: Record<string, string>;
+    /** The response body as bytes. */
+    body: Uint8Array;
+    /** Content type for choosing file extension. */
+    contentType: string;
+    /**
+     * Whether this is an RSC flight payload (for client navigation)
+     * vs an HTML page (for initial load).
+     */
+    kind: 'html' | 'rsc' | 'api';
+}
+/** An error encountered during static generation. */
+export interface StaticGenerationError {
+    urlPath: string;
+    message: string;
+    status?: number;
+}
+/** A redirect discovered during static generation. */
+export interface StaticRedirectEntry {
+    /** The source URL path (e.g., "/old-page"). */
+    from: string;
+    /** The redirect target (Location header value). */
+    to: string;
+    /** HTTP status code (301, 302, 307, 308). */
+    status: number;
+}
+/** Result of the static generation pass. */
+export interface StaticGenerationSummary {
+    /** Total pages rendered (HTML + RSC pairs count as 2). */
+    rendered: number;
+    /** Pages that failed to render. */
+    errors: StaticGenerationError[];
+    /** Redirects from middleware/proxy that need platform redirect rules. */
+    redirects: StaticRedirectEntry[];
+    /**
+     * Non-fatal problems the build should surface. Unlike `errors`, these do not
+     * fail the build — they name a degraded outcome the developer can act on
+     * (e.g. the not-found probe answering with something other than a 404).
+     */
+    warnings: string[];
+}
+export interface StaticGenerationOptions {
+    /** Called for each rendered page/asset. File I/O is the caller's job. */
+    onEntry: (entry: StaticPageEntry) => Promise<void>;
+    /** Progress/warning logger. */
+    log?: (message: string) => void;
+    /** Timeout per page render in milliseconds. Default: 30000. */
+    renderTimeoutMs?: number;
+    /**
+     * When true and no user-authored sitemap exists, the generator will
+     * render `/sitemap.xml` (and any paginated sub-sitemaps) through the
+     * handler to capture auto-generated sitemaps in the static output.
+     */
+    autoSitemapEnabled?: boolean;
+}
+interface StaticUrl {
+    urlPath: string;
+    kind: 'page' | 'api';
+}
+/**
+ * Walk the manifest tree and collect all concrete URLs to render.
+ *
+ * Static routes produce their URL directly. Dynamic routes call
+ * `generateStaticSegmentParams()` from the page module. Dynamic routes
+ * without the export are a build error in static mode.
+ */
+export declare function enumerateStaticUrls(root: ManifestSegmentNode, log: (message: string) => void, timeoutMs?: number): Promise<{
+    urls: StaticUrl[];
+    errors: StaticGenerationError[];
+}>;
+/**
+ * Generate all static pages from the route manifest.
+ *
+ * For each page: renders HTML (for initial load) and RSC flight (for SPA nav).
+ * For each API route: calls the GET handler.
+ *
+ * Must run inside the built RSC bundle — the handler and manifest are
+ * module instances from this bundle's graph.
+ */
+export declare function generateStaticSite(manifest: ManifestRoot, handler: (req: Request) => Promise<Response>, options: StaticGenerationOptions): Promise<StaticGenerationSummary>;
+/** Extract /sitemap/N.xml URLs from a sitemap index XML. */
+export declare function discoverSubSitemapUrls(xml: string): string[];
+export {};
+//# sourceMappingURL=static-generator.d.ts.map

package/dist/server/static-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-generator.d.ts","sourceRoot":"","sources":["../../src/server/static-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAgB,MAAM,oBAAoB,CAAC;AAc1F,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,kCAAkC;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;CAC9B;AAED,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,yEAAyE;IACzE,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,+BAA+B;IAC/B,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAID,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC9B,SAAS,GAAE,MAAkC,GAC5C,OAAO,CAAC;IAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAAC,MAAM,EAAE,qBAAqB,EAAE,CAAA;CAAE,CAAC,CA0HjE;AA6KD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,uBAAuB,CAAC,CAmOlC;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAe5D"}

package/dist/server/static-not-found.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 404.html generation for static builds.
+ *
+ * `404.html` is written unconditionally (design/11-platform.md item 7). When
+ * the not-found probe does not produce a usable page, the framework default
+ * status page is written instead and the reason is reported as a warning —
+ * a static deploy that silently shipped no 404 page fell back to the host's
+ * generic one, and nothing in the build output said so (TIM-1258).
+ *
+ * The classification lives here, apart from the generation orchestration, so
+ * it can be exercised directly: every branch is a different diagnosis handed
+ * to a developer, and a wrong one sends them to the wrong file.
+ */
+import type { ManifestSegmentNode } from './route-matcher.js';
+/**
+ * The probe path. `_timber/` is the framework's reserved prefix and
+ * `__not_found` is a private segment (double underscore), so user routes —
+ * including a catch-all `[...slug]` — cannot claim it.
+ */
+export declare const NOT_FOUND_PROBE_PATH = "/_timber/__not_found";
+/** URL path the static build maps to `404.html`. See plugins/static-build.ts. */
+export declare const NOT_FOUND_ENTRY_PATH = "/_timber_not_found";
+/** What the probe produced: a response, or the failure that replaced one. */
+export type NotFoundProbe = {
+    kind: 'response';
+    status: number;
+    body: Uint8Array;
+    headers: Record<string, string>;
+    contentType: string;
+} | {
+    kind: 'threw';
+    error: unknown;
+};
+export interface NotFoundResult {
+    /** Body to write as `404.html` — never empty. */
+    body: Uint8Array;
+    headers: Record<string, string>;
+    contentType: string;
+    /** Non-fatal problem to report, or null when the app rendered its own page. */
+    warning: string | null;
+    /** Build log line. Names *which* page was written. */
+    logLine: string;
+}
+/**
+ * Decide what to write as `404.html`, and what to tell the developer.
+ *
+ * @param probe  What requesting {@link NOT_FOUND_PROBE_PATH} produced.
+ * @param root   Root segment of the route manifest — the only thing that can
+ *               distinguish an absent not-found page from a broken one.
+ */
+export declare function resolveNotFoundPage(probe: NotFoundProbe, root: ManifestSegmentNode): NotFoundResult;
+//# sourceMappingURL=static-not-found.d.ts.map

package/dist/server/static-not-found.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-not-found.d.ts","sourceRoot":"","sources":["../../src/server/static-not-found.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GACrB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;CACrB,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AA8BD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,mBAAmB,GACxB,cAAc,CA6ChB"}

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

@@ -5,6 +5,12 @@
  * correct file to render by walking the fallback chain described in
  * design/10-error-handling.md §"Status-Code Files".
  *
+ * **Generic over `TFile`** (TIM-848). Walks `SegmentNode<TFile>` trees
+ * regardless of whether `TFile` is the build-time `RouteFile` or the
+ * runtime `ManifestFile`. Before TIM-848 there were two near-identical
+ * resolvers — one for the Map-based scanner output and one for the
+ * object-based runtime manifest. Now there is one.
+ *
  * Supports two format families:
  * - 'component' (default): .tsx/.jsx/.mdx status files → React rendering pipeline
  * - 'json': .json status files → raw JSON response, no React
@@ -13,28 +19,26 @@
  *
  * **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)
+ *   Pass 2 — error.tsx (leaf → root)
+ *   Pass 3 — framework default (returns null)
  *
- * **JSON chain (4xx):**
- *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
+ * **JSON chain (4xx and 5xx):**
+ *   Pass 1 — json status files (leaf → root): {status}.json → {category}.json
  *   Pass 2 — framework default JSON (returns null, caller provides bare JSON)
  *
- * **5xx (component only):**
+ * **5xx component:**
  *   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';
+import type { SegmentNode } from '../routing/types.js';
 /** How the status-code file was matched. */
-export type StatusFileKind = 'exact' | 'category' | 'legacy' | 'error';
+export type StatusFileKind = 'exact' | 'category' | '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 {
+export interface StatusFileResolution<TFile> {
     /** The matched route file. */
-    file: RouteFile;
+    file: TFile;
     /** The HTTP status code (always the original status, not the file's code). */
     status: number;
     /** How the file was matched. */
@@ -45,9 +49,9 @@ export interface StatusFileResolution {
 /** How a slot denial file was matched. */
 export type SlotDeniedKind = 'denied' | 'default';
 /** Result of resolving a slot denied file. */
-export interface SlotDeniedResolution {
+export interface SlotDeniedResolution<TFile> {
     /** The matched route file (denied.tsx or default.tsx). */
-    file: RouteFile;
+    file: TFile;
     /** Slot name without @ prefix. */
     slotName: string;
     /** How the file was matched. */
@@ -63,8 +67,15 @@ export interface SlotDeniedResolution {
  * @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'.
+ * @param maxIndex - Optional upper bound on the segment index to search.
+ *   When set, the resolver only considers segments `0..maxIndex` (inclusive),
+ *   skipping any segments deeper in the tree. Used by the deny renderers to
+ *   prevent resolving a status file below a denied segment — matching
+ *   `buildDenyPageChain`'s start-at-i semantics. The error renderers omit
+ *   this parameter, so the full chain is searched — a 500 from a leaf page
+ *   should use the leaf's own `5xx.tsx`. See TIM-1358.
  */
-export declare function resolveStatusFile(status: number, segments: ReadonlyArray<SegmentNode>, format?: StatusFileFormat): StatusFileResolution | null;
+export declare function resolveStatusFile<TFile>(status: number, segments: ReadonlyArray<SegmentNode<TFile>>, format?: StatusFileFormat, maxIndex?: number): StatusFileResolution<TFile> | null;
 /**
  * Resolve the denial file for a parallel route slot.
  *
@@ -73,5 +84,5 @@ export declare function resolveStatusFile(status: number, segments: ReadonlyArra
  *
  * @param slotNode - The segment node for the slot (segmentType === 'slot').
  */
-export declare function resolveSlotDenied(slotNode: SegmentNode): SlotDeniedResolution | null;
+export declare function resolveSlotDenied<TFile>(slotNode: SegmentNode<TFile>): SlotDeniedResolution<TFile> | null;
 //# sourceMappingURL=status-code-resolver.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"status-code-resolver.d.ts","sourceRoot":"","sources":["../../src/server/status-code-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,UAAU,GACV,OAAO,CAAC;AAEZ,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,MAAM,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,8BAA8B;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,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,CAAC,KAAK;IACzC,0DAA0D;IAC1D,IAAI,EAAE,KAAK,CAAC;IACZ,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;CACtB;AA4BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAC3C,MAAM,GAAE,gBAA8B,EACtC,QAAQ,CAAC,EAAE,MAAM,GAChB,oBAAoB,CAAC,KAAK,CAAC,GAAG,IAAI,CAKpC;AA6FD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,GAC3B,oBAAoB,CAAC,KAAK,CAAC,GAAG,IAAI,CAYpC"}

package/dist/server/stream-utils.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Stream utilities for the RSC rendering pipeline.
+ *
+ * teeWithErrorPropagation — wraps native ReadableStream.tee() with:
+ * 1. Cross-branch error propagation (error on one branch cancels the other)
+ * 2. Buffer divergence monitoring (warns + cancels when threshold exceeded)
+ *
+ * This prevents two classes of bugs:
+ * - Silent stalls when one tee branch errors and the other hangs indefinitely
+ * - Unbounded memory growth when one consumer (SSR) is much slower than the other
+ *
+ * Design doc: 02-rendering-pipeline.md §"RSC → SSR → Client Hydration"
+ */
+export interface TeeOptions {
+    /**
+     * Maximum byte divergence between the two branches before both are
+     * cancelled. When one branch has consumed this many more bytes than
+     * the other, the tee's internal buffer is at least this large.
+     *
+     * Default: 5MB.
+     */
+    maxBufferBytes?: number;
+}
+/**
+ * Tee a ReadableStream with error propagation and buffer monitoring.
+ *
+ * Delegates to the native `stream.tee()` for the actual forking, then wraps
+ * each branch in a ReadableStream that:
+ * - Tracks bytes consumed per branch
+ * - Cancels both branches if byte divergence exceeds `maxBufferBytes`
+ * - Cancels the other branch if either branch is cancelled or errors
+ *
+ * The returned streams are drop-in replacements for the native tee branches.
+ */
+export declare function teeWithErrorPropagation(stream: ReadableStream<Uint8Array>, options?: TeeOptions): [ReadableStream<Uint8Array>, ReadableStream<Uint8Array>];
+/**
+ * Wrap a response body with stream-lifecycle timing instrumentation.
+ *
+ * Logs firstChunk, lastChunk, close, maxGap (largest inter-chunk gap),
+ * chunk count, and byte count on stream termination (clean close OR
+ * cancellation/disconnect). Gated behind `serverTiming: 'detailed'`.
+ *
+ * Uses a manual reader pump to guarantee logging on all termination
+ * paths — TransformStream.flush() is not called on cancellation.
+ */
+export declare function wrapResponseWithStreamTiming(body: ReadableStream<Uint8Array>, startTime: number): ReadableStream<Uint8Array>;
+//# sourceMappingURL=stream-utils.d.ts.map

package/dist/server/stream-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-utils.d.ts","sourceRoot":"","sources":["../../src/server/stream-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,OAAO,CAAC,EAAE,UAAU,GACnB,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,CAmK1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,SAAS,EAAE,MAAM,GAChB,cAAc,CAAC,UAAU,CAAC,CA4D5B"}