@tsrx/core 0.1.41 → 0.1.43

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "type": "module",
   "repository": {
     "type": "git",
@@ -63,11 +63,11 @@
   "dependencies": {
     "@jridgewell/sourcemap-codec": "^1.5.5",
     "@noble/hashes": "^2.2.0",
-    "@sveltejs/acorn-typescript": "^1.0.10",
+    "@sveltejs/acorn-typescript": "^1.0.11",
     "@types/estree-jsx": "^1.0.5",
     "@types/estree": "^1.0.8",
-    "acorn": "^8.16.0",
-    "esrap": "^2.2.8",
+    "acorn": "^8.17.0",
+    "esrap": "^2.3.0",
     "is-reference": "^3.0.3",
     "magic-string": "^0.30.18",
     "zimmerframe": "^1.1.2"

package/src/comment-utils.js

@@ -58,6 +58,18 @@ export function is_jsdoc_ts_annotation(comment) {
 	return tsAnnotations.some((annotation) => comment.value.includes(annotation));
 }
 
+/**
+ * Check if a comment is a TypeScript JSX pragma (`@jsxImportSource`,
+ * `@jsxRuntime`, `@jsxFrag`, `@jsx`). TS reads these from a file's LEADING
+ * comments to pick that file's JSX type source/factory, overriding tsconfig —
+ * dropping one silently retypes every JSX expression in the file.
+ * @param {AST.CommentWithLocation} comment
+ * @returns {boolean}
+ */
+export function is_jsx_pragma(comment) {
+	return /@jsx(ImportSource|Runtime|Frag)?\b/.test(comment.value);
+}
+
 /**
  * Check if a comment should be preserved in to_ts mode
  * @param {AST.CommentWithLocation} comment
@@ -65,7 +77,10 @@ export function is_jsdoc_ts_annotation(comment) {
  */
 export function should_preserve_comment(comment) {
 	return (
-		is_ts_pragma(comment) || is_triple_slash_directive(comment) || is_jsdoc_ts_annotation(comment)
+		is_ts_pragma(comment) ||
+		is_triple_slash_directive(comment) ||
+		is_jsdoc_ts_annotation(comment) ||
+		is_jsx_pragma(comment)
 	);
 }
 

package/src/parse/index.js

@@ -219,12 +219,38 @@ export function createParser(...plugins) {
 		/** @type {AST.Program} */
 		let ast;
 
+		// Lexer-authoritative keyword positions (volar opt-in): the mapping
+		// collector needs the SOURCE spans of `async`/`function`, which no AST
+		// node records. The tokenizer is the only correct source — offset
+		// arithmetic breaks on extra whitespace, and text search breaks on
+		// comments (`async /* function */ function`).
+		/** @type {Array<{ value: string, start: number, end: number, loc: AST.SourceLocation }> | undefined} */
+		const keyword_tokens = options?.keywordTokens ? [] : undefined;
+		/** @type {Parse.Options['onToken'] | undefined} */
+		const onToken = keyword_tokens
+			? (token) => {
+					const t = /** @type {any} */ (token);
+					const is_function_keyword = t.type?.keyword === 'function';
+					const is_async_name = t.type?.label === 'name' && t.value === 'async';
+					if (is_function_keyword || is_async_name) {
+						keyword_tokens.push({
+							value: is_function_keyword ? 'function' : 'async',
+							start: t.start,
+							end: t.end,
+							loc: t.loc,
+						});
+					}
+				}
+			: undefined;
+
 		try {
 			ast = parser.parse(source, {
 				sourceType: 'module',
 				ecmaVersion: 13,
 				allowReturnOutsideFunction: true,
 				locations: true,
+				onToken,
+				preserveParens: !!options?.preserveParens,
 				onComment,
 				tsrxOptions: {
 					filename,
@@ -245,6 +271,10 @@ export function createParser(...plugins) {
 
 		add_comments(ast);
 
+		if (keyword_tokens) {
+			/** @type {any} */ (ast).tsrx_keyword_tokens = keyword_tokens;
+		}
+
 		return ast;
 	};
 }

package/src/transform/jsx/helpers.js

@@ -2,6 +2,7 @@
 /** @import { Visitors } from 'zimmerframe' */
 
 import tsx from 'esrap/languages/tsx';
+import { should_preserve_comment, format_comment } from '../../comment-utils.js';
 
 /**
  * Zimmerframe provides `path` as the ancestor chain. A native template node in
@@ -51,18 +52,48 @@ export function set_node_path_metadata(node, path) {
 }
 
 /**
- * Wrap esrap's `tsx()` printer with location markers for nodes whose spans
- * (e.g. the leading `new ` of a NewExpression or the angle-bracket delimiters
- * around generic arguments) are otherwise invisible to the source map.
- * Without these markers, Volar mapping collection in `segments.js` throws
- * when looking up the node's start/end positions.
+ * Wrap esrap's `tsx()` printer with location markers for the remaining nodes
+ * whose spans are invisible to the source map (e.g. `class`, template-literal
+ * backticks, JSX angle brackets, generic-argument delimiters). Without these
+ * markers, Volar mapping collection in `segments.js` throws when looking up
+ * the node's start/end positions. esrap ≥2.3.0 (keyword writes +
+ * `boundaryTokens`) covers most starts, but not statement ends — see the
+ * list below for what each entry still compensates.
  *
  * Shared across all JSX-producing targets (React, Preact, Solid).
  *
  * @returns {any}
  */
-export function tsx_with_ts_locations() {
-	const base = /** @type {any} */ (tsx());
+/**
+ * @param {boolean} [boundary_tokens] Enable esrap's `boundaryTokens` anchors
+ * (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.
+ */
+export function tsx_with_ts_locations(boundary_tokens = false, comments = undefined) {
+	const base = /** @type {any} */ (tsx({ boundaryTokens: boundary_tokens }));
+
+	const leading_preserved = (/** @type {any} */ program) => {
+		if (!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((/** @type {any} */ node) => node.loc);
+		return comments.filter(
+			(/** @type {any} */ comment) =>
+				should_preserve_comment(comment) &&
+				(first?.loc == null ||
+					(comment.loc &&
+						(comment.loc.end.line < first.loc.start.line ||
+							(comment.loc.end.line === first.loc.start.line &&
+								comment.loc.end.column <= first.loc.start.column)))),
+		);
+	};
 
 	/**
 	 * @param {any} node
@@ -81,17 +112,17 @@ export function tsx_with_ts_locations() {
 
 	/** @type {Record<string, (node: any, context: any) => void>} */
 	const wrappers = {
-		ArrayPattern: (node, context) => {
-			base.ArrayPattern(node, context);
-			if (node.typeAnnotation) {
-				context.visit(node.typeAnnotation);
+		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();
 			}
+			base.Program(node, context);
 		},
-		Identifier: (node, context) => {
-			context.write(node.name, node);
-			if (node.optional) {
-				context.write('?');
-			}
+		ArrayPattern: (node, context) => {
+			base.ArrayPattern(node, context);
 			if (node.typeAnnotation) {
 				context.visit(node.typeAnnotation);
 			}
@@ -134,39 +165,6 @@ export function tsx_with_ts_locations() {
 			context.write(' ');
 			context.visit(value.body);
 		},
-		// esrap's ArrowFunctionExpression printer ignores `typeParameters` and
-		// `returnType`, so an annotated arrow like `(): Record<...> => ...`
-		// prints as `() => ...` and segments.js can't resolve the return-type
-		// nodes' positions in the generated output.
-		ArrowFunctionExpression: (node, context) => {
-			if (node.async) context.write('async ');
-			if (node.typeParameters) {
-				context.visit(node.typeParameters);
-			}
-			context.write('(');
-			for (let i = 0; i < node.params.length; i++) {
-				if (i > 0) context.write(', ');
-				context.visit(node.params[i]);
-			}
-			context.write(')');
-			if (node.returnType) {
-				context.visit(node.returnType);
-			}
-			context.write(' => ');
-			const body = node.body;
-			const wrap_body =
-				body.type === 'ObjectExpression' ||
-				(body.type === 'AssignmentExpression' && body.left.type === 'ObjectPattern') ||
-				(body.type === 'LogicalExpression' && body.left.type === 'ObjectExpression') ||
-				(body.type === 'ConditionalExpression' && body.test.type === 'ObjectExpression');
-			if (wrap_body) {
-				context.write('(');
-				context.visit(body);
-				context.write(')');
-			} else {
-				context.visit(body);
-			}
-		},
 
 		// esrap's JSXOpeningElement printer doesn't emit `typeArguments`, so generic
 		// component tags like `<RenderProp<User>>` lose the `<User>` in the output.
@@ -196,6 +194,11 @@ export function tsx_with_ts_locations() {
 			}
 		},
 		TSModuleDeclaration: (node, context) => {
+			// Ambient `declare module '…' { … }` must keep its `declare` — the
+			// typeOnly/volar output is real TS and `module '…' { … }` alone is a
+			// syntax error (TS1035). Non-ambient `module name { }` blocks have no
+			// `declare` and print unchanged.
+			if (node.declare) context.write('declare ');
 			context.write(node.metadata?.module_keyword ?? 'module');
 			context.write(' ');
 			context.visit(node.id);
@@ -209,9 +212,14 @@ export function tsx_with_ts_locations() {
 	// on the whole node, only then duplicate it here
 	// e.g. JSXOpeningElement is such a case
 	for (const type of [
-		// JS nodes whose esrap printer emits no location marker, causing
-		// segments.js get_mapping_from_node() to throw when it asks for the
-		// generated position of the node's start (or end).
+		// JS nodes with boundary positions esrap still cannot map. Keyword
+		// writes (if/new/return/for/switch/await) and `boundaryTokens`
+		// anchors (brackets, braces, parens, computed/call closers) cover
+		// many STARTS, but statement ENDS land on unanchored characters
+		// (`;`, a block's `}`), `class` is not a keyword-write, template
+		// literals' backticks carry no location, and an arrow's span can
+		// start at a bare `(` — so these node-level markers remain the
+		// source of both boundaries until esrap can anchor them.
 		'ClassDeclaration',
 		'ClassExpression',
 		'IfStatement',

package/src/transform/jsx/index.js

@@ -214,32 +214,53 @@ function lower_code_block_child(block) {
  * `lower_code_block_child`). This is the element-scoped equivalent of
  * `transform_function`'s body lowering — function and arrow bodies are never
  * element children, so they are untouched here.
+ *
+ * The input tree is never mutated: replacements land on a shallow copy of the
+ * owning node (or array), so the return value must be used in place of the
+ * argument. Untouched subtrees are shared by reference with the input.
  * @param {any} node
  * @param {Set<any>} [seen]
- * @returns {void}
+ * @returns {any}
  */
 function expand_child_code_blocks(node, seen = new Set()) {
-	if (!node || typeof node !== 'object' || seen.has(node)) return;
+	if (!node || typeof node !== 'object' || seen.has(node)) return node;
 	seen.add(node);
 
 	if (Array.isArray(node)) {
-		for (const item of node) expand_child_code_blocks(item, seen);
-		return;
+		let changed = false;
+		const result = node.map((item) => {
+			const walked = expand_child_code_blocks(item, seen);
+			if (walked !== item) changed = true;
+			return walked;
+		});
+		return changed ? result : node;
 	}
 
+	let out = node;
+	const set = (/** @type {string} */ key, /** @type {any} */ value) => {
+		if (out[key] === value) return;
+		if (out === node) out = { ...node };
+		out[key] = value;
+	};
+
 	if (
 		Array.isArray(node.children) &&
 		node.children.some((/** @type {any} */ c) => c?.type === 'JSXCodeBlock')
 	) {
-		node.children = node.children.flatMap((/** @type {any} */ child) =>
-			child?.type === 'JSXCodeBlock' ? lower_code_block_child(child) : [child],
+		set(
+			'children',
+			node.children.flatMap((/** @type {any} */ child) =>
+				child?.type === 'JSXCodeBlock' ? lower_code_block_child(child) : [child],
+			),
 		);
 	}
 
-	for (const key of Object.keys(node)) {
+	for (const key of Object.keys(out)) {
 		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') continue;
-		expand_child_code_blocks(node[key], seen);
+		set(key, expand_child_code_blocks(out[key], seen));
 	}
+
+	return out;
 }
 
 /**
@@ -418,13 +439,17 @@ function wrap_lowered_value_in_fragment(expression, source) {
  * its rendered value. Either way nothing leaks to the printer as a raw
  * `JSX…Expression`.
  *
+ * The input tree is never mutated: every replacement lands on a shallow copy of
+ * the owning node (or array), so the return value must be used in place of the
+ * argument. Untouched subtrees are shared by reference with the input.
+ *
  * @param {any} node
  * @param {TransformContext} transform_context
  * @param {Set<any>} [seen]
- * @returns {void}
+ * @returns {any}
  */
 function wrap_control_flow_expression_values(node, transform_context, seen = new Set()) {
-	if (!node || typeof node !== 'object' || seen.has(node)) return;
+	if (!node || typeof node !== 'object' || seen.has(node)) return node;
 	seen.add(node);
 
 	// Dynamic tags on factory platforms must lower before control-flow
@@ -454,11 +479,17 @@ function wrap_control_flow_expression_values(node, transform_context, seen = new
 			: value;
 
 	if (Array.isArray(node)) {
-		for (let i = 0; i < node.length; i++) {
-			node[i] = lower_child(node[i]);
-			wrap_control_flow_expression_values(node[i], transform_context, seen);
-		}
-		return;
+		let changed = false;
+		const result = node.map((entry) => {
+			const walked = wrap_control_flow_expression_values(
+				lower_child(entry),
+				transform_context,
+				seen,
+			);
+			if (walked !== entry) changed = true;
+			return walked;
+		});
+		return changed ? result : node;
 	}
 
 	// Wrap a bare control-flow directive that is the sole value of a render-output
@@ -469,50 +500,72 @@ function wrap_control_flow_expression_values(node, transform_context, seen = new
 	const wrap_value = (/** @type {any} */ value) =>
 		is_jsx_control_flow_expression(value) ? wrap_in_native_tsrx_fragment(value) : value;
 
+	// All replacements land on `out`, a shallow copy made on first write; the
+	// input node's fields are never reassigned.
+	let out = node;
+	const set = (/** @type {string} */ key, /** @type {any} */ value) => {
+		if (out[key] === value) return;
+		if (out === node) out = { ...node };
+		out[key] = value;
+	};
+
 	if (
 		node.type === 'ArrowFunctionExpression' &&
 		node.body?.type !== 'BlockStatement' &&
 		is_jsx_control_flow_expression(node.body)
 	) {
-		node.body = wrap_in_native_tsrx_fragment(node.body);
+		set('body', wrap_in_native_tsrx_fragment(node.body));
 	} else if (node.type === 'ReturnStatement' && is_jsx_control_flow_expression(node.argument)) {
-		node.argument = wrap_in_native_tsrx_fragment(node.argument);
+		set('argument', wrap_in_native_tsrx_fragment(node.argument));
 	} else if (
 		node.type === 'ExpressionStatement' &&
 		is_jsx_control_flow_expression(node.expression)
 	) {
-		node.expression = wrap_in_native_tsrx_fragment(node.expression);
+		set('expression', wrap_in_native_tsrx_fragment(node.expression));
 	} else if (node.type === 'VariableDeclarator' && is_jsx_control_flow_expression(node.init)) {
-		node.init = wrap_in_native_tsrx_fragment(node.init);
+		set('init', wrap_in_native_tsrx_fragment(node.init));
 	} else if (node.type === 'AssignmentExpression' && is_jsx_control_flow_expression(node.right)) {
-		node.right = wrap_in_native_tsrx_fragment(node.right);
+		set('right', wrap_in_native_tsrx_fragment(node.right));
 	} else if (
 		(node.type === 'CallExpression' || node.type === 'NewExpression') &&
 		Array.isArray(node.arguments)
 	) {
-		node.arguments = node.arguments.map(wrap_value);
+		const wrapped = node.arguments.map(wrap_value);
+		if (
+			wrapped.some(
+				(/** @type {any} */ argument, /** @type {number} */ i) => argument !== node.arguments[i],
+			)
+		) {
+			set('arguments', wrapped);
+		}
 	}
 
-	for (const key of Object.keys(node)) {
+	for (const key of Object.keys(out)) {
 		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') continue;
 		// A directive is allowed as a render child/statement, and as the sole value
 		// of a render-output slot (handled above for control flow; `@{ … }` blocks
 		// self-lower). Everywhere else it is combined into an expression — wrap it.
 		const allowed_slot =
 			is_statement_or_template_slot(node, key) || is_render_output_value_slot(node, key);
-		const value = node[key];
+		const value = out[key];
 		if (Array.isArray(value)) {
-			for (let i = 0; i < value.length; i++) {
-				value[i] = lower_child(value[i]);
-				if (!allowed_slot) value[i] = wrap_directive_in_expression(value[i]);
-				wrap_control_flow_expression_values(value[i], transform_context, seen);
-			}
+			let changed = false;
+			const result = value.map((entry) => {
+				let next = lower_child(entry);
+				if (!allowed_slot) next = wrap_directive_in_expression(next);
+				next = wrap_control_flow_expression_values(next, transform_context, seen);
+				if (next !== entry) changed = true;
+				return next;
+			});
+			if (changed) set(key, result);
 		} else {
-			node[key] = lower_child(node[key]);
-			if (!allowed_slot) node[key] = wrap_directive_in_expression(node[key]);
-			wrap_control_flow_expression_values(node[key], transform_context, seen);
+			let next = lower_child(value);
+			if (!allowed_slot) next = wrap_directive_in_expression(next);
+			set(key, wrap_control_flow_expression_values(next, transform_context, seen));
 		}
 	}
+
+	return out;
 }
 
 /**
@@ -578,8 +631,8 @@ export function createJsxTransform(platform) {
 			...(platform.hooks?.initialState?.() ?? {}),
 		};
 
-		expand_child_code_blocks(/** @type {any} */ (ast));
-		wrap_control_flow_expression_values(/** @type {any} */ (ast), transform_context);
+		ast = expand_child_code_blocks(/** @type {any} */ (ast));
+		ast = wrap_control_flow_expression_values(/** @type {any} */ (ast), transform_context);
 
 		if (!transform_context.typeOnly) {
 			preallocate_lazy_ids(/** @type {any} */ (ast), transform_context);
@@ -735,7 +788,15 @@ export function createJsxTransform(platform) {
 			},
 		});
 
-		const transformed_program = /** @type {AST.Program} */ (transformed);
+		let transformed_program = /** @type {AST.Program} */ (transformed);
+		// The walk returns the input program unchanged when no visitor replaced
+		// anything beneath it. The post-passes below (style anchors, helper
+		// expansion, import injection) write into the program's `body`, so
+		// detach from the caller's AST first; a changed program is already a
+		// fresh walk-owned node with a fresh `body` array.
+		if (/** @type {any} */ (transformed_program) === /** @type {any} */ (ast)) {
+			transformed_program = { ...transformed_program, body: [...transformed_program.body] };
+		}
 		if (type_only_style_anchors.length > 0) {
 			transformed_program.body.unshift(...type_only_style_anchors);
 		}
@@ -751,7 +812,7 @@ export function createJsxTransform(platform) {
 		// lazy transform runs, so every `@{ … }` block / `@`-directive has already
 		// been lowered to its final closure / block shape. The lazy transform can
 		// then walk the complete function structure in one pass.
-		lower_remaining_jsx_code_blocks(expanded, transform_context);
+		const lowered_program = lower_remaining_jsx_code_blocks(expanded, transform_context);
 
 		// Apply lazy destructuring transforms to module-level code (top-level function
 		// declarations, arrow functions, etc.).
@@ -772,18 +833,28 @@ export function createJsxTransform(platform) {
 		// so lazy bindings declared inside a nested block or directive body are
 		// rewritten just like a flat function body.
 		if (!transform_context.typeOnly) {
-			preallocate_lazy_ids(/** @type {any} */ (expanded), transform_context);
+			preallocate_lazy_ids(/** @type {any} */ (lowered_program), transform_context);
 		}
 		const final_program = /** @type {any} */ (
 			transform_context.typeOnly
-				? expanded
-				: apply_lazy_transforms(/** @type {any} */ (expanded), new Map())
+				? lowered_program
+				: apply_lazy_transforms(/** @type {any} */ (lowered_program), new Map())
 		);
 
-		const result = print(/** @type {any} */ (final_program), tsx_with_ts_locations(), {
-			sourceMapSource: filename,
-			sourceMapContent: source,
-		});
+		const result = print(
+			final_program,
+			// typeOnly output is real TS input: re-emit preserved leading comments
+			// (@jsxImportSource / @ts-nocheck / triple-slash references) so TS
+			// semantics survive the comment-stripping print.
+			tsx_with_ts_locations(
+				transform_context.typeOnly,
+				transform_context.typeOnly ? transform_context.comments : undefined,
+			),
+			{
+				sourceMapSource: filename,
+				sourceMapContent: source,
+			},
+		);
 
 		const { css, cssHash } = render_css_result(/** @type {any} */ (stylesheets));
 
@@ -1707,7 +1778,7 @@ function get_active_native_tsrx_function(path) {
 
 /**
  * @param {any} node
- * @param {{ next: () => any, state: TransformContext, path: AST.Node[] }} context
+ * @param {{ next: () => any, visit: (node: any, state?: TransformContext) => any, state: TransformContext, path: AST.Node[] }} context
  * @returns {any}
  */
 function transform_function(node, context) {
@@ -1717,15 +1788,26 @@ function transform_function(node, context) {
 	// from here it flows through the existing native-component machinery exactly
 	// like the older fenced `{ return <> … </> }` shape.
 	const has_jsx_code_block_body = node.body?.type === 'JSXCodeBlock';
-	lower_jsx_code_block_function_body(node);
+	const lowered = lower_jsx_code_block_function_body(node);
+	if (lowered !== node) {
+		// The lowering produced a COPY; carry the native-body fact through the
+		// sanctioned metadata channel and re-dispatch so the walker transforms
+		// the lowered tree (terminates: the copy's body is a BlockStatement).
+		lowered.metadata = { ...(lowered.metadata || {}), native_tsrx_body: true };
+		return context.visit(lowered);
+	}
 
 	if (
 		has_jsx_code_block_body ||
 		node.metadata?.native_tsrx_function ||
+		node.metadata?.native_tsrx_body ||
 		function_has_native_tsrx_return(node)
 	) {
 		return transform_native_tsrx_function(node, context, {
-			nativeBody: has_jsx_code_block_body || !!node.metadata?.native_tsrx_function,
+			nativeBody:
+				has_jsx_code_block_body ||
+				!!node.metadata?.native_tsrx_function ||
+				!!node.metadata?.native_tsrx_body,
 		});
 	}
 
@@ -1733,11 +1815,14 @@ function transform_function(node, context) {
 }
 
 /**
+ * Lower a `@{ … }` body (JSXCodeBlock) to an ordinary block on a COPY built
+ * with the AST builders — the source function node is never mutated. Returns
+ * the input node unchanged when there is nothing to lower.
  * @param {any} node
- * @returns {void}
+ * @returns {any}
  */
 function lower_jsx_code_block_function_body(node) {
-	if (node.body?.type !== 'JSXCodeBlock') return;
+	if (node.body?.type !== 'JSXCodeBlock') return node;
 
 	const code_block = node.body;
 	const statements = [...code_block.body];
@@ -1758,10 +1843,11 @@ function lower_jsx_code_block_function_body(node) {
 		}
 		statements.push(b.return(render, code_block.render));
 	}
-	node.body = b.block(statements, code_block);
-	if (node.type === 'ArrowFunctionExpression') {
-		node.expression = false;
-	}
+	return {
+		...node,
+		body: b.block(statements, code_block),
+		...(node.type === 'ArrowFunctionExpression' ? { expression: false } : null),
+	};
 }
 
 /**
@@ -3039,46 +3125,62 @@ function expand_component_helpers(program) {
  * If one of those helpers contains a statement-container body, lower it before
  * the printer sees the helper subtree.
  *
+ * The tree is never mutated: replacements land on a shallow copy of the owning
+ * node (or array), so the return value must be used in place of the argument.
+ * Untouched subtrees are shared by reference with the input.
+ *
  * @param {any} node
  * @param {TransformContext} transform_context
  * @param {Set<any>} [seen]
- * @returns {void}
+ * @returns {any}
  */
 function lower_remaining_jsx_code_blocks(node, transform_context, seen = new Set()) {
-	if (!node || typeof node !== 'object' || seen.has(node)) return;
+	if (!node || typeof node !== 'object' || seen.has(node)) return node;
 	seen.add(node);
 
-	if (is_function_or_class_boundary(node)) {
-		lower_jsx_code_block_function_body(node);
-	}
+	// A code-block function body lowers to a fresh copy of the function node;
+	// its children are then walked below like any other node's.
+	let out = is_function_or_class_boundary(node) ? lower_jsx_code_block_function_body(node) : node;
+	const set = (/** @type {string} */ key, /** @type {any} */ value) => {
+		if (out[key] === value) return;
+		if (out === node) out = { ...node };
+		out[key] = value;
+	};
 
-	for (const key of Object.keys(node)) {
+	for (const key of Object.keys(out)) {
 		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') continue;
-		let value = node[key];
+		const value = out[key];
 		if (!value || typeof value !== 'object') continue;
 
 		if (Array.isArray(value)) {
-			if (key === 'body') {
-				value = node[key] = value.flatMap((child) => {
-					if (child?.type !== 'JSXCodeBlock') return [child];
-					const body_nodes = get_jsx_code_block_body_nodes(child, transform_context);
-					return mark_native_pretransformed_jsx(
-						build_render_statements(
-							body_nodes,
-							true,
-							transform_context,
-							is_authored_native_fragment(child.render) ? child.render : null,
-						),
-					);
-				});
-			}
-			for (const child of value) {
-				lower_remaining_jsx_code_blocks(child, transform_context, seen);
-			}
+			const expanded =
+				key === 'body' && value.some((child) => child?.type === 'JSXCodeBlock')
+					? value.flatMap((child) => {
+							if (child?.type !== 'JSXCodeBlock') return [child];
+							const body_nodes = get_jsx_code_block_body_nodes(child, transform_context);
+							return mark_native_pretransformed_jsx(
+								build_render_statements(
+									body_nodes,
+									true,
+									transform_context,
+									is_authored_native_fragment(child.render) ? child.render : null,
+								),
+							);
+						})
+					: value;
+			let changed = expanded !== value;
+			const result = expanded.map((child) => {
+				const walked = lower_remaining_jsx_code_blocks(child, transform_context, seen);
+				if (walked !== child) changed = true;
+				return walked;
+			});
+			if (changed) set(key, result);
 		} else {
-			lower_remaining_jsx_code_blocks(value, transform_context, seen);
+			set(key, lower_remaining_jsx_code_blocks(value, transform_context, seen));
 		}
 	}
+
+	return out;
 }
 
 /**
@@ -3202,9 +3304,8 @@ function get_loop_skip_if_consequent_body(node) {
  */
 function create_component_loop_skip_if_statement(node, render_nodes, transform_context) {
 	const consequent_body = /** @type {any[]} */ (get_loop_skip_if_consequent_body(node));
-	const branch_statements = build_render_statements(consequent_body, true, transform_context);
-	prepend_render_nodes_to_return_statements(
-		branch_statements,
+	const branch_statements = prepend_render_nodes_to_return_statements(
+		build_render_statements(consequent_body, true, transform_context),
 		render_nodes,
 		transform_context.typeOnly,
 	);
@@ -3221,19 +3322,23 @@ function create_component_loop_skip_if_statement(node, render_nodes, transform_c
 }
 
 /**
+ * Statements can be passed through `build_render_statements` by reference, so
+ * rewritten returns land on shallow copies; the returned array must be used in
+ * place of the argument.
+ *
  * @param {any[]} statements
  * @param {any[]} render_nodes
  * @param {boolean} [type_only]
- * @returns {void}
+ * @returns {any[]}
  */
 function prepend_render_nodes_to_return_statements(statements, render_nodes, type_only = false) {
 	if (render_nodes.length === 0) {
-		return;
+		return statements;
 	}
 
-	for (const statement of statements) {
-		prepend_render_nodes_to_return_statement(statement, render_nodes, false, type_only);
-	}
+	return /** @type {any[]} */ (
+		prepend_render_nodes_to_return_statement(statements, render_nodes, false, type_only)
+	);
 }
 
 /**
@@ -3241,7 +3346,7 @@ function prepend_render_nodes_to_return_statements(statements, render_nodes, typ
  * @param {any[]} render_nodes
  * @param {boolean} inside_nested_function
  * @param {boolean} [type_only]
- * @returns {void}
+ * @returns {any}
  */
 function prepend_render_nodes_to_return_statement(
 	node,
@@ -3250,7 +3355,7 @@ function prepend_render_nodes_to_return_statement(
 	type_only = false,
 ) {
 	if (!node || typeof node !== 'object') {
-		return;
+		return node;
 	}
 
 	if (
@@ -3262,33 +3367,44 @@ function prepend_render_nodes_to_return_statement(
 	}
 
 	if (!inside_nested_function && node.type === 'ReturnStatement') {
-		node.argument = combine_render_return_argument(render_nodes, node.argument, type_only);
-		return;
+		return {
+			...node,
+			argument: combine_render_return_argument(render_nodes, node.argument, type_only),
+		};
 	}
 
 	if (Array.isArray(node)) {
-		for (const child of node) {
-			prepend_render_nodes_to_return_statement(
+		let changed = false;
+		const result = node.map((child) => {
+			const walked = prepend_render_nodes_to_return_statement(
 				child,
 				render_nodes,
 				inside_nested_function,
 				type_only,
 			);
-		}
-		return;
+			if (walked !== child) changed = true;
+			return walked;
+		});
+		return changed ? result : node;
 	}
 
+	let out = node;
 	for (const key of Object.keys(node)) {
 		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') {
 			continue;
 		}
-		prepend_render_nodes_to_return_statement(
+		const walked = prepend_render_nodes_to_return_statement(
 			node[key],
 			render_nodes,
 			inside_nested_function,
 			type_only,
 		);
+		if (walked !== node[key]) {
+			if (out === node) out = { ...node };
+			out[key] = walked;
+		}
 	}
+	return out;
 }
 
 /**
@@ -4733,9 +4849,16 @@ function continue_to_bare_return(source_node) {
  */
 export function rewrite_loop_continues_to_bare_returns(node, is_root = true) {
 	if (Array.isArray(node)) {
-		return node.map((child) =>
-			rewrite_loop_continues_to_bare_returns(child, is_root && !is_loop_statement(child)),
-		);
+		let changed = false;
+		const result = node.map((child) => {
+			const walked = rewrite_loop_continues_to_bare_returns(
+				child,
+				is_root && !is_loop_statement(child),
+			);
+			if (walked !== child) changed = true;
+			return walked;
+		});
+		return changed ? result : node;
 	}
 
 	if (!node || typeof node !== 'object') {
@@ -4750,14 +4873,19 @@ export function rewrite_loop_continues_to_bare_returns(node, is_root = true) {
 		return node;
 	}
 
+	let out = node;
 	for (const key of Object.keys(node)) {
 		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') {
 			continue;
 		}
-		node[key] = rewrite_loop_continues_to_bare_returns(node[key], false);
+		const walked = rewrite_loop_continues_to_bare_returns(node[key], false);
+		if (walked !== node[key]) {
+			if (out === node) out = { ...node };
+			out[key] = walked;
+		}
 	}
 
-	return node;
+	return out;
 }
 
 /**
@@ -4921,7 +5049,7 @@ function for_of_statement_to_jsx_child(node, transform_context) {
 	}
 
 	const loop_params = get_for_of_iteration_params(node.left, node.index);
-	const loop_body = /** @type {any[]} */ (
+	let loop_body = /** @type {any[]} */ (
 		node.body.type === 'BlockStatement' ? node.body.body : [node.body]
 	);
 	validate_for_body_control_flow(loop_body, transform_context);
@@ -4952,10 +5080,10 @@ function for_of_statement_to_jsx_child(node, transform_context) {
 	}
 
 	if (implicit_non_hook_key_expression && should_apply_key_to_loop_body(loop_body)) {
-		apply_key_to_loop_body(loop_body, implicit_non_hook_key_expression);
+		loop_body = apply_key_to_loop_body(loop_body, implicit_non_hook_key_expression);
 	}
 
-	const body_statements = has_hooks
+	let body_statements = has_hooks
 		? hook_safe_render_statements(loop_body, key_expression, transform_context)
 		: build_render_statements(loop_body, true, transform_context);
 
@@ -4972,7 +5100,11 @@ function for_of_statement_to_jsx_child(node, transform_context) {
 
 	const non_hook_key_expression = key_expression ?? implicit_non_hook_key_expression;
 	if (!has_hooks && non_hook_key_expression) {
-		apply_key_to_render_statements(body_statements, non_hook_key_expression, transform_context);
+		body_statements = apply_key_to_render_statements(
+			body_statements,
+			non_hook_key_expression,
+			transform_context,
+		);
 	}
 
 	// Restore bindings
@@ -5025,32 +5157,40 @@ function for_of_statement_to_jsx_child(node, transform_context) {
 }
 
 /**
+ * Returns a copy of `body_nodes` where the first keyable element carries the
+ * key attribute on a rebuilt opening element — the source nodes are never
+ * mutated (they may belong to the caller's parsed AST).
  * @param {any[]} body_nodes
  * @param {any} key_expression
- * @returns {void}
+ * @returns {any[]}
  */
 function apply_key_to_loop_body(body_nodes, key_expression) {
-	for (const node of body_nodes) {
-		if (node.type === 'JSXElement') {
-			const attributes = node.openingElement?.attributes || [];
-			const has_key = attributes.some(
-				(/** @type {any} */ attr) =>
-					attr.type === 'JSXAttribute' &&
-					attr.name?.type === 'JSXIdentifier' &&
-					attr.name.name === 'key',
-			);
-
-			if (!has_key) {
-				attributes.push(
+	let applied = false;
+	return body_nodes.map((node) => {
+		if (applied || node.type !== 'JSXElement') return node;
+		applied = true;
+		const attributes = node.openingElement?.attributes || [];
+		const has_key = attributes.some(
+			(/** @type {any} */ attr) =>
+				attr.type === 'JSXAttribute' &&
+				attr.name?.type === 'JSXIdentifier' &&
+				attr.name.name === 'key',
+		);
+		if (has_key) return node;
+		return {
+			...node,
+			openingElement: {
+				...node.openingElement,
+				attributes: [
+					...attributes,
 					b.jsx_attribute(
 						b.jsx_id('key'),
 						to_jsx_expression_container(clone_expression_node(key_expression), key_expression),
 					),
-				);
-			}
-			return;
-		}
-	}
+				],
+			},
+		};
+	});
 }
 
 /**
@@ -5068,10 +5208,14 @@ function should_apply_key_to_loop_body(body_nodes) {
 }
 
 /**
+ * Statement entries can be shared with the source tree, so the keyed return
+ * lands on shallow copies; the returned array must be used in place of the
+ * argument.
+ *
  * @param {any[]} statements
  * @param {any} key_expression
  * @param {TransformContext} transform_context
- * @returns {void}
+ * @returns {any[]}
  */
 function apply_key_to_render_statements(statements, key_expression, transform_context) {
 	for (let i = statements.length - 1; i >= 0; i -= 1) {
@@ -5080,21 +5224,29 @@ function apply_key_to_render_statements(statements, key_expression, transform_co
 			continue;
 		}
 
-		if (statement.argument.type === 'JSXElement') {
-			apply_key_to_jsx_element(statement.argument, key_expression);
-		} else if (statement.argument.type === 'JSXFragment') {
+		let argument = statement.argument;
+		if (argument.type === 'JSXElement') {
+			argument = apply_key_to_jsx_element(argument, key_expression);
+		} else if (argument.type === 'JSXFragment') {
 			transform_context.needs_fragment = true;
-			statement.argument = keyed_fragment_to_jsx_element(statement.argument, key_expression);
+			argument = keyed_fragment_to_jsx_element(argument, key_expression);
 		}
 
-		return;
+		if (argument === statement.argument) {
+			return statements;
+		}
+		const result = [...statements];
+		result[i] = { ...statement, argument };
+		return result;
 	}
+	return statements;
 }
 
 /**
  * @param {any} element
  * @param {any} key_expression
- * @returns {void}
+ * @returns {any} the element itself when it already has a `key`, otherwise a
+ * shallow copy with the key attribute appended.
  */
 function apply_key_to_jsx_element(element, key_expression) {
 	const attributes = element.openingElement?.attributes || [];
@@ -5104,15 +5256,21 @@ function apply_key_to_jsx_element(element, key_expression) {
 			attr.name?.type === 'JSXIdentifier' &&
 			attr.name.name === 'key',
 	);
+	if (has_key) return element;
 
-	if (!has_key) {
-		attributes.push(
-			b.jsx_attribute(
-				b.jsx_id('key'),
-				to_jsx_expression_container(clone_expression_node(key_expression), key_expression),
-			),
-		);
-	}
+	return {
+		...element,
+		openingElement: {
+			...element.openingElement,
+			attributes: [
+				...attributes,
+				b.jsx_attribute(
+					b.jsx_id('key'),
+					to_jsx_expression_container(clone_expression_node(key_expression), key_expression),
+				),
+			],
+		},
+	};
 }
 
 /**

package/src/transform/segments.js

@@ -962,19 +962,12 @@ export function convert_source_map_to_mappings(
 				const is_method = node.metadata?.is_method;
 
 				if (node.type === 'ArrowFunctionExpression' && node.loc) {
-					const start_key = `${node.loc.start.line}:${node.loc.start.column}`;
-					const end_key = `${node.loc.end.line}:${node.loc.end.column}`;
-
-					if (src_to_gen_map.has(start_key) && src_to_gen_map.has(end_key)) {
-						mappings.push(
-							get_mapping_from_node(
-								node,
-								src_to_gen_map,
-								gen_line_offsets,
-								mapping_data_verify_only,
-							),
-						);
-					}
+					// The printer emits node-level boundary markers for arrows (their
+					// span can start at a bare `(`), so the strict lookup always
+					// resolves — no defensive has() guard.
+					mappings.push(
+						get_mapping_from_node(node, src_to_gen_map, gen_line_offsets, mapping_data_verify_only),
+					);
 				}
 
 				// Add the function keyword token.
@@ -987,41 +980,68 @@ export function convert_source_map_to_mappings(
 					const function_hover = create_function_hover_replacement(
 						/** @type {AST.Parameter[]} */ (node.params),
 					);
-					let start_col = node_fn.loc.start.column;
-					let start = node_fn.start;
-					const async_keyword = 'async';
+					// Keyword SOURCE spans come from the LEXER (parse-time
+					// `tsrx_keyword_tokens`, opt-in via ParseOptions.keywordTokens):
+					// no AST node records them, offset arithmetic breaks on extra
+					// whitespace, and text search breaks on comments. Fall back to
+					// node-start-anchored arithmetic when tokens were not collected.
+					const keyword_bound =
+						node_fn.id?.start ?? node_fn.params?.[0]?.start ?? node_fn.body?.start ?? node_fn.end;
+					/** @type {Array<{ value: string, start: number, end: number, loc: AST.SourceLocation }>} */
+					const lexer_tokens = /** @type {any} */ (ast_from_source).tsrx_keyword_tokens ?? [];
+					/**
+					 * @param {'async' | 'function'} keyword
+					 * @param {number} from
+					 * @returns {AST.SourceLocation | null}
+					 */
+					const keyword_loc = (keyword, from) => {
+						const token = lexer_tokens.find(
+							(candidate) =>
+								candidate.value === keyword &&
+								candidate.start >= from &&
+								candidate.start < keyword_bound,
+						);
+						if (token) return token.loc;
+						if (lexer_tokens.length > 0) return null;
+						// Arithmetic fallback (callers that do not collect tokens):
+						// assumes the historical `async` + one-space + `function`
+						// single-line layout.
+						const offset =
+							keyword === 'function' && node_fn.async
+								? node_fn.start + 'async '.length
+								: node_fn.start;
+						const start_pos = offset_to_line_col(offset, src_line_offsets);
+						const end_pos = offset_to_line_col(offset + keyword.length, src_line_offsets);
+						return { start: start_pos, end: end_pos };
+					};
 
+					let function_from = node_fn.start;
 					if (node_fn.async) {
-						// We explicitly mapped async and function in esrap
+						const async_loc = keyword_loc('async', node_fn.start);
+						if (async_loc) {
+							tokens.push({
+								source: 'async',
+								generated: 'async',
+								loc: async_loc,
+								metadata: {},
+							});
+							function_from = loc_to_offset(
+								async_loc.end.line,
+								async_loc.end.column,
+								src_line_offsets,
+							);
+						}
+					}
+
+					const function_loc = keyword_loc('function', function_from);
+					if (function_loc) {
 						tokens.push({
-							source: async_keyword,
-							generated: async_keyword,
-							loc: {
-								start: { line: node_fn.loc.start.line, column: start_col },
-								end: {
-									line: node_fn.loc.start.line,
-									column: start_col + async_keyword.length,
-								},
-							},
-							metadata: {},
+							source: 'function',
+							generated: 'function',
+							loc: function_loc,
+							metadata: function_hover ? { hover: function_hover } : {},
 						});
-
-						start_col += async_keyword.length + 1; // +1 for space
-						start += async_keyword.length + 1;
 					}
-
-					tokens.push({
-						source: 'function',
-						generated: 'function',
-						loc: {
-							start: { line: node_fn.loc.start.line, column: start_col },
-							end: {
-								line: node_fn.loc.start.line,
-								column: start_col + 'function'.length,
-							},
-						},
-						metadata: function_hover ? { hover: function_hover } : {},
-					});
 				}
 
 				// Visit in source order: id, params, body

package/src/utils/builders.js

@@ -251,6 +251,22 @@ export function export_default(declaration) {
 	return { type: 'ExportDefaultDeclaration', declaration, metadata: { path: [] } };
 }
 
+/**
+ * @param {string | AST.Identifier} local
+ * @param {string | AST.Identifier} [exported]
+ * @param {AST.ExportSpecifier['exportKind']} [exportKind]
+ * @returns {AST.ExportSpecifier}
+ */
+export function export_specifier(local, exported = local, exportKind = 'value') {
+	return {
+		type: 'ExportSpecifier',
+		local: typeof local === 'string' ? id(local) : local,
+		exported: typeof exported === 'string' ? id(exported) : exported,
+		exportKind,
+		metadata: { path: [] },
+	};
+}
+
 /**
  * @param {AST.Declaration | null} declaration
  * @param {AST.ExportSpecifier[]} [specifiers]

package/types/index.d.ts

@@ -230,12 +230,14 @@ declare module 'estree' {
 	interface MethodDefinition {
 		typeParameters?: TSTypeParameterDeclaration;
 		accessibility?: Accessibility;
+		optional?: boolean;
 	}
 
 	interface PropertyDefinition {
 		accessibility?: Accessibility;
 		readonly?: boolean;
 		optional?: boolean;
+		definite?: boolean;
 	}
 
 	interface ClassDeclaration {
@@ -484,6 +486,9 @@ declare module 'estree' {
 	interface ExportNamedDeclaration {
 		exportKind: TSESTree.ExportNamedDeclaration['exportKind'];
 	}
+	interface ExportSpecifier {
+		exportKind: TSESTree.ExportSpecifier['exportKind'];
+	}
 
 	interface BaseNodeWithoutComments {
 		// Adding start, end for now as always there
@@ -1231,6 +1236,13 @@ export interface ParseError {
 export interface ParseOptions {
 	collect?: boolean;
 	loose?: boolean;
+	preserveParens?: boolean;
+	/**
+	 * Collect `async`/`function` keyword tokens from the lexer onto the
+	 * returned program (`tsrx_keyword_tokens`) so mapping collection can span
+	 * keywords exactly. Volar/typeOnly parses opt in.
+	 */
+	keywordTokens?: boolean;
 	errors?: CompileError[];
 	comments?: AST.CommentWithLocation[];
 }