@tsrx/core 0.0.18 → 0.0.20

package/README.md

@@ -35,194 +35,19 @@ const ast = parseModule(source, 'App.tsrx');
 The parser produces an ESTree-compatible AST, augmented with the TSRX node types
 listed below. Framework compilers walk this AST to emit their own output.
 
-## TSRX Specification (draft)
+## Language docs
 
-TSRX is a superset of TypeScript. All valid TypeScript is valid TSRX. TSRX adds
-the following productions.
+The TSRX website is the canonical source for language documentation:
 
-### 1. `component` declarations
+- [Getting Started](https://tsrx.dev/getting-started) — install TSRX for React,
+  Preact, Solid, Vue, or Ripple and configure editor/AI tooling.
+- [Features](https://tsrx.dev/features) — examples of components, statement
+  templates, control flow, scoped styles, server blocks, and lazy destructuring.
+- [Specification](https://tsrx.dev/specification) — the current grammar and
+  parser-level semantics.
 
-A `component` is a new top-level and expression-level declaration form. It has the
-same shape as a function declaration, but is a distinct AST node (`Component`) so
-that framework compilers can treat it specially.
-
-```tsx
-component Button(props: Props) {
-  <button>{props.label}</button>
-}
-```
-
-- `component` may be used wherever `function` may be used (declaration,
-  expression, default export).
-- The body of a `component` may contain JSX-like elements as statements — see §3.
-- `component` is a contextual keyword. Use as an identifier is preserved in
-  non-declaration positions.
-
-### 2. JSX-as-statements
-
-Inside a `component` body, JSX elements are valid _statement_ forms. They describe
-rendered output and are not expressions — they have no value. Static text may be
-written as a direct double-quoted child; dynamic values and other JavaScript
-expressions stay inside `{}`.
-
-```tsx
-component Greeting() {
-  <h1>"Hello"</h1>
-  <p>"Welcome"</p>
-}
-```
-
-Only double quotes have direct-child text meaning. Single-quoted strings and
-template literals remain JavaScript expressions and must be written inside `{}`.
-
-Elsewhere (outside a `component` body), JSX remains an expression, as in standard
-JSX.
-
-### 4. Control-flow statements in `component` bodies
-
-Inside a `component` body, the standard JavaScript control-flow keywords `if`,
-`else`, `for`, `switch`, and `try` gain an additional role: their branches may
-contain JSX-as-statements (§2) describing conditionally- or repeatedly-rendered
-output. The keywords retain their usual JavaScript syntax — no new grammar is
-introduced — but framework compilers treat them as _reactive_ boundaries.
-
-```tsx
-component List(props: { items: Item[]; showHeader: boolean }) {
-  if (props.showHeader) {
-    <h1>"Items"</h1>
-  } else {
-    <h2>"(no header)"</h2>
-  }
-
-  for (const item of props.items) {
-    <li>{item.name}</li>
-  }
-
-  switch (props.items.length) {
-    case 0:
-      <p>"empty"</p>
-      break;
-    default:
-      <p>"has items"</p>
-  }
-
-  try {
-    <AsyncThing />
-  } catch (e) {
-    <pre>{String(e)}</pre>
-  }
-}
-```
-
-**Early returns.** A bare `return;` (or `return` at the end of a branch) is a
-valid statement inside a `component` body and short-circuits any remaining
-rendering in the current branch. This composes naturally with the control-flow
-forms above:
-
-```tsx
-component Page(props: { user: User | null }) {
-  if (props.user == null) {
-    <LoginPrompt />
-    return;
-  }
-
-  <Dashboard user={props.user} />
-}
-```
-
-Because a `component` body does not produce a value, `return` never carries an
-expression — it only marks a rendering short-circuit.
-
-**Nesting inside elements.** Control-flow statements may appear directly as
-children of a JSX element, not only at the top level of the component body. Their
-branches contribute children to the enclosing element in source order:
-
-```tsx
-component Menu(props: { items: Item[]; loading: boolean }) {
-  <ul>
-    if (props.loading) {
-      <li>{'loading…'}</li>
-    } else {
-      for (const item of props.items) {
-        <li>
-          <a href={item.href}>{item.label}</a>
-          if (item.badge) {
-            <span class="badge">{item.badge}</span>
-          }
-        </li>
-      }
-    }
-  </ul>
-}
-```
-
-Any control-flow form that is legal at the component-body level is also legal as a
-child of a JSX element, and may be nested to arbitrary depth.
-
-TSRX only describes what is syntactically permitted. The reactive semantics
-(dependency tracking, list reconciliation, error boundaries, suspense) are the
-responsibility of the framework compiler.
-
-### 5. JSX escape hatch: `<tsx>...</tsx>`
-
-Because JSX inside a `component` body is a _statement_ (§2), the element itself
-has no value. To embed regular _expression_-form JSX — e.g. when a third-party
-library accepts a JSX tree as a value — wrap it in the reserved `<tsx>` element.
-Its children are parsed as standard JSX expressions and the whole form evaluates
-to the JSX expression value (or an array of values if there are multiple
-children).
-
-```tsx
-component Page() {
-  const header = <tsx><h1>Hello</h1></tsx>;
-  renderSomewhereElse(header);
-}
-```
-
-`<tsx>` is a reserved tag name in TSRX. It has no runtime representation of its
-own — the framework compiler unwraps it into the underlying JSX expression.
-
-### 6. Lazy destructuring: `&[]` and `&{}`
-
-Two new destructuring forms prefixed with `&` bind by _reference_ rather than by
-value. Each bound name compiles to a lazy property lookup on the source, so reads
-and writes are deferred to the use-site.
-
-```tsx
-let &[count] = source;        // array-style lazy destructure
-let &{ name, age } = props;   // object-style lazy destructure
-```
-
-Semantics are provided by the framework compiler. TSRX only defines the syntax and
-the AST shape (`kind: 'lazy'` binding patterns).
-
-### 7. `#server` blocks
-
-A `#server { ... }` block marks a lexical region whose contents are intended for
-the server compile target. TSRX parses the block and records its exports;
-framework compilers decide how to emit or strip it per target.
-
-```ts
-#server {
-  export async function load() { /* ... */ }
-}
-```
-
-### 8. `#style` identifier
-
-`#style` is a reserved identifier that refers, at compile time, to the set of
-scoped CSS classes declared in the current module. It is legal only in positions
-where the framework compiler expects a class-name value.
-
-```tsx
-<div class={#style.card} />
-```
-
-### 9. Scoped CSS blocks
-
-A `component` may contain a trailing CSS block (delimited by the framework
-compiler's chosen grammar). The block is parsed into a `CSS.StyleSheet` AST node
-and hashed for scoping.
+Keeping the language reference on the website avoids duplicating the specification
+here and keeps package docs focused on the core parser API.
 
 ## What `@tsrx/core` provides
 

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "type": "module",
   "repository": {
     "type": "git",
@@ -28,6 +28,7 @@
       "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",

package/src/diagnostics.js

@@ -0,0 +1,7 @@
+export const DIAGNOSTIC_CODES = {
+	JSX_EXPRESSION_VALUE: 'tsrx-jsx-expression-value',
+	JSX_RETURN_IN_COMPONENT: 'tsrx-jsx-return-in-component',
+	FUNCTION_COMPONENT_SYNTAX: 'tsrx-function-component-syntax',
+	UNCLOSED_TAG: 'tsrx-unclosed-tag',
+	MISMATCHED_CLOSING_TAG: 'tsrx-mismatched-closing-tag',
+};

package/src/errors.js

@@ -10,9 +10,10 @@
  * @param {AST.Node | AST.NodeWithLocation} node
  * @param {CompileError[]} [errors]
  * @param {AST.CommentWithLocation[]} [comments]
+ * @param {string} [code]
  * @returns {void}
  */
-export function error(message, filename, node, errors, comments) {
+export function error(message, filename, node, errors, comments, code) {
 	if (errors && comments && is_error_suppressed(node, comments)) {
 		return;
 	}
@@ -25,6 +26,7 @@ export function error(message, filename, node, errors, comments) {
 
 	// custom properties
 	error.fileName = filename;
+	error.code = code;
 	error.end = node.end ?? undefined;
 	error.loc = !node.loc
 		? undefined

package/src/index.js

@@ -24,6 +24,7 @@ export { create_scopes as createScopes, ScopeRoot, Scope } from './scope.js';
 
 // Errors
 export { error } from './errors.js';
+export { DIAGNOSTIC_CODES } from './diagnostics.js';
 
 // Constants
 export {

package/src/parse/index.js

@@ -201,7 +201,8 @@ export function createParser(...plugins) {
 	return function parse(source, filename, options) {
 		/** @type {AST.CommentWithLocation[]} */
 		const comments = [];
-		const output_comments = options?.comments;
+		const collect = !!(options?.collect || options?.loose);
+		const output_comments = collect ? options?.comments : undefined;
 
 		const { onComment, add_comments } = get_comment_handlers(source, comments);
 		/** @type {AST.Program} */
@@ -216,7 +217,8 @@ export function createParser(...plugins) {
 				onComment,
 				tsrxOptions: {
 					filename,
-					errors: options?.errors ?? [],
+					collect,
+					errors: collect ? (options?.errors ?? []) : undefined,
 					loose: options?.loose || false,
 				},
 			});

package/src/plugin.js

@@ -15,6 +15,10 @@ import {
 } from './parse/index.js';
 import { regex_newline_characters } from './utils/patterns.js';
 import { error } from './errors.js';
+import { DIAGNOSTIC_CODES } from './diagnostics.js';
+
+const JSX_EXPRESSION_VALUE_ERROR =
+	'JSX elements cannot be used as expressions. Wrap with `<>...</>` or `<tsx>...</tsx>` or use elements as statements within a component.';
 
 /** @type {WeakMap<Record<string, boolean>, Map<string, number>>} */
 const argument_clash_first_positions = new WeakMap();
@@ -153,6 +157,35 @@ function looks_like_generic_arrow(input, pos) {
 	return input.charCodeAt(i) === 61 && input.charCodeAt(i + 1) === 62;
 }
 
+/**
+ * @param {AST.Node | null | undefined} node
+ * @returns {boolean}
+ */
+function is_pascal_case_function(node) {
+	if (node && 'id' in node && node.id && node.id.type === 'Identifier') {
+		return /^[A-Z]/.test(node.id.name);
+	}
+	return false;
+}
+
+/**
+ * @param {string} input
+ * @param {number} pos
+ */
+function previous_word_before(input, pos) {
+	let i = pos - 1;
+	while (i >= 0) {
+		const ch = input.charCodeAt(i);
+		if (ch !== 32 && ch !== 9 && ch !== 10 && ch !== 13) break;
+		i--;
+	}
+	const end = i + 1;
+	while (i >= 0 && /[$_\p{ID_Continue}]/u.test(input[i])) {
+		i--;
+	}
+	return input.slice(i + 1, end);
+}
+
 /**
  * Acorn parser plugin for Ripple syntax extensions.
  * Adds support for: component declarations, &[]/&{} lazy destructuring,
@@ -178,7 +211,10 @@ export function TSRXPlugin(config) {
 			#allowTagStartAfterDoubleQuotedText = false;
 			#allowDoubleQuotedTextChildAfterBrace = false;
 			#commentContextId = 0;
+			#collect = false;
 			#loose = false;
+			/** @type {AST.Node[]} */
+			#functionStack = [];
 			/** @type {import('../types/index').CompileError[] | undefined} */
 			#errors = undefined;
 			/** @type {string | null} */
@@ -192,6 +228,7 @@ export function TSRXPlugin(config) {
 			constructor(options, input) {
 				super(options, input);
 				const tsrx_options = options?.tsrxOptions ?? options?.rippleOptions;
+				this.#collect = tsrx_options?.collect === true || tsrx_options?.loose === true;
 				this.#loose = tsrx_options?.loose === true;
 				this.#errors = tsrx_options?.errors;
 				this.#filename = tsrx_options?.filename || null;
@@ -274,8 +311,9 @@ export function TSRXPlugin(config) {
 			 * @param {number} position
 			 * @param {number} end
 			 * @param {string} message
+			 * @param {string} [code]
 			 */
-			#report_recoverable_error_range(position, end, message) {
+			#report_recoverable_error_range(position, end, message, code) {
 				const start = Math.max(0, Math.min(position, this.input.length));
 				const range_end = Math.max(start, Math.min(end, this.input.length));
 				const start_loc = acorn.getLineInfo(this.input, start);
@@ -292,20 +330,37 @@ export function TSRXPlugin(config) {
 							end: end_loc,
 						},
 					}),
-					this.#loose ? this.#errors : undefined,
+					this.#collect ? this.#errors : undefined,
+					undefined,
+					code,
 				);
 			}
 
 			/**
 			 * @param {number} position
 			 * @param {string} message
+			 * @param {string} [code]
+			 */
+			#report_recoverable_error(position, message, code) {
+				this.#report_recoverable_error_range(position, position + 1, message, code);
+			}
+
+			/**
+			 * @param {number} position
+			 * @param {string} message
+			 * @param {string} [code]
 			 */
-			#report_recoverable_error(position, message) {
-				this.#report_recoverable_error_range(position, position + 1, message);
+			#report_broken_markup_error(position, message, code = DIAGNOSTIC_CODES.UNCLOSED_TAG) {
+				if (this.#loose) return;
+				if (this.#collect) {
+					this.#report_recoverable_error(position, message, code);
+					return;
+				}
+				this.raise(position, message);
 			}
 
 			/**
-			 * In loose mode, keep parsing after duplicate declaration diagnostics so
+			 * When collecting, keep parsing after duplicate declaration diagnostics so
 			 * editor tooling can continue producing AST and mappings.
 			 * @param {number} position
 			 * @param {string | { message?: string }} message
@@ -339,7 +394,7 @@ export function TSRXPlugin(config) {
 			 */
 			reportReservedArrowTypeParam(node) {
 				// Allow <T>() => {} syntax without requiring trailing comma
-				if (this.#loose && node.params.length === 1 && node.extra?.trailingComma === undefined) {
+				if (this.#collect && node.params.length === 1 && node.extra?.trailingComma === undefined) {
 					error(
 						'This syntax is reserved in files with the .mts or .cts extension. Add a trailing comma, as in `<T,>() => ...`.',
 						this.#filename,
@@ -350,7 +405,7 @@ export function TSRXPlugin(config) {
 			}
 
 			/**
-			 * Override to allow `readonly` type modifier on any type in loose mode.
+			 * Override to allow `readonly` type modifier on any type when collecting.
 			 * By default, @sveltejs/acorn-typescript throws an error for `readonly { ... }`
 			 * because TypeScript only permits `readonly` on array and tuple types.
 			 * Suppress the error in the strict mode as ts is compiled away.
@@ -363,7 +418,7 @@ export function TSRXPlugin(config) {
 					return;
 				}
 
-				if (this.#loose) {
+				if (this.#collect) {
 					error(
 						"'readonly' type modifier is only permitted on array and tuple literal types.",
 						this.#filename,
@@ -607,21 +662,17 @@ export function TSRXPlugin(config) {
 			}
 
 			/**
-			 * Inside a component, `<T,>(x: T) => x` should parse as a generic arrow
-			 * function, not a JSX element. acorn-typescript's `readToken` would
-			 * otherwise tokenize `<` as `jsxTagStart` (when `exprAllowed` or the
-			 * context is `tc_expr`), bypassing our `getTokenFromCode` override. We
-			 * intercept here, but only when the source from `<` actually looks like
-			 * a generic arrow expression — so JSX like `<div>` keeps parsing normally.
+			 * `<T,>(x: T) => x` and `<T>(x: T): T => x` should parse as generic
+			 * arrow functions, not JSX elements. acorn-typescript's `readToken`
+			 * can otherwise tokenize `<` as `jsxTagStart` when expression parsing
+			 * allows JSX, bypassing our `getTokenFromCode` override. We intercept
+			 * only when the source from `<` actually looks like a generic arrow
+			 * expression, so JSX like `<div>` keeps parsing normally.
 			 *
 			 * @type {Parse.Parser['readToken']}
 			 */
 			readToken(code) {
-				if (
-					code === 60 &&
-					this.#path.findLast((n) => n.type === 'Component') &&
-					looks_like_generic_arrow(this.input, this.pos)
-				) {
+				if (code === 60 && looks_like_generic_arrow(this.input, this.pos)) {
 					++this.pos;
 					return this.finishToken(tt.relational, '<');
 				}
@@ -854,15 +905,15 @@ export function TSRXPlugin(config) {
 			}
 
 			/**
-			 * Acorn reports only the second duplicate function parameter. In loose
-			 * mode, report the first one too so editor diagnostics can underline both
+			 * Acorn reports only the second duplicate function parameter. When collecting,
+			 * report the first one too so editor diagnostics can underline both
 			 * binding sites. Keep strict mode on Acorn's normal fatal path.
 			 *
 			 * @type {Parse.Parser['checkLValSimple']}
 			 */
 			checkLValSimple(expr, bindingType = BINDING_TYPES.BIND_NONE, checkClashes) {
 				if (
-					this.#loose &&
+					this.#collect &&
 					expr.type === 'Identifier' &&
 					bindingType !== BINDING_TYPES.BIND_NONE &&
 					checkClashes
@@ -1298,10 +1349,12 @@ export function TSRXPlugin(config) {
 			 */
 			parseFunctionBody(node, isArrowFunction, isMethod, forInit, ...args) {
 				this.#functionBodyDepth++;
+				this.#functionStack.push(node);
 
 				try {
 					return super.parseFunctionBody(node, isArrowFunction, isMethod, forInit, ...args);
 				} finally {
+					this.#functionStack.pop();
 					this.#functionBodyDepth--;
 				}
 			}
@@ -1849,10 +1902,16 @@ export function TSRXPlugin(config) {
 					);
 				}
 
-				this.raise(
-					this.start,
-					'JSX elements cannot be used as expressions. Wrap with `<tsx>...</tsx>` or use elements as statements within a component.',
-				);
+				const code = this.#functionStack.findLast(is_pascal_case_function)
+					? DIAGNOSTIC_CODES.FUNCTION_COMPONENT_SYNTAX
+					: this.#path.findLast((node) => node.type === 'Component') &&
+						  this.#functionStack.length === 0 &&
+						  previous_word_before(this.input, this.start) === 'return'
+						? DIAGNOSTIC_CODES.JSX_RETURN_IN_COMPONENT
+						: DIAGNOSTIC_CODES.JSX_EXPRESSION_VALUE;
+
+				this.#report_recoverable_error(this.start, JSX_EXPRESSION_VALUE_ERROR, code);
+				return super.jsx_parseElement();
 			}
 
 			/**
@@ -2051,12 +2110,10 @@ export function TSRXPlugin(config) {
 							this.#path.pop();
 						} else {
 							// No closing tag
-							if (!this.#loose) {
-								this.raise(
-									open.end,
-									"Unclosed tag '<script>'. Expected '</script>' before end of component.",
-								);
-							}
+							this.#report_broken_markup_error(
+								open.end,
+								"Unclosed tag '<script>'. Expected '</script>' before end of component.",
+							);
 							/** @type {AST.Element} */ (element).unclosed = true;
 							this.#path.pop();
 						}
@@ -2113,12 +2170,10 @@ export function TSRXPlugin(config) {
 							this.exprAllowed = false;
 							this.#path.pop();
 						} else {
-							if (!this.#loose) {
-								this.raise(
-									open.end,
-									"Unclosed tag '<style>'. Expected '</style>' before end of component.",
-								);
-							}
+							this.#report_broken_markup_error(
+								open.end,
+								"Unclosed tag '<style>'. Expected '</style>' before end of component.",
+							);
 							/** @type {AST.Element} */ (element).unclosed = true;
 							this.#path.pop();
 						}
@@ -2203,20 +2258,17 @@ export function TSRXPlugin(config) {
 							}
 						} else if (this.#path[this.#path.length - 1] === element) {
 							// Check if this element was properly closed
-							if (!this.#loose) {
-								const tagName = this.getElementName(element.id);
-								this.raise(
-									this.start,
-									`Unclosed tag '<${tagName}>'. Expected '</${tagName}>' before end of component.`,
-								);
-							} else {
-								element.unclosed = true;
-								element.loc.end = {
-									.../** @type {AST.SourceLocation} */ (element.openingElement.loc).end,
-								};
-								element.end = element.openingElement.end;
-								this.#path.pop();
-							}
+							const tagName = this.getElementName(element.id);
+							this.#report_broken_markup_error(
+								this.start,
+								`Unclosed tag '<${tagName}>'. Expected '</${tagName}>' before end of component.`,
+							);
+							element.unclosed = true;
+							element.loc.end = {
+								.../** @type {AST.SourceLocation} */ (element.openingElement.loc).end,
+							};
+							element.end = element.openingElement.end;
+							this.#path.pop();
 						}
 					}
 
@@ -2267,18 +2319,15 @@ export function TSRXPlugin(config) {
 
 					while (true) {
 						if (this.type === tt.eof || this.pos >= this.input.length || this.type === tt.braceR) {
-							if (!this.#loose) {
-								this.raise(
-									this.start,
-									`Unclosed tag '<tsx>'. Expected '</tsx>' before end of component.`,
-								);
-							} else {
-								inside_tsx.unclosed = true;
-								/** @type {AST.NodeWithLocation} */ (inside_tsx).loc.end = {
-									.../** @type {AST.SourceLocation} */ (inside_tsx.openingElement.loc).end,
-								};
-								inside_tsx.end = inside_tsx.openingElement.end;
-							}
+							this.#report_broken_markup_error(
+								this.start,
+								`Unclosed tag '<tsx>'. Expected '</tsx>' before end of component.`,
+							);
+							inside_tsx.unclosed = true;
+							/** @type {AST.NodeWithLocation} */ (inside_tsx).loc.end = {
+								.../** @type {AST.SourceLocation} */ (inside_tsx.openingElement.loc).end,
+							};
+							inside_tsx.end = inside_tsx.openingElement.end;
 							return;
 						}
 
@@ -2344,18 +2393,15 @@ export function TSRXPlugin(config) {
 
 					while (true) {
 						if (this.type === tt.eof || this.pos >= this.input.length || this.type === tt.braceR) {
-							if (!this.#loose) {
-								this.raise(
-									this.start,
-									`Unclosed tag '<tsx:${inside_tsx_compat.kind}>'. Expected '</tsx:${inside_tsx_compat.kind}>' before end of component.`,
-								);
-							} else {
-								inside_tsx_compat.unclosed = true;
-								/** @type {AST.NodeWithLocation} */ (inside_tsx_compat).loc.end = {
-									.../** @type {AST.SourceLocation} */ (inside_tsx_compat.openingElement.loc).end,
-								};
-								inside_tsx_compat.end = inside_tsx_compat.openingElement.end;
-							}
+							this.#report_broken_markup_error(
+								this.start,
+								`Unclosed tag '<tsx:${inside_tsx_compat.kind}>'. Expected '</tsx:${inside_tsx_compat.kind}>' before end of component.`,
+							);
+							inside_tsx_compat.unclosed = true;
+							/** @type {AST.NodeWithLocation} */ (inside_tsx_compat).loc.end = {
+								.../** @type {AST.SourceLocation} */ (inside_tsx_compat.openingElement.loc).end,
+							};
+							inside_tsx_compat.end = inside_tsx_compat.openingElement.end;
 							return;
 						}
 
@@ -2480,46 +2526,45 @@ export function TSRXPlugin(config) {
 						}
 
 						if (openingTagName !== closingTagName) {
-							if (!this.#loose) {
-								this.raise(
-									closingElement.start,
-									`Expected closing tag to match opening tag. Expected '</${openingTagName}>' but found '</${closingTagName}>'`,
-								);
-							} else {
-								// Loop through all unclosed elements on the stack
-								while (this.#path.length > 0) {
-									const elem = this.#path[this.#path.length - 1];
+							// this will throw if not collecting errors
+							this.#report_broken_markup_error(
+								closingElement.start,
+								`Expected closing tag to match opening tag. Expected '</${openingTagName}>' but found '</${closingTagName}>'`,
+								DIAGNOSTIC_CODES.MISMATCHED_CLOSING_TAG,
+							);
+							// Loop through all unclosed elements on the stack
+							while (this.#path.length > 0) {
+								const elem = this.#path[this.#path.length - 1];
 
-									// Stop at non-Element boundaries (Component, etc.)
-									if (elem.type !== 'Element' && elem.type !== 'Tsx' && elem.type !== 'TsxCompat') {
-										break;
-									}
+								// Stop at non-Element boundaries (Component, etc.)
+								if (elem.type !== 'Element' && elem.type !== 'Tsx' && elem.type !== 'TsxCompat') {
+									break;
+								}
 
-									const elemName =
-										elem.type === 'TsxCompat'
-											? 'tsx:' + elem.kind
-											: elem.type === 'Tsx'
-												? elem.openingElement.name
-													? 'tsx'
-													: null
-												: elem.id
-													? this.getElementName(elem.id)
-													: null;
-
-									// Found matching opening tag
-									if (elemName === closingTagName) {
-										break;
-									}
+								const elemName =
+									elem.type === 'TsxCompat'
+										? 'tsx:' + elem.kind
+										: elem.type === 'Tsx'
+											? elem.openingElement.name
+												? 'tsx'
+												: null
+											: elem.id
+												? this.getElementName(elem.id)
+												: null;
+
+								// Found matching opening tag
+								if (elemName === closingTagName) {
+									break;
+								}
 
-									// Mark as unclosed and adjust location
-									elem.unclosed = true;
-									/** @type {AST.NodeWithLocation} */ (elem).loc.end = {
-										.../** @type {AST.SourceLocation} */ (elem.openingElement.loc).end,
-									};
-									elem.end = elem.openingElement.end;
+								// Mark as unclosed and adjust location
+								elem.unclosed = true;
+								/** @type {AST.NodeWithLocation} */ (elem).loc.end = {
+									.../** @type {AST.SourceLocation} */ (elem.openingElement.loc).end,
+								};
+								elem.end = elem.openingElement.end;
 
-									this.#path.pop(); // Remove from stack
-								}
+								this.#path.pop(); // Remove from stack
 							}
 						}
 

package/src/scope.js

@@ -335,7 +335,7 @@ export class Scope {
 				`Cannot declare a variable named "${node.name}" as identifiers starting with "${IDENTIFIER_OBFUSCATION_PREFIX}" are reserved`,
 				this.#error_options.filename,
 				node,
-				this.#error_options.loose ? this.#error_options.errors : undefined,
+				this.#error_options.collect ? this.#error_options.errors : undefined,
 				this.#error_options.comments,
 			);
 		}
@@ -345,7 +345,7 @@ export class Scope {
 				`'${node.name}' has already been declared in the current scope`,
 				this.#error_options.filename,
 				node,
-				this.#error_options.loose ? this.#error_options.errors : undefined,
+				this.#error_options.collect ? this.#error_options.errors : undefined,
 				this.#error_options.comments,
 			);
 		}

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,18 +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,
- *   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,
- * }} 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
  */
 
 /**
@@ -95,11 +92,12 @@ export function createJsxTransform(platform) {
 		const module_uses_server_directive = should_scan_use_server_directive
 			? has_use_server_directive(ast)
 			: true;
+		const collect = !!(options?.collect || options?.loose);
 		/** @type {any[]} */
 		const stylesheets = [];
 
 		/** @type {TransformContext} */
-		const transform_context = /** @type {any} */ ({
+		const transform_context = {
 			platform,
 			local_statement_component_index: 0,
 			needs_error_boundary: false,
@@ -109,17 +107,26 @@ export function createJsxTransform(platform) {
 			available_bindings: new Map(),
 			lazy_next_id: 0,
 			current_css_hash: null,
+			filename: filename ?? null,
+			collect,
+			errors: collect ? 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);
 
 		walk(/** @type {any} */ (ast), transform_context, {
 			ReturnStatement(node, { next, path }) {
 				if (get_component_from_path(path)) {
-					validate_component_return_statement(node, filename);
+					validate_component_return_statement(
+						node,
+						filename,
+						transform_context.errors,
+						transform_context.comments,
+					);
 				}
 
 				return next();
@@ -143,9 +150,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,
 						);
 					}
 
@@ -212,10 +222,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))
 				);
 			},
 
@@ -1485,7 +1495,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);
@@ -2111,7 +2136,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':
@@ -2282,9 +2307,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,
 		);
 	}
 
@@ -2460,23 +2488,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,
 		);
 	}
 
@@ -2484,16 +2522,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,
 			);
 		}
 	}
