@tsrx/core 0.0.27 → 0.0.28

package/package.json

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

package/src/index.js

@@ -141,8 +141,14 @@ export { escape, escape_script as escapeScript } from './utils/escaping.js';
 
 // Transform
 export {
+	add_jsx_setup_declaration as addJsxSetupDeclaration,
 	createJsxTransform,
+	CREATE_REF_PROP_INTERNAL_NAME,
+	extract_jsx_setup_declarations as extractJsxSetupDeclarations,
+	is_ref_prop_expression as isRefPropExpression,
+	MERGE_REFS_INTERNAL_NAME,
 	merge_duplicate_refs as mergeDuplicateRefs,
+	NORMALIZE_SPREAD_PROPS_INTERNAL_NAME,
 	rewrite_loop_continues_to_bare_returns as rewriteLoopContinuesToBareReturns,
 	to_jsx_attribute as toJsxAttribute,
 	validate_at_most_one_ref_attribute as validateAtMostOneRefAttribute,

package/src/plugin.js

@@ -1320,7 +1320,7 @@ export function TSRXPlugin(config) {
 					if (!nextChars) {
 						this.raise(
 							ref.start,
-							'"component" is a Ripple keyword and cannot be used as an identifier',
+							'"component" is a TSRX keyword and cannot be used as an identifier',
 						);
 					}
 				}
@@ -1345,6 +1345,21 @@ export function TSRXPlugin(config) {
 				let node = /** @type {ESTreeJSX.JSXExpressionContainer} */ (this.startNode());
 				this.next();
 
+				if (this.type === tt.name && this.value === 'ref') {
+					const ref_node = /** @type {AST.RefExpression} */ (this.startNode());
+					this.next();
+					if (this.type === tt.braceR) {
+						this.raise(
+							this.start,
+							'"ref" is a TSRX keyword and must be used in the form {ref item}',
+						);
+					}
+					ref_node.argument = this.parseMaybeAssign();
+					node.expression = /** @type {any} */ (this.finishNode(ref_node, 'RefExpression'));
+					this.expect(tt.braceR);
+					return this.finishNode(node, 'JSXExpressionContainer');
+				}
+
 				if (this.type === tt.name && this.value === 'html') {
 					node.html = true;
 					this.next();

package/src/runtime/language-helpers.js

@@ -0,0 +1,57 @@
+/** @type {typeof Object.getOwnPropertyDescriptor} */
+export var get_descriptor = Object.getOwnPropertyDescriptor;
+/** @type {typeof Object.getOwnPropertyDescriptors} */
+export var get_descriptors = Object.getOwnPropertyDescriptors;
+/** @type {typeof Array.from} */
+export var array_from = Array.from;
+/** @type {typeof Array.isArray} */
+export var is_array = Array.isArray;
+/** @type {typeof Object.defineProperty} */
+export var define_property = Object.defineProperty;
+/** @type {typeof Object.getPrototypeOf} */
+export var get_prototype_of = Object.getPrototypeOf;
+/** @type {typeof Object.values} */
+export var object_values = Object.values;
+/** @type {typeof Object.entries} */
+export var object_entries = Object.entries;
+/** @type {typeof Object.keys} */
+export var object_keys = Object.keys;
+/** @type {typeof Object.getOwnPropertySymbols} */
+export var get_own_property_symbols = Object.getOwnPropertySymbols;
+/** @type {typeof structuredClone} */
+export var structured_clone = structuredClone;
+/** @type {typeof Object.prototype} */
+export var object_prototype = Object.prototype;
+/** @type {typeof Array.prototype} */
+export var array_prototype = Array.prototype;
+/** @type {typeof Object.prototype.hasOwnProperty} */
+export var has_own_property = object_prototype.hasOwnProperty;
+
+/**
+ * @param {object} value
+ * @param {PropertyKey} key
+ * @returns {boolean}
+ */
+export function has_prototype_accessor(value, key) {
+	var proto = get_prototype_of(value);
+	while (proto != null) {
+		var descriptor = get_descriptor(proto, key);
+		if (descriptor !== undefined) {
+			return typeof descriptor.get === 'function' || typeof descriptor.set === 'function';
+		}
+		proto = get_prototype_of(proto);
+	}
+	return false;
+}
+
+/**
+ * Slice helper for arrays and array-like values.
+ * @param {ArrayLike<any>} array_like
+ * @param {...number} args
+ * @returns {any[]}
+ */
+export function array_slice(array_like, ...args) {
+	return is_array(array_like)
+		? array_like.slice(...args)
+		: array_prototype.slice.call(array_like, ...args);
+}

package/src/runtime/ref.js

@@ -0,0 +1,250 @@
+import {
+	has_own_property,
+	get_descriptor,
+	has_prototype_accessor,
+} from '@tsrx/core/runtime/language-helpers';
+
+const REF_VALUE = Symbol();
+
+/**
+ * Merge multiple refs (function refs and ref objects) into a single
+ * callback ref. Used by React, Preact, and Vue targets when an element has
+ * more than one `ref` attribute.
+ * This is a public method and also used by the compiler to unite any refs with
+ * any of the supported syntaxes.  It does not process spreads, that is delegated to
+ * `normalize_spread_props`.
+ *
+ * @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 (is_ref_object(ref, 'current')) {
+				/** @type {{ current: any }} */ (ref).current = node;
+				cleanups.push(() => {
+					/** @type {{ current: any }} */ (ref).current = null;
+				});
+			} else if (is_ref_object(ref, 'value')) {
+				/** @type {{ value: any }} */ (ref).value = node;
+				cleanups.push(() => {
+					/** @type {{ value: any }} */ (ref).value = null;
+				});
+			}
+		}
+		return () => {
+			for (const cleanup of cleanups) cleanup();
+		};
+	};
+}
+
+export { is_ref_prop as isRefProp };
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function is_ref_prop(value) {
+	return typeof value === 'function' && REF_VALUE in value;
+}
+
+/**
+ * @param {any} ref_value
+ * @param {any} node
+ * @param {(value: any) => void} [set_ref_value]
+ * @returns {void | (() => void)}
+ */
+export function apply_ref_value(ref_value, node, set_ref_value) {
+	if (typeof ref_value === 'function') {
+		return ref_value(node);
+	}
+
+	if (ref_value && typeof ref_value === 'object') {
+		if (is_ref_object(ref_value, 'current')) {
+			ref_value.current = node;
+			return () => {
+				ref_value.current = null;
+			};
+		}
+
+		if (is_ref_object(ref_value, 'value')) {
+			ref_value.value = node;
+			return () => {
+				ref_value.value = null;
+			};
+		}
+	}
+
+	if (set_ref_value !== undefined) {
+		set_ref_value(node);
+	}
+}
+
+/**
+ * @param {() => any} get_ref_value
+ * @param {(value: any) => void} [set_ref_value]
+ * @returns {(node: any) => void | (() => void)}
+ */
+export function create_ref_prop(get_ref_value, set_ref_value) {
+	/**
+	 * @param {any} node
+	 * @returns {void | (() => void)}
+	 */
+	function ref_prop_callback(node) {
+		const ref_value = get_ref_value();
+		const cleanup = apply_ref_value(ref_value, node, set_ref_value);
+		if (typeof cleanup === 'function' || node === null) {
+			return cleanup;
+		}
+		return () => {
+			apply_ref_value(ref_value, null, set_ref_value);
+		};
+	}
+
+	Object.defineProperty(ref_prop_callback, REF_VALUE, {
+		value: 'ref_value',
+		enumerable: false,
+	});
+
+	return ref_prop_callback;
+}
+
+/**
+ * @param {...any} refs
+ * @returns {any}
+ */
+export function merge_ref_props(...refs) {
+	const filtered = refs.filter((ref) => ref != null);
+
+	if (filtered.length === 0) {
+		return undefined;
+	}
+
+	if (filtered.length === 1) {
+		return filtered[0];
+	}
+
+	/**
+	 * @param {any} node
+	 * @returns {void | (() => void)}
+	 */
+	function merged_ref_prop(node) {
+		/** @type {Array<() => void>} */
+		const cleanups = [];
+
+		for (const ref of filtered) {
+			const cleanup = apply_ref_value(ref, node);
+			if (typeof cleanup === 'function') {
+				cleanups.push(cleanup);
+			} else if (typeof ref === 'function' && node !== null) {
+				cleanups.push(() => ref(null));
+			}
+		}
+
+		return () => {
+			for (const cleanup of cleanups) {
+				cleanup();
+			}
+		};
+	}
+
+	return merged_ref_prop;
+}
+
+/**
+ * @param {Record<string | symbol, any> | null | undefined} props
+ * @param {...any} outer_refs
+ * @returns {Record<string | symbol, any> | null | undefined}
+ */
+export function normalize_spread_props(props, ...outer_refs) {
+	if (props == null) {
+		return props;
+	}
+
+	/** @type {any[]} */
+	const refs = [];
+	/** @type {Record<string | symbol, any>} */
+	let next = {};
+	let changed = false;
+	let existing_ref;
+
+	for (const key of Reflect.ownKeys(props)) {
+		const descriptor = get_descriptor(props, key);
+		if (!descriptor?.enumerable) {
+			continue;
+		}
+
+		const value = /** @type {any} */ (props)[key];
+
+		if (key === 'ref') {
+			if (is_ref_prop(value)) {
+				refs.push(value);
+				changed = true;
+			} else {
+				existing_ref = value;
+			}
+			continue;
+		}
+
+		if (is_ref_prop(value)) {
+			refs.push(value);
+			changed = true;
+			continue;
+		}
+
+		next[key] = value;
+	}
+
+	if (!changed && outer_refs.length === 0) {
+		return props;
+	}
+
+	const merged_ref = merge_ref_props(existing_ref, ...refs, ...outer_refs);
+	if (merged_ref !== undefined) {
+		next.ref = merged_ref;
+	}
+
+	return next;
+}
+
+/**
+ * @param {object} value
+ * @param {'current' | 'value'} key
+ * @returns {boolean}
+ */
+function is_ref_object(value, key) {
+	if (is_dom_node(value)) {
+		return false;
+	}
+	if (key === 'value' && '__v_isRef' in value) {
+		return true;
+	}
+	if (has_own_property.call(value, key)) {
+		return true;
+	}
+	return key === 'value' && has_prototype_accessor(value, 'value');
+}
+
+/**
+ * @param {object} value
+ * @returns {boolean}
+ */
+function is_dom_node(value) {
+	return (
+		(typeof Node !== 'undefined' && value instanceof Node) ||
+		('nodeType' in value &&
+			typeof (/** @type {{ nodeType?: unknown }} */ (value).nodeType) === 'number' &&
+			'nodeName' in value &&
+			typeof (/** @type {{ nodeName?: unknown }} */ (value).nodeName) === 'string')
+	);
+}

