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

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

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

package/dist/server/param-coercion.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Segment param coercion — runs the app/schema.ts codecs over the raw
+ * matcher output before middleware and rendering.
+ *
+ * Lifted out of `pipeline-phases.ts` (TIM-853) so the coercer can be
+ * imported directly by other entry points (the action-dispatch wrapper,
+ * the revalidation renderer in `rsc-entry/index.ts`) without pulling
+ * the entire pipeline phase module along with it.
+ *
+ * The function throws `ParamCoercionError` (defined below) on any codec
+ * failure; the pipeline catches that and dispatches to the 404 page.
+ * See design/07-routing.md §"Where Coercion Runs".
+ */
+import type { Codec } from '../codec.ts';
+import type { SegmentType } from '../routing/types.ts';
+import type { RouteMatch } from './pipeline.ts';
+import { type CoercedParams } from '../shared/param-value.ts';
+/**
+ * Thrown when an app/schema.ts segment-param codec's parse() fails.
+ * The pipeline catches this and responds with 404.
+ */
+export declare class ParamCoercionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Register the global schema codecs. Called once from the RSC entry
+ * at server startup when app/schema.ts provides segment param codecs.
+ * @internal
+ */
+export declare function setGlobalSchemaCodecs(codecs: Record<string, Codec<unknown>> | null): void;
+/**
+ * Coerce raw slot params through global schema codecs.
+ *
+ * Each slot segment that has a paramName is looked up in the global codec
+ * map by its bracket key (e.g. '[...year]' for catch-all). If a codec
+ * exists, the raw value is parsed through it. If no codec exists or no
+ * global codecs are registered, the raw value passes through unchanged.
+ *
+ * Segments are read through `effectiveUrlSegment` because an intercepting
+ * node's own `segmentType` is `'intercepting'` and its `paramName` is unset
+ * — the param it binds lives in the intercepted name (`(.)[id]` → `[id]`).
+ * The slot resolver matches through the same helper, so the key a param is
+ * coerced under is always the key it was matched under (TIM-1281).
+ *
+ * Unlike main route coercion, this does NOT throw ParamCoercionError on
+ * failure — slots degrade gracefully. A failed coercion logs a warning
+ * in dev mode and keeps the raw value.
+ *
+ * @internal — framework use only
+ */
+export declare function coerceSlotParams(slotChain: Array<{
+    segmentName: string;
+    segmentType: SegmentType;
+    paramName?: string;
+    interceptedSegmentName?: string;
+}>, rawParams: Record<string, string | string[]>): CoercedParams;
+/**
+ * Coerce the matched route's raw segment params and return the result.
+ *
+ * Reads `match.rawSegmentParams` and never writes to `match`: the caller
+ * decides where the coerced params go. Reading the raw record makes the call
+ * repeatable — coercing a match twice runs every codec on the URL value both
+ * times, never on its own output.
+ *
+ * Codecs come from `app/schema.ts` and nowhere else (TIM-1342 completed
+ * design/41-global-params.md migration step 9). A route with no schema, or
+ * a param the schema does not declare, keeps its raw string — which is the
+ * honest type for an uninterpreted URL segment.
+ *
+ * Throws ParamCoercionError if any codec fails (→ 404).
+ *
+ * This runs BEFORE middleware, so ctx.segmentParams is already typed.
+ * See design/07-routing.md §"Where Coercion Runs"
+ * See design/41-global-params.md §"Pipeline Integration"
+ *
+ * Stays `async` with nothing to await: it is injected as a
+ * `CoerceSegmentParamsFn` into the revalidation renderer, which awaits
+ * it. Making it synchronous would
+ * change that contract and remove a microtask boundary the pipeline's
+ * ordering has always had, for no gain.
+ */
+export declare function coerceSegmentParams(match: RouteMatch): Promise<CoercedParams>;
+//# sourceMappingURL=param-coercion.d.ts.map

package/dist/server/param-coercion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param-coercion.d.ts","sourceRoot":"","sources":["../../src/server/param-coercion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACnF;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAUD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAEzF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC,EACF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAC3C,aAAa,CAyCf;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAuDnF"}

