@tsrx/core 0.0.4 → 0.0.5

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "repository": {
     "type": "git",

package/src/index.js

@@ -132,7 +132,29 @@ export { escape } from './utils/escaping.js';
 
 // Transform
 export { render_stylesheets as renderStylesheets } from './transform/stylesheet.js';
-export { convert_source_map_to_mappings as convertSourceMapToMappings } from './transform/segments.js';
+export {
+	prepare_stylesheet_for_render as prepareStylesheetForRender,
+	is_style_element as isStyleElement,
+	is_composite_element as isCompositeElement,
+	annotate_with_hash as annotateWithHash,
+	annotate_component_with_hash as annotateComponentWithHash,
+	add_hash_class as addHashClass,
+} from './transform/scoping.js';
+export {
+	convert_source_map_to_mappings as convertSourceMapToMappings,
+	create_volar_mappings_result as createVolarMappingsResult,
+	dedupe_mappings as dedupeMappings,
+	serialize_mapping_value as serializeMappingValue,
+} from './transform/segments.js';
+export {
+	create_lazy_context as createLazyContext,
+	collect_lazy_bindings as collectLazyBindings,
+	collect_lazy_bindings_from_component as collectLazyBindingsFromComponent,
+	collect_lazy_bindings_from_statements as collectLazyBindingsFromStatements,
+	preallocate_lazy_ids as preallocateLazyIds,
+	apply_lazy_transforms as applyLazyTransforms,
+	replace_lazy_params as replaceLazyParams,
+} from './transform/lazy.js';
 
 // Analyze
 export { analyze_css as analyzeCss } from './analyze/css-analyze.js';

package/src/parse/index.js

@@ -110,6 +110,68 @@ export function isWhitespaceTextNode(node) {
 	return false;
 }
 
+/**
+ * @type {AcornPlugin}
+ */
+function elementTemplateClosingTagPlugin(Base) {
+	const jsxTagStart = /** @type {any} */ (Base).acornTypeScript?.tokTypes?.jsxTagStart;
+	if (!jsxTagStart) return Base;
+
+	/**
+	 * @param {any} parser
+	 */
+	function inElementTemplateBodyDirect(parser) {
+		const stack = parser.context;
+		const top = stack[stack.length - 1];
+		const below = stack[stack.length - 2];
+		return top && top.token === '{' && below && below.token === '<tag>...</tag>';
+	}
+
+	/**
+	 * @param {any} parser
+	 */
+	function inElementTemplateBodyAnywhere(parser) {
+		const stack = parser.context;
+		for (let i = 1; i < stack.length; i++) {
+			if (
+				stack[i] &&
+				stack[i].token === '{' &&
+				stack[i - 1] &&
+				stack[i - 1].token === '<tag>...</tag>'
+			) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	return class extends Base {
+		/** @param {number} code */
+		// @ts-ignore — extending acorn's Parser with internal hooks
+		getTokenFromCode(code) {
+			if (code === 60 /* '<' */ && !(/** @type {any} */ (this).inType)) {
+				const self = /** @type {any} */ (this);
+				const nextChar =
+					self.pos + 1 < self.input.length ? self.input.charCodeAt(self.pos + 1) : -1;
+				if (nextChar === 47 /* '/' */ && inElementTemplateBodyDirect(self)) {
+					++self.pos;
+					return self.finishToken(jsxTagStart);
+				}
+			}
+			// @ts-ignore — super dispatches to next layer in the plugin chain
+			return super.getTokenFromCode(code);
+		}
+
+		// @ts-ignore — extending acorn's Parser with internal hooks
+		canInsertSemicolon() {
+			const self = /** @type {any} */ (this);
+			if (self.type === jsxTagStart && inElementTemplateBodyAnywhere(self)) return true;
+			// @ts-ignore
+			return super.canInsertSemicolon();
+		}
+	};
+}
+
 /**
  * Create a parser by composing Acorn with TypeScript/JSX support and optional framework plugins.
  *
@@ -125,6 +187,7 @@ export function createParser(...plugins) {
 			acorn.Parser.extend(
 				tsPlugin({ jsx: true }),
 				...plugins.map((p) => /** @type {AcornPlugin} */ (/** @type {unknown} */ (p))),
+				elementTemplateClosingTagPlugin,
 			)
 		)
 	);
