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

package/src/server/{deny-page-resolver.ts → deny-boundary.ts}

@@ -1,23 +1,41 @@
 /**
- * Deny Page Resolver — resolves status-code file components for in-tree deny handling.
+ * Deny boundary subsystem — the in-tree DenySignal flow.
  *
- * When AccessGate or PageDenyBoundary catches a DenySignal, they need to
- * render the matching deny page (403.tsx, 4xx.tsx, error.tsx) as a normal
- * element in the React tree. This module resolves the deny page chain from
- * the segment chain — a list of fallback components ordered by specificity.
+ * Three things live together here because they form a single flow:
  *
- * The chain is built during buildRouteElement and passed as a prop to
- * AccessGate and PageDenyBoundary. At catch time, the first matching
- * component is rendered.
+ * 1. **Chain construction** (`buildDenyPageChain`) — walks the matched
+ *    segment chain at element-tree build time and produces a list of
+ *    `DenyPageEntry` records ordered by specificity (specific status →
+ *    category catch-all → `error.tsx`).
  *
- * See design/10-error-handling.md §"Status-Code Files", TIM-666.
+ * 2. **Runtime matching** (`renderMatchingDenyPage`) — picks the first
+ *    chain entry whose status filter matches the thrown DenySignal and
+ *    returns a React element for the matching component. Used by
+ *    `AccessGate` and `PageDenyBoundary` when they catch a deny.
+ *
+ * 3. **The page boundary itself** (`PageDenyBoundary`) — the async server
+ *    component that wraps a server-component page, calls it, and catches
+ *    `DenySignal` so the deny page renders in-tree (no throw reaches
+ *    React Flight, single render pass).
+ *
+ * Plus the ALS helpers (`setDenyStatus` / `getDenyStatus`) the boundary
+ * uses to thread the matched status code back to the pipeline so the
+ * HTTP status reflects the deny.
+ *
+ * Folded into one module from the former `deny-page-resolver.ts` and
+ * `page-deny-boundary.tsx` (TIM-853) — the names were misleading and the
+ * three pieces only made sense together.
+ *
+ * See design/04-authorization.md, design/10-error-handling.md, TIM-666.
  */
 
 import { createElement } from 'react';
 
-import type { ManifestSegmentNode } from './route-matcher.js';
-import { loadModule } from './safe-load.js';
 import { requestContextAls } from './als-registry.js';
+import { DenySignal } from './primitives.js';
+import { loadModule } from './safe-load.js';
+import { withSpan } from './tracing.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -29,7 +47,7 @@ export interface DenyPageEntry {
   component: (...args: unknown[]) => unknown;
 }
 