package/dist/server/pipeline-helpers.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Pipeline helpers — small utility functions used by `pipeline.ts` and
+ * `pipeline-phases.ts`. Lifted out of `pipeline.ts` to keep that file
+ * focused on the request handler entry point.
+ *
+ * Each helper is intentionally a free function with no closure capture, so
+ * it can be unit-tested in isolation.
+ *
+ * See design/07-routing.md §"Request Lifecycle".
+ */
+import type { ProxyExport } from './proxy.ts';
+import { RedirectSignal } from './primitives.ts';
+import { type ManifestLoader } from './safe-load.ts';
+import { type ManifestSegmentNode } from './route-matcher.ts';
+import type { ProxyConfig, RouteMatcher } from './pipeline.ts';
+import { type CsrfConfig } from './csrf.ts';
+import type { PhaseName } from './pipeline-outcome.ts';
+/**
+ * The pipeline-boundary CSRF gate: the 403 to answer with, or null to go on.
+ *
+ * Runs on every request after canonicalization and before proxy.ts, so it
+ * covers route.ts handlers and server actions alike, and no user code has
+ * run when it decides. The per-route exemption is looked up only for a
+ * request the check would reject — the common accepted request never pays
+ * for a match. The lookup uses the pipeline's own matcher on the canonical
+ * path, the same match `handleRequest` dispatches on, and reads a flag the
+ * scanner took from route.ts source, so deciding it loads no module.
+ *
+ * A matcher that throws leaves the request unexempted: fail closed.
+ *
+ * See design/08-forms-and-actions.md §"CSRF Protection".
+ */
+export declare function csrfGate(req: Request, canonicalPath: string, csrf: CsrfConfig, matchRoute: RouteMatcher): Response | null;
+/**
+ * Resolver closure produced once at pipeline construction. The lazy variant
+ * still calls `loader()` per-request (HMR relies on re-importing), but the
+ * choice of which branch to take is made once, not on every request.
+ */
+export type ProxyResolver = () => ProxyExport | Promise<ProxyExport>;
+/**
+ * Build a proxy resolver closure from the declared source. Called exactly
+ * once at `createPipeline` setup time, so the hot path sees only the branch
+ * that corresponds to this pipeline's configured variant.
+ *
+ * Returns `null` when the app has no proxy.ts — the hot path short-circuits
+ * around `runProxyPhase` entirely in that case.
+ *
+ * Accepts the sugar form (a bare `ProxyExport` — function or function array)
+ * and normalises it to the static variant. Functions and arrays are
+ * structurally distinct from the tagged `{ kind: 'lazy', loader }` object,
+ * so discrimination is unambiguous.
+ */
+export declare function makeProxyResolver(proxy: ProxyConfig | ProxyExport | undefined): ProxyResolver | null;
+/**
+ * Apply all Set-Cookie headers from the cookie jar to a Headers object.
+ * Each cookie gets its own Set-Cookie header per RFC 6265 §4.1.
+ */
+export declare function applyCookieJar(headers: Headers): void;
+/**
+ * Bring a bag the jar was already applied to up to date with the jar.
+ *
+ * `applied` is what `getSetCookieHeaders()` returned when the jar was
+ * applied to `headers`. Values the jar no longer holds (a later write to the
+ * same name replaced them) are removed, and values it gained are appended.
+ * Every cookie then appears once, with its last write (design/29-cookies.md
+ * §"Last-Write-Wins for Same Name"). `Set-Cookie` values that did not come
+ * from the jar, such as a middleware appending to `ctx.headers` directly,
+ * are left alone.
+ */
+export declare function syncCookieJar(headers: Headers, applied: readonly string[]): void;
+/**
+ * Merge framework-managed response headers onto a terminal response without
+ * overwriting headers the terminal response already set itself.
+ */
+export declare function mergeMissingHeaders(target: Headers, source: Headers): void;
+/**
+ * Clone a Response into a fresh one whose header bag is guaranteed mutable.
+ *
+ * `Response.redirect()` and some platform-level passthrough responses (notably
+ * on Cloudflare Workers) return objects with frozen header bags. Calling
+ * `.set()` or `.append()` on them throws `TypeError: immutable`, which the
+ * pipeline can hit when it appends Set-Cookie or Server-Timing entries.
+ *
+ * The pipeline calls this at the producer sites where user-controlled
+ * responses enter the framework — `outcomeToResponse` for all phase outcomes,
+ * and `handleRequest` for metadata-route and auto-sitemap user handlers — so
+ * downstream code can write headers without runtime feature-detection.
+ *
+ * The clone is unconditional. This is a deliberate trade: we avoid a
+ * try/catch + thrown `TypeError` on every request (the previous probe-based
+ * approach paid that cost on the hot path) and accept one cheap Response
+ * rewrap at the framework boundary instead.
+ */
+export declare function cloneWithMutableHeaders(response: Response): Response;
+/**
+ * A fresh response header bag for a page the pipeline renders, seeded with
+ * the default dynamic-page cache policy.
+ *
+ * Without a Cache-Control header, CDNs (particularly Cloudflare) may attempt
+ * to buffer/process the response differently, causing intermittent
+ * multi-second delays. This matches Next.js's default behavior. Every bag a
+ * rendered page can be written onto starts here — a matched route, the
+ * no-match 404, and a deny page for a proxy-phase signal — so none of them
+ * leaves without a cache policy. Middleware and route handlers may replace it.
+ */
+export declare function dynamicResponseHeaders(): Headers;
+/**
+ * Build a redirect Response from a RedirectSignal.
+ *
+ * For a client navigation (an RSC payload request for a page), returns 204 +
+ * X-Timber-Redirect so the client router can perform a soft SPA redirect. A
+ * raw 302 would be turned into an opaque redirect by
+ * fetch({redirect:'manual'}), crashing createFromFetch. See
+ * design/19-client-navigation.md. The caller decides what counts as a
+ * navigation: a route.ts match answers with a real 3xx whatever it accepts.
+ */
+export declare function buildRedirectResponse(signal: RedirectSignal, headers: Headers, navigation: boolean): Response;
+/**
+ * Where an error was raised: a pipeline phase, a server action, or a
+ * handler that answers outside the page pipeline — a metadata route or the
+ * auto-generated sitemap — which reports like a route.ts handler.
+ */
+export type ErrorSource = PhaseName | 'action' | 'route';
+/**
+ * Fire the user's onRequestError hook with request context.
+ *
+ * The one place a pipeline phase becomes the `phase` / `routeType` the hook
+ * reports, so every caller agrees. A render-phase error on a route.ts match
+ * is phase `'route'`, because the handler is what ran. Middleware reports
+ * as `'handler'`, its public name.
+ */
+export declare function fireOnRequestError(error: unknown, req: Request, source: ErrorSource, segments?: readonly ManifestSegmentNode[]): Promise<void>;
+/**
+ * Whether an error is a failure `onRequestError` should hear about.
+ *
+ * Control-flow signals are outcomes the code chose — a `deny()` picks the
+ * page's status and data — and an abort is the client leaving. Callers answering
+ * a live request also skip everything once `req.signal` has aborted: a
+ * driver that throws "connection closed" after a disconnect is not a bug.
+ */
+export declare function isReportableError(error: unknown): boolean;
+/**
+ * Log and report a render error that was answered in place rather than
+ * handed to the pipeline: a slot that degraded to its fallback, a Flight
+ * error row, a fallback page that failed and fell back again. The pipeline
+ * never sees these, so this is their one report. Errors that are not
+ * reportable (`isReportableError()`), or that arrive after the request
+ * aborted, are only logged.
+ */
+export declare function reportRenderError(error: unknown, req: Request, details?: {
+    errorId?: string;
+    segments?: readonly ManifestSegmentNode[];
+}): void;
+/**
+ * Load a module the render can do without — a status page, an error page,
+ * `global-error.tsx`, a fallback page's layout — or report why it could not
+ * load and return `null`, so the next tier answers instead of the failure
+ * taking the page down. Every such load goes through here, whether it builds
+ * a boundary for a normal render or a fallback page, so a broken module is
+ * never skipped silently.
+ *
+ * Logged and reported once per broken file, not once per request: every
+ * request that renders under a broken `error.tsx` loads it again (TIM-1458).
+ * See `skippedFiles` for how "the same failure" is recognised. The first
+ * request to hit a failure is the one that reports it; if that request has
+ * already aborted, `fireOnRequestError()` drops the report and the failure is
+ * only logged.
+ *
+ * Never rejects, including when a user logger throws: building an error
+ * boundary must not itself throw (TIM-584), and the boundary walk does not
+ * catch for it.
+ */
+export declare function loadFallbackModule(file: ManifestLoader, req: Request, segments?: readonly ManifestSegmentNode[]): Promise<Record<string, unknown> | null>;
+/**
+ * Run a `cache.component` stale-while-revalidate re-render as a singleflight
+ * body, and log and report its failure once for the flight. The stale
+ * payload already answered, so nothing else sees the failure.
+ *
+ * - **Once per flight.** A `.catch` on the flight's promise would run once
+ *   per request that joined it, so the report happens inside the body. A
+ *   body still running when the singleflight times out is reported then,
+ *   with the timeout error (the signal's reason), and its later rejection
+ *   is dropped.
+ * - **Against the request whose stale read started it**, read from the
+ *   request context the work runs in. With no request (the build-time
+ *   capture store) it is only logged.
+ * - **As phase `'render'`, route type `'page`.** A `cache.component` is a
+ *   server component, so the read that started this was a page render (a
+ *   revalidated page tree included). The request's own abort does not
+ *   suppress the report: the work runs after the response either way.
+ */
+export declare function runBackgroundFlight(signal: AbortSignal, work: () => Promise<unknown>, log: (error: unknown) => void): Promise<void>;
+//# sourceMappingURL=pipeline-helpers.d.ts.map

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

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

