@tsrx/core 0.1.58 → 0.1.60

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,
@@ -718,9 +728,24 @@ export function createJsxTransform(platform) {
 				// hooks can inspect the original JSX child shape.
 				const raw_children = node_children(node).map((child) => ({ ...child }));
 				const inner = /** @type {AST.TSRXJSXElement} */ (next() ?? node);
+				const in_jsx_child = in_jsx_child_context(path);
 				const hook = platform.hooks?.transformElement;
-				if (hook) return hook(inner, state, raw_children);
-				return to_jsx_element(inner, state, raw_children, in_jsx_child_context(path));
+				const produced = hook
+					? hook(inner, state, raw_children)
+					: to_jsx_element(inner, state, raw_children, in_jsx_child);
+				// A host element carrying `ref` plus a spread lowers to a generated
+				// `let X = __normalize_spread_props_for_ref_attr(…)` that rides on the
+				// element's metadata for a later pass to hoist. Only the render-block
+				// statement builder and the native-directive path hoist it, so an
+				// element in plain-JS expression position — a ternary arm, a concise
+				// arrow body, a declarator init, a callback body, an attribute value, an
+				// array element — reaches neither: the declaration is dropped while the
+				// rewritten attributes still reference the name, and the type-only print
+				// carries an undefined identifier (TS2304). Wrap it in the same IIFE the
+				// native-directive path already uses.
+				return state.typeOnly && produced.type !== 'JSXSpreadChild' && produced.type !== 'JSXText'
+					? wrap_jsx_setup_declarations(produced, in_jsx_child)
+					: produced;
 			},
 
 			JSXExpressionContainer(node, { next, state }) {
@@ -781,7 +806,7 @@ export function createJsxTransform(platform) {
 					return visited;
 				}
 				const is_component = is_component_like_jsx_name(visited.name);
-				return b.jsx_opening_element(
+				const lowered = b.jsx_opening_element(
 					visited.name,
 					merge_duplicate_refs(
 						normalize_host_ref_spreads(visited.attributes || [], !is_component, transform_context),
@@ -791,6 +816,17 @@ export function createJsxTransform(platform) {
 					visited.typeArguments,
 					has_location(visited) ? visited : undefined,
 				);
+				// `normalize_host_ref_spreads` is NOT idempotent: run twice it reads the
+				// `ref={[authored, __spread_props1.ref]}` array it just produced as an
+				// AUTHORED ref and lowers again, emitting a second helper binding and a
+				// nested ref array. The attribute list cannot answer "already lowered"
+				// on its own — `merge_duplicate_refs` rebuilds the merged `ref` without
+				// the `synthetic_ref` marker — so record it on the element instead.
+				lowered.metadata = {
+					...(lowered.metadata || {}),
+					host_ref_spread_lowered: true,
+				};
+				return lowered;
 			},
 		});
 
@@ -811,7 +847,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
@@ -1055,6 +1091,7 @@ function inject_dynamic_import(program, transform_context) {
  * @param {AST.CSS.StyleSheet} css
  * @param {TransformContext} transform_context
  * @param {boolean} [export_top_scoped_classes]
+ * @param {string} [region_hash]
  * @returns {void}
  */
 function apply_css_definition_metadata(
@@ -1062,6 +1099,7 @@ function apply_css_definition_metadata(
 	css,
 	transform_context,
 	export_top_scoped_classes = false,
+	region_hash = css.hash,
 ) {
 	analyze_css(css);
 
@@ -1072,7 +1110,7 @@ function apply_css_definition_metadata(
 
 	const prune = () => {
 		for (const element of elements) {
-			prune_css(css, element, style_classes, top_scoped_classes);
+			prune_css(css, element, style_classes, top_scoped_classes, region_hash);
 		}
 	};
 
@@ -2281,19 +2319,20 @@ function node_contains_native_tsrx_template(node) {
 
 /**
  * @param {AST.NativeTSRXNode} node
- * @returns {AST.CSS.StyleSheet | null}
+ * @param {boolean} allow_multiple
+ * @returns {AST.CSS.StyleSheet[] | null}
  */
-function collect_tsrx_stylesheet(node) {
+function collect_tsrx_stylesheets(node, allow_multiple) {
 	/** @type {AST.CSS.StyleSheet[]} */
 	const styles = [];
 	collect_style_elements(node_children(node), styles);
 
 	if (styles.length === 0) return null;
-	if (styles.length > 1) {
+	if (styles.length > 1 && !allow_multiple) {
 		throw new Error('TSRX fragments can only have one style tag');
 	}
 
-	return styles[0];
+	return styles;
 }
 
 /**
@@ -2302,14 +2341,37 @@ function collect_tsrx_stylesheet(node) {
  * @returns {JsxStyleContext | null}
  */
 function prepare_tsrx_fragment_styles(node, transform_context) {
-	const css = collect_tsrx_stylesheet(node);
-	if (!css) return null;
-
+	// Type-only output must stay analyzable: a throw here makes language hosts
+	// (tsrx-tsc, editors) fall back to presenting the RAW source as the virtual
+	// TSX, so every CSS brace in the file becomes a TSX parse error. Platforms
+	// whose runtime dialect allows one scope to split its CSS across several
+	// `<style>` tags are valid input here, and platforms that forbid it still
+	// report the rule through their own runtime compiler.
+	const sheets = collect_tsrx_stylesheets(node, transform_context.typeOnly);
+	if (!sheets) return null;
+
+	const css = sheets[0];
 	const style_refs = collect_style_ref_attributes(node);
-	// `prune_css` inside marks the matching selectors as used/scoped; selectors
-	// that match no element render commented out, like the Ripple target.
-	apply_css_definition_metadata(node, css, transform_context, style_refs.length > 0);
-	transform_context.stylesheets.push(css);
+	// A component scope keeps ONE hash even when its CSS is split across
+	// several `<style>` tags: rebase every sheet onto the first sheet's hash
+	// before scoping, so selector rewriting and the DOM hash annotation below
+	// agree. `apply_css_definition_metadata` accumulates into the component's
+	// `styleClasses`/`topScopedClasses` metadata, so per-sheet calls compose
+	// into one class map for style refs.
+	for (const sheet of sheets) {
+		const region_hash = sheet.hash;
+		sheet.hash = css.hash;
+		// `prune_css` inside marks the matching selectors as used/scoped; selectors
+		// that match no element render commented out, like the Ripple target.
+		apply_css_definition_metadata(
+			node,
+			sheet,
+			transform_context,
+			style_refs.length > 0,
+			region_hash,
+		);
+		transform_context.stylesheets.push(sheet);
+	}
 	const fragment = annotate_tsrx_with_hash(
 		node,
 		css.hash,
@@ -6110,8 +6172,16 @@ function transform_element_attributes_dispatch(attrs, transform_context, element
 	}
 	const hook = transform_context.platform.hooks?.transformElementAttributes;
 	const result = hook ? hook(attrs, transform_context, element) : attrs;
+	// An element in plain-JS expression position reaches BOTH lowering sites —
+	// the JSXOpeningElement visitor above and this dispatch — so without the
+	// marker its host ref/spread is lowered twice. Scoped to the type-only
+	// print: runtime emit for the other platforms sharing this transform keeps
+	// its existing output.
+	const already_lowered =
+		transform_context.typeOnly &&
+		element?.openingElement?.metadata?.host_ref_spread_lowered === true;
 	return merge_duplicate_refs(
-		normalize_host_ref_spreads(result, !is_component, transform_context),
+		already_lowered ? result : normalize_host_ref_spreads(result, !is_component, transform_context),
 		transform_context,
 	);
 }

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') {
@@ -793,7 +885,7 @@ export function convert_source_map_to_mappings(
 										definition: {
 											description: `CSS class selector for '.${name}'`,
 											location: {
-												embeddedId: get_style_region_id(css.hash),
+												embeddedId: get_style_region_id(cssLocation.regionHash ?? css.hash),
 												start: cssLocation.start,
 												end: cssLocation.end,
 											},
@@ -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

@@ -989,6 +989,8 @@ declare module 'estree-jsx' {
 	interface JSXOpeningElement {
 		metadata: BaseNodeMetaData & {
 			native_tsrx_pretransformed?: boolean;
+			/** Type-only host ref/spread normalization has already run for this element. */
+			host_ref_spread_lowered?: boolean;
 		};
 	}
 
@@ -2090,6 +2092,8 @@ export type TopScopedClasses = Map<
 		start: number;
 		end: number;
 		selector: AST.CSS.ClassSelector;
+		/** Source `<style>` region for editor definition navigation. */
+		regionHash?: string;
 	}
 >;
 
@@ -2218,6 +2222,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 +2239,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';