@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

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

@@ -13,7 +13,7 @@
  *
  * See design/08-forms-and-actions.md §"No-JS Error 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 two unit-level producers that are also reachable as
+ * standalone functions (`handleRouteRequest`, `handleApiRoute`) call it too, so
+ * each honours HEAD on its own; they share 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"}

package/dist/server/html-injector-core.d.ts

@@ -0,0 +1,257 @@
+/**
+ * HTML injector core — pure stateful helpers for streaming HTML post-processing.
+ *
+ * These helpers contain the actual byte/string logic for the held-flush
+ * streaming pipeline (buffered transforms, suffix moving, head injection,
+ * RSC flight interleaving). They are stream-shape agnostic: they know
+ * nothing about Web `TransformStream` or Node.js `Transform` and contain
+ * no `setImmediate` scheduling or controller plumbing.
+ *
+ * The Web Stream wrapper (`html-injectors.ts`) and the Node Stream wrapper
+ * (`node-stream-transforms.ts`) compose these helpers behind whichever
+ * stream shape their target runtime needs:
+ *
+ *   - On Cloudflare/edge: Web `TransformStream` wraps the helpers.
+ *   - On Node.js/Bun: Node `Transform` wraps the helpers (faster — C++ streams).
+ *
+ * Keeping this module split per-shape (rather than one file exporting both)
+ * preserves the build-time tree-shake: Cloudflare bundles never import
+ * `node:stream` even transitively. Only the helpers below are shared.
+ *
+ * **Pure functions only.** Anything that touches a stream API, schedules
+ * a tick, or owns a controller belongs in the wrapper, not here.
+ *
+ * Design docs: 02-rendering-pipeline.md §"Streaming Constraints", 18-build-system.md §"Entry Files"
+ */
+import { type Machine } from '../utils/state-machine.ts';
+import { type FlightInjectionState, type FlightInjectionEvent } from './flight-injection-state.ts';
+/** Closing tags React Fizz emits inside the shell chunk. */
+export declare const SUFFIX = "</body></html>";
+/** UTF-8 bytes of {@link SUFFIX}. Cached so wrappers don't re-encode per request. */
+export declare const SUFFIX_BYTES: Uint8Array;
+/** Encode a UTF-8 string. Convenience for wrappers that need a single source of truth. */
+export declare function encodeUtf8(text: string): Uint8Array;
+/**
+ * Pure buffer state for the buffered transform.
+ *
+ * Both Web and Node wrappers want the same behaviour: collect chunks that
+ * arrive in the same event-loop tick, decide whether the buffer has grown
+ * beyond `maxBufferByteLength` and must flush synchronously, then emit a
+ * single concatenated chunk on the next tick.
+ *
+ * The only thing the two wrappers disagree on is *who schedules the tick*
+ * (`setImmediate` callback vs Promise-based) and *how to push the merged
+ * chunk* (`controller.enqueue` vs `transform.push`). This class owns
+ * everything else.
+ */
+export declare class BufferAggregator {
+    private chunks;
+    private byteLength;
+    private readonly maxBufferByteLength;
+    constructor(maxBufferByteLength?: number);
+    /**
+     * Append a chunk. Returns `true` if the caller should flush synchronously
+     * right now (the buffer has reached the byte cap), `false` if a deferred
+     * tick-end flush is sufficient.
+     */
+    append(chunk: Uint8Array): boolean;
+    /** Drain the buffer into a single concatenated chunk, or `null` if empty. */
+    drain(): Uint8Array | null;
+    get bufferedByteLength(): number;
+    get isEmpty(): boolean;
+}
+/**
+ * Result of feeding one chunk through the suffix-mover state.
+ *
+ * - `passthrough` — already found and removed the suffix on a previous chunk.
+ *   Caller emits the chunk unchanged.
+ * - `noSuffix` — current chunk does not contain the suffix. When `emitSafe`
+ *   is set, the caller must emit those bytes (the safe head minus the
+ *   retained tail). When `emitSafe` is null, the entire chunk was absorbed
+ *   into the tail buffer and there is nothing to emit yet.
+ * - `suffixFound` — caller emits `before` and `after` (skipping the suffix
+ *   itself). The suffix will be re-emitted later by {@link suffixFlush}.
+ */
+export type SuffixChunkResult = {
+    kind: 'passthrough';
+} | {
+    kind: 'noSuffix';
+    emitSafe?: Uint8Array;
+} | {
+    kind: 'suffixFound';
+    before: Uint8Array | null;
+    after: Uint8Array | null;
+};
+/**
+ * State for the suffix mover. Works entirely in bytes — no TextDecoder
+ * needed because `</body></html>` is pure ASCII and its byte values are
+ * all < 0x80, so the pattern cannot appear inside multi-byte UTF-8
+ * sequences. This avoids the surrogate-pair and codepoint-corruption
+ * hazards that a text-based search + re-encode would introduce.
+ *
+ * We retain a trailing byte buffer (length `SUFFIX_BYTES.length - 1`)
+ * across chunks so the suffix is detected even when split across chunk
+ * boundaries — the same tail-buffer approach the head injector uses.
+ */
+export interface SuffixState {
+    found: boolean;
+    /** Trailing bytes from the previous chunk for cross-boundary search. */
+    tail: Uint8Array | null;
+    readonly tailLen: number;
+}
+export declare function createSuffixState(): SuffixState;
+/**
+ * Search a chunk for {@link SUFFIX_BYTES}. If found, mark state and return
+ * the surrounding bytes (the caller emits them; the suffix is held for the
+ * end of the stream). A trailing byte tail is retained across calls so the
+ * suffix is detected even when split across chunk boundaries.
+ *
+ * All output is raw byte slices — no text decoding or re-encoding — so
+ * multi-byte UTF-8 codepoints and astral characters are never corrupted.
+ */
+export declare function processSuffixChunk(state: SuffixState, chunk: Uint8Array): SuffixChunkResult;
+/**
+ * Final emit for the suffix mover. Returns any leftover tail bytes
+ * followed by the suffix. Always appends the suffix — even if none was
+ * ever observed in the input — so output is well-formed.
+ */
+export declare function suffixFlush(state: SuffixState): Uint8Array;
+/**
+ * Pure state for `injectHead`-style transforms: scan for a target tag,
+ * inject `content` once at the matching position, then pass everything
+ * else through. We keep a small trailing string buffer (just under the
+ * length of the target tag) so the tag can be detected even when split
+ * across chunk boundaries.
+ *
+ * The `decoder` is a long-lived `TextDecoder` reused across every chunk
+ * with `{ stream: true }`. This is required so a UTF-8 codepoint that
+ * spans two chunks (e.g. the bytes of `é` arriving in two halves) is
+ * reassembled correctly. A fresh decoder per chunk would drop or
+ * replace the partial codepoint and corrupt streamed HTML.
+ */
+export interface InjectorState {
+    injected: boolean;
+    tail: string;
+    readonly content: string;
+    readonly targetTag: string;
+    readonly position: 'before' | 'after';
+    readonly tailLen: number;
+    readonly decoder: TextDecoder;
+}
+export interface InjectorOptions {
+    content: string;
+    targetTag: string;
+    position?: 'before' | 'after';
+}
+export declare function createInjectorState(options: InjectorOptions): InjectorState;
+/**
+ * Result of feeding one chunk through {@link processInjectorChunk}.
+ *
+ * - `passthrough` — already injected. Emit `chunk` unchanged.
+ * - `emit` — emit the returned bytes (or nothing if `null`).
+ *
+ * Note: when not yet injected and the target tag is not present, the
+ * helper still emits the *safe head* of the buffer — everything except
+ * the trailing `tailLen` characters that might be the start of the
+ * target tag spilled into the next chunk. The unsafe tail is held in
+ * `state.tail` for the next call.
+ */
+export type InjectorChunkResult = {
+    kind: 'passthrough';
+} | {
+    kind: 'emit';
+    bytes: Uint8Array | null;
+};
+export declare function processInjectorChunk(state: InjectorState, chunk: Uint8Array): InjectorChunkResult;
+/**
+ * Final emit for the injector. If the target tag never appeared, the
+ * leftover tail bytes are returned so they aren't lost. (The injection
+ * itself is silently skipped — same behaviour as before extraction.)
+ */
+export declare function injectorFlush(state: InjectorState): Uint8Array | null;
+/**
+ * Pure async core of the RSC flight-injection transform.
+ *
+ * Both wrappers (Web `TransformStream` and Node `Transform`) implement the
+ * exact same protocol around an RSC reader:
+ *
+ *   1. On the first HTML chunk, send `FIRST_CHUNK` and start the pull loop.
+ *   2. The pull loop reads from `rscReader` (timeout-guarded), wraps each
+ *      chunk in a `<script>` via `flightChunkScript`, and pushes it onto a
+ *      pending queue. Between reads, it yields with a single-shot
+ *      `setImmediate` so HTML chunks get event-loop priority — and after
+ *      yielding, it drains the queue (via the wrapper's `onYieldDrain`)
+ *      so flight data reaches the client at shell-flush time.
+ *   3. After every emitted HTML chunk, the wrapper drains the queue.
+ *   4. On `flush()` the wrapper sends `HTML_DONE` and awaits `pullPromise`.
+ *      No polling — just `.then()`.
+ *
+ * The wrappers only differ in:
+ *   - How they push bytes (controller.enqueue vs transform.push).
+ *   - How they signal a terminal error (controller.error vs transform.destroy).
+ *
+ * This class owns the state machine, the pending queue, and the pull
+ * loop itself. The wrapper supplies the drain callback and consumes the
+ * pending queue + machine state to decide what to push.
+ *
+ * **No polling.** See design/02-rendering-pipeline.md §"No Polling".
+ * **Always timeout-guarded reads.** Per design/02 §"Streaming Constraints".
+ */
+export interface FlightInjectorOptions {
+    /**
+     * 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). `0` ("disabled") still enforces a 120s ceiling
+     * so a stalled RSC stream can never hang the connection forever.
+     */
+    renderTimeoutMs?: number;
+    /** Signal that fires when an unhandled RSC error is detected. */
+    errorSignal?: AbortSignal;
+    /** Request CSP nonce, stamped on every emitted `<script>` (TIM-1414). */
+    nonce?: string;
+}
+export declare class FlightInjectorCore {
+    readonly machine: Machine<FlightInjectionState, FlightInjectionEvent>;
+    /** Script chunks waiting to be drained between HTML chunks. */
+    readonly pending: Uint8Array[];
+    private readonly rscReader;
+    private readonly timeoutMs;
+    private readonly errorSignal?;
+    private readonly nonce?;
+    private readonly decoder;
+    private pullPromise;
+    private _aborted;
+    constructor(rscStream: ReadableStream<Uint8Array>, options?: FlightInjectorOptions);
+    /** Tell the machine the first HTML chunk has arrived. Idempotent-ish: caller checks. */
+    notifyFirstChunk(): void;
+    /** Tell the machine HTML output is finished — pull loop will stop yielding. */
+    notifyHtmlDone(): void;
+    get isInit(): boolean;
+    get isPullDone(): boolean;
+    get hasPullPromise(): boolean;
+    /**
+     * Get (or start) the pull-loop promise. The wrapper calls this from
+     * `flush()` and chains `.then()` onto it — never `await` without an
+     * existing finish callback (we don't want to block transform()).
+     *
+     * `onYieldDrain` is invoked between RSC reads while HTML is still
+     * streaming. It must drain the pending queue into the output stream.
+     */
+    ensurePullLoop(onYieldDrain: () => void): Promise<void>;
+    /**
+     * Get the current terminal error if the machine is in the error phase,
+     * else `null`. Wrappers use this after a drain to decide whether to
+     * `controller.error()` / `transform.destroy()`.
+     */
+    get terminalError(): unknown;
+    /**
+     * Abort the pull loop and release the RSC reader. Called by stream
+     * wrappers when the HTML pipeline is torn down (Node `destroy()`,
+     * Web `cancel()`). Safe to call multiple times.
+     */
+    abort(reason?: unknown): void;
+    get isAborted(): boolean;
+    private runPullLoop;
+}
+//# sourceMappingURL=html-injector-core.d.ts.map

package/dist/server/html-injector-core.d.ts.map

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