@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.98

package/dist/server/node-stream-transforms.d.ts

@@ -1,13 +1,14 @@
 /**
  * Node.js native stream transforms for SSR HTML post-processing.
  *
- * These are Node.js Transform stream equivalents of the Web Stream
- * transforms in html-injectors.ts. Used on Node.js/Bun where native
- * streams (C++ backed) are faster than Web Streams (JS reimplementation).
- *
- * The transforms are pure string operations on HTML chunks — the same
- * logic as the Web Stream versions, just wrapped in Node.js Transform
- * instead of Web TransformStream.
+ * Node.js `Transform` wrappers around the pure helpers in
+ * `html-injector-core.ts`. Used on Node.js / Bun where C++-backed
+ * native streams are significantly faster than the JS-implemented
+ * Web Streams. The Web `TransformStream` equivalents live in
+ * `html-injectors.ts` and wrap the same core — keep the two files
+ * byte-for-byte equivalent in behavior. If you fix a streaming bug
+ * here, it almost certainly belongs in the core (`html-injector-core.ts`),
+ * not in this wrapper.
  *
  * Architecture:
  *   renderToPipeableStream → pipe(errorHandler) → pipe(headInjector)
@@ -17,9 +18,7 @@
  * Readable.toWeb() conversion for the Response body.
  */
 import { Transform } from 'node:stream';