package/dist/server/pipeline-interception.d.ts

@@ -8,20 +8,71 @@
  *
  * See design/07-routing.md §"Intercepting Routes"
  */
-/** Result of a successful interception match. */
-export interface InterceptionMatchResult {
-    /** The pathname to re-match (the source/intercepting route's parent). */
-    sourcePathname: string;
-}
+import type { InterceptionRewrite } from '../routing/interception.ts';
+import type { InterceptionContext, PipelineConfig, RouteMatch } from './pipeline.ts';
 /**
  * Check if an intercepting route applies for this soft navigation.
  *
- * Matches the target pathname against interception rewrites, constrained
- * by the source URL (X-Timber-URL header — where the user navigates FROM).
+ * Two conditions must hold:
  *
- * Returns the source pathname to re-match if interception applies, or null.
+ * 1. The **target** pathname matches the rewrite's intercepted pattern.
+ * 2. The **source** route — the page the user is navigating FROM, per the
+ *    validated X-Timber-URL header — renders the segment that owns the slot
+ *    holding the intercepting page (`interceptingScope`). Only then does that
+ *    slot exist in the rendered tree, so only then can the intercepting page
+ *    render.
+ *
+ * Condition 2 replaced a URL-prefix check (TIM-1279). A prefix cannot
+ * distinguish a route-group-scoped interception from a genuinely root-level
+ * one — route groups are invisible in `urlPath`, so both collapse to "/" and
+ * the guard degenerates to always-true. Tree paths carry group identity.
+ * The scope check also subsumes the old segment-boundary rule: a source route
+ * under /feed-private has no "/feed" in its chain.
+ *
+ * A third condition lives with the caller, which owns route matching, and it
+ * applies to the `'slot'` shape only: the route produced by re-matching
+ * `interceptingPrefix` must pass through the scope too. Conditions 1–2 are
+ * about the route the user is leaving; the slot has to exist in the tree that
+ * actually renders. The `'children'` shape resolves its owner from the scope
+ * directly rather than from a pathname, so it satisfies that by construction.
+ *
+ * `resolveSourceScopes` is a thunk so its inputs are only resolved when some
+ * rewrite's pattern actually matches the target — the common case is no match
+ * at all. It returns the two client-supplied answers to "what is on screen?"
+ * as **separate sets, most authoritative first**: the tree paths the client
+ * says it has mounted, then those of the route the departing URL matches. It
+ * returns null only when neither yields anything, which is not a soft
+ * navigation this can reason about.
+ *
+ * They are two sets rather than one union because ranking needs a chain
+ * (TIM-1318). Each channel describes a single rendered chain, so within one the
+ * scopes are strictly nested and the deepest is the innermost owner. Unioned
+ * they are not: once a modal is open the address bar holds the *intercepted*
+ * URL, so the second channel describes the canonical branch — possibly an
+ * exclusive route group the client never mounted — and a deeper scope from
+ * there would outrank the owner actually on screen. Trying the mounted channel
+ * to exhaustion first keeps the fallback the union was there to provide while
+ * ranking only within one chain.
+ *
+ * Returns the winning build-time rewrite, or null. Only build-time values ever
+ * reach the renderer: the client-supplied header selects a rewrite but never
+ * becomes a rendered route or pathname.
+ *
+ * The **first** matching rewrite wins, and the caller does not fall back to the
+ * next one when the winner fails to resolve. That is deliberate and pre-dates
+ * the two shapes: a rewrite that matched the target and the scope described the
+ * author's intent, and quietly rendering some other author's interception
+ * instead would be harder to explain than rendering the canonical route.
+ *
+ * "First" is meaningful because the list arrives **deepest scope first** —
+ * `collectInterceptionRewrites` sorts it at build time, so the deepest owner a
+ * single chain passes through wins and nothing here has to score (TIM-1318).
+ * Tree-walk order used to decide it, which meant renaming a route group flipped
+ * which modal opened. The precondition is a property of the manifest this reads
+ * rather than something it can re-derive, so it is asserted at its source:
+ * `tests/interception.test.ts` §"rewrite order is decided by scope depth".
  */
