@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

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.ts';
+/** 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;AAgB1F,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;AAqID;;;;;;;;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.ts';
+/**
+ * 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.ts';
 /** 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,59 @@
+/**
+ * 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>;
+/**
+ * Read a byte stream to completion under one overall deadline and return
+ * the concatenated bytes. Every read is raced against the time remaining,
+ * and the reader is cancelled on every exit, so a stalled upstream never
+ * outlives the deadline. See design/02-rendering-pipeline.md §"Always
+ * Timeout-Guard Stream Reads".
+ *
+ * @param label - Prefix for the timeout error message. Both ways the deadline
+ *   can pass (between reads, or while a read is pending) reject with the same
+ *   `${label} did not complete within ${timeoutMs}ms`.
+ */
+export declare function readAllBytesWithDeadline(stream: ReadableStream<Uint8Array>, timeoutMs: number, label: string): Promise<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;AAOH,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,CA8D5B;AASD;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,UAAU,CAAC,CAkCrB"}

package/dist/server/tracing.d.ts

@@ -1,14 +1,14 @@
 /**
  * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.
  *
- * traceId() is always available in server code (middleware, access, components, actions).
+ * getTraceId() 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"
  */
-import { type TraceStore } from './als-registry.js';
-export type { TraceStore } from './als-registry.js';
+import { type TraceStore } from './als-registry.ts';
+export type { TraceStore } from './als-registry.ts';
 /**
  * Returns the current request's trace ID — always a 32-char lowercase hex string.
  *
@@ -17,11 +17,11 @@ export type { TraceStore } from './als-registry.js';
  *
  * Throws if called outside a request context (no ALS store).
  */
-export declare function traceId(): string;
+export declare function getTraceId(): string;
 /**
  * Returns the current OTEL span ID if available, undefined otherwise.
  */
-export declare function spanId(): string | undefined;
+export declare function getSpanId(): string | undefined;
 /**
  * Generate a 32-char lowercase hex ID from crypto.randomUUID().
  * Same format as OTEL trace IDs — zero-friction upgrade path.
@@ -33,19 +33,15 @@ export declare function generateTraceId(): string;
  */
 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.
+ * Replace the request's trace ID. Used when OTEL creates the root span and
+ * we want to switch from the UUID fallback to the real OTEL trace ID. Writes
+ * the request's shared trace, so every scope in the request sees it —
+ * including the ones outside the span this runs in.
  */
-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;
+export declare function replaceTraceId(newTraceId: string): void;
 /**
  * Get the current trace store, or undefined if outside a request context.
- * Framework-internal — use traceId()/spanId() in user code.
+ * Framework-internal — use getTraceId()/getSpanId() in user code.
  */
 export declare function getTraceStore(): TraceStore | undefined;
 /**
@@ -56,22 +52,59 @@ export declare function getTraceStore(): TraceStore | undefined;
  * 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.
+ * Idempotent across module re-evaluations (HMR) — only the first call
+ * registers. Called in dev, and in production only when TIMBER_DEBUG is
+ * set — otherwise production never loads the OTEL SDK.
  */
-export declare function initDevTracing(config: import('./dev-logger.js').DevLoggerConfig): Promise<void>;
+export declare function initDevTracing(config: import('../dev-tools/logger.ts').DevLoggerConfig): Promise<void>;
+/**
+ * A native platform span. Mirrors the subset of the Cloudflare Workers
+ * `Span` API that timber uses. See design/17-logging.md §"Cloudflare Native
+ * Spans" and TIM-1135.
+ */
+export interface PlatformSpan {
+    setAttribute(key: string, value: string | number | boolean): void;
+}
+/**
+ * Adapter-provided native tracer. Callback-scoped like Cloudflare's
+ * `tracing.enterSpan()` — the span starts when the callback is invoked and
+ * ends when it returns or its promise settles. Nesting follows the
+ * platform's async context.
+ *
+ * When registered, withSpan() wraps every framework span in a native span
+ * *in addition to* the OTEL emission — dual emission, so external OTEL
+ * collectors keep working alongside the platform's native trace view.
+ *
+ * Register via setPlatformTracer(), or by writing the
+ * Symbol.for('timber:platform-tracer') key on globalThis from
+ * adapter-generated entry code (what the Cloudflare _worker.js does).
+ */
+export interface PlatformTracer {
+    enterSpan<T>(name: string, fn: (span: PlatformSpan) => T): T;
+}
+/** Register (or clear) the native platform tracer for this runtime. */
+export declare function setPlatformTracer(tracer: PlatformTracer | undefined): void;
+/** The registered native platform tracer, if any. */
+export declare function getPlatformTracer(): PlatformTracer | undefined;
 /**
  * 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.
+ * Run a function within a framework span. Composes two emission channels:
+ *
+ * - **Native platform span** — when an adapter registered a PlatformTracer
+ *   (Cloudflare Workers), the fn is wrapped in platformTracer.enterSpan()
+ *   so it appears in the platform's native trace view.
+ * - **OTEL span** — when an OTEL SDK is active, the fn also runs inside an
+ *   OTEL span (dual emission). No SDK and no platform tracer = zero overhead.
  *
  * Automatically:
  * - Creates the span as a child of the current context
- * - Updates the ALS span ID for log–trace correlation
+ * - Runs fn in its own trace scope carrying the span's IDs, for log–trace
+ *   correlation and setSpanAttribute()
  * - Ends the span when the function completes
- * - Records exceptions on error
+ * - Records exceptions on error (OTEL channel)
  */
 export declare function withSpan<T>(name: string, attributes: Record<string, string | number | boolean>, fn: () => T | Promise<T>): Promise<T>;
 /**
@@ -96,10 +129,8 @@ export declare function addSpanEvent(name: string, attributes?: Record<string, s
 export declare function addSpanEventSync(name: string, attributes?: Record<string, string | number | boolean>): 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.
+ * Returns undefined if OTEL is not active or no span exists. (The span ID
+ * reaches logs through the span's own trace scope, not from here.)
  */