-// ─── Resolver ─────────────────────────────────────────────────────────────
+// ─── Chain Construction ──────────────────────────────────────────────────
 
 /**
  * Build the deny page fallback chain from the segment chain.
@@ -101,7 +119,7 @@ export async function buildDenyPageChain(
   return chain;
 }
 
-// ─── Matcher ──────────────────────────────────────────────────────────────
+// ─── Runtime Matcher ──────────────────────────────────────────────────────
 
 /**
  * Find the first deny page in the chain that matches the given status code.
@@ -131,7 +149,53 @@ export function renderMatchingDenyPage(
   return null;
 }
 
-// ─── ALS Helper ───────────────────────────────────────────────────────────
+// ─── Page Boundary ────────────────────────────────────────────────────────
+
+/**
+ * Async server component that wraps a page call with DenySignal catching.
+ *
+ * Calls the page component as an async function (the same thing React
+ * Flight does internally), awaits it, and catches DenySignal. On catch,
+ * renders the matching deny page in-tree. On success, returns the page's
+ * rendered output normally.
+ *
+ * Client component pages ('use client') are NOT wrapped — they can't call
+ * deny() (server-only API) and must go through createElement normally.
+ *
+ * No error reaches React Flight — the Flight stream is clean, SSR succeeds,
+ * and the entire request uses a single renderToReadableStream call.
+ */
+export async function PageDenyBoundary({
+  Page,
+  route,
+  denyPages,
+}: {
+  /** The page server component function. */
+  Page: (...args: unknown[]) => unknown;
+  /** Route path for OTEL tracing. */
+  route: string;
+  /** Deny page fallback chain from the segment chain. */
+  denyPages: DenyPageEntry[];
+}): Promise<React.ReactElement> {
+  try {
+    // Call the page as an async function — same as React Flight does.
+    // Wrap in OTEL span for tracing (replaces the TracedPage wrapper).
+    const result = await withSpan('timber.page', { 'timber.route': route }, () => Page({}));
+    return result as React.ReactElement;
+  } catch (error: unknown) {
+    if (error instanceof DenySignal) {
+      const denyElement = renderMatchingDenyPage(denyPages, error.status, error.data);
+      if (denyElement) {
+        setDenyStatus(error.status);
+        return denyElement;
+      }
+    }
+    // Non-deny errors (RedirectSignal, runtime errors) propagate normally.
+    throw error;
+  }
+}
+
+// ─── ALS Helpers ──────────────────────────────────────────────────────────
 
 /**
  * Set the deny status in the request context ALS.

package/src/server/deny-renderer.ts

@@ -22,8 +22,9 @@ import { DenySignal } from './primitives.js';
 import { logRenderError } from './logger.js';
 import { loadModule } from './safe-load.js';
 import { isDebug } from './debug.js';
+import { escapeHtml } from './utils/escape-html.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
-import { resolveManifestStatusFile } from './manifest-status-resolver.js';
+import { resolveStatusFile } from './status-code-resolver.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import type { RouteMatch } from './pipeline.js';
 import type { NavContext } from './ssr-entry.js';
@@ -87,7 +88,7 @@ export async function renderDenyPage(
   }
 
   // Page routes → component chain first, JSON fallback only if no component found.
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'component');
+  const resolution = resolveStatusFile(deny.status, segments, 'component');
 
   // No component status file — try JSON chain before bare fallback
   if (!resolution) {
@@ -99,7 +100,7 @@ export async function renderDenyPage(
   // Dev warning: JSON status file exists but is shadowed by the component chain.
   // This helps developers understand why their .json file isn't being served.
   if (isDebug()) {
-    const jsonResolution = resolveManifestStatusFile(deny.status, segments, 'json');
+    const jsonResolution = resolveStatusFile(deny.status, segments, 'json');
     if (jsonResolution) {
       console.warn(
         `[timber] ${jsonResolution.file.filePath} exists but is shadowed by ` +
@@ -190,7 +191,7 @@ export async function renderDenyPageAsRsc(
   responseHeaders: Headers,
   createDebugChannelSink: DebugChannelFactory
 ): Promise<Response> {
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'component');
+  const resolution = resolveStatusFile(deny.status, segments, 'component');
 
   if (!resolution) {
     responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
@@ -249,7 +250,7 @@ async function renderDenyPageJson(
   segments: ManifestSegmentNode[],
   responseHeaders: Headers
 ): Promise<Response | null> {
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'json');
+  const resolution = resolveStatusFile(deny.status, segments, 'json');
 
   if (!resolution) {
     return null;
@@ -280,10 +281,4 @@ function bareJsonResponse(status: number, responseHeaders: Headers): Response {
   });
 }
 
-function escapeHtml(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
+// escapeHtml imported from server/utils/escape-html.ts

package/src/server/early-hints-sender.ts

@@ -19,6 +19,7 @@
  */
 
 import { earlyHintsSenderAls } from './als-registry.js';
+import { swallow } from './logger.js';
 
 /** Function that sends Link header values as a 103 Early Hints response. */
 export type EarlyHintsSenderFn = (links: string[]) => void;
@@ -47,7 +48,7 @@ export function sendEarlyHints103(links: string[]): void {
   if (!sender) return;
   try {
     sender(links);
-  } catch {
-    // Sending 103 is best-effort — failure never blocks the request.
+  } catch (err) {
+    swallow(err, 'early hints 103 send failed');
   }
 }

package/src/server/fallback-error.ts

@@ -66,7 +66,7 @@ export async function renderFallbackError(
     // then fall through to global-error.tsx if those also fail.
     logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
   }