-export declare function findInterceptionMatch(targetPathname: string, sourceUrl: string, rewrites: import('#/routing/interception.js').InterceptionRewrite[]): InterceptionMatchResult | null;
+export declare function findInterceptionMatch(targetPathname: string, resolveSourceScopes: () => ReadonlySet<string>[] | null, rewrites: InterceptionRewrite[]): InterceptionRewrite | null;
 /**
  * Check if a pathname matches a URL pattern with dynamic segments.
  *
@@ -29,4 +80,14 @@ export declare function findInterceptionMatch(targetPathname: string, sourceUrl:
  * Static segments must match exactly.
  */
 export declare function pathnameMatchesPattern(pathname: string, pattern: string): boolean;
+/**
+ * Resolve which route renders a soft navigation that an intercepting route
+ * may claim. Returns the canonical match unchanged when no rewrite applies.
+ *
+ * Runs during route setup, so anything it throws is a `'setup'` outcome.
+ */
+export declare function resolveInterceptedRoute(config: PipelineConfig, req: Request, canonicalPathname: string, canonicalMatch: RouteMatch | null): {
+    match: RouteMatch | null;
+    interception?: InterceptionContext;
+};
 //# sourceMappingURL=pipeline-interception.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"pipeline-interception.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-interception.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,OAAO,2BAA2B,EAAE,mBAAmB,EAAE,GAClE,uBAAuB,GAAG,IAAI,CAYhC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CA0BjF"}
