@tsrx/core 0.1.58 → 0.1.59

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.1.58",
+  "version": "0.1.59",
   "type": "module",
   "repository": {
     "type": "git",
@@ -78,12 +78,14 @@
     "esrap": "^2.3.2",
     "is-reference": "^3.0.3",
     "magic-string": "^0.30.18",
-    "zimmerframe": "^1.1.2"
+    "zimmerframe": "^1.1.2",
+    "@tsrx/runtime": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
     "@typescript-eslint/types": "^8.40.0",
     "@volar/language-core": "~2.4.28",
+    "@volar/source-map": "~2.4.28",
     "typescript": "^5.9.3",
     "vite": "^8.1.5",
     "vscode-languageserver-types": "^3.17.5"

package/src/comment-utils.js

@@ -29,6 +29,14 @@ export function is_triple_slash_directive(comment) {
 	return /^\/\s*<(reference|amd-module|amd-dependency)/.test(value);
 }
 
+/**
+ * @param {AST.CommentWithLocation} comment
+ * @returns {boolean}
+ */
+export function is_jsdoc_comment(comment) {
+	return comment.type === 'Block' && comment.value.startsWith('*');
+}
+
 /**
  * Check if a comment is a JSDoc comment with TypeScript annotations
  * Examples: block comments containing `@type`, `@typedef`, `@param`, `@returns`, etc.
@@ -36,10 +44,7 @@ export function is_triple_slash_directive(comment) {
  * @returns {boolean}
  */
 export function is_jsdoc_ts_annotation(comment) {
-	if (comment.type !== 'Block') return false;
-
-	// JSDoc comments start with /** which means the value starts with * after /* is stripped
-	if (!comment.value.startsWith('*')) return false;
+	if (!is_jsdoc_comment(comment)) return false;
 
 	// Check if it contains TypeScript-relevant tags
 	const tsAnnotations = [
@@ -84,6 +89,36 @@ export function should_preserve_comment(comment) {
 	);
 }
 
+/**
+ * Declaration generators also consume documentation and custom `// @...`
+ * annotations from JSX-backed virtual TypeScript. Keep this broader policy
+ * separate from the legacy to_ts printer's semantic-comment policy.
+ * @param {AST.CommentWithLocation} comment
+ * @returns {boolean}
+ */
+export function should_preserve_jsx_tooling_comment(comment) {
+	return (
+		should_preserve_comment(comment) ||
+		is_jsdoc_comment(comment) ||
+		(comment.type === 'Line' && comment.value.trimStart().startsWith('@'))
+	);
+}
+
+/**
+ * Only file-wide directives may move ahead of generated imports or hoists.
+ * In particular, @ts-ignore/@ts-expect-error and declaration JSDoc must stay
+ * with the statement they describe.
+ * @param {AST.CommentWithLocation} comment
+ * @returns {boolean}
+ */
+export function is_file_level_pragma(comment) {
+	return (
+		is_jsx_pragma(comment) ||
+		is_triple_slash_directive(comment) ||
+		(comment.type === 'Line' && /^\s*@ts-(?:no)?check\b/.test(comment.value))
+	);
+}
+
 /**
  * Format a comment for output
  * @param {AST.CommentWithLocation} comment

package/src/runtime/iterable.js

@@ -1,112 +1 @@
-/**
- * @template T
- * @template U
- * @param {Iterable<T> | Iterator<T>} iterable
- * @param {(item: T, index: number, is_last: boolean) => U} fn
- * @param {() => U | U[]} [tail]
- * @param {() => U | U[]} [empty]
- * @returns {U[]}
- */
-export function map_iterable(iterable, fn, tail, empty) {
-	if (Array.isArray(iterable)) {
-		return map_array(iterable, fn, tail, empty);
-	}
-
-	/** @type {Iterator<T>} */
-	var iterator;
-	var iterable_prop = /** @type {Iterable<T>} */ (iterable)[Symbol.iterator];
-
-	if (typeof iterable_prop === 'function') {
-		iterator = iterable_prop.call(iterable);
-	} else if (typeof (/** @type {Iterator<T>} */ (iterable).next) === 'function') {
-		iterator = Iterator.from(iterable);
-	} else {
-		throw new TypeError('The loop target has to be an Iterable');
-	}
-
-	var current = iterator.next();
-	if (current.done) {
-		if (!empty) {
-			return [];
-		}
-		var empty_value = empty();
-		if (Array.isArray(empty_value)) {
-			return empty_value;
-		}
-		return [empty_value];
-	}
-
-	var index = 0;
-	var result = [];
-	while (true) {
-		var next = iterator.next();
-		var value = fn(current.value, index++, !!next.done);
-		if (Array.isArray(value)) {
-			for (var j = 0; j < value.length; j++) {
-				result.push(value[j]);
-			}
-		} else {
-			result.push(value);
-		}
-		if (next.done) {
-			break;
-		}
-		current = next;
-	}
-	if (tail) {
-		var tail_value = tail();
-		if (Array.isArray(tail_value)) {
-			for (var j = 0; j < tail_value.length; j++) {
-				result.push(tail_value[j]);
-			}
-		} else {
-			result.push(tail_value);
-		}
-	}
-	return result;
-}
-
-/**
- * @template T
- * @template U
- * @param {Array<T>} array
- * @param {(item: T, index: number, is_last: boolean) => U} fn
- * @param {() => U | U[]} [tail]
- * @param {() => U | U[]} [empty]
- * @returns {U[]}
- */
-function map_array(array, fn, tail, empty) {
-	var length = array.length;
-	if (length === 0) {
-		if (!empty) {
-			return [];
-		}
-		var empty_value = empty();
-		if (Array.isArray(empty_value)) {
-			return empty_value;
-		}
-		return [empty_value];
-	}
-	var result = [];
-	for (var i = 0; i < length; i++) {
-		var value = fn(array[i], i, i === length - 1);
-		if (Array.isArray(value)) {
-			for (var j = 0; j < value.length; j++) {
-				result.push(value[j]);
-			}
-		} else {
-			result.push(value);
-		}
-	}
-	if (tail) {
-		var tail_value = tail();
-		if (Array.isArray(tail_value)) {
-			for (var j = 0; j < tail_value.length; j++) {
-				result.push(tail_value[j]);
-			}
-		} else {
-			result.push(tail_value);
-		}
-	}
-	return result;
-}
+export * from '@tsrx/runtime/iterable';

package/src/runtime/language-helpers.js

@@ -1,139 +1 @@
-/** @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.
- * @template T
- * @param {ArrayLike<T>} array_like
- * @param {...number} args
- * @returns {T[]}
- */
-export function array_slice(array_like, ...args) {
-	return is_array(array_like)
-		? array_like.slice(...args)
-		: array_prototype.slice.call(array_like, ...args);
-}
-
-/**
- * Converts iterables, iterators, and array-like values to an array from an index.
- * @template T
- * @param {Iterable<T> | Iterator<T> | ArrayLike<T>} iterable
- * @param {number} [index]
- * @returns {T[]}
- */
-export function iterable_array_from(iterable, index = 0) {
-	/** @type {Iterator<T>} */
-	var iterator;
-	var iterable_prop = /** @type {Iterable<T>} */ (iterable)[Symbol.iterator];
-
-	if (typeof iterable_prop === 'function') {
-		iterator = iterable_prop.call(iterable);
-	} else if (typeof (/** @type {Iterator<T>} */ (iterable).next) === 'function') {
-		iterator = Iterator.from(/** @type {Iterator<T>} */ (iterable));
-	} else {
-		return array_from(/** @type {ArrayLike<T>} */ (iterable)).slice(index);
-	}
-
-	var result = [];
-	var i = 0;
-	var current = iterator.next();
-	while (!current.done) {
-		if (i++ < index) {
-			current = iterator.next();
-			continue;
-		}
-		result.push(current.value);
-		current = iterator.next();
-	}
-	return result;
-}
-
-/**
- * Creates a shallow forwarding object without one prop. Values are exposed through
- * getters so compiler-emitted reactive prop accessors are not snapshotted.
- *
- * @template {object} [T=Record<PropertyKey, unknown>]
- * @template {PropertyKey} [K=PropertyKey]
- * @param {T | null | undefined} props
- * @param {K} exclude_prop
- * @returns {Omit<T, K>} the forwarding object; `{}` when `props` is nullish
- */
-export function exclude_prop_from_object(props, exclude_prop) {
-	/** @type {Record<PropertyKey, unknown>} */
-	const next = {};
-
-	if (props != null) {
-		const source = /** @type {Record<PropertyKey, unknown>} */ (props);
-
-		for (const prop of Reflect.ownKeys(source)) {
-			if (prop === exclude_prop) continue;
-
-			const descriptor = get_descriptor(source, prop);
-			if (!descriptor?.enumerable) continue;
-
-			/** @type {PropertyDescriptor} */
-			const forwarding_descriptor = {
-				enumerable: true,
-				configurable: true,
-				get() {
-					return source[prop];
-				},
-			};
-
-			if (descriptor.writable === true || typeof descriptor.set === 'function') {
-				forwarding_descriptor.set = (value) => {
-					source[prop] = value;
-				};
-			}
-
-			define_property(next, prop, forwarding_descriptor);
-		}
-	}
-
-	// The forwarding object is assembled key by key, which no incremental type
-	// can describe; it mirrors `props` minus `exclude_prop` by construction.
-	return /** @type {Omit<T, K>} */ (next);
-}
+export * from '@tsrx/runtime/language-helpers';

package/src/runtime/ref.js

@@ -1,319 +1 @@
-/** @import { MergeableRef, RefProp, RefValue, SpreadProps } from '../../types/runtime/ref' */
-
-import {
-	has_own_property,
-	get_descriptor,
-	has_prototype_accessor,
-	is_array,
-} 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`.
- *
- * @template [T=Element]
- * @param {...MergeableRef<T>} refs
- * @returns {(node: T | null) => (() => 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')) {
-				ref.current = node;
-				cleanups.push(() => {
-					ref.current = null;
-				});
-			} else if (is_ref_object(ref, 'value')) {
-				ref.value = node;
-				cleanups.push(() => {
-					ref.value = null;
-				});
-			}
-		}
-		return () => {
-			for (const cleanup of cleanups) cleanup();
-		};
-	};
-}
-
-export { is_ref_prop as isRefProp };
-
-/**
- * A ref value that is a function is a callback ref — the bare-element branch of
- * `RefValue` is never callable.
- *
- * @template T
- * @param {RefValue<T>} value
- * @returns {value is (node: T | null) => void | (() => void)}
- */
-function is_ref_callback(value) {
-	return typeof value === 'function';
-}
-
-/**
- * @param {unknown} value
- * @returns {value is RefProp<Element>}
- */
-function is_ref_prop(value) {
-	return typeof value === 'function' && REF_VALUE in value;
-}
-
-/**
- * @template [T=Element]
- * @param {RefValue<T>} ref_value
- * @param {T | null} node
- * @param {(value: T | null) => void} [set_ref_value]
- * @returns {void | (() => void)}
- */
-export function apply_ref_value(ref_value, node, set_ref_value) {
-	if (is_array(ref_value)) {
-		/** @type {Array<() => void>} */
-		const cleanups = [];
-		for (const item of ref_value) {
-			const cleanup = apply_ref_value(item, node);
-			if (typeof cleanup === 'function') {
-				cleanups.push(cleanup);
-			} else if (is_ref_callback(item) && node !== null) {
-				cleanups.push(() => item(null));
-			}
-		}
-		if (cleanups.length > 0) {
-			return () => {
-				for (const cleanup of cleanups) cleanup();
-			};
-		}
-		return;
-	}
-
-	if (is_ref_callback(ref_value)) {
-		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);
-	}
-}
-
-/**
- * @template [T=Element]
- * @param {() => RefValue<T>} get_ref_value
- * @param {(value: T | null) => void} [set_ref_value]
- * @returns {RefProp<T>}
- */
-export function create_ref_prop(get_ref_value, set_ref_value) {
-	/**
-	 * @param {T | null} 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;
-}
-
-/**
- * @template [T=Element]
- * @param {...RefValue<T>} refs
- * @returns {RefValue<T>} the single surviving ref, or a callback applying all
- */
-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 {T | null} 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 (is_ref_callback(ref) && node !== null) {
-				cleanups.push(() => ref(null));
-			}
-		}
-
-		return () => {
-			for (const cleanup of cleanups) {
-				cleanup();
-			}
-		};
-	}
-
-	return merged_ref_prop;
-}
-
-/**
- * @param {object | null | undefined} props a props bag; `object` rather than an
- *   index signature so an interface-typed bag is accepted
- * @param {...RefValue<Element>} outer_refs
- * @returns {SpreadProps | null | undefined}
- */
-export function normalize_spread_props(props, ...outer_refs) {
-	if (props == null) {
-		return props;
-	}
-
-	const source = /** @type {SpreadProps} */ (props);
-	/** @type {Array<RefValue<Element>>} */
-	const refs = [];
-	/** @type {SpreadProps} */
-	const next = {};
-	let changed = false;
-	let existing_ref;
-
-	for (const key of Reflect.ownKeys(source)) {
-		const descriptor = get_descriptor(source, key);
-		if (!descriptor?.enumerable) {
-			continue;
-		}
-
-		const value = source[key];
-
-		if (key === 'ref') {
-			if (is_ref_prop(value)) {
-				refs.push(value);
-				changed = true;
-			} else {
-				existing_ref = /** @type {RefValue<Element>} */ (value);
-			}
-			continue;
-		}
-
-		if (is_ref_prop(value)) {
-			refs.push(value);
-			changed = true;
-			continue;
-		}
-
-		next[key] = value;
-	}
-
-	if (!changed && outer_refs.length === 0) {
-		return source;
-	}
-
-	const merged_ref = merge_ref_props(existing_ref, ...refs, ...outer_refs);
-	if (merged_ref !== undefined) {
-		next.ref = merged_ref;
-	}
-
-	return next;
-}
-
-/**
- * Normalize spread props for targets that read refs through an explicit
- * `ref={normalized.ref}` attribute. The returned `ref` stays readable for that
- * attribute but is non-enumerable so `{...normalized}` does not also pass it as
- * a DOM prop.
- *
- * @param {object | null | undefined} props
- * @param {...RefValue<Element>} outer_refs
- * @returns {SpreadProps | null | undefined}
- */
-export function normalize_spread_props_for_ref_attr(props, ...outer_refs) {
-	const next = normalize_spread_props(props, ...outer_refs);
-	if (next == null || !has_own_property.call(next, 'ref')) {
-		return next;
-	}
-
-	const ref = next.ref;
-	const without_ref = { ...next };
-	delete without_ref.ref;
-	Object.defineProperty(without_ref, 'ref', {
-		value: ref,
-		enumerable: false,
-		configurable: true,
-		writable: true,
-	});
-	return without_ref;
-}
-
-/**
- * @template {'current' | 'value'} K
- * @param {object} value
- * @param {K} key
- * @returns {value is Record<K, unknown>}
- */
-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')
-	);
-}
+export * from '@tsrx/runtime/ref';

package/src/transform/jsx/helpers.js

@@ -2,7 +2,13 @@
 /** @import * as ESRap from 'esrap' */
 
 import tsx from 'esrap/languages/tsx';
-import { should_preserve_comment, format_comment } from '../../comment-utils.js';
+import {
+	should_preserve_comment,
+	should_preserve_jsx_tooling_comment,
+	is_file_level_pragma,
+	format_comment,
+} from '../../comment-utils.js';
+import { has_location } from '../../utils/ast.js';
 import { with_deferred_imports } from '../imports.js';
 
 /**
@@ -69,25 +75,64 @@ export function set_node_path_metadata(node, path) {
  * (structural tokens carry one-character source locations). typeOnly/volar
  * prints opt in — their maps are consumed positionally by the language
  * tooling and never shipped; build prints stay sparse.
- * @param {AST.CommentWithLocation[]} [comments] Source comments; the ones
- * `should_preserve_comment` classifies as semantic-to-TS (`@ts-nocheck`,
- * `@jsxImportSource`, triple-slash references, …) and that LEAD the program
- * are re-emitted at the top of the printed output. The generated TSX is real
- * TS input — dropping a leading pragma changes how the whole file checks.
+ * @param {AST.CommentWithLocation[]} [comments] Source comments. In type-only
+ * output, file-wide pragmas lead the program while documentation and scoped
+ * annotations stay with their declarations, members, or statements. A sparse
+ * print with explicitly supplied comments retains its existing leading-pragma
+ * behavior. Ordinary build callers supply no comments.
  */
 export function tsx_with_ts_locations(boundary_tokens = false, comments = undefined) {
 	const base = with_deferred_imports(tsx({ boundaryTokens: boundary_tokens }));
 	const { _: base_visitor, ...base_visitors } = base;
+	const preserve_comments = comments !== undefined;
+	const preserve_owner_comments = boundary_tokens && preserve_comments;
+	/** @type {Set<string> | null} */
+	const emitted_comments = preserve_comments ? new Set() : null;
+
+	/**
+	 * @param {AST.CommentWithLocation} comment
+	 * @param {ESRap.Context} context
+	 */
+	const write_preserved_comment = (comment, context) => {
+		if (
+			!emitted_comments ||
+			!(preserve_owner_comments
+				? should_preserve_jsx_tooling_comment(comment)
+				: should_preserve_comment(comment))
+		) {
+			return;
+		}
+		const key = `${comment.start}:${comment.end}:${comment.type}:${comment.value}`;
+		if (emitted_comments.has(key)) return;
+		emitted_comments.add(key);
+		if (comment.loc) context.location(comment.loc.start.line, comment.loc.start.column);
+		context.write(format_comment(comment));
+		if (comment.loc) context.location(comment.loc.end.line, comment.loc.end.column);
+		context.newline();
+	};
+
+	/**
+	 * @param {AST.Node} node
+	 * @param {ESRap.Context} context
+	 */
+	const write_leading_comments = (node, context) => {
+		if (!node.leadingComments || !is_comment_owner(node)) return;
+		for (const comment of node.leadingComments) {
+			if (has_location(comment)) write_preserved_comment(comment, context);
+		}
+	};
 
 	const leading_preserved = (/** @type {AST.Program} */ program) => {
-		if (!comments?.length) return [];
+		if (!preserve_comments || !comments?.length) return [];
 		// Injected statements (dynamic-import/try-import prepends) carry no
 		// loc; anchor "leading" on the first statement that maps to source,
 		// else every preserved comment in the file would hoist to the top.
 		const first = program.body.find((node) => node.loc);
 		return comments.filter(
 			(comment) =>
-				should_preserve_comment(comment) &&
+				(preserve_owner_comments
+					? is_file_level_pragma(comment)
+					: should_preserve_comment(comment)) &&
 				(first?.loc == null ||
 					(comment.loc &&
 						(comment.loc.end.line < first.loc.start.line ||
@@ -100,10 +145,7 @@ export function tsx_with_ts_locations(boundary_tokens = false, comments = undefi
 	const wrappers = {
 		Program: (node, context) => {
 			for (const comment of leading_preserved(node)) {
-				if (comment.loc) context.location(comment.loc.start.line, comment.loc.start.column);
-				context.write(format_comment(comment));
-				if (comment.loc) context.location(comment.loc.end.line, comment.loc.end.column);
-				context.newline();
+				write_preserved_comment(comment, context);
 			}
 			/** @type {NonNullable<typeof base.Program>} */ (base.Program)(node, context);
 		},
@@ -206,8 +248,13 @@ export function tsx_with_ts_locations(boundary_tokens = false, comments = undefi
 			context.visit(node.body);
 		},
 		_(node, context, visit) {
+			if (preserve_owner_comments) write_leading_comments(node, context);
 			const visit_with_locations = () => {
-				if (!LOCATION_WRAPPED_NODE_TYPES.has(node.type) || !node.loc) {
+				if (
+					!node.loc ||
+					(!LOCATION_WRAPPED_NODE_TYPES.has(node.type) &&
+						!(boundary_tokens && TOOLING_LOCATION_WRAPPED_NODE_TYPES.has(node.type)))
+				) {
 					visit(node);
 					return;
 				}
@@ -226,6 +273,44 @@ export function tsx_with_ts_locations(boundary_tokens = false, comments = undefi
 	return { ...base_visitors, ...wrappers };
 }
 
+/**
+ * A newline is safe before a statement/declaration or a member, but not before
+ * an arbitrary expression: `return /** @type {number} *\/ 1` must not become a
+ * bare return, and `throw` forbids a line terminator before its argument.
+ * @param {AST.Node} node
+ * @returns {boolean}
+ */
+function is_comment_owner(node) {
+	return (
+		node.type.endsWith('Declaration') ||
+		node.type.endsWith('Statement') ||
+		COMMENT_OWNER_NODE_TYPES.has(node.type)
+	);
+}
+
+const COMMENT_OWNER_NODE_TYPES = new Set([
+	'VariableDeclarator',
+	'Property',
+	'PropertyDefinition',
+	'AccessorProperty',
+	'MethodDefinition',
+	'TSAbstractPropertyDefinition',
+	'TSAbstractAccessorProperty',
+	'TSAbstractMethodDefinition',
+	'TSPropertySignature',
+	'TSMethodSignature',
+	'TSIndexSignature',
+	'TSEnumMember',
+	'TSExportAssignment',
+]);
+
+const TOOLING_LOCATION_WRAPPED_NODE_TYPES = new Set([
+	'ExportNamedDeclaration',
+	'ExportDefaultDeclaration',
+	'ExportAllDeclaration',
+	'TSPropertySignature',
+]);
+
 // Be careful when adding visitors that are already defined in `wrappers`.
 // JSXOpeningElement is intentionally in both places: its custom printer still
 // needs a location marker around the whole node.

package/src/transform/jsx/index.js

@@ -561,7 +561,17 @@ export function createJsxTransform(platform) {
 	 * @returns {JsxTransformResult}
 	 */
 	function transform(ast, source, filename, options) {
-		const suspense_source = options?.suspenseSource ?? platform.imports.suspense;
+		const effective_platform =
+			options?.runtimeImports === 'direct' && platform.directRuntimeImports
+				? {
+						...platform,
+						imports: {
+							...platform.imports,
+							...platform.directRuntimeImports,
+						},
+					}
+				: platform;
+		const suspense_source = options?.suspenseSource ?? effective_platform.imports.suspense;
 		const collect = !!(options?.collect || options?.loose);
 		/** @type {AST.CSS.StyleSheet[]} */
 		const stylesheets = [];
@@ -570,7 +580,7 @@ export function createJsxTransform(platform) {
 
 		/** @type {TransformContext} */
 		const transform_context = {
-			platform,
+			platform: effective_platform,
 			local_statement_component_index: 0,
 			needs_error_boundary: false,
 			needs_suspense: false,
@@ -811,7 +821,7 @@ export function createJsxTransform(platform) {
 		if (platform.hooks?.injectImports) {
 			platform.hooks.injectImports(expanded, transform_context, suspense_source);
 		} else {
-			inject_try_imports(expanded, transform_context, platform, suspense_source);
+			inject_try_imports(expanded, transform_context, effective_platform, suspense_source);
 		}
 
 		// Lower any `@{ … }` code blocks left in generated helper bodies before the

package/src/transform/segments.js

@@ -34,11 +34,19 @@ import {
 	build_line_offsets,
 	get_mapping_from_node,
 } from '../source-map-utils.js';
-import { should_preserve_comment } from '../comment-utils.js';
+import { should_preserve_jsx_tooling_comment, format_comment } from '../comment-utils.js';
 import { has_location } from '../utils/ast.js';
 
 const LAZY_PARAM_IDENTIFIER_REGEX = /^__lazy\d+$/;
 const RETURN_KEYWORD = 'return';
+const EXPORT_KEYWORD = 'export';
+const BLOCK_DECLARATION_TYPES = new Set([
+	'FunctionDeclaration',
+	'ClassDeclaration',
+	'TSInterfaceDeclaration',
+	'TSEnumDeclaration',
+	'TSModuleDeclaration',
+]);
 
 /**
  * @param {string} value
@@ -418,6 +426,88 @@ export function convert_source_map_to_mappings(
 		return candidates[Math.min(index, candidates.length - 1)];
 	}
 
+	/**
+	 * A comment's end can share a source coordinate with the next declaration,
+	 * and synthetic file pragmas can share offset zero with the first export.
+	 * Select the position that actually prints this node's opening text instead
+	 * of treating the first source-map entry as an unambiguous boundary.
+	 * @param {AST.Position} position
+	 * @param {string} text
+	 * @returns {number | undefined}
+	 */
+	function generated_offset_for_text(position, text) {
+		const positions = src_to_gen_map.get(`${position.line}:${position.column}`);
+		for (const generated of positions ?? []) {
+			const offset = loc_to_offset(generated.line, generated.column, gen_line_offsets);
+			if (generated_code.startsWith(text, offset)) return offset;
+		}
+	}
+
+	/**
+	 * @param {AST.NodeWithLocation} node
+	 * @param {string} start_text
+	 * @returns {CodeMapping | undefined}
+	 */
+	function declaration_mapping(node, start_text) {
+		const start = generated_offset_for_text(node.loc.start, start_text);
+		if (start === undefined) return;
+		const positions = src_to_gen_map.get(`${node.loc.end.line}:${node.loc.end.column}`);
+		for (const generated of positions ?? []) {
+			const end = loc_to_offset(generated.line, generated.column, gen_line_offsets);
+			if (end < start) continue;
+			return {
+				sourceOffsets: [node.start],
+				lengths: [node.end - node.start],
+				generatedOffsets: [start],
+				generatedLengths: [end - start],
+				data: { ...mapping_data_verify_only, customData: {} },
+			};
+		}
+	}
+
+	/** @param {AST.ExportNamedDeclaration | AST.ExportDefaultDeclaration | AST.ExportAllDeclaration} node */
+	function add_export_mapping(node) {
+		if (!has_location(node)) return;
+		const mapping = declaration_mapping(node, EXPORT_KEYWORD);
+		if (mapping) {
+			const declaration = node.type === 'ExportAllDeclaration' ? null : node.declaration;
+			const end = mapping.generatedOffsets[0] + mapping.generatedLengths[0];
+			// A semicolon-free source declaration shares its end with its last
+			// expression. The first map entry then precedes the statement's emitted
+			// semicolon. Block declarations are different: a following `;` is an
+			// empty statement, not part of TypeScript's declaration range.
+			if (
+				generated_code[end] === ';' &&
+				(!declaration || !BLOCK_DECLARATION_TYPES.has(declaration.type))
+			) {
+				mapping.generatedLengths[0]++;
+			}
+			// Full declaration queries need both endpoints in the same Volar
+			// mapping, not a linear claim over the generated body. A transformed
+			// component can contain synthetic imports, tags, and helper calls that
+			// must not acquire source locations merely because it is exported.
+			const generated_start = mapping.generatedOffsets[0];
+			const generated_end = generated_start + mapping.generatedLengths[0];
+			mapping.sourceOffsets = [node.start, node.end];
+			mapping.generatedOffsets = [generated_start, generated_end];
+			mapping.lengths = [0, 0];
+			mapping.generatedLengths = [0, 0];
+			mappings.push(mapping);
+		}
+		tokens.push({
+			source: EXPORT_KEYWORD,
+			generated: EXPORT_KEYWORD,
+			loc: {
+				start: node.loc.start,
+				end: {
+					line: node.loc.start.line,
+					column: node.loc.start.column + EXPORT_KEYWORD.length,
+				},
+			},
+			metadata: {},
+		});
+	}
+
 	/**
 	 * Needed for a mapping that includes the computed brackets for diagnostics
 	 * @param {AST.MethodDefinition | AST.Property} node
@@ -464,25 +554,24 @@ export function convert_source_map_to_mappings(
 			if (!Array.isArray(comments)) continue;
 
 			for (const comment of comments) {
-				if (!has_location(comment) || !should_preserve_comment(comment)) continue;
+				if (!has_location(comment) || !should_preserve_jsx_tooling_comment(comment)) continue;
 
 				const comment_key = `${comment.start}:${comment.end}`;
 				if (mapped_comments.has(comment_key)) continue;
 				mapped_comments.add(comment_key);
 
-				try {
-					mappings.push(
-						get_mapping_from_node(
-							comment,
-							src_to_gen_map,
-							gen_line_offsets,
-							mapping_data_verify_only,
-						),
-					);
-				} catch {
-					// Comments that were not emitted in generated TSX have no source-map
-					// segment. They should not produce Volar mappings.
-				}
+				const text = format_comment(comment);
+				const start = generated_offset_for_text(comment.loc.start, text);
+				// A stripped or moved comment must not claim another node's shared
+				// source coordinate. The printer writes this exact formatted text.
+				if (start === undefined) continue;
+				mappings.push({
+					sourceOffsets: [comment.start],
+					lengths: [comment.end - comment.start],
+					generatedOffsets: [start],
+					generatedLengths: [text.length],
+					data: { ...mapping_data_verify_only, customData: {} },
+				});
 			}
 		}
 	}
@@ -704,6 +793,7 @@ export function convert_source_map_to_mappings(
 				}
 				return;
 			} else if (node.type === 'ExportNamedDeclaration') {
+				add_export_mapping(node);
 				if (node.specifiers && node.specifiers.length > 0) {
 					for (const specifier of node.specifiers) {
 						visit(specifier);
@@ -715,12 +805,14 @@ export function convert_source_map_to_mappings(
 				}
 				return;
 			} else if (node.type === 'ExportDefaultDeclaration') {
+				add_export_mapping(node);
 				// Visit the declaration
 				if (node.declaration) {
 					visit(/** @type {AST.Node} */ (node.declaration));
 				}
 				return;
 			} else if (node.type === 'ExportAllDeclaration') {
+				add_export_mapping(node);
 				// Nothing to visit (just source string)
 				return;
 			} else if (node.type === 'JSXOpeningElement') {
@@ -1908,6 +2000,24 @@ export function convert_source_map_to_mappings(
 				}
 				return;
 			} else if (node.type === 'TSPropertySignature') {
+				if (has_location(node)) {
+					const start_text = node.readonly
+						? 'readonly'
+						: node.computed
+							? '['
+							: node.key.type === 'Identifier'
+								? node.key.name
+								: source.slice(node.start, node.key.end);
+					const mapping = declaration_mapping(node, start_text);
+					if (mapping) {
+						const end = mapping.generatedOffsets[0] + mapping.generatedLengths[0];
+						// esrap's containing type/interface prints member separators
+						// after the property's own end marker. TS includes that `;`
+						// in its PropertySignature range, even when it was not authored.
+						if (generated_code[end] === ';') mapping.generatedLengths[0]++;
+						mappings.push(mapping);
+					}
+				}
 				// Property signature in type
 				if (node.key) {
 					visit(node.key);
@@ -2354,7 +2464,11 @@ export function convert_source_map_to_mappings(
 
 	// Add a mapping for the very beginning of the file to handle import additions
 	// This ensures that code actions adding imports at the top work correctly
-	if (!isImportDeclarationPresent && mappings.length > 0 && mappings[0].sourceOffsets[0] > 0) {
+	if (
+		!isImportDeclarationPresent &&
+		mappings.length > 0 &&
+		(mappings[0].sourceOffsets[0] > 0 || mappings[0].generatedOffsets[0] > 0)
+	) {
 		mappings.unshift({
 			sourceOffsets: [0],
 			generatedOffsets: [0],

package/types/index.d.ts

@@ -2218,6 +2218,14 @@ export interface VolarCompileOptions extends Omit<ParseOptions, 'errors' | 'comm
 	dev?: boolean;
 }
 
+/**
+ * Selects where generated runtime helper imports resolve from. Direct mode
+ * emits bare imports from the target's standalone runtime package; the package
+ * that owns the generated modules must declare that runtime as a direct
+ * production dependency.
+ */
+export type RuntimeImportMode = 'compiler' | 'direct';
+
 /**
  * Common base options accepted by every TSRX target's `compile` entry point.
  * Targets that need extra knobs (e.g. ripple's `mode`/`dev`/`hmr`, preact's
@@ -2227,6 +2235,13 @@ export interface VolarCompileOptions extends Omit<ParseOptions, 'errors' | 'comm
 export interface BaseCompileOptions {
 	collect?: boolean;
 	loose?: boolean;
+	/**
+	 * Selects where generated runtime helper imports resolve from. The default
+	 * `'compiler'` mode preserves compiler-package compatibility subpaths;
+	 * `'direct'` targets the renderer's small runtime package, which the package
+	 * owning the generated modules must declare as a direct production dependency.
+	 */
+	runtimeImports?: RuntimeImportMode;
 }
 
 /**

package/types/jsx-platform.d.ts

@@ -1,7 +1,7 @@
 import type * as AST from 'estree';
 import type * as ESTreeJSX from 'estree-jsx';
 import type { RawSourceMap } from 'source-map';
-import type { CompileError, JsxHelperComponent, JsxHelperState } from './index';
+import type { CompileError, JsxHelperComponent, JsxHelperState, RuntimeImportMode } from './index';
 
 /**
  * Result returned by a JSX platform transform (React, Preact, Solid).
@@ -82,6 +82,13 @@ export interface JsxTransformContext {
  * Optional per-call compile options passed to a created JSX transform.
  */
 export interface JsxTransformOptions {
+	/**
+	 * Selects compiler-package compatibility imports or direct renderer runtime
+	 * package imports. Defaults to `'compiler'`. Direct mode requires the package
+	 * owning generated modules to declare the target runtime as a direct
+	 * production dependency.
+	 */
+	runtimeImports?: RuntimeImportMode;
 	/**
 	 * Override the import source used for `Suspense` in try-block transforms.
 	 * Falls back to `platform.imports.suspense`. Preact uses this to let the
@@ -412,6 +419,17 @@ export interface JsxPlatform {
 		forOfIterableHelper?: string;
 	};
 
+	/**
+	 * Runtime-helper import sources used when a compile call opts into direct
+	 * runtime imports. Fields omitted here continue using `imports`.
+	 */
+	directRuntimeImports?: {
+		errorBoundary?: string;
+		mergeRefs?: string;
+		refProp?: string;
+		forOfIterableHelper?: string;
+	};
+
 	jsx: {
 		/**
 		 * Rewrite Ripple's `class` attribute to `className` for legacy targets

package/types/runtime/iterable.d.ts

@@ -1,13 +1 @@
-// Helper type for item in an array or iterable
-// example: IterationValue<typeof something>
-export type IterationValue<T> = T extends readonly unknown[]
-	? T[number]
-	: T extends Iterable<infer U>
-		? U
-		: never;
-
-export function map_iterable<T, U>(
-	value: Iterable<T>,
-	fn: (item: T, index: number, is_last: boolean) => U,
-	tail?: () => U | U[],
-): U[];
+export * from '@tsrx/runtime/iterable';

package/types/runtime/language-helpers.d.ts

@@ -1,30 +1 @@
-export const get_descriptor: typeof Object.getOwnPropertyDescriptor;
-export const get_descriptors: typeof Object.getOwnPropertyDescriptors;
-export const array_from: typeof Array.from;
-export const is_array: typeof Array.isArray;
-export const define_property: typeof Object.defineProperty;
-export const get_prototype_of: typeof Object.getPrototypeOf;
-export const object_values: typeof Object.values;
-export const object_entries: typeof Object.entries;
-export const object_keys: typeof Object.keys;
-export const get_own_property_symbols: typeof Object.getOwnPropertySymbols;
-export const structured_clone: typeof structuredClone;
-export const object_prototype: typeof Object.prototype;
-export const array_prototype: typeof Array.prototype;
-export const has_own_property: typeof Object.prototype.hasOwnProperty;
-
-export function has_prototype_accessor(value: object, key: PropertyKey): boolean;
-export function array_slice<T>(array_like: ArrayLike<T>, ...args: number[]): T[];
-export function iterable_array_from<T>(
-	iterable: Iterable<T> | Iterator<T> | ArrayLike<T>,
-	index?: number,
-): T[];
-/**
- * The props bag minus one prop. Constrained to `object` rather than an index
- * signature so an interface- or class-typed props bag is accepted; returns `{}`
- * when `props` is nullish.
- */
-export function exclude_prop_from_object<
-	T extends object = Record<PropertyKey, unknown>,
-	K extends PropertyKey = PropertyKey,
->(props: T | null | undefined, exclude_prop: K): Omit<T, K>;
+export * from '@tsrx/runtime/language-helpers';

package/types/runtime/ref.d.ts

@@ -1,88 +1 @@
-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 RefValue<T = Element> =
-	| ((node: T) => void | (() => void))
-	| readonly RefValue<T>[]
-	| { current: T | null }
-	| { value: T | null }
-	| T
-	| null
-	| undefined;
-
-export type MergeableRef<T> =
-	MergeableRefCallback<T> | MergeableRefObject<T> | MergeableVueRef<T> | null | undefined;
-
-/**
- * A props bag as it reaches a spread: keys the caller has not narrowed.
- *
- * Accepting bag is spelled `object` at the parameter position — an index
- * signature would reject an interface- or class-typed props bag — while this
- * is what the helpers hand back when they rebuild one.
- */
-export type SpreadProps = Record<PropertyKey, unknown>;
-
-/**
- * The node a ref value points at, derived from the ref's own type in the order
- * the runtime resolves it (see `apply_ref_value` and `is_ref_object`): a list
- * resolves through its entries, a callback through its parameter, and a DOM
- * node is never treated as a ref object.
- *
- * Inferring through `RefValue<T>` instead would read the target off the wrong
- * union member: TypeScript prefers a structural member over a naked type
- * parameter, so `HTMLInputElement` would match the `{ value: T | null }`
- * (Vue ref) branch and resolve `T` to `string`.
- */
-export type RefTarget<V> = [V] extends [never]
-	? never
-	: V extends null | undefined
-		? never
-		: V extends (node: infer N) => unknown
-			? N
-			: V extends readonly (infer E)[]
-				? RefTarget<E>
-				: V extends Node
-					? V
-					: V extends { current: infer C }
-						? NonNullable<C>
-						: V extends { value: infer C }
-							? NonNullable<C>
-							: V;
-
-export function mergeRefs<T = Element>(
-	...refs: Array<MergeableRef<T>>
-): (node: T | null) => () => void;
-export function isRefProp(value: unknown): boolean;
-// The inference overload comes first so an inferred call resolves the target
-// through `RefTarget`; the `T` overload below still serves explicit type
-// arguments, which is what every compiler-generated call passes.
-export function create_ref_prop<V>(
-	get_ref_value: () => V,
-	set_ref_value?: (value: RefTarget<V> | null) => void,
-): RefProp<RefTarget<V>>;
-export function create_ref_prop<T = Element>(
-	get_ref_value: () => RefValue<T>,
-	set_ref_value?: (value: T | null) => void,
-): RefProp<T>;
-export function apply_ref_value<V>(
-	ref_value: V,
-	node: RefTarget<V> | null,
-	set_ref_value?: (value: RefTarget<V> | null) => void,
-): void | (() => void);
-export function apply_ref_value<T = Element>(
-	ref_value: RefValue<T>,
-	node: T | null,
-	set_ref_value?: (value: T | null) => void,
-): void | (() => void);
-export function merge_ref_props<T = Element>(...refs: Array<RefValue<T>>): RefValue<T>;
-export function normalize_spread_props<T extends object | null | undefined>(
-	props: T,
-	...outer_refs: Array<RefValue<Element>>
-): T | SpreadProps;
-export function normalize_spread_props_for_ref_attr<T extends object | null | undefined>(
-	props: T,
-	...outer_refs: Array<RefValue<Element>>
-): T | SpreadProps;
+export * from '@tsrx/runtime/ref';