@timber-js/app 0.2.0-alpha.48 → 0.2.0-alpha.49

package/dist/server/flight-injection-state.d.ts

@@ -7,10 +7,14 @@
  * states and the transition map once.
  *
  * Valid state flow:
- *   init → streaming → body-level → flushing → done
- *                  └──────────────→ flushing → done
+ *   init → streaming → flushing → done
  *   (any) → error
  *
+ * Suffix stripping (</body></html>) is handled by a separate
+ * createMoveSuffixStream / createNodeMoveSuffixTransform upstream
+ * in the pipeline (TIM-530). The flight injector only interleaves
+ * RSC scripts between HTML chunks — no suffix tracking needed.
+ *
  * Design doc: 02-rendering-pipeline.md
  */
 import type { TransitionMap } from '../utils/state-machine.js';
@@ -18,42 +22,28 @@ import type { TransitionMap } from '../utils/state-machine.js';
 export interface InitState {
     phase: 'init';
 }
-/** HTML chunks flowing, pull loop running, suffix not yet stripped. */
+/** HTML chunks flowing, pull loop running. */
 export interface StreamingState {
     phase: 'streaming';
 }
-/**
- * Suffix (</body></html>) stripped. RSC scripts injected at body level.
- * HTML may still be streaming (Suspense chunks after suffix).
- */
-export interface BodyLevelState {
-    phase: 'body-level';
-}
 /** HTML stream done (flush fired). Draining remaining RSC chunks. */
 export interface FlushingState {
     phase: 'flushing';
-    /** When true, suffix was found before flushing. */
-    hadSuffix: boolean;
 }
 /** All streams consumed. Terminal state. */
 export interface DoneState {
     phase: 'done';
-    hadSuffix: boolean;
 }
 /** Pull loop failed. Terminal state with captured error. */
 export interface ErrorState {
     phase: 'error';
     error: unknown;
 }
-export type FlightInjectionState = InitState | StreamingState | BodyLevelState | FlushingState | DoneState | ErrorState;
+export type FlightInjectionState = InitState | StreamingState | FlushingState | DoneState | ErrorState;
 /** First HTML chunk arrived — start the pull loop. */
 export interface FirstChunkEvent {
     type: 'FIRST_CHUNK';
 }