+{"version":3,"file":"pipeline-interception.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-interception.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAKtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,EACtB,mBAAmB,EAAE,MAAM,WAAW,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,EACvD,QAAQ,EAAE,mBAAmB,EAAE,GAC9B,mBAAmB,GAAG,IAAI,CAyB5B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAsCjF;AAID;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,iBAAiB,EAAE,MAAM,EACzB,cAAc,EAAE,UAAU,GAAG,IAAI,GAChC;IAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAAC,YAAY,CAAC,EAAE,mBAAmB,CAAA;CAAE,CA6FlE"}

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

@@ -15,7 +15,7 @@
  *
  * See design/16-metadata.md §"Metadata Routes"
  */
-export declare function serveStaticMetadataFile(metaMatch: import('./route-matcher.js').MetadataRouteMatch): Promise<Response>;
+export declare function serveStaticMetadataFile(metaMatch: import('./route-matcher.ts').MetadataRouteMatch): Promise<Response>;
 /**
  * Serialize a sitemap array to XML.
  * Follows the sitemap.org protocol: https://www.sitemaps.org/protocol.html
@@ -26,6 +26,12 @@ export declare function serializeSitemap(entries: Array<{
     changeFrequency?: string;
     priority?: number;
 }>): string;
+/**
+ * Serialize a sitemap index (list of sub-sitemap URLs) to XML.
+ * Used for pagination when the total URL count exceeds 50,000.
+ * Follows the sitemap.org protocol: https://www.sitemaps.org/protocol.html
+ */
+export declare function serializeSitemapIndex(sitemapUrls: string[]): string;
 /** Escape special XML characters. */
 export declare function escapeXml(str: string): string;
 //# sourceMappingURL=pipeline-metadata.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"pipeline-metadata.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,OAAO,oBAAoB,EAAE,kBAAkB,GACzD,OAAO,CAAC,QAAQ,CAAC,CAYnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,GACD,MAAM,CAoBR;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO7C"}
