npm - ripple - Versions diffs - 0.3.91 → 0.3.92 - Mend

ripple 0.3.91 → 0.3.92

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/CHANGELOG.md +21 -0
package/package.json +1 -1
package/src/constants.js +13 -0
package/src/runtime/index-client.js +5 -1
package/src/runtime/internal/client/hydration.js +4 -1
package/src/runtime/internal/client/template.js +2 -1
package/src/runtime/internal/client/try.js +199 -9
package/src/runtime/internal/client/types.d.ts +25 -0
package/src/runtime/internal/server/blocks.js +47 -9
package/src/runtime/internal/server/index.js +546 -69
package/src/runtime/internal/server/stream-runtime.js +173 -0
package/src/utils/track-async-serialization.js +1 -1
package/tests/hydration/compiled/client/streaming.js +448 -0
package/tests/hydration/compiled/server/streaming.js +476 -0
package/tests/hydration/components/streaming.tsrx +164 -0
package/tests/hydration/streaming.test.js +342 -0
package/tests/hydration/track-async-serialization.test.js +3 -3
package/tests/hydration/try.test.js +4 -4
package/tests/server/streaming-ssr.test.tsrx +710 -0
package/tests/server/track-async-serialization.test.tsrx +9 -9
package/types/server.d.ts +15 -0

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,26 @@
 # ripple
