@tsrx/core 0.0.19 → 0.0.21

package/src/transform/jsx/index.js

@@ -31,6 +31,7 @@ import {
 	jsx_attribute as build_jsx_attribute,
 	jsx_id as build_jsx_id,
 } from '../../utils/builders.js';
+import * as b from '../../utils/builders.js';
 import {
 	apply_lazy_transforms,
 	collect_lazy_bindings_from_component,
@@ -92,6 +93,7 @@ export function createJsxTransform(platform) {
 		const module_uses_server_directive = should_scan_use_server_directive
 			? has_use_server_directive(ast)
 			: true;
+		const collect = !!(options?.collect || options?.loose);
 		/** @type {any[]} */
 		const stylesheets = [];
 
@@ -107,8 +109,8 @@ export function createJsxTransform(platform) {
 			lazy_next_id: 0,
 			current_css_hash: null,
 			filename: filename ?? null,
-			loose: !!options?.loose,
-			errors: options?.loose ? options?.errors : undefined,
+			collect,
+			errors: collect ? options?.errors : undefined,
 			comments: options?.comments,
 			// Platforms can seed their own tracking state (e.g. solid's
 			// needs_show / needs_for flags) via `hooks.initialState`.
@@ -120,7 +122,12 @@ export function createJsxTransform(platform) {
 		walk(/** @type {any} */ (ast), transform_context, {
 			ReturnStatement(node, { next, path }) {
 				if (get_component_from_path(path)) {
-					validate_component_return_statement(node, filename);
+					validate_component_return_statement(
+						node,
+						filename,
+						transform_context.errors,
+						transform_context.comments,
+					);
 				}
 
 				return next();
@@ -583,6 +590,105 @@ function build_render_statements(body_nodes, return_null_when_empty, transform_c
 			continue;
 		}
 
+		if (
+			child.type === 'IfStatement' &&
+			!child.alternate &&
+			!is_returning_if_statement(child) &&
+			!transform_context.platform.hooks?.isTopLevelSetupCall &&
+			body_contains_top_level_hook_call([child], transform_context, true) &&
+			i + 1 < body_nodes.length
+		) {
+			statements.push(
+				...create_continuation_lift_if_statement(
+					child,
+					body_nodes.slice(i + 1),
+					render_nodes,
+					transform_context,
+				),
+			);
+			transform_context.available_bindings = saved_bindings;
+			return statements;
+		}
+
+		if (
+			child.type === 'ForOfStatement' &&
+			!child.await &&
+			!transform_context.platform.hooks?.isTopLevelSetupCall &&
+			!transform_context.platform.hooks?.controlFlow?.forOf &&
+			body_contains_top_level_hook_call(
+				child.body.type === 'BlockStatement' ? child.body.body : [child.body],
+				transform_context,
+				true,
+			)
+		) {
+			const for_of_continuation = body_nodes.slice(i + 1);
+			const hoisted = build_hoisted_for_of_with_hooks(
+				child,
+				for_of_continuation,
+				transform_context,
+			);
+			if (hoisted) {
+				statements.push(...hoisted.hoist_statements);
+				if (for_of_continuation.length > 0) {
+					// Tail was lifted into the helper; everything after the for-of
+					// now lives there. Combine prior render_nodes with the iteration
+					// JSX and return.
+					statements.push({
+						type: 'ReturnStatement',
+						argument: combine_render_return_argument(render_nodes, hoisted.jsx_child),
+						metadata: { path: [] },
+					});
+					transform_context.available_bindings = saved_bindings;
+					return statements;
+				}
+				if (interleaved && is_capturable_jsx_child(hoisted.jsx_child)) {
+					const { declaration, reference } = captureJsxChild(hoisted.jsx_child, capture_index++);
+					statements.push(declaration);
+					render_nodes.push(reference);
+				} else {
+					render_nodes.push(hoisted.jsx_child);
+				}
+				continue;
+			}
+		}
+
+		if (
+			child.type === 'TryStatement' &&
+			!child.finalizer &&
+			!transform_context.platform.hooks?.isTopLevelSetupCall &&
+			try_statement_contains_hooks(child, transform_context) &&
+			i + 1 < body_nodes.length
+		) {
+			statements.push(
+				...create_continuation_lift_try_statement(
+					child,
+					body_nodes.slice(i + 1),
+					render_nodes,
+					transform_context,
+				),
+			);
+			transform_context.available_bindings = saved_bindings;
+			return statements;
+		}
+
+		if (
+			child.type === 'SwitchStatement' &&
+			!transform_context.platform.hooks?.isTopLevelSetupCall &&
+			body_contains_top_level_hook_call([child], transform_context, true) &&
+			i + 1 < body_nodes.length
+		) {
+			statements.push(
+				...create_continuation_lift_switch_statement(
+					child,
+					body_nodes.slice(i + 1),
+					render_nodes,
+					transform_context,
+				),
+			);
+			transform_context.available_bindings = saved_bindings;
+			return statements;
+		}
+
 		if (is_jsx_child(child)) {
 			const jsx = to_jsx_child(child, transform_context);
 			if (interleaved && is_capturable_jsx_child(jsx)) {
@@ -832,35 +938,26 @@ function create_helper_props_property(binding) {
  */
 function create_helper_component_element(helper_id, bindings, source_node, mapping = {}) {
 	const { mapWrapper = true, mapBindingNames = true, mapBindingValues = true } = mapping;
-	const attributes = bindings.map(
-		(binding) =>
-			/** @type {any} */ ({
-				type: 'JSXAttribute',
-				name: identifier_to_jsx_name(
-					mapBindingNames ? clone_identifier(binding) : create_generated_identifier(binding.name),
-				),
-				value: to_jsx_expression_container(
-					mapBindingValues ? clone_identifier(binding) : create_generated_identifier(binding.name),
-					binding,
-				),
-				metadata: { path: [] },
-			}),
+	const attributes = bindings.map((binding) =>
+		b.jsx_attribute(
+			identifier_to_jsx_name(
+				mapBindingNames ? clone_identifier(binding) : create_generated_identifier(binding.name),
+			),
+			to_jsx_expression_container(
+				mapBindingValues ? clone_identifier(binding) : create_generated_identifier(binding.name),
+				binding,
+			),
+		),
 	);
 
-	const openingElement = {
-		type: 'JSXOpeningElement',
-		name: identifier_to_jsx_name(clone_identifier(helper_id)),
+	const opening_element = b.jsx_opening_element(
+		identifier_to_jsx_name(clone_identifier(helper_id)),
 		attributes,
-		selfClosing: true,
-		metadata: { path: [] },
-	};
-	const element = /** @type {any} */ ({
-		type: 'JSXElement',
-		openingElement: mapWrapper ? set_loc(openingElement, source_node) : openingElement,
-		closingElement: null,
-		children: [],
-		metadata: { path: [] },
-	});
+		true,
+	);
+	const element = b.jsx_element_fresh(
+		mapWrapper ? set_loc(opening_element, source_node) : opening_element,
+	);
 
 	return mapWrapper ? set_loc(element, source_node) : element;
 }
@@ -1050,21 +1147,7 @@ function hoist_static_render_nodes(render_nodes, transform_context) {
 		const name = create_helper_name(transform_context.helper_state, 'static');
 		const id = create_generated_identifier(name);
 
-		transform_context.helper_state.statics.push(
-			/** @type {any} */ ({
-				type: 'VariableDeclaration',
-				kind: 'const',
-				declarations: [
-					{
-						type: 'VariableDeclarator',
-						id,
-						init: node,
-						metadata: { path: [] },
-					},
-				],
-				metadata: { path: [] },
-			}),
-		);
+		transform_context.helper_state.statics.push(b.const(id, node));
 
 		render_nodes[i] = to_jsx_expression_container(clone_identifier(id), node);
 	}
@@ -1170,25 +1253,13 @@ function create_component_return_statement(
 	source_node,
 	map_render_node_locations = true,
 ) {
-	return set_loc(
-		/** @type {any} */ ({
-			type: 'ReturnStatement',
-			argument: build_return_expression(
-				render_nodes.map((node) =>
-					map_render_node_locations
-						? clone_expression_node(node)
-						: clone_expression_node_without_locations(node),
-				),
-			) || {
-				type: 'Literal',
-				value: null,
-				raw: 'null',
-				metadata: { path: [] },
-			},
-			metadata: { path: [] },
-		}),
-		source_node,
+	const cloned = render_nodes.map((node) =>
+		map_render_node_locations
+			? clone_expression_node(node)
+			: clone_expression_node_without_locations(node),
 	);
+
+	return set_loc(b.return(build_return_expression(cloned) || create_null_literal()), source_node);
 }
 
 /**
@@ -1200,20 +1271,14 @@ function create_component_lone_return_if_statement(node, render_nodes) {
 	const consequent_body = get_if_consequent_body(node);
 
 	return set_loc(
-		/** @type {any} */ ({
-			type: 'IfStatement',
-			test: node.test,
-			consequent: set_loc(
-				/** @type {any} */ ({
-					type: 'BlockStatement',
-					body: [create_component_return_statement(render_nodes, consequent_body[0], false)],
-					metadata: { path: [] },
-				}),
+		b.if(
+			node.test,
+			set_loc(
+				b.block([create_component_return_statement(render_nodes, consequent_body[0], false)]),
 				node.consequent,
 			),
-			alternate: null,
-			metadata: { path: [] },
-		}),
+			null,
+		),
 		node,
 	);
 }
@@ -1229,23 +1294,84 @@ function create_component_returning_if_statement(node, render_nodes, transform_c
 	const branch_statements = build_render_statements(consequent_body, true, transform_context);
 	prepend_render_nodes_to_return_statements(branch_statements, render_nodes);
 
-	return set_loc(
-		/** @type {any} */ ({
-			type: 'IfStatement',
-			test: node.test,
-			consequent: set_loc(
-				/** @type {any} */ ({
-					type: 'BlockStatement',
-					body: branch_statements,
-					metadata: { path: [] },
-				}),
-				node.consequent,
-			),
-			alternate: null,
-			metadata: { path: [] },
-		}),
-		node,
-	);
+	return set_loc(b.if(node.test, set_loc(b.block(branch_statements), node.consequent), null), node);
+}
+
+/* ---------------------------------------------------------------------- *
+ * Continuation-lift primitives shared across if / switch / try / for-of  *
+ * ---------------------------------------------------------------------- */
+
+/**
+ * Build the helper component that owns the post-control-flow continuation.
+ * Same shape as `create_hook_safe_helper`; named for intent at lift call sites.
+ *
+ * @param {any[]} continuation_body
+ * @param {any} source_node
+ * @param {TransformContext} transform_context
+ * @returns {{ setup_statements: any[], component_element: ESTreeJSX.JSXElement }}
+ */
+function build_tail_helper(continuation_body, source_node, transform_context) {
+	return create_hook_safe_helper(continuation_body, undefined, source_node, transform_context);
+}
+
+/**
+ * Clone the tail helper's component element for embedding inside another
+ * branch's body. Loses location info because the same element appears in
+ * multiple positions and downstream tooling treats AST nodes as identity-keyed.
+ *
+ * @param {{ component_element: ESTreeJSX.JSXElement }} tail_helper
+ * @returns {any}
+ */
+function clone_tail_invocation(tail_helper) {
+	return clone_expression_node_without_locations(tail_helper.component_element);
+}
+
+/**
+ * Return `[...body, <TailHelper x={x} />]` so the branch's render output
+ * includes the tail invocation and the post-hook locals flow forward.
+ * Used by if / switch / try (unconditional append). For-of uses a different
+ * shape — gating on `_tsrx_isLast_<n>` — so it constructs its own.
+ *
+ * @param {any[]} body
+ * @param {{ component_element: ESTreeJSX.JSXElement }} tail_helper
+ * @returns {any[]}
+ */
+function append_tail_invocation(body, tail_helper) {
+	return [...body, clone_tail_invocation(tail_helper)];
+}
+
+/**
+ * Build a `return <combined-render-fragment>;` statement, prepending any
+ * `render_nodes` collected before the control-flow construct so they don't
+ * get dropped on the lift path.
+ *
+ * @param {any[]} render_nodes
+ * @param {any} jsx_child
+ * @returns {any}
+ */
+function combined_return_statement(render_nodes, jsx_child) {
+	return b.return(combine_render_return_argument(render_nodes, jsx_child));
+}
+
+/**
+ * Hoist a for-of iteration source into a generated `let` and add a
+ * normalization assignment via `Array.isArray(src) ? src : Array.from(src)`.
+ * Always emits both — even when the source is already a simple identifier —
+ * so the loop-scoped TS type aliases have a stable name to reference and the
+ * runtime check skips the copy when the value is already an array.
+ *
+ * @param {AST.Identifier} source_id
+ * @param {any} source_expr
+ * @returns {{ source_decl: any, source_normalize_decl: any }}
+ */
+function build_array_normalization_decls(source_id, source_expr) {
+	const source_decl = b.let(clone_identifier(source_id), clone_expression_node(source_expr));
+	const is_array_call = b.call(b.member(b.id('Array'), 'isArray'), clone_identifier(source_id));
+	const from_call = b.call(b.member(b.id('Array'), 'from'), clone_identifier(source_id));
+	const normalized = b.conditional(is_array_call, clone_identifier(source_id), from_call);
+	const source_normalize_decl = b.stmt(b.assignment('=', clone_identifier(source_id), normalized));
+
+	return { source_decl, source_normalize_decl };
 }
 
 /**
@@ -1277,43 +1403,582 @@ function create_component_helper_split_returning_if_statements(
 		node,
 		transform_context,
 	);
+
+	const branch_block = set_loc(
+		b.block([
+			...branch_helper.setup_statements,
+			combined_return_statement(render_nodes, branch_helper.component_element),
+		]),
+		node.consequent,
+	);
+
 	return [
-		set_loc(
-			/** @type {any} */ ({
-				type: 'IfStatement',
-				test: node.test,
-				consequent: set_loc(
-					/** @type {any} */ ({
-						type: 'BlockStatement',
-						body: [
-							...branch_helper.setup_statements,
-							{
-								type: 'ReturnStatement',
-								argument: combine_render_return_argument(
-									render_nodes,
-									branch_helper.component_element,
-								),
-								metadata: { path: [] },
-							},
-						],
-						metadata: { path: [] },
-					}),
-					node.consequent,
-				),
-				alternate: null,
-				metadata: { path: [] },
-			}),
-			node,
-		),
+		set_loc(b.if(node.test, branch_block, null), node),
 		...continuation_helper.setup_statements,
-		{
-			type: 'ReturnStatement',
-			argument: combine_render_return_argument(render_nodes, continuation_helper.component_element),
-			metadata: { path: [] },
+		combined_return_statement(render_nodes, continuation_helper.component_element),
+	];
+}
+
+/**
+ * Lift a non-returning `if` whose consequent contains hook calls plus the
+ * statements that follow it into helper components.
+ *
+ * Without this, the consequent's hook would be wrapped into a child component
+ * (StatementBodyHook) but any code after the `if` that reads bindings the hook
+ * mutates would observe the pre-hook value, because React commits children
+ * after their parent has finished rendering. The fix mirrors the early-return
+ * splitter: emit a tail helper that owns the post-`if` statements, append a
+ * call to it inside the branch helper so the post-hook bindings flow forward,
+ * and render the tail helper directly when the `if` is false.
+ *
+ * @param {any} if_node
+ * @param {any[]} continuation_body
+ * @param {any[]} render_nodes
+ * @param {TransformContext} transform_context
+ * @returns {any[]}
+ */
+function create_continuation_lift_if_statement(
+	if_node,
+	continuation_body,
+	render_nodes,
+	transform_context,
+) {
+	const consequent_body = get_if_consequent_body(if_node);
+	const tail_helper = build_tail_helper(continuation_body, if_node, transform_context);
+	const branch_helper = create_hook_safe_helper(
+		append_tail_invocation(consequent_body, tail_helper),
+		undefined,
+		if_node.consequent,
+		transform_context,
+	);
+
+	const branch_block = set_loc(
+		b.block([
+			...branch_helper.setup_statements,
+			combined_return_statement(render_nodes, branch_helper.component_element),
+		]),
+		if_node.consequent,
+	);
+
+	return [
+		...tail_helper.setup_statements,
+		set_loc(b.if(if_node.test, branch_block, null), if_node),
+		combined_return_statement(render_nodes, tail_helper.component_element),
+	];
+}
+
+/**
+ * Continuation lift for `try` / `try / pending / catch` statements. Same
+ * shape as if/switch: build a tail helper from the post-`try` statements, and
+ * append a clone of its invocation to the try body and the catch body so the
+ * post-hook locals inside each branch flow forward into the tail. The pending
+ * body is left untouched — when Suspense renders the pending fallback the
+ * parent's render is unwound, so the tail wouldn't run in source semantics
+ * either. Once augmented, the existing try transform builds the
+ * Suspense / TsrxErrorBoundary wrapper as usual.
+ *
+ * @param {any} node - TryStatement
+ * @param {any[]} continuation_body
+ * @param {any[]} render_nodes
+ * @param {TransformContext} transform_context
+ * @returns {any[]}
+ */
+function create_continuation_lift_try_statement(
+	node,
+	continuation_body,
+	render_nodes,
+	transform_context,
+) {
+	const tail_helper = build_tail_helper(continuation_body, node, transform_context);
+
+	const augmented_block = {
+		...node.block,
+		body: append_tail_invocation(node.block.body || [], tail_helper),
+	};
+
+	let augmented_handler = node.handler;
+	if (node.handler) {
+		augmented_handler = {
+			...node.handler,
+			body: {
+				...node.handler.body,
+				body: append_tail_invocation(node.handler.body.body || [], tail_helper),
+			},
+		};
+	}
+
+	const augmented_try = {
+		...node,
+		block: augmented_block,
+		handler: augmented_handler,
+	};
+
+	const try_jsx_child = (
+		transform_context.platform.hooks?.controlFlow?.tryStatement ?? try_statement_to_jsx_child
+	)(augmented_try, transform_context);
+
+	return [...tail_helper.setup_statements, combined_return_statement(render_nodes, try_jsx_child)];
+}
+
+/**
+ * @param {any} node - TryStatement
+ * @param {TransformContext} transform_context
+ * @returns {boolean}
+ */
+function try_statement_contains_hooks(node, transform_context) {
+	if (body_contains_top_level_hook_call(node.block?.body || [], transform_context, true)) {
+		return true;
+	}
+	if (
+		node.handler &&
+		body_contains_top_level_hook_call(node.handler.body?.body || [], transform_context, true)
+	) {
+		return true;
+	}
+	if (
+		node.pending &&
+		body_contains_top_level_hook_call(node.pending.body || [], transform_context, true)
+	) {
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Continuation lift for `switch` statements. Same shape as the if-version:
+ * each case body is wrapped in its own helper component that ends with a
+ * call to a shared tail helper, so post-hook bindings inside any case flow
+ * forward to the statements after the switch. The fall-through return at
+ * the end renders the tail helper directly, covering the case where no
+ * `case` (and no `default`) matched.
+ *
+ * Empty fall-through cases (`case 'a':` with no body, falling through to
+ * the next case) are preserved as-is — they must not get their own helper
+ * because that would convert fall-through into early-return.
+ *
+ * @param {any} switch_node
+ * @param {any[]} continuation_body
+ * @param {any[]} render_nodes
+ * @param {TransformContext} transform_context
+ * @returns {any[]}
+ */
+function create_continuation_lift_switch_statement(
+	switch_node,
+	continuation_body,
+	render_nodes,
+	transform_context,
+) {
+	const tail_helper = build_tail_helper(continuation_body, switch_node, transform_context);
+
+	// Per-case info computed once: own body (statements before any
+	// terminator) and whether the case has a `break` / `return`.
+	const case_info = switch_node.cases.map((/** @type {any} */ c) => {
+		const consequent = flatten_switch_consequent(c.consequent || []);
+		const own_body = [];
+		let own_has_terminator = false;
+		for (const node of consequent) {
+			if (node.type === 'BreakStatement' || node.type === 'ReturnStatement') {
+				own_has_terminator = true;
+				break;
+			}
+			own_body.push(node);
+		}
+		return { own_body, own_has_terminator };
+	});
+
+	// Allocate helper ids in source order (forward pass) so the snapshot's
+	// `StatementBodyHook<N>` numbering reads top-to-bottom by case position.
+	/** @type {Array<AST.Identifier | null>} */
+	const helper_ids = case_info.map(
+		(/** @type {{ own_body: any[], own_has_terminator: boolean }} */ info) =>
+			info.own_body.length === 0
+				? null
+				: create_generated_identifier(create_local_statement_component_name(transform_context)),
+	);
+
+	// Build helpers in reverse order: each fall-through case's helper body
+	// invokes the *next* case's helper, so the chain forwards post-mutation
+	// locals through the switch. Reverse iteration ensures the next helper's
+	// component_element is already constructed when we need to embed it.
+	/** @type {Array<{ setup_statements: any[], component_element: any } | null>} */
+	const case_helper_by_index = new Array(switch_node.cases.length).fill(null);
+	for (let i = switch_node.cases.length - 1; i >= 0; i--) {
+		const { own_body, own_has_terminator } = case_info[i];
+		if (own_body.length === 0) continue;
+
+		// Determine the downstream helper this case invokes after its own body.
+		// - With a terminator: invoke the tail helper directly (case exits switch).
+		// - Otherwise (fall-through): invoke the next non-empty case's helper,
+		//   or the tail if nothing else follows.
+		let downstream;
+		if (own_has_terminator) {
+			downstream = tail_helper;
+		} else {
+			let next_helper = null;
+			for (let j = i + 1; j < switch_node.cases.length; j++) {
+				if (case_helper_by_index[j]) {
+					next_helper = case_helper_by_index[j];
+					break;
+				}
+			}
+			downstream = next_helper ?? tail_helper;
+		}
+
+		case_helper_by_index[i] = create_hook_safe_helper(
+			append_tail_invocation(own_body, downstream),
+			undefined,
+			switch_node.cases[i],
+			transform_context,
+			/** @type {any} */ (helper_ids[i]),
+		);
+	}
+
+	const new_cases = switch_node.cases.map(
+		(/** @type {any} */ original_case, /** @type {number} */ i) => {
+			const helper = case_helper_by_index[i];
+			if (helper) {
+				return b.switch_case(original_case.test, [
+					combined_return_statement(render_nodes, helper.component_element),
+				]);
+			}
+
+			const { own_body, own_has_terminator } = case_info[i];
+			if (own_body.length === 0 && own_has_terminator) {
+				// `case 'a': break;` — exits the switch, then runs the tail.
+				return b.switch_case(original_case.test, [
+					combined_return_statement(render_nodes, tail_helper.component_element),
+				]);
+			}
+			// Genuine empty fall-through (`case 'a': case 'b': ...`).
+			return b.switch_case(original_case.test, []);
 		},
+	);
+
+	// Hoist all case helpers' setup statements above the switch in source
+	// order so the switch body is purely a dispatcher.
+	const case_helper_setup_statements = [];
+	for (const helper of case_helper_by_index) {
+		if (helper) case_helper_setup_statements.push(...helper.setup_statements);
+	}
+
+	return [
+		...tail_helper.setup_statements,
+		...case_helper_setup_statements,
+		set_loc(b.switch(switch_node.discriminant, new_cases), switch_node),
+		combined_return_statement(render_nodes, tail_helper.component_element),
 	];
 }
 
+/**
+ * Hoist the helper for a hook-bearing for-of body out of the iteration
+ * callback so the helper is declared once per render rather than re-bound on
+ * every iteration. Loop-scoped param types are derived from the iteration
+ * source via a TS `type` alias (rather than the const+typeof pattern used
+ * for outer bindings, which would require the loop var to be in scope).
+ *
+ * The iteration source is hoisted into a generated `let` and normalized via
+ * `Array.isArray(src) ? src : Array.from(src)` so any Iterable / ArrayLike
+ * works while skipping the copy when the source is already an array. The
+ * iteration itself is emitted as `source.map((item, i) => ...)`.
+ *
+ * If `continuation_body` is non-empty (the for-of has a tail) we also lift
+ * the tail into a TailHelper and call it conditionally on the last iteration
+ * via an `isLast={i === source.length - 1}` prop on the loop helper. The
+ * loop helper's mutated locals (post-`useState`) flow into the TailHelper as
+ * its props. When the source is empty, `.map` returns `[]` and the TailHelper
+ * never renders — we add a sibling fallback so the source's tail still runs
+ * with the original outer values in that case.
+ *
+ * Bails out (returns null) when the loop pattern is destructured — deriving
+ * element types from a tuple/object pattern is more involved and deferred.
+ *
+ * @param {any} node - ForOfStatement
+ * @param {any[]} continuation_body
+ * @param {TransformContext} transform_context
+ * @returns {{ hoist_statements: any[], jsx_child: any } | null}
+ */
+function build_hoisted_for_of_with_hooks(node, continuation_body, transform_context) {
+	const loop_params = get_for_of_iteration_params(node.left, node.index);
+	for (const param of loop_params) {
+		if (param.type !== 'Identifier') return null;
+	}
+
+	const has_tail = continuation_body.length > 0;
+	const original_loop_body = node.body.type === 'BlockStatement' ? node.body.body : [node.body];
+
+	// When there's a tail, build TailHelper first so its component_element can
+	// be embedded inside the loop helper's body (gated on isLast). The
+	// synthetic isLast prop uses the loop helper's index (which will be the
+	// next one assigned, since `create_hook_safe_helper` for the tail just
+	// consumed one) so it lines up with `StatementBodyHook<N>` in the output.
+	let tail_helper = null;
+	/** @type {AST.Identifier} */ let tail_synthetic_id;
+	if (has_tail) {
+		tail_helper = build_tail_helper(continuation_body, node, transform_context);
+		tail_synthetic_id = create_generated_identifier(
+			`_tsrx_isLast_${transform_context.local_statement_component_index + 1}`,
+		);
+	} else {
+		tail_synthetic_id = /** @type {any} */ (null);
+	}
+	const loop_body = has_tail
+		? [
+				...original_loop_body,
+				b.jsx_expression_container(
+					b.logical(
+						'&&',
+						clone_identifier(tail_synthetic_id),
+						clone_tail_invocation(/** @type {any} */ (tail_helper)),
+					),
+				),
+			]
+		: original_loop_body;
+
+	const source_id = create_generated_identifier(
+		`_tsrx_iteration_items_${transform_context.local_statement_component_index + 1}`,
+	);
+	const { source_decl, source_normalize_decl } = build_array_normalization_decls(
+		source_id,
+		node.right,
+	);
+
+	const saved_bindings = transform_context.available_bindings;
+	transform_context.available_bindings = new Map(saved_bindings);
+	for (const param of loop_params) {
+		collect_pattern_bindings(param, transform_context.available_bindings);
+	}
+
+	const all_helper_bindings = get_referenced_helper_bindings(
+		loop_body,
+		transform_context.available_bindings,
+	);
+	const loop_scoped_names = new Set(loop_params.map((/** @type {any} */ p) => p.name));
+	const outer_bindings = all_helper_bindings.filter((b) => !loop_scoped_names.has(b.name));
+	const loop_bindings = all_helper_bindings.filter((b) => loop_scoped_names.has(b.name));
+
+	const helper_id = create_generated_identifier(
+		create_local_statement_component_name(transform_context),
+	);
+
+	const outer_aliases = outer_bindings.map((binding) =>
+		create_helper_type_alias_declaration(helper_id, binding),
+	);
+	const loop_aliases = loop_bindings.map((binding) =>
+		create_loop_scoped_type_alias_declaration(helper_id, binding, source_id, loop_params),
+	);
+
+	// Synthetic `isLast` prop on the loop helper when there's a tail. It's
+	// passed from the .map callback as `i === source.length - 1` so the loop
+	// helper renders the tail helper only on the last iteration. We do not
+	// gate on this prop's value here — the JSXLogicalExpression appended to
+	// `loop_body` does the gating at render time.
+	const tail_isLast_alias = has_tail
+		? {
+				id: create_generated_identifier(`_tsrx_${helper_id.name}_isLast`),
+				declaration: b.ts_type_alias(
+					create_generated_identifier(`_tsrx_${helper_id.name}_isLast`),
+					b.ts_keyword_type('boolean'),
+				),
+			}
+		: null;
+
+	const ordered_bindings = [...outer_bindings, ...loop_bindings];
+	const ordered_aliases = [...outer_aliases, ...loop_aliases];
+	const ordered_use_typeof = [...outer_bindings.map(() => true), ...loop_bindings.map(() => false)];
+
+	const signature_bindings = has_tail ? [...ordered_bindings, tail_synthetic_id] : ordered_bindings;
+	const signature_aliases = has_tail
+		? [...ordered_aliases, /** @type {any} */ (tail_isLast_alias)]
+		: ordered_aliases;
+	const signature_use_typeof = has_tail ? [...ordered_use_typeof, false] : ordered_use_typeof;
+
+	const props_type =
+		signature_bindings.length > 0
+			? create_helper_props_type_literal_with_typeof_flags(
+					signature_bindings,
+					signature_aliases,
+					signature_use_typeof,
+				)
+			: null;
+	const params =
+		props_type !== null ? [create_typed_helper_props_pattern(signature_bindings, props_type)] : [];
+
+	const fn_saved_bindings = transform_context.available_bindings;
+	transform_context.available_bindings = new Map(fn_saved_bindings);
+	if (has_tail) {
+		transform_context.available_bindings.set(tail_synthetic_id.name, tail_synthetic_id);
+	}
+	const fn_body_statements = build_render_statements(loop_body, true, transform_context);
+	transform_context.available_bindings = fn_saved_bindings;
+
+	const helper_fn = /** @type {any} */ (
+		b.function(clone_identifier(helper_id), params, b.block(fn_body_statements))
+	);
+	helper_fn.metadata = { path: [], is_component: true, is_method: false };
+
+	let helper_decl;
+	if (transform_context.helper_state) {
+		const cache_id = create_generated_identifier(
+			`${transform_context.helper_state.base_name}__${helper_id.name}`,
+		);
+		transform_context.helper_state.helpers.push(create_helper_cache_declaration(cache_id));
+		helper_decl = create_cached_helper_declaration(
+			helper_id,
+			cache_id,
+			create_helper_init_expression(helper_id, helper_fn, node, transform_context),
+		);
+	} else {
+		helper_decl = create_helper_declaration(helper_id, helper_fn, node, transform_context);
+	}
+
+	transform_context.available_bindings = saved_bindings;
+
+	const callback_invocation_element = create_helper_component_element(
+		helper_id,
+		ordered_bindings,
+		node,
+		{ mapWrapper: false, mapBindingNames: false, mapBindingValues: false },
+	);
+
+	// When there's a tail, the .map callback always needs an index to compute
+	// `isLast`. If the user didn't write `index i`, synthesize one. The same
+	// identifier is also used as the implicit key fallback below.
+	let index_identifier;
+	if (loop_params.length >= 2) {
+		index_identifier = clone_identifier(loop_params[1]);
+	} else if (has_tail) {
+		index_identifier = create_generated_identifier('i');
+	} else {
+		index_identifier = null;
+	}
+
+	const body_key_expression = find_key_expression_in_body(loop_body);
+	const explicit_key_expression =
+		body_key_expression ?? (node.key ? clone_expression_node(node.key) : undefined);
+	const key_expression =
+		explicit_key_expression ??
+		(loop_params.length >= 2 ? clone_identifier(loop_params[1]) : undefined);
+	if (key_expression) {
+		callback_invocation_element.openingElement.attributes.push(
+			b.jsx_attribute(b.jsx_id('key'), to_jsx_expression_container(key_expression, key_expression)),
+		);
+	}
+
+	if (has_tail && index_identifier) {
+		const length_minus_one = b.binary(
+			'-',
+			b.member(clone_identifier(source_id), 'length'),
+			b.literal(1),
+		);
+		callback_invocation_element.openingElement.attributes.push(
+			b.jsx_attribute(
+				b.jsx_id(tail_synthetic_id.name),
+				to_jsx_expression_container(
+					b.binary('===', clone_identifier(index_identifier), length_minus_one),
+				),
+			),
+		);
+	}
+
+	const callback_params =
+		has_tail && loop_params.length < 2 && index_identifier
+			? [
+					...loop_params.map((/** @type {any} */ p) => clone_identifier(p)),
+					clone_identifier(index_identifier),
+				]
+			: loop_params.map((/** @type {any} */ p) => clone_identifier(p));
+
+	const iter_callback = b.arrow(callback_params, callback_invocation_element);
+
+	const map_call = b.call(b.member(clone_identifier(source_id), 'map'), iter_callback);
+
+	// jsx_child for the iteration. When there's a tail, also render the tail
+	// helper directly when the source is empty (no iterations means the loop
+	// helper never fires, so the tail wouldn't run otherwise).
+	const jsx_child = has_tail
+		? to_jsx_expression_container(
+				b.conditional(
+					b.binary('===', b.member(clone_identifier(source_id), 'length'), b.literal(0)),
+					clone_tail_invocation(/** @type {any} */ (tail_helper)),
+					map_call,
+				),
+				node,
+			)
+		: to_jsx_expression_container(map_call, node);
+
+	const hoist_statements = [source_decl, source_normalize_decl];
+	if (has_tail) {
+		// TailHelper's setup statements (its alias consts and cache decl).
+		hoist_statements.push(.../** @type {any} */ (tail_helper).setup_statements);
+	}
+	for (const alias of ordered_aliases) hoist_statements.push(alias.declaration);
+	if (has_tail && tail_isLast_alias) {
+		hoist_statements.push(tail_isLast_alias.declaration);
+	}
+	hoist_statements.push(helper_decl);
+
+	return {
+		hoist_statements,
+		jsx_child,
+	};
+}
+
+/**
+ * Build a TS `type` alias for a loop-scoped binding, deriving the type
+ * from the iteration source. For the value param we use
+ * `(typeof source)[number]`, which gives the right element type for arrays
+ * and tuples (the common case in JSX templates). For the index param,
+ * the type is always `number`.
+ *
+ * @param {AST.Identifier} helper_id
+ * @param {AST.Identifier} binding
+ * @param {AST.Identifier} source_id
+ * @param {any[]} loop_params
+ * @returns {{ id: AST.Identifier, declaration: any }}
+ */
+function create_loop_scoped_type_alias_declaration(helper_id, binding, source_id, loop_params) {
+	const alias_id = create_generated_identifier(`_tsrx_${helper_id.name}_${binding.name}`);
+	const is_index = loop_params.length > 1 && binding.name === loop_params[1].name;
+	const type_annotation = is_index
+		? b.ts_keyword_type('number')
+		: /** @type {any} */ ({
+				type: 'TSIndexedAccessType',
+				objectType: b.ts_type_query(clone_identifier(source_id)),
+				indexType: b.ts_keyword_type('number'),
+				metadata: { path: [] },
+			});
+
+	return {
+		id: alias_id,
+		declaration: b.ts_type_alias(clone_identifier(alias_id), type_annotation),
+	};
+}
+
+/**
+ * Variant of {@link create_helper_props_type_literal} that lets each
+ * binding's type reference the alias either via `typeof <alias>` (for
+ * outer-scope const aliases) or directly as `<alias>` (for TS `type`
+ * aliases derived from a loop source).
+ *
+ * @param {AST.Identifier[]} bindings
+ * @param {{ id: AST.Identifier }[]} aliases
+ * @param {boolean[]} use_typeof
+ * @returns {any}
+ */
+function create_helper_props_type_literal_with_typeof_flags(bindings, aliases, use_typeof) {
+	return b.ts_type_literal(
+		bindings.map((binding, i) => {
+			const alias_ref = use_typeof[i]
+				? b.ts_type_query(clone_identifier(aliases[i].id))
+				: b.ts_type_reference(clone_identifier(aliases[i].id));
+			return b.ts_property_signature(
+				create_generated_identifier(binding.name),
+				b.ts_type_annotation(alias_ref),
+			);
+		}),
+	);
+}
+
 /**
  * @param {any} node
  * @param {any[]} continuation_body
@@ -1544,47 +2209,21 @@ function to_jsx_element(node, transform_context, raw_children = node.children ||
 		(/** @type {any} */ attribute) => attribute?.metadata?.has_unmappable_value,
 	);
 
-	/** @type {ESTreeJSX.JSXOpeningElement} */
-	const openingElement = /** @type {ESTreeJSX.JSXOpeningElement} */ (
-		has_unmappable_attribute
-			? {
-					type: 'JSXOpeningElement',
-					name,
-					attributes,
-					selfClosing,
-					metadata: { path: [] },
-				}
-			: set_loc(
-					/** @type {any} */ ({
-						type: 'JSXOpeningElement',
-						name,
-						attributes,
-						selfClosing,
-					}),
-					node.openingElement || node,
-				)
-	);
+	const opening_element_node = b.jsx_opening_element(name, attributes, selfClosing);
+	const openingElement = has_unmappable_attribute
+		? opening_element_node
+		: set_loc(opening_element_node, node.openingElement || node);
 
-	/** @type {ESTreeJSX.JSXClosingElement | null} */
 	const closingElement = selfClosing
 		? null
 		: set_loc(
-				/** @type {any} */ ({
-					type: 'JSXClosingElement',
-					name: clone_jsx_name(name, node.closingElement?.name || node.closingElement || node),
-				}),
+				b.jsx_closing_element(
+					clone_jsx_name(name, node.closingElement?.name || node.closingElement || node),
+				),
 				node.closingElement || node,
 			);
 
-	return set_loc(
-		/** @type {any} */ ({
-			type: 'JSXElement',
-			openingElement,
-			closingElement,
-			children,
-		}),
-		node,
-	);
+	return set_loc(b.jsx_element_fresh(openingElement, closingElement, children), node);
 }
 
 /**
@@ -1789,12 +2428,22 @@ function get_referenced_helper_bindings(body_nodes, available_bindings) {
  * @param {any} key_expression
  * @param {any} source_node
  * @param {TransformContext} transform_context
+ * @param {AST.Identifier} [preallocated_helper_id] - Optional pre-allocated id.
+ *   Used by the switch lift's chained-call build, which allocates ids in
+ *   source order in a forward pass and then constructs helpers in reverse so
+ *   each fall-through case can reference the next case's component element.
  * @returns {{ setup_statements: any[], component_element: ESTreeJSX.JSXElement }}
  */
-function create_hook_safe_helper(body_nodes, key_expression, source_node, transform_context) {
-	const helper_id = create_generated_identifier(
-		create_local_statement_component_name(transform_context),
-	);
+function create_hook_safe_helper(
+	body_nodes,
+	key_expression,
+	source_node,
+	transform_context,
+	preallocated_helper_id,
+) {
+	const helper_id =
+		preallocated_helper_id ??
+		create_generated_identifier(create_local_statement_component_name(transform_context));
 	const helper_bindings = get_referenced_helper_bindings(
 		body_nodes,
 		transform_context.available_bindings,
@@ -2695,27 +3344,10 @@ function try_statement_to_jsx_child(node, transform_context) {
  * @returns {any}
  */
 function create_jsx_element(tag_name, attributes, children) {
-	const name = { type: 'JSXIdentifier', name: tag_name, metadata: { path: [] } };
-	return {
-		type: 'JSXElement',
-		openingElement: {
-			type: 'JSXOpeningElement',
-			name,
-			attributes,
-			selfClosing: children.length === 0,
-			metadata: { path: [] },
-		},
-		closingElement:
-			children.length > 0
-				? {
-						type: 'JSXClosingElement',
-						name: { type: 'JSXIdentifier', name: tag_name, metadata: { path: [] } },
-						metadata: { path: [] },
-					}
-				: null,
-		children,
-		metadata: { path: [] },
-	};
+	const self_closing = children.length === 0;
+	const opening_element = b.jsx_opening_element(b.jsx_id(tag_name), attributes, self_closing);
+	const closing_element = self_closing ? null : b.jsx_closing_element(b.jsx_id(tag_name));
+	return b.jsx_element_fresh(opening_element, closing_element, children);
 }
 
 /**
@@ -3049,8 +3681,8 @@ export function validate_at_most_one_ref_attribute(raw_attrs, transform_context)
 	}
 	for (let i = 0; i < refs.length; i++) {
 		const node = refs[i];
-		if (!transform_context?.loose && i === 0) {
-			// in the non-loose mode, only throw on the second duplicate
+		if (!transform_context?.collect && i === 0) {
+			// when not collecting, only throw on the second duplicate
 			continue;
 		}
 		error(
@@ -3359,25 +3991,11 @@ function create_dynamic_jsx_element(dynamic_id, node, transform_context) {
 	const children = create_element_children(node.children || [], transform_context);
 	const name = identifier_to_jsx_name(clone_identifier(dynamic_id));
 
-	return /** @type {any} */ ({
-		type: 'JSXElement',
-		openingElement: {
-			type: 'JSXOpeningElement',
-			name,
-			attributes,
-			selfClosing,
-			metadata: { path: [] },
-		},
-		closingElement: selfClosing
-			? null
-			: {
-					type: 'JSXClosingElement',
-					name: clone_jsx_name(name),
-					metadata: { path: [] },
-				},
+	return b.jsx_element_fresh(
+		b.jsx_opening_element(name, attributes, selfClosing),
+		selfClosing ? null : b.jsx_closing_element(clone_jsx_name(name)),
 		children,
-		metadata: { path: [] },
-	});
+	);
 }
 
 /**