@@ -2963,7 +3007,7 @@ 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);
+	validate_at_most_one_ref_attribute(attrs, transform_context);
 	const preprocess = transform_context.platform.hooks?.preprocessElementAttributes;
 	if (preprocess) {
 		attrs = preprocess(attrs, transform_context, element);
@@ -2987,9 +3031,11 @@ function transform_element_attributes_dispatch(attrs, transform_context, element
  * 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) {
-	let first = null;
+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 =
@@ -3002,14 +3048,25 @@ export function validate_at_most_one_ref_attribute(raw_attrs) {
 				attr.name.type === 'JSXIdentifier' &&
 				attr.name.name === 'ref');
 		if (!is_ref_attr) continue;
-		if (first) {
-			throw create_compile_error(
-				attr,
-				'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.",
-			);
+		refs.push(attr.name);
+	}
+	if (refs.length < 2) {
+		return;
+	}
+	for (let i = 0; i < refs.length; i++) {
+		const node = refs[i];
+		if (!transform_context?.collect && i === 0) {
+			// when not collecting, only throw on the second duplicate
+			continue;
 		}
-		first = attr;
+		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,
+		);
 	}
 }
 
@@ -3040,18 +3097,34 @@ export function merge_duplicate_refs(jsx_attrs, transform_context) {
 	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)) count += 1;