+{"version":3,"file":"pipeline-metadata.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,OAAO,oBAAoB,EAAE,kBAAkB,GACzD,OAAO,CAAC,QAAQ,CAAC,CAanB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,GACD,MAAM,CAoBR;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAMnE;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO7C"}

package/dist/server/pipeline-outcome.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pipeline outcome translator — converts a `PhaseOutcome` (the value
+ * each phase function returns) into a final `Response`.
+ *
+ * Lifted out of `pipeline-phases.ts` (TIM-853) so the per-phase try /
+ * catch logic and the terminal Response-building logic each live in
+ * their own file. The phases produce values; this module is the single
+ * source of truth for how those values become wire responses.
+ *
+ * See design/07-routing.md §"Request Lifecycle".
+ */
+import { RedirectSignal, DenySignal } from './primitives.ts';
+import type { PipelineConfig, RouteMatch } from './pipeline.ts';
+/**
+ * The pipeline phase an outcome came from.
+ *
+ * `'setup'` is route setup between `proxy.ts` and `middleware.ts`: route
+ * matching, interception, and segment-param coercion. It has its own name
+ * rather than borrowing `'middleware'` because both the cookie-jar guard
+ * and `onRequestError` key on the phase (TIM-1537).
+ */
+export type PhaseName = 'proxy' | 'setup' | 'middleware' | 'render';
+export type PhaseOutcome = {
+    kind: 'response';
+    phase: PhaseName;
+    response: Response;
+} | {
+    kind: 'redirect';
+    phase: PhaseName;
+    signal: RedirectSignal;
+} | {
+    kind: 'deny';
+    phase: PhaseName;
+    signal: DenySignal;
+} | {
+    kind: 'error';
+    phase: PhaseName;
+    error: unknown;
+};
+/** The outcome for a value a phase threw: a signal, or an error. */
+export declare function thrownOutcome(phase: PhaseName, thrown: unknown): PhaseOutcome;
+export interface OutcomeContext {
+    req: Request;
+    method: string;
+    path: string;
+    responseHeaders?: Headers;
+    match?: RouteMatch;
+}
+/**
+ * Terminal outcome handler — converts a `PhaseOutcome` into a final
+ * `Response`, applying cookies, building redirects, rendering deny pages
+ * and fallback error pages, and firing instrumentation hooks.
+ *
+ * This is the single source of truth for how phase outputs become wire
+ * responses; the per-phase try/catch blocks now produce values, not
+ * Responses, so the conversion logic lives in exactly one place.
+ */
+export declare function outcomeToResponse(config: PipelineConfig, outcome: PhaseOutcome, ctx: OutcomeContext): Promise<Response>;
+//# sourceMappingURL=pipeline-outcome.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-outcome.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAmBH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAO7D,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAkFhE;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEpE,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAExD,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,YAAY,CAI7E;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAID;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,QAAQ,CAAC,CA6HnB"}

