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

package/src/server/html-injectors.ts

@@ -1,17 +1,39 @@
 /**
- * HTML stream injectors — TransformStreams that modify streamed HTML.
+ * HTML stream injectors — Web `TransformStream` wrappers around the
+ * pure helpers in `html-injector-core.ts`.
  *
- * These are extracted into a separate module so they can be tested
- * independently of rsc-entry.ts (which imports virtual modules).
+ * Used on edge runtimes (Cloudflare Workers, Deno, browser SSR) where
+ * Web Streams are the native shape. The Node.js / Bun adapters live in
+ * `node-stream-transforms.ts` and wrap the same core in Node `Transform`s.
+ * Both wrappers must stay byte-for-byte equivalent — the core enforces
+ * that. If you fix a streaming bug here, you almost certainly need to
+ * fix it (or its cause) in the core, not in the Node wrapper.
+ *
+ * Also exports the `buildClientScripts` helper used by RSC entry to
+ * resolve bootstrap script URLs from the build manifest. That helper
+ * is unrelated to streaming but lives here for historical reasons (it
+ * shares no code with the core and was previously co-located with the
+ * Web stream transforms).
  *
  * Design docs: 02-rendering-pipeline.md, 18-build-system.md §"Entry Files"
  */
 
+import {
+  BufferAggregator,
+  FlightInjectorCore,
+  createInjectorState,
+  createSuffixState,
+  encodeUtf8,
+  injectorFlush,
+  processInjectorChunk,
+  processSuffixChunk,
+  suffixFlush,
+} from './html-injector-core.js';
+import { flightChunkScript } from './flight-scripts.js';
+import { withTimeout, RenderTimeoutError } from './render-timeout.js';
+
 // ─── Buffered Transform ──────────────────────────────────────────────────────
 
