ripple 0.3.64 → 0.3.66

package/tests/hydration/components/try.tsrx

@@ -1,5 +1,31 @@
 import { trackAsync } from 'ripple';
 
+export component RootPending() {
+	<p class="root-pending">{'root loading...'}</p>
+}
+
+export component RootCatch({ error, reset }: { error: Error; reset: () => void }) {
+	<section class="root-catch">
+		<p class="root-error">{error.message}</p>
+		<button class="root-reset" onClick={reset}>{'retry'}</button>
+	</section>
+}
+
+export component RootThrows() {
+	throw new Error('root exploded');
+	<p>{'should not render'}</p>
+}
+
+export component RootAsyncDirect() {
+	let &[value] = trackAsync(() => Promise.resolve('root async value'));
+	<p class="root-async-value">{value}</p>
+}
+
+export component RootAsyncRejects() {
+	let &[value] = trackAsync(() => Promise.reject(new Error('root async failed')));
+	<p class="root-async-value">{value}</p>
+}
+
 export component AsyncListInTryPending() {
 	try {
 		<AsyncList />

package/tests/hydration/try.test.js

@@ -1,10 +1,18 @@
 import { describe, it, expect } from 'vitest';
+import { DEV } from 'esm-env';
 import { flushSync } from 'ripple';
-import { hydrateComponent, container } from '../setup-hydration.js';
+import {
+	hydrateComponent,
+	hydrateComponentWithRootBoundary,
+	container,
+} from '../setup-hydration.js';
 
 import * as ServerComponents from './compiled/server/try.js';
 import * as ClientComponents from './compiled/client/try.js';
 
+const TRACK_ASYNC_PUBLIC_ERROR_MESSAGE = 'An error occurred during async rendering';
+const ROOT_TRACK_ASYNC_ERROR_MESSAGE = DEV ? 'root async failed' : TRACK_ASYNC_PUBLIC_ERROR_MESSAGE;
+
 describe('hydration > try blocks (async)', () => {
 	it('hydrates async try with resolved server content', async () => {
 		await hydrateComponent(
@@ -30,6 +38,97 @@ describe('hydration > try blocks (async)', () => {
 	});
 });
 
+describe('hydration > root try boundary', () => {
+	it('hydrates root catch content rendered by the server root boundary', async () => {
+		/** @type {Element | null | undefined} */
+		let ssrCatch;
+		/** @type {Element | null | undefined} */
+		let ssrError;
+		/** @type {Element | null | undefined} */
+		let ssrReset;
+
+		await hydrateComponentWithRootBoundary(
+			ServerComponents.RootThrows,
+			ClientComponents.RootThrows,
+			{ catch: ServerComponents.RootCatch, pending: ServerComponents.RootPending },
+			{ catch: ClientComponents.RootCatch, pending: ClientComponents.RootPending },
+			({ container, body }) => {
+				expect(body).toContain('<!--[-->');
+				expect(body).toContain('<!--]-->');
+
+				ssrCatch = container.querySelector('.root-catch');
+				ssrError = container.querySelector('.root-error');
+				ssrReset = container.querySelector('.root-reset');
+			},
+		);
+
+		expect(container.querySelector('.root-catch')).toBe(ssrCatch);
+		expect(container.querySelector('.root-error')).toBe(ssrError);
+		expect(container.querySelector('.root-reset')).toBe(ssrReset);
+		expect(ssrError?.textContent).toBe('root exploded');
+		expect(container.querySelector('.root-pending')).toBeNull();
+		expect(container.textContent).not.toContain('should not render');
+	});
+
+	it('hydrates resolved root content from a server trackAsync result', async () => {
+		/** @type {Element | null | undefined} */
+		let ssrValue;
+
+		await hydrateComponentWithRootBoundary(
+			ServerComponents.RootAsyncDirect,
+			ClientComponents.RootAsyncDirect,
+			{ catch: ServerComponents.RootCatch, pending: ServerComponents.RootPending },
+			{ catch: ClientComponents.RootCatch, pending: ClientComponents.RootPending },
+			({ container, body }) => {
+				expect(body).toContain('<!--[-->');
+				expect(body).toContain('<!--]-->');
+				expect(body).toContain('__tsrx_ta_');
+
+				ssrValue = container.querySelector('.root-async-value');
+			},
+		);
+
+		expect(container.querySelector('.root-async-value')).toBe(ssrValue);
+		expect(ssrValue?.textContent).toBe('root async value');
+		expect(container.querySelector('.root-pending')).toBeNull();
+		expect(container.querySelector('.root-catch')).toBeNull();
+		expect(container.querySelector('script[id^="__tsrx_ta_"]')).toBeNull();
+	});
+
+	it('hydrates root catch content from a rejected server trackAsync result', async () => {
+		/** @type {Element | null | undefined} */
+		let ssrCatch;
+		/** @type {Element | null | undefined} */
+		let ssrError;
+		/** @type {Element | null | undefined} */
+		let ssrReset;
+
+		await hydrateComponentWithRootBoundary(
+			ServerComponents.RootAsyncRejects,
+			ClientComponents.RootAsyncRejects,
+			{ catch: ServerComponents.RootCatch, pending: ServerComponents.RootPending },
+			{ catch: ClientComponents.RootCatch, pending: ClientComponents.RootPending },
+			({ container, body }) => {
+				expect(body).toContain('<!--[-->');
+				expect(body).toContain('<!--]-->');
+				expect(body).toContain('__tsrx_ta_');
+
+				ssrCatch = container.querySelector('.root-catch');
+				ssrError = container.querySelector('.root-error');
+				ssrReset = container.querySelector('.root-reset');
+			},
+		);
+
+		expect(container.querySelector('.root-catch')).toBe(ssrCatch);
+		expect(container.querySelector('.root-error')).toBe(ssrError);
+		expect(container.querySelector('.root-reset')).toBe(ssrReset);
+		expect(ssrError?.textContent).toBe(ROOT_TRACK_ASYNC_ERROR_MESSAGE);
+		expect(container.querySelector('.root-async-value')).toBeNull();
+		expect(container.querySelector('.root-pending')).toBeNull();
+		expect(container.querySelector('script[id^="__tsrx_ta_"]')).toBeNull();
+	});
+});
+
 describe.skip('streaming ssr > try blocks (async pending)', () => {
 	it('hydrates async try/pending and retains pending fallback', async () => {
 		await hydrateComponent(

package/tests/server/await.test.tsrx

@@ -1,4 +1,4 @@
-import { get, set, track } from 'ripple';
+import { track } from 'ripple';
 
 describe('await in control flow', () => {
 	it('all tests are commented out for now as await in control flow is not yet supported', () => {

package/tests/server/basic.test.tsrx

@@ -73,7 +73,9 @@ second"</pre>
 		}
 
 		component Basic() {
-			{<tsx>{[1, 2, 3].map((item) => <div class="app-item">{item}</div>)}</tsx>}
+			{<tsx>
+				{[1, 2, 3].map((item) => <div class="app-item">{item}</div>)}
+			</tsx>}
 			{makeFragment('from helper')}
 		}
 

package/tests/server/compiler.test.tsrx

@@ -24,6 +24,115 @@ function getString(e: string = 'test') {
 		expect(result.code).toMatchSnapshot();
 	});
 
+	it('removes TypeScript-only expression wrappers from assignment and update targets', () => {
+		const source = `
+beforeAll(() => {
+	(global as any).ResizeObserver = createMockResizeObserver;
+	(global as any).count++;
+});
+
+component Test() {
+	let toggle: { value: boolean } | undefined;
+	toggle!.value = false;
+	toggle!.value++;
+}`;
+
+		const { code } = compile(source, 'test.tsrx', { mode: 'server' });
+
+		expect(code).toContain('global.ResizeObserver = createMockResizeObserver');
+		expect(code).toContain('global.count++');
+		expect(code).toContain('toggle.value = false');
+		expect(code).toContain('toggle.value++');
+		expect(code).not.toContain('as any');
+		expect(code).not.toContain('!');
+	});
+
+	it(
+		'compiles writes to unknown lazy array index 1 through lazy array helpers in SSR output',
+		() => {
+			const source = `component Child({ pair: &[first, second] }) {
+	second = 10;
+	<div>{first}</div>
+}
+component App() {
+	<Child pair={[0, 1]} />
+}`;
+			const { code } = compile(source, 'test.tsrx', { mode: 'server' });
+
+			expect(code).toContain('_$_.lazy_array_set(lazy, 10, 1)');
+			expect(code).not.toContain('lazy[1] =');
+		},
+	);
+
+	it('does not double-wrap member access on lazy array value bindings in SSR output', () => {
+		const source = `component Child({ pair: &[first] }) {
+	let value = first[0];
+	<div>{value}</div>
+}
+component App() {
+	<Child pair={[{ 0: 'x' }]} />
+}`;
+		const { code } = compile(source, 'test.tsrx', { mode: 'server' });
+
+		expect(code).toContain('let value = _$_.lazy_array_get(lazy, 0)[0];');
+		expect(code).not.toContain('_$_.lazy_array_get(_$_.lazy_array_get(lazy, 0), 0)');
+	});
+
+	it('throws on indexed access through known tracked lazy destructures in SSR output', () => {
+		const source = `import { track } from 'ripple';
+component App() {
+	let &[value, tracked_ref] = track({ 0: 'x' });
+	let nested = value[0];
+	tracked_ref[0] = { 0: 'y' };
+	let next = value[0];
+	<div>{nested}{next}</div>
+}`;
+
+		expect(() => compile(source, 'test.tsrx', { mode: 'server' })).toThrow(
+			/Use \.value or &\[\] lazy destructuring/,
+		);
+	});
+
+	it('throws on known tracked indexed access in SSR output', () => {
+		const source = `import { track } from 'ripple';
+component App() {
+	let tracked = track(0);
+	++tracked[0];
+	tracked[0]++;
+	tracked[0] = tracked[0] + 1;
+	let value = tracked[0];
+	let ref = tracked[1];
+	<div>{value}</div>
+}`;
+
+		expect(() => compile(source, 'test.tsrx', { mode: 'server' })).toThrow(
+			/Use \.value or &\[\] lazy destructuring/,
+		);
+	});
+
+	it(
+		'compiles indexed access on unknown lazy tracked refs through lazy array helpers in SSR output',
+		() => {
+			const source = `import { track } from 'ripple';
+component Child({ pair: &[value, tracked_ref] }) {
+	++tracked_ref[0];
+	tracked_ref[0]++;
+	<div>{value}</div>
+}
+component App() {
+	let tracked = track(0);
+	<Child pair={tracked} />
+}`;
+			const { code } = compile(source, 'test.tsrx', { mode: 'server' });
+
+			expect(code).toContain('_$_.lazy_array_get(lazy, 1)');
+			expect(code).toContain('_$_.lazy_array_update_pre(_$_.lazy_array_get(lazy, 1), 0)');
+			expect(code).toContain('_$_.lazy_array_update(_$_.lazy_array_get(lazy, 1), 0)');
+			expect(code).not.toContain('lazy[1][0]');
+			expect(code).not.toContain('lazy_array_get(lazy, 1)[0]');
+		},
+	);
+
 	it('removes class TypeScript syntax from JS output', () => {
 		const source = `interface BaseEvent {}
 

package/tests/server/lazy-destructuring.test.tsrx

@@ -192,6 +192,19 @@ describe('lazy destructuring', () => {
 		expect(body).toBeHtml('<pre>Alice-30</pre>');
 	});
 
+	it('preserves numeric member access on lazy array value bindings', async () => {
+		component Child({ pair: &[first] }: { pair: [{ 0: string }] }) {
+			<pre>{first[0]}</pre>
+		}
+
+		component Test() {
+			<Child pair={[{ 0: 'x' }]} />
+		}
+
+		const { body } = await render(Test);
+		expect(body).toBeHtml('<pre>x</pre>');
+	});
+
 	it('supports rest in lazy array destructuring for tracked tuples (iterable)', async () => {
 		component Test() {
 			let tracked_value = track(0);
@@ -214,6 +227,23 @@ describe('lazy destructuring', () => {
 		expect(body).toBeHtml('<pre>x-yz</pre>');
 	});
 
+	it('supports rest in lazy array destructuring for iterable values', async () => {
+		component Test() {
+			const source = {
+				*[Symbol.iterator]() {
+					yield 'x';
+					yield 'y';
+					yield 'z';
+				},
+			};
+			const &[first, ...rest] = source;
+			<pre>{`${first}-${rest.join('')}`}</pre>
+		}
+
+		const { body } = await render(Test);
+		expect(body).toBeHtml('<pre>x-yz</pre>');
+	});
+
 	it('supports standalone lazy array destructuring with track()', async () => {
 		component Test() {
 			let count;
@@ -225,6 +255,38 @@ describe('lazy destructuring', () => {
 		expect(body).toBeHtml('<div>0</div>');
 	});
 
+	it('supports direct value access on tracked values during SSR', async () => {
+		component Test() {
+			let tracked = track(0);
+			++tracked.value;
+			tracked.value++;
+			tracked.value = tracked.value + 1;
+			let value = tracked.value;
+			let ref = tracked;
+
+			<pre>{`${value}-${ref === tracked}`}</pre>
+		}
+
+		const { body } = await render(Test);
+		expect(body).toBeHtml('<pre>3-true</pre>');
+	});
+
+	it('supports lazy destructured tracked ref value access during SSR', async () => {
+		component Child({ pair: &[value, tracked_ref] }: { pair: Tracked<number> }) {
+			++tracked_ref.value;
+			tracked_ref.value++;
+			<pre>{`${value}-${tracked_ref.value}`}</pre>
+		}
+
+		component Test() {
+			let tracked = track(0);
+			<Child pair={tracked} />
+		}
+
+		const { body } = await render(Test);
+		expect(body).toBeHtml('<pre>2-2</pre>');
+	});
+
 	it('supports standalone lazy object destructuring', async () => {
 		component Test() {
 			let a;

package/tests/server/tracked-index-access.test.tsrx

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { track } from 'ripple';
+import {
+	lazy_array_get,
+	lazy_array_set,
+	lazy_array_update,
+} from '../../src/runtime/internal/server/index.js';
+
+const value_message = /Use \.value or &\[\] lazy destructuring/;
+const reference_message = /Use the tracked value directly instead/;
+const value_index = Number(0);
+const reference_index = Number(1);
+
+describe('server tracked numeric access', () => {
+	it('throws when tracked values are accessed through numeric properties', () => {
+		const values = [track(0)];
+		const value = values[0];
+
+		expect(() => value[value_index]).toThrow(value_message);
+		expect(() => {
+			value[value_index] = 1;
+		}).toThrow(value_message);
+		expect(() => value[reference_index]).toThrow(reference_message);
+	});
+
+	it('throws when derived values are accessed through numeric properties', () => {
+		const values = [track(() => 1)];
+		const value = values[0];
+
+		expect(() => value[value_index]).toThrow(value_message);
+		expect(() => {
+			value[value_index] = 2;
+		}).toThrow(value_message);
+		expect(() => value[reference_index]).toThrow(reference_message);
+	});
+
+	it('sets tracked lazy index 0 and rejects tracked lazy index 1', () => {
+		const value = track(0);
+
+		lazy_array_set(value, 2, 0);
+		expect(value.value).toBe(2);
+		expect(() => {
+			lazy_array_set(value, track(1), 1);
+		}).toThrow(reference_message);
+		expect(() => {
+			lazy_array_update(value, 1);
+		}).toThrow(reference_message);
+	});
+
+	it('returns undefined for tracked lazy indexes past the tuple length', () => {
+		const value = track(0);
+		const derived = track(() => value.value + 1);
+
+		expect(lazy_array_get(value, 0)).toBe(0);
+		expect(lazy_array_get(value, 1)).toBe(value);
+		expect(lazy_array_get(value, 2)).toBeUndefined();
+		expect(lazy_array_get(derived, 0)).toBe(1);
+		expect(lazy_array_get(derived, 1)).toBe(derived);
+		expect(lazy_array_get(derived, 2)).toBeUndefined();
+	});
+
+	it('ignores tracked lazy writes past the tuple length', () => {
+		const value = track(0);
+		const derived = track(() => value.value + 1);
+
+		lazy_array_set(value, 10, 2);
+		lazy_array_update(value, 2);
+		lazy_array_set(derived, 20, 2);
+		lazy_array_update(derived, 2);
+
+		expect(lazy_array_get(value, 2)).toBeUndefined();
+		expect(lazy_array_get(derived, 2)).toBeUndefined();
+		expect(Object.hasOwn(value, 2)).toBe(false);
+		expect(Object.hasOwn(derived, 2)).toBe(false);
+	});
+});

package/tests/setup-hydration.js

@@ -26,6 +26,37 @@ export async function hydrateComponent(serverComponent, clientComponent) {
 	return { container, unmount };
 }
 
+/**
+ * Helper to server render and hydrate a component with explicit root boundary options.
+ * @param {() => void} serverComponent
+ * @param {() => void} clientComponent
+ * @param {import('ripple/server').BaseRenderOptions['rootBoundary']} serverRootBoundary
+ * @param {import('ripple').RootBoundaryOptions} clientRootBoundary
+ * @param {((details: { container: HTMLDivElement, body: string }) => void) | undefined} [beforeHydrate]
+ * @returns {Promise<{ container: HTMLDivElement, unmount: () => void, body: string }>}
+ */
+export async function hydrateComponentWithRootBoundary(
+	serverComponent,
+	clientComponent,
+	serverRootBoundary,
+	clientRootBoundary,
+	beforeHydrate,
+) {
+	const { body } = await render(serverComponent, {
+		rootBoundary: serverRootBoundary,
+	});
+
+	container.innerHTML = body;
+	beforeHydrate?.({ container, body });
+
+	const unmount = hydrate(clientComponent, {
+		target: container,
+		rootBoundary: clientRootBoundary,
+	});
+
+	return { container, unmount, body };
+}
+
 /**
  * Strips hydration markers from HTML for testing purposes.
  * Hydration markers are: <!--[--> <!--[!--> <!--]-->

package/types/index.d.ts

@@ -4,6 +4,8 @@ export type { AddEventOptions, AddEventObject, ExtendedEventOptions } from '@tsr
 export type Component<T = Record<string, any>> = (props: T) => void;
 
 declare const TSRX_ELEMENT: unique symbol;
+declare const REF_KEY: unique symbol;
+export type RefKey = typeof REF_KEY;
 
 export type TSRXElement = {
 	readonly render: Function;
@@ -17,14 +19,19 @@ export function tsrx_element(render: Function): TSRXElement;
 
 export function mount(
 	component: Component,
-	options: { target: HTMLElement; props?: Record<string, any> },
+	options: { target: HTMLElement; props?: Record<string, any>; rootBoundary?: RootBoundaryOptions },
 ): () => void;
 
 export function hydrate(
 	component: Component,
-	options: { target: HTMLElement; props?: Record<string, any> },
+	options: { target: HTMLElement; props?: Record<string, any>; rootBoundary?: RootBoundaryOptions },
 ): () => void;
 
+export interface RootBoundaryOptions {
+	pending?: Component<Record<string, never>>;
+	catch?: Component<{ error: unknown; reset: () => void }>;
+}
+
 export function tick(): Promise<void>;
 
 export function untrack<T>(fn: () => T): T;
@@ -144,7 +151,7 @@ declare global {
 	};
 }
 
-export function createRefKey(): symbol;
+export function createRefKey(): RefKey;
 
 export function isRefProp(value: unknown): boolean;
 
@@ -163,8 +170,7 @@ interface TrackedBase<V> {
 interface TrackedCallable<V> {
 	(props: V extends Component<infer P> ? P : never): V extends Component ? void : never;
 }
-// Supports indexed access: track(0)[0] → value, track(0)[1] → Tracked<V>
-// And destructuring `const [one, two] = track(0);`
+// Supports destructuring `const [one, two] = track(0);`
 export type Tracked<V> = [V, Tracked<V>] & TrackedBase<V> & TrackedCallable<V>;
 
 // Helper type to infer component type from a function that returns a component
@@ -183,10 +189,6 @@ export type PropsNoChildren<T extends object = {}> = Expand<T>;
 
 type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
 
-export function get<V>(tracked: Tracked<V>): V;
-
-export function set<V>(tracked: Tracked<V>, value: V): void;
-
 // Overload for tracked values - returns the original tracked value type
 export function track<V>(value: Tracked<V>): Tracked<V>;
 // Overload for function values - infers the return type of the function

package/types/server.d.ts

@@ -1,4 +1,4 @@
-import type { Component } from '#public';
+import type { Component, RootBoundaryOptions } from '#public';
 
 // Re-export runtime types for server-compiled components
 export {
@@ -48,6 +48,7 @@ export interface BaseRenderOptions {
 	// defaults to true
 	// set to false to add more content
 	closeStream?: boolean;
+	rootBoundary?: RootBoundaryOptions;
 }
 
 export interface StreamingRenderOptions extends BaseRenderOptions {