package/dist/server/pipeline-phases.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Pipeline phase functions — module-level free functions that take their
+ * dependencies as explicit parameters. Each phase returns a `PhaseOutcome`
+ * (a discriminated union over response / redirect / deny / error) defined
+ * in `pipeline-outcome.ts`. The terminal `outcomeToResponse` (also in
+ * `pipeline-outcome.ts`) translates outcomes into Responses.
+ *
+ * Lifted out of `createPipeline` so each phase can be unit-tested in
+ * isolation. The lift is mechanical — these functions used to be closures
+ * over `config`; they now take `config` as an explicit parameter.
+ *
+ * See design/07-routing.md §"Request Lifecycle", design/02-rendering-pipeline.md §"Request Flow".
+ */
+import { type ProxyResolver } from './pipeline-helpers.ts';
+import { type PhaseOutcome } from './pipeline-outcome.ts';
+import type { InterceptionContext, PipelineConfig, RouteMatch } from './pipeline.ts';
+interface RenderContext {
+    canonicalPathname: string;
+    interception?: InterceptionContext;
+}
+/**
+ * Run the proxy.ts phase. Calls user proxy code with a `next()` continuation.
+ *
+ * When `next` is provided, it replaces the default `handleRequest` as the
+ * continuation — this lets the pipeline inject action dispatch between proxy
+ * and route matching (TIM-1213). The proxy resolver was picked at pipeline
+ * construction time so the hot path sees no per-request branching on the
+ * `ProxyConfig` discriminant.
+ */
+export declare function runProxyPhase(config: PipelineConfig, getProxy: ProxyResolver, req: Request, method: string, path: string, next?: () => Promise<Response>): Promise<PhaseOutcome>;
+/**
+ * Run the middleware chain phase. If the chain short-circuits with a Response,
+ * returns it as a 'response' outcome. Otherwise applies the request header
+ * overlay and falls through to the render phase.
+ */
+export declare function runMiddlewarePhase(config: PipelineConfig, req: Request, match: RouteMatch, responseHeaders: Headers, renderContext: RenderContext): Promise<PhaseOutcome>;
+/**
+ * Run the render phase. Wraps the configured renderer in a span and a
+ * timing scope, and translates thrown signals into outcome variants.
+ *
+ * The render phase owns `responseHeaders` from here on, so it is the one
+ * place the cookie jar is applied to that bag (design/29-cookies.md
+ * §"Applied Exactly Once"). Doing it here rather than in the middleware
+ * phase means every render-phase outcome — a 200, or a deny / redirect /
+ * error thrown from render — carries the jar whether or not a middleware
+ * chain ran, and `outcomeToResponse` can skip render-phase outcomes
+ * unconditionally (TIM-1491). Application precedes `config.render` so
+ * middleware cookie writes are visible to route-handler header merging,
+ * while handler `Set-Cookie` values still come after them and take
+ * precedence.
+ */
+export declare function runRenderPhase(config: PipelineConfig, req: Request, match: RouteMatch, responseHeaders: Headers, { canonicalPathname, interception }: RenderContext): Promise<PhaseOutcome>;
+/**
+ * Process a single request from canonicalization through phase dispatch.
+ *
+ * Stages: canonicalize → metadata routes → auto-sitemap → version skew →
+ * route match → interception → early hints → param coercion → middleware →
+ * render → outcome translation. Pre-routing short-circuits return Responses
+ * directly; post-match dispatch goes through `outcomeToResponse`.
+ *
+ * Used both as the top-level entry (when no proxy.ts is configured) and as
+ * the `next()` continuation passed to `runProxy()`.
+ *
+ * @param pathIsCanonical When true, `path` has already been canonicalized by
+ *   `createPipeline` — skip re-canonicalization to prevent double-decode.
+ *   When false (default), runs canonicalize as a safety net for direct callers.
+ */
+export declare function handleRequest(config: PipelineConfig, req: Request, method: string, path: string, pathIsCanonical?: boolean): Promise<Response>;
+export {};
+//# sourceMappingURL=pipeline-phases.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-phases.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsBH,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAMrF,UAAU,aAAa;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAID;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,aAAa,EACvB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,GAC7B,OAAO,CAAC,YAAY,CAAC,CAavB;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,aAAa,EAAE,aAAa,GAC3B,OAAO,CAAC,YAAY,CAAC,CAsDvB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,EAAE,iBAAiB,EAAE,YAAY,EAAE,EAAE,aAAa,GACjD,OAAO,CAAC,YAAY,CAAC,CAYvB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,OAAO,GACxB,OAAO,CAAC,QAAQ,CAAC,CAuRnB"}