-/**
- * Options for the Node.js buffered transform.
- */
+import { SUFFIX_BYTES } from './html-injector-core.js';
 export interface NodeBufferedTransformOptions {
     /**
      * Flush synchronously once the buffer reaches this many bytes.
@@ -29,67 +28,65 @@ export interface NodeBufferedTransformOptions {
     readonly maxBufferByteLength?: number;
 }
 /**
- * Node.js Transform that buffers incoming chunks and coalesces them
+ * Node.js `Transform` that buffers incoming chunks and coalesces them
  * within a single event loop tick.
  *
- * Equivalent to createBufferedTransformStream() in html-injectors.ts.
- * React Fizz may emit multiple micro-chunks within a single flush.
- * Without buffering, downstream transforms (especially flight injection)
- * could see chunk boundaries in the middle of HTML tags or attributes.
+ * Equivalent to `createBufferedTransformStream` in `html-injectors.ts` —
+ * the actual buffer math lives in `BufferAggregator`. This wrapper only
+ * owns the `setImmediate` scheduling and the push to the Node `Transform`.
  *
- * This transform collects all chunks that arrive in the same tick and
- * emits them as a single concatenated Buffer on the next `setImmediate`.
- *
- * **Not a polling loop.** Uses a single-shot `setImmediate` per flush
- * cycle — no recursive scheduling, no busy-wait. See design/02 §"No Polling".
- *
- * Inspired by Next.js `createBufferedTransformStream`.
+ * **Not a polling loop.** Single-shot `setImmediate` per flush cycle —
+ * no recursive scheduling. See design/02 §"No Polling".
  */
 export declare function createNodeBufferedTransform(options?: NodeBufferedTransformOptions): Transform;
 /**
- * Node.js Transform that moves `</body></html>` to the end of the stream.
+ * Node.js `Transform` that moves `</body></html>` to the end of the stream.
  *
- * Equivalent to createMoveSuffixStream() in html-injectors.ts.
- * Strips the suffix when first encountered and re-emits it in flush().
- * If no suffix is found, it's appended anyway for well-formed HTML.
+ * Equivalent to `createMoveSuffixStream` in `html-injectors.ts`. Strips
+ * the suffix on first sight and re-emits it from `flush()`. If the
+ * suffix never appeared in the input, it is appended anyway so output
+ * is well-formed.
  */
 export declare function createNodeMoveSuffixTransform(): Transform;
+export { SUFFIX_BYTES };
 /**
- * Node.js Transform that injects HTML content before </head>.
+ * Node.js `Transform` that injects HTML content before `</head>`.
  *
- * Equivalent to injectHead() in html-injectors.ts. Streams chunks
+ * Equivalent to `injectHead` in `html-injectors.ts`. Streams chunks
  * through immediately, keeping only a small trailing buffer to handle
- * </head> split across chunk boundaries.
+ * `</head>` split across chunk boundaries.
  */
 export declare function createNodeHeadInjector(headHtml: string): Transform;
-/**
- * Node.js Transform that merges RSC script tags into the HTML stream.
- *
- * Reads RSC chunks from the provided ReadableStream and injects them
- * as `<script>` tags between HTML chunks. Scripts are buffered in
- * pending[] and only drained from transform() (after a complete HTML
- * chunk) or flush() — never pushed directly from the pull loop.
- *
- * Suffix stripping (</body></html>) is handled upstream by
- * createNodeMoveSuffixTransform. This transform only interleaves
- * RSC scripts at safe chunk boundaries.
- *
- * The RSC stream is a Web ReadableStream (from the tee'd RSC Flight
- * stream). We read from it using the Web API — this is the one bridge
- * point between Web Streams and Node.js streams in the pipeline.
- */
 /**
  * Options for the Node.js flight injector.
  */
 export interface NodeFlightInjectorOptions {
     /**
-     * Timeout in milliseconds for individual RSC stream reads.
-     * If a single `rscReader.read()` call does not resolve within
-     * this duration, the read is aborted and the stream errors with
-     * a RenderTimeoutError. Default: 30000 (30s).
+     * Timeout in milliseconds for individual RSC stream reads. If a single
+     * `rscReader.read()` call does not resolve within this duration, the
+     * read is aborted and the stream errors with a `RenderTimeoutError`.
+     * Default: 30000 (30s).
      */
     renderTimeoutMs?: number;
 }
+/**
+ * Node.js `Transform` that merges RSC script tags into the HTML stream.
+ *
+ * Equivalent to `createFlightInjectionTransform` in `html-injectors.ts`.
+ * The state machine, pending queue, and pull loop all live in
+ * `FlightInjectorCore` — this wrapper only shuffles bytes between the
+ * core and the Node `Transform.push()` API.
+ *
+ * Suffix stripping (`</body></html>`) is handled upstream by
+ * `createNodeMoveSuffixTransform`. RSC scripts are buffered in
+ * `core.pending[]` and only drained from `transform()` (after a complete
+ * HTML chunk) or `flush()` — never mid-tag. See design/02
+ * §"Scripts at Chunk Boundaries Only".
+ *
+ * The RSC stream is a Web `ReadableStream` (from the tee'd RSC Flight
+ * stream). The core reads from it using the Web API — this is the one
+ * bridge point between Web Streams and Node.js streams in the pipeline.
+ */
 export declare function createNodeFlightInjector(rscStream: ReadableStream<Uint8Array> | undefined, options?: NodeFlightInjectorOptions): Transform;
 /**
  * Node.js Transform that catches post-shell streaming errors.

package/dist/server/node-stream-transforms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-stream-transforms.d.ts","sourceRoot":"","sources":["../../src/server/node-stream-transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,4BAAiC,GAAG,SAAS,CAgDjG;AAqBD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,IAAI,SAAS,CAwCzD;AAID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA+ClE;AAID;;;;;;;;;;;;;;;GAeG;AACH;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,OAAO,CAAC,EAAE,yBAAyB,GAClC,SAAS,CAgJX;AAOD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAwBtE;AAoBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,OAAO,EACvB,eAAe,EAAE,OAAO,GACvB,SAAS,GAAG,IAAI,CA8BlB"}
+{"version":3,"file":"node-stream-transforms.d.ts","sourceRoot":"","sources":["../../src/server/node-stream-transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAGL,YAAY,EAOb,MAAM,yBAAyB,CAAC;AAKjC,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,4BAAiC,GAAG,SAAS,CAsCjG;AAID;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,IAAI,SAAS,CAoBzD;AAGD,OAAO,EAAE,YAAY,EAAE,CAAC;AAIxB;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA2BlE;AAID;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,OAAO,CAAC,EAAE,yBAAyB,GAClC,SAAS,CA6DX;AAOD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAwBtE;AAmBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,OAAO,EACvB,eAAe,EAAE,OAAO,GACvB,SAAS,GAAG,IAAI,CA8BlB"}

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

@@ -0,0 +1,88 @@
+/**
+ * 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.js';
+import { RedirectSignal } from './primitives.js';
+import type { ProxyConfig } from './pipeline.js';
+/**
+ * Shallow merge that skips top-level prototype-polluting keys.
+ *
+ * This is intentionally NOT a deep sanitizer. It only blocks shallow
+ * pollution via top-level `__proto__` / `constructor` / `prototype`
+ * keys. The deeper guarantee for segment params comes from merging
+ * codec output into a null-prototype target inside coerceSegmentParams().
+ *
+ * See TIM-655, TIM-855, design/13-security.md
+ */
+export declare function safeMerge(target: Record<string, unknown>, source: Record<string, unknown>): void;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * Build a redirect Response from a RedirectSignal.
+ *
+ * For RSC payload requests (client navigation), 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.
+ */
+export declare function buildRedirectResponse(signal: RedirectSignal, req: Request, headers: Headers): Response;
+/**
+ * Fire the user's onRequestError hook with request context.
+ * Extracts request info from the Request object and calls the instrumentation hook.
+ */
+export declare function fireOnRequestError(error: unknown, req: Request, phase: 'proxy' | 'handler' | 'render' | 'action' | 'route'): 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":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAOjD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMhG;AAID;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,GAAG,WAAW,GAAG,SAAS,GAC3C,aAAa,GAAG,IAAI,CAatB;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAIrD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAO1E;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAMpE;AAID;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,OAAO,GACf,QAAQ,CAQV;AAID;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GACzD,OAAO,CAAC,IAAI,CAAC,CAYf"}

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