-/** The </body></html> suffix was found and stripped. */
-export interface SuffixFoundEvent {
-    type: 'SUFFIX_FOUND';
-}
 /** HTML stream finished (flush/end). */
 export interface HtmlDoneEvent {
     type: 'HTML_DONE';
@@ -67,10 +57,8 @@ export interface PullErrorEvent {
     type: 'PULL_ERROR';
     error: unknown;
 }
-export type FlightInjectionEvent = FirstChunkEvent | SuffixFoundEvent | HtmlDoneEvent | PullDoneEvent | PullErrorEvent;
+export type FlightInjectionEvent = FirstChunkEvent | HtmlDoneEvent | PullDoneEvent | PullErrorEvent;
 export declare const flightInjectionTransitions: TransitionMap<FlightInjectionState, FlightInjectionEvent>;
-/** Whether the machine is in a state where the suffix has been stripped. */
-export declare function isSuffixStripped(state: FlightInjectionState): boolean;
 /** Whether the HTML stream has finished (flush/end fired). */
 export declare function isHtmlDone(state: FlightInjectionState): boolean;
 /** Whether the RSC pull loop has completed. */

package/dist/server/flight-injection-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flight-injection-state.d.ts","sourceRoot":"","sources":["../../src/server/flight-injection-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAI/D,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,cAAc,GACd,cAAc,GACd,aAAa,GACb,SAAS,GACT,UAAU,CAAC;AAIf,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,oBAAoB,GAC5B,eAAe,GACf,gBAAgB,GAChB,aAAa,GACb,aAAa,GACb,cAAc,CAAC;AAInB,eAAO,MAAM,0BAA0B,EAAE,aAAa,CAAC,oBAAoB,EAAE,oBAAoB,CAwB9F,CAAC;AAIJ,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAUrE;AAED,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAE/D;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAE/D"}
+{"version":3,"file":"flight-injection-state.d.ts","sourceRoot":"","sources":["../../src/server/flight-injection-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAI/D,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,cAAc,GACd,aAAa,GACb,SAAS,GACT,UAAU,CAAC;AAIf,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,aAAa,GAAG,aAAa,GAAG,cAAc,CAAC;AAIpG,eAAO,MAAM,0BAA0B,EAAE,aAAa,CAAC,oBAAoB,EAAE,oBAAoB,CAgB9F,CAAC;AAIJ,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAE/D;AAED,+CAA+C;AAC/C,wBAAgB,UAAU,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAE/D"}

package/dist/server/html-injectors.d.ts

@@ -6,6 +6,52 @@
  *
  * Design docs: 02-rendering-pipeline.md, 18-build-system.md §"Entry Files"
  */
+/**
+ * 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 declare function createBufferedTransformStream(options?: BufferedTransformOptions): TransformStream<Uint8Array, Uint8Array>;
+/**
+ * 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 declare function createMoveSuffixStream(): TransformStream<Uint8Array, Uint8Array>;
 /**
  * Inject metadata elements before </head> in the HTML stream.
  *

package/dist/server/html-injectors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html-injectors.d.ts","sourceRoot":"","sources":["../../src/server/html-injectors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA6EH;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,cAAc,CAAC,UAAU,CAAC,CAE5B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,EAAE,MAAM,GAClB,cAAc,CAAC,UAAU,CAAC,CAE5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CAiC5B;AAiLD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CAS5B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;CACtB;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,OAAO,CAAA;KAAE,CAAC;IACjE,GAAG,EAAE,OAAO,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;CAC7D,GAAG,qBAAqB,CA8DxB"}
+{"version":3,"file":"html-injectors.d.ts","sourceRoot":"","sources":["../../src/server/html-injectors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,wBAA6B,GACrC,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAgEzC;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,CAuChF;AA8ED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,cAAc,CAAC,UAAU,CAAC,CAE5B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,EAAE,MAAM,GAClB,cAAc,CAAC,UAAU,CAAC,CAE5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CAiC5B;AAmHD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,eAAe,CAAC,EAAE,MAAM,GACvB,cAAc,CAAC,UAAU,CAAC,CAiB5B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;CACtB;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,OAAO,CAAA;KAAE,CAAC;IACjE,GAAG,EAAE,OAAO,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;CAC7D,GAAG,qBAAqB,CA8DxB"}

package/dist/server/node-stream-transforms.d.ts

@@ -17,6 +17,43 @@
  * Readable.toWeb() conversion for the Response body.
  */
 import { Transform } from 'node:stream';
+/**
+ * Options for the Node.js buffered transform.
+ */
+export interface NodeBufferedTransformOptions {
+    /**
+     * 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;
+}
+/**
+ * Node.js Transform that buffers incoming chunks and coalesces them
+ * within a single event loop tick.
+ *
+ * Equivalent to createBufferedTransformStream() in html-injectors.ts.
+ * React Fizz may emit multiple micro-chunks within a single flush.
+ * Without buffering, downstream transforms (especially flight injection)
+ * could see chunk boundaries in the middle of HTML tags or attributes.
+ *
+ * This transform collects all chunks that arrive in the same tick and
+ * emits them as a single concatenated Buffer on the next `setImmediate`.
+ *
+ * **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 declare function createNodeBufferedTransform(options?: NodeBufferedTransformOptions): Transform;
+/**
+ * Node.js Transform that moves `</body></html>` to the end of the stream.
+ *
+ * Equivalent to createMoveSuffixStream() in html-injectors.ts.
+ * Strips the suffix when first encountered and re-emits it in flush().
+ * If no suffix is found, it's appended anyway for well-formed HTML.
+ */
+export declare function createNodeMoveSuffixTransform(): Transform;
 /**
  * Node.js Transform that injects HTML content before </head>.
  *
@@ -28,15 +65,14 @@ export declare function createNodeHeadInjector(headHtml: string): Transform;
 /**
  * Node.js Transform that merges RSC script tags into the HTML stream.
  *
- * Equivalent to injectRscPayload() in html-injectors.ts. Combines
- * createInlinedRscStream + createFlightInjectionTransform into a single
- * Node.js Transform.
+ * Reads RSC chunks from the provided ReadableStream and injects them
+ * as `<script>` tags between HTML chunks. Scripts are buffered in
+ * pending[] and only drained from transform() (after a complete HTML
+ * chunk) or flush() — never pushed directly from the pull loop.
  *
- * 1. Strips `</body></html>` from the shell so all subsequent content
- *    is at `<body>` level.
- * 2. Reads RSC chunks from the provided ReadableStream and injects them
- *    as `<script>` tags after HTML chunks.
- * 3. Re-emits `</body></html>` at the very end.
+ * Suffix stripping (</body></html>) is handled upstream by
+ * createNodeMoveSuffixTransform. This transform only interleaves
+ * RSC scripts at safe chunk boundaries.
  *
  * The RSC stream is a Web ReadableStream (from the tee'd RSC Flight
  * stream). We read from it using the Web API — this is the one bridge

package/dist/server/node-stream-transforms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-stream-transforms.d.ts","sourceRoot":"","sources":["../../src/server/node-stream-transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAkBxC;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA+ClE;AAID;;;;;;;;;;;;;;;;GAgBG;AACH;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,OAAO,CAAC,EAAE,yBAAyB,GAClC,SAAS,CAuJX;AAOD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAwBtE;AAoBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,OAAO,EACvB,eAAe,EAAE,OAAO,GACvB,SAAS,GAAG,IAAI,CA8BlB"}
+{"version":3,"file":"node-stream-transforms.d.ts","sourceRoot":"","sources":["../../src/server/node-stream-transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,4BAAiC,GAAG,SAAS,CAgDjG;AAqBD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,IAAI,SAAS,CAwCzD;AAID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA+ClE;AAID;;;;;;;;;;;;;;;GAeG;AACH;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,EACjD,OAAO,CAAC,EAAE,yBAAyB,GAClC,SAAS,CA2IX;AAOD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAwBtE;AAoBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,OAAO,EACvB,eAAe,EAAE,OAAO,GACvB,SAAS,GAAG,IAAI,CA8BlB"}

package/dist/server/ssr-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA0EH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC;;;0DAGsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;4DACwD;IACxD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE;QACZ,gFAAgF;QAChF,QAAQ,EAAE,MAAM,CAAC;QACjB,uDAAuD;QACvD,OAAO,EAAE,MAAM,CAAC;QAChB,gEAAgE;QAChE,MAAM,EAAE,MAAM,CAAC;QACf,wEAAwE;QACxE,UAAU,EAAE,MAAM,CAAC;QACnB,+CAA+C;QAC/C,OAAO,EAAE,MAAM,CAAC;QAChB,sDAAsD;QACtD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CA0JnB;AAED,eAAe,SAAS,CAAC"}
+{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA8EH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC;;;0DAGsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;4DACwD;IACxD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE;QACZ,gFAAgF;QAChF,QAAQ,EAAE,MAAM,CAAC;QACjB,uDAAuD;QACvD,OAAO,EAAE,MAAM,CAAC;QAChB,gEAAgE;QAChE,MAAM,EAAE,MAAM,CAAC;QACf,wEAAwE;QACxE,UAAU,EAAE,MAAM,CAAC;QACnB,+CAA+C;QAC/C,OAAO,EAAE,MAAM,CAAC;QAChB,sDAAsD;QACtD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAmLnB;AAED,eAAe,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.48",
+  "version": "0.2.0-alpha.49",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/server/flight-injection-state.ts

@@ -7,10 +7,14 @@
  * states and the transition map once.
  *
  * Valid state flow:
- *   init → streaming → body-level → flushing → done
- *                  └──────────────→ flushing → done
+ *   init → streaming → flushing → done
  *   (any) → error
  *
+ * Suffix stripping (</body></html>) is handled by a separate
+ * createMoveSuffixStream / createNodeMoveSuffixTransform upstream
+ * in the pipeline (TIM-530). The flight injector only interleaves
+ * RSC scripts between HTML chunks — no suffix tracking needed.
+ *
  * Design doc: 02-rendering-pipeline.md
  */
 
@@ -23,30 +27,19 @@ export interface InitState {
   phase: 'init';
 }
 
-/** HTML chunks flowing, pull loop running, suffix not yet stripped. */
+/** HTML chunks flowing, pull loop running. */
 export interface StreamingState {
   phase: 'streaming';
 }
 
-/**
- * Suffix (</body></html>) stripped. RSC scripts injected at body level.
- * HTML may still be streaming (Suspense chunks after suffix).
- */
-export interface BodyLevelState {
-  phase: 'body-level';
-}
-
 /** HTML stream done (flush fired). Draining remaining RSC chunks. */
 export interface FlushingState {
   phase: 'flushing';
-  /** When true, suffix was found before flushing. */
-  hadSuffix: boolean;
 }
 
 /** All streams consumed. Terminal state. */
 export interface DoneState {
   phase: 'done';
-  hadSuffix: boolean;
 }
 
 /** Pull loop failed. Terminal state with captured error. */
@@ -58,7 +51,6 @@ export interface ErrorState {
 export type FlightInjectionState =
   | InitState
   | StreamingState
-  | BodyLevelState
   | FlushingState
   | DoneState
   | ErrorState;
@@ -70,11 +62,6 @@ export interface FirstChunkEvent {
   type: 'FIRST_CHUNK';
 }
 
-/** The </body></html> suffix was found and stripped. */
-export interface SuffixFoundEvent {
-  type: 'SUFFIX_FOUND';
-}
-
 /** HTML stream finished (flush/end). */
 export interface HtmlDoneEvent {
   type: 'HTML_DONE';
@@ -91,56 +78,30 @@ export interface PullErrorEvent {
   error: unknown;
 }
 
-export type FlightInjectionEvent =
-  | FirstChunkEvent
-  | SuffixFoundEvent
-  | HtmlDoneEvent
-  | PullDoneEvent
-  | PullErrorEvent;
+export type FlightInjectionEvent = FirstChunkEvent | HtmlDoneEvent | PullDoneEvent | PullErrorEvent;
 
 // ─── Transitions ─────────────────────────────────────────────────────────────
 
 export const flightInjectionTransitions: TransitionMap<FlightInjectionState, FlightInjectionEvent> =
   {
-    'init': {
+    init: {
       FIRST_CHUNK: (): StreamingState => ({ phase: 'streaming' }),
       // Edge case: HTML stream ends immediately (empty body)
-      HTML_DONE: (): FlushingState => ({ phase: 'flushing', hadSuffix: false }),
+      HTML_DONE: (): FlushingState => ({ phase: 'flushing' }),
     },
-    'streaming': {
-      SUFFIX_FOUND: (): BodyLevelState => ({ phase: 'body-level' }),
-      HTML_DONE: (): FlushingState => ({ phase: 'flushing', hadSuffix: false }),
+    streaming: {
+      HTML_DONE: (): FlushingState => ({ phase: 'flushing' }),
       PULL_DONE: (): StreamingState => ({ phase: 'streaming' }),
       PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
     },
-    'body-level': {
-      HTML_DONE: (): FlushingState => ({ phase: 'flushing', hadSuffix: true }),
-      PULL_DONE: (): BodyLevelState => ({ phase: 'body-level' }),
-      PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
-    },
-    'flushing': {
-      PULL_DONE: (s): DoneState => ({ phase: 'done', hadSuffix: s.hadSuffix }),
+    flushing: {
+      PULL_DONE: (): DoneState => ({ phase: 'done' }),
       PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
-      // Suffix can be found during flushing if flush() processes remaining text
-      SUFFIX_FOUND: (_s): FlushingState => ({ phase: 'flushing', hadSuffix: true }),
     },
   };
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-/** Whether the machine is in a state where the suffix has been stripped. */
-export function isSuffixStripped(state: FlightInjectionState): boolean {
-  switch (state.phase) {
-    case 'body-level':
-      return true;
-    case 'flushing':
-    case 'done':
-      return state.hadSuffix;
-    default:
-      return false;
-  }
-}
-
 /** Whether the HTML stream has finished (flush/end fired). */
 export function isHtmlDone(state: FlightInjectionState): boolean {
   return state.phase === 'flushing' || state.phase === 'done';

package/src/server/html-injectors.ts

@@ -7,11 +7,172 @@
  * 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,
-  isSuffixStripped,
   isHtmlDone,
   isPullDone,
   type FlightInjectionState,
@@ -158,26 +319,19 @@ export function createInlinedRscStream(
 
 /**
  * Merge RSC script stream into the HTML stream, injecting scripts
- * only as direct children of `<body>`.
- *
- * This single transform replaces the previous two-stage pipeline
- * (createFlightInjectionTransform + createMoveSuffixStream). It:
+ * between HTML chunks at safe boundaries.
  *
- * 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.
+ * Suffix stripping (</body></html>) is handled upstream by
+ * createMoveSuffixStream. This transform only interleaves RSC
+ * scripts — no suffix tracking needed.
  *
- * 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.
+ * 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).
  *
  * State machine phases:
- *   init → streaming → body-level → flushing → done
- *                  └──────────────→ flushing → done
+ *   init → streaming → flushing → done
  *   (any) → error
  *
  * Inspired by Next.js createFlightDataInjectionTransformStream.
@@ -186,11 +340,6 @@ function createFlightInjectionTransform(
   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;
 
@@ -201,26 +350,18 @@ function createFlightInjectionTransform(
 
   let pullPromise: Promise<void> | null = null;
 
-  // RSC script chunks waiting to be injected at the body level.
+  // RSC script chunks waiting to be drained at a safe boundary.
   const pending: Uint8Array[] = [];
 
   async function pullLoop(): Promise<void> {
     // Yield once so the first HTML shell chunk flows through
-    // transform() before we start reading RSC data. Uses
-    // setImmediate (check phase — end of current event loop
-    // iteration) instead of setTimeout(0) (timer phase — next
-    // iteration). Under concurrency, setTimeout(0) yields to
-    // ALL pending timer callbacks from other requests, adding
-    // 1-4ms per yield. setImmediate fires before timers.
-    // Available on both Node.js and Cloudflare Workers.
+    // transform() before we start reading RSC data.
     await new Promise<void>((r) => setImmediate(r));
 
     try {
       for (;;) {
-        // Guard each RSC read with a timeout so a permanently hung
-        // RSC stream eventually aborts. When timeoutMs <= 0, the
-        // guard is disabled. See design/02-rendering-pipeline.md
-        // §"Streaming Constraints".
+        // Guard each RSC read with a timeout.
+        // See design/02 §"Streaming Constraints".
         const readPromise = rscReader.read();
         const { done, value } =
           timeoutMs > 0
@@ -231,16 +372,13 @@ function createFlightInjectionTransform(
           return;
         }
         pending.push(value);
-        // Yield between reads so HTML chunks get a chance to flow
-        // through transform() first — but only while HTML is still
-        // streaming. Once flush() fires (all HTML emitted), drain
-        // remaining RSC chunks without yielding.
+        // 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));
         }
       }
     } catch (err) {
-      // On timeout, cancel the RSC reader to release resources.
       if (err instanceof RenderTimeoutError) {
         rscReader.cancel(err).catch(() => {});
       }
@@ -260,63 +398,24 @@ function createFlightInjectionTransform(
 
   return new TransformStream<Uint8Array, Uint8Array>({
     transform(chunk, controller) {
-      // Pull-based start: don't begin reading RSC until the first
-      // HTML chunk flows through. This matches Next.js's approach
-      // and ensures the shell HTML is enqueued before any RSC
-      // script tags. Without this, the pull loop starts eagerly
-      // and may read RSC data before the browser has any HTML.
       if (machine.state.phase === 'init') {
         machine.send({ type: 'FIRST_CHUNK' });
         pullPromise = pullLoop();
       }
 
-      if (isSuffixStripped(machine.state)) {
-        // 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;
-      }
-
-      // Look for </body></html> in the shell chunk.
-      const text = decoder.decode(chunk, { stream: true });
-      const idx = text.indexOf(suffix);
-      if (idx !== -1) {
-        machine.send({ type: 'SUFFIX_FOUND' });
-        // 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) {
-      // All HTML chunks have been emitted. Transition to flushing —
-      // the pull loop will stop yielding between RSC reads since
-      // isHtmlDone() now returns true. This eliminates ~36 macrotask
-      // yields per request (18 chunks × 2 yields each) that were the
-      // primary source of SSR overhead vs Next.js.
+      // All HTML chunks emitted. Pull loop stops yielding.
       machine.send({ type: 'HTML_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 (machine.state.phase === 'done' && machine.state.hadSuffix) {
-          controller.enqueue(suffixBytes);
-        } else if (machine.state.phase === 'flushing' && machine.state.hadSuffix) {
-          // Pull was already done before flush — drainPending didn't
-          // transition, but we still need the suffix
-          controller.enqueue(suffixBytes);
-        }
       };
 
       if (isPullDone(machine.state)) {
@@ -358,9 +457,17 @@ export function injectRscPayload(
   // Transform RSC binary stream → stream of <script> tags
   const rscScriptStream = createInlinedRscStream(rscStream, renderTimeoutMs);
 
-  // Single transform: strip </body></html>, inject RSC scripts at
-  // body level, re-emit suffix at the very end.
-  return htmlStream.pipeThrough(createFlightInjectionTransform(rscScriptStream, 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());
 }
 
 /**

package/src/server/node-stream-transforms.ts

@@ -20,11 +20,93 @@
 import { Transform } from 'node:stream';
 import { createGzip, constants } from 'node:zlib';
 
+// ─── Buffered Transform ──────────────────────────────────────────────────────
+
+/**
+ * Options for the Node.js buffered transform.
+ */
+export interface NodeBufferedTransformOptions {
+  /**
+   * 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;
+}
+
+/**
+ * Node.js Transform that buffers incoming chunks and coalesces them
+ * within a single event loop tick.
+ *
+ * Equivalent to createBufferedTransformStream() in html-injectors.ts.
+ * React Fizz may emit multiple micro-chunks within a single flush.
+ * Without buffering, downstream transforms (especially flight injection)
+ * could see chunk boundaries in the middle of HTML tags or attributes.
+ *
+ * This transform collects all chunks that arrive in the same tick and
+ * emits them as a single concatenated Buffer on the next `setImmediate`.
+ *
+ * **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 createNodeBufferedTransform(options: NodeBufferedTransformOptions = {}): Transform {
+  const { maxBufferByteLength = Infinity } = options;
+
+  let bufferedChunks: Buffer[] = [];
+  let bufferByteLength = 0;
+  let pendingImmediate: ReturnType<typeof setImmediate> | null = null;
+
+  const transform = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      bufferedChunks.push(chunk);
+      bufferByteLength += chunk.byteLength;
+
+      if (bufferByteLength >= maxBufferByteLength) {
+        // Synchronous flush — buffer is too large to hold
+        flushBuffer();
+      } else if (!pendingImmediate) {
+        // Schedule a deferred flush for end of this tick.
+        // Single-shot setImmediate — NOT a recursive loop.
+        // See design/02 §"No Polling".
+        pendingImmediate = setImmediate(() => {
+          pendingImmediate = null;
+          flushBuffer();
+        });
+      }
+
+      callback();
+    },
+    flush(callback) {
+      // Cancel any pending deferred flush and flush synchronously
+      if (pendingImmediate) {
+        clearImmediate(pendingImmediate);
+        pendingImmediate = null;
+      }
+      flushBuffer();
+      callback();
+    },
+  });
+
+  function flushBuffer() {
+    if (bufferedChunks.length === 0) return;
+
+    const merged = Buffer.concat(bufferedChunks, bufferByteLength);
+    bufferedChunks = [];
+    bufferByteLength = 0;
+    transform.push(merged);
+  }
+
+  return transform;
+}
+
+// ─── Injection Transforms ────────────────────────────────────────────────────
+
 import { createMachine } from '../utils/state-machine.js';
 import { flightChunkScript } from './flight-scripts.js';
 import {
   flightInjectionTransitions,
-  isSuffixStripped,
   isHtmlDone,
   isPullDone,
   type FlightInjectionState,
@@ -33,6 +115,60 @@ import {
 import { withTimeout, RenderTimeoutError } from './render-timeout.js';
 import { logStreamingError } from './logger.js';
 
+// ─── Move Suffix Transform ───────────────────────────────────────────────────
+
+const SUFFIX = '</body></html>';
+const SUFFIX_BUF = Buffer.from(SUFFIX, 'utf-8');
+
+/**
+ * Node.js Transform that moves `</body></html>` to the end of the stream.
+ *
+ * Equivalent to createMoveSuffixStream() in html-injectors.ts.
+ * Strips the suffix when first encountered and re-emits it in flush().
+ * If no suffix is found, it's appended anyway for well-formed HTML.
+ */
+export function createNodeMoveSuffixTransform(): Transform {
+  let foundSuffix = false;
+
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      if (foundSuffix) {
+        this.push(chunk);
+        callback();
+        return;
+      }
+
+      const text = chunk.toString('utf-8');
+      const idx = text.indexOf(SUFFIX);
+      if (idx === -1) {
+        this.push(chunk);
+        callback();
+        return;
+      }
+
+      foundSuffix = true;
+
+      // If the entire chunk is exactly the suffix, skip it
+      if (chunk.byteLength === SUFFIX_BUF.byteLength) {
+        callback();
+        return;
+      }
+
+      // Emit content before the suffix
+      const before = text.slice(0, idx);
+      const after = text.slice(idx + SUFFIX.length);
+      if (before) this.push(Buffer.from(before, 'utf-8'));
+      if (after) this.push(Buffer.from(after, 'utf-8'));
+      callback();
+    },
+    flush(callback) {
+      // Always emit the suffix at the very end
+      this.push(SUFFIX_BUF);
+      callback();
+    },
+  });
+}
+
 // ─── Head Injection ──────────────────────────────────────────────────────────
 
 /**
@@ -96,15 +232,14 @@ export function createNodeHeadInjector(headHtml: string): Transform {
 /**
  * Node.js Transform that merges RSC script tags into the HTML stream.
  *
- * Equivalent to injectRscPayload() in html-injectors.ts. Combines
- * createInlinedRscStream + createFlightInjectionTransform into a single
- * Node.js Transform.
+ * Reads RSC chunks from the provided ReadableStream and injects them
+ * as `<script>` tags between HTML chunks. Scripts are buffered in
+ * pending[] and only drained from transform() (after a complete HTML
+ * chunk) or flush() — never pushed directly from the pull loop.
  *
- * 1. Strips `</body></html>` from the shell so all subsequent content
- *    is at `<body>` level.
- * 2. Reads RSC chunks from the provided ReadableStream and injects them
- *    as `<script>` tags after HTML chunks.
- * 3. Re-emits `</body></html>` at the very end.
+ * Suffix stripping (</body></html>) is handled upstream by
+ * createNodeMoveSuffixTransform. This transform only interleaves
+ * RSC scripts at safe chunk boundaries.
  *
  * The RSC stream is a Web ReadableStream (from the tee'd RSC Flight
  * stream). We read from it using the Web API — this is the one bridge
@@ -136,8 +271,6 @@ export function createNodeFlightInjector(
   }
 
   const timeoutMs = options?.renderTimeoutMs ?? 30_000;
-  const suffix = '</body></html>';
-  const suffixBuf = Buffer.from(suffix, 'utf-8');
   const rscReader = rscStream.getReader();
   const decoder = new TextDecoder('utf-8', { fatal: true });
 
@@ -147,26 +280,29 @@ export function createNodeFlightInjector(
   });
 
   // Stored promise from pullLoop — awaited in flush() via .then()
-  // instead of polling. Matches the Web Streams pattern in
-  // html-injectors.ts (pullPromise.then(finish)).
+  // instead of polling. See design/02 §"No Polling".
   let pullPromise: Promise<void> | null = null;
 
-  // pullLoop reads RSC chunks and pushes them directly to the transform
-  // output as <script> tags. This ensures RSC data is delivered to the
-  // browser as soon as it's available — not deferred until the next HTML
-  // chunk. Critical for streaming: the shell RSC payload must arrive
-  // with the shell HTML so hydration can start before Suspense resolves.
-
-  async function pullLoop(stream: Transform): Promise<void> {
-    // Yield once so the first transform() call can emit the bootstrap
-    // signal before we start pushing data chunks.
+  // RSC script chunks waiting to be drained at a safe boundary.
+  // pullLoop buffers here; transform() and flush() drain.
+  // Scripts are NEVER pushed directly from pullLoop — they are only
+  // emitted from transform() (after a complete HTML chunk) or flush().
+  // This guarantees scripts never land mid-tag. See TIM-527/TIM-529.
+  const pending: Buffer[] = [];
+
+  // pullLoop reads RSC chunks and buffers them as <script> tags in
+  // pending[]. It does NOT push directly to the transform output —
+  // that would cause scripts to interleave at arbitrary byte
+  // boundaries within HTML chunks (TIM-527). Pending scripts are
+  // drained only from transform() or flush().
+  async function pullLoop(): Promise<void> {
+    // Yield once so the first transform() call can process the shell
+    // HTML chunk before we start reading RSC data.
     await new Promise<void>((r) => setImmediate(r));
     try {
       for (;;) {
         // Guard each RSC read with a timeout so a permanently hung
-        // RSC stream (e.g. a Suspense component with a fetch that
-        // never resolves) eventually aborts instead of blocking
-        // forever. When timeoutMs <= 0, the guard is disabled.
+        // RSC stream eventually aborts instead of blocking forever.
         // See design/02-rendering-pipeline.md §"Streaming Constraints".
         const readPromise = rscReader.read();
         const { done, value } =
@@ -179,13 +315,11 @@ export function createNodeFlightInjector(
         }
         const decoded = decoder.decode(value, { stream: true });
         const scriptBuf = Buffer.from(flightChunkScript(decoded), 'utf-8');
-        // Push directly to the transform output — don't wait for an
-        // HTML chunk to trigger drainPending.
-        stream.push(scriptBuf);
+        // Buffer the script — drained by the next transform() or flush().
+        pending.push(scriptBuf);
         // Yield between reads so HTML chunks get a chance to flow
         // through transform() first — but only while HTML is still
-        // streaming. Once flush() fires (all HTML emitted), drain
-        // remaining RSC chunks without yielding.
+        // streaming. Once flush() fires, drain without yielding.
         if (!isHtmlDone(machine.state)) {
           await new Promise<void>((r) => setImmediate(r));
         }
@@ -199,6 +333,13 @@ export function createNodeFlightInjector(
     }
   }
 
+  /** Drain all buffered RSC script chunks to the transform output. */
+  function drainPending(): void {
+    while (pending.length > 0) {
+      transform.push(pending.shift()!);
+    }
+  }
+
   // No bootstrap script here — the init script is in <head> via
   // flightInitScript() (see flight-scripts.ts). This ensures __timber_f
   // exists before any chunk scripts execute.
@@ -210,30 +351,17 @@ export function createNodeFlightInjector(
         machine.send({ type: 'FIRST_CHUNK' });
       }
 
-      if (isSuffixStripped(machine.state)) {
-        transform.push(chunk);
-        callback();
-        return;
-      }
+      // 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 each chunk is
+      // a coherent HTML fragment. Suffix stripping is handled upstream
+      // by createNodeMoveSuffixTransform (TIM-530).
+      transform.push(chunk);
+      drainPending();
 
-      const text = chunk.toString('utf-8');
-      const idx = text.indexOf(suffix);
-      if (idx !== -1) {
-        machine.send({ type: 'SUFFIX_FOUND' });
-        const before = text.slice(0, idx);
-        const after = text.slice(idx + suffix.length);
-        if (before) transform.push(Buffer.from(before, 'utf-8'));
-        if (after) transform.push(Buffer.from(after, 'utf-8'));
-      } else {
-        transform.push(chunk);
-      }
-
-      // Start the pull loop on the first HTML chunk to stream RSC
-      // data chunks alongside the HTML. The __timber_f init script is
-      // already in <head> (via flightInitScript), so no bootstrap needed.
-      // Store the promise so flush() can await it instead of polling.
+      // Start the pull loop on the first HTML chunk.
       if (isFirst) {
-        pullPromise = pullLoop(transform);
+        pullPromise = pullLoop();
       }
       callback();
     },
@@ -244,17 +372,13 @@ export function createNodeFlightInjector(
       machine.send({ type: 'HTML_DONE' });
 
       const finish = () => {
+        // Drain any remaining buffered RSC scripts
+        drainPending();
         if (machine.state.phase === 'error') {
           const err = machine.state.error;
           transform.destroy(err instanceof Error ? err : new Error(String(err)));
           return;
         }
-        const hadSuffix =
-          (machine.state.phase === 'done' && machine.state.hadSuffix) ||
-          (machine.state.phase === 'flushing' && machine.state.hadSuffix);
-        if (hadSuffix) {
-          transform.push(suffixBuf);
-        }
         callback();
       };
 
@@ -263,11 +387,10 @@ export function createNodeFlightInjector(
         return;
       }
       // Wait for the RSC pull loop promise to resolve instead of
-      // polling with setImmediate. This matches the Web Streams
-      // pattern in html-injectors.ts: `pullPromise.then(finish)`.
-      // No CPU spin, no busy-poll — just a Promise chain.
+      // polling with setImmediate. No CPU spin, no busy-poll —
+      // just a Promise chain. See design/02 §"No Polling".
       if (!pullPromise) {
-        pullPromise = pullLoop(transform);
+        pullPromise = pullLoop();
       }
       pullPromise.then(finish, (err) => {
         machine.send({ type: 'PULL_ERROR', error: err });

package/src/server/ssr-entry.ts

@@ -30,7 +30,7 @@ import {
 } from './ssr-render.js';
 import { logRenderError } from './logger.js';
 import { SsrStreamError } from './primitives.js';
-import { injectHead, injectRscPayload } from './html-injectors.js';
+import { createBufferedTransformStream, injectHead, injectRscPayload } from './html-injectors.js';
 import { withNuqsSsrAdapter } from './nuqs-ssr-provider.js';
 import { withSpan } from './tracing.js';
 import { setCurrentParams } from '#/client/use-params.js';
@@ -40,7 +40,9 @@ import { registerSsrDataProvider, type SsrData } from '#/client/ssr-data.js';
 // Dynamic imports of node-stream-transforms and node:stream/promises were
 // costing 3-17ms per request due to module resolution overhead.
 let _nodeStreamImports: {
+  createNodeBufferedTransform: typeof import('./node-stream-transforms.js').createNodeBufferedTransform;
   createNodeHeadInjector: typeof import('./node-stream-transforms.js').createNodeHeadInjector;
+  createNodeMoveSuffixTransform: typeof import('./node-stream-transforms.js').createNodeMoveSuffixTransform;
   createNodeFlightInjector: typeof import('./node-stream-transforms.js').createNodeFlightInjector;
   createNodeErrorHandler: typeof import('./node-stream-transforms.js').createNodeErrorHandler;
   pipeline: typeof import('node:stream/promises').pipeline;
@@ -58,7 +60,9 @@ if (useNodeStreams) {
       import('node:stream'),
     ]);
     _nodeStreamImports = {
+      createNodeBufferedTransform: transforms.createNodeBufferedTransform,
       createNodeHeadInjector: transforms.createNodeHeadInjector,
+      createNodeMoveSuffixTransform: transforms.createNodeMoveSuffixTransform,
       createNodeFlightInjector: transforms.createNodeFlightInjector,
       createNodeErrorHandler: transforms.createNodeErrorHandler,
       pipeline: streamPromises.pipeline,
@@ -236,7 +240,9 @@ export async function handleSsr(
       if (_nodeStreamImports) {
         // Node.js fast path: full pipeline in native streams
         const {
+          createNodeBufferedTransform,
           createNodeHeadInjector,
+          createNodeMoveSuffixTransform,
           createNodeFlightInjector,
           createNodeErrorHandler,
           pipeline,
@@ -264,14 +270,32 @@ export async function handleSsr(
 
         // React 19.3+ emits <!DOCTYPE html> automatically when the root
         // element is <html>, so no framework-level doctype prepend needed.
+        //
+        // Pipeline: buffer → errorHandler → headInjector → flightInjector → moveSuffix → output
+        //
+        // 1. buffer: coalesces Fizz micro-chunks into coherent fragments (TIM-528)
+        // 2. errorHandler: catches post-shell streaming errors
+        // 3. headInjector: injects metadata before </head>
+        // 4. flightInjector: interleaves RSC scripts between HTML chunks (TIM-529)
+        // 5. moveSuffix: strips </body></html>, re-emits at end (TIM-530)
+        const bufferedTransform = createNodeBufferedTransform();
         const errorHandler = createNodeErrorHandler(navContext.signal);
         const headInjector = createNodeHeadInjector(navContext.headHtml);
         const flightInjector = createNodeFlightInjector(navContext.rscStream, {
           renderTimeoutMs,
         });
+        const moveSuffix = createNodeMoveSuffixTransform();
 
         const output = new PassThrough();
-        pipeline(nodeHtmlStream, errorHandler, headInjector, flightInjector, output).catch(() => {
+        pipeline(
+          nodeHtmlStream,
+          bufferedTransform,
+          errorHandler,
+          headInjector,
+          flightInjector,
+          moveSuffix,
+          output
+        ).catch(() => {
           // Pipeline errors are handled by errorHandler transform
         });
         const _pipelineEnd = performance.now();
@@ -310,9 +334,14 @@ export async function handleSsr(
 
       const _renderEnd = performance.now();
 
-      // Inject metadata into <head>, then interleave RSC payload chunks
-      // into the body as they arrive from the tee'd RSC stream.
-      let outputStream = injectHead(htmlStream, navContext.headHtml);
+      // Pipeline: buffer → injectHead → injectRscPayload
+      //
+      // The buffered transform coalesces Fizz micro-chunks into coherent
+      // HTML fragments so downstream transforms never see chunk boundaries
+      // mid-tag. This prevents RSC script injection from breaking HTML
+      // structure (TIM-527).
+      let outputStream = htmlStream.pipeThrough(createBufferedTransformStream());
+      outputStream = injectHead(outputStream, navContext.headHtml);
       outputStream = injectRscPayload(outputStream, navContext.rscStream, renderTimeoutMs);
       const _pipelineEnd = performance.now();