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

package/dist/server/error-boundary-wrapper.d.ts

@@ -1,17 +1,109 @@
 /**
- * Error boundary wrapper — wraps a React element in error boundaries from a route segment.
+ * Error boundary wrapper — wraps a React element in the error boundaries
+ * declared by a route segment (`{status}.tsx`, `4xx.tsx`/`5xx.tsx`, `error.tsx`).
  *
- * Extracted to allow reuse by both rsc-entry.ts and route-element-builder.ts.
- * See design/10-error-handling.md.
+ * This is the single implementation of that walk. It is driven by the
+ * request-time renderer walking the runtime manifest (`SegmentNode<ManifestFile>`):
+ *
+ *   - `route-element-builder.ts` / `slot-resolver.ts`
+ *
+ * `errorBoundaryComponent` is injected rather than imported: `TimberErrorBoundary`
+ * is a `'use client'` module, and importing it here would pull client code into
+ * every consumer. `tests/use-client-pipeline.test.ts` walks the import graph
+ * from this file to enforce that no `client/` module is reachable at any depth.
+ *
+ * See design/10-error-handling.md §"Status-Code File Variants".
+ */
+import type { ReactNode } from 'react';
+import type { SegmentNode } from '../routing/types.ts';
+import { type LoadedComponent } from './utils/element-type.ts';
+/**
+ * Framework-injected error boundary wrapper.
+ * Wraps content with status-code error boundary handling.
+ *
+ * Field types must agree with `TimberErrorBoundaryProps` in
+ * `client/error-boundary.tsx`. The two are kept structurally compatible by
+ * convention rather than by direct type import — this is the server-side
+ * construction site and may not import types from a 'use client' module.
  */
-import type { ManifestSegmentNode } from './route-matcher.js';
+export interface ErrorBoundaryProps {
+    /** The component to render when an error is caught. */
+    fallbackComponent?: LoadedComponent;
+    /** Status code filter: 400 = any 4xx, 500 = any 5xx, specific number = exact match. */
+    status?: number;
+    /**
+     * Segment key of the segment that declared this boundary. An in-tree deny
+     * catch site that matched a file it may not render in place re-throws with
+     * that file's owning key on the signal; boundaries whose key differs
+     * decline, so the deny page lands at its owner rather than at the first
+     * boundary the throw happens to pass. Unset for slot boundaries and for
+     * construction sites with no deny chains — an unkeyed boundary declines
+     * every owner-addressed deny. See TIM-1356.
+     */
+    segmentKey?: string;
+    /**
+     * Catch denies only; re-throw every other error. Set on the copy of a
+     * segment's boundaries that sits outside its layout, which exists to give a
+     * deny thrown from the layout's own chrome a catcher at the right position
+     * without changing where a 5xx from that chrome goes. See TIM-1450.
+     */
+    denyOnly?: boolean;
+    /**
+     * The boundary belongs to a parallel slot. A slot degrading is the page
+     * staying: its status pages never set the document status and never tell
+     * the segment cache the main route's chain is gone. Set on every boundary
+     * a slot's files declare, not only the catch-all outside them — the
+     * identity is the slot's, not the file's (codex on #1138).
+     */
+    isSlotBoundary?: boolean;
+    children: ReactNode;
+}
 /**
- * Wrap an element in error boundaries defined by a route segment.
+ * How to load a route file's module. Only `default` is read. A module that
+ * fails to load resolves to `null` — the loader must not reject, because
+ * building an error boundary must not itself throw (TIM-584). The server
+ * injects `loadFallbackModule`, which logs and reports the failed load before
+ * returning `null`, so a broken status or error page is never skipped
+ * silently (TIM-1458). The walk deliberately does not catch a rejection:
+ * a catch here would be the silent skip.
+ */
+type BoundaryModuleLoader<TFile> = (file: TFile) => {
+    default?: unknown;
+} | null | Promise<{
+    default?: unknown;
+} | null>;
+/** Everything the walk needs from its host environment. */
+export interface ErrorBoundaryWrapConfig<TFile, TElement> {
+    /** `React.createElement` or an equivalent element factory. */
+    createElement: (type: unknown, props: object) => TElement;
+    /** Loads a route file's module; resolves to `null` when it fails. See `BoundaryModuleLoader`. */
+    loadModule: BoundaryModuleLoader<TFile>;
+    /**
+     * The error boundary component to instantiate (`TimberErrorBoundary`, or a
+     * host-specific stand-in). Injected — see the module docstring.
+     */
+    errorBoundaryComponent: unknown;
+    /** Segment key stamped on every boundary this walk creates. See `ErrorBoundaryProps`. */
+    segmentKey?: string;
+    /** Stamped on every boundary this walk creates. See `ErrorBoundaryProps`. */
+    denyOnly?: boolean;
+    /** Stamped on every boundary this walk creates. See `ErrorBoundaryProps`. */
+    isSlotBoundary?: boolean;
+}
+/**
+ * Wrap an element in the error boundaries declared by a route segment.
+ *
+ * Wrapping is applied inside-out — the last wrap produces the outermost
+ * boundary — so the processing order below is innermost to outermost:
+ *
+ * 1. Specific status files (e.g. `404.tsx`, `503.tsx`) — highest priority at runtime
+ * 2. Category catch-alls (`4xx.tsx`, `5xx.tsx`)
+ * 3. `error.tsx` — catches anything not matched by a status file
+ *
+ * The order is load-bearing: it decides which boundary catches a given throw.
  *
- * Processing order (innermost to outermost):
- * 1. Specific status files (e.g., 404.tsx, 500.tsx) — highest priority at runtime
- * 2. Category catch-alls (4xx.tsx, 5xx.tsx)
- * 3. error.tsx — catches anything not matched by status files
+ * See design/10-error-handling.md §"Format-Aware Fallback Chains".
  */