@@ -0,0 +1,97 @@
+/**
+ * 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). The
+ * terminal `outcomeToResponse` 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 { RedirectSignal, DenySignal } from './primitives.js';
+import { type ProxyResolver } from './pipeline-helpers.js';
+import type { InterceptionContext, PipelineConfig, RouteMatch } from './pipeline.js';
+export type PhaseName = 'proxy' | '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;
+};
+export interface OutcomeContext {
+    req: Request;
+    method: string;
+    path: string;
+    responseHeaders?: Headers;
+    match?: RouteMatch;
+}
+interface RenderContext {
+    canonicalPathname: string;
+    interception?: InterceptionContext;
+}
+/**
+ * Run segment param coercion on the matched route's segments.
+ *
+ * Loads params.ts modules from segments that have them, extracts the
+ * segmentParams definition, and coerces raw string params through codecs.
+ * 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"
+ */
+export declare function coerceSegmentParams(match: RouteMatch): Promise<void>;
+/**
+ * Run the proxy.ts phase. Calls user proxy code and uses `handleRequest` as
+ * the inner `next()` continuation. 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): 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, requestHeaderOverlay: 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.
+ */
+export declare function runRenderPhase(config: PipelineConfig, req: Request, match: RouteMatch, responseHeaders: Headers, requestHeaderOverlay: 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()`.
+ */
+export declare function handleRequest(config: PipelineConfig, req: Request, method: string, path: string): Promise<Response>;
+/**
+ * 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>;
+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;;;;;;;;;;;GAWG;AAmBH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAM7D,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAKrF,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,YAAY,GAAG,QAAQ,CAAC;AAE1D,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,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;AAED,UAAU,aAAa;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAID;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA0C1E;AAID;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,aAAa,EACvB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,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,oBAAoB,EAAE,OAAO,EAC7B,aAAa,EAAE,aAAa,GAC3B,OAAO,CAAC,YAAY,CAAC,CA6DvB;AAID;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,EAAE,iBAAiB,EAAE,YAAY,EAAE,EAAE,aAAa,GACjD,OAAO,CAAC,YAAY,CAAC,CAkBvB;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,QAAQ,CAAC,CAsMnB;AAID;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,QAAQ,CAAC,CA2FnB"}

package/dist/server/pipeline.d.ts

@@ -4,30 +4,34 @@
  * Pipeline stages (in order):
  *   proxy.ts → canonicalize → route match → 103 Early Hints → middleware.ts → render
  *
- * Each stage is a pure function or returns a Response to short-circuit.
- * Each request gets a trace ID, structured logging, and OTEL spans.
+ * The phase functions live in `pipeline-phases.ts` so each phase can be
+ * tested in isolation. The terminal `outcomeToResponse` translator and
+ * stateless helpers live in `pipeline-phases.ts` and `pipeline-helpers.ts`
+ * respectively. This file owns only the public type surface and the
+ * `createPipeline` entry point: trace ID setup, request-context ALS,
+ * Server-Timing wrapping, and the activeRequests counter.
  *
  * See design/07-routing.md §"Request Lifecycle", design/02-rendering-pipeline.md §"Request Flow",
  * and design/17-logging.md §"Production Logging"
  */
-import { type ProxyExport } from './proxy.js';
-import { type MiddlewareFn } from './middleware-runner.js';
+import type { ProxyExport } from './proxy.js';
+import type { MiddlewareFn } from './middleware-runner.js';
 import { DenySignal } from './primitives.js';
-import type { SegmentNode } from '../routing/types.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+export { safeMerge } from './pipeline-helpers.js';
+export { coerceSegmentParams } from './pipeline-phases.js';
 /**
- * Shallow merge that skips prototype-polluting keys.
+ * Result of matching a canonical pathname against the route tree.
  *
- * Used instead of Object.assign when the source object comes from
- * user-authored codec output (segmentParams.parse), which could
- * contain __proto__, constructor, or prototype keys.
- *
- * See TIM-655, design/13-security.md
+ * `segments` is the runtime (`ManifestFile`-specialized) shape — the same
+ * nodes carried in the virtual route manifest. TIM-863 unified this: the
+ * matcher produces `ManifestSegmentNode[]` directly and every consumer
+ * (render, slots, params coercion, early hints, deny fallback) sees the
+ * same structural type with no `as unknown as` laundering.
  */
-export declare function safeMerge(target: Record<string, unknown>, source: Record<string, unknown>): void;
-/** Result of matching a canonical pathname against the route tree. */
 export interface RouteMatch {
     /** The matched segment chain from root to leaf. */
-    segments: SegmentNode[];
+    segments: ManifestSegmentNode[];
     /** Extracted segment params (catch-all segments produce string[]). */
     segmentParams: Record<string, string | string[]>;
     /** Middleware chain from the segment tree, ordered root-to-leaf. */
@@ -46,13 +50,37 @@ export interface InterceptionContext {
 export type RouteRenderer = (req: Request, match: RouteMatch, responseHeaders: Headers, requestHeaderOverlay: Headers, interception?: InterceptionContext) => Response | Promise<Response>;
 /** Function that sends 103 Early Hints for a matched route. */
 export type EarlyHintsEmitter = (match: RouteMatch, req: Request, responseHeaders: Headers) => void | Promise<void>;
-export interface PipelineConfig {
-    /** The proxy.ts default export (function or array). Undefined if no proxy.ts. */
-    proxy?: ProxyExport;
-    /** Lazy loader for proxy.ts — called per-request so HMR updates take effect. */
-    proxyLoader?: () => Promise<{
+/**
+ * Proxy source — a tagged union so the choice between "already-resolved
+ * export" and "lazy HMR-friendly loader" is encoded in the type, not
+ * inferred per-request.
+ *
+ * - `static` — the proxy export is already resolved (production, tests).
+ * - `lazy`   — a loader is called per-request for HMR freshness (dev).
+ *
+ * `PipelineConfig.proxy` also accepts a bare `ProxyExport` (a function or
+ * function array) as shorthand for the static variant — convenient for tests
+ * that construct a `createPipeline` config inline. Omit the field entirely
+ * when the app has no `proxy.ts`.
+ *
+ * See design/07-routing.md §"proxy.ts — Global Middleware".
+ */
+export type ProxyConfig = {
+    kind: 'static';
+    export: ProxyExport;
+} | {
+    kind: 'lazy';
+    loader: () => Promise<{
         default: ProxyExport;
     }>;
+};
+export interface PipelineConfig {
+    /**
+     * proxy.ts source. Undefined if the app has no proxy.ts. Accepts either a
+     * tagged `ProxyConfig` (canonical) or a bare `ProxyExport` as sugar for the
+     * static variant.
+     */
+    proxy?: ProxyConfig | ProxyExport;
     /** Route matcher — resolves a canonical pathname to a RouteMatch. */
     matchRoute: RouteMatcher;
     /** Metadata route matcher — resolves metadata route pathnames (sitemap.xml, robots.txt, etc.) */
@@ -130,22 +158,15 @@ export interface PipelineConfig {
      */
     match?: RouteMatch) => Response | Promise<Response>;
 }
-/**
- * Run segment param coercion on the matched route's segments.
- *
- * Loads params.ts modules from segments that have them, extracts the
- * segmentParams definition, and coerces raw string params through codecs.
- * 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"
- */
-export declare function coerceSegmentParams(match: RouteMatch): Promise<void>;
 /**
  * Create the request handler from a pipeline configuration.
  *
- * Returns a function that processes an incoming Request through all pipeline stages
- * and produces a Response. This is the top-level entry point for the server.
+ * Returns a function that processes an incoming Request through all pipeline
+ * stages and produces a Response. This is the top-level entry point for the
+ * server. The body is intentionally small — phase logic lives in
+ * `pipeline-phases.ts`. This function only owns the per-request setup that
+ * has to wrap the entire dispatch: trace ID, request context ALS, span
+ * scope, Server-Timing header emission, and the active-request counter.
  */
 export declare function createPipeline(config: PipelineConfig): (req: Request) => Promise<Response>;
 //# sourceMappingURL=pipeline.d.ts.map

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

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

package/dist/server/port-resolution.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Port resolution for the dev server, Vite preview, and the Node
+ * production preview server.
+ *
+ * Behavior (see TIM-842):
+ *
+ *   1. Default port is **3000** for both dev and prod.
+ *   2. If the user did NOT set an explicit port, auto-bump from 3000
+ *      until a free port is found (3000 → 3001 → 3002 → …).
+ *   3. If the user DID set an explicit port (via `--port`, `PORT` env
+ *      var, or `vite.config.ts` `server.port`), use it as-is and let
+ *      the bind fail loudly on conflict (`strictPort: true`).
+ *
+ * The port-bump probe is performed by binding the **actual** server
+ * (e.g. the dev holding server) — not a throwaway probe — so there is
+ * no time-of-check / time-of-use race between probing and listening.
+ *
+ * Design doc: 21-dev-server.md §"Default Port and Auto-Bump".
+ */
+/** Default port used by `timber dev` and `timber preview`. */
+export declare const DEFAULT_PORT = 3000;
+/**
+ * A function that attempts to bind to a given port.
+ *
+ * Resolves with the bound port on success. Rejects with an error
+ * (typically with `code === 'EADDRINUSE'`) on failure.
+ */
+export type ListenFn = (port: number) => Promise<number>;
+export interface ResolvePortInput {
+    /**
+     * Port read from `vite.config.ts` `server.port` or the `--port` CLI
+     * flag (Vite merges `--port` into `userConfig.server.port` before
+     * plugins see it).
+     */
+    configPort?: number | undefined;
+    /** Raw value of `process.env.PORT`. */
+    envPort?: string | undefined;
+    /** Default port to use when neither `configPort` nor `envPort` is set. */
+    defaultPort?: number;
+}
+export interface ResolvedPortInput {
+    /** Port to start binding from. */
+    port: number;
+    /**
+     * `true` if the port came from an explicit user override (config or
+     * env). When `true`, callers must NOT auto-bump and must surface
+     * `EADDRINUSE` to the user.
+     */
+    explicit: boolean;
+}
+/**
+ * Pure: compute the starting port from config / env / defaults.
+ *
+ * Performs no I/O — pair with {@link bindWithBump} to actually listen.
+ */
+export declare function resolveStartPort(input: ResolvePortInput): ResolvedPortInput;
+export interface BindWithBumpOptions {
+    /** First port to attempt. */
+    startPort: number;
+    /**
+     * If `true`, increment the port and retry on `EADDRINUSE`. If
+     * `false`, attempt once and let the error propagate.
+     */
+    autoBump: boolean;
+    /** Maximum number of port attempts when `autoBump` is `true`. */
+    maxAttempts?: number;
+}
+export interface BindWithBumpResult {
+    /** Port that was actually bound. */
+    port: number;
+    /** `true` if the bound port differs from `startPort`. */
+    bumped: boolean;
+}
+/**
+ * Bind a server starting at `startPort`, optionally bumping the port
+ * on `EADDRINUSE` until a free one is found.
+ *
+ * Use this with the actual server you intend to keep listening (e.g.
+ * the dev holding server). Pairing the probe with the real listen
+ * eliminates the TOCTOU race that a throwaway probe would introduce.
+ */
+export declare function bindWithBump(listen: ListenFn, options: BindWithBumpOptions): Promise<BindWithBumpResult>;
+/** True if `err` is a Node `EADDRINUSE` error from `server.listen()`. */
+export declare function isAddrInUse(err: unknown): boolean;
+export interface StartDevServerPortInput {
+    /** Resolved port from `userConfig.server?.port` (or `--port`), or undefined. */
+    configPort: number | undefined;
+    /** Raw `process.env.PORT` value. */
+    envPort: string | undefined;
+    /** ListenFn for the holding server (or any pre-bind probe target). */
+    listen: ListenFn;
+    /** Logger — defaults to `console`. Injected for tests. */
+    log?: (msg: string) => void;
+    warn?: (msg: string) => void;
+}
+export interface StartDevServerPortResult {
+    /** Port chosen for both the holding server and Vite's dev server. */
+    port: number;
+    /** True if the user explicitly set the port (=> Vite must `strictPort: true`). */
+    explicit: boolean;
+    /** True if the holding server actually bound the port. */
+    bound: boolean;
+}
+/**
+ * Run the full dev-server port resolution + holding-server bind sequence.
+ *
+ * Resolves the port from config / env / default, attempts to bind the
+ * holding server (auto-bumping when the port came from the default),
+ * and logs the chosen URL. On a clean failure for an explicit port, it
+ * warns and falls back to the requested port so Vite can surface the
+ * conflict via `strictPort: true`.
+ *
+ * Extracted from `index.ts` so the rootSync `config()` hook stays
+ * focused on plugin assembly.
+ */
+export declare function startDevServerPort(input: StartDevServerPortInput): Promise<StartDevServerPortResult>;
+//# sourceMappingURL=port-resolution.d.ts.map

package/dist/server/port-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-resolution.d.ts","sourceRoot":"","sources":["../../src/server/port-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAIzD,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CAiB3E;AAID,MAAM,WAAW,mBAAmB;IAClC,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAkB7B;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIjD;AAID,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,oCAAoC;IACpC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,sEAAsE;IACtE,MAAM,EAAE,QAAQ,CAAC;IACjB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,QAAQ,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,wBAAwB,CAAC,CAqCnC"}