-  const match: RouteMatch = { segments: segments as never, segmentParams: {}, middlewareChain: [] };
+  const match: RouteMatch = { segments, segmentParams: {}, middlewareChain: [] };
   return renderErrorPage(
     error,
     500,
@@ -98,7 +98,7 @@ export async function renderDevErrorPage(error: unknown, projectRoot?: string):
   try {
     // Dynamic import — keeps dev-error-page.ts and its transitive deps
     // (dev-error-overlay.ts, @jridgewell/trace-mapping) out of production bundles.
-    const { generateDevErrorPage } = await import('../plugins/dev-error-page.js');
+    const { generateDevErrorPage } = await import('../dev-tools/error-page.js');
     html = generateDevErrorPage(err, 'render', root);
     // Inject Vite client script so the error overlay fires when HMR connects.
     html = html.replace(

package/src/server/html-injector-core.ts

@@ -0,0 +1,403 @@
+/**
+ * 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 { createMachine, type Machine } from '../utils/state-machine.js';
+import { flightChunkScript } from './flight-scripts.js';
+import {
+  flightInjectionTransitions,
+  isHtmlDone,
+  isPullDone,
+  type FlightInjectionState,
+  type FlightInjectionEvent,
+} from './flight-injection-state.js';
+import { withTimeout, RenderTimeoutError } from './render-timeout.js';
+
+// ─── Encoders / Constants ────────────────────────────────────────────────────
+
+const encoder = new TextEncoder();
+
+/** Closing tags React Fizz emits inside the shell chunk. */
+export const SUFFIX = '</body></html>';
+/** UTF-8 bytes of {@link SUFFIX}. Cached so wrappers don't re-encode per request. */
+export const SUFFIX_BYTES: Uint8Array = encoder.encode(SUFFIX);
+
+/** Encode a UTF-8 string. Convenience for wrappers that need a single source of truth. */
+export function encodeUtf8(text: string): Uint8Array {
+  return encoder.encode(text);
+}
+
+// ─── Buffered Aggregator ─────────────────────────────────────────────────────
+
+/**
+ * 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 class BufferAggregator {
+  private chunks: Uint8Array[] = [];
+  private byteLength = 0;
+
+  constructor(private readonly maxBufferByteLength: number = Infinity) {}
+
+  /**
+   * 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 {
+    this.chunks.push(chunk);
+    this.byteLength += chunk.byteLength;
+    return this.byteLength >= this.maxBufferByteLength;
+  }
+
+  /** Drain the buffer into a single concatenated chunk, or `null` if empty. */
+  drain(): Uint8Array | null {
+    if (this.chunks.length === 0) return null;
+
+    const merged = new Uint8Array(this.byteLength);
+    let offset = 0;
+    for (const chunk of this.chunks) {
+      merged.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    this.chunks = [];
+    this.byteLength = 0;
+    return merged;
+  }
+
+  get bufferedByteLength(): number {
+    return this.byteLength;
+  }
+
+  get isEmpty(): boolean {
+    return this.chunks.length === 0;
+  }
+}
+
+// ─── Suffix Mover ────────────────────────────────────────────────────────────
+
+/**
+ * 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. Caller emits unchanged.
+ * - `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' }
+  | { kind: 'suffixFound'; before: Uint8Array | null; after: Uint8Array | null };
+
+export interface SuffixState {
+  found: boolean;
+}
+
+export function createSuffixState(): SuffixState {
+  return { found: false };
+}
+
+/**
+ * Search a chunk for {@link SUFFIX}. If found, mark state and return the
+ * surrounding bytes (the caller emits them; the suffix is held for the
+ * end of the stream). The bytes-vs-text dance matches what both Web and
+ * Node implementations did before extraction — search via decoded UTF-8
+ * to avoid splitting multi-byte characters at the suffix boundary.
+ */
+export function processSuffixChunk(state: SuffixState, chunk: Uint8Array): SuffixChunkResult {
+  if (state.found) return { kind: 'passthrough' };
+
+  const text = new TextDecoder().decode(chunk, { stream: true });
+  const idx = text.indexOf(SUFFIX);
+  if (idx === -1) return { kind: 'noSuffix' };
+
+  state.found = true;
+
+  // Whole chunk was the suffix — nothing to emit before/after.
+  if (chunk.byteLength === SUFFIX_BYTES.byteLength) {
+    return { kind: 'suffixFound', before: null, after: null };
+  }
+
+  const beforeText = text.slice(0, idx);
+  const afterText = text.slice(idx + SUFFIX.length);
+  return {
+    kind: 'suffixFound',
+    before: beforeText ? encoder.encode(beforeText) : null,
+    after: afterText ? encoder.encode(afterText) : null,
+  };
+}
+
+/**
+ * Final emit for the suffix mover. Always returns the suffix bytes — even
+ * if no suffix was ever observed in the input — so output is well-formed.
+ */
+export function suffixFlush(_state: SuffixState): Uint8Array {
+  return SUFFIX_BYTES;
+}
+
+// ─── Tag Injector (head / body) ──────────────────────────────────────────────
+
+/**
+ * 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 function createInjectorState(options: InjectorOptions): InjectorState {
+  return {
+    injected: false,
+    tail: '',
+    content: options.content,
+    targetTag: options.targetTag,
+    position: options.position ?? 'before',
+    tailLen: options.targetTag.length - 1,
+    decoder: new TextDecoder('utf-8'),
+  };
+}
+
+/**
+ * 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 function processInjectorChunk(state: InjectorState, chunk: Uint8Array): InjectorChunkResult {
+  if (state.injected) return { kind: 'passthrough' };
+
+  // Reuse the long-lived decoder so split UTF-8 codepoints are preserved
+  // across chunk boundaries. See comment on InjectorState.decoder.
+  const decoded = state.decoder.decode(chunk, { stream: true });
+  const text = state.tail + decoded;
+  const tagIndex = text.indexOf(state.targetTag);
+
+  if (tagIndex !== -1) {
+    const splitPoint = state.position === 'before' ? tagIndex : tagIndex + state.targetTag.length;
+    const before = text.slice(0, splitPoint);
+    const after = text.slice(splitPoint);
+    state.injected = true;
+    state.tail = '';
+    return { kind: 'emit', bytes: encoder.encode(before + state.content + after) };
+  }
+
+  // Tag not yet seen — flush everything except the last tailLen chars,
+  // which might be the start of the target tag split across chunks.
+  const safeEnd = Math.max(0, text.length - state.tailLen);
+  const safe = safeEnd > 0 ? text.slice(0, safeEnd) : '';
+  state.tail = text.slice(safeEnd);
+  return { kind: 'emit', bytes: safe ? encoder.encode(safe) : null };
+}
+
+/**
+ * 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 function injectorFlush(state: InjectorState): Uint8Array | null {
+  if (!state.injected && state.tail) return encoder.encode(state.tail);
+  return null;
+}
+
+// ─── Flight Injection Core ───────────────────────────────────────────────────
+
+/**
+ * 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 class FlightInjectorCore {
+  readonly machine: Machine<FlightInjectionState, FlightInjectionEvent>;
+  /** Script chunks waiting to be drained between HTML chunks. */
+  readonly pending: Uint8Array[] = [];
+
+  private readonly rscReader: ReadableStreamDefaultReader<Uint8Array>;
+  private readonly timeoutMs: number;
+  private readonly decoder = new TextDecoder('utf-8', { fatal: true });
+  private pullPromise: Promise<void> | null = null;
+
+  constructor(rscStream: ReadableStream<Uint8Array>, renderTimeoutMs?: number) {
+    this.rscReader = rscStream.getReader();
+    this.timeoutMs = renderTimeoutMs ?? 30_000;
+    this.machine = createMachine<FlightInjectionState, FlightInjectionEvent>({
+      initial: { phase: 'init' },
+      transitions: flightInjectionTransitions,
+    });
+  }
+
+  /** Tell the machine the first HTML chunk has arrived. Idempotent-ish: caller checks. */
+  notifyFirstChunk(): void {
+    this.machine.send({ type: 'FIRST_CHUNK' });
+  }
+
+  /** Tell the machine HTML output is finished — pull loop will stop yielding. */
+  notifyHtmlDone(): void {
+    this.machine.send({ type: 'HTML_DONE' });
+  }
+
+  get isInit(): boolean {
+    return this.machine.state.phase === 'init';
+  }
+
+  get isPullDone(): boolean {
+    return isPullDone(this.machine.state);
+  }
+
+  get hasPullPromise(): boolean {
+    return this.pullPromise !== null;
+  }
+
+  /**
+   * 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> {
+    if (!this.pullPromise) {
+      this.pullPromise = this.runPullLoop(onYieldDrain);
+    }
+    return this.pullPromise;
+  }
+
+  /**
+   * 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 {
+    return this.machine.state.phase === 'error' ? this.machine.state.error : null;
+  }
+
+  private async runPullLoop(onYieldDrain: () => void): Promise<void> {
+    // Yield once so the first HTML shell chunk flows through the wrapper
+    // before we start reading RSC data.
+    await new Promise<void>((r) => setImmediate(r));
+
+    try {
+      for (;;) {
+        // Guard each read with a timeout so a permanently hung RSC stream
+        // eventually aborts. See design/02 §"Streaming Constraints".
+        const readPromise = this.rscReader.read();
+        const { done, value } =
+          this.timeoutMs > 0
+            ? await withTimeout(readPromise, this.timeoutMs, 'RSC stream read timed out')
+            : await readPromise;
+
+        if (done) {
+          this.machine.send({ type: 'PULL_DONE' });
+          return;
+        }
+
+        const decoded = this.decoder.decode(value, { stream: true });
+        this.pending.push(encoder.encode(flightChunkScript(decoded)));
+
+        // Yield between reads so HTML chunks get priority — but only while
+        // HTML is still streaming. Once flush() fires (HTML_DONE), drain
+        // without yielding so remaining RSC data doesn't stall.
+        if (!isHtmlDone(this.machine.state)) {
+          await new Promise<void>((r) => setImmediate(r));
+          // After yielding, drain. Without this, hydration blocks waiting
+          // for flight data stuck in pending[]. Safe because we're between
+          // event-loop ticks (no transform() call mid-execution → no
+          // mid-tag risk; the buffered transform upstream coalesced HTML
+          // chunks to coherent fragments).
+          if (this.pending.length > 0) onYieldDrain();
+        }
+      }
+    } catch (err) {
+      if (err instanceof RenderTimeoutError) {
+        this.rscReader.cancel(err).catch(() => {});
+      }
+      this.machine.send({ type: 'PULL_ERROR', error: err });
+    }
+  }
+}