+		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);
 		}
@@ -3080,23 +3153,23 @@ export function merge_duplicate_refs(jsx_attrs, transform_context) {
 		transform_context.needs_merge_refs = true;
 	}
 
-	// The merged ref attribute is a synthesis of multiple input refs and
-	// has no single source position to map back to, so we omit `loc` for
-	// the same reason `to_jsx_attribute` does for `RefAttribute`-derived
-	// JSX attributes.
-	result.push(
+	// 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: 'JSXAttribute',
-			name: { type: 'JSXIdentifier', name: 'ref', metadata: { path: [] } },
-			value: {
-				type: 'JSXExpressionContainer',
-				expression: merged_value,
-				metadata: { path: [] },
-			},
-			shorthand: false,
+			type: 'JSXExpressionContainer',
+			expression: merged_value,
 			metadata: { path: [] },
 		}),
+		false,
+		source_attr,
 	);
+	result.push(merged_attr);
 
 	return result;
 }
@@ -3150,13 +3223,16 @@ export function to_jsx_attribute(attr, transform_context) {
 		// 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: [] },
+				metadata: { path: [], from_ref_keyword: true },
 			}),
 			attr,
 		);
@@ -3189,13 +3265,7 @@ export 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;
@@ -3360,16 +3430,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,19 +8,28 @@ 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 };
 
 /**
  * Compile error interface
  */
 export interface CompileError extends Error {
+	code: string | undefined;
 	pos: number | undefined;
 	raisedAt: number | undefined;
 	end: number | undefined;
@@ -42,6 +51,11 @@ export interface CompileOptions {
 	 * When true, non-fatal errors are collected on the result's `errors`
 	 * array instead of being thrown. Defaults to false (strict mode: throws).
 	 */
+	collect?: boolean;
+	/**
+	 * Enables editor-oriented parser recovery such as incomplete markup.
+	 * Also collects non-fatal errors as `collect`.
+	 */
 	loose?: boolean;
 }
 
@@ -1141,6 +1155,7 @@ export interface ParseError {
  * Parse options
  */
 export interface ParseOptions {
+	collect?: boolean;
 	loose?: boolean;
 	errors?: CompileError[];
 	comments?: AST.CommentWithLocation[];
@@ -1270,7 +1285,7 @@ export interface ScopeConstructorInterface {
 	parent: ScopeInterface | null;
 	porous: boolean;
 	error_options: {
-		loose: boolean;
+		collect: boolean;
 		errors: CompileError[];
 		filename: string;
 		comments?: AST.CommentWithLocation[];
@@ -1363,7 +1378,7 @@ export interface AnalysisState extends BaseState {
 	};
 	elements?: AST.Element[];
 	function_depth?: number;
-	loose?: boolean;
+	collect?: boolean;
 	configured_compat_kinds?: Set<string>;
 	metadata: BaseStateMetaData & {
 		styleClasses?: StyleClasses;
@@ -1574,7 +1589,7 @@ export interface CompileResult {
 	css: string;
 	/**
 	 * Non-fatal errors collected during compilation. Populated only when the
-	 * caller passes `loose: true`; empty otherwise.
+	 * caller passes `collect: true` or `loose: true`; empty otherwise.
 	 */
 	errors: CompileError[];
 }

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. */
+	collect: boolean;
+	/** Collected non-fatal errors. Undefined when `collect` 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,26 @@ 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.
+	 */
+	collect?: boolean;
+	/**
+	 * Don't collect allowable errors such as unclosed tags
+	 */
+	loose?: boolean;
+	/**
+	 * Collected non-fatal errors. The transform appends to this array when
+	 * `collect` or `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[];
 }
 
 /**

package/types/parse.d.ts

@@ -183,13 +183,15 @@ export namespace Parse {
 
 	export interface Options extends Omit<acorn.Options, 'onComment' | 'ecmaVersion'> {
 		tsrxOptions?: {
+			collect: boolean;
 			loose: boolean;
-			errors: CoreCompiler.CompileError[];
+			errors: CoreCompiler.CompileError[] | undefined;
 			filename: string | undefined;
 		};
 		rippleOptions?: {
+			collect: boolean;
 			loose: boolean;
-			errors: CoreCompiler.CompileError[];
+			errors: CoreCompiler.CompileError[] | undefined;
 			filename: string | undefined;
 		};
 		// The type has "latest" but it's converted to 1e8 at runtime

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;