@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.81

package/src/server/html-injectors.ts

@@ -7,6 +7,179 @@
  * Design docs: 02-rendering-pipeline.md, 18-build-system.md §"Entry Files"
  */
 
+// ─── Buffered Transform ──────────────────────────────────────────────────────
+
+/**
+ * Options for the buffered transform stream.
+ */
+export interface BufferedTransformOptions {
+  /**
+   * Flush synchronously once the buffer reaches this many bytes.
+   * Prevents unbounded memory growth for very large Fizz flushes.
+   * Default: Infinity (no byte limit — flush only on tick boundary).
+   */
+  readonly maxBufferByteLength?: number;
+}
+
+/**
+ * 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.
+ *
+ * **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`.
+ */
+export function createBufferedTransformStream(
+  options: BufferedTransformOptions = {}
+): TransformStream<Uint8Array, Uint8Array> {
+  const { maxBufferByteLength = Infinity } = options;
+
+  let bufferedChunks: Uint8Array[] = [];
+  let bufferByteLength = 0;
+  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;
+
+    try {
+      controller.enqueue(merged);
+    } catch {
+      // Controller may be errored (e.g., stream 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);
+      }
+    },
+    flush() {
+      // Wait for any pending scheduled flush to complete
+      return pendingFlush;
+    },
+  });
+}
+
+// ─── 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.
+ *
+ * Equivalent to Next.js's `createMoveSuffixStream`.
+ */
+export function createMoveSuffixStream(): TransformStream<Uint8Array, Uint8Array> {
+  const encoder = new TextEncoder();
+  const suffixBytes = encoder.encode(SUFFIX);
+  let foundSuffix = false;
+
+  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) {
+        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));
+    },
+    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);
+    },
+  });
+}
+
+// ─── 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';
+
 /**
  * Inject HTML content before a closing tag in the stream.
  *
@@ -95,22 +268,6 @@ export function injectScripts(
   return createInjector(stream, scriptsHtml, '</body>');
 }
 
-/**
- * Escape a string for safe embedding inside a `<script>` tag within
- * a JSON-encoded value.
- *
- * Only needs to prevent `</script>` from closing the tag early and
- * handle U+2028/U+2029 (line/paragraph separators valid in JSON but
- * historically problematic in JS). Since we use JSON.stringify for the
- * outer encoding, we only escape `<` and the line separators.
- */
-function htmlEscapeJsonString(str: string): string {
-  return str
-    .replace(/</g, '\\u003c')
-    .replace(/\u2028/g, '\\u2028')
-    .replace(/\u2029/g, '\\u2029');
-}
-
 /**
  * Transform an RSC Flight stream into a stream of inline `<script>` tags.
  *
@@ -118,42 +275,42 @@ function htmlEscapeJsonString(str: string): string {
  * transform) drives reads from the RSC stream on demand. No background
  * reader, no shared mutable arrays, no race conditions.
  *
- * Each RSC chunk becomes:
- *   <script>(self.__timber_f=self.__timber_f||[]).push([1,"escaped_chunk"])</script>
- *
- * The first chunk emitted is the bootstrap signal [0] which the client
- * uses to initialize its buffer.
- *
- * Uses JSON-encoded typed tuples matching the pattern from Next.js:
- *   [0]        — bootstrap signal
- *   [1, data]  — RSC Flight data chunk (UTF-8 string)
+ * 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.
  */
 export function createInlinedRscStream(
-  rscStream: ReadableStream<Uint8Array>
+  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>({
-    start(controller) {
-      // Emit bootstrap signal — tells the client that __timber_f is active
-      const bootstrap = `<script>(self.__timber_f=self.__timber_f||[]).push(${htmlEscapeJsonString(JSON.stringify([0]))})</script>`;
-      controller.enqueue(encoder.encode(bootstrap));
-    },
+    // 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 { done, value } = await rscReader.read();
+        const readPromise = rscReader.read();
+        const { done, value } =
+          timeoutMs > 0
+            ? await withTimeout(readPromise, timeoutMs, 'RSC stream read timed out')
+            : await readPromise;
         if (done) {
           controller.close();
           return;
         }
         if (value) {
           const decoded = decoder.decode(value, { stream: true });
-          const escaped = htmlEscapeJsonString(JSON.stringify([1, decoded]));
-          controller.enqueue(encoder.encode(`<script>self.__timber_f.push(${escaped})</script>`));
+          controller.enqueue(encoder.encode(flightChunkScript(decoded)));
         }
       } catch (error) {
+        if (error instanceof RenderTimeoutError) {
+          rscReader.cancel(error).catch(() => {});
+        }
         controller.error(error);
       }
     },
@@ -162,67 +319,84 @@ export function createInlinedRscStream(
 
 /**
  * Merge RSC script stream into the HTML stream, injecting scripts
- * only as direct children of `<body>`.
+ * between HTML chunks at safe boundaries.
  *
- * This single transform replaces the previous two-stage pipeline
- * (createFlightInjectionTransform + createMoveSuffixStream). It:
+ * Suffix stripping (</body></html>) is handled upstream by
+ * createMoveSuffixStream. This transform only interleaves RSC
+ * scripts — no suffix tracking needed.
  *
- * 1. Strips `</body></html>` from the shell chunk so all subsequent
- *    content is at the `<body>` level.
- * 2. Buffers RSC `<script>` tags and drains them after the suffix
- *    has been stripped — guaranteeing body-level injection.
- * 3. Re-emits `</body></html>` at the very end after all RSC scripts.
+ * 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).
  *
- * Because the suffix is stripped before any scripts are injected,
- * scripts are always direct children of `<body>` regardless of how
- * React's renderToReadableStream chunks the HTML. No HTML structure
- * scanning or depth tracking needed — the suffix removal is the
- * structural guarantee.
+ * State machine phases:
+ *   init → streaming → flushing → done
+ *   (any) → error
  *
  * Inspired by Next.js createFlightDataInjectionTransformStream.
  */
 function createFlightInjectionTransform(
-  rscScriptStream: ReadableStream<Uint8Array>
+  rscScriptStream: ReadableStream<Uint8Array>,
+  renderTimeoutMs?: number
 ): TransformStream<Uint8Array, Uint8Array> {
-  const encoder = new TextEncoder();
-  const decoder = new TextDecoder();
-  const suffix = '</body></html>';
-  const suffixBytes = encoder.encode(suffix);
-
   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;
-  let donePulling = false;
-  let pullError: unknown = null;
-  // Once the suffix is stripped, all content is body-level and
-  // scripts can safely be drained after any HTML chunk.
-  let foundSuffix = false;
 
-  // RSC script chunks waiting to be injected at the body level.
+  // 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).
+  let _controller: TransformStreamDefaultController<Uint8Array> | null = null;
+
   async function pullLoop(): Promise<void> {
-    // Wait one macrotask so the HTML shell chunk flows through
-    // transform() first. The browser needs the shell HTML before
-    // RSC data script tags arrive.
-    await new Promise<void>((r) => setTimeout(r, 0));
+    // 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 (;;) {
-        const { done, value } = await rscReader.read();
+        // 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) {
-          donePulling = true;
+          machine.send({ type: 'PULL_DONE' });
           return;
         }
         pending.push(value);
-        // Yield between reads so HTML chunks get a chance to flow
-        // through transform() first. RSC and HTML are driven by the
-        // same source — each RSC chunk typically produces a
-        // corresponding HTML chunk from SSR.
-        await new Promise<void>((r) => setTimeout(r, 0));
+        // 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) {
-      pullError = err;
-      donePulling = true;
+      if (err instanceof RenderTimeoutError) {
+        rscReader.cancel(err).catch(() => {});
+      }
+      machine.send({ type: 'PULL_ERROR', error: err });
     }
   }
 
@@ -231,59 +405,36 @@ function createFlightInjectionTransform(
     while (pending.length > 0) {
       controller.enqueue(pending.shift()!);
     }
-    if (pullError) {
-      const err = pullError;
-      pullError = null;
-      controller.error(err);
+    if (machine.state.phase === 'error') {
+      controller.error(machine.state.error);
     }
   }
 
   return new TransformStream<Uint8Array, Uint8Array>({
     transform(chunk, controller) {
-      // Start pulling RSC scripts into the buffer (if not started)
-      if (!pullPromise) {
-        pullPromise = pullLoop();
-      }
+      _controller = controller;
 
-      if (foundSuffix) {
-        // Post-suffix: everything is body-level (Suspense chunks).
-        // Emit HTML, then drain any buffered scripts.
-        controller.enqueue(chunk);
-        if (pending.length > 0) drainPending(controller);
-        return;
+      if (machine.state.phase === 'init') {
+        machine.send({ type: 'FIRST_CHUNK' });
+        pullPromise = pullLoop();
       }
 
-      // Look for </body></html> in the shell chunk.
-      const text = decoder.decode(chunk, { stream: true });
-      const idx = text.indexOf(suffix);
-      if (idx !== -1) {
-        foundSuffix = true;
-        // Emit everything before the suffix (still inside <body>'s
-        // child elements — don't inject scripts here).
-        const before = text.slice(0, idx);
-        const after = text.slice(idx + suffix.length);
-        if (before) controller.enqueue(encoder.encode(before));
-        // Now we're at body level — drain buffered scripts
-        if (pending.length > 0) drainPending(controller);
-        // Emit any content after the suffix (shouldn't normally exist)
-        if (after) controller.enqueue(encoder.encode(after));
-      } else {
-        // Pre-suffix: inside nested elements. Pass through, don't
-        // inject scripts (they'd become children of nested elements).
-        controller.enqueue(chunk);
-      }
+      // Emit the HTML chunk, then drain any buffered RSC scripts.
+      // Scripts always come AFTER a complete HTML chunk — never mid-tag.
+      // 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);
     },
     flush(controller) {
-      // HTML stream is done — drain remaining RSC chunks at body level
+      // All HTML chunks emitted. Pull loop stops yielding.
+      machine.send({ type: 'HTML_DONE' });
+
       const finish = () => {
         drainPending(controller);
-        // Re-emit the suffix at the very end so HTML is well-formed
-        if (foundSuffix) {
-          controller.enqueue(suffixBytes);
-        }
       };
 
-      if (donePulling) {
+      if (isPullDone(machine.state)) {
         finish();
         return;
       }
@@ -314,16 +465,25 @@ function createFlightInjectionTransform(
  */
 export function injectRscPayload(
   htmlStream: ReadableStream<Uint8Array>,
-  rscStream: ReadableStream<Uint8Array> | undefined
+  rscStream: ReadableStream<Uint8Array> | undefined,
+  renderTimeoutMs?: number
 ): ReadableStream<Uint8Array> {
   if (!rscStream) return htmlStream;
 
   // Transform RSC binary stream → stream of <script> tags
-  const rscScriptStream = createInlinedRscStream(rscStream);
-
-  // Single transform: strip </body></html>, inject RSC scripts at
-  // body level, re-emit suffix at the very end.
-  return htmlStream.pipeThrough(createFlightInjectionTransform(rscScriptStream));
+  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.
+  return htmlStream
+    .pipeThrough(createFlightInjectionTransform(rscScriptStream, renderTimeoutMs))
+    .pipeThrough(createMoveSuffixStream());
 }
 
 /**
@@ -344,7 +504,7 @@ export interface ClientBootstrapConfig {
   preloadLinks: string;
 }
 
-/** Find a manifest entry by matching the key suffix (e.g. 'client/browser-entry.ts'). */
+/** Find a manifest entry by matching the key suffix (e.g. 'client/browser-entry/index.ts'). */
 function findManifestEntry(map: Record<string, string>, suffix: string): string | undefined {
   for (const [key, value] of Object.entries(map)) {
     if (key.endsWith(suffix)) return value;
@@ -425,7 +585,7 @@ export function buildClientScripts(runtimeConfig: {
   // a monorepo). Match by suffix to handle both cases.
   const manifest = runtimeConfig.buildManifest;
   const browserEntryUrl = manifest
-    ? findManifestEntry(manifest.js, 'client/browser-entry.ts')
+    ? findManifestEntry(manifest.js, 'client/browser-entry/index.ts')
     : undefined;
 
   let preloadLinks = '';
@@ -435,7 +595,7 @@ export function buildClientScripts(runtimeConfig: {
     // Modulepreload hints for browser entry dependencies
     const preloads =
       (manifest
-        ? findManifestEntryArray(manifest.modulepreload, 'client/browser-entry.ts')
+        ? findManifestEntryArray(manifest.modulepreload, 'client/browser-entry/index.ts')
         : undefined) ?? [];
     for (const url of preloads) {
       preloadLinks += `<link rel="modulepreload" href="${url}">`;