ripple 0.2.131 → 0.2.133

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.2.131",
+  "version": "0.2.133",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -81,6 +81,6 @@
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "ripple": "0.2.131"
+    "ripple": "0.2.133"
   }
 }

package/src/compiler/phases/1-parse/index.js

@@ -1,3 +1,4 @@
+// @ts-nocheck
 /** @import { Program } from 'estree' */
 /** @import {
  *   CommentWithLocation,
@@ -28,6 +29,14 @@ function convert_from_jsx(node) {
 	return node;
 }
 
+function isWhitespaceTextNode(node) {
+	if (!node || node.type !== 'Text') {
+		return false;
+	}
+	const value = typeof node.value === 'string' ? node.value : typeof node.raw === 'string' ? node.raw : '';
+	return /^\s*$/.test(value);
+}
+
 /**
  * Acorn parser plugin for Ripple syntax extensions
  * @param {RipplePluginConfig} [config] - Plugin configuration
@@ -42,6 +51,37 @@ function RipplePlugin(config) {
 		class RippleParser extends Parser {
 			/** @type {any[]} */
 			#path = [];
+			#commentContextId = 0;
+
+			#createCommentMetadata() {
+				if (this.#path.length === 0) {
+					return null;
+				}
+
+				const container = this.#path[this.#path.length - 1];
+				if (!container || container.type !== 'Element') {
+					return null;
+				}
+
+				const children = Array.isArray(container.children) ? container.children : [];
+				const hasMeaningfulChildren = children.some((child) => child && !isWhitespaceTextNode(child));
+
+				if (hasMeaningfulChildren) {
+					return null;
+				}
+
+				container.metadata ??= {};
+				if (container.metadata.commentContainerId === undefined) {
+					container.metadata.commentContainerId = ++this.#commentContextId;
+				}
+
+				return {
+					containerId: container.metadata.commentContainerId,
+					containerType: container.type,
+					childIndex: children.length,
+					beforeMeaningfulChild: !hasMeaningfulChildren,
+				};
+			}
 
 			/**
 			 * Helper method to get the element name from a JSX identifier or member expression
@@ -107,7 +147,8 @@ function RipplePlugin(config) {
 						// Inside nested functions (scopeStack.length >= 5), treat < as relational/generic operator
 						// At component top-level (scopeStack.length <= 4), apply JSX detection logic
 						// BUT: if the < is followed by /, it's a closing JSX tag, not a less-than operator
-						const nextChar = this.pos + 1 < this.input.length ? this.input.charCodeAt(this.pos + 1) : -1;
+						const nextChar =
+							this.pos + 1 < this.input.length ? this.input.charCodeAt(this.pos + 1) : -1;
 						const isClosingTag = nextChar === 47; // '/'
 
 						if (this.scopeStack.length >= 5 && !isClosingTag) {
@@ -169,15 +210,19 @@ function RipplePlugin(config) {
 
 						// Check if this is #Map or #Set
 						if (this.input.slice(this.pos, this.pos + 4) === '#Map') {
-							const charAfter = this.pos + 4 < this.input.length ? this.input.charCodeAt(this.pos + 4) : -1;
-							if (charAfter === 40) { // ( character
+							const charAfter =
+								this.pos + 4 < this.input.length ? this.input.charCodeAt(this.pos + 4) : -1;
+							if (charAfter === 40) {
+								// ( character
 								this.pos += 4; // consume '#Map'
 								return this.finishToken(tt.name, '#Map');
 							}
 						}
 						if (this.input.slice(this.pos, this.pos + 4) === '#Set') {
-							const charAfter = this.pos + 4 < this.input.length ? this.input.charCodeAt(this.pos + 4) : -1;
-							if (charAfter === 40) { // ( character
+							const charAfter =
+								this.pos + 4 < this.input.length ? this.input.charCodeAt(this.pos + 4) : -1;
+							if (charAfter === 40) {
+								// ( character
 								this.pos += 4; // consume '#Set'
 								return this.finishToken(tt.name, '#Set');
 							}
@@ -206,12 +251,18 @@ function RipplePlugin(config) {
 						// Check if this is an invalid #Identifier pattern
 						// Valid patterns: #[, #{, #Map(, #Set(, #server
 						// If we see # followed by an uppercase letter that isn't Map or Set, it's an error
-						if (nextChar >= 65 && nextChar <= 90) { // A-Z
+						if (nextChar >= 65 && nextChar <= 90) {
+							// A-Z
 							// Extract the identifier name
 							let identEnd = this.pos + 1;
 							while (identEnd < this.input.length) {
 								const ch = this.input.charCodeAt(identEnd);
-								if ((ch >= 65 && ch <= 90) || (ch >= 97 && ch <= 122) || (ch >= 48 && ch <= 57) || ch === 95) {
+								if (
+									(ch >= 65 && ch <= 90) ||
+									(ch >= 97 && ch <= 122) ||
+									(ch >= 48 && ch <= 57) ||
+									ch === 95
+								) {
 									// A-Z, a-z, 0-9, _
 									identEnd++;
 								} else {
@@ -220,7 +271,10 @@ function RipplePlugin(config) {
 							}
 							const identName = this.input.slice(this.pos + 1, identEnd);
 							if (identName !== 'Map' && identName !== 'Set') {
-								this.raise(this.pos, `Invalid tracked syntax '#${identName}'. Only #Map and #Set are currently supported using shorthand tracked syntax.`);
+								this.raise(
+									this.pos,
+									`Invalid tracked syntax '#${identName}'. Only #Map and #Set are currently supported using shorthand tracked syntax.`,
+								);
 							}
 						}
 					}
@@ -940,9 +994,13 @@ function RipplePlugin(config) {
 				return this.finishNode(node, 'JSXIdentifier');
 			}
 
-			// Override jsx_parseElementName to support @ syntax in member expressions
 			jsx_parseElementName() {
-				let node = this.jsx_parseIdentifier();
+				let node = this.jsx_parseNamespacedName();
+
+				if (node.type === 'JSXNamespacedName') {
+					return node;
+				}
+
 				if (this.eat(tt.dot)) {
 					let memberExpr = this.startNodeAt(node.start, node.loc && node.loc.start);
 					memberExpr.object = node;
@@ -1019,11 +1077,15 @@ function RipplePlugin(config) {
 			}
 
 			jsx_readToken() {
+				const inside_tsx_compat = this.#path.findLast((n) => n.type === 'TsxCompat');
+				if (inside_tsx_compat) {
+					return super.jsx_readToken();
+				}
 				let out = '',
 					chunkStart = this.pos;
 				const tok = this.acornTypeScript.tokTypes;
 
-				for (;;) {
+				while (true) {
 					if (this.pos >= this.input.length) this.raise(this.start, 'Unterminated JSX contents');
 					let ch = this.input.charCodeAt(this.pos);
 
@@ -1061,6 +1123,7 @@ function RipplePlugin(config) {
 
 								// Call onComment if it exists
 								if (this.options.onComment) {
+									const metadata = this.#createCommentMetadata();
 									this.options.onComment(
 										false,
 										commentText,
@@ -1068,6 +1131,7 @@ function RipplePlugin(config) {
 										commentEnd,
 										startLoc,
 										endLoc,
+										metadata,
 									);
 								}
 
@@ -1098,6 +1162,7 @@ function RipplePlugin(config) {
 
 								// Call onComment if it exists
 								if (this.options.onComment) {
+									const metadata = this.#createCommentMetadata();
 									this.options.onComment(
 										true,
 										commentText,
@@ -1105,6 +1170,7 @@ function RipplePlugin(config) {
 										commentEnd,
 										startLoc,
 										endLoc,
+										metadata,
 									);
 								}
 
@@ -1178,10 +1244,29 @@ function RipplePlugin(config) {
 				element.start = position.index;
 				element.loc.start = position;
 				element.metadata = {};
-				element.type = 'Element';
-				this.#path.push(element);
 				element.children = [];
 				const open = this.jsx_parseOpeningElementAt();
+
+				// Check if this is a namespaced element (tsx:react)
+				const is_tsx_compat = open.name.type === 'JSXNamespacedName';
+
+				if (is_tsx_compat) {
+					element.type = 'TsxCompat';
+					element.kind = open.name.name.name; // e.g., "react" from "tsx:react"
+
+					if (open.selfClosing) {
+						const tagName = open.name.namespace.name + ':' + open.name.name.name;
+						this.raise(
+							open.start,
+							`TSX compatibility elements cannot be self-closing. '<${tagName} />' must have a closing tag '</${tagName}>'.`,
+						);
+					}
+				} else {
+					element.type = 'Element';
+				}
+
+				this.#path.push(element);
+
 				for (const attr of open.attributes) {
 					if (attr.type === 'JSXAttribute') {
 						attr.type = 'Attribute';
@@ -1195,14 +1280,18 @@ function RipplePlugin(config) {
 						}
 					}
 				}
-				if (open.name.type === 'JSXIdentifier') {
-					open.name.type = 'Identifier';
+
+				if (!is_tsx_compat) {
+					if (open.name.type === 'JSXIdentifier') {
+						open.name.type = 'Identifier';
+					}
+					element.id = convert_from_jsx(open.name);
+					element.selfClosing = open.selfClosing;
 				}
 
-				element.id = convert_from_jsx(open.name);
 				element.attributes = open.attributes;
-				element.selfClosing = open.selfClosing;
-				element.metadata = {};
+				element.metadata ??= {};
+				element.metadata.commentContainerId = ++this.#commentContextId;
 
 				if (element.selfClosing) {
 					this.#path.pop();
@@ -1295,10 +1384,40 @@ function RipplePlugin(config) {
 						this.parseTemplateBody(element.children);
 						this.exitScope();
 
-						// Check if this element was properly closed
-						// If we reach here and this element is still in the path, it means it was never closed
-						if (this.#path[this.#path.length - 1] === element) {
+						if (element.type === 'TsxCompat') {
+							this.#path.pop();
+
+							const raise_error = () => {
+								this.raise(this.start, `Expected closing tag '</tsx:${element.kind}>'`);
+							};
+
+							this.next();
+							// we should expect to see </tsx:kind>
+							if (this.value !== '/') {
+								raise_error();
+							}
+							this.next();
+							if (this.value !== 'tsx') {
+								raise_error();
+							}
+							this.next();
+							if (this.type.label !== ':') {
+								raise_error();
+							}
+							this.next();
+							if (this.value !== element.kind) {
+								raise_error();
+							}
+							this.next();
+							if (this.type.label !== 'jsxTagEnd') {
+								raise_error();
+							}
+							this.next();
+						} else if (this.#path[this.#path.length - 1] === element) {
+							// Check if this element was properly closed
+							// If we reach here and this element is still in the path, it means it was never closed
 							const tagName = this.getElementName(element.id);
+
 							this.raise(
 								this.start,
 								`Unclosed tag '<${tagName}>'. Expected '</${tagName}>' before end of component.`,
@@ -1314,13 +1433,14 @@ function RipplePlugin(config) {
 					}
 				}
 
-				this.finishNode(element, 'Element');
+				this.finishNode(element, element.type);
 				return element;
 			}
 
 			parseTemplateBody(body) {
-				var inside_func =
+				const inside_func =
 					this.context.some((n) => n.token === 'function') || this.scopeStack.length > 1;
+				const inside_tsx_compat = this.#path.findLast((n) => n.type === 'TsxCompat');
 
 				if (!inside_func) {
 					if (this.type.label === 'return') {
@@ -1334,6 +1454,19 @@ function RipplePlugin(config) {
 					}
 				}
 
+				if (inside_tsx_compat) {
+					this.exprAllowed = true;
+
+					while (true) {
+						const node = super.parseExpression();
+						body.push(node);
+
+						if (this.input.slice(this.pos, this.pos + 5) === '/tsx:') {
+							return;
+						}
+					}
+				}
+
 				if (this.type.label === '{') {
 					const node = this.jsx_parseExpressionContainer();
 					node.type = node.html ? 'Html' : 'Text';
@@ -1350,12 +1483,32 @@ function RipplePlugin(config) {
 
 						// Validate that the closing tag matches the opening tag
 						const currentElement = this.#path[this.#path.length - 1];
-						if (!currentElement || currentElement.type !== 'Element') {
+						if (
+							!currentElement ||
+							(currentElement.type !== 'Element' && currentElement.type !== 'TsxCompat')
+						) {
 							this.raise(this.start, 'Unexpected closing tag');
 						}
 
-						const openingTagName = this.getElementName(currentElement.id);
-						const closingTagName = this.getElementName(closingTag);
+						let openingTagName;
+						let closingTagName;
+
+						if (currentElement.type === 'TsxCompat') {
+							if (closingTag.type === 'JSXNamespacedName') {
+								openingTagName = 'tsx:' + currentElement.kind;
+								closingTagName = closingTag.namespace.name + ':' + closingTag.name.name;
+							} else {
+								openingTagName = 'tsx:' + currentElement.kind;
+								closingTagName = this.getElementName(closingTag);
+							}
+						} else {
+							// Regular Element node
+							openingTagName = this.getElementName(currentElement.id);
+							closingTagName =
+								closingTag.type === 'JSXNamespacedName'
+									? closingTag.namespace.name + ':' + closingTag.name.name
+									: this.getElementName(closingTag);
+						}
 
 						if (openingTagName !== closingTagName) {
 							this.raise(
@@ -1535,7 +1688,7 @@ function RipplePlugin(config) {
  */
 function get_comment_handlers(source, comments, index = 0) {
 	return {
-		onComment: (block, value, start, end, start_loc, end_loc) => {
+		onComment: (block, value, start, end, start_loc, end_loc, metadata) => {
 			if (block && /\n/.test(value)) {
 				let a = start;
 				while (a > 0 && source[a - 1] !== '\n') a -= 1;
@@ -1556,6 +1709,7 @@ function get_comment_handlers(source, comments, index = 0) {
 					start: /** @type {import('acorn').Position} */ (start_loc),
 					end: /** @type {import('acorn').Position} */ (end_loc),
 				},
+				context: metadata ?? null,
 			});
 		},
 		add_comments: (ast) => {
@@ -1563,14 +1717,41 @@ function get_comment_handlers(source, comments, index = 0) {
 
 			comments = comments
 				.filter((comment) => comment.start >= index)
-				.map(({ type, value, start, end, loc }) => ({ type, value, start, end, loc }));
+				.map(({ type, value, start, end, loc, context }) => ({ type, value, start, end, loc, context }));
 
 			walk(ast, null, {
 				_(node, { next, path }) {
 					let comment;
 
+						const metadata = /** @type {{ commentContainerId?: number, elementLeadingComments?: CommentWithLocation[] }} */ (node?.metadata);
+
+						if (metadata && metadata.commentContainerId !== undefined) {
+							while (
+								comments[0] &&
+								comments[0].context &&
+								comments[0].context.containerId === metadata.commentContainerId &&
+								comments[0].context.beforeMeaningfulChild
+							) {
+								const elementComment = /** @type {CommentWithLocation & { context?: any }} */ (comments.shift());
+								(metadata.elementLeadingComments ||= []).push(elementComment);
+							}
+						}
+
 					while (comments[0] && comments[0].start < node.start) {
 						comment = /** @type {CommentWithLocation} */ (comments.shift());
+						if (comment.loc) {
+							const ancestorElements = path
+								.filter((ancestor) => ancestor && ancestor.type === 'Element' && ancestor.loc)
+								.sort((a, b) => a.loc.start.line - b.loc.start.line);
+
+							const targetAncestor = ancestorElements.find((ancestor) => comment.loc.start.line < ancestor.loc.start.line);
+
+							if (targetAncestor) {
+								targetAncestor.metadata ??= {};
+								(targetAncestor.metadata.elementLeadingComments ||= []).push(comment);
+								continue;
+							}
+						}
 						(node.leadingComments ||= []).push(comment);
 					}
 
@@ -1584,6 +1765,14 @@ function get_comment_handlers(source, comments, index = 0) {
 								return;
 							}
 						}
+						// Handle empty Element nodes the same way as empty BlockStatements
+						if (node.type === 'Element' && (!node.children || node.children.length === 0)) {
+							if (comments[0].start < node.end && comments[0].end < node.end) {
+								comment = /** @type {CommentWithLocation} */ (comments.shift());
+								(node.innerComments ||= []).push(comment);
+								return;
+							}
+						}
 						const parent = /** @type {any} */ (path.at(-1));
 
 						if (parent === undefined || node.end !== parent.end) {

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

@@ -575,13 +575,17 @@ const visitors = {
 	},
 
 	JSXElement(node, context) {
-		{
-			error(
-				'Elements cannot be used as generic expressions, only as statements within a component',
-				context.state.analysis.module.filename,
-				node,
-			);
+		const inside_tsx_compat = context.path.some((n) => n.type === 'TsxCompat');
+
+		if (inside_tsx_compat) {
+			return context.next();
 		}
+		error(
+			'Elements cannot be used as generic expressions, only as statements within a component',
+			context.state.analysis.module.filename,
+			node,
+		);
+
 	},
 
 	Element(node, context) {

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

@@ -150,6 +150,21 @@ function visit_title_element(node, context) {
 	}
 }
 
+/**
+ * @param {string} name
+ * @param {any} context
+ * @returns {string}
+ */
+function import_from_ripple_if_needed(name, context) {
+	const alias = context.state.ripple_user_imports?.get?.(name);
+
+	if (!alias && !context.state.imports.has(`import { ${name} } from 'ripple'`)) {
+		context.state.imports.add(`import { ${name} } from 'ripple'`);
+	}
+
+	return alias ?? name;
+}
+
 const visitors = {
 	_: function set_scope(node, { next, state }) {
 		const scope = state.scopes.get(node);
@@ -369,12 +384,10 @@ const visitors = {
 
 	TrackedArrayExpression(node, context) {
 		if (context.state.to_ts) {
-			if (!context.state.imports.has(`import { TrackedArray } from 'ripple'`)) {
-				context.state.imports.add(`import { TrackedArray } from 'ripple'`);
-			}
+			const arrayAlias = import_from_ripple_if_needed("TrackedArray", context);
 
 			return b.call(
-				b.member(b.id('TrackedArray'), b.id('from')),
+				b.member(b.id(arrayAlias), b.id('from')),
 				b.array(node.elements.map((el) => context.visit(el))),
 			);
 		}
@@ -388,12 +401,10 @@ const visitors = {
 
 	TrackedObjectExpression(node, context) {
 		if (context.state.to_ts) {
-			if (!context.state.imports.has(`import { TrackedObject } from 'ripple'`)) {
-				context.state.imports.add(`import { TrackedObject } from 'ripple'`);
-			}
+			const objectAlias = import_from_ripple_if_needed("TrackedObject", context);
 
 			return b.new(
-				b.id('TrackedObject'),
+				b.id(objectAlias),
 				b.object(node.properties.map((prop) => context.visit(prop))),
 			);
 		}
@@ -407,11 +418,9 @@ const visitors = {
 
 	TrackedMapExpression(node, context) {
 		if (context.state.to_ts) {
-			if (!context.state.imports.has(`import { TrackedMap } from 'ripple'`)) {
-				context.state.imports.add(`import { TrackedMap } from 'ripple'`);
-			}
+			const mapAlias = import_from_ripple_if_needed('TrackedMap', context);
 
-			const calleeId = b.id('TrackedMap');
+			const calleeId = b.id(mapAlias);
 			// Preserve location from original node for Volar mapping
 			calleeId.loc = node.loc;
 			// Add metadata for Volar mapping - map "TrackedMap" identifier to "#Map" in source
@@ -428,11 +437,9 @@ const visitors = {
 
 	TrackedSetExpression(node, context) {
 		if (context.state.to_ts) {
-			if (!context.state.imports.has(`import { TrackedSet } from 'ripple'`)) {
-				context.state.imports.add(`import { TrackedSet } from 'ripple'`);
-			}
+			const setAlias = import_from_ripple_if_needed('TrackedSet', context);
 
-			const calleeId = b.id('TrackedSet');
+			const calleeId = b.id(setAlias);
 			// Preserve location from original node for Volar mapping
 			calleeId.loc = node.loc;
 			// Add metadata for Volar mapping - map "TrackedSet" identifier to "#Set" in source
@@ -541,6 +548,84 @@ const visitors = {
 		return visit_function(node, context);
 	},
 
+	JSXText(node, context) {
+		return b.literal(node.value + '');
+	},
+
+	JSXIdentifier(node, context) {
+		return b.id(node.name);
+	},
+
+	JSXElement(node, context) {
+		const name = node.openingElement.name;
+		const attributes = node.openingElement.attributes;
+		const normalized_children = node.children.filter((child) => {
+			return child.type !== 'JSXText' || child.value.trim() !== '';
+		});
+
+		const props = b.object(
+			attributes.map((attr) => {
+				if (attr.type === 'JSXAttribute') {
+					return b.prop('init', context.visit(attr.name), context.visit(attr.value));
+				} else if (attr.type === 'JSXSpreadAttribute') {
+					return b.spread(context.visit(attr.argument));
+				}
+			}),
+		);
+
+		if (normalize_children.length > 0) {
+			props.properties.push(
+				b.prop(
+					'init',
+					b.id('children'),
+					normalized_children.length === 1
+						? context.visit(normalized_children[0])
+						: b.array(normalized_children.map((child) => context.visit(child))),
+				),
+			);
+		}
+
+		return b.call(
+			'_$_jsx',
+			name.type === 'JSXIdentifier' && name.name[0].toLowerCase() === name.name[0]
+				? b.literal(name.name)
+				: context.visit(name),
+			props,
+		);
+	},
+
+	TsxCompat(node, context) {
+		const { state, visit } = context;
+
+		state.template.push('<!>');
+
+		const normalized_children = node.children.filter((child) => {
+			return child.type !== 'JSXText' || child.value.trim() !== '';
+		});
+		const needs_fragment = normalized_children.length !== 1;
+		const id = state.flush_node();
+		const children_fn = b.arrow(
+			[b.id('__compat')],
+			needs_fragment
+				? b.call(
+						'__compat._jsxs',
+						b.id('__compat.Fragment'),
+						b.object([
+							b.prop(
+								'init',
+								b.id('children'),
+								b.array(normalized_children.map((child) => visit(child, state))),
+							),
+						]),
+					)
+				: visit(normalized_children[0], state),
+		);
+
+		context.state.init.push(
+			b.stmt(b.call('_$_.tsx_compat', b.literal(node.kind), id, children_fn)),
+		);
+	},
+
 	Element(node, context) {
 		const { state, visit } = context;
 
@@ -568,9 +653,10 @@ const visitors = {
 
 		const handle_static_attr = (name, value) => {
 			const attr_value = b.literal(
-				` ${name}${is_boolean_attribute(name) && value === true
-					? ''
-					: `="${value === true ? '' : escape_html(value, true)}"`
+				` ${name}${
+					is_boolean_attribute(name) && value === true
+						? ''
+						: `="${value === true ? '' : escape_html(value, true)}"`
 				}`,
 			);
 
@@ -903,8 +989,11 @@ const visitors = {
 			}
 
 			if (node.metadata.scoped && state.component.css) {
-				const hasClassAttr = node.attributes.some(attr =>
-					attr.type === 'Attribute' && attr.name.type === 'Identifier' && attr.name.name === 'class'
+				const hasClassAttr = node.attributes.some(
+					(attr) =>
+						attr.type === 'Attribute' &&
+						attr.name.type === 'Identifier' &&
+						attr.name.name === 'class',
 				);
 				if (!hasClassAttr) {
 					const name = is_spreading ? '#class' : 'class';
@@ -1061,10 +1150,10 @@ const visitors = {
 				operator === '='
 					? context.visit(right)
 					: b.binary(
-						operator === '+=' ? '+' : operator === '-=' ? '-' : operator === '*=' ? '*' : '/',
-							/** @type {Expression} */(context.visit(left)),
-							/** @type {Expression} */(context.visit(right)),
-					),
+							operator === '+=' ? '+' : operator === '-=' ? '-' : operator === '*=' ? '*' : '/',
+							/** @type {Expression} */ (context.visit(left)),
+							/** @type {Expression} */ (context.visit(right)),
+						),
 				b.id('__block'),
 			);
 		}
@@ -1080,12 +1169,12 @@ const visitors = {
 				operator === '='
 					? context.visit(right)
 					: b.binary(
-						operator === '+=' ? '+' : operator === '-=' ? '-' : operator === '*=' ? '*' : '/',
-							/** @type {Expression} */(
-							context.visit(left, { ...context.state, metadata: { tracking: false } })
+							operator === '+=' ? '+' : operator === '-=' ? '-' : operator === '*=' ? '*' : '/',
+							/** @type {Expression} */ (
+								context.visit(left, { ...context.state, metadata: { tracking: false } })
+							),
+							/** @type {Expression} */ (context.visit(right)),
 						),
-							/** @type {Expression} */(context.visit(right)),
-					),
 				b.id('__block'),
 			);
 		}
@@ -1292,12 +1381,12 @@ const visitors = {
 								b.stmt(b.call(b.id('__render'), b.id(consequent_id))),
 								alternate_id
 									? b.stmt(
-										b.call(
-											b.id('__render'),
-											b.id(alternate_id),
-											node.alternate ? b.literal(false) : undefined,
-										),
-									)
+											b.call(
+												b.id('__render'),
+												b.id(alternate_id),
+												node.alternate ? b.literal(false) : undefined,
+											),
+										)
 									: undefined,
 							),
 						]),
@@ -1374,9 +1463,9 @@ const visitors = {
 					node.handler === null
 						? b.literal(null)
 						: b.arrow(
-							[b.id('__anchor'), ...(node.handler.param ? [node.handler.param] : [])],
-							b.block(transform_body(node.handler.body.body, context)),
-						),
+								[b.id('__anchor'), ...(node.handler.param ? [node.handler.param] : [])],
+								b.block(transform_body(node.handler.body.body, context)),
+							),
 					node.pending === null
 						? undefined
 						: b.arrow([b.id('__anchor')], b.block(transform_body(node.pending.body, context))),
@@ -1502,7 +1591,7 @@ function join_template(items) {
 	}
 
 	for (const quasi of template.quasis) {
-		quasi.value.raw = sanitize_template_string(/** @type {string} */(quasi.value.cooked));
+		quasi.value.raw = sanitize_template_string(/** @type {string} */ (quasi.value.cooked));
 	}
 
 	quasi.tail = true;
@@ -1555,12 +1644,12 @@ function transform_ts_child(node, context) {
 				const argument = visit(attr.argument, { ...state, metadata });
 				return b.jsx_spread_attribute(argument);
 			} else if (attr.type === 'RefAttribute') {
-				if (!context.state.imports.has(`import { createRefKey } from 'ripple'`)) {
-					context.state.imports.add(`import { createRefKey } from 'ripple'`);
-				}
+				const createRefKeyAlias = import_from_ripple_if_needed('createRefKey', context);
 				const metadata = { await: false };
 				const argument = visit(attr.argument, { ...state, metadata });
-				const wrapper = b.object([b.prop('init', b.call('createRefKey'), argument, true)]);
+				const wrapper = b.object(
+					[b.prop('init', b.call(createRefKeyAlias), argument, true)]
+				);
 				return b.jsx_spread_attribute(wrapper);
 			}
 		});
@@ -1841,6 +1930,8 @@ function transform_children(children, context) {
 				visit(node, { ...state, flush_node, namespace: state.namespace });
 			} else if (node.type === 'HeadElement') {
 				visit(node, { ...state, flush_node, namespace: state.namespace });
+			} else if (node.type === 'TsxCompat') {
+				visit(node, { ...state, flush_node, namespace: state.namespace });
 			} else if (node.type === 'Html') {
 				const metadata = { tracking: false, await: false };
 				const expression = visit(node.expression, { ...state, metadata });
@@ -1966,9 +2057,75 @@ function transform_body(body, { visit, state }) {
 	return [...body_state.setup, ...body_state.init, ...body_state.final];
 }
 
+/**
+ * Create a TSX language handler with enhanced TypeScript support
+ * @returns {Object} TSX language handler with TypeScript return type support
+ */
+function create_tsx_with_typescript_support() {
+	const base_tsx = tsx();
+
+	// Override the ArrowFunctionExpression handler to support TypeScript return types
+	return {
+		...base_tsx,
+		ArrowFunctionExpression(node, context) {
+			if (node.async) context.write('async ');
+
+			context.write('(');
+			// Visit each parameter
+			for (let i = 0; i < node.params.length; i++) {
+				if (i > 0) context.write(', ');
+				context.visit(node.params[i]);
+			}
+			context.write(')');
+
+			// Add TypeScript return type annotation if present
+			if (node.returnType) {
+				context.visit(node.returnType);
+			}
+
+			context.write(' => ');
+
+			if (
+				node.body.type === 'ObjectExpression' ||
+				(node.body.type === 'AssignmentExpression' && node.body.left.type === 'ObjectPattern') ||
+				(node.body.type === 'LogicalExpression' && node.body.left.type === 'ObjectExpression') ||
+				(node.body.type === 'ConditionalExpression' && node.body.test.type === 'ObjectExpression')
+			) {
+				context.write('(');
+				context.visit(node.body);
+				context.write(')');
+			} else {
+				context.visit(node.body);
+			}
+		}
+	};
+}
+
 export function transform_client(filename, source, analysis, to_ts) {
+	/**
+	 * User's named imports from 'ripple' so we can reuse them in TS output
+	 * when transforming shorthand syntax. E.g., if the user has already imported
+	 * TrackedArray, we want to reuse that import instead of importing it again
+	 * if we encounter `#[]`. It's a Map of export name to local name in case the
+	 * user renamed something when importing.
+	 * @type {Map<string, string>}
+	 */
+	const ripple_user_imports = new Map(); // exported -> local
+	if (analysis && analysis.ast && Array.isArray(analysis.ast.body)) {
+		for (const stmt of analysis.ast.body) {
+			if (stmt && stmt.type === 'ImportDeclaration' && stmt.source && stmt.source.value === 'ripple') {
+				for (const spec of stmt.specifiers || []) {
+					if (spec.type === 'ImportSpecifier' && spec.imported && spec.local) {
+						ripple_user_imports.set(spec.imported.name, spec.local.name);
+					}
+				}
+			}
+		}
+	}
+
 	const state = {
 		imports: new Set(),
+		ripple_user_imports,
 		events: new Set(),
 		template: null,
 		hoisted: [],
@@ -1985,7 +2142,7 @@ export function transform_client(filename, source, analysis, to_ts) {
 	};
 
 	const program = /** @type {Program} */ (
-		walk(/** @type {Node} */(analysis.ast), { ...state, namespace: 'html' }, visitors)
+		walk(/** @type {Node} */ (analysis.ast), { ...state, namespace: 'html' }, visitors)
 	);
 
 	for (const hoisted of state.hoisted) {
@@ -2004,7 +2161,7 @@ export function transform_client(filename, source, analysis, to_ts) {
 		);
 	}
 
-	const js = print(program, tsx(), {
+	const js = print(program, to_ts ? create_tsx_with_typescript_support() : tsx(), {
 		sourceMapContent: source,
 		sourceMapSource: path.basename(filename),
 	});

package/src/compiler/phases/3-transform/segments.js

@@ -254,6 +254,16 @@ export function convert_source_map_to_mappings(ast, source, generated_code, sour
 					visit(node.local);
 				}
 				return;
+			} else if (node.type === 'ExportSpecifier') {
+				// If local and exported are the same, only visit local to avoid duplicates
+				// Otherwise visit both in order
+				if (node.local && node.exported && node.local.name !== node.exported.name) {
+					visit(node.local);
+					visit(node.exported);
+				} else if (node.local) {
+					visit(node.local);
+				}
+				return;
 			} else if (node.type === 'ExportNamedDeclaration') {
 				if (node.specifiers && node.specifiers.length > 0) {
 					for (const specifier of node.specifiers) {

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

@@ -119,6 +119,18 @@ export interface Element extends Omit<Node, 'type'> {
 	metadata: any;
 }
 
+/**
+ * TSX compatibility node for elements with namespaces like <tsx:react>
+ * Note: TsxCompat elements cannot be self-closing and must have a closing tag
+ */
+export interface TsxCompat extends Omit<Node, 'type'> {
+	type: 'TsxCompat';
+	kind: string;
+	attributes: Array<Attribute | SpreadAttribute>;
+	children: Node[];
+	metadata: any;
+}
+
 /**
  * Ripple attribute node
  */

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

@@ -0,0 +1,8 @@
+/**
+ * @param {string} kind 
+ * @param {Node} node 
+ * @param {() => JSX.Element[]} children_fn 
+ */
+export function tsx_compat(kind, node, children_fn) {
+  throw new Error("Not implemented yet");
+}

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

@@ -76,3 +76,5 @@ export { script } from './script.js';
 export { html } from './html.js';
 
 export { rpc } from './rpc.js';
+
+export { tsx_compat } from './compat.js';

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

@@ -1,4 +1,16 @@
-import { parse, compile } from 'ripple/compiler';
+import { parse, compile, compile_to_volar_mappings } from 'ripple/compiler';
+
+function count_occurrences(string, subString) {
+	let count = 0;
+	let pos = string.indexOf(subString);
+
+	while (pos !== -1) {
+		count++;
+		pos = string.indexOf(subString, pos + subString.length);
+	}
+
+	return count;
+}
 
 describe('compiler > basics', () => {
 	it('parses style content correctly', () => {
@@ -200,4 +212,108 @@ describe('compiler > basics', () => {
 
 		const result = compile(source, 'test.ripple', { mode: 'client' });
 	});
+
+	it("doesn't add duplicate imports when encountering shorthand syntax", () => {
+		const source = `
+import {
+	TrackedArray,
+	TrackedObject,
+	TrackedSet,
+	TrackedMap,
+	createRefKey,
+} from 'ripple';
+
+component App() {
+	const items = #[1, 2, 3];
+	const obj = #{ a: 1, b: 2, c: 3 };
+	const set = #Set([1, 2, 3]);
+	const map = #Map([['a', 1], ['b', 2], ['c', 3]]);
+
+	<div {ref () => {}} />
+}
+`;
+		const result = compile_to_volar_mappings(source, 'test.ripple').code;
+
+		expect(count_occurrences(result, "TrackedArray")).toBe(2);
+		expect(count_occurrences(result, "TrackedObject")).toBe(2);
+		expect(count_occurrences(result, "TrackedSet")).toBe(2);
+		expect(count_occurrences(result, "TrackedMap")).toBe(2);
+		expect(count_occurrences(result, "createRefKey")).toBe(2);
+	});
+
+	it("doesn't add duplicate imports for renamed imports when encountering shorthand syntax", () => {
+		const source = `
+import {
+	TrackedArray as TA,
+	TrackedObject as TO,
+	TrackedSet as TS,
+	TrackedMap as TM,
+	createRefKey as crk,
+} from 'ripple';
+
+component App() {
+	const items = #[1, 2, 3];
+	const obj = #{ a: 1, b: 2, c: 3 };
+	const set = #Set([1, 2, 3]);
+	const map = #Map([['a', 1], ['b', 2], ['c', 3]]);
+
+	<div {ref () => {}} />
+}
+`;
+		const result = compile_to_volar_mappings(source, 'test.ripple').code;
+
+		expect(count_occurrences(result, "TrackedArray")).toBe(1);
+		expect(count_occurrences(result, "TA")).toBe(2);
+		expect(count_occurrences(result, "TrackedObject")).toBe(1);
+		expect(count_occurrences(result, "TO")).toBe(2);
+		expect(count_occurrences(result, "TrackedSet")).toBe(1);
+		expect(count_occurrences(result, "TS")).toBe(2);
+		expect(count_occurrences(result, "TrackedMap")).toBe(1);
+		expect(count_occurrences(result, "TM")).toBe(2);
+		expect(count_occurrences(result, "createRefKey")).toBe(1);
+		expect(count_occurrences(result, "crk")).toBe(2);
+	});
+
+	it('adds missing imports for shorthand syntax', () => {
+		const source = `
+component App() {
+	const items = #[1, 2, 3];
+	const obj = #{ a: 1, b: 2, c: 3 };
+	const set = #Set([1, 2, 3]);
+	const map = #Map([['a', 1], ['b', 2], ['c', 3]]);
+
+	<div {ref () => {}} />
+}
+`;
+		const result = compile_to_volar_mappings(source, 'test.ripple').code;
+
+		expect(count_occurrences(result, "TrackedArray")).toBe(2);
+		expect(count_occurrences(result, "TrackedObject")).toBe(2);
+		expect(count_occurrences(result, "TrackedSet")).toBe(2);
+		expect(count_occurrences(result, "TrackedMap")).toBe(2);
+		expect(count_occurrences(result, "createRefKey")).toBe(2);
+	});
+
+	it('only adds missing imports for shorthand syntax, reusing existing ones', () => {
+		const source = `
+import { TrackedArray, TrackedMap, createRefKey as crk } from 'ripple';
+
+component App() {
+	const items = #[1, 2, 3];
+	const obj = #{ a: 1, b: 2, c: 3 };
+	const set = #Set([1, 2, 3]);
+	const map = #Map([['a', 1], ['b', 2], ['c', 3]]);
+
+	<div {ref () => {}} />
+}
+`;
+		const result = compile_to_volar_mappings(source, 'test.ripple').code;
+
+		expect(count_occurrences(result, "TrackedArray")).toBe(2);
+		expect(count_occurrences(result, "TrackedObject")).toBe(2);
+		expect(count_occurrences(result, "TrackedSet")).toBe(2);
+		expect(count_occurrences(result, "TrackedMap")).toBe(2);
+		expect(count_occurrences(result, "createRefKey")).toBe(1);
+		expect(count_occurrences(result, "crk")).toBe(2);
+	});
 });