+## 0.3.92
+### Patch Changes
+- [#1326](https://github.com/Ripple-TS/ripple/pull/1326)
+  [`fea49bf`](https://github.com/Ripple-TS/ripple/commit/fea49bfb4410a05e0c915dfa39acdaba7f542737)
+  Thanks [@leonidaz](https://github.com/leonidaz)! - Streaming SSR:
+  `render(App, { stream })` now streams progressively. The synchronous shell (with
+  pending fallbacks for suspended `@try` boundaries and all CSS registered so far)
+  is flushed immediately; each boundary's content streams out of order as a framed
+  chunk once its async work settles, including per-chunk CSS, trackAsync envelopes
+  and `<head>` content. A tiny inline runtime swaps chunks into their slots before
+  hydration, and hydrated boundaries activate streamed chunks in place afterwards
+  — claiming the streamed DOM without re-rendering. Catch-only async boundaries
+  stream an empty slot and resolve to their body or server-rendered catch; errors
+  whose catch region is already on the wire hand off to the client boundary via an
+  error envelope. `render` also gains a `streamTemplate` option for document
+  scaffolding, and the vite plugin streams render-route responses when
+  `ssr.streaming` is enabled in ripple.config.ts (falling back to buffered SSR
+  when index.html lacks the `<!--ssr-head-->`/`<!--ssr-body-->` markers).
 ## 0.3.91
 ### Patch Changes

package/package.json CHANGED Viewed

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.3.91",
+  "version": "0.3.92",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",

package/src/constants.js CHANGED Viewed

@@ -13,6 +13,19 @@ export const HYDRATION_START = '[';
 export const HYDRATION_END = ']';
 export const HYDRATION_ERROR = {};
+// Streaming SSR slot markers. A `<!--[?N-->` comment opens the slot of flush
+// unit N whose content has not been streamed yet (the slot shows the pending
+// fallback, or nothing for catch-only boundaries). The inline stream runtime
+// rewrites the slot to plain `<!--[-->…<!--]-->` when the unit's chunk
+// arrives, or to `<!--[!N-->` when the unit errored after its region was
+// already on the wire.
+export const HYDRATION_START_PENDING = '[?';
+export const HYDRATION_START_ERRORED = '[!';
+export const STREAM_CHUNK_ATTR = 'data-ripple-chunk';
+export const STREAM_HEAD_ATTR = 'data-ripple-head';
+export const STREAM_ERROR_SCRIPT_PREFIX = '__ripple_te_';
 export const BLOCK_OPEN = `<!--${HYDRATION_START}-->`;
 export const BLOCK_CLOSE = `<!--${HYDRATION_END}-->`;
 export const EMPTY_COMMENT = `<!---->`;

package/src/runtime/index-client.js CHANGED Viewed

@@ -133,7 +133,11 @@ export function hydrate(component, options) {
 	try {
 		while (
 			anchor &&
-			(anchor.nodeType !== COMMENT_NODE || /** @type {Comment} */ (anchor).data !== HYDRATION_START)
+			(anchor.nodeType !== COMMENT_NODE ||
+				// any `[`-prefixed marker anchors the root boundary — a streamed
+				// shell whose root suspended starts with a `<!--[?N-->` slot
+				// marker instead of a plain `<!--[-->`
+				!(/** @type {Comment} */ (anchor).data.startsWith(HYDRATION_START)))
 		) {
 			anchor = get_next_sibling(anchor);
 		}

package/src/runtime/internal/client/hydration.js CHANGED Viewed

@@ -73,6 +73,9 @@ export function pop(node) {
  * Scans forward from the current hydrate_node to find the matching HYDRATION_END
  * comment, handling nested blocks by tracking depth.
  * Should be called after hydrate_next() has consumed the opening HYDRATION_START.
+ * Any `[`-prefixed comment opens a nested region — this includes the plain
+ * `<!--[-->` markers as well as streaming slot markers (`<!--[?N-->`,
+ * `<!--[!N-->`), which always pair with a `<!--]-->`.
  * @returns {Node} The HYDRATION_END comment node.
  */
 export function skip_to_hydration_end() {
@@ -84,7 +87,7 @@ export function skip_to_hydration_end() {
 			if (data === HYDRATION_END) {
 				if (depth === 0) return node;
 				depth -= 1;
-			} else if (data === HYDRATION_START) {
+			} else if (data.startsWith(HYDRATION_START)) {
 				depth += 1;
 			}
 		}

package/src/runtime/internal/client/template.js CHANGED Viewed

@@ -223,7 +223,8 @@ function is_after_hydration_block(start, target) {
 		if (current.nodeType === COMMENT_NODE) {
 			var data = /** @type {Comment} */ (current).data;
-			if (data === HYDRATION_START) {
+			// `[`-prefixed covers plain block starts and streaming slot markers
+			if (data.startsWith(HYDRATION_START)) {
 				depth += 1;
 			} else if (data === HYDRATION_END) {
 				if (depth === 0) {

package/src/runtime/internal/client/try.js CHANGED Viewed

@@ -9,7 +9,21 @@ import {
 	resume_block,
 } from './blocks.js';
 import { TRY_BLOCK } from './constants.js';
-import { hydrate_next, hydrate_node, hydrating } from './hydration.js';
+import {
+	COMMENT_NODE,
+	HYDRATION_START,
+	HYDRATION_START_PENDING,
+	HYDRATION_START_ERRORED,
+	STREAM_ERROR_SCRIPT_PREFIX,
+} from '../../../constants.js';
+import {
+	hydrate_next,
+	hydrate_node,
+	hydrating,
+	set_hydrate_node,
+	set_hydrating,
+	skip_to_hydration_end,
+} from './hydration.js';
 import { append } from './template.js';
 import {
 	active_block,
@@ -60,6 +74,14 @@ export function try_block(node, try_fn, catch_fn, pending_fn = null, root_contro
 	var pending_deferreds = new Map();
 	/** @type {Set<Block>} */
 	var paused_blocks = new Set();
+	/** @type {string | null} */
+	var streamed_id = null;
+	var streamed_errored = false;
+	var streamed_fallback = false;
+	/** @type {Comment | null} */
+	var slot_open = null;
+	/** @type {Comment | null} */
+	var slot_close = null;
 	function clear_paused_blocks() {
 		paused_blocks.clear();
@@ -218,6 +240,119 @@ export function try_block(node, try_fn, catch_fn, pending_fn = null, root_contro
 		destroy_resolved();
 	}
+	/**
+	 * Retires the slot wrapper markers once the slot's fate is decided: the
+	 * open comment loses its marker data (it may still serve as the boundary
+	 * anchor, so it must stay in the DOM) and the close comment is dropped —
+	 * keeping `[`/`]` depth balanced for scans over surrounding slots.
+	 * @returns {void}
+	 */
+	function neutralize_slot_markers() {
+		/** @type {Comment} */ (slot_open).data = '';
+		/** @type {ChildNode} */ (slot_close).remove();
+	}
+	/**
+	 * Reads the streamed unit error envelope for this slot and routes the
+	 * error into this boundary, or the nearest catch boundary above it.
+	 * @param {string} id
+	 * @returns {void}
+	 */
+	function route_streamed_error(id) {
+		if (try_block === null || is_destroyed(try_block)) {
+			return;
+		}
+		neutralize_slot_markers();
+		var message = 'An error occurred during server rendering';
+		var script = document.getElementById(STREAM_ERROR_SCRIPT_PREFIX + id);
+		if (script !== null) {
+			try {
+				message = JSON.parse(/** @type {string} */ (script.textContent)).message ?? message;
+			} catch {
+				// keep the generic message
+			}
+			script.remove();
+		}
+		var error = new Error(message);
+		if (catch_fn !== null) {
+			handle_error(error);
+			return;
+		}
+		var outer = get_boundary_with_catch(/** @type {Block} */ (try_block));
+		if (outer === null) {
+			throw error;
+		}
+		outer.s.c(error);
+	}
+	/**
+	 * Empties the streamed slot: destroys the hydrated fallback branch and
+	 * sweeps whatever remains between the wrapper comments (leftover marker
+	 * comments included).
+	 * @returns {void}
+	 */
+	function clear_streamed_slot() {
+		destroy_pending();
+		var node = /** @type {ChildNode} */ (slot_open).nextSibling;
+		while (node !== null && node !== slot_close) {
+			var next = node.nextSibling;
+			/** @type {ChildNode} */ (node).remove();
+			node = next;
+		}
+	}
+	/**
+	 * Called by the inline stream runtime when this slot's chunk arrives after
+	 * hydration: swaps the fallback for the streamed content and claims the
+	 * new DOM through a boundary-scoped hydration walk (trackAsync inside the
+	 * body picks its serialized envelope up from the same chunk).
+	 * @param {HTMLTemplateElement | null} template
+	 * @param {number | undefined} [errored]
+	 * @returns {void}
+	 */
+	function activate_streamed_chunk(template, errored) {
+		if (try_block === null || is_destroyed(try_block)) {
+			return;
+		}
+		var id = /** @type {string} */ (streamed_id);
+		streamed_id = null;
+		if (errored) {
+			clear_streamed_slot();
+			route_streamed_error(id);
+			return;
+		}
+		clear_streamed_slot();
+		if (template !== null) {
+			/** @type {ChildNode} */ (slot_close).before(template.content);
+		}
+		var first = /** @type {ChildNode} */ (slot_open).nextSibling;
+		if (first === null || first === slot_close) {
+			neutralize_slot_markers();
+			return;
+		}
+		// adopt the streamed body's own <!--[--> as the boundary anchor (the
+		// node the buffered-SSR hydration path would have used) and drop the
+		// slot wrapper comments, so the resulting DOM matches buffered SSR
+		// exactly like the pre-hydration swap path does
+		if (anchor === slot_open) {
+			anchor = first;
+		}
+		/** @type {ChildNode} */ (slot_open).remove();
+		/** @type {ChildNode} */ (slot_close).remove();
+		var previous_hydrating = hydrating;
+		var previous_hydrate_node = hydrate_node;
+		set_hydrating(true);
+		set_hydrate_node(first);
+		hydrate_next(); // consume the streamed body's <!--[-->
+		try {
+			has_resolved = true;
+			render_resolved();
+		} finally {
+			set_hydrating(previous_hydrating);
+			set_hydrate_node(previous_hydrate_node, true);
+		}
+	}
 	function begin_request() {
 		var request_id = ++request_version;
 		active_requests.add(request_id);
@@ -312,23 +447,78 @@ export function try_block(node, try_fn, catch_fn, pending_fn = null, root_contro
 	};
 	if (hydrating && (pending_fn !== null || catch_fn !== null)) {
-		// Server wraps try_fn body with <!--[-->...<!--]--> markers when pending or catch is present.
-		// Server resolves all async content fully (pending is only for future streaming SSR),
-		// so the SSR HTML contains resolved content.
-		// Mark as already resolved so begin_request's microtask won't transition to pending.
-		if (pending_fn !== null) {
-			has_resolved = true;
-		}
+		// Server wraps a settled try body with <!--[-->...<!--]--> markers when
+		// pending or catch is present, and the boundary hydrates as resolved.
+		// Streaming SSR instead emits a slot wrapper around the fallback:
+		// <!--[?N--> while unit N's content is still on its way, or
+		// <!--[!N--> when the unit errored after its region was already sent.
 		if (root_controlled) {
 			boundary = /** @type {Node} */ (hydrate_node);
 		}
-		hydrate_next(); // consume <!--[-->
+		var marker = /** @type {Comment} */ (hydrate_node);
+		var data = marker.nodeType === COMMENT_NODE ? marker.data : '';
+		// a slot marker at the boundary's own anchor always belongs to this
+		// boundary — the root boundary included: when the root suspends, the
+		// server emits its slot as the whole body, so the marker doubles as
+		// the hydration anchor
+		if (data.startsWith(HYDRATION_START_PENDING) || data.startsWith(HYDRATION_START_ERRORED)) {
+			// live streamed slot
+			streamed_id = data.slice(HYDRATION_START_PENDING.length);
+			streamed_errored = data.startsWith(HYDRATION_START_ERRORED);
+			slot_open = marker;
+			hydrate_next(); // consume the slot wrapper open
+			slot_close = /** @type {Comment} */ (skip_to_hydration_end());
+			var fallback_start = /** @type {Comment} */ (hydrate_node);
+			streamed_fallback =
+				!streamed_errored &&
+				pending_fn !== null &&
+				fallback_start.nodeType === COMMENT_NODE &&
+				fallback_start.data === HYDRATION_START;
+			if (streamed_fallback) {
+				hydrate_next(); // consume the fallback's <!--[-->
+			}
+		} else {
+			// settled content: mark as already resolved so begin_request's
+			// microtask won't transition to pending
+			if (pending_fn !== null) {
+				has_resolved = true;
+			}
+			hydrate_next(); // consume <!--[-->
+		}
 	}
 	try_block = create_try_block(() => {
+		if (streamed_id !== null) {
+			// the streamed body hasn't arrived yet — hydrate the fallback (if
+			// any) as the pending branch and wait for the chunk to activate us
+			if (streamed_fallback) {
+				mode = 'pending';
+				pending_branch = boundary_fn_running_block(() => {
+					/** @type {PendingFunction} */ (pending_fn)(anchor);
+				});
+			}
+			return;
+		}
 		resolved_branch = boundary_fn_running_block(() => try_fn(anchor));
 	}, state);
+	if (streamed_id !== null) {
+		// continue the outer hydration walk after the slot
+		set_hydrate_node(slot_close);
+		var registry = (window.__RIPPLE_B__ ??= {});
+		var unit_id = streamed_id;
+		if (streamed_errored) {
+			// the inline runtime already emptied the slot and marked it errored
+			// — route the error once the surrounding hydration has finished
+			queue_microtask(() => route_streamed_error(unit_id));
+		} else {
+			registry[unit_id] = { a: activate_streamed_chunk };
+		}
+	}
 	if (hydrating && root_controlled) {
 		append(/** @type {ChildNode} */ (node), /** @type {Node} */ (boundary));
 	}

package/src/runtime/internal/client/types.d.ts CHANGED Viewed

@@ -68,7 +68,32 @@ export type RootBoundaryOptions = {
 	catch?: (anchor: Node, props: { error: unknown; reset: () => void }, block: Block | null) => void;
 };
+/**
+ * Called by the inline stream runtime when a boundary's chunk arrives after
+ * hydration: receives the chunk template (null for error-only chunks) and a
+ * truthy flag when the unit errored server-side.
+ */
+export type StreamBoundaryActivator = (
+	template: HTMLTemplateElement | null,
+	errored?: number,
+) => void;
+/**
+ * `window.__RIPPLE_B__` — shared between the inline stream runtime and
+ * hydrated try boundaries. A boundary that hydrated a still-pending slot
+ * registers `{ a: activator }` under its unit id; the runtime stores `1`
+ * once the slot has been swapped or handed over.
+ */
+export type StreamBoundaryRegistry = Record<string | number, 1 | { a: StreamBoundaryActivator }>;
 declare global {
+	interface Window {
+		/** streamed-boundary registry, see {@link StreamBoundaryRegistry} */
+		__RIPPLE_B__?: StreamBoundaryRegistry;
+		/** inline stream runtime entry point: swaps unit `id`'s chunk into its slot */
+		__RIPPLE_S__?: (id: number, errored?: number) => void;
+	}
 	interface Element {
 		__attributes?: {
 			checked?: boolean;

package/src/runtime/internal/server/blocks.js CHANGED Viewed

@@ -13,6 +13,7 @@ import { ASYNC_DERIVED_READ_THROWN } from '../client/constants.js';
 import {
 	TRY_CATCH_BLOCK,
 	TRY_PENDING_BLOCK,
+	TRY_BLOCK,
 	REGULAR_BLOCK,
 	COMPONENT_BLOCK,
 	ROOT_BLOCK,
@@ -27,6 +28,7 @@ import {
 	TrackAsyncRunError,
 	create_public_track_async_error,
 	serialize_track_async_error,
+	begin_stream_unit,
 } from './index.js';
 /**
@@ -87,14 +89,21 @@ export function try_block(try_fn, catch_fn = null, pending_fn = null) {
 	try {
 		try_fn();
+		if (created_block.o.isStreamMode() && created_block.o.hasPendingAsyncOperations()) {
+			// the body suspended: turn this boundary into a streaming flush unit —
+			// the partially-rendered body is kept (async re-runs fill its holes in
+			// place) and the live slot gets the wrapper markers plus the pending
+			// fallback (nothing, for catch-only boundaries)
+			begin_stream_unit(created_block, pending_fn);
+		}
 	} catch (error) {
 		set_active_block(created_block);
-		if (error === ASYNC_DERIVED_READ_THROWN && created_block.f & TRY_PENDING_BLOCK) {
-			// we should only end up here in the streaming mode during the sync phase
-			created_block.o.clear();
-			pending_fn?.();
-			// continue processing other try blocks
-			return created_block;
+		if (error === ASYNC_DERIVED_READ_THROWN) {
+			// pending reads inside blocks are swallowed by run_block (they
+			// register a re-run); a sentinel escaping to here means a read
+			// happened outside any block — let an outer boundary deal with it
+			throw error;
 		}
 		if (created_block.f & TRY_CATCH_BLOCK) {
@@ -140,6 +149,26 @@ export function component_block(fn) {
 	return block(COMPONENT_BLOCK, fn, null, true);
 }
+/**
+ * Nearest try boundary (pending or catch) — async work is accounted on it,
+ * and in stream mode it is the boundary that becomes a flush unit.
+ * @param {Block} block
+ * @returns {TryBlock}
+ */
+export function get_closest_try_block(block) {
+	var current = block;
+	while (current !== null) {
+		if (current.f & TRY_BLOCK) {
+			return /** @type {TryBlock} */ (current);
+		}
+		// the root block always carries try flags, so we never reach null
+		current = /** @type {Block} */ (current.p);
+	}
+	throw new Error('No try block found');
+}
 /**
  * @param {Block} block
  * @returns {TryBlockWithCatch}
@@ -161,15 +190,20 @@ export function get_closest_catch_block(block) {
 }
 /**
+ * Cancels outstanding async work below an error boundary. Descendant try
+ * boundaries (`is_descendant`) additionally abandon their streaming flush
+ * units — their regions get replaced by the boundary's catch content, so
+ * they must never stream a stale chunk.
  * @param {Block | null} block
+ * @param {boolean} [is_descendant=false]
  * @returns {void}
  */
-export function cancel_async_operations(block) {
+export function cancel_async_operations(block, is_descendant = false) {
 	if (block === null) {
 		return;
 	}
-	if (block.f & TRY_CATCH_BLOCK) {
+	if (block.f & TRY_BLOCK) {
 		if (block.f & CAUGHT_ERROR) {
 			// already handling an error — skip
 			return;
@@ -177,11 +211,15 @@ export function cancel_async_operations(block) {
 		block.o.cancelAsyncOperations();
 		block.f |= CAUGHT_ERROR;
+		if (is_descendant) {
+			block.o.abandonUnit();
+		}
 	}
 	var child = block.first;
 	while (child !== null) {
-		cancel_async_operations(child);
+		cancel_async_operations(child, true);
 		child = child.next;
 	}
 }