-export declare function wrapSegmentWithErrorBoundaries(segment: ManifestSegmentNode, element: React.ReactElement, h: (...args: unknown[]) => React.ReactElement): Promise<React.ReactElement>;
+export declare function wrapSegmentWithErrorBoundaries<TFile, TElement extends ReactNode>(segment: SegmentNode<TFile>, element: TElement, config: ErrorBoundaryWrapConfig<TFile, TElement>): Promise<TElement>;
+export {};
 //# sourceMappingURL=error-boundary-wrapper.d.ts.map

package/dist/server/error-boundary-wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-boundary-wrapper.d.ts","sourceRoot":"","sources":["../../src/server/error-boundary-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,KAAK,CAAC,YAAY,EAC3B,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,KAAK,CAAC,YAAY,GAC5C,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CA8C7B"}
+{"version":3,"file":"error-boundary-wrapper.d.ts","sourceRoot":"","sources":["../../src/server/error-boundary-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAEnF;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,KAAK,oBAAoB,CAAC,KAAK,IAAI,CACjC,IAAI,EAAE,KAAK,KACR;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,OAAO,CAAC;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAC,CAAC;AAE1E,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB,CAAC,KAAK,EAAE,QAAQ;IACtD,8DAA8D;IAC9D,aAAa,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,QAAQ,CAAC;IAC1D,iGAAiG;IACjG,UAAU,EAAE,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACxC;;;OAGG;IACH,sBAAsB,EAAE,OAAO,CAAC;IAChC,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAsCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,8BAA8B,CAAC,KAAK,EAAE,QAAQ,SAAS,SAAS,EACpF,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,EAC3B,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,uBAAuB,CAAC,KAAK,EAAE,QAAQ,CAAC,GAC/C,OAAO,CAAC,QAAQ,CAAC,CAmCnB"}

package/dist/server/error-response-headers.d.ts

@@ -0,0 +1,3 @@
+/** Preserve request-wide metadata when replacing a failed response body. */
+export declare function errorResponseHeaders(responseHeaders?: Headers): Headers;
+//# sourceMappingURL=error-response-headers.d.ts.map

package/dist/server/error-response-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-response-headers.d.ts","sourceRoot":"","sources":["../../src/server/error-response-headers.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,OAAO,CAcvE"}

package/dist/server/fallback-error.d.ts

@@ -8,21 +8,33 @@
  * In production: attempts to render root error pages (500.tsx / 5xx.tsx /
  * error.tsx) via the normal RSC → SSR pipeline. Stack traces are never
  * exposed to the client (design/13-security.md principle 4).
+ *
+ * A route.ts match, in dev or production, gets the API route's JSON format
+ * instead: the `500.json` / `5xx.json` chain, then the bare
+ * `{"error": true, "status": 500}` body. That is the same format its denies
+ * use (design/10-error-handling.md §"JSON Error Pages").
  */
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
+import type { RouteMatch } from './pipeline.ts';
+import { type ManifestSegmentNode } from './route-matcher.ts';
+import type { ClientBootstrapConfig } from './html-injectors.ts';
+import type { GlobalErrorFile } from './rsc-entry/error-renderer.ts';
 /**
  * Render a fallback error page when the render pipeline throws.
  *
+ * For a route.ts match: the JSON status chain.
  * In dev: styled HTML with error details.
  * In prod: renders root error pages via renderErrorPage.
  */
-export declare function renderFallbackError(error: unknown, req: Request, responseHeaders: Headers, isDev: boolean, rootSegment: ManifestSegmentNode, clientBootstrap: ClientBootstrapConfig): Promise<Response>;
+export declare function renderFallbackError(error: unknown, req: Request, responseHeaders: Headers, match: RouteMatch | undefined, isDev: boolean, rootSegment: ManifestSegmentNode, clientBootstrap: ClientBootstrapConfig, globalError?: GlobalErrorFile, projectRoot?: string, hmrOptions?: import('../dev-tools/dev-page-shell.ts').DevErrorHmrOptions): Promise<Response>;
 /**
- * Render a dev-mode 500 error page with error message and stack trace.
+ * Render a dev-mode 500 error page with error details, source context,
+ * classified stack trace, and copy button.
+ *
+ * Dynamically imports the shared template from `plugins/dev-error-page.ts`
+ * so it is NOT pulled into production server bundles. The Vite client script
+ * is injected so the error overlay fires when the HMR WebSocket connects.
  *
- * Returns an HTML Response that displays the error in a styled page.
- * The Vite HMR client script is included so the error overlay still fires.
+ * Dev-only — the dynamic import has zero production cost.
  */
-export declare function renderDevErrorPage(error: unknown): Response;
+export declare function renderDevErrorPage(error: unknown, projectRoot?: string, hmrOptions?: import('../dev-tools/dev-page-shell.ts').DevErrorHmrOptions): Promise<Response>;
 //# sourceMappingURL=fallback-error.d.ts.map

package/dist/server/fallback-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fallback-error.d.ts","sourceRoot":"","sources":["../../src/server/fallback-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,OAAO,EACxB,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,mBAAmB,EAChC,eAAe,EAAE,qBAAqB,GACrC,OAAO,CAAC,QAAQ,CAAC,CA4BnB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAmF3D"}
+{"version":3,"file":"fallback-error.d.ts","sourceRoot":"","sources":["../../src/server/fallback-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAIrE;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,OAAO,EACxB,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,mBAAmB,EAChC,eAAe,EAAE,qBAAqB,EACtC,WAAW,CAAC,EAAE,eAAe,EAC7B,WAAW,CAAC,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,OAAO,gCAAgC,EAAE,kBAAkB,GACvE,OAAO,CAAC,QAAQ,CAAC,CA8CnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,OAAO,EACd,WAAW,CAAC,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,OAAO,gCAAgC,EAAE,kBAAkB,GACvE,OAAO,CAAC,QAAQ,CAAC,CAwBnB"}

package/dist/server/flight-injection-state.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared state machine types and transitions for RSC Flight injection.
+ *
+ * Both html-injectors.ts (Web Streams) and node-stream-transforms.ts
+ * (Node.js streams) implement identical state transitions — only the
+ * I/O primitives differ. This module defines the discriminated union
+ * states and the transition map once.
+ *
+ * Valid state flow:
+ *   init → streaming → flushing → done
+ *   (any) → error
+ *
+ * Suffix stripping (</body></html>) is handled by a separate
+ * createMoveSuffixStream / createNodeMoveSuffixTransform upstream
+ * in the pipeline (TIM-530). The flight injector only interleaves
+ * RSC scripts between HTML chunks — no suffix tracking needed.
+ *
+ * Design doc: 02-rendering-pipeline.md
+ */
+import type { TransitionMap } from '../utils/state-machine.ts';
+/** Waiting for first HTML chunk. Pull loop not started. */
+export interface InitState {
+    phase: 'init';
+}
+/** HTML chunks flowing, pull loop running. */
+export interface StreamingState {
+    phase: 'streaming';
+}
+/** HTML stream done (flush fired). Draining remaining RSC chunks. */
+export interface FlushingState {
+    phase: 'flushing';
+}
+/** All streams consumed. Terminal state. */
+export interface DoneState {
+    phase: 'done';
+}
+/** Pull loop failed. Terminal state with captured error. */
+export interface ErrorState {
+    phase: 'error';
+    error: unknown;
+}
+export type FlightInjectionState = InitState | StreamingState | FlushingState | DoneState | ErrorState;
+/** First HTML chunk arrived — start the pull loop. */
+export interface FirstChunkEvent {
+    type: 'FIRST_CHUNK';
+}
+/** HTML stream finished (flush/end). */
+export interface HtmlDoneEvent {
+    type: 'HTML_DONE';
+}
+/** RSC pull loop completed (all chunks read or stream closed). */
+export interface PullDoneEvent {
+    type: 'PULL_DONE';
+}
+/** RSC pull loop encountered an error. */
+export interface PullErrorEvent {
+    type: 'PULL_ERROR';
+    error: unknown;
+}
+export type FlightInjectionEvent = FirstChunkEvent | HtmlDoneEvent | PullDoneEvent | PullErrorEvent;
+export declare const flightInjectionTransitions: TransitionMap<FlightInjectionState, FlightInjectionEvent>;
+/** Whether the HTML stream has finished (flush/end fired). */
+export declare function isHtmlDone(state: FlightInjectionState): boolean;
+/** Whether the RSC pull loop has completed. */
+export declare function isPullDone(state: FlightInjectionState): boolean;
+//# sourceMappingURL=flight-injection-state.d.ts.map

package/dist/server/flight-injection-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flight-injection-state.d.ts","sourceRoot":"","sources":["../../src/server/flight-injection-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAI/D,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,cAAc,GACd,aAAa,GACb,SAAS,GACT,UAAU,CAAC;AAIf,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,aAAa,GAAG,aAAa,GAAG,cAAc,CAAC;AAIpG,eAAO,MAAM,0BAA0B,EAAE,aAAa,CAAC,oBAAoB,EAAE,oBAAoB,CAgB9F,CAAC;AAIJ,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAE/D;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAE/D"}

package/dist/server/flight-scripts.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared Flight data script generation.
+ *
+ * Both html-injectors.ts (Web Streams / dev) and node-stream-transforms.ts
+ * (Node streams / production) use this module to generate inline `<script>`
+ * tags for RSC Flight data injection.
+ *
+ * The init script goes in `<head>` as part of the HTML shell (guaranteed
+ * to execute before any streaming chunk scripts). Push scripts are emitted
+ * as RSC chunks arrive during streaming.
+ *
+ * Every generator takes the request's CSP nonce (from `getCspNonce()`)
+ * so the tags run under a nonce-based `script-src` (TIM-1414).
+ *
+ * See design/02-rendering-pipeline.md, LOCAL-415
+ */
+/**
+ * Escape a JSON string for safe embedding inside an HTML `<script>` tag.
+ *
+ * Prevents XSS via `</script>` injection and handles Unicode line/paragraph
+ * separators that are valid JSON but invalid in JS string literals (pre-ES2019).
+ */
+export declare function htmlEscapeJsonString(str: string): string;
+/**
+ * Generate the init script that creates the Flight data array.
+ *
+ * This MUST be included in `<head>` (via headHtml) so it executes before
+ * any streaming chunk scripts arrive in `<body>`. The array is created
+ * unconditionally — no `||[]` guard needed in push scripts.
+ *
+ * Also emits the bootstrap signal [0] which tells the client that
+ * Flight data is active for this page.
+ */
+export declare function flightInitScript(nonce?: string): string;
+/**
+ * Generate a push script for a Flight data chunk.
+ *
+ * Normally the init script runs first (it's in `<head>`), so
+ * `self.__timber_f` already exists. However, shell-less status pages
+ * (e.g. standalone error pages) may have no `<head>` tag, so the init script
+ * never runs. The `||[]` guard ensures the array is created on first
+ * push if needed, preventing a TypeError. See TIM-559.
+ */
+export declare function flightChunkScript(data: string, nonce?: string): string;
+//# sourceMappingURL=flight-scripts.d.ts.map

package/dist/server/flight-scripts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flight-scripts.d.ts","sourceRoot":"","sources":["../../src/server/flight-scripts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMxD;AAOD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtE"}

package/dist/server/form-data.d.ts

@@ -34,6 +34,18 @@ export declare function parseFormData(formData: FormData): Record<string, unknow
  * ```
  */
 export declare const coerce: {
+    /**
+     * Coerce an empty string to undefined for optional text fields.
+     * Use with `.optional()` schemas where an empty input means "not provided".
+     *
+     * ```ts
+     * // Zod
+     * z.unknown().transform(coerce.text).pipe(z.string().optional())
+     * // Valibot
+     * v.pipe(v.unknown(), v.transform(coerce.text), v.optional(v.string()))
+     * ```
+     */
+    text(value: unknown): string | undefined;
     /**
      * Coerce a string to a number.
      * - `"42"` → `42`
@@ -56,5 +68,34 @@ export declare const coerce: {
      * - Invalid JSON → `undefined` (schema validation will catch this)
      */
     json(value: unknown): unknown;
+    /**
+     * Coerce a date string to a Date object.
+     * Handles `<input type="date">` (`"2024-01-15"`), `<input type="datetime-local">`
+     * (`"2024-01-15T10:30"`), and full ISO 8601 strings.
+     * - Valid date string → `Date`
+     * - `""` / `undefined` / `null` → `undefined`
+     * - Invalid date strings → `undefined` (schema validation will catch this)
+     * - Impossible dates that `new Date()` silently normalizes (e.g. Feb 31) → `undefined`
+     */
+    date(value: unknown): Date | undefined;
+    /**
+     * Create a File coercion function with optional size and mime type validation.
+     * Returns the File if valid, `undefined` otherwise.
+     *
+     * ```ts
+     * // Basic — just checks it's a real File
+     * z.preprocess(coerce.file(), z.instanceof(File))
+     *
+     * // With constraints
+     * z.preprocess(
+     *   coerce.file({ maxSize: 5 * 1024 * 1024, accept: ['image/png', 'image/jpeg'] }),
+     *   z.instanceof(File)
+     * )
+     * ```
+     */
+    file(options?: {
+        maxSize?: number;
+        accept?: string[];
+    }): (value: unknown) => File | undefined;
 };
 //# sourceMappingURL=form-data.d.ts.map

package/dist/server/form-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"form-data.d.ts","sourceRoot":"","sources":["../../src/server/form-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzE;AAyED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM;IACjB;;;;;;OAMG;kBACW,OAAO,GAAG,MAAM,GAAG,SAAS;IAS1C;;;;;OAKG;oBACa,OAAO,GAAG,OAAO;IAOjC;;;;;OAKG;gBACS,OAAO,GAAG,OAAO;CAS9B,CAAC"}
+{"version":3,"file":"form-data.d.ts","sourceRoot":"","sources":["../../src/server/form-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2BzE;AAqFD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM;IACjB;;;;;;;;;;OAUG;IACH,IAAI,QAAQ,OAAO,GAAG,MAAM,GAAG,SAAS;IAMxC;;;;;;OAMG;IACH,MAAM,QAAQ,OAAO,GAAG,MAAM,GAAG,SAAS;IAS1C;;;;;OAKG;IACH,QAAQ,QAAQ,OAAO,GAAG,OAAO;IAOjC;;;;;OAKG;IACH,IAAI,QAAQ,OAAO,GAAG,OAAO;IAU7B;;;;;;;;OAQG;IACH,IAAI,QAAQ,OAAO,GAAG,IAAI,GAAG,SAAS;IAgCtC;;;;;;;;;;;;;;OAcG;IACH,IAAI,WAAW;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,SAAS;CAmB9F,CAAC"}

package/dist/server/form-flash.d.ts

@@ -11,9 +11,9 @@
  *
  * The flash data is server-side only — never serialized to cookies or headers.
  *
- * See design/08-forms-and-actions.md §"No-JS Error Round-Trip"
+ * See design/08-forms-and-actions.md §"No-JS Result Round-Trip"
  */
-import type { ValidationErrors } from './action-client.js';
+import type { ValidationErrors } from './action-client.ts';
 /**
  * Flash data injected into the re-render after a no-JS form submission.
  *

package/dist/server/head-response.d.ts

@@ -0,0 +1,35 @@
+/**
+ * HEAD body stripping — RFC 9110 §9.3.2.
+ *
+ * "The HEAD method is identical to GET except that the server MUST NOT send
+ * content in the response." The headers, however, must be the ones the
+ * corresponding GET would have produced — which is why timber renders the
+ * route in full and discards the body here rather than short-circuiting the
+ * render. Content-Type, Content-Length, Set-Cookie, cache directives and
+ * everything else ride through untouched.
+ *
+ * Node's `ServerResponse` happens to discard writes for HEAD, so the wire is
+ * usually correct even without this. That is a property of one adapter, not of
+ * the `Response` object: static generation, the Cloudflare and Nitro adapters,
+ * tests, and anything calling the pipeline handler as a function all observe
+ * the `Response` directly and saw the full body before TIM-1324.
+ *
+ * The pipeline applies this at its single exit so every response shape is
+ * covered — page render, API route, metadata route, deny page, error page,
+ * proxy short-circuit. The unit-level producer that is also reachable as a
+ * standalone function (`handleRouteRequest`) calls it too, so it honours HEAD
+ * on its own; it shares this implementation rather than repeating it, and
+ * applying it twice is a no-op.
+ */
+/**
+ * Return a bodyless copy of `response` when `method` is HEAD.
+ *
+ * A no-op for every other method and for responses that already carry no body
+ * (204, 304, redirects), so callers do not need to pre-check either.
+ *
+ * The discarded stream is cancelled: an SSR render that reached this point has
+ * a live producer attached, and dropping the reference without cancelling
+ * leaks it for the lifetime of the render (design/13-security.md A4).
+ */
+export declare function stripHeadBody(response: Response, method: string): Response;
+//# sourceMappingURL=head-response.d.ts.map

package/dist/server/head-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"head-response.d.ts","sourceRoot":"","sources":["../../src/server/head-response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAmB1E"}