-export declare function getOtelTraceId(): Promise<{
-    traceId: string;
-    spanId: string;
-} | undefined>;
+export declare function getOtelTraceId(): Promise<string | undefined>;
 //# sourceMappingURL=tracing.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/server/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG9D,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAIpD;;;;;;;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;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,IAAI,CASN;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAc/F"}
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/server/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG9D,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAIpD;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,MAAM,CASnC;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;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;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAKvD;AAiBD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,SAAS,CAEtD;AAcD;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,OAAO,wBAAwB,EAAE,eAAe,GACvD,OAAO,CAAC,IAAI,CAAC,CAsBf;AAID;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CACnE;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,CAAC,GAAG,CAAC,CAAC;CAC9D;AAOD,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAE1E;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AA4BD;;GAEG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,OAAO,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC,CAUrF;AAED;;;;;;;;;;;;;;;GAeG;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,CAeZ;AAwCD;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAC/B,OAAO,CAAC,IAAI,CAAC,CAcf;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;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,IAAI,CASN;AAED;;;;GAIG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAclE"}

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

@@ -0,0 +1,59 @@
+/**
+ * Shared URL-matching tree walker for segment trees.
+ *
+ * Both the main route matcher (`route-matcher.ts`) and slot resolver
+ * (`slot-resolver.ts`) need to walk a SegmentNode tree, matching URL
+ * parts against children with the same priority semantics:
+ *
+ *   static > dynamic > catch-all > optional-catch-all
+ *
+ * Before this module, each had its own walker with subtle divergences
+ * (different group handling, missing backtracking, incomplete
+ * optional-catch-all support). This shared walker is the single
+ * source of truth for URL-to-segment matching.
+ *
+ * See design/07-routing.md §"Request Lifecycle" and TIM-940.
+ */
+import type { SegmentNode } from '../routing/types.ts';
+/** Result of matching URL parts against a segment tree. */
+export interface TreeMatchResult<TFile> {
+    /** Matched segment chain from root to leaf, inclusive. */
+    chain: SegmentNode<TFile>[];
+    /** Collected params, keyed by param name. Catch-all params are string[]. */
+    params: Record<string, string | string[]>;
+}
+export interface TreeMatchOptions {
+    /**
+     * When true (default), only match if the leaf node has a page or route
+     * handler. Set to false for metadata route matching, where we just need
+     * to find the owning segment regardless of whether it has a page.
+     */
+    requireTerminal?: boolean;
+}
+/**
+ * Match URL path parts against a segment tree.
+ *
+ * Walks the tree depth-first with backtracking, applying priority
+ * ordering globally across group boundaries. Returns the matched
+ * segment chain and collected params, or null if no route matches.
+ *
+ * By default, a match requires a terminal node (one with `page` or
+ * `route`) at the leaf. Pass `{ requireTerminal: false }` to match
+ * any segment (used by metadata route matching).
+ *
+ * @param root  The root segment node to start matching from.
+ * @param parts URL path parts (e.g. ['blog', 'hello-world']).
+ *              Empty array matches the root itself (if terminal).
+ */
+export declare function matchUrlParts<TFile>(root: SegmentNode<TFile>, parts: string[], options?: TreeMatchOptions): TreeMatchResult<TFile> | null;
+/**
+ * Yield every match for the given URL parts, in priority order.
+ *
+ * Same matching semantics as `matchUrlParts` — static > affixed-dynamic >
+ * bare-dynamic > catch-all > optional-catch-all — but instead of returning
+ * the first match, it yields all of them. Used by the metadata route matcher,
+ * which needs to try alternate owner segments when the first match doesn't
+ * own the requested metadata file.
+ */
+export declare function matchUrlPartsAll<TFile>(root: SegmentNode<TFile>, parts: string[], options?: TreeMatchOptions): Generator<TreeMatchResult<TFile>>;
+//# sourceMappingURL=tree-match.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-match.d.ts","sourceRoot":"","sources":["../../src/server/tree-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,2DAA2D;AAC3D,MAAM,WAAW,eAAe,CAAC,KAAK;IACpC,0DAA0D;IAC1D,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;IAC5B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,KAAK,EACjC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EACxB,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe,CAAC,KAAK,CAAC,GAAG,IAAI,CAS/B;AAED;;;;;;;;GAQG;AACH,wBAAiB,gBAAgB,CAAC,KAAK,EACrC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EACxB,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE,gBAAgB,GACzB,SAAS,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAMnC"}