@@ -151,7 +214,7 @@ export function createParser(...plugins) {
 				allowReturnOutsideFunction: true,
 				locations: true,
 				onComment,
-				rippleOptions: {
+				tsrxOptions: {
 					filename,
 					errors: options?.errors ?? [],
 					loose: options?.loose || false,

package/src/parse/style.js

@@ -119,7 +119,7 @@ export function parse_style(content, options) {
 
 	return {
 		source: content,
-		hash: `ripple-${hash(content)}`,
+		hash: `tsrx-${hash(content)}`,
 		type: 'StyleSheet',
 		children: read_body(parser),
 		start: 0,

package/src/plugin.js

@@ -51,9 +51,10 @@ export function TSRXPlugin(config) {
 			 */
 			constructor(options, input) {
 				super(options, input);
-				this.#loose = options?.rippleOptions.loose === true;
-				this.#errors = options?.rippleOptions.errors;
-				this.#filename = options?.rippleOptions.filename || null;
+				const tsrx_options = options?.tsrxOptions ?? options?.rippleOptions;
+				this.#loose = tsrx_options?.loose === true;
+				this.#errors = tsrx_options?.errors;
+				this.#filename = tsrx_options?.filename || null;
 			}
 
 			/**

package/src/source-map-utils.js

@@ -286,7 +286,7 @@ export function build_line_offsets(text) {
  * @param {number} [gen_max_len]
  * @returns {CodeMapping | Error}
  */
-function maybe_get_mapping_from_node(
+export function maybe_get_mapping_from_node(
 	node,
 	src_to_gen_map,
 	gen_line_offsets,

package/src/transform/lazy.js

@@ -0,0 +1,664 @@
+/** @import * as AST from 'estree' */
+
+/**
+ * Lazy destructuring transform — framework-agnostic.
+ *
+ * Shared between `@tsrx/react` and `@tsrx/solid`. Walks an AST and rewrites
+ * references to names introduced by `&{ ... }` / `&[ ... ]` destructuring
+ * patterns into member-expression accesses on a generated source identifier.
+ *
+ * Usage:
+ *   1. Create a context with `createLazyContext()` (or provide any object with
+ *      a `lazy_next_id: number` field).
+ *   2. Run `preallocateLazyIds(root, context)` once over the full program to
+ *      assign stable `metadata.lazy_id` values to every lazy pattern.
+ *   3. For each function/component scope, collect bindings with
+ *      `collectLazyBindingsFromComponent(params, body, context)` and pass the
+ *      resulting map into `applyLazyTransforms(body, map)`.
+ *   4. If a component declares lazy params, pass its params through
+ *      `replaceLazyParams(params)` before emitting.
+ *
+ * The transform is purely AST-to-AST and has no framework-specific knowledge.
+ */
+
+/**
+ * @typedef {{ lazy_next_id: number }} LazyContext
+ */
+
+/**
+ * @typedef {{ source_name: string, read: () => any }} LazyBinding
+ */
+
+/**
+ * Create a fresh lazy-id allocation context.
+ *
+ * @returns {LazyContext}
+ */
+export function create_lazy_context() {
+	return { lazy_next_id: 0 };
+}
+
+/**
+ * @param {LazyContext} context
+ * @returns {string}
+ */
+function generate_lazy_id(context) {
+	return `__lazy${context.lazy_next_id++}`;
+}
+
+/**
+ * @param {string} name
+ * @returns {any}
+ */
+function create_generated_identifier(name) {
+	return /** @type {any} */ ({ type: 'Identifier', name, metadata: { path: [] } });
+}
+
+/**
+ * Collect lazy bindings from a destructuring pattern.
+ *
+ * For `&{ name, age }` on source `S`, maps `name` → `S.name`, `age` → `S.age`.
+ * For `&[a, b]` on source `S`, maps `a` → `S[0]`, `b` → `S[1]`. Handles nested
+ * `AssignmentPattern` (default values); skips `RestElement`.
+ *
+ * @param {any} pattern
+ * @param {string} source_name
+ * @param {Map<string, LazyBinding>} lazy_bindings
+ */
+export function collect_lazy_bindings(pattern, source_name, lazy_bindings) {
+	if (pattern.type === 'ObjectPattern') {
+		for (const prop of pattern.properties || []) {
+			if (prop.type === 'RestElement') continue;
+			const value = prop.value;
+			const actual = value.type === 'AssignmentPattern' ? value.left : value;
+			if (actual.type === 'Identifier') {
+				const key = prop.key;
+				const computed = prop.computed || key.type !== 'Identifier';
+				lazy_bindings.set(actual.name, {
+					source_name,
+					read: () => ({
+						type: 'MemberExpression',
+						object: create_generated_identifier(source_name),
+						property: computed
+							? { ...key }
+							: { type: 'Identifier', name: key.name, metadata: { path: [] } },
+						computed,
+						optional: false,
+						metadata: { path: [] },
+					}),
+				});
+			}
+		}
+	} else if (pattern.type === 'ArrayPattern') {
+		for (let i = 0; i < (pattern.elements || []).length; i++) {
+			const element = pattern.elements[i];
+			if (!element) continue;
+			if (element.type === 'RestElement') continue;
+			const actual = element.type === 'AssignmentPattern' ? element.left : element;
+			if (actual.type === 'Identifier') {
+				const index = i;
+				lazy_bindings.set(actual.name, {
+					source_name,
+					read: () => ({
+						type: 'MemberExpression',
+						object: create_generated_identifier(source_name),
+						property: { type: 'Literal', value: index, raw: String(index), metadata: { path: [] } },
+						computed: true,
+						optional: false,
+						metadata: { path: [] },
+					}),
+				});
+			}
+		}
+	}
+}
+
+/**
+ * Collect lazy bindings from a component's params and top-level body declarations.
+ * Mutates each lazy pattern's `metadata.lazy_id` in place (idempotent if already set).
+ *
+ * @param {any[]} params
+ * @param {any[]} body
+ * @param {LazyContext} context
+ * @returns {Map<string, LazyBinding>}
+ */
+export function collect_lazy_bindings_from_component(params, body, context) {
+	/** @type {Map<string, LazyBinding>} */
+	const lazy_bindings = new Map();
+
+	for (const param of params) {
+		const pattern = param.type === 'AssignmentPattern' ? param.left : param;
+		if ((pattern.type === 'ObjectPattern' || pattern.type === 'ArrayPattern') && pattern.lazy) {
+			const lazy_name = pattern.metadata?.lazy_id || generate_lazy_id(context);
+			if (!pattern.metadata?.lazy_id) {
+				pattern.metadata = { ...pattern.metadata, lazy_id: lazy_name };
+			}
+			collect_lazy_bindings(pattern, lazy_name, lazy_bindings);
+		}
+	}
+
+	// VariableDeclaration lazy patterns already have their `lazy_id` assigned
+	// by `preallocate_lazy_ids` (run once over the whole program by the target
+	// transforms), so `collect_lazy_bindings_from_statements` handles them
+	// alongside the expression-statement assignment form.
+	collect_lazy_bindings_from_statements(body, lazy_bindings);
+
+	return lazy_bindings;
+}
+
+/**
+ * Collect lazy bindings from statements at the top level of a block. Reads
+ * already-allocated `lazy_id` values from pattern metadata. Handles both
+ * `let &[x] = ...` variable declarations and statement-level `&[x] = expr;`
+ * assignment expressions.
+ *
+ * @param {any[]} statements
+ * @param {Map<string, LazyBinding>} lazy_bindings
+ */
+export function collect_lazy_bindings_from_statements(statements, lazy_bindings) {
+	for (const stmt of statements || []) {
+		if (stmt.type === 'VariableDeclaration') {
+			for (const declarator of stmt.declarations || []) {
+				const pattern = declarator.id;
+				if (
+					(pattern?.type === 'ObjectPattern' || pattern?.type === 'ArrayPattern') &&
+					pattern.lazy &&
+					pattern.metadata?.lazy_id &&
+					!lazy_bindings_contains(lazy_bindings, pattern)
+				) {
+					collect_lazy_bindings(pattern, pattern.metadata.lazy_id, lazy_bindings);
+				}
+			}
+		} else if (
+			stmt.type === 'ExpressionStatement' &&
+			stmt.expression?.type === 'AssignmentExpression' &&
+			stmt.expression.operator === '=' &&
+			(stmt.expression.left?.type === 'ObjectPattern' ||
+				stmt.expression.left?.type === 'ArrayPattern') &&
+			stmt.expression.left.lazy &&
+			stmt.expression.left.metadata?.lazy_id
+		) {
+			collect_lazy_bindings(
+				stmt.expression.left,
+				stmt.expression.left.metadata.lazy_id,
+				lazy_bindings,
+			);
+		}
+	}
+}
+
+/**
+ * @param {Map<string, LazyBinding>} lazy_bindings
+ * @param {any} pattern
+ * @returns {boolean}
+ */
+function lazy_bindings_contains(lazy_bindings, pattern) {
+	if (pattern.type === 'ObjectPattern') {
+		for (const prop of pattern.properties || []) {
+			if (prop.type === 'RestElement') continue;
+			const value = prop.value;
+			const actual = value?.type === 'AssignmentPattern' ? value.left : value;
+			if (actual?.type === 'Identifier' && lazy_bindings.has(actual.name)) return true;
+		}
+	} else if (pattern.type === 'ArrayPattern') {
+		for (const element of pattern.elements || []) {
+			if (!element || element.type === 'RestElement') continue;
+			const actual = element.type === 'AssignmentPattern' ? element.left : element;
+			if (actual?.type === 'Identifier' && lazy_bindings.has(actual.name)) return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Walk the AST and pre-allocate `lazy_id` metadata on every lazy destructuring
+ * pattern: function/component params, variable declarator ids, and statement-level
+ * assignment LHS. Idempotent: skips patterns that already have a `lazy_id`.
+ *
+ * @param {any} root
+ * @param {LazyContext} context
+ */
+export function preallocate_lazy_ids(root, context) {
+	/** @param {any} pattern */
+	const assign_id = (pattern) => {
+		if (
+			(pattern?.type === 'ObjectPattern' || pattern?.type === 'ArrayPattern') &&
+			pattern.lazy &&
+			!pattern.metadata?.lazy_id
+		) {
+			pattern.metadata = {
+				...pattern.metadata,
+				lazy_id: generate_lazy_id(context),
+			};
+		}
+	};
+
+	/** @param {any} node */
+	const visit = (node) => {
+		if (!node || typeof node !== 'object') return;
+		if (Array.isArray(node)) {
+			for (const child of node) visit(child);
+			return;
+		}
+
+		if (
+			node.type === 'FunctionDeclaration' ||
+			node.type === 'FunctionExpression' ||
+			node.type === 'ArrowFunctionExpression' ||
+			node.type === 'Component'
+		) {
+			for (const param of node.params || []) {
+				assign_id(param?.type === 'AssignmentPattern' ? param.left : param);
+			}
+		}
+
+		if (node.type === 'VariableDeclarator') {
+			assign_id(node.id);
+		}
+
+		if (
+			node.type === 'ExpressionStatement' &&
+			node.expression?.type === 'AssignmentExpression' &&
+			node.expression.operator === '='
+		) {
+			assign_id(node.expression.left);
+		}
+
+		for (const key of Object.keys(node)) {
+			if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') continue;
+			visit(node[key]);
+		}
+	};
+
+	visit(root);
+}
+
+/**
+ * Recursively rewrite lazy-binding references in `node`.
+ *
+ * @param {any} node
+ * @param {Map<string, LazyBinding>} lazy_bindings
+ * @returns {any}
+ */
+export function apply_lazy_transforms(node, lazy_bindings) {
+	if (!node || typeof node !== 'object') return node;
+	if (Array.isArray(node)) return node.map((child) => apply_lazy_transforms(child, lazy_bindings));
+
+	if (
+		node.type === 'FunctionDeclaration' ||
+		node.type === 'FunctionExpression' ||
+		node.type === 'ArrowFunctionExpression'
+	) {
+		// Default parameter values are evaluated in the outer scope — transform them first.
+		let params_changed = false;
+		const new_params = (node.params || []).map((/** @type {any} */ param) => {
+			const transformed = transform_param_defaults(param, lazy_bindings);
+			if (transformed !== param) params_changed = true;
+			return transformed;
+		});
+
+		/** @type {Set<string>} */
+		const shadowed = new Set();
+		for (const param of node.params || []) {
+			collect_shadowed_names(param, lazy_bindings, shadowed);
+		}
+
+		const outer_minus_shadow =
+			shadowed.size > 0 ? remove_shadowed(lazy_bindings, shadowed) : lazy_bindings;
+
+		/** @type {Map<string, LazyBinding>} */
+		const own_bindings = new Map();
+		let had_lazy_param = false;
+		for (const param of node.params || []) {
+			const pattern = param?.type === 'AssignmentPattern' ? param.left : param;
+			if (
+				(pattern?.type === 'ObjectPattern' || pattern?.type === 'ArrayPattern') &&
+				pattern.lazy &&
+				pattern.metadata?.lazy_id
+			) {
+				had_lazy_param = true;
+				collect_lazy_bindings(pattern, pattern.metadata.lazy_id, own_bindings);
+			}
+		}
+
+		// Own bindings override any outer binding with the same name.
+		const inner_bindings =
+			own_bindings.size > 0
+				? new Map([...outer_minus_shadow, ...own_bindings])
+				: outer_minus_shadow;
+
+		if (inner_bindings.size === 0 && !params_changed && !had_lazy_param) return node;
+
+		const new_body =
+			inner_bindings.size > 0 ? apply_lazy_transforms(node.body, inner_bindings) : node.body;
+
+		const final_params_src = params_changed ? new_params : node.params;
+		const final_params = had_lazy_param ? replace_lazy_params(final_params_src) : final_params_src;
+
+		if (new_body !== node.body || final_params !== node.params) {
+			return { ...node, params: final_params, body: new_body };
+		}
+		return node;
+	}
+
+	if (node.type === 'BlockStatement' || node.type === 'Program') {
+		const block_bindings = collect_block_shadowed_names(node.body, lazy_bindings);
+		const after_shadow =
+			block_bindings.size > 0 ? remove_shadowed(lazy_bindings, block_bindings) : lazy_bindings;
+
+		/** @type {Map<string, LazyBinding>} */
+		const block_lazy = new Map();
+		collect_lazy_bindings_from_statements(node.body, block_lazy);
+
+		const effective_bindings =
+			block_lazy.size > 0 ? new Map([...after_shadow, ...block_lazy]) : after_shadow;
+
+		let changed = false;
+		const new_body = node.body.map((/** @type {any} */ stmt) => {
+			const transformed = apply_lazy_transforms(stmt, effective_bindings);
+			if (transformed !== stmt) changed = true;
+			return transformed;
+		});
+		return changed ? { ...node, body: new_body } : node;
+	}
+
+	if (node.type === 'CatchClause') {
+		/** @type {Set<string>} */
+		const shadowed = new Set();
+		if (node.param) collect_shadowed_names(node.param, lazy_bindings, shadowed);
+		const effective_bindings =
+			shadowed.size > 0 ? remove_shadowed(lazy_bindings, shadowed) : lazy_bindings;
+		const new_body = apply_lazy_transforms(node.body, effective_bindings);
+		if (new_body !== node.body) return { ...node, body: new_body };
+		return node;
+	}
+
+	if (node.type === 'ForStatement') {
+		/** @type {Set<string>} */
+		const shadowed = new Set();
+		if (node.init?.type === 'VariableDeclaration') {
+			for (const decl of node.init.declarations) {
+				if (decl.id) collect_shadowed_names(decl.id, lazy_bindings, shadowed);
+			}
+		}
+		const effective_bindings =
+			shadowed.size > 0 ? remove_shadowed(lazy_bindings, shadowed) : lazy_bindings;
+		let changed = false;
+		const new_init = apply_lazy_transforms(node.init, effective_bindings);
+		if (new_init !== node.init) changed = true;
+		const new_test = apply_lazy_transforms(node.test, effective_bindings);
+		if (new_test !== node.test) changed = true;
+		const new_update = apply_lazy_transforms(node.update, effective_bindings);
+		if (new_update !== node.update) changed = true;
+		const new_body = apply_lazy_transforms(node.body, effective_bindings);
+		if (new_body !== node.body) changed = true;
+		return changed
+			? { ...node, init: new_init, test: new_test, update: new_update, body: new_body }
+			: node;
+	}
+
+	if (node.type === 'ForOfStatement' || node.type === 'ForInStatement') {
+		/** @type {Set<string>} */
+		const shadowed = new Set();
+		if (node.left?.type === 'VariableDeclaration') {
+			for (const decl of node.left.declarations) {
+				if (decl.id) collect_shadowed_names(decl.id, lazy_bindings, shadowed);
+			}
+		}
+		const effective_bindings =
+			shadowed.size > 0 ? remove_shadowed(lazy_bindings, shadowed) : lazy_bindings;
+		// `node.left` is a binding site, not an expression context: a declaration
+		// like `const x` or `const [a, b]` has no outer references to rewrite,
+		// and recursing here would hit the VariableDeclarator handler and
+		// rewrite a lazy declarator id that `preallocate_lazy_ids` already
+		// tagged — double-processing the loop variable. Leave `node.left`
+		// untouched; the body and right-hand side are the only scopes with
+		// live references.
+		let changed = false;
+		// The right-hand side is evaluated in the outer scope (before the loop
+		// variable is bound), so use the unshadowed bindings there.
+		const new_right = apply_lazy_transforms(node.right, lazy_bindings);
+		if (new_right !== node.right) changed = true;
+		const new_body = apply_lazy_transforms(node.body, effective_bindings);
+		if (new_body !== node.body) changed = true;
+		return changed ? { ...node, right: new_right, body: new_body } : node;
+	}
+
+	if (node.type === 'SwitchStatement') {
+		let changed = false;
+		const new_discriminant = apply_lazy_transforms(node.discriminant, lazy_bindings);
+		if (new_discriminant !== node.discriminant) changed = true;
+		const new_cases = node.cases.map((/** @type {any} */ switch_case) => {
+			const case_bindings = collect_block_shadowed_names(switch_case.consequent, lazy_bindings);
+			const effective_bindings =
+				case_bindings.size > 0 ? remove_shadowed(lazy_bindings, case_bindings) : lazy_bindings;
+			let case_changed = false;
+			const new_test = switch_case.test
+				? apply_lazy_transforms(switch_case.test, lazy_bindings)
+				: null;
+			if (new_test !== switch_case.test) case_changed = true;
+			const new_consequent = switch_case.consequent.map((/** @type {any} */ stmt) => {
+				const transformed = apply_lazy_transforms(stmt, effective_bindings);
+				if (transformed !== stmt) case_changed = true;
+				return transformed;
+			});
+			if (case_changed) {
+				changed = true;
+				return { ...switch_case, test: new_test, consequent: new_consequent };
+			}
+			return switch_case;
+		});
+		return changed ? { ...node, discriminant: new_discriminant, cases: new_cases } : node;
+	}
+
+	// Standalone lazy destructuring assignment: `&[data] = track(0);` becomes
+	// `const __lazy0 = track(0);`. Individual name bindings are already in scope
+	// via the enclosing BlockStatement handler.
+	if (
+		node.type === 'ExpressionStatement' &&
+		node.expression?.type === 'AssignmentExpression' &&
+		node.expression.operator === '=' &&
+		(node.expression.left?.type === 'ObjectPattern' ||
+			node.expression.left?.type === 'ArrayPattern') &&
+		node.expression.left.lazy &&
+		node.expression.left.metadata?.lazy_id
+	) {
+		const pattern = node.expression.left;
+		const lazy_id = create_generated_identifier(pattern.metadata.lazy_id);
+		if (pattern.typeAnnotation) lazy_id.typeAnnotation = pattern.typeAnnotation;
+		const init = apply_lazy_transforms(node.expression.right, lazy_bindings);
+		return /** @type {any} */ ({
+			type: 'VariableDeclaration',
+			kind: 'const',
+			declarations: [
+				{
+					type: 'VariableDeclarator',
+					id: lazy_id,
+					init,
+					metadata: { path: [] },
+				},
+			],
+			metadata: { path: [] },
+		});
+	}
+
+	// AssignmentExpression / UpdateExpression whose target is a lazy identifier.
+	if (
+		node.type === 'AssignmentExpression' &&
+		node.left?.type === 'Identifier' &&
+		lazy_bindings.has(node.left.name)
+	) {
+		const binding = /** @type {LazyBinding} */ (lazy_bindings.get(node.left.name));
+		return {
+			...node,
+			left: binding.read(),
+			right: apply_lazy_transforms(node.right, lazy_bindings),
+		};
+	}
+
+	if (
+		node.type === 'UpdateExpression' &&
+		node.argument?.type === 'Identifier' &&
+		lazy_bindings.has(node.argument.name)
+	) {
+		const binding = /** @type {LazyBinding} */ (lazy_bindings.get(node.argument.name));
+		return { ...node, argument: binding.read() };
+	}
+
+	// Replace lazy variable declaration patterns with generated identifiers.
+	if (node.type === 'VariableDeclarator' && node.id?.metadata?.lazy_id) {
+		const lazy_id = create_generated_identifier(node.id.metadata.lazy_id);
+		if (node.id.typeAnnotation) lazy_id.typeAnnotation = node.id.typeAnnotation;
+		return {
+			...node,
+			id: lazy_id,
+			init: apply_lazy_transforms(node.init, lazy_bindings),
+		};
+	}
+
+	// Shorthand object properties `{ name }` → `{ name: __lazy0.name }`.
+	if (node.type === 'Property' && node.shorthand && node.value?.type === 'Identifier') {
+		const binding = lazy_bindings.get(node.value.name);
+		if (binding) {
+			return { ...node, shorthand: false, value: binding.read() };
+		}
+	}
+
+	// Bare identifier reference.
+	if (node.type === 'Identifier' && lazy_bindings.has(node.name)) {
+		const binding = /** @type {LazyBinding} */ (lazy_bindings.get(node.name));
+		return binding.read();
+	}
+
+	// JSXIdentifier is a label (component/element name), never a reference.
+	if (node.type === 'JSXIdentifier') return node;
+
+	let changed = false;
+	/** @type {any} */
+	const clone = { ...node };
+	for (const key of Object.keys(node)) {
+		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') continue;
+
+		// Skip non-computed, non-shorthand property keys (they are labels).
+		if (key === 'key' && node.type === 'Property' && !node.computed && !node.shorthand) continue;
+		// Skip non-computed member expression property access.
+		if (key === 'property' && node.type === 'MemberExpression' && !node.computed) continue;
+		// Skip JSXMemberExpression property (label, not reference).
+		if (key === 'property' && node.type === 'JSXMemberExpression') continue;
+		// Skip JSXAttribute names (labels).
+		if (key === 'name' && node.type === 'JSXAttribute') continue;
+		// Skip VariableDeclarator id (already handled above).
+		if (key === 'id' && node.type === 'VariableDeclarator') continue;
+
+		const new_value = apply_lazy_transforms(node[key], lazy_bindings);
+		if (new_value !== node[key]) {
+			clone[key] = new_value;
+			changed = true;
+		}
+	}
+	return changed ? clone : node;
+}
+
+/**
+ * @param {any} param
+ * @param {Map<string, LazyBinding>} lazy_bindings
+ */
+function transform_param_defaults(param, lazy_bindings) {
+	if (param?.type === 'AssignmentPattern') {
+		const new_right = apply_lazy_transforms(param.right, lazy_bindings);
+		if (new_right !== param.right) return { ...param, right: new_right };
+	}
+	return param;
+}
+
+/**
+ * @param {any} pattern
+ * @param {Map<string, LazyBinding>} lazy_bindings
+ * @param {Set<string>} shadowed
+ */
+function collect_shadowed_names(pattern, lazy_bindings, shadowed) {
+	if (!pattern || typeof pattern !== 'object') return;
+	if (pattern.type === 'Identifier' && lazy_bindings.has(pattern.name)) {
+		shadowed.add(pattern.name);
+		return;
+	}
+	if (pattern.type === 'AssignmentPattern') {
+		collect_shadowed_names(pattern.left, lazy_bindings, shadowed);
+		return;
+	}
+	if (pattern.type === 'RestElement') {
+		collect_shadowed_names(pattern.argument, lazy_bindings, shadowed);
+		return;
+	}
+	if (pattern.type === 'ObjectPattern') {
+		for (const prop of pattern.properties || []) {
+			if (prop.type === 'RestElement') {
+				collect_shadowed_names(prop.argument, lazy_bindings, shadowed);
+			} else {
+				collect_shadowed_names(prop.value, lazy_bindings, shadowed);
+			}
+		}
+		return;
+	}
+	if (pattern.type === 'ArrayPattern') {
+		for (const element of pattern.elements || []) {
+			if (element) collect_shadowed_names(element, lazy_bindings, shadowed);
+		}
+	}
+}
+
+/**
+ * @param {any[]} statements
+ * @param {Map<string, LazyBinding>} lazy_bindings
+ * @returns {Set<string>}
+ */
+function collect_block_shadowed_names(statements, lazy_bindings) {
+	/** @type {Set<string>} */
+	const shadowed = new Set();
+	for (const stmt of statements) {
+		if (stmt.type === 'VariableDeclaration') {
+			for (const decl of stmt.declarations) {
+				if (decl.id?.metadata?.lazy_id) continue;
+				if (decl.id) collect_shadowed_names(decl.id, lazy_bindings, shadowed);
+			}
+		} else if (stmt.type === 'FunctionDeclaration' && stmt.id) {
+			if (lazy_bindings.has(stmt.id.name)) shadowed.add(stmt.id.name);
+		}
+	}
+	return shadowed;
+}
+
+/**
+ * @param {Map<string, LazyBinding>} lazy_bindings
+ * @param {Set<string>} shadowed
+ * @returns {Map<string, LazyBinding>}
+ */
+function remove_shadowed(lazy_bindings, shadowed) {
+	const result = new Map(lazy_bindings);
+	for (const name of shadowed) result.delete(name);
+	return result;
+}
+
+/**
+ * Replace any lazy `&{}` / `&[]` patterns in a parameter list with their
+ * generated lazy identifiers. Leaves non-lazy params untouched.
+ *
+ * @param {any[]} params
+ * @returns {any[]}
+ */
+export function replace_lazy_params(params) {
+	return params.map((param) => {
+		const pattern = param.type === 'AssignmentPattern' ? param.left : param;
+		if (
+			(pattern.type === 'ObjectPattern' || pattern.type === 'ArrayPattern') &&
+			pattern.lazy &&
+			pattern.metadata?.lazy_id
+		) {
+			const lazy_id = create_generated_identifier(pattern.metadata.lazy_id);
+			if (pattern.typeAnnotation) lazy_id.typeAnnotation = pattern.typeAnnotation;
+			if (param.type === 'AssignmentPattern') return { ...param, left: lazy_id };
+			return lazy_id;
+		}
+		return param;
+	});
+}

package/src/transform/scoping.js

@@ -0,0 +1,180 @@
+/**
+ * Framework-agnostic CSS scoping utilities shared between the `@tsrx/react`
+ * and `@tsrx/solid` transforms. These walk the template AST and annotate
+ * `Element` nodes with a hash class so scope-qualified selectors
+ * (e.g. `.foo.hash`) match after rendering.
+ */
+
+import { walk } from 'zimmerframe';
+
+/**
+ * Mark every selector inside the stylesheet as "used" so `renderStylesheets`
+ * does not comment it out. We skip selector-pruning because component
+ * boundaries can be dynamic — any selector authored inside the component's
+ * `<style>` block is considered intentional.
+ *
+ * @param {any} stylesheet
+ * @returns {any}
+ */
+export function prepare_stylesheet_for_render(stylesheet) {
+	walk(stylesheet, null, {
+		_(node, { next }) {
+			if (node && node.metadata && typeof node.metadata === 'object') {
+				node.metadata.used = true;
+				if (node.type === 'RelativeSelector' && !node.metadata.is_global) {
+					node.metadata.scoped = true;
+				}
+			}
+			return next();
+		},
+	});
+	return stylesheet;
+}
+
+/**
+ * @param {any} node
+ * @returns {boolean}
+ */
+export function is_style_element(node) {
+	return (
+		node &&
+		node.type === 'Element' &&
+		node.id &&
+		node.id.type === 'Identifier' &&
+		node.id.name === 'style'
+	);
+}
+
+/**
+ * @param {any} node
+ * @returns {boolean}
+ */
+export function is_composite_element(node) {
+	if (!node || node.type !== 'Element' || !node.id) {
+		return false;
+	}
+
+	if (node.id.type === 'Identifier') {
+		return /^[A-Z]/.test(node.id.name);
+	}
+
+	return node.id.type === 'MemberExpression';
+}
+
+/**
+ * Recursively walk `Element` nodes within a component body and add the hash
+ * class name so scope-qualified selectors (e.g. `.foo.hash`) match.
+ *
+ * @param {any} node
+ * @param {string} hash
+ * @returns {any}
+ */
+export function annotate_with_hash(node, hash) {
+	if (!node || typeof node !== 'object') return node;
+	if (
+		node.type === 'Component' ||
+		node.type === 'FunctionDeclaration' ||
+		node.type === 'FunctionExpression' ||
+		node.type === 'ArrowFunctionExpression'
+	) {
+		return node;
+	}
+
+	if (node.type === 'Element') {
+		if (!is_style_element(node) && !is_composite_element(node)) {
+			add_hash_class(node, hash);
+		}
+		if (Array.isArray(node.children)) {
+			node.children = node.children
+				.filter((/** @type {any} */ child) => !is_style_element(child))
+				.map((/** @type {any} */ child) => annotate_with_hash(child, hash));
+		}
+		return node;
+	}
+
+	for (const key of Object.keys(node)) {
+		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata' || key === 'css') {
+			continue;
+		}
+
+		const value = node[key];
+		if (Array.isArray(value)) {
+			node[key] = value.map((/** @type {any} */ child) => annotate_with_hash(child, hash));
+		} else if (value && typeof value === 'object') {
+			node[key] = annotate_with_hash(value, hash);
+		}
+	}
+
+	return node;
+}
+
+/**
+ * @param {any} component
+ * @param {string} hash
+ * @returns {void}
+ */
+export function annotate_component_with_hash(component, hash) {
+	/** @type {any[]} */
+	const body = component.body;
+	component.body = body
+		.filter((/** @type {any} */ child) => !is_style_element(child))
+		.map((/** @type {any} */ child) => annotate_with_hash(child, hash));
+}
+
+/**
+ * Ensure the element carries a `class` attribute containing the scoping hash.
+ *
+ * @param {any} element
+ * @param {string} hash
+ * @returns {void}
+ */
+export function add_hash_class(element, hash) {
+	const attrs = element.attributes || (element.attributes = []);
+	const existing = attrs.find(
+		(/** @type {any} */ a) =>
+			a.type === 'Attribute' &&
+			a.name &&
+			a.name.type === 'Identifier' &&
+			(a.name.name === 'class' || a.name.name === 'className'),
+	);
+
+	if (!existing) {
+		attrs.push({
+			type: 'Attribute',
+			name: { type: 'Identifier', name: 'class' },
+			value: { type: 'Literal', value: hash, raw: JSON.stringify(hash) },
+		});
+		return;
+	}
+
+	const value = existing.value;
+	if (!value) {
+		existing.value = { type: 'Literal', value: hash, raw: JSON.stringify(hash) };
+		return;
+	}
+
+	if (value.type === 'Literal' && typeof value.value === 'string') {
+		const merged = `${value.value} ${hash}`;
+		existing.value = { type: 'Literal', value: merged, raw: JSON.stringify(merged) };
+		return;
+	}
+
+	// Dynamic expression. Concatenate at runtime via template literal.
+	const expression = value.type === 'JSXExpressionContainer' ? value.expression : value;
+	existing.value = {
+		type: 'TemplateLiteral',
+		expressions: [expression],
+		quasis: [
+			{
+				type: 'TemplateElement',
+				value: { raw: '', cooked: '' },
+				tail: false,
+			},
+			{
+				type: 'TemplateElement',
+				value: { raw: ` ${hash}`, cooked: ` ${hash}` },
+				tail: true,
+			},
+		],
+	};
+}

package/src/transform/segments.js

@@ -9,6 +9,7 @@
 	CodeMapping,
 	VolarMappingsResult,
 	PostProcessingChanges,
+	LineOffsets,
 } from '../../types/index';
 @import { CodeMapping as VolarCodeMapping } from '@volar/language-core';
  */
@@ -51,6 +52,7 @@ import {
 	mapping_data_verify_complete,
 	build_line_offsets,
 	get_mapping_from_node,
+	maybe_get_mapping_from_node,
 } from '../source-map-utils.js';
 
 const LABEL_TO_COMPONENT_REPLACE_REGEX = /(function|\((property|method)\))/;
@@ -668,9 +670,21 @@ export function convert_source_map_to_mappings(
 				return;
 			} else if (node.type === 'JSXExpressionContainer') {
 				if (node.loc) {
-					mappings.push(
-						get_mapping_from_node(node, src_to_gen_map, gen_line_offsets, mapping_data_verify_only),
+					// Use maybe_get_mapping_from_node because a transform may set the
+					// container's loc to the source range of the original `{...}`
+					// construct (e.g. a Ripple TSRXExpression or Text node), while
+					// esrap only emits a segment for the inner expression. In that
+					// case the container's start/end won't resolve — skip rather
+					// than hard-failing, and rely on the inner expression's mapping.
+					const mapping = maybe_get_mapping_from_node(
+						node,
+						src_to_gen_map,
+						gen_line_offsets,
+						mapping_data_verify_only,
 					);
+					if (!(mapping instanceof Error)) {
+						mappings.push(mapping);
+					}
 				}
 				// Visit the expression inside {}
 				if (node.expression) {
@@ -726,24 +740,38 @@ export function convert_source_map_to_mappings(
 					}
 				}
 
-				if (closing || opening.selfClosing) {
-					// Add the whole closing tag or the self-closing
-					const mapping = get_mapping_from_node(
-						closing ? closing : opening,
-						src_to_gen_map,
-						gen_line_offsets,
-						mapping_data_verify_only,
-					);
+				if ((closing?.loc || opening.loc) && (closing || opening.selfClosing)) {
+					// Add the whole closing tag or the self-closing.
+					// For self-closing elements, use maybe_get_mapping_from_node because
+					// attribute transforms (e.g. class→className, {ref fn}→ref={fn}) can shift
+					// the position of `/>` in the generated output, making the source map
+					// entry for the opening element's end position unresolvable.
+					const target_node = closing ? closing : opening;
+					const mapping = closing
+						? get_mapping_from_node(
+								target_node,
+								src_to_gen_map,
+								gen_line_offsets,
+								mapping_data_verify_only,
+							)
+						: maybe_get_mapping_from_node(
+								target_node,
+								src_to_gen_map,
+								gen_line_offsets,
+								mapping_data_verify_only,
+							);
 
-					// The generated code includes a semicolon after the closing or self-closed tag
-					// We're extending the mapping to include the semicolon
-					// because the diagnostics errors can include the whole element
-					// and we need to account for the semicolon as it's a part of the diagnostic
-					// At the same time, we could've instead applied this logic to the whole `node` element
-					// but since we already map the opening - start, we just need the proper end
-					// and it was causing some issues with mappings
-					mapping.generatedLengths = [mapping.generatedLengths[0] + 1];
-					mappings.push(mapping);
+					if (!(mapping instanceof Error)) {
+						// The generated code includes a semicolon after the closing or self-closed tag
+						// We're extending the mapping to include the semicolon
+						// because the diagnostics errors can include the whole element
+						// and we need to account for the semicolon as it's a part of the diagnostic
+						// At the same time, we could've instead applied this logic to the whole `node` element
+						// but since we already map the opening - start, we just need the proper end
+						// and it was causing some issues with mappings
+						mapping.generatedLengths = [mapping.generatedLengths[0] + 1];
+						mappings.push(mapping);
+					}
 				}
 
 				if (closing) {
@@ -769,37 +797,52 @@ export function convert_source_map_to_mappings(
 					let start = node_fn.start;
 					const async_keyword = 'async';
 
-					if (node_fn.async) {
-						// We explicitly mapped async and function in esrap
+					if (is_component && node_fn.id?.loc) {
+						const mapping = get_mapping_from_node(node_fn.id, src_to_gen_map, gen_line_offsets);
+						const generated_id_start = mapping.generatedOffsets[0];
+						const generated_keyword_start = find_component_keyword_offset(
+							generated_code,
+							generated_id_start,
+						);
+						mapping.sourceOffsets = [start];
+						mapping.lengths = [source_func_keyword.length];
+						mapping.generatedOffsets = [generated_keyword_start];
+						mapping.generatedLengths = ['function'.length];
+						mapping.data.customData.hover = replace_label_to_component;
+						mappings.push(mapping);
+					} else {
+						if (node_fn.async) {
+							// We explicitly mapped async and function in esrap
+							tokens.push({
+								source: async_keyword,
+								generated: async_keyword,
+								loc: {
+									start: { line: node_fn.loc.start.line, column: start_col },
+									end: {
+										line: node_fn.loc.start.line,
+										column: start_col + async_keyword.length,
+									},
+								},
+								metadata: {},
+							});
+
+							start_col += async_keyword.length + 1; // +1 for space
+							start += async_keyword.length + 1;
+						}
+
 						tokens.push({
-							source: async_keyword,
-							generated: async_keyword,
+							source: source_func_keyword,
+							generated: 'function',
 							loc: {
 								start: { line: node_fn.loc.start.line, column: start_col },
 								end: {
 									line: node_fn.loc.start.line,
-									column: start_col + async_keyword.length,
+									column: start_col + source_func_keyword.length,
 								},
 							},
-							metadata: {},
+							metadata: is_component ? { hover: replace_label_to_component } : {},
 						});
-
-						start_col += async_keyword.length + 1; // +1 for space
-						start += async_keyword.length + 1;
 					}
-
-					tokens.push({
-						source: source_func_keyword,
-						generated: 'function',
-						loc: {
-							start: { line: node_fn.loc.start.line, column: start_col },
-							end: {
-								line: node_fn.loc.start.line,
-								column: start_col + source_func_keyword.length,
-							},
-						},
-						metadata: is_component ? { hover: replace_label_to_component } : {},
-					});
 				}
 
 				// Visit in source order: id, params, body
@@ -982,9 +1025,11 @@ export function convert_source_map_to_mappings(
 					visit(node.body);
 				}
 
-				mappings.push(
-					get_mapping_from_node(node, src_to_gen_map, gen_line_offsets, mapping_data_verify_only),
-				);
+				if (node.loc) {
+					mappings.push(
+						get_mapping_from_node(node, src_to_gen_map, gen_line_offsets, mapping_data_verify_only),
+					);
+				}
 
 				return;
 			} else if (node.type === 'WhileStatement' || node.type === 'DoWhileStatement') {
@@ -1321,9 +1366,11 @@ export function convert_source_map_to_mappings(
 					}
 				}
 
-				mappings.push(
-					get_mapping_from_node(node, src_to_gen_map, gen_line_offsets, mapping_data_verify_only),
-				);
+				if (node.loc) {
+					mappings.push(
+						get_mapping_from_node(node, src_to_gen_map, gen_line_offsets, mapping_data_verify_only),
+					);
+				}
 
 				return;
 			} else if (node.type === 'SwitchCase') {
@@ -2030,11 +2077,16 @@ export function convert_source_map_to_mappings(
 		);
 		const source_length = source_text.length;
 		const gen_length = gen_text.length;
-		const gen_line_col = get_generated_position(
-			token.loc.start.line,
-			token.loc.start.column,
-			src_to_gen_map,
-		);
+		let gen_line_col;
+		try {
+			gen_line_col = get_generated_position(
+				token.loc.start.line,
+				token.loc.start.column,
+				src_to_gen_map,
+			);
+		} catch {
+			continue;
+		}
 		const gen_start = loc_to_offset(gen_line_col.line, gen_line_col.column, gen_line_offsets);
 
 		/** @type {CustomMappingData} */
@@ -2138,3 +2190,117 @@ export function convert_source_map_to_mappings(
 		cssMappings,
 	};
 }
+
+/**
+ * @param {string} generated_code
+ * @param {number} generated_id_start
+ * @returns {number}
+ */
+function find_component_keyword_offset(generated_code, generated_id_start) {
+	const function_keyword_index = generated_code.lastIndexOf('function', generated_id_start);
+
+	if (function_keyword_index === -1) {
+		return generated_id_start;
+	}
+
+	return function_keyword_index;
+}
+
+/**
+ * Build a `VolarMappingsResult` from generated code plus source-map metadata.
+ *
+ * Framework packages are responsible for producing the generated AST/code/map.
+ * Core owns the generic mapping conversion and result envelope so the editor
+ * integration is not coupled to any specific framework package.
+ *
+ * @param {{
+ * 	ast: AST.Program,
+ * 	ast_from_source: AST.Program,
+ * 	source: string,
+ * 	generated_code: string,
+ * 	source_map: RawSourceMap,
+ * 	errors?: import('../../types/index').CompileError[],
+ * 	post_processing_changes?: PostProcessingChanges,
+ * 	line_offsets?: LineOffsets,
+ * }} params
+ * @returns {VolarMappingsResult}
+ */
+export function create_volar_mappings_result({
+	ast,
+	ast_from_source,
+	source,
+	generated_code,
+	source_map,
+	errors = [],
+	post_processing_changes,
+	line_offsets,
+}) {
+	return {
+		...convert_source_map_to_mappings(
+			ast,
+			ast_from_source,
+			source,
+			generated_code,
+			source_map,
+			/** @type {PostProcessingChanges} */ (post_processing_changes),
+			line_offsets ?? build_line_offsets(generated_code),
+		),
+		errors,
+	};
+}
+
+/**
+ * Remove byte-for-byte duplicate mappings. Framework compilers that extract
+ * shared helpers or replay JSX can emit identical mapping entries for the
+ * same source and generated span; Volar merges duplicates into a single
+ * hover/navigation result, so deduping upstream avoids a stutter.
+ *
+ * @param {CodeMapping[]} mappings
+ * @returns {CodeMapping[]}
+ */
+export function dedupe_mappings(mappings) {
+	const deduped = [];
+	const seen = new Set();
+
+	for (const mapping of mappings) {
+		const key = JSON.stringify(serialize_mapping_value(mapping));
+
+		if (seen.has(key)) {
+			continue;
+		}
+
+		seen.add(key);
+		deduped.push(mapping);
+	}
+
+	return deduped;
+}
+
+/**
+ * Serialize a mapping (or any nested value) into a stable JSON-friendly
+ * shape so {@link dedupe_mappings} can compare two entries by content.
+ * Object keys are sorted and functions are reduced to their source so
+ * structurally-identical entries produce the same string.
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function serialize_mapping_value(value) {
+	if (typeof value === 'function') {
+		return value.toString();
+	}
+
+	if (Array.isArray(value)) {
+		return value.map(serialize_mapping_value);
+	}
+
+	if (value && typeof value === 'object') {
+		return Object.fromEntries(
+			Object.entries(value)
+				.sort(([left], [right]) => left.localeCompare(right))
+				.map(([key, nested_value]) => [key, serialize_mapping_value(nested_value)]),
+		);
+	}
+
+	return value;
+}

package/types/index.d.ts

@@ -1387,7 +1387,7 @@ export interface TransformClientState extends BaseState {
 	applyParentCssScope?: AST.CSS.StyleSheet['hash'];
 	skip_children_traversal: boolean;
 	return_flags?: Map<AST.ReturnStatement, { name: string; tracked: boolean }>;
-	is_ripple_element?: boolean;
+	is_tsrx_element?: boolean;
 }
 
 /** Override zimmerframe types and provide our own */

package/types/parse.d.ts

@@ -182,7 +182,12 @@ export namespace Parse {
 	}
 
 	export interface Options extends Omit<acorn.Options, 'onComment' | 'ecmaVersion'> {
-		rippleOptions: {
+		tsrxOptions?: {
+			loose: boolean;
+			errors: CoreCompiler.CompileError[];
+			filename: string | undefined;
+		};
+		rippleOptions?: {
 			loose: boolean;
 			errors: CoreCompiler.CompileError[];
 			filename: string | undefined;