package/src/transform/jsx/ast-builders.js

@@ -143,7 +143,7 @@ export function identifier_to_jsx_name(id) {
 			/** @type {any} */ ({
 				type: 'JSXIdentifier',
 				name: id.name,
-				metadata: { path: [], is_component: /^[A-Z]/.test(id.name) },
+				metadata: { ...(id.metadata || {}), path: [], is_component: /^[A-Z]/.test(id.name) },
 			}),
 			id,
 		);
@@ -376,26 +376,26 @@ export function to_text_expression(expression, source_node = expression) {
 }
 
 /**
- * Deep-clone an AST subtree. `loc` / `start` / `end` are shallow-shared by
- * reference rather than recursed into — `loc` objects can contain back-refs
- * to sub-objects that would blow the stack with a naive deep clone, and
- * every other traversal in the targets treats these positional keys as
- * shared.
+ * Deep-clone an AST subtree.
  *
  * @param {any} node
+ * @param {boolean} with_locations
  * @returns {any}
  */
-export function clone_expression_node(node) {
+export function clone_expression_node(node, with_locations = true) {
 	if (!node || typeof node !== 'object') return node;
-	if (Array.isArray(node)) return node.map(clone_expression_node);
-	const clone = { ...node };
-	for (const key of Object.keys(clone)) {
-		if (key === 'loc' || key === 'start' || key === 'end') continue;
+	if (Array.isArray(node)) return node.map((child) => clone_expression_node(child, with_locations));
+	const clone = /** @type {Record<string, any>} */ ({});
+
+	for (const key of Object.keys(node)) {
+		if (!with_locations && (key === 'loc' || key === 'start' || key === 'end')) {
+			continue;
+		}
 		if (key === 'metadata') {
-			clone.metadata = clone.metadata ? { ...clone.metadata } : { path: [] };
+			clone.metadata = node.metadata ? { ...node.metadata } : { path: [] };
 			continue;
 		}
-		clone[key] = clone_expression_node(clone[key]);
+		clone[key] = clone_expression_node(node[key], with_locations);
 	}
 	return clone;
 }

package/src/transform/jsx/index.js

@@ -169,6 +169,8 @@ export function createJsxTransform(platform) {
 			needs_error_boundary: false,
 			needs_suspense: false,
 			needs_merge_refs: false,
+			needs_ref_prop: false,
+			needs_normalize_spread_props: false,
 			needs_fragment: false,
 			module_scoped_hook_components:
 				options?.moduleScopedHookComponents ?? !!platform.hooks?.moduleScopedHookComponents,
@@ -382,13 +384,20 @@ export function createJsxTransform(platform) {
 
 			Tsx(node, { next, path }) {
 				const inner = /** @type {any} */ (next() ?? node);
-				return /** @type {any} */ (tsx_node_to_jsx_expression(inner, in_jsx_child_context(path)));
+				const in_jsx_child = in_jsx_child_context(path);
+				return /** @type {any} */ (
+					wrap_jsx_setup_declarations(tsx_node_to_jsx_expression(inner, in_jsx_child), in_jsx_child)
+				);
 			},
 
 			TsxCompat(node, { next, path, state }) {
 				const inner = /** @type {any} */ (next() ?? node);
+				const in_jsx_child = in_jsx_child_context(path);
 				return /** @type {any} */ (
-					tsx_compat_node_to_jsx_expression(inner, state, in_jsx_child_context(path))
+					wrap_jsx_setup_declarations(
+						tsx_compat_node_to_jsx_expression(inner, state, in_jsx_child),
+						in_jsx_child,
+					)
 				);
 			},
 
@@ -432,6 +441,27 @@ export function createJsxTransform(platform) {
 			FunctionDeclaration: ensure_function_metadata,
 			FunctionExpression: ensure_function_metadata,
 			ArrowFunctionExpression: ensure_function_metadata,
+
+			RefExpression(node) {
+				return create_ref_prop_call(node, transform_context);
+			},
+
+			JSXOpeningElement(node, { next }) {
+				const visited = next() || node;
+				const is_component = is_component_like_jsx_name(visited.name);
+				const attrs = normalize_named_ref_attributes(
+					visited.attributes || [],
+					!is_component,
+					transform_context,
+				);
+				return {
+					...visited,
+					attributes: merge_duplicate_refs(
+						normalize_host_ref_spreads(attrs, !is_component, transform_context),
+						transform_context,
+					),
+				};
+			},
 		});
 
 		const expanded = expand_component_helpers(/** @type {AST.Program} */ (transformed));
@@ -906,6 +936,7 @@ function build_render_statements(body_nodes, return_null_when_empty, transform_c
 
 		if (is_jsx_child(child)) {
 			const jsx = to_jsx_child(child, transform_context);
+			statements.push(...extract_jsx_setup_declarations(jsx));
 			if (interleaved && is_capturable_jsx_child(jsx)) {
 				const { declaration, reference } = captureJsxChild(jsx, capture_index++);
 				statements.push(declaration);
@@ -1576,9 +1607,7 @@ function create_component_return_statement(
 	map_render_node_locations = true,
 ) {
 	const cloned = render_nodes.map((node) =>
-		map_render_node_locations
-			? clone_expression_node(node)
-			: clone_expression_node_without_locations(node),
+		map_render_node_locations ? clone_expression_node(node) : clone_expression_node(node, false),
 	);
 
 	return set_loc(b.return(build_return_expression(cloned) || create_null_literal()), source_node);
@@ -1645,7 +1674,7 @@ function build_tail_helper(continuation_body, source_node, transform_context) {
  * @returns {any}
  */
 function clone_tail_invocation(tail_helper) {
-	return clone_expression_node_without_locations(tail_helper.component_element);
+	return clone_expression_node(tail_helper.component_element, false);
 }
 
 /**
@@ -2553,7 +2582,7 @@ function prepend_render_nodes_to_return_statement(node, render_nodes, inside_nes
  * @returns {any}
  */
 function combine_render_return_argument(render_nodes, return_argument) {
-	const combined = render_nodes.map((node) => clone_expression_node_without_locations(node));
+	const combined = render_nodes.map((node) => clone_expression_node(node, false));
 
 	if (return_argument != null && !is_null_literal(return_argument)) {
 		combined.push(return_argument_to_render_node(return_argument));
@@ -2586,30 +2615,6 @@ function is_null_literal(node) {
 	return node?.type === 'Literal' && node.value == null;
 }
 
-/**
- * @param {any} node
- * @returns {any}
- */
-function clone_expression_node_without_locations(node) {
-	if (!node || typeof node !== 'object') return node;
-	if (Array.isArray(node)) return node.map(clone_expression_node_without_locations);
-
-	const clone = { ...node };
-	delete clone.loc;
-	delete clone.start;
-	delete clone.end;
-
-	for (const key of Object.keys(clone)) {
-		if (key === 'metadata') {
-			clone.metadata = clone.metadata ? { ...clone.metadata } : { path: [] };
-			continue;
-		}
-		clone[key] = clone_expression_node_without_locations(clone[key]);
-	}
-
-	return clone;
-}
-
 const TEMPLATE_FRAGMENT_ERROR =
 	'JSX fragment syntax is not needed in TSRX templates. TSRX renders in immediate mode, so everything is already a fragment. Use `<>...</>` only within <tsx>...</tsx>.';
 
@@ -4201,30 +4206,79 @@ 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;
+	const merge_refs_source =
+		transform_context.needs_merge_refs && platform.imports.mergeRefs
+			? platform.imports.mergeRefs
+			: null;
+	const ref_prop_source =
+		transform_context.needs_ref_prop && platform.imports.refProp ? platform.imports.refProp : null;
+	const normalize_spread_props_source =
+		transform_context.needs_normalize_spread_props && platform.imports.refProp
+			? platform.imports.refProp
+			: null;
+
+	/** @type {Map<string, any[]>} */
+	const ref_imports = new Map();
+
+	if (merge_refs_source !== null) {
+		add_ref_import_specifier(ref_imports, merge_refs_source, {
+			type: 'ImportSpecifier',
+			imported: {
+				type: 'Identifier',
+				name: 'mergeRefs',
+				metadata: { path: [] },
+			},
+			local: {
+				type: 'Identifier',
+				name: MERGE_REFS_INTERNAL_NAME,
+				metadata: { path: [] },
+			},
+			metadata: { path: [] },
+		});
+	}
+
+	if (ref_prop_source !== null) {
+		add_ref_import_specifier(ref_imports, ref_prop_source, {
+			type: 'ImportSpecifier',
+			imported: {
+				type: 'Identifier',
+				name: 'create_ref_prop',
+				metadata: { path: [] },
+			},
+			local: {
+				type: 'Identifier',
+				name: CREATE_REF_PROP_INTERNAL_NAME,
+				metadata: { path: [] },
+			},
+			metadata: { path: [] },
+		});
+	}
+
+	if (normalize_spread_props_source !== null) {
+		add_ref_import_specifier(ref_imports, normalize_spread_props_source, {
+			type: 'ImportSpecifier',
+			imported: {
+				type: 'Identifier',
+				name: 'normalize_spread_props',
+				metadata: { path: [] },
+			},
+			local: {
+				type: 'Identifier',
+				name: NORMALIZE_SPREAD_PROPS_INTERNAL_NAME,
+				metadata: { path: [] },
+			},
+			metadata: { path: [] },
+		});
+	}
+
+	for (const [source, ref_specifiers] of ref_imports) {
 		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: [] },
-				},
-			],
+			specifiers: ref_specifiers,
 			source: {
 				type: 'Literal',
-				value: merge_refs_source,
-				raw: `'${merge_refs_source}'`,
+				value: source,
+				raw: `'${source}'`,
 			},
 			metadata: { path: [] },
 		});
@@ -4235,6 +4289,20 @@ function inject_try_imports(program, transform_context, platform, suspense_sourc
 	}
 }
 
+/**
+ * @param {Map<string, any[]>} imports
+ * @param {string} source
+ * @param {any} specifier
+ */
+function add_ref_import_specifier(imports, source, specifier) {
+	const specifiers = imports.get(source);
+	if (specifiers) {
+		specifiers.push(specifier);
+	} else {
+		imports.set(source, [specifier]);
+	}
+}
+
 /**
  * @param {any} node
  * @param {TransformContext} transform_context
@@ -4421,6 +4489,8 @@ function to_jsx_expression_container(expression, source_node = expression) {
  */
 function transform_element_attributes_dispatch(attrs, transform_context, element) {
 	validate_at_most_one_ref_attribute(attrs, transform_context);
+	const is_component = is_component_like_element(element);
+	attrs = normalize_named_ref_attributes(attrs, !is_component, transform_context);
 	const preprocess = transform_context.platform.hooks?.preprocessElementAttributes;
 	if (preprocess) {
 		attrs = preprocess(attrs, transform_context, element);
@@ -4429,7 +4499,238 @@ function transform_element_attributes_dispatch(attrs, transform_context, element
 	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);
+	return merge_duplicate_refs(
+		normalize_host_ref_spreads(result, !is_component, transform_context),
+		transform_context,
+	);
+}
+
+/**
+ * @param {any} element
+ * @returns {boolean}
+ */
+function is_component_like_element(element) {
+	const id = element?.id;
+	if (!id) return false;
+	if (id.type === 'Identifier') return /^[A-Z]/.test(id.name);
+	if (id.type === 'JSXIdentifier') return /^[A-Z]/.test(id.name);
+	if (id.type === 'MemberExpression') return true;
+	if (id.type === 'JSXMemberExpression') return true;
+	return false;
+}
+
+/**
+ * @param {any} name
+ * @returns {boolean}
+ */
+function is_component_like_jsx_name(name) {
+	if (!name) return false;
+	if (name.type === 'JSXIdentifier') return /^[A-Z]/.test(name.name);
+	if (name.type === 'JSXMemberExpression') return true;
+	return false;
+}
+
+/**
+ * @param {any[]} attrs
+ * @param {boolean} is_host
+ * @param {TransformContext} transform_context
+ * @returns {any[]}
+ */
+function normalize_named_ref_attributes(attrs, is_host, transform_context) {
+	if (!is_host) return attrs;
+
+	return attrs.map((attr) => {
+		if (!is_named_ref_attribute(attr)) {
+			return attr;
+		}
+
+		if (transform_context.typeOnly) {
+			return mark_type_only_named_ref_attribute(attr);
+		}
+
+		return {
+			...attr,
+			metadata: { ...(attr.metadata || {}), from_ref_keyword: true },
+			name:
+				attr.name?.type === 'JSXIdentifier'
+					? { ...attr.name, name: 'ref' }
+					: { type: 'Identifier', name: 'ref', metadata: { path: [] } },
+		};
+	});
+}
+
+/**
+ * @param {any} attr
+ * @returns {any}
+ */
+function mark_type_only_named_ref_attribute(attr) {
+	return {
+		...attr,
+		name: attr.name
+			? {
+					...attr.name,
+					metadata: { ...(attr.name.metadata || {}), disable_verification: true },
+				}
+			: attr.name,
+	};
+}
+
+/**
+ * @param {any[]} attrs
+ * @param {boolean} is_host
+ * @param {TransformContext} transform_context
+ * @returns {any[]}
+ */
+function normalize_host_ref_spreads(attrs, is_host, transform_context) {
+	if (!is_host) return attrs;
+
+	const needs_explicit_spread_ref =
+		transform_context.platform.jsx?.hostSpreadRefStrategy === 'explicit-ref-attr';
+	const ref_exprs = attrs
+		.filter((attr) => is_jsx_ref_attribute(attr))
+		.map((attr) => attr.value.expression);
+	const needs_synthetic_spread_ref = needs_explicit_spread_ref || ref_exprs.length > 0;
+
+	return attrs.flatMap((attr) => {
+		if (!attr || attr.type !== 'JSXSpreadAttribute') {
+			return [attr];
+		}
+
+		transform_context.needs_normalize_spread_props = true;
+		const normalized = b.call(NORMALIZE_SPREAD_PROPS_INTERNAL_NAME, attr.argument);
+
+		if (needs_synthetic_spread_ref) {
+			const normalized_id = create_generated_identifier(
+				create_spread_props_name(transform_context),
+			);
+			const spread = {
+				...attr,
+				argument: clone_identifier(normalized_id),
+			};
+			const ref_attr = b.jsx_attribute(
+				b.jsx_id('ref'),
+				to_jsx_expression_container(b.member(clone_identifier(normalized_id), 'ref'), attr),
+				false,
+				attr,
+			);
+			ref_attr.metadata = { ...(ref_attr.metadata || {}) };
+			/** @type {any} */ (ref_attr.metadata).from_ref_keyword = true;
+			add_jsx_setup_declaration(spread, b.let(clone_identifier(normalized_id), normalized));
+
+			return [spread, ref_attr];
+		}
+
+		return [
+			{
+				...attr,
+				argument: normalized,
+			},
+		];
+	});
+}
+
+/**
+ * @param {TransformContext} transform_context
+ * @returns {string}
+ */
+function create_spread_props_name(transform_context) {
+	if (transform_context.helper_state) {
+		return create_helper_name(transform_context.helper_state, 'spread_props');
+	}
+
+	transform_context.local_statement_component_index += 1;
+	return `_tsrx_spread_props_${transform_context.local_statement_component_index}`;
+}
+
+/**
+ * @param {any} node
+ * @param {any} declaration
+ */
+export function add_jsx_setup_declaration(node, declaration) {
+	node.metadata ??= { path: [] };
+	(node.metadata.generated_setup_declarations ??= []).push(declaration);
+}
+
+/**
+ * @param {any} node
+ * @param {Set<any>} [seen]
+ * @returns {any[]}
+ */
+export function extract_jsx_setup_declarations(node, seen = new Set()) {
+	if (node == null || typeof node !== 'object' || seen.has(node)) {
+		return [];
+	}
+	seen.add(node);
+
+	const declarations = node.metadata?.generated_setup_declarations ?? [];
+	if (node.metadata?.generated_setup_declarations) {
+		delete node.metadata.generated_setup_declarations;
+	}
+
+	for (const key of Object.keys(node)) {
+		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') {
+			continue;
+		}
+		declarations.push(...extract_jsx_setup_declarations(node[key], seen));
+	}
+
+	return declarations;
+}
+
+/**
+ * @param {any} expression
+ * @param {boolean} in_jsx_child
+ * @returns {any}
+ */
+function wrap_jsx_setup_declarations(expression, in_jsx_child) {
+	const declarations = extract_jsx_setup_declarations(expression);
+	if (declarations.length === 0) {
+		return expression;
+	}
+
+	const return_expression =
+		expression?.type === 'JSXExpressionContainer' ? expression.expression : expression;
+	const call = b.call(
+		b.arrow(
+			[],
+			b.block([...declarations, b.return(return_expression)], expression),
+			false,
+			expression,
+		),
+	);
+
+	return in_jsx_child ? to_jsx_expression_container(call, expression) : call;
+}
+
+/**
+ * @param {any} attr
+ * @returns {boolean}
+ */
+function is_named_ref_attribute(attr) {
+	return !!(
+		attr &&
+		(attr.type === 'Attribute' || attr.type === 'JSXAttribute') &&
+		attr.name &&
+		((attr.name.type === 'Identifier' && attr.name.name !== 'ref') ||
+			(attr.name.type === 'JSXIdentifier' && attr.name.name !== 'ref')) &&
+		(attr.value?.type === 'RefExpression' ||
+			is_ref_prop_expression(attr.value) ||
+			(attr.value?.type === 'JSXExpressionContainer' &&
+				is_ref_prop_expression(attr.value.expression)))
+	);
+}
+
+/**
+ * @param {any} expression
+ * @returns {boolean}
+ */
+export function is_ref_prop_expression(expression) {
+	return (
+		expression?.type === 'RefExpression' ||
+		(expression?.type === 'CallExpression' &&
+			expression.callee?.type === 'Identifier' &&
+			expression.callee.name === CREATE_REF_PROP_INTERNAL_NAME)
+	);
 }
 
 /**
@@ -4549,7 +4850,7 @@ export function merge_duplicate_refs(jsx_attrs, transform_context) {
 					type: 'CallExpression',
 					callee: {
 						type: 'Identifier',
-						name: MERGE_REFS_LOCAL_NAME,
+						name: MERGE_REFS_INTERNAL_NAME,
 						metadata: { path: [] },
 					},
 					arguments: ref_exprs,
@@ -4610,7 +4911,9 @@ function is_jsx_ref_attribute(attr) {
  * double-underscore matches the convention for compiler-generated
  * identifiers and avoids shadowing user-declared `mergeRefs` symbols.
  */
-const MERGE_REFS_LOCAL_NAME = '__mergeRefs';
+export const MERGE_REFS_INTERNAL_NAME = '__mergeRefs';
+export const CREATE_REF_PROP_INTERNAL_NAME = '__create_ref_prop';
+export const NORMALIZE_SPREAD_PROPS_INTERNAL_NAME = '__normalize_spread_props';
 
 /**
  * @param {any} attr
@@ -4619,7 +4922,31 @@ const MERGE_REFS_LOCAL_NAME = '__mergeRefs';
  */
 export function to_jsx_attribute(attr, transform_context) {
 	if (!attr) return attr;
-	if (attr.type === 'JSXAttribute' || attr.type === 'JSXSpreadAttribute') {
+	if (attr.type === 'JSXAttribute') {
+		if (
+			attr.value?.type === 'JSXExpressionContainer' &&
+			attr.value.expression?.type === 'RefExpression'
+		) {
+			return {
+				...attr,
+				value: to_jsx_expression_container(
+					create_ref_prop_call(attr.value.expression, transform_context),
+				),
+				metadata: { ...(attr.metadata || {}), from_ref_keyword: true },
+			};
+		}
+		if (
+			attr.value?.type === 'JSXExpressionContainer' &&
+			is_ref_prop_expression(attr.value.expression)
+		) {
+			return {
+				...attr,
+				metadata: { ...(attr.metadata || {}), from_ref_keyword: true },
+			};
+		}
+		return attr;
+	}
+	if (attr.type === 'JSXSpreadAttribute') {
 		return attr;
 	}
 	if (attr.type === 'SpreadAttribute') {
@@ -4670,15 +4997,28 @@ export function to_jsx_attribute(attr, transform_context) {
 		attr_name && attr_name.type === 'Identifier' ? identifier_to_jsx_name(attr_name) : attr_name;
 
 	let value = attr.value;
+	const is_ref_expression_value =
+		value?.type === 'RefExpression' ||
+		is_ref_prop_expression(value) ||
+		(value?.type === 'JSXExpressionContainer' && is_ref_prop_expression(value.expression));
 	if (value) {
 		if (value.type === 'Literal' && typeof value.value === 'string') {
 			// Keep string literal as attribute string.
+		} else if (value.type === 'RefExpression') {
+			value = to_jsx_expression_container(create_ref_prop_call(value, transform_context));
 		} else if (value.type !== 'JSXExpressionContainer') {
 			value = to_jsx_expression_container(value);
+		} else if (value.expression?.type === 'RefExpression') {
+			value = to_jsx_expression_container(
+				create_ref_prop_call(value.expression, transform_context),
+			);
 		}
 	}
 
 	const jsx_attribute = build_jsx_attribute(name, value || null, attr.shorthand === true);
+	if (is_ref_expression_value) {
+		/** @type {any} */ (jsx_attribute.metadata).from_ref_keyword = true;
+	}
 
 	if (value_has_unmappable_jsx_loc(value)) {
 		/** @type {any} */ (jsx_attribute.metadata).has_unmappable_value = true;
@@ -4700,6 +5040,35 @@ function value_has_unmappable_jsx_loc(value) {
 	);
 }
 
+/**
+ * @param {any} node
+ * @param {TransformContext} transform_context
+ * @returns {any}
+ */
+function create_ref_prop_call(node, transform_context) {
+	transform_context.needs_ref_prop = true;
+
+	const argument = node.argument;
+	const args = [b.thunk(argument)];
+
+	if (argument.type === 'Identifier' || argument.type === 'MemberExpression') {
+		args.push(
+			b.arrow(
+				[b.id('v')],
+				/** @type {any} */ ({
+					type: 'AssignmentExpression',
+					operator: '=',
+					left: clone_expression_node(argument, false),
+					right: b.id('v'),
+					metadata: { path: [] },
+				}),
+			),
+		);
+	}
+
+	return b.call(CREATE_REF_PROP_INTERNAL_NAME, ...args);
+}
+
 /**
  * @param {any} node
  * @param {TransformContext} transform_context

package/src/transform/segments.js

@@ -562,16 +562,17 @@ export function convert_source_map_to_mappings(
 			} else if (node.type === 'JSXIdentifier') {
 				// JSXIdentifiers can also be capitalized (for dynamic components)
 				if (node.loc && node.name) {
-					if (node.metadata?.is_capitalized) {
-						tokens.push({
-							source: node.metadata.source_name,
-							generated: node.name,
-							loc: node.loc,
-							metadata: {},
-						});
-					} else {
-						tokens.push({ source: node.name, generated: node.name, loc: node.loc, metadata: {} });
+					/** @type {Token} */
+					const token = {
+						source: node.metadata?.is_capitalized ? node.metadata.source_name : node.name,
+						generated: node.name,
+						loc: node.loc,
+						metadata: {},
+					};
+					if (node.metadata?.disable_verification) {
+						token.mappingData = { ...mapping_data, verification: false };
 					}
+					tokens.push(token);
 				}
 				return; // Leaf node, don't traverse further
 			} else if (node.type === 'Literal') {
@@ -866,6 +867,15 @@ export function convert_source_map_to_mappings(
 					// 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];
+					if (!closing && opening.selfClosing) {
+						const generated_close_length = '/>;'.length;
+						mapping.sourceOffsets = [/** @type {AST.NodeWithLocation} */ (opening).end - 2];
+						mapping.lengths = ['/>'.length];
+						mapping.generatedOffsets = [
+							mapping.generatedOffsets[0] + mapping.generatedLengths[0] - generated_close_length,
+						];
+						mapping.generatedLengths = [generated_close_length];
+					}
 					mappings.push(mapping);
 				}
 

package/types/index.d.ts

@@ -213,6 +213,7 @@ declare module 'estree' {
 		Text: TextNode;
 		Attribute: Attribute;
 		RefAttribute: RefAttribute;
+		RefExpression: RefExpression;
 		SpreadAttribute: SpreadAttribute;
 		ParenthesizedExpression: ParenthesizedExpression;
 		ScriptContent: ScriptContent;
@@ -220,6 +221,7 @@ declare module 'estree' {
 
 	interface ExpressionMap {
 		Style: Style;
+		RefExpression: RefExpression;
 		Text: TextNode;
 		JSXEmptyExpression: ESTreeJSX.JSXEmptyExpression;
 		ParenthesizedExpression: ParenthesizedExpression;
@@ -437,6 +439,12 @@ declare module 'estree' {
 		loc?: AST.SourceLocation;
 	}
 
+	interface RefExpression extends AST.BaseNode {
+		type: 'RefExpression';
+		argument: AST.Expression;
+		loc?: AST.SourceLocation;
+	}
+
 	interface SpreadAttribute extends AST.BaseNode {
 		type: 'SpreadAttribute';
 		argument: AST.Expression;

package/types/jsx-platform.d.ts

@@ -36,6 +36,8 @@ export interface JsxTransformContext {
 	needs_error_boundary: boolean;
 	needs_suspense: boolean;
 	needs_merge_refs: boolean;
+	needs_ref_prop: boolean;
+	needs_normalize_spread_props: boolean;
 	needs_fragment: boolean;
 	module_scoped_hook_components: boolean;
 	helper_state: {
@@ -290,9 +292,14 @@ export interface JsxPlatform {
 		 * 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'`.
+		 * otherwise. React: `'@tsrx/react/ref'`. Preact: `'@tsrx/preact/ref'`.
 		 */
 		mergeRefs?: string;
+		/**
+		 * Module to import named-ref-prop helpers from when compiling
+		 * `prop={ref expr}` or normalizing host spreads containing named refs.
+		 */
+		refProp?: string;
 	};
 
 	jsx: {
@@ -320,6 +327,12 @@ export interface JsxPlatform {
 		 *   unchanged. The platform's runtime is responsible.
 		 */
 		multiRefStrategy?: 'merge-refs' | 'array';
+		/**
+		 * Some JSX runtimes do not apply a `ref` that arrives through a props
+		 * spread. In that case, host spread normalization also emits an
+		 * explicit `ref={normalized.ref}` attribute.
+		 */
+		hostSpreadRefStrategy?: 'explicit-ref-attr';
 	};
 
 	validation: {

package/types/runtime/ref.d.ts

@@ -0,0 +1,32 @@
+export type MergeableRefCallback<T> = {
+	bivarianceHack(node: T | null): void | (() => void);
+}['bivarianceHack'];
+export type MergeableRefObject<T> = { current: T | null };
+export type MergeableVueRef<T> = { value: T | null };
+export type RefProp<T = unknown> = (node: T | null) => void | (() => void);
+
+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;
+export function isRefProp(value: unknown): boolean;
+export function create_ref_prop<T>(
+	get_ref_value: () => T,
+	set_ref_value?: (value: T) => void,
+): RefProp<T>;
+export function apply_ref_value<T>(
+	ref_value: unknown,
+	node: T | null,
+	set_ref_value?: (value: T) => void,
+): void | (() => void);
+export function merge_ref_props<T = any>(
+	...refs: unknown[]
+): undefined | ((node: T | null) => void | (() => void));
+export function normalize_spread_props<T extends Record<PropertyKey, any> | null | undefined>(
+	props: T,
+	...outer_refs: unknown[]
+): T | Record<PropertyKey, any>;

package/src/runtime/merge-refs.js

@@ -1,61 +0,0 @@
-/**
- * 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/types/runtime/merge-refs.d.ts

@@ -1,12 +0,0 @@
-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;