@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.131

package/src/server/html-injectors.ts

@@ -1,20 +1,137 @@
 /**
- * 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';
+import { createTickCoalescer } from './coalesce-tick.js';
+
+// ─── Buffered Transform ──────────────────────────────────────────────────────
+
+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. 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.
+ *
+ * See design/02 §"No Polling" and §"Scripts at Chunk Boundaries Only".
+ */
+export function createBufferedTransformStream(
+  options: BufferedTransformOptions = {}
+): TransformStream<Uint8Array, Uint8Array> {
+  const buffer = new BufferAggregator(options.maxBufferByteLength ?? Infinity);
+  let controller: TransformStreamDefaultController<Uint8Array> | null = null;
+
+  const drainTo = () => {
+    const merged = buffer.drain();
+    if (!merged || !controller) return;
+    try {
+      controller.enqueue(merged);
+    } catch {
+      // Controller may be errored (e.g. cancelled) — ignore.
+    }
+  };
+
+  const coalescer = createTickCoalescer(drainTo);
+
+  return new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, ctrl) {
+      controller = ctrl;
+      const overCap = buffer.append(chunk);
+      if (overCap) {
+        drainTo();
+        return;
+      }
+      coalescer.schedule();
+    },
+    flush() {
+      return coalescer.pending;
+    },
+  });
+}
+
+// ─── Move Suffix Transform ───────────────────────────────────────────────────
+
+/**
+ * Move `</body></html>` to the end of the stream.
+ *
+ * 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 state = createSuffixState();
+
+  return new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      const result = processSuffixChunk(state, chunk);
+      if (result.kind === 'passthrough' || result.kind === 'noSuffix') {
+        controller.enqueue(chunk);
+        return;
+      }
+      if (result.before) controller.enqueue(result.before);
+      if (result.after) controller.enqueue(result.after);
+    },
+    flush(controller) {
+      controller.enqueue(suffixFlush(state));
+    },
+  });
+}
+
+// ─── 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>,
@@ -23,57 +140,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>,
@@ -83,10 +172,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>,
@@ -95,65 +183,46 @@ 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');
-}
+// ─── 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:
- *   <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)
+ * 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>
+  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));
-    },
     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(encodeUtf8(flightChunkScript(decoded)));
         }
       } catch (error) {
+        if (error instanceof RenderTimeoutError) {
+          rscReader.cancel(error).catch(() => {});
+        }
         controller.error(error);
       }
     },
@@ -161,136 +230,71 @@ export function createInlinedRscStream(
 }
 
 /**
- * Merge RSC script stream into the HTML stream, injecting scripts
- * only as direct children of `<body>`.
+ * 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.
  *
- * This single transform replaces the previous two-stage pipeline
- * (createFlightInjectionTransform + createMoveSuffixStream). It:
+ * 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.
  *
- * 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.
+ * **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.
  *
- * 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.
+ * Inspired by Next.js `createFlightDataInjectionTransformStream`. See
+ * design/02 §"Scripts at Chunk Boundaries Only".
  */
 function createFlightInjectionTransform(
-  rscScriptStream: ReadableStream<Uint8Array>
+  rscStream: ReadableStream<Uint8Array>,
+  renderTimeoutMs?: number,
+  errorSignal?: AbortSignal
 ): TransformStream<Uint8Array, Uint8Array> {
-  const encoder = new TextEncoder();
-  const decoder = new TextDecoder();
-  const suffix = '</body></html>';
-  const suffixBytes = encoder.encode(suffix);
-
-  const rscReader = rscScriptStream.getReader();
-  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.
-  const pending: Uint8Array[] = [];
-
-  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));
+  const core = new FlightInjectorCore(rscStream, renderTimeoutMs, errorSignal);
+  // 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;
 
-    try {
-      for (;;) {
-        const { done, value } = await rscReader.read();
-        if (done) {
-          donePulling = true;
-          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));
-      }
-    } catch (err) {
-      pullError = err;
-      donePulling = true;
-    }
-  }
+  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 (pullError) {
-      const err = pullError;
-      pullError = null;
-      controller.error(err);
-    }
-  }
+  const onYieldDrain = (): void => {
+    if (_controller) drain(_controller);
+  };
 
   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 (core.isInit) {
+        core.notifyFirstChunk();
+        core.ensurePullLoop(onYieldDrain);
       }
 
-      // 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 (core.pending.length > 0) drain(controller);
     },
     flush(controller) {
-      // HTML stream is done — drain remaining RSC chunks at body level
-      const finish = () => {
-        drainPending(controller);
-        // Re-emit the suffix at the very end so HTML is well-formed
-        if (foundSuffix) {
-          controller.enqueue(suffixBytes);
-        }
-      };
+      // All HTML chunks emitted. Pull loop stops yielding.
+      core.notifyHtmlDone();
 
-      if (donePulling) {
+      const finish = () => drain(controller);
+
+      if (core.isPullDone) {
         finish();
         return;
       }
-      if (!pullPromise) {
-        pullPromise = pullLoop();
-      }
-      return pullPromise.then(finish);
+      return core.ensurePullLoop(onYieldDrain).then(finish);
     },
   });
 }
@@ -298,34 +302,42 @@ 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
  *
- * The RSC stream is transformed into <script> tags via createInlinedRscStream
- * (pull-based, no shared mutable state) and merged into the HTML pipeline
- * via createFlightInjectionTransform.
+ * 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.
+ *
+ * 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>,
-  rscStream: ReadableStream<Uint8Array> | undefined
+  rscStream: ReadableStream<Uint8Array> | undefined,
+  renderTimeoutMs?: number,
+  errorSignal?: AbortSignal
 ): 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));
+  // 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(rscStream, renderTimeoutMs, errorSignal))
+    .pipeThrough(createMoveSuffixStream());
 }
 
+// ─── Client Bootstrap Script Resolution ──────────────────────────────────────
+
 /**
  * Client bootstrap configuration returned by buildClientScripts.
  *
@@ -344,7 +356,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;
@@ -366,19 +378,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;
@@ -425,7 +437,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 +447,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}">`;