-/**
- * Options for the buffered transform stream.
- */
 export interface BufferedTransformOptions {
   /**
    * Flush synchronously once the buffer reaches this many bytes.
@@ -24,85 +46,55 @@ export interface BufferedTransformOptions {
 /**
  * Buffer incoming chunks and coalesce them within a single event loop tick.
  *
- * React Fizz may emit multiple micro-chunks within a single flush (e.g.,
- * opening tags, attributes, closing tags as separate writes). Without
- * buffering, downstream transforms (especially flight injection) could
- * see chunk boundaries in the middle of HTML tags or attribute values.
- *
- * This transform collects all chunks that arrive in the same tick and
- * emits them as a single concatenated chunk on the next `setImmediate`.
- * This ensures each output chunk represents a coherent HTML fragment
- * from a single Fizz flush — safe for downstream script injection at
- * chunk boundaries.
+ * React Fizz may emit multiple micro-chunks within a single flush. Without
+ * coalescing, downstream transforms (especially flight injection) could
+ * see chunk boundaries in the middle of HTML tags. This transform collects
+ * everything that arrives in the same tick and emits it as one concatenated
+ * chunk on the next `setImmediate` — a single-shot schedule, not a poll.
  *
- * **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`.
+ * See design/02 §"No Polling" and §"Scripts at Chunk Boundaries Only".
  */
 export function createBufferedTransformStream(
   options: BufferedTransformOptions = {}
 ): TransformStream<Uint8Array, Uint8Array> {
-  const { maxBufferByteLength = Infinity } = options;
-
-  let bufferedChunks: Uint8Array[] = [];
-  let bufferByteLength = 0;
+  const buffer = new BufferAggregator(options.maxBufferByteLength ?? Infinity);
   let pendingFlush: Promise<void> | undefined;
 
-  const flush = (controller: TransformStreamDefaultController<Uint8Array>) => {
-    if (bufferedChunks.length === 0) return;
-
-    // Concatenate all buffered chunks into a single output chunk
-    const merged = new Uint8Array(bufferByteLength);
-    let offset = 0;
-    for (const chunk of bufferedChunks) {
-      merged.set(chunk, offset);
-      offset += chunk.byteLength;
-    }
-
-    bufferedChunks = [];
-    bufferByteLength = 0;
-
+  const drainTo = (controller: TransformStreamDefaultController<Uint8Array>) => {
+    const merged = buffer.drain();
+    if (!merged) return;
     try {
       controller.enqueue(merged);
     } catch {
-      // Controller may be errored (e.g., stream cancelled) — ignore
+      // Controller may be errored (e.g. cancelled) — ignore.
     }
   };
 
-  const scheduleFlush = (controller: TransformStreamDefaultController<Uint8Array>) => {
-    if (pendingFlush) return;
-
-    // Single-shot setImmediate — fires once at the end of the current
-    // event loop iteration (check phase), then the promise resolves.
-    // NOT a recursive loop — no CPU spin risk.
-    pendingFlush = new Promise<void>((resolve) => {
-      setImmediate(() => {
-        try {
-          flush(controller);
-        } finally {
-          pendingFlush = undefined;
-          resolve();
-        }
-      });
-    });
-  };
-
   return new TransformStream<Uint8Array, Uint8Array>({
     transform(chunk, controller) {
-      bufferedChunks.push(chunk);
-      bufferByteLength += chunk.byteLength;
-
-      if (bufferByteLength >= maxBufferByteLength) {
-        // Synchronous flush — buffer is too large to hold
-        flush(controller);
-      } else {
-        // Schedule a deferred flush for end of this tick
-        scheduleFlush(controller);
+      const overCap = buffer.append(chunk);
+      if (overCap) {
+        // Buffer too large to hold — flush synchronously now.
+        drainTo(controller);
+        return;
       }
+      if (pendingFlush) return;
+      // Single-shot setImmediate — fires once at the end of this tick,
+      // then the promise resolves. NOT a recursive loop. See design/02
+      // §"No Polling".
+      pendingFlush = new Promise<void>((resolve) => {
+        setImmediate(() => {
+          try {
+            drainTo(controller);
+          } finally {
+            pendingFlush = undefined;
+            resolve();
+          }
+        });
+      });
     },
     flush() {
-      // Wait for any pending scheduled flush to complete
+      // Wait for any pending scheduled flush to complete.
       return pendingFlush;
     },
   });
@@ -110,84 +102,47 @@ export function createBufferedTransformStream(
 
 // ─── Move Suffix Transform ───────────────────────────────────────────────────
 
-const SUFFIX = '</body></html>';
-
 /**
  * Move `</body></html>` to the end of the stream.
  *
- * React's renderToReadableStream emits `</body></html>` as part of the
- * shell chunk. Content that arrives after the shell (Suspense resolutions,
- * RSC script tags) would appear after the closing tags, producing invalid
- * HTML like `</body></html><script>...</script>`.
- *
- * This transform strips the suffix when first encountered and re-emits
- * it in `flush()` — after all content has passed through. If no suffix
- * is found, it's appended anyway to ensure well-formed HTML.
+ * React's renderToReadableStream emits the closing tags as part of the
+ * shell chunk. Content arriving after the shell (Suspense resolutions,
+ * RSC scripts) would otherwise appear after `</html>` and produce invalid
+ * HTML. This transform strips the suffix on first sight and re-emits it
+ * from `flush()` — after every other byte has passed through. If the
+ * suffix never appeared in the input, it is appended anyway so output
+ * is well-formed.
  *
  * Equivalent to Next.js's `createMoveSuffixStream`.
  */
 export function createMoveSuffixStream(): TransformStream<Uint8Array, Uint8Array> {
-  const encoder = new TextEncoder();
-  const suffixBytes = encoder.encode(SUFFIX);
-  let foundSuffix = false;
+  const state = createSuffixState();
 
   return new TransformStream<Uint8Array, Uint8Array>({
     transform(chunk, controller) {
-      if (foundSuffix) {
-        controller.enqueue(chunk);
-        return;
-      }
-
-      // Search for the suffix in this chunk
-      const text = new TextDecoder().decode(chunk, { stream: true });
-      const idx = text.indexOf(SUFFIX);
-      if (idx === -1) {
+      const result = processSuffixChunk(state, chunk);
+      if (result.kind === 'passthrough' || result.kind === 'noSuffix') {
         controller.enqueue(chunk);
         return;
       }
-
-      foundSuffix = true;
-
-      // If the entire chunk is exactly the suffix, skip it
-      if (chunk.byteLength === suffixBytes.byteLength) return;
-
-      // Emit content before the suffix
-      const before = text.slice(0, idx);
-      const after = text.slice(idx + SUFFIX.length);
-      if (before) controller.enqueue(encoder.encode(before));
-      // Emit content after the suffix (shouldn't normally exist,
-      // but handle it for robustness)
-      if (after) controller.enqueue(encoder.encode(after));
+      if (result.before) controller.enqueue(result.before);
+      if (result.after) controller.enqueue(result.after);
     },
     flush(controller) {
-      // Always emit the suffix at the very end — even if we didn't
-      // find it in the input (ensures well-formed HTML).
-      controller.enqueue(suffixBytes);
+      controller.enqueue(suffixFlush(state));
     },
   });
 }
 
-// ─── Injection Transforms ────────────────────────────────────────────────────
-
-import { createMachine } 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';
+// ─── Tag Injection ───────────────────────────────────────────────────────────
 
 /**
- * Inject HTML content before a closing tag in the stream.
+ * Inject `content` immediately before (or after) `targetTag` in the stream.
  *
- * Streams chunks through immediately, keeping only a small trailing
- * buffer (the length of the target tag minus one) to handle the case
- * where the target tag spans two chunks. This preserves React's
- * streaming behavior for Suspense boundaries — chunks are not held
- * back waiting for the closing tag.
+ * Streams chunks through immediately, keeping only a small trailing buffer
+ * (length of target tag minus one) so a tag split across chunks is still
+ * detected. Suspense streaming chunks are never held back waiting for the
+ * closing tag.
  */
 function createInjector(
   stream: ReadableStream<Uint8Array>,
@@ -196,57 +151,29 @@ function createInjector(
   position: 'before' | 'after' = 'before'
 ): ReadableStream<Uint8Array> {
   if (!content) return stream;
-
-  const decoder = new TextDecoder();
-  const encoder = new TextEncoder();
-  let injected = false;
-  // Keep a trailing buffer just large enough that the target tag
-  // can't be split across the boundary without us seeing it.
-  let tail = '';
-  const tailLen = targetTag.length - 1;
+  const state = createInjectorState({ content, targetTag, position });
 
   return stream.pipeThrough(
     new TransformStream<Uint8Array, Uint8Array>({
       transform(chunk, controller) {
-        if (injected) {
+        const result = processInjectorChunk(state, chunk);
+        if (result.kind === 'passthrough') {
           controller.enqueue(chunk);
           return;
         }
-
-        // Combine the trailing buffer with the new chunk
-        const text = tail + decoder.decode(chunk, { stream: true });
-        const tagIndex = text.indexOf(targetTag);
-
-        if (tagIndex !== -1) {
-          const splitPoint = position === 'before' ? tagIndex : tagIndex + targetTag.length;
-          const before = text.slice(0, splitPoint);
-          const after = text.slice(splitPoint);
-          controller.enqueue(encoder.encode(before + content + after));
-          injected = true;
-          tail = '';
-        } else {
-          // 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 - tailLen);
-          if (safeEnd > 0) {
-            controller.enqueue(encoder.encode(text.slice(0, safeEnd)));
-          }
-          tail = text.slice(safeEnd);
-        }
+        if (result.bytes) controller.enqueue(result.bytes);
       },
       flush(controller) {
-        if (!injected && tail) {
-          controller.enqueue(encoder.encode(tail));
-        }
+        const leftover = injectorFlush(state);
+        if (leftover) controller.enqueue(leftover);
       },
     })
   );
 }
 
 /**
- * Inject metadata elements before </head> in the HTML stream.
- *
- * If no </head> is found, the buffer is emitted as-is.
+ * Inject metadata elements before `</head>` in the HTML stream.
+ * If no `</head>` is found, the buffer is emitted as-is.
  */
 export function injectHead(
   stream: ReadableStream<Uint8Array>,
@@ -256,10 +183,9 @@ export function injectHead(
 }
 
 /**
- * Inject client bootstrap scripts before </body> in the HTML stream.
- *
- * Returns the stream unchanged if scriptsHtml is empty (client JS disabled mode).
- * If no </body> is found, the buffer is emitted as-is.
+ * Inject client bootstrap scripts before `</body>` in the HTML stream.
+ * Returns the stream unchanged if `scriptsHtml` is empty (client JS
+ * disabled mode). If no `</body>` is found, the buffer is emitted as-is.
  */
 export function injectScripts(
   stream: ReadableStream<Uint8Array>,
@@ -268,30 +194,27 @@ export function injectScripts(
   return createInjector(stream, scriptsHtml, '</body>');
 }
 
+// ─── RSC Flight Injection ────────────────────────────────────────────────────
+
 /**
  * Transform an RSC Flight stream into a stream of inline `<script>` tags.
  *
  * Uses a **pull-based** ReadableStream — the consumer (the injection
  * transform) drives reads from the RSC stream on demand. No background
- * reader, no shared mutable arrays, no race conditions.
- *
- * Each RSC chunk becomes a `<script>self.__timber_f.push([1,"data"])</script>`.
- * The init script (which creates __timber_f) is in `<head>` via
- * flightInitScript() — see flight-scripts.ts.
+ * reader, no shared mutable arrays, no race conditions. Each RSC chunk
+ * becomes `<script>self.__timber_f.push([1,"data"])</script>`. The
+ * init script (which creates `__timber_f`) is in `<head>` via
+ * `flightInitScript()` — see flight-scripts.ts.
  */
 export function createInlinedRscStream(
   rscStream: ReadableStream<Uint8Array>,
   renderTimeoutMs?: number
 ): ReadableStream<Uint8Array> {
-  const encoder = new TextEncoder();
   const rscReader = rscStream.getReader();
   const decoder = new TextDecoder('utf-8', { fatal: true });
   const timeoutMs = renderTimeoutMs ?? 30_000;
 
   return new ReadableStream<Uint8Array>({
-    // No bootstrap signal here — the init script is in <head> via
-    // flightInitScript() (see flight-scripts.ts). This ensures the
-    // __timber_f array exists before any chunk scripts execute.
     async pull(controller) {
       try {
         const readPromise = rscReader.read();
@@ -305,7 +228,7 @@ export function createInlinedRscStream(
         }
         if (value) {
           const decoded = decoder.decode(value, { stream: true });
-          controller.enqueue(encoder.encode(flightChunkScript(decoded)));
+          controller.enqueue(encodeUtf8(flightChunkScript(decoded)));
         }
       } catch (error) {
         if (error instanceof RenderTimeoutError) {
@@ -318,105 +241,50 @@ export function createInlinedRscStream(
 }
 
 /**
- * Merge RSC script stream into the HTML stream, injecting scripts
- * between HTML chunks at safe boundaries.
+ * Merge a raw RSC byte stream into the HTML stream, wrapping each RSC
+ * chunk in a `<script>` and injecting it between HTML chunks at safe
+ * boundaries. Suffix stripping is handled upstream by
+ * `createMoveSuffixStream` — this transform only interleaves.
  *
- * Suffix stripping (</body></html>) is handled upstream by
- * createMoveSuffixStream. This transform only interleaves RSC
- * scripts — no suffix tracking needed.
+ * The state machine, pending queue, script wrapping (`flightChunkScript`),
+ * and pull loop all live in `FlightInjectorCore`. This wrapper only
+ * shuffles bytes between the core and the Web `TransformStream` controller.
  *
- * RSC scripts are buffered in pending[] by pullLoop and only
- * drained from transform() (after a complete HTML chunk) or
- * flush(). Never pushed directly from pullLoop to avoid mid-tag
- * injection (TIM-527).
+ * **Input must be the raw RSC stream, not the pre-scripted output of
+ * `createInlinedRscStream`.** The core wraps each chunk itself; passing
+ * an already-wrapped stream would double-wrap and break hydration.
  *
- * State machine phases:
- *   init → streaming → flushing → done
- *   (any) → error
+ * State machine phases: init → streaming → flushing → done; (any) → error.
  *
- * Inspired by Next.js createFlightDataInjectionTransformStream.
+ * Inspired by Next.js `createFlightDataInjectionTransformStream`. See
+ * design/02 §"Scripts at Chunk Boundaries Only".
  */
 function createFlightInjectionTransform(
-  rscScriptStream: ReadableStream<Uint8Array>,
+  rscStream: ReadableStream<Uint8Array>,
   renderTimeoutMs?: number
 ): TransformStream<Uint8Array, Uint8Array> {
-  const rscReader = rscScriptStream.getReader();
-  const timeoutMs = renderTimeoutMs ?? 30_000;
-
-  const machine = createMachine<FlightInjectionState, FlightInjectionEvent>({
-    initial: { phase: 'init' },
-    transitions: flightInjectionTransitions,
-  });
-
-  let pullPromise: Promise<void> | null = null;
-
-  // RSC script chunks waiting to be drained at a safe boundary.
-  // pullLoop buffers here; transform(), flush(), and pullLoop's
-  // post-yield drain all consume from this buffer.
-  const pending: Uint8Array[] = [];
-
-  // Controller reference — set on first transform() call so pullLoop
-  // can drain pending scripts between HTML chunks (after yielding).
+  const core = new FlightInjectorCore(rscStream, renderTimeoutMs);
+  // Controller reference — set on first transform() call so the pull
+  // loop can drain pending scripts between HTML chunks (after yielding).
   let _controller: TransformStreamDefaultController<Uint8Array> | null = null;
 
-  async function pullLoop(): Promise<void> {
-    // Yield once so the first HTML shell chunk flows through
-    // transform() before we start reading RSC data.
-    await new Promise<void>((r) => setImmediate(r));
-
-    try {
-      for (;;) {
-        // Guard each RSC read with a timeout.
-        // See design/02 §"Streaming Constraints".
-        const readPromise = rscReader.read();
-        const { done, value } =
-          timeoutMs > 0
-            ? await withTimeout(readPromise, timeoutMs, 'RSC stream read timed out')
-            : await readPromise;
-        if (done) {
-          machine.send({ type: 'PULL_DONE' });
-          return;
-        }
-        pending.push(value);
-        // Yield between reads so HTML chunks get priority.
-        // Once flush() fires, drain without yielding.
-        if (!isHtmlDone(machine.state)) {
-          await new Promise<void>((r) => setImmediate(r));
-          // After yielding, drain pending scripts. This ensures RSC
-          // flight data reaches the client at shell-flush time — without
-          // this, hydration blocks waiting for data stuck in pending[].
-          // Safe because the upstream buffered transform (TIM-528)
-          // guarantees chunks end at tag boundaries.
-          if (pending.length > 0 && _controller) {
-            drainPending(_controller);
-          }
-        }
-      }
-    } catch (err) {
-      if (err instanceof RenderTimeoutError) {
-        rscReader.cancel(err).catch(() => {});
-      }
-      machine.send({ type: 'PULL_ERROR', error: err });
-    }
-  }
+  const drain = (controller: TransformStreamDefaultController<Uint8Array>): void => {
+    while (core.pending.length > 0) controller.enqueue(core.pending.shift()!);
+    const err = core.terminalError;
+    if (err !== null) controller.error(err);
+  };
 
-  /** Drain all buffered RSC script chunks to the output. */
-  function drainPending(controller: TransformStreamDefaultController<Uint8Array>): void {
-    while (pending.length > 0) {
-      controller.enqueue(pending.shift()!);
-    }
-    if (machine.state.phase === 'error') {
-      controller.error(machine.state.error);
-    }
-  }
+  const onYieldDrain = (): void => {
+    if (_controller) drain(_controller);
+  };
 
   return new TransformStream<Uint8Array, Uint8Array>({
     transform(chunk, controller) {
       _controller = controller;
 
-      if (machine.state.phase === 'init') {
-        machine.send({ type: 'FIRST_CHUNK' });
-        pullPromise = pullLoop();
+      if (core.isInit) {
+        core.notifyFirstChunk();
+        core.ensurePullLoop(onYieldDrain);
       }
 
       // Emit the HTML chunk, then drain any buffered RSC scripts.
@@ -424,24 +292,19 @@ function createFlightInjectionTransform(
       // The buffered transform upstream (TIM-528) ensures coherent chunks.
       // Suffix stripping is upstream via createMoveSuffixStream (TIM-530).
       controller.enqueue(chunk);
-      if (pending.length > 0) drainPending(controller);
+      if (core.pending.length > 0) drain(controller);
     },
     flush(controller) {
       // All HTML chunks emitted. Pull loop stops yielding.
-      machine.send({ type: 'HTML_DONE' });
+      core.notifyHtmlDone();
 
-      const finish = () => {
-        drainPending(controller);
-      };
+      const finish = () => drain(controller);
 
-      if (isPullDone(machine.state)) {
+      if (core.isPullDone) {
         finish();
         return;
       }
-      if (!pullPromise) {
-        pullPromise = pullLoop();
-      }
-      return pullPromise.then(finish);
+      return core.ensurePullLoop(onYieldDrain).then(finish);
     },
   });
 }
@@ -449,19 +312,23 @@ function createFlightInjectionTransform(
 /**
  * Progressively inline RSC Flight payload chunks into the HTML stream.
  *
- * Architecture (3 TransformStream pipeline):
- * 1. HTML stream → moveSuffix (captures </body></html>, re-emits at end)
- * 2. → flightInjection (merges RSC <script> tags between HTML chunks)
- * 3. → output (well-formed HTML with interleaved RSC data)
+ * Architecture (2 TransformStream pipeline):
+ *   HTML stream → flightInjection → moveSuffix → output
+ *
+ * 1. flightInjection wraps each RSC chunk in a `<script>` and interleaves
+ *    them between HTML chunks.
+ * 2. moveSuffix strips `</body></html>` and re-emits at end so injected
+ *    scripts appear before the closing tags.
  *
- * The RSC stream is transformed into <script> tags via createInlinedRscStream
- * (pull-based, no shared mutable state) and merged into the HTML pipeline
- * via createFlightInjectionTransform.
+ * Wrapping happens inside `FlightInjectorCore` (via `flightChunkScript`).
+ * The raw RSC stream is passed straight to `createFlightInjectionTransform`
+ * — do not pre-wrap with `createInlinedRscStream` (that helper still
+ * exists for callers that want a standalone scripted stream).
  *
  * The client reads these script tags via `self.__timber_f` and feeds
- * them to `createFromReadableStream` for progressive hydration.
- * Stream completion is signaled by the DOMContentLoaded event on the
- * client side — no custom done flag needed.
+ * them to `createFromReadableStream` for progressive hydration. Stream
+ * completion is signaled by the `DOMContentLoaded` event on the client
+ * side — no custom done flag needed.
  */
 export function injectRscPayload(
   htmlStream: ReadableStream<Uint8Array>,
@@ -469,23 +336,17 @@ export function injectRscPayload(
   renderTimeoutMs?: number
 ): ReadableStream<Uint8Array> {
   if (!rscStream) return htmlStream;
-
-  // Transform RSC binary stream → stream of <script> tags
-  const rscScriptStream = createInlinedRscStream(rscStream, renderTimeoutMs);
-
-  // Pipeline: flightInjection → moveSuffix
-  //
-  // 1. flightInjection interleaves RSC scripts between HTML chunks
-  // 2. moveSuffix strips </body></html> and re-emits at end
-  //
-  // The flight injector is upstream and interleaves scripts between
-  // HTML chunks. The moveSuffix transform then ensures </body></html>
-  // appears after all injected scripts, producing well-formed HTML.
+  // Pass the raw RSC stream directly to the flight injection transform.
+  // The transform's core (FlightInjectorCore) wraps each chunk in a
+  // <script> via flightChunkScript itself — do NOT pre-wrap with
+  // createInlinedRscStream here, that would double-wrap.
   return htmlStream
-    .pipeThrough(createFlightInjectionTransform(rscScriptStream, renderTimeoutMs))
+    .pipeThrough(createFlightInjectionTransform(rscStream, renderTimeoutMs))
     .pipeThrough(createMoveSuffixStream());
 }
 
+// ─── Client Bootstrap Script Resolution ──────────────────────────────────────
+
 /**
  * Client bootstrap configuration returned by buildClientScripts.
  *
@@ -526,19 +387,19 @@ function findManifestEntryArray(
 /**
  * Build client bootstrap configuration based on runtime config.
  *
- * Returns empty strings when client JavaScript is disabled,
- * which produces zero-JS output. When `enableHMRInDev` is true and
- * running in dev mode, injects only the Vite HMR client (no app
- * bootstrap) so hot reloading works during development.
+ * Returns empty strings when client JavaScript is disabled, which produces
+ * zero-JS output. When `enableHMRInDev` is true and running in dev mode,
+ * injects only the Vite HMR client (no app bootstrap) so hot reloading
+ * works during development.
  *
  * In production, uses hashed chunk URLs from the build manifest.
  *
  * The bootstrap uses dynamic `import()` inside a regular (non-module)
  * inline script so it executes immediately during HTML parsing. This
- * is critical for streaming: `<script type="module">` is deferred
- * until the document finishes parsing, which blocks hydration behind
- * Suspense boundaries. Dynamic `import()` starts module loading and
- * execution as soon as the shell HTML is parsed.
+ * is critical for streaming: `<script type="module">` is deferred until
+ * the document finishes parsing, which blocks hydration behind Suspense
+ * boundaries. Dynamic `import()` starts module loading and execution as
+ * soon as the shell HTML is parsed.
  */
 export function buildClientScripts(runtimeConfig: {
   output: string;