ripple 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # ripple
 
+## 0.3.7
+
+### Patch Changes
+
+- [#832](https://github.com/Ripple-TS/ripple/pull/832)
+  [`9ca9310`](https://github.com/Ripple-TS/ripple/commit/9ca9310550a800f4435821ed84b24bdd4f243117)
+  Thanks [@trueadm](https://github.com/trueadm)! - Fix lazy array rest
+  destructuring for tracked and array-like values by routing rest extraction
+  through a shared `array_slice` helper instead of calling `.slice()` directly on
+  the source.
+
+- [#832](https://github.com/Ripple-TS/ripple/pull/832)
+  [`9ca9310`](https://github.com/Ripple-TS/ripple/commit/9ca9310550a800f4435821ed84b24bdd4f243117)
+  Thanks [@trueadm](https://github.com/trueadm)! - Allow tracked tuple `.length`
+  member access in compiler analysis and simplify tracked direct-access validation
+  into a single combined condition.
+
+- [#832](https://github.com/Ripple-TS/ripple/pull/832)
+  [`9ca9310`](https://github.com/Ripple-TS/ripple/commit/9ca9310550a800f4435821ed84b24bdd4f243117)
+  Thanks [@trueadm](https://github.com/trueadm)! - Fix `to_ts` output for lazy
+  array destructuring so it keeps direct destructuring syntax for `track()` and
+  `trackSplit()` instead of expanding through an intermediate `lazy` variable.
+
+- [#832](https://github.com/Ripple-TS/ripple/pull/832)
+  [`9ca9310`](https://github.com/Ripple-TS/ripple/commit/9ca9310550a800f4435821ed84b24bdd4f243117)
+  Thanks [@trueadm](https://github.com/trueadm)! - Replace tracked `get()`/`set()`
+  APIs with a `value` getter/setter across runtime, types, analyzer tracked-access
+  rules, and lazy destructuring tests.
+
+- Updated dependencies
+  [[`9ca9310`](https://github.com/Ripple-TS/ripple/commit/9ca9310550a800f4435821ed84b24bdd4f243117),
+  [`9ca9310`](https://github.com/Ripple-TS/ripple/commit/9ca9310550a800f4435821ed84b24bdd4f243117),
+  [`9ca9310`](https://github.com/Ripple-TS/ripple/commit/9ca9310550a800f4435821ed84b24bdd4f243117),
+  [`9ca9310`](https://github.com/Ripple-TS/ripple/commit/9ca9310550a800f4435821ed84b24bdd4f243117)]:
+  - ripple@0.3.7
+
+## 0.3.6
+
+### Patch Changes
+
+- Updated dependencies []:
+  - ripple@0.3.6
+
 ## 0.3.5
 
 ### Patch Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -105,6 +105,6 @@
     "vscode-languageserver-types": "^3.17.5"
   },
   "peerDependencies": {
-    "ripple": "0.3.5"
+    "ripple": "0.3.7"
   }
 }

package/src/compiler/phases/2-analyze/index.js

@@ -76,8 +76,16 @@ function mark_control_flow_has_template(path) {
  * @param {AST.Identifier} source_id - The identifier to access properties on
  * @param {AnalysisState} state - The analysis state
  * @param {boolean} writable - Whether assignments/updates should be supported (let vs const)
+ * @param {boolean} is_track_call - Whether the RHS is a Ripple track() call
  */
-function setup_lazy_transforms(pattern, source_id, state, writable) {
+function setup_lazy_transforms(pattern, source_id, state, writable, is_track_call) {
+	// For ArrayPattern from track() calls, use direct get/set calls as a fast path
+	// instead of going through prototype getters source[0]/source[1]
+	if (pattern.type === 'ArrayPattern' && is_track_call) {
+		setup_lazy_array_transforms(pattern, source_id, state, writable);
+		return;
+	}
+
 	const paths = extract_paths(pattern);
 
 	for (const path of paths) {
@@ -141,6 +149,185 @@ function setup_lazy_transforms(pattern, source_id, state, writable) {
 	}
 }
 
+/**
+ * Set up fast-path transforms for lazy array destructuring of tracked values.
+ * For index 0 (the value): uses _$_.get/set/update directly instead of source[0] getters.
+ * For index 1 (the tracked ref): returns source directly instead of source[1].
+ * @param {AST.ArrayPattern} pattern - The array destructuring pattern
+ * @param {AST.Identifier} source_id - The identifier for the tracked value
+ * @param {AnalysisState} state - The analysis state
+ * @param {boolean} writable - Whether assignments/updates should be supported
+ */
+function setup_lazy_array_transforms(pattern, source_id, state, writable) {
+	for (let i = 0; i < pattern.elements.length; i++) {
+		const element = pattern.elements[i];
+		if (!element) continue;
+
+		// Rest elements — fall back to generic source.slice(i)
+		if (element.type === 'RestElement') {
+			const rest_paths = extract_paths(pattern);
+			for (const path of rest_paths) {
+				if (!path.is_rest) continue;
+				const name = /** @type {AST.Identifier} */ (path.node).name;
+				const binding = state.scope.get(name);
+				if (binding !== null) {
+					binding.kind = path.has_default_value ? 'lazy_fallback' : 'lazy';
+					binding.transform = {
+						read: (_) => path.expression(source_id),
+					};
+				}
+			}
+			continue;
+		}
+
+		const actual = element.type === 'AssignmentPattern' ? element.left : element;
+		const has_fallback = element.type === 'AssignmentPattern';
+		const fallback_value = has_fallback
+			? /** @type {AST.AssignmentPattern} */ (element).right
+			: null;
+
+		if (actual.type === 'Identifier' && i <= 1) {
+			const name = actual.name;
+			const binding = state.scope.get(name);
+			if (binding === null) continue;
+
+			binding.kind = has_fallback ? 'lazy_fallback' : 'lazy';
+
+			if (i === 0) {
+				// Fast path for index 0: use _$_.get(source) instead of source[0]
+				const read_expr = has_fallback
+					? () => b.call('_$_.fallback', b.call('_$_.get', source_id), fallback_value)
+					: () => b.call('_$_.get', source_id);
+
+				// Signal that read already produces an unwrapped value (calls _$_.get internally)
+				binding.read_unwraps = true;
+
+				binding.transform = {
+					read: (_) => read_expr(),
+				};
+
+				if (writable) {
+					binding.transform.assign = (_, value) => {
+						return b.call('_$_.set', source_id, value);
+					};
+
+					if (has_fallback) {
+						binding.transform.update = (node) => {
+							const delta = node.operator === '++' ? b.literal(1) : b.literal(-1);
+							const temp = b.id('_v');
+
+							if (node.prefix) {
+								// ++count: compute new value and set it, return new value
+								return b.call(
+									b.arrow(
+										[],
+										b.block([
+											b.var(temp, b.binary('+', read_expr(), delta)),
+											b.stmt(b.call('_$_.set', source_id, temp)),
+											b.return(temp),
+										]),
+									),
+								);
+							} else {
+								// count++: read old value, set new value, return old value
+								return b.call(
+									b.arrow(
+										[],
+										b.block([
+											b.var(temp, read_expr()),
+											b.stmt(b.call('_$_.set', source_id, b.binary('+', temp, delta))),
+											b.return(temp),
+										]),
+									),
+								);
+							}
+						};
+					} else {
+						binding.transform.update = (node) => {
+							const fn_name = node.prefix ? '_$_.update_pre' : '_$_.update';
+							const args = [source_id];
+							if (node.operator === '--') {
+								args.push(b.literal(-1));
+							}
+							return b.call(fn_name, ...args);
+						};
+					}
+				}
+			} else {
+				// Fast path for index 1: source itself is the tracked ref
+				binding.transform = {
+					read: (_) => source_id,
+				};
+			}
+		} else {
+			// Nested patterns or indices > 1: fall back to generic source[i] access via extract_paths
+			/** @type {(object: AST.Expression) => AST.Expression} */
+			const base_expression =
+				i === 0
+					? (object) => b.call('_$_.get', object)
+					: i === 1
+						? (object) => object
+						: (object) => b.member(object, b.literal(i), true);
+
+			const inner_paths = extract_paths(element);
+			for (const path of inner_paths) {
+				const name = /** @type {AST.Identifier} */ (path.node).name;
+				const binding = state.scope.get(name);
+				if (binding === null) continue;
+
+				binding.kind = path.has_default_value ? 'lazy_fallback' : 'lazy';
+
+				binding.transform = {
+					read: (_) => path.expression(base_expression(source_id)),
+				};
+
+				if (writable) {
+					binding.transform.assign = (node, value) => {
+						return b.assignment(
+							'=',
+							/** @type {AST.MemberExpression} */ (
+								path.update_expression(base_expression(source_id))
+							),
+							value,
+						);
+					};
+
+					if (path.has_default_value) {
+						binding.transform.update = (node) => {
+							const member = path.update_expression(base_expression(source_id));
+							const fallback_read = path.expression(base_expression(source_id));
+							const delta = node.operator === '++' ? b.literal(1) : b.literal(-1);
+
+							if (node.prefix) {
+								return b.assignment('=', member, b.binary('+', fallback_read, delta));
+							} else {
+								const temp = b.id('_v');
+								return b.call(
+									b.arrow(
+										[],
+										b.block([
+											b.var(temp, fallback_read),
+											b.stmt(b.assignment('=', member, b.binary('+', temp, delta))),
+											b.return(temp),
+										]),
+									),
+								);
+							}
+						};
+					} else {
+						binding.transform.update = (node) =>
+							b.update(
+								node.operator,
+								path.update_expression(base_expression(source_id)),
+								node.prefix,
+							);
+					}
+				}
+			}
+		}
+	}
+}
+
 /**
  * @param {AST.Function} node
  * @param {AnalysisContext} context
@@ -158,7 +345,7 @@ function visit_function(node, context) {
 
 		if ((param.type === 'ObjectPattern' || param.type === 'ArrayPattern') && param.lazy) {
 			const param_id = b.id(context.state.scope.generate('param'));
-			setup_lazy_transforms(param, param_id, context.state, true);
+			setup_lazy_transforms(param, param_id, context.state, true, false);
 			// Store the generated identifier name on the pattern for the transform phase
 			param.metadata = { ...param.metadata, lazy_id: param_id.name };
 		}
@@ -391,6 +578,21 @@ const visitors = {
 			}
 		}
 
+		// Lazy bindings from track() calls (read_unwraps) are inherently reactive —
+		// propagate tracking even without the @ prefix so that control flow (if/for/switch)
+		// and early returns create reactive blocks
+		if (
+			!node.tracked &&
+			binding?.read_unwraps &&
+			is_reference(node, /** @type {AST.Node} */ (parent)) &&
+			binding.node !== node
+		) {
+			mark_as_tracked(context.path);
+			if (context.state.metadata?.tracking === false) {
+				context.state.metadata.tracking = true;
+			}
+		}
+
 		context.next();
 	},
 
@@ -485,13 +687,27 @@ const visitors = {
 				binding.initial?.type === 'CallExpression' &&
 				is_ripple_track_call(binding.initial.callee, context)
 			) {
-				error(
-					`Accessing a tracked object directly is not allowed, use the \`@\` prefix to read the value inside a tracked object - for example \`@${node.object.name}${node.property.type === 'Identifier' ? `.${node.property.name}` : ''}\``,
-					context.state.analysis.module.filename,
-					node.object,
-					context.state.loose ? context.state.analysis.errors : undefined,
-					context.state.analysis.comments,
-				);
+				const is_allowed_tracked_access =
+					// Allow [0] and [1] indexed access on tracked objects.
+					(node.computed &&
+						node.property.type === 'Literal' &&
+						(node.property.value === 0 || node.property.value === 1)) ||
+					// Allow .value and .length property access on tracked objects.
+					(!node.computed &&
+						node.property.type === 'Identifier' &&
+						(node.property.name === 'value' || node.property.name === 'length'));
+
+				if (is_allowed_tracked_access) {
+					// pass through
+				} else {
+					error(
+						`Accessing a tracked object directly is not allowed, use the \`@\` prefix to read the value inside a tracked object - for example \`@${node.object.name}${node.property.type === 'Identifier' ? `.${node.property.name}` : ''}\``,
+						context.state.analysis.module.filename,
+						node.object,
+						context.state.loose ? context.state.analysis.errors : undefined,
+						context.state.analysis.comments,
+					);
+				}
 			}
 		}
 
@@ -570,7 +786,10 @@ const visitors = {
 				) {
 					const lazy_id = b.id(state.scope.generate('lazy'));
 					const writable = node.kind !== 'const';
-					setup_lazy_transforms(declarator.id, lazy_id, state, writable);
+					const init_is_track =
+						declarator.init?.type === 'CallExpression' &&
+						is_ripple_track_call(declarator.init.callee, context) === 'track';
+					setup_lazy_transforms(declarator.id, lazy_id, state, writable, !!init_is_track);
 					// Store the generated identifier name on the pattern for the transform phase
 					declarator.id.metadata = { ...declarator.id.metadata, lazy_id: lazy_id.name };
 				}
@@ -651,7 +870,7 @@ const visitors = {
 
 			if ((props.type === 'ObjectPattern' || props.type === 'ArrayPattern') && props.lazy) {
 				// Lazy destructuring: &{...} or &[...] — set up lazy transforms
-				setup_lazy_transforms(props, b.id('__props'), context.state, true);
+				setup_lazy_transforms(props, b.id('__props'), context.state, true, false);
 			} else if (props.type === 'AssignmentPattern') {
 				error(
 					'Props are always an object, use destructured props with default values instead',

package/src/compiler/phases/3-transform/client/index.js

@@ -533,7 +533,7 @@ const visitors = {
 					if (context.state.metadata?.tracking === false) {
 						context.state.metadata.tracking = true;
 					}
-					if (node.tracked) {
+					if (node.tracked && !binding?.read_unwraps) {
 						return b.call('_$_.get', build_getter(node, context));
 					}
 				}
@@ -634,17 +634,9 @@ const visitors = {
 			}
 		}
 
-		if (!context.state.to_ts && is_ripple_track_call(callee, context)) {
-			const track_method_name =
-				callee.type === 'Identifier'
-					? callee.name === 'trackSplit'
-						? 'track_split'
-						: 'track'
-					: callee.type === 'MemberExpression' && callee.property.type === 'Identifier'
-						? callee.property.name === 'trackSplit'
-							? 'track_split'
-							: 'track'
-						: 'track';
+		const matched_track_call = !context.state.to_ts ? is_ripple_track_call(callee, context) : null;
+		if (matched_track_call) {
+			const track_method_name = matched_track_call === 'trackSplit' ? 'track_split' : 'track';
 
 			if (callee.type === 'Identifier' && callee.name === 'track') {
 				if (node.arguments.length === 0) {
@@ -943,6 +935,20 @@ const visitors = {
 			}
 		}
 
+		if (context.state.to_ts) {
+			for (const declarator of node.declarations) {
+				if (
+					(declarator.id.type === 'ObjectPattern' || declarator.id.type === 'ArrayPattern') &&
+					declarator.id.lazy
+				) {
+					declarator.id.lazy = false;
+					if (declarator.id.metadata?.lazy_id) {
+						delete declarator.id.metadata.lazy_id;
+					}
+				}
+			}
+		}
+
 		return context.next();
 	},
 
@@ -2019,6 +2025,24 @@ const visitors = {
 
 		const left = node.left;
 
+		// Handle lazy binding assignments (e.g., value = 5 where value is from let &[value] = track(0))
+		// Must come before the left.tracked check to use the binding's transform
+		if (left.type === 'Identifier') {
+			const binding = context.state.scope?.get(left.name);
+			if (binding?.transform?.assign && binding.node !== left) {
+				let value = /** @type {AST.Expression} */ (context.visit(node.right));
+
+				// For compound operators (+=, -=, *=, /=), expand to read + operation
+				if (node.operator !== '=') {
+					const operator = node.operator.slice(0, -1); // '+=' -> '+'
+					const current = binding.transform.read(left);
+					value = b.binary(/** @type {AST.BinaryOperator} */ (operator), current, value);
+				}
+
+				return binding.transform.assign(left, value);
+			}
+		}
+
 		if (
 			left.type === 'MemberExpression' &&
 			(left.tracked || (left.property.type === 'Identifier' && left.property.tracked))

package/src/compiler/phases/3-transform/server/index.js

@@ -334,7 +334,7 @@ const visitors = {
 				(binding.kind === 'lazy' || binding.kind === 'lazy_fallback')
 			) {
 				const transformed = binding.transform.read(node);
-				if (node.tracked) {
+				if (node.tracked && !binding.read_unwraps) {
 					const is_right_side_of_assignment =
 						parent.type === 'AssignmentExpression' && parent.right === node;
 					if (
@@ -520,17 +520,9 @@ const visitors = {
 			}
 		}
 
-		if (is_ripple_track_call(callee, context)) {
-			const track_method_name =
-				callee.type === 'Identifier'
-					? callee.name === 'trackSplit'
-						? 'track_split'
-						: 'track'
-					: callee.type === 'MemberExpression' && callee.property.type === 'Identifier'
-						? callee.property.name === 'trackSplit'
-							? 'track_split'
-							: 'track'
-						: 'track';
+		const track_call_name = is_ripple_track_call(callee, context);
+		if (track_call_name) {
+			const track_method_name = track_call_name === 'trackSplit' ? 'track_split' : 'track';
 
 			return {
 				...node,

package/src/compiler/types/index.d.ts

@@ -1157,9 +1157,11 @@ export interface Binding {
 	/** Transform functions for reading, assigning, and updating this binding */
 	transform?: {
 		read: (node?: AST.Identifier) => AST.Expression;
-		assign?: (node: AST.Pattern, value: AST.Expression) => AST.AssignmentExpression;
+		assign?: (node: AST.Identifier, value: AST.Expression) => AST.Expression;
 		update?: (node: AST.UpdateExpression) => AST.Expression;
 	};
+	/** Whether the read transform already produces an unwrapped value (calls get() internally) */
+	read_unwraps?: boolean;
 }
 
 /**

package/src/compiler/utils.js

@@ -289,27 +289,31 @@ export function is_component_level_function(context) {
 }
 
 /**
- * Returns true if callee is a Ripple track call
+ * Returns the matched Ripple tracking call name
  * @param {AST.Expression | AST.Super} callee
  * @param {CommonContext} context
- * @returns {boolean}
+ * @returns {'track' | 'trackSplit' | null}
  */
 export function is_ripple_track_call(callee, context) {
 	// Super expressions cannot be Ripple track calls
-	if (callee.type === 'Super') return false;
+	if (callee.type === 'Super') return null;
 
 	if (callee.type === 'Identifier' && (callee.name === 'track' || callee.name === 'trackSplit')) {
-		return is_ripple_import(callee, context);
+		return is_ripple_import(callee, context) ? callee.name : null;
 	}
 
-	return (
+	if (
 		callee.type === 'MemberExpression' &&
 		callee.object.type === 'Identifier' &&
 		callee.property.type === 'Identifier' &&
 		(callee.property.name === 'track' || callee.property.name === 'trackSplit') &&
 		!callee.computed &&
 		is_ripple_import(callee, context)
-	);
+	) {
+		return callee.property.name;
+	}
+
+	return null;
 }
 
 /**

package/src/runtime/internal/client/index.js

@@ -80,6 +80,8 @@ export { switch_block as switch } from './switch.js';
 
 export { template, append, text } from './template.js';
 
+export { array_slice } from './utils.js';
+
 export { ripple_array } from '../../array.js';
 
 export { ripple_object } from '../../object.js';

package/src/runtime/internal/client/runtime.js

@@ -289,6 +289,95 @@ export function run_block(block) {
 
 var empty_get_set = { get: undefined, set: undefined };
 
+class TrackedValue {
+	/**
+	 * @param {any} v
+	 * @param {Block} block
+	 * @param {{ get?: Function; set?: Function }} a
+	 */
+	constructor(v, block, a) {
+		this.a = a;
+		this.b = block;
+		this.c = 0;
+		this.f = TRACKED;
+		this.__v = v;
+	}
+	get [0]() {
+		return get_tracked(/** @type {Tracked} */ (this));
+	}
+	set [0](v) {
+		set(/** @type {Tracked} */ (this), v);
+	}
+	get [1]() {
+		return this;
+	}
+	get value() {
+		return get_tracked(/** @type {Tracked} */ (this));
+	}
+	/** @param {any} v */
+	set value(v) {
+		set(/** @type {Tracked} */ (this), v);
+	}
+	/** @returns {2} */
+	get length() {
+		return 2;
+	}
+	*[Symbol.iterator]() {
+		yield get_tracked(/** @type {Tracked} */ (this));
+		yield this;
+	}
+}
+
+class DerivedValue {
+	/**
+	 * @param {Function} fn
+	 * @param {Block} block
+	 * @param {{ get?: Function; set?: Function }} a
+	 */
+	constructor(fn, block, a) {
+		this.a = a;
+		this.b = block;
+		/** @type {null | Block[]} */
+		this.blocks = null;
+		this.c = 0;
+		this.co = active_component;
+		/** @type {null | Dependency} */
+		this.d = null;
+		this.f = TRACKED | DERIVED;
+		this.fn = fn;
+		this.__v = UNINITIALIZED;
+	}
+	get [0]() {
+		return get_derived(/** @type {Derived} */ (this));
+	}
+	set [0](v) {
+		set(/** @type {Derived} */ (this), v);
+	}
+	get [1]() {
+		return this;
+	}
+	get value() {
+		return get_derived(/** @type {Derived} */ (this));
+	}
+	/** @param {any} v */
+	set value(v) {
+		set(/** @type {Derived} */ (this), v);
+	}
+	/** @returns {2} */
+	get length() {
+		return 2;
+	}
+	*[Symbol.iterator]() {
+		yield get_derived(/** @type {Derived} */ (this));
+		yield this;
+	}
+}
+
+if (DEV) {
+	define_property(TrackedValue.prototype, 'DO_NOT_ACCESS_THIS_OBJECT_DIRECTLY', { value: true });
+	define_property(DerivedValue.prototype, 'DO_NOT_ACCESS_THIS_OBJECT_DIRECTLY', { value: true });
+}
+
 /**
  *
  * @param {any} v
@@ -298,25 +387,9 @@ var empty_get_set = { get: undefined, set: undefined };
  * @returns {Tracked}
  */
 export function tracked(v, block, get, set) {
-	// TODO: now we expose tracked, we should likely block access in DEV somehow
-	if (DEV) {
-		return {
-			DO_NOT_ACCESS_THIS_OBJECT_DIRECTLY: true,
-			a: get || set ? { get, set } : empty_get_set,
-			b: block || active_block,
-			c: 0,
-			f: TRACKED,
-			__v: v,
-		};
-	}
-
-	return {
-		a: get || set ? { get, set } : empty_get_set,
-		b: block || active_block,
-		c: 0,
-		f: TRACKED,
-		__v: v,
-	};
+	return /** @type {Tracked} */ (
+		new TrackedValue(v, block || active_block, get || set ? { get, set } : empty_get_set)
+	);
 }
 
 /**
@@ -327,32 +400,9 @@ export function tracked(v, block, get, set) {
  * @returns {Derived}
  */
 export function derived(fn, block, get, set) {
-	if (DEV) {
-		return {
-			DO_NOT_ACCESS_THIS_OBJECT_DIRECTLY: true,
-			a: get || set ? { get, set } : empty_get_set,
-			b: block || active_block,
-			blocks: null,
-			c: 0,
-			co: active_component,
-			d: null,
-			f: TRACKED | DERIVED,
-			fn,
-			__v: UNINITIALIZED,
-		};
-	}
-
-	return {
-		a: get || set ? { get, set } : empty_get_set,
-		b: block || active_block,
-		blocks: null,
-		c: 0,
-		co: active_component,
-		d: null,
-		f: TRACKED | DERIVED,
-		fn,
-		__v: UNINITIALIZED,
-	};
+	return /** @type {Derived} */ (
+		new DerivedValue(fn, block || active_block, get || set ? { get, set } : empty_get_set)
+	);
 }
 
 /**

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

@@ -24,6 +24,11 @@ export type Tracked<V = any> = {
 	c: number;
 	f: number;
 	__v: V;
+	readonly [0]: V;
+	[1]: Tracked<V>;
+	value: V;
+	readonly length: 2;
+	[Symbol.iterator](): Iterator<V | Tracked<V>>;
 };
 
 export type Derived = {
@@ -37,6 +42,11 @@ export type Derived = {
 	f: number;
 	fn: Function;
 	__v: any;
+	readonly [0]: any;
+	[1]: Derived;
+	value: any;
+	readonly length: 2;
+	[Symbol.iterator](): Iterator<any | Derived>;
 };
 
 export type Block = {

package/src/runtime/internal/client/utils.js

@@ -27,6 +27,18 @@ export var object_prototype = Object.prototype;
 /** @type {typeof Array.prototype} */
 export var array_prototype = Array.prototype;
 
+/**
+ * Slice helper for arrays and array-like values.
+ * @param {ArrayLike<any>} array_like
+ * @param {...number} args
+ * @returns {any[]}
+ */
+export function array_slice(array_like, ...args) {
+	return is_array(array_like)
+		? array_like.slice(...args)
+		: array_prototype.slice.call(array_like, ...args);
+}
+
 /**
  * Creates a text node that serves as an anchor point in the DOM.
  * @returns {Text}

package/src/runtime/internal/server/index.js

@@ -5,7 +5,13 @@
 
 import { Readable } from 'stream';
 import { DERIVED, UNINITIALIZED, TRACKED } from '../client/constants.js';
-import { is_ripple_object, get_descriptor, define_property, is_array } from '../client/utils.js';
+import {
+	is_ripple_object,
+	get_descriptor,
+	define_property,
+	is_array,
+	array_slice,
+} from '../client/utils.js';
 import { escape } from '../../../utils/escaping.js';
 import { is_boolean_attribute } from '../../../compiler/utils.js';
 import { clsx } from 'clsx';
@@ -20,6 +26,7 @@ export { escape };
 export { register_component_css as register_css } from './css-registry.js';
 export { hash } from '../../../utils/hashing.js';
 export { context } from './context.js';
+export { array_slice };
 
 /** @type {null | Component} */
 export let active_component = null;
@@ -607,6 +614,84 @@ export function spread_attrs(attrs, css_hash) {
 
 var empty_get_set = { get: undefined, set: undefined };
 
+class TrackedValue {
+	/**
+	 * @param {any} v
+	 * @param {{ get?: Function; set?: Function }} a
+	 */
+	constructor(v, a) {
+		this.a = a;
+		this.c = 0;
+		this.f = TRACKED;
+		this.v = v;
+	}
+	get [0]() {
+		return get(/** @type {Tracked} */ (this));
+	}
+	set [0](v) {
+		set(/** @type {Tracked} */ (this), v);
+	}
+	get [1]() {
+		return this;
+	}
+	get value() {
+		return get(/** @type {Tracked} */ (this));
+	}
+	/** @param {any} v */
+	set value(v) {
+		set(/** @type {Tracked} */ (this), v);
+	}
+	/** @returns {2} */
+	get length() {
+		return 2;
+	}
+	*[Symbol.iterator]() {
+		yield get(/** @type {Tracked} */ (this));
+		yield this;
+	}
+}
+
+class DerivedValue {
+	/**
+	 * @param {Function} fn
+	 * @param {{ get?: Function; set?: Function }} a
+	 */
+	constructor(fn, a) {
+		this.a = a;
+		this.c = 0;
+		this.co = active_component;
+		/** @type {null | import('#server').Dependency} */
+		this.d = null;
+		this.f = TRACKED | DERIVED;
+		this.fn = fn;
+		this.v = UNINITIALIZED;
+	}
+	get [0]() {
+		return get(/** @type {Derived} */ (this));
+	}
+	set [0](v) {
+		set(/** @type {Derived} */ (this), v);
+	}
+	get [1]() {
+		return this;
+	}
+	get value() {
+		return get(/** @type {Derived} */ (this));
+	}
+	/** @param {any} v */
+	set value(v) {
+		set(/** @type {Derived} */ (this), v);
+	}
+	/** @returns {2} */
+	get length() {
+		return 2;
+	}
+	*[Symbol.iterator]() {
+		yield get(/** @type {Derived} */ (this));
+		yield this;
+	}
+}
+
 /**
  * @param {any} v
  * @param {(value: any) => any} [get]
@@ -614,12 +699,7 @@ var empty_get_set = { get: undefined, set: undefined };
  * @returns {Tracked}
  */
 function tracked(v, get, set) {
-	return {
-		a: get || set ? { get, set } : empty_get_set,
-		c: 0,
-		f: TRACKED,
-		v,
-	};
+	return /** @type {Tracked} */ (new TrackedValue(v, get || set ? { get, set } : empty_get_set));
 }
 
 /**
@@ -636,15 +716,7 @@ export function track(v, get, set) {
 	}
 
 	if (typeof v === 'function') {
-		return {
-			a: get || set ? { get, set } : empty_get_set,
-			c: 0,
-			co: active_component,
-			d: null,
-			f: TRACKED | DERIVED,
-			fn: v,
-			v: UNINITIALIZED,
-		};
+		return /** @type {Derived} */ (new DerivedValue(v, get || set ? { get, set } : empty_get_set));
 	}
 
 	return tracked(v, get, set);
@@ -678,7 +750,7 @@ export function track_split(v, l) {
 				t = v[key];
 			} else {
 				t = tracked(undefined);
-				t = define_property(t, '__v', /** @type {PropertyDescriptor} */ (get_descriptor(v, key)));
+				t = define_property(t, 'v', /** @type {PropertyDescriptor} */ (get_descriptor(v, key)));
 			}
 		} else {
 			t = tracked(undefined);

package/src/runtime/internal/server/types.d.ts

@@ -19,6 +19,11 @@ export type Derived = {
 	f: number;
 	fn: Function;
 	v: any;
+	readonly [0]: any;
+	[1]: Derived;
+	value: any;
+	readonly length: 2;
+	[Symbol.iterator](): Iterator<any | Derived>;
 };
 
 export type Tracked = {
@@ -26,4 +31,9 @@ export type Tracked = {
 	c: number;
 	f: number;
 	v: any;
+	readonly [0]: any;
+	[1]: Tracked;
+	value: any;
+	readonly length: 2;
+	[Symbol.iterator](): Iterator<any | Tracked>;
 };

package/src/utils/ast.js

@@ -195,7 +195,7 @@ function _extract_paths(assignments = [], param, expression, update_expression,
 					if (element.type === 'RestElement') {
 						/** @type {DestructuredAssignment['expression']} */
 						const rest_expression = (object) =>
-							b.call(b.member(expression(object), 'slice'), b.literal(i));
+							b.call('_$_.array_slice', expression(object), b.literal(i));
 						if (element.argument.type === 'Identifier') {
 							assignments.push({
 								node: element.argument,

package/tests/client/compiler/compiler.basic.test.ripple

@@ -340,6 +340,35 @@ component App() {
 		expect(result).toMatch(/value:\s*value\??\.\['#v'\]/);
 	});
 
+	it('keeps lazy destructuring as plain destructuring in to_ts output', () => {
+		const track_split_source = `
+import { trackSplit } from 'ripple';
+component App() {
+	const source = { a: 1, b: 2, c: 3 };
+	let &[a, b, rest] = trackSplit(source, ['a', 'b']);
+	const sum = @a + @b + @rest.c;
+}
+`;
+		const track_split_result = compile_to_volar_mappings(track_split_source, 'test.ripple').code;
+		expect(track_split_result).toContain('let [a, b, rest] = trackSplit(source, [\'a\', \'b\']);');
+		expect(track_split_result).not.toContain('let lazy = trackSplit');
+
+		const track_source = `
+import { track } from 'ripple';
+component App() {
+	let &[value, ...rest] = track(0);
+	const x = value;
+}
+`;
+		const track_result = compile_to_volar_mappings(track_source, 'test.ripple').code;
+		expect(track_result).toContain('let [value, ...rest] = track(0);');
+		expect(track_result).toContain('const x = value;');
+		expect(track_result).not.toContain('let lazy = track(0)');
+		expect(track_result).not.toContain('.slice(');
+		expect(track_result).not.toContain('_$_.get(');
+		expect(track_result).not.toContain('lazy0');
+	});
+
 	it('preserves generic type args in interface extends for Volar mappings', () => {
 		const source = `
 interface PolymorphicProps<T extends keyof HTMLElementTagNameMap> {

package/tests/client/compiler/compiler.tracked-access.test.ripple

@@ -121,4 +121,70 @@ import { get, track } from 'ripple';
 			expect(() => compile(code, 'test.ripple')).not.toThrow();
 		},
 	);
+
+	it('should allow indexed [0] access on a tracked object', () => {
+		const code = `
+import { track } from 'ripple';
+            export default component App() {
+                let count = track(0);
+                console.log(count[0]);
+            }
+        `;
+		expect(() => compile(code, 'test.ripple')).not.toThrow();
+	});
+
+	it('should allow indexed [1] access on a tracked object', () => {
+		const code = `
+import { track } from 'ripple';
+            export default component App() {
+                let count = track(0);
+                let raw = count[1];
+            }
+        `;
+		expect(() => compile(code, 'test.ripple')).not.toThrow();
+	});
+
+	it('should allow [0] write on a tracked object', () => {
+		const code = `
+import { track } from 'ripple';
+            export default component App() {
+                let count = track(0);
+                count[0] = 5;
+            }
+        `;
+		expect(() => compile(code, 'test.ripple')).not.toThrow();
+	});
+
+	it('should allow .value read access on a tracked object', () => {
+		const code = `
+import { track } from 'ripple';
+            export default component App() {
+                let count = track(0);
+                console.log(count.value);
+            }
+        `;
+		expect(() => compile(code, 'test.ripple')).not.toThrow();
+	});
+
+	it('should allow .value assignment on a tracked object', () => {
+		const code = `
+import { track } from 'ripple';
+            export default component App() {
+                let count = track(0);
+                count.value = 5;
+            }
+        `;
+		expect(() => compile(code, 'test.ripple')).not.toThrow();
+	});
+
+	it('should allow .length read access on a tracked object', () => {
+		const code = `
+import { track } from 'ripple';
+            export default component App() {
+                let count = track(0);
+                console.log(count.length);
+            }
+        `;
+		expect(() => compile(code, 'test.ripple')).not.toThrow();
+	});
 });

package/tests/client/lazy-destructuring.test.ripple

@@ -1,6 +1,28 @@
-import { flushSync, track } from 'ripple';
+import { flushSync, track, trackSplit } from 'ripple';
 
 describe('lazy destructuring', () => {
+	it('supports tracked value getter and setter', () => {
+		component Test() {
+			let count = track(1);
+			let doubled = track(() => count.value * 2);
+
+			<div>{`${count.value}-${doubled.value}`}</div>
+			<button
+				onClick={() => {
+					count.value = 5;
+				}}
+			>
+				{'set'}
+			</button>
+		}
+
+		render(Test);
+		expect(container.querySelector('div')!.textContent).toBe('1-2');
+		container.querySelector('button')!.click();
+		flushSync();
+		expect(container.querySelector('div')!.textContent).toBe('5-10');
+	});
+
 	it('lazily accesses object properties with const', () => {
 		component Inner(&{ a, b }: { a: number; b: string }) {
 			<pre>{`${a}-${b}`}</pre>
@@ -183,6 +205,38 @@ describe('lazy destructuring', () => {
 		expect(container.querySelector('pre')!.textContent).toBe('1-99');
 	});
 
+	it('does not apply the track tuple fast-path to trackSplit lazy arrays', () => {
+		component Test() {
+			const source = { a: 1, b: 2, c: 3 };
+			let &[a, b, rest] = trackSplit(source, ['a', 'b']);
+			<pre>{`${@a}-${@b}-${@rest.c}`}</pre>
+		}
+
+		render(Test);
+		expect(container.querySelector('pre')!.textContent).toBe('1-2-3');
+	});
+
+	it('supports rest destructuring from iterable array-like tracked values', () => {
+		component Test() {
+			let &[value, ...rest] = track(0);
+			<pre>{`${value}-${@rest.length}-${@rest[0] === value}`}</pre>
+		}
+
+		render(Test);
+		expect(container.querySelector('pre')!.textContent).toBe('0-1-false');
+	});
+
+	it('supports rest destructuring from length-only array-like sources', () => {
+		component Test() {
+			const source = { 0: 'x', 1: 'y', 2: 'z', length: 3 };
+			const &[first, ...rest] = source;
+			<pre>{`${first}-${rest.join(',')}`}</pre>
+		}
+
+		render(Test);
+		expect(container.querySelector('pre')!.textContent).toBe('x-y,z');
+	});
+
 	it('supports update expressions on lazy bindings with default values', () => {
 		component Test() {
 			const obj: { count?: number } = {};

package/tests/hydration/components/basic.ripple

@@ -1,5 +1,5 @@
 // Basic static components for hydration testing
-import type { Component } from 'ripple';
+import type { Children } from 'ripple';
 
 export component StaticText() {
 	<div>{'Hello World'}</div>
@@ -97,7 +97,7 @@ component Actions({ playgroundVisible = false }: { playgroundVisible: boolean })
 	</div>
 }
 
-component Layout({ children }: { children: Component }) {
+component Layout({ children }: { children: Children }) {
 	<main>
 		<div class="container">
 			<children />

package/tests/hydration/components/composite.ripple

@@ -1,6 +1,6 @@
-import type { Component } from 'ripple';
+import type { Children } from 'ripple';
 
-export component Layout(&{ children }: { children?: Component }) {
+export component Layout(&{ children }: { children?: Children }) {
 	<div class="layout">
 		<children />
 	</div>

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

@@ -1,4 +1,20 @@
+import { track, trackSplit } from 'ripple';
+
 describe('lazy destructuring', () => {
+	it('supports tracked value getter and setter', async () => {
+		component Test() {
+			let count = track(1);
+			let derived = track(() => count.value * 2);
+
+			count.value = 3;
+
+			<pre>{`${count.value}-${derived.value}`}</pre>
+		}
+
+		const { body } = await render(Test);
+		expect(body).toBeHtml('<pre>3-6</pre>');
+	});
+
 	it('lazily accesses object properties', async () => {
 		component Inner(&{ a, b }: { a: number; b: string }) {
 			<pre>{`${a}-${b}`}</pre>
@@ -100,4 +116,37 @@ describe('lazy destructuring', () => {
 		const { body } = await render(Test);
 		expect(body).toBeHtml('<pre>Alice-30</pre>');
 	});
+
+	it('treats lazy array destructuring of trackSplit as regular array access', async () => {
+		component Test() {
+			const source = { a: 1, b: 2, c: 3 };
+			const &[a, b, rest] = trackSplit(source, ['a', 'b']);
+			<pre>{`${@a}-${@b}-${@rest.c}`}</pre>
+		}
+
+		const { body } = await render(Test);
+		expect(body).toBeHtml('<pre>1-2-3</pre>');
+	});
+
+	it('supports rest in lazy array destructuring for tracked tuples (iterable)', async () => {
+		component Test() {
+			let tracked_value = track(0);
+			let &[value, ...rest] = tracked_value;
+			<pre>{`${value}-${@rest.length}-${@rest[0] === tracked_value}`}</pre>
+		}
+
+		const { body } = await render(Test);
+		expect(body).toBeHtml('<pre>0-1-true</pre>');
+	});
+
+	it('supports rest in lazy array destructuring for length-only array-like values', async () => {
+		component Test() {
+			const array_like = { 0: 'x', 1: 'y', 2: 'z', length: 3 };
+			const &[first, ...rest] = array_like;
+			<pre>{`${first}-${rest.join('')}`}</pre>
+		}
+
+		const { body } = await render(Test);
+		expect(body).toBeHtml('<pre>x-yz</pre>');
+	});
 });

package/tests/utils/vite-plugin-hmr.test.js

@@ -0,0 +1,98 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ripple } from '@ripple-ts/vite-plugin';
+
+describe('vite-plugin-ripple hotUpdate', () => {
+	it('invalidates SSR modules for non-self-accepting .ripple files', async () => {
+		const [plugin] = ripple({ excludeRippleExternalModules: true });
+		await plugin.configResolved?.({ root: '/workspace', command: 'serve' });
+
+		const transform_request = vi.fn().mockResolvedValue(undefined);
+		const get_css_module = vi.fn().mockReturnValue(undefined);
+		const invalidate_css_module = vi.fn();
+		const send_hot_update = vi.fn();
+		const get_ssr_modules = vi.fn().mockReturnValue(new Set([{ id: 'ssr:a' }, { id: 'ssr:b' }]));
+		const invalidate_ssr_module = vi.fn();
+
+		const result = await plugin.hotUpdate.handler.call(
+			{
+				environment: {
+					name: 'client',
+					transformRequest: transform_request,
+					moduleGraph: {
+						getModuleById: get_css_module,
+						invalidateModule: invalidate_css_module,
+					},
+					hot: {
+						send: send_hot_update,
+					},
+				},
+			},
+			{
+				file: '/workspace/src/non-component.ripple',
+				modules: [{ id: 'client:non-component', isSelfAccepting: false }],
+				server: {
+					environments: {
+						ssr: {
+							moduleGraph: {
+								getModulesByFile: get_ssr_modules,
+								invalidateModule: invalidate_ssr_module,
+							},
+						},
+					},
+				},
+			},
+		);
+
+		expect(transform_request).toHaveBeenCalledWith('/src/non-component.ripple');
+		expect(get_ssr_modules).toHaveBeenCalledWith('/workspace/src/non-component.ripple');
+		expect(invalidate_ssr_module).toHaveBeenCalledTimes(2);
+		expect(send_hot_update).toHaveBeenCalledWith({ type: 'full-reload' });
+		expect(result).toEqual([]);
+	});
+
+	it('keeps self-accepting .ripple files on Vite HMR path', async () => {
+		const [plugin] = ripple({ excludeRippleExternalModules: true });
+		await plugin.configResolved?.({ root: '/workspace', command: 'serve' });
+
+		const transform_request = vi.fn().mockResolvedValue(undefined);
+		const get_ssr_modules = vi.fn();
+		const invalidate_ssr_module = vi.fn();
+		const send_hot_update = vi.fn();
+
+		const result = await plugin.hotUpdate.handler.call(
+			{
+				environment: {
+					name: 'client',
+					transformRequest: transform_request,
+					moduleGraph: {
+						getModuleById: vi.fn().mockReturnValue(undefined),
+						invalidateModule: vi.fn(),
+					},
+					hot: {
+						send: send_hot_update,
+					},
+				},
+			},
+			{
+				file: '/workspace/src/component.ripple',
+				modules: [{ id: 'client:component', isSelfAccepting: true }],
+				server: {
+					environments: {
+						ssr: {
+							moduleGraph: {
+								getModulesByFile: get_ssr_modules,
+								invalidateModule: invalidate_ssr_module,
+							},
+						},
+					},
+				},
+			},
+		);
+
+		expect(transform_request).toHaveBeenCalledWith('/src/component.ripple');
+		expect(get_ssr_modules).not.toHaveBeenCalled();
+		expect(invalidate_ssr_module).not.toHaveBeenCalled();
+		expect(send_hot_update).not.toHaveBeenCalled();
+		expect(result).toBeUndefined();
+	});
+});

package/types/index.d.ts

@@ -1,5 +1,8 @@
 export type Component<T = Record<string, any>> = (props: T) => void;
 
+/** Type for JSX children - accepts single child, multiple children, or no children */
+export type Children = Component | readonly Component[];
+
 export type CompatApi = {
 	createRoot: () => void;
 	createComponent: (node: any, children_fn: () => any) => void;
@@ -142,16 +145,21 @@ declare global {
 export function createRefKey(): symbol;
 
 // Base Tracked interface - all tracked values have a '#v' property containing the actual value
-export interface Tracked<V> {
+interface TrackedBase<V> {
 	'#v': V;
+	value: V;
 }
 
 // Augment Tracked to be callable when V is a Component
 // This allows <@Something /> to work in JSX when Something is Tracked<Component>
-export interface Tracked<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);`
+export type Tracked<V> = [V, Tracked<V>] & TrackedBase<V> & TrackedCallable<V>;
+
 // Helper type to infer component type from a function that returns a component
 // If T is a function returning a Component, extract the Component type itself, not the return type (void)
 export type InferComponent<T> = T extends () => infer R ? (R extends Component<any> ? R : T) : T;
@@ -159,10 +167,10 @@ export type InferComponent<T> = T extends () => infer R ? (R extends Component<a
 export type Props<K extends PropertyKey = any, V = unknown> = Record<K, V>;
 export type PropsWithExtras<T extends object> = Props & T & Record<string, unknown>;
 export type PropsWithChildren<T extends object = {}> = Expand<
-	Omit<T, 'children'> & { children: Component }
+	Omit<T, 'children'> & { children: Children }
 >;
 export type PropsWithChildrenOptional<T extends object = {}> = Expand<
-	Omit<T, 'children'> & { children?: Component }
+	Omit<T, 'children'> & { children?: Children }
 >;
 export type PropsNoChildren<T extends object = {}> = Expand<T>;
 
@@ -383,10 +391,10 @@ export const MediaQuery: MediaQueryConstructor;
 
 export function Portal<V = HTMLElement>({
 	target,
-	children: Component,
+	children,
 }: {
 	target: V;
-	children?: Component;
+	children?: Children;
 }): void;
 
 export type GetFunction<V> = () => V;