@tsrx/core 0.0.17 → 0.0.19

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "type": "module",
   "repository": {
     "type": "git",
@@ -27,6 +27,10 @@
     "./types/acorn": {
       "types": "./types/acorn.d.ts"
     },
+    "./runtime/merge-refs": {
+      "types": "./types/runtime/merge-refs.d.ts",
+      "default": "./src/runtime/merge-refs.js"
+    },
     "./test-harness/source-mappings": "./tests/shared/source-mappings.js",
     "./test-harness/compile": "./tests/shared/compile.js"
   },

package/src/index.js

@@ -139,6 +139,9 @@ export { escape } from './utils/escaping.js';
 // Transform
 export {
 	createJsxTransform,
+	merge_duplicate_refs as mergeDuplicateRefs,
+	to_jsx_attribute as toJsxAttribute,
+	validate_at_most_one_ref_attribute as validateAtMostOneRefAttribute,
 	component_to_function_declaration as componentToFunctionDeclaration,
 } from './transform/jsx/index.js';
 export {

package/src/plugin.js

@@ -176,6 +176,7 @@ export function TSRXPlugin(config) {
 			/** @type {AST.Node[]} */
 			#path = [];
 			#allowTagStartAfterDoubleQuotedText = false;
+			#allowDoubleQuotedTextChildAfterBrace = false;
 			#commentContextId = 0;
 			#loose = false;
 			/** @type {import('../types/index').CompileError[] | undefined} */
@@ -229,7 +230,7 @@ export function TSRXPlugin(config) {
 					prev === 34 || // "
 					prev === 59 || // ;
 					prev === 62 || // >
-					prev === 123 || // {
+					(prev === 123 && this.#allowDoubleQuotedTextChildAfterBrace) || // {
 					prev === 125 // }
 				);
 			}
@@ -632,8 +633,14 @@ export function TSRXPlugin(config) {
 			 * @type {Parse.Parser['getTokenFromCode']}
 			 */
 			getTokenFromCode(code) {
-				if (code === 34 && this.#isDoubleQuotedTextChildStart()) {
-					return this.#readDoubleQuotedTextChildToken();
+				if (code === 34) {
+					const is_double_quoted_text_child = this.#isDoubleQuotedTextChildStart();
+					this.#allowDoubleQuotedTextChildAfterBrace = false;
+					if (is_double_quoted_text_child) {
+						return this.#readDoubleQuotedTextChildToken();
+					}
+				} else {
+					this.#allowDoubleQuotedTextChildAfterBrace = false;
 				}
 
 				if (code !== 60) {
@@ -1058,6 +1065,9 @@ export function TSRXPlugin(config) {
 				const parent_function_body_depth = this.#functionBodyDepth;
 				this.#functionBodyDepth = 0;
 
+				if (this.type === tt.braceL) {
+					this.#allowDoubleQuotedTextChildAfterBrace = true;
+				}
 				this.eat(tt.braceL);
 				node.body = [];
 				this.#path.push(node);
@@ -2654,6 +2664,7 @@ export function TSRXPlugin(config) {
 					if (node === void 0) node = /** @type {AST.BlockStatement} */ (this.startNode());
 
 					node.body = [];
+					this.#allowDoubleQuotedTextChildAfterBrace = true;
 					this.expect(tt.braceL);
 					if (createNewLexicalScope) {
 						this.enterScope(0);

package/src/runtime/merge-refs.js

@@ -0,0 +1,61 @@
+/**
+ * Merge multiple refs (function refs and ref objects) into a single
+ * callback ref. Used by the tsrx-react, tsrx-preact, and tsrx-vue
+ * compilers when an element has more than one `ref` attribute, since
+ * those runtimes treat duplicate `ref` props as a regular duplicate-prop
+ * collision (last wins) rather than running both. Solid does not use this
+ * helper — its native runtime accepts an array of refs and the compiler
+ * emits an array literal directly.
+ *
+ * The returned callback ref handles four cases per input:
+ * - `null` / `undefined`: skipped.
+ * - function ref: invoked with the node. If it returns a function, that
+ *   return value is treated as a React 19 cleanup. Otherwise we record a
+ *   cleanup that calls the ref with `null` so the legacy unmount contract
+ *   still fires.
+ * - React-style ref object (`{ current }`): assigned on mount, cleared
+ *   on unmount.
+ * - Vue-style ref object (`{ value }`, e.g. `ref()` / `useTemplateRef()`):
+ *   assigned on mount, cleared on unmount.
+ *
+ * The merged ref always returns a cleanup. Under React 19 the cleanup
+ * runs on unmount and the inner refs are not separately re-invoked with
+ * `null`. Under older React, Preact, and Vue the cleanup return value
+ * is ignored, so the runtime instead invokes the merged ref a second
+ * time with `null` — which re-runs the loop body, calling each inner
+ * with `null` and clearing each ref object. Either way every inner ref
+ * sees a balanced mount/unmount.
+ *
+ * @param {...((node: any) => void | (() => void)) | { current: any } | { value: any } | null | undefined} refs
+ * @returns {(node: any) => (() => void)}
+ */
+export function mergeRefs(...refs) {
+	return (node) => {
+		/** @type {Array<() => void>} */
+		const cleanups = [];
+		for (const ref of refs) {
+			if (ref == null) continue;
+			if (typeof ref === 'function') {
+				const result = ref(node);
+				if (typeof result === 'function') {
+					cleanups.push(result);
+				} else {
+					cleanups.push(() => ref(null));
+				}
+			} else if ('current' in ref) {
+				ref.current = node;
+				cleanups.push(() => {
+					ref.current = null;
+				});
+			} else if ('value' in ref) {
+				ref.value = node;
+				cleanups.push(() => {
+					ref.value = null;
+				});
+			}
+		}
+		return () => {
+			for (const cleanup of cleanups) cleanup();
+		};
+	};
+}

package/src/transform/jsx/index.js

@@ -1,9 +1,10 @@
 /** @import * as AST from 'estree' */
 /** @import * as ESTreeJSX from 'estree-jsx' */
-/** @import { JsxPlatform, JsxTransformOptions, JsxTransformResult } from '@tsrx/core/types' */
+/** @import { JsxPlatform, JsxTransformContext, JsxTransformOptions, JsxTransformResult } from '@tsrx/core/types' */
 
 import { walk } from 'zimmerframe';
 import { print } from 'esrap';
+import { error } from '../../errors.js';
 import {
 	ensure_function_metadata,
 	in_jsx_child_context,
@@ -14,7 +15,6 @@ import {
 	clone_expression_node,
 	clone_identifier,
 	clone_jsx_name,
-	create_compile_error,
 	create_generated_identifier,
 	create_null_literal,
 	flatten_switch_consequent,
@@ -26,7 +26,11 @@ import {
 	to_text_expression,
 } from './ast-builders.js';
 import { render_stylesheets as renderStylesheets } from '../stylesheet.js';
-import { set_location as setLocation } from '../../utils/builders.js';
+import {
+	set_location as setLocation,
+	jsx_attribute as build_jsx_attribute,
+	jsx_id as build_jsx_id,
+} from '../../utils/builders.js';
 import {
 	apply_lazy_transforms,
 	collect_lazy_bindings_from_component,
@@ -45,17 +49,11 @@ import {
 import { is_hoist_safe_jsx_node } from '../jsx-hoist.js';
 
 /**
- * @typedef {{
- *   platform: JsxPlatform,
- *   local_statement_component_index: number,
- *   needs_error_boundary: boolean,
- *   needs_suspense: boolean,
- *   helper_state: { base_name: string, next_id: number, helpers: any[], statics: any[] } | null,
- *   available_bindings: Map<string, AST.Identifier>,
- *   lazy_next_id: number,
- *   current_css_hash: string | null,
- *   inside_element_child?: boolean,
- * }} TransformContext
+ * Local alias for the shared `JsxTransformContext`. Kept as a typedef so the
+ * rest of this file's `@param {TransformContext}` annotations don't all have
+ * to spell out the import.
+ *
+ * @typedef {JsxTransformContext} TransformContext
  */
 
 /**
@@ -98,19 +96,24 @@ export function createJsxTransform(platform) {
 		const stylesheets = [];
 
 		/** @type {TransformContext} */
-		const transform_context = /** @type {any} */ ({
+		const transform_context = {
 			platform,
 			local_statement_component_index: 0,
 			needs_error_boundary: false,
 			needs_suspense: false,
+			needs_merge_refs: false,
 			helper_state: null,
 			available_bindings: new Map(),
 			lazy_next_id: 0,
 			current_css_hash: null,
+			filename: filename ?? null,
+			loose: !!options?.loose,
+			errors: options?.loose ? options?.errors : undefined,
+			comments: options?.comments,
 			// Platforms can seed their own tracking state (e.g. solid's
 			// needs_show / needs_for flags) via `hooks.initialState`.
 			...(platform.hooks?.initialState?.() ?? {}),
-		});
+		};
 
 		preallocate_lazy_ids(/** @type {any} */ (ast), transform_context);
 
@@ -141,9 +144,12 @@ export function createJsxTransform(platform) {
 							source,
 						);
 					} else if (!module_uses_server_directive) {
-						throw create_compile_error(
-							await_expression,
+						error(
 							`${platform.name} components can only use \`await\` when the module has a top-level "use server" directive.`,
+							state.filename,
+							await_expression,
+							state.errors,
+							state.comments,
 						);
 					}
 
@@ -210,10 +216,10 @@ export function createJsxTransform(platform) {
 				return /** @type {any} */ (tsx_node_to_jsx_expression(inner, in_jsx_child_context(path)));
 			},
 
-			TsxCompat(node, { next, path }) {
+			TsxCompat(node, { next, path, state }) {
 				const inner = /** @type {any} */ (next() ?? node);
 				return /** @type {any} */ (
-					tsx_compat_node_to_jsx_expression(inner, platform, in_jsx_child_context(path))
+					tsx_compat_node_to_jsx_expression(inner, state, in_jsx_child_context(path))
 				);
 			},
 
@@ -1483,7 +1489,22 @@ const TEMPLATE_FRAGMENT_ERROR =
 function to_jsx_element(node, transform_context, raw_children = node.children || []) {
 	if (node.type === 'JSXElement') return node;
 	if (!node.id) {
-		throw create_compile_error(node, TEMPLATE_FRAGMENT_ERROR);
+		error(
+			TEMPLATE_FRAGMENT_ERROR,
+			transform_context.filename,
+			node,
+			transform_context.errors,
+			transform_context.comments,
+		);
+		return set_loc(
+			/** @type {any} */ ({
+				type: 'JSXFragment',
+				openingFragment: { type: 'JSXOpeningFragment' },
+				closingFragment: { type: 'JSXClosingFragment' },
+				children: [],
+			}),
+			node,
+		);
 	}
 	if (is_dynamic_element_id(node.id)) {
 		return dynamic_element_to_jsx_child(node, transform_context);
@@ -2109,7 +2130,7 @@ function to_jsx_child(node, transform_context) {
 			// JSXExpressionContainer wrapper for bare `{expr}` children.
 			return tsx_node_to_jsx_expression(node, true);
 		case 'TsxCompat':
-			return tsx_compat_node_to_jsx_expression(node, transform_context.platform, true);
+			return tsx_compat_node_to_jsx_expression(node, transform_context, true);
 		case 'Element':
 			return to_jsx_element(node, transform_context);
 		case 'Text':
@@ -2280,9 +2301,12 @@ function find_key_expression_in_body(body_nodes) {
  */
 function for_of_statement_to_jsx_child(node, transform_context) {
 	if (node.await) {
-		throw create_compile_error(
-			node,
+		error(
 			`${transform_context.platform.name} TSRX does not support \`for await...of\` in component templates.`,
+			transform_context.filename,
+			node,
+			transform_context.errors,
+			transform_context.comments,
 		);
 	}
 
@@ -2458,23 +2482,33 @@ function try_statement_to_jsx_child(node, transform_context) {
 	const finalizer = node.finalizer;
 
 	if (finalizer) {
-		throw create_compile_error(
-			finalizer,
+		error(
 			`${transform_context.platform.name} TSRX does not support JavaScript \`try/finally\` in component templates. \`finally\` is not part of TSRX control flow; move the try/finally into a function if you need cleanup logic.`,
+			transform_context.filename,
+			finalizer,
+			transform_context.errors,
+			transform_context.comments,
 		);
 	}
 
 	if (!pending && !handler) {
-		throw create_compile_error(
-			node,
+		error(
 			'Component try statements must have a `pending` or `catch` block.',
+			transform_context.filename,
+			node,
+			transform_context.errors,
+			transform_context.comments,
 		);
+		return to_jsx_expression_container(create_null_literal());
 	}
 
 	if (pending && transform_context.platform.validation.unsupportedTryPendingMessage) {
-		throw create_compile_error(
-			pending,
+		error(
 			transform_context.platform.validation.unsupportedTryPendingMessage,
+			transform_context.filename,
+			pending,
+			transform_context.errors,
+			transform_context.comments,
 		);
 	}
 
@@ -2482,16 +2516,22 @@ function try_statement_to_jsx_child(node, transform_context) {
 	if (pending) {
 		const try_body = node.block.body || [];
 		if (!try_body.some(is_jsx_child)) {
-			throw create_compile_error(
-				node.block,
+			error(
 				'Component try statements must contain a template in their main body. Move the try statement into a function if it does not render anything.',
+				transform_context.filename,
+				node.block,
+				transform_context.errors,
+				transform_context.comments,
 			);
 		}
 		const pending_body = pending.body || [];
 		if (!pending_body.some(is_jsx_child)) {
-			throw create_compile_error(
-				pending,
+			error(
 				'Component try statements must contain a template in their "pending" body. Rendering a pending fallback is required to have a template.',
+				transform_context.filename,
+				pending,
+				transform_context.errors,
+				transform_context.comments,
 			);
 		}
 	}
@@ -2679,10 +2719,11 @@ function create_jsx_element(tag_name, attributes, children) {
 }
 
 /**
- * Inject import declarations for `Suspense` and `TsrxErrorBoundary` if the
- * transform determined they are needed. The import sources are platform-
- * specific (e.g. `react` vs `preact/compat`, `@tsrx/react/error-boundary`
- * vs `@tsrx/preact/error-boundary`).
+ * Inject runtime-helper import declarations the transform decided it needed
+ * during the walk: `Suspense` for `try { ... } pending { ... }`,
+ * `TsrxErrorBoundary` for `try { ... } catch (...)`, and `mergeRefs` for
+ * elements with multiple `ref` attributes under the `'merge-refs'`
+ * strategy. Import sources are platform-specific.
  *
  * @param {AST.Program} program
  * @param {TransformContext} transform_context
@@ -2743,6 +2784,35 @@ function inject_try_imports(program, transform_context, platform, suspense_sourc
 		});
 	}
 
+	if (transform_context.needs_merge_refs && platform.imports.mergeRefs) {
+		const merge_refs_source = platform.imports.mergeRefs;
+		imports.push({
+			type: 'ImportDeclaration',
+			specifiers: [
+				{
+					type: 'ImportSpecifier',
+					imported: {
+						type: 'Identifier',
+						name: 'mergeRefs',
+						metadata: { path: [] },
+					},
+					local: {
+						type: 'Identifier',
+						name: MERGE_REFS_LOCAL_NAME,
+						metadata: { path: [] },
+					},
+					metadata: { path: [] },
+				},
+			],
+			source: {
+				type: 'Literal',
+				value: merge_refs_source,
+				raw: `'${merge_refs_source}'`,
+			},
+			metadata: { path: [] },
+		});
+	}
+
 	if (imports.length > 0) {
 		program.body.unshift(...imports);
 	}
@@ -2915,9 +2985,15 @@ function to_jsx_expression_container(expression, source_node = expression) {
 /**
  * Dispatch point for element attribute transformation. Platforms can replace
  * the default "map over `to_jsx_attribute`" via
- * `hooks.transformElementAttributes` — Solid uses this to collapse
- * `<elem>{'text'}</elem>` into a `textContent` attribute and to route
- * attributes through its composite-element handling.
+ * `hooks.transformElementAttributes`. Whether or not the hook is used,
+ * the result is run through `merge_duplicate_refs` so platforms with a
+ * `multiRefStrategy` get duplicate-`ref` handling for free.
+ *
+ * Before lowering, the raw attribute list is validated to reject elements
+ * with more than one TSX-style `ref={...}` attribute — that shape produces
+ * duplicate JSX props which the JSX runtime collapses to last-wins (and
+ * which TypeScript can't type cleanly). Multiple Ripple `{ref expr}`
+ * keyword-form refs remain valid and merge into a single ref attribute.
  *
  * @param {any[]} attrs
  * @param {TransformContext} transform_context
@@ -2925,21 +3001,204 @@ function to_jsx_expression_container(expression, source_node = expression) {
  * @returns {any[]}
  */
 function transform_element_attributes_dispatch(attrs, transform_context, element) {
+	validate_at_most_one_ref_attribute(attrs, transform_context);
 	const preprocess = transform_context.platform.hooks?.preprocessElementAttributes;
 	if (preprocess) {
 		attrs = preprocess(attrs, transform_context, element);
 	}
 	const hook = transform_context.platform.hooks?.transformElementAttributes;
-	if (hook) return hook(attrs, transform_context, element);
-	return attrs.map((/** @type {any} */ a) => to_jsx_attribute(a, transform_context));
+	const result = hook
+		? hook(attrs, transform_context, element)
+		: attrs.map((/** @type {any} */ a) => to_jsx_attribute(a, transform_context));
+	return merge_duplicate_refs(result, transform_context);
+}
+
+/**
+ * Reject elements with more than one TSX-style `ref={...}` attribute.
+ * Ripple's `{ref expr}` keyword form is parsed as a `RefAttribute` node
+ * and is excluded from the count — multiple keyword-form refs are a Ripple
+ * feature that compose via the merge pass. This validator runs over the
+ * raw, pre-lowering attribute list so each shape is still distinguishable
+ * by `type`. Ripple `Element` attributes have type `Attribute` with an
+ * `Identifier` name (the parser normalizes `JSXAttribute`/`JSXIdentifier`
+ * for non-Tsx elements); inside `<tsx:react>` compat blocks they retain
+ * the original `JSXAttribute`/`JSXIdentifier` shape, so we accept both.
+ *
+ * @param {any[]} raw_attrs
+ * @param {TransformContext} [transform_context]
+ */
+export function validate_at_most_one_ref_attribute(raw_attrs, transform_context) {
+	/** @type {any[]} */
+	const refs = [];
+	for (const attr of raw_attrs) {
+		if (!attr) continue;
+		const is_ref_attr =
+			(attr.type === 'Attribute' &&
+				attr.name &&
+				attr.name.type === 'Identifier' &&
+				attr.name.name === 'ref') ||
+			(attr.type === 'JSXAttribute' &&
+				attr.name &&
+				attr.name.type === 'JSXIdentifier' &&
+				attr.name.name === 'ref');
+		if (!is_ref_attr) continue;
+		refs.push(attr.name);
+	}
+	if (refs.length < 2) {
+		return;
+	}
+	for (let i = 0; i < refs.length; i++) {
+		const node = refs[i];
+		if (!transform_context?.loose && i === 0) {
+			// in the non-loose mode, only throw on the second duplicate
+			continue;
+		}
+		error(
+			'Element has multiple `ref={...}` attributes; an element may have at most one. ' +
+				"Use Ripple's `{ref expr}` keyword form to combine multiple refs on one element.",
+			transform_context?.filename ?? null,
+			node,
+			transform_context?.errors,
+			transform_context?.comments,
+		);
+	}
+}
+
+/**
+ * Collapse multiple `ref` JSXAttributes on a single element into one. Both
+ * Ripple's `{ref expr}` keyword form and TSX-style `ref={expr}` are handled
+ * because they have already been normalized to `JSXAttribute` named `ref`
+ * by `to_jsx_attribute` (Ripple) or the parser (TSX-style). The shape of
+ * the merged value depends on `platform.jsx.multiRefStrategy`:
+ *
+ * - `'merge-refs'` — emit `ref={__mergeRefs(a, b, ...)}` and flag
+ *   `needs_merge_refs` so an import is injected later. React and Preact
+ *   need this because their runtimes dedupe duplicate `ref` props.
+ * - `'array'` — emit `ref={[a, b, ...]}`. Solid's runtime iterates
+ *   array refs natively, so no helper is required.
+ * - `undefined` — return the list unchanged. The platform takes care
+ *   of duplicate refs at runtime (or doesn't support them).
+ *
+ * Single-ref elements are always left unchanged so trivial cases stay
+ * import-free and produce no helper call.
+ *
+ * @param {any[]} jsx_attrs
+ * @param {TransformContext} transform_context
+ * @returns {any[]}
+ */
+export function merge_duplicate_refs(jsx_attrs, transform_context) {
+	const strategy = transform_context.platform.jsx.multiRefStrategy;
+	if (!strategy) return jsx_attrs;
+
+	let count = 0;
+	let tsx_form_count = 0;
+	for (const attr of jsx_attrs) {
+		if (!is_jsx_ref_attribute(attr)) continue;
+		count += 1;
+		if (!attr.metadata?.from_ref_keyword) tsx_form_count += 1;
+	}
+	if (count <= 1) return jsx_attrs;
+	// Two or more genuine `ref={...}` (TSX-form) attributes are already a
+	// validator-flagged compile error and TypeScript flags them as duplicate
+	// JSX props. Leave them in place so the user gets all three signals
+	// instead of silently composing them into `__mergeRefs(...)`.
+	if (tsx_form_count >= 2) return jsx_attrs;
+
+	/** @type {any[]} */
+	const ref_exprs = [];
+	/** @type {any[]} */
+	const result = [];
+	/** @type {any} */
+	let source_attr = null;
+	for (const attr of jsx_attrs) {
+		if (is_jsx_ref_attribute(attr)) {
+			ref_exprs.push(attr.value.expression);
+			// Inherit loc from the (at most one) `ref={expr}`-form attribute so
+			// the kept `ref` keyword in the generated `ref={__mergeRefs(...)}`
+			// retains a source mapping back to its original `ref=` keyword.
+			if (!source_attr && !attr.metadata?.from_ref_keyword) {
+				source_attr = attr;
+			}
+		} else {
+			result.push(attr);
+		}
+	}
+
+	const merged_value =
+		strategy === 'merge-refs'
+			? /** @type {any} */ ({
+					type: 'CallExpression',
+					callee: {
+						type: 'Identifier',
+						name: MERGE_REFS_LOCAL_NAME,
+						metadata: { path: [] },
+					},
+					arguments: ref_exprs,
+					optional: false,
+					metadata: { path: [] },
+				})
+			: /** @type {any} */ ({
+					type: 'ArrayExpression',
+					elements: ref_exprs,
+					metadata: { path: [] },
+				});
+
+	if (strategy === 'merge-refs') {
+		transform_context.needs_merge_refs = true;
+	}
+
+	// Inherit start/end/loc from the (at most one) `ref={expr}`-form attribute
+	// so segments.js emits a normal source-to-generated mapping for the
+	// merged attribute and its name. Without this the kept `ref` keyword in
+	// `ref={__mergeRefs(...)}` has no source mapping back to the user's `ref=`
+	// keyword.
+	const merged_name = build_jsx_id('ref', source_attr?.name);
+	const merged_attr = build_jsx_attribute(
+		merged_name,
+		/** @type {any} */ ({
+			type: 'JSXExpressionContainer',
+			expression: merged_value,
+			metadata: { path: [] },
+		}),
+		false,
+		source_attr,
+	);
+	result.push(merged_attr);
+
+	return result;
 }
 
+/**
+ * @param {any} attr
+ * @returns {boolean}
+ */
+function is_jsx_ref_attribute(attr) {
+	return (
+		!!attr &&
+		attr.type === 'JSXAttribute' &&
+		!!attr.name &&
+		attr.name.type === 'JSXIdentifier' &&
+		attr.name.name === 'ref' &&
+		!!attr.value &&
+		attr.value.type === 'JSXExpressionContainer' &&
+		!!attr.value.expression &&
+		attr.value.expression.type !== 'JSXEmptyExpression'
+	);
+}
+
+/**
+ * Local alias used for the injected `mergeRefs` import. The leading
+ * double-underscore matches the convention for compiler-generated
+ * identifiers and avoids shadowing user-declared `mergeRefs` symbols.
+ */
+const MERGE_REFS_LOCAL_NAME = '__mergeRefs';
+
 /**
  * @param {any} attr
  * @param {TransformContext} transform_context
  * @returns {ESTreeJSX.JSXAttribute | ESTreeJSX.JSXSpreadAttribute}
  */
-function to_jsx_attribute(attr, transform_context) {
+export function to_jsx_attribute(attr, transform_context) {
 	if (!attr) return attr;
 	if (attr.type === 'JSXAttribute' || attr.type === 'JSXSpreadAttribute') {
 		return attr;
@@ -2954,15 +3213,23 @@ function to_jsx_attribute(attr, transform_context) {
 		);
 	}
 	if (attr.type === 'RefAttribute') {
-		// RefAttribute uses `{ref expr}` syntax whose source positions don't map to the
-		// generated `ref={expr}` JSX attribute, so we intentionally omit loc.
-		return /** @type {any} */ ({
-			type: 'JSXAttribute',
-			name: { type: 'JSXIdentifier', name: 'ref', metadata: { path: [] } },
-			value: to_jsx_expression_container(attr.argument),
-			shorthand: false,
-			metadata: { path: [] },
-		});
+		// `{ref expr}` and the generated `ref={expr}` have different shapes,
+		// so the source-to-generated mapping is imprecise — but pointing
+		// editors at the `{ref expr}` span is still useful for hover/jump,
+		// matching how shorthand `{name}` → `name={name}` carries loc.
+		// `from_ref_keyword` lets `merge_duplicate_refs` tell this form apart
+		// from genuine `ref={...}` attributes without inferring it from
+		// whether `name.loc` happens to be present.
+		return set_loc(
+			/** @type {any} */ ({
+				type: 'JSXAttribute',
+				name: { type: 'JSXIdentifier', name: 'ref', metadata: { path: [] } },
+				value: to_jsx_expression_container(attr.argument),
+				shorthand: false,
+				metadata: { path: [], from_ref_keyword: true },
+			}),
+			attr,
+		);
 	}
 
 	// Platforms that expect React-style DOM attrs (React) rewrite `class` to
@@ -2992,13 +3259,7 @@ function to_jsx_attribute(attr, transform_context) {
 		}
 	}
 
-	const jsx_attribute = /** @type {any} */ ({
-		type: 'JSXAttribute',
-		name,
-		value: value || null,
-		shorthand: false,
-		metadata: { path: [] },
-	});
+	const jsx_attribute = build_jsx_attribute(name, value || null, attr.shorthand === true);
 
 	if (value_has_unmappable_jsx_loc(value)) {
 		/** @type {any} */ (jsx_attribute.metadata).has_unmappable_value = true;
@@ -3163,16 +3424,20 @@ function build_return_expression(render_nodes) {
 
 /**
  * @param {any} node
- * @param {JsxPlatform} platform
+ * @param {TransformContext} transform_context
  * @param {boolean} [in_jsx_child]
  * @returns {any}
  */
-function tsx_compat_node_to_jsx_expression(node, platform, in_jsx_child = false) {
+function tsx_compat_node_to_jsx_expression(node, transform_context, in_jsx_child = false) {
+	const platform = transform_context.platform;
 	if (!platform.jsx.acceptedTsxKinds.includes(node.kind)) {
 		const accepted = platform.jsx.acceptedTsxKinds.map((k) => `<tsx:${k}>`).join(', ');
-		throw create_compile_error(
-			node,
+		error(
 			`${platform.name} TSRX does not support <tsx:${node.kind}> blocks. Use <tsx> or one of: ${accepted}.`,
+			transform_context.filename,
+			node,
+			transform_context.errors,
+			transform_context.comments,
 		);
 	}
 

package/types/index.d.ts

@@ -8,13 +8,21 @@ import type { RequireAllOrNone } from '../src/helpers.js';
 import type {
 	JsxPlatform,
 	JsxPlatformHooks,
+	JsxTransformContext,
 	JsxTransformOptions,
 	JsxTransformResult,
 	componentToFunctionDeclaration,
 	createJsxTransform,
 } from './jsx-platform';
 
-export type { Parse, JsxPlatform, JsxPlatformHooks, JsxTransformOptions, JsxTransformResult };
+export type {
+	Parse,
+	JsxPlatform,
+	JsxPlatformHooks,
+	JsxTransformContext,
+	JsxTransformOptions,
+	JsxTransformResult,
+};
 export { createJsxTransform, componentToFunctionDeclaration };
 
 /**

package/types/jsx-platform.d.ts

@@ -1,5 +1,6 @@
 import type * as AST from 'estree';
 import type { RawSourceMap } from 'source-map';
+import type { CompileError } from './index';
 
 /**
  * Result returned by a JSX platform transform (React, Preact, Solid).
@@ -16,6 +17,38 @@ export interface JsxTransformResult {
 	css: { code: string; hash: string } | null;
 }
 
+/**
+ * Shared base for the per-call transform context that the JSX factory passes
+ * into every visitor and helper. Platform-specific transforms (e.g. Solid)
+ * extend this with their own `needs_*` flags via `hooks.initialState`; helpers
+ * defined in `@tsrx/core` only ever rely on these base fields.
+ */
+export interface JsxTransformContext {
+	platform: JsxPlatform;
+	local_statement_component_index: number;
+	needs_error_boundary: boolean;
+	needs_suspense: boolean;
+	needs_merge_refs: boolean;
+	helper_state: {
+		base_name: string;
+		next_id: number;
+		helpers: any[];
+		statics: any[];
+	} | null;
+	available_bindings: Map<string, AST.Identifier>;
+	lazy_next_id: number;
+	current_css_hash: string | null;
+	inside_element_child?: boolean;
+	/** Source filename for diagnostics; null when the caller did not supply one. */
+	filename: string | null;
+	/** True when recoverable errors should be collected onto `errors` instead of thrown. */
+	loose: boolean;
+	/** Collected non-fatal errors. Undefined when `loose` is false. */
+	errors: CompileError[] | undefined;
+	/** Module-level comments used to honor `@tsrx-ignore` / `@tsrx-expect-error`. */
+	comments: AST.CommentWithLocation[] | undefined;
+}
+
 /**
  * Optional per-call compile options passed to a created JSX transform.
  */
@@ -26,6 +59,22 @@ export interface JsxTransformOptions {
 	 * host pick `preact/compat` vs. another compat entry point.
 	 */
 	suspenseSource?: string;
+	/**
+	 * When true, recoverable transform errors are pushed onto `errors` instead
+	 * of thrown so editor tooling can surface them as diagnostics. Errors that
+	 * leave the transform in an unrecoverable state are still thrown.
+	 */
+	loose?: boolean;
+	/**
+	 * Collected non-fatal errors. The transform appends to this array when
+	 * `loose` is true; callers read it after the transform returns.
+	 */
+	errors?: CompileError[];
+	/**
+	 * Module-level comments used to suppress diagnostics via `@tsrx-ignore` /
+	 * `@tsrx-expect-error` line comments.
+	 */
+	comments?: AST.CommentWithLocation[];
 }
 
 /**
@@ -91,8 +140,10 @@ export interface JsxPlatformHooks {
 	injectImports?: (program: AST.Program, ctx: any, suspenseSource: string) => void;
 	/**
 	 * Transform a Ripple element's attributes to JSX attributes. Default
-	 * is "map over `to_jsx_attribute`". Solid replaces this to route
-	 * attributes through its composite-element handling.
+	 * is "map over `to_jsx_attribute`" plus the shared multi-`ref` merge
+	 * pass. Platforms that own a `transformElement` hook (e.g. Solid) bypass
+	 * this entirely — they never reach the dispatch path that would call
+	 * it — and run their own attribute pass inside their `transformElement`.
 	 */
 	transformElementAttributes?: (attrs: any[], ctx: any, element: any) => any[];
 	/**
@@ -194,6 +245,13 @@ export interface JsxPlatform {
 		 * block appears. Usually `'@tsrx/<platform>/error-boundary'`.
 		 */
 		errorBoundary: string;
+		/**
+		 * Module to import `mergeRefs` from when an element has more than one
+		 * `ref` attribute and the platform uses the `'merge-refs'` strategy.
+		 * Required when `jsx.multiRefStrategy === 'merge-refs'`; ignored
+		 * otherwise. React: `'@tsrx/react/merge-refs'`. Preact: `'@tsrx/preact/merge-refs'`.
+		 */
+		mergeRefs?: string;
 	};
 
 	jsx: {
@@ -207,6 +265,20 @@ export interface JsxPlatform {
 		 * only `'react'`. Preact accepts both `'preact'` and `'react'`.
 		 */
 		acceptedTsxKinds: readonly string[];
+		/**
+		 * How to collapse multiple `ref` attributes on the same element into
+		 * one. React's and Preact's runtimes treat duplicate `ref` props as
+		 * a normal duplicate-prop collision (last wins), so they need a
+		 * compile-time merge. Solid's runtime accepts an array of refs
+		 * natively, so it can use the cheaper array form.
+		 *
+		 * - `'merge-refs'`: emit `ref={mergeRefs(a, b, ...)}` and inject an
+		 *   import from `imports.mergeRefs`.
+		 * - `'array'`: emit `ref={[a, b, ...]}`. No runtime helper needed.
+		 * - `undefined`: no merging — duplicate `ref` attributes pass through
+		 *   unchanged. The platform's runtime is responsible.
+		 */
+		multiRefStrategy?: 'merge-refs' | 'array';
 	};
 
 	validation: {

package/types/runtime/merge-refs.d.ts

@@ -0,0 +1,12 @@
+export type MergeableRefCallback<T> = (node: T | null) => void | (() => void);
+export type MergeableRefObject<T> = { current: T | null };
+export type MergeableVueRef<T> = { value: T | null };
+
+export type MergeableRef<T> =
+	| MergeableRefCallback<T>
+	| MergeableRefObject<T>
+	| MergeableVueRef<T>
+	| null
+	| undefined;
+
+export function mergeRefs<T = any>(...refs: Array<MergeableRef<T>>): (node: T | null) => () => void;