From 9155447cd6c5060ac4049c33c8287d92a9b6c898 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Sat, 4 Jul 2026 23:02:15 +0000
Subject: [PATCH] docs(core): update hydrate function docs to reflect triple
 stream output

- Renamed "Dual Stream Output" to "Triple Stream Output" in `incubation-js.md`
- Explicitly defined `resolvedStream`, `mapStream`, and `bodyStream` output types
- Added comprehensive JSDoc type definitions to the `hydrate` implementation blueprint

Co-authored-by: TarasMazepa <6552358+TarasMazepa@users.noreply.github.com>
---
 incubation-js.md | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/incubation-js.md b/incubation-js.md
index 50e1a94..8cf10ac 100644
--- a/incubation-js.md
+++ b/incubation-js.md
@@ -8,10 +8,11 @@ This document captures the formal architectural decisions and API designs specif
   * We are moving away from string-indexed parsing which pulls the entire payload into memory. The `hydrate` function must be implemented as a single-pass, chunk-safe state machine. It needs to handle boundary splits (e.g., holding back an ambiguous `{` at the end of a chunk) to ensure multi-byte characters and template tags are not corrupted across stream chunks.
 * **Polymorphic Inputs**
   * To support Node.js, Deno, and the Browser, the `template` input must support polymorphic types: `String` (for in-memory DX), `ReadableStream` (the Web standard), and `AsyncIterable` (for universal compatibility).
-* **Dual Stream Output (The Plain Object Signature)**
+* **Triple Stream Output (The Plain Object Signature)**
   * To output both the resolved text and the source map without breaking the single-pass rule, the `hydrate` function will return a structured plain object: `{ resolvedStream, mapStream, bodyStream }`.
-  * `resolvedStream` is a `ReadableStream` yielding `String` chunks.
-  * `mapStream` is a `ReadableStream` yielding JS objects (the Index Shift Map with `hydrated-start`, `original-start`, etc.).
+  * `resolvedStream`: A `ReadableStream<string>` yielding safely decoded text chunks.
+  * `mapStream`: A `ReadableStream<Object>` yielding the Index Shift Map JS objects (with `hydrated-start`, `original-start`, etc.).
+  * `bodyStream`: A `ReadableStream<Uint8Array>` yielding raw binary byte chunks for the network handoff.
   * This avoids anti-patterns like attaching custom subfields to a single stream object and makes downstream consumer routing trivial via destructuring.
 * **Synchronous Stream Composition & Detached Processing**
   * **Synchronous Return (Early Return):** The core `hydrate` function must be entirely synchronous (i.e., drop the `async` keyword from the main signature). It must immediately instantiate the `ReadableStream` objects and return the `{ resolvedStream, mapStream, bodyStream }` object before any data is actually read. This is the gold standard for stream pipelines, allowing downstream consumers to synchronously wire up their entire pipeline (e.g., `.pipeTo()`) in a single execution tick without blocking `await` calls.
@@ -21,6 +22,16 @@ This document captures the formal architectural decisions and API designs specif
 ## 1.1 Implementation Blueprint
 
 ```javascript
+/**
+ * @param {ReadableStream<Uint8Array | string>} templateStream
+ * @param {Object} [data={}]
+ * @param {Array<ReadableStream<Uint8Array> | Blob | any>} [streams=[]]
+ * @returns {{
+ * resolvedStream: ReadableStream<string>,
+ * mapStream: ReadableStream<object>,
+ * bodyStream: ReadableStream<Uint8Array>
+ * }}
+ */
 export function hydrate(templateStream, data = {}, streams = []) {
   let resolvedController, mapController, bodyController;