@tsrx/core 0.1.32 → 0.1.33

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "type": "module",
   "repository": {
     "type": "git",

package/src/constants.js

@@ -2,6 +2,10 @@ export const TEMPLATE_FRAGMENT = 1;
 export const TEMPLATE_USE_IMPORT_NODE = 1 << 1;
 export const IS_CONTROLLED = 1 << 2;
 export const IS_INDEXED = 1 << 3;
+// A control-flow block that is its component's sole root: renders before the
+// parent `__anchor` (sibling semantics, no `<!>` wrapper). Must match the value
+// in ripple's runtime constants.
+export const ROOT_CONTROLLED = 1 << 4;
 export const TEMPLATE_SVG_NAMESPACE = 1 << 5;
 export const TEMPLATE_MATHML_NAMESPACE = 1 << 6;
 

package/src/index.js

@@ -31,6 +31,7 @@ export {
 	TEMPLATE_USE_IMPORT_NODE,
 	IS_CONTROLLED,
 	IS_INDEXED,
+	ROOT_CONTROLLED,
 	TEMPLATE_SVG_NAMESPACE,
 	TEMPLATE_MATHML_NAMESPACE,
 	HYDRATION_START,
@@ -147,6 +148,7 @@ export {
 	create_hook_safe_helper as createHookSafeHelper,
 	create_element_ref_target_type as createElementRefTargetType,
 	create_element_ref_target_type_for_name as createElementRefTargetTypeForName,
+	build_return_expression as buildReturnExpression,
 	createJsxTransform,
 	extract_jsx_setup_declarations as extractJsxSetupDeclarations,
 	is_component_like_element,
@@ -163,7 +165,7 @@ export {
 } from './transform/jsx/index.js';
 export {
 	in_jsx_child_context as inJsxChildContext,
-	tsx_node_to_jsx_expression as tsxNodeToJsxExpression,
+	is_empty_jsx_fragment as isEmptyJsxFragment,
 	tsx_with_ts_locations as tsxWithTsLocations,
 	is_template_if_node as isTemplateIfNode,
 	is_template_for_of_node as isTemplateForOfNode,

package/src/plugin.js

@@ -232,6 +232,7 @@ export function TSRXPlugin(config) {
 		// If we push an undefined context, Acorn's tokenizer will later crash reading `.override`.
 		const b_stat = tc.b_stat || acorn.tokContexts.b_stat;
 		const b_expr = tc.b_expr || acorn.tokContexts.b_expr;
+		const q_tmpl = tc.q_tmpl || acorn.tokContexts.q_tmpl;
 		const tstt = Parser.acornTypeScript.tokTypes;
 		const tstc = Parser.acornTypeScript.tokContexts;
 
@@ -1272,14 +1273,21 @@ export function TSRXPlugin(config) {
 			 */
 			#parseCodeBlockSetupStatement() {
 				const previous_context = this.context;
-				this.context = previous_context.filter(
-					(context) =>
-						context !== tstc.tc_expr && context !== tstc.tc_oTag && context !== tstc.tc_cTag,
-				);
+				const at_template_literal = this.type === tt.backQuote;
 				let pushed_statement_context = false;
-				if (this.curContext() !== b_stat) {
-					this.context.push(b_stat);
-					pushed_statement_context = true;
+				if (at_template_literal) {
+					if (this.curContext() !== q_tmpl) {
+						this.context.push(q_tmpl);
+					}
+				} else {
+					this.context = previous_context.filter(
+						(context) =>
+							context !== tstc.tc_expr && context !== tstc.tc_oTag && context !== tstc.tc_cTag,
+					);
+					if (this.curContext() !== b_stat) {
+						this.context.push(b_stat);
+						pushed_statement_context = true;
+					}
 				}
 				this.exprAllowed = true;
 				const previous_path = this.#path;
@@ -1287,22 +1295,7 @@ export function TSRXPlugin(config) {
 				this.#templateScriptParsingDepth++;
 				let node;
 				try {
-					// A code-block/directive body is statements plus at most one render node —
-					// never bare text or markup tokens. If the tokenizer mis-read trailing
-					// code as JSX (raw text or a tag-name token — both can happen for a
-					// statement following the render node, depending on the leftover context),
-					// reposition to the token start and re-read it as code now that the
-					// template path is hidden. It then parses as a statement so the
-					// one-render-node rule reports a clear "statements cannot follow" error
-					// instead of a generic parse fault.
 					if (this.type === tstt.jsxText || this.type === tstt.jsxName) {
-						// Rewinding `pos` to the mis-read token's start must also rewind the
-						// line counter: a `jsxText` token can span newlines (e.g. the blank
-						// line before a following render node), and reading it already
-						// advanced `curLine`/`lineStart` to its end. Resetting only `pos`
-						// would leave the line counter ahead of `pos`, inflating the `loc`
-						// of this statement and every node after it (which crashes source-map
-						// mapping when the inflated end line runs past the file).
 						const loc = acorn.getLineInfo(this.input, this.start);
 						this.pos = this.start;
 						this.curLine = loc.line;
@@ -1316,7 +1309,9 @@ export function TSRXPlugin(config) {
 					if (pushed_statement_context && this.curContext() === b_stat) {
 						this.context.pop();
 					}
-					this.context = previous_context;
+					if (!at_template_literal) {
+						this.context = previous_context;
+					}
 				}
 				if (this.curContext() === tstc.tc_expr) {
 					this.context.pop();
@@ -4383,22 +4378,29 @@ export function TSRXPlugin(config) {
 			parseTemplateBody(body) {
 				const current_template_node = this.#currentNativeTemplateNode();
 				if (!current_template_node) return;
-				// Outside a `@{ … }` block every element/fragment body is plain JSX (§2,
-				// §5). There is no script section and no `---` fence to infer — text is
-				// text, and setup code lives only inside a code block.
 				current_template_node.metadata ??= { path: [] };
 				current_template_node.metadata.templateMode = 'template';
 
-				// `@{ … }` code block as element/fragment content (§2 rule 1). Sibling
-				// code blocks are allowed, so this is not gated on an empty body;
-				// reposition onto the `@` if leading whitespace was tokenized ahead of it.
 				if (this.#atCodeBlockStart()) {
 					const at_index = skip_whitespace_from(this.input, this.start);
 					if (this.start !== at_index) {
+						const ws_start = this.start;
+						const ws_start_loc = this.startLoc;
+						const ws_value = this.input.slice(ws_start, at_index);
+						const text_node = /** @type {ESTreeJSX.JSXText} */ (
+							this.startNodeAt(ws_start, ws_start_loc)
+						);
+						text_node.value = ws_value;
+						text_node.raw = ws_value;
 						const loc = acorn.getLineInfo(this.input, at_index);
+						const at_position = new acorn.Position(loc.line, loc.column);
+						this.finishNodeAt(text_node, 'JSXText', at_index, at_position);
+						if (this.#shouldKeepTemplateTextNode(text_node)) {
+							body.push(text_node);
+						}
 						this.pos = at_index;
 						this.start = at_index;
-						this.startLoc = new acorn.Position(loc.line, loc.column);
+						this.startLoc = at_position;
 						this.curLine = loc.line;
 						this.lineStart = at_index - loc.column;
 					}
@@ -4416,8 +4418,23 @@ export function TSRXPlugin(config) {
 					// text never starts at `<`, so drop the leaked context and re-read the
 					// tag instead of emitting an empty node.
 					if (this.input.charCodeAt(this.start) === CharCode.lessThan) {
-						while (this.curContext() === tstc.tc_expr) {
-							this.context.pop();
+						if (this.input.charCodeAt(this.start + 1) === CharCode.slash) {
+							while (this.curContext() === tstc.tc_expr) {
+								this.context.pop();
+							}
+						} else {
+							let native_depth = 0;
+							for (const node of this.#path) {
+								if (this.#isNativeTemplateNode(node)) native_depth++;
+							}
+							let tc_expr_depth = 0;
+							for (const context of this.context) {
+								if (context === tstc.tc_expr) tc_expr_depth++;
+							}
+							while (tc_expr_depth > native_depth && this.curContext() === tstc.tc_expr) {
+								this.context.pop();
+								tc_expr_depth--;
+							}
 						}
 						this.pos = this.start;
 						this.exprAllowed = true;

package/src/transform/jsx/helpers.js

@@ -19,6 +19,20 @@ export function in_jsx_child_context(path) {
 	return !!parent && (parent.type === 'JSXElement' || parent.type === 'JSXFragment');
 }
 
+/**
+ * @param {any} node
+ * @returns {boolean}
+ */
+export function is_empty_jsx_fragment(node) {
+	return (
+		node?.type === 'JSXFragment' &&
+		!(node.children || []).some(
+			(/** @type {any} */ child) =>
+				child && (child.type !== 'JSXText' || child.value.trim() !== ''),
+		)
+	);
+}
+
 /**
  * Match Ripple's transform path metadata shape: every node seen by the walker
  * carries its current ancestor path for downstream CSS pruning and mapping
@@ -36,45 +50,6 @@ export function set_node_path_metadata(node, path) {
 	}
 }
 
-/**
- * Flatten a JSX-compatible island's children into a single expression. In a
- * JSX-child position, a JSXExpressionContainer `{expr}` is valid and must stay
- * wrapped. In an expression position (e.g. `return ...`), `{expr}` parses as
- * a block/object literal, so unwrap to `expr`.
- *
- * @param {any} node
- * @param {boolean} [in_jsx_child]
- * @returns {any}
- */
-export function tsx_node_to_jsx_expression(node, in_jsx_child = false) {
-	const children = (node.children || []).filter(
-		(/** @type {any} */ child) => child.type !== 'JSXText' || child.value.trim() !== '',
-	);
-
-	if (
-		children.length === 1 &&
-		children[0].type !== 'JSXText' &&
-		// Reactive-block containers (dynamic tags) must stay expression
-		// children so the host JSX compiler wraps them in a render block;
-		// unwrapping to a bare call would evaluate them once.
-		children[0].metadata?.tsrx_reactive_block !== true
-	) {
-		const only = children[0];
-		if (only.type === 'JSXExpressionContainer' && !in_jsx_child) {
-			return only.expression;
-		}
-		return only;
-	}
-
-	return /** @type {any} */ ({
-		type: 'JSXFragment',
-		openingFragment: { type: 'JSXOpeningFragment', metadata: { path: [] } },
-		closingFragment: { type: 'JSXClosingFragment', metadata: { path: [] } },
-		children,
-		metadata: { 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

package/src/transform/jsx/index.js

@@ -5,10 +5,12 @@
 import { walk } from 'zimmerframe';
 import { print } from 'esrap';
 import { error } from '../../errors.js';
+import { is_template_value_position } from '../../analyze/validation.js';
 import { analyze_css } from '../../analyze/css-analyze.js';
 import { prune_css } from '../../analyze/prune.js';
 import {
 	in_jsx_child_context,
+	is_empty_jsx_fragment,
 	set_node_path_metadata,
 	tsx_with_ts_locations,
 	is_template_if_node,
@@ -258,29 +260,170 @@ function is_jsx_control_flow_expression(node) {
 
 /**
  * Wrap a render-output node in a native TSRX fragment so it flows through the
- * same single-child render path as a `<> … </>` output.
+ * same single-child render path as a `<> … </>` output. This is a compiler
+ * GENERATED wrapper (it wraps a control-flow directive / render output so it
+ * lowers to a value) — it is marked `tsrx_generated_wrapper` so the single-child
+ * collapse keeps unwrapping it, unlike an AUTHORED `<> … </>` which is kept.
  * @param {any} node
  * @returns {any}
  */
 function wrap_in_native_tsrx_fragment(node) {
 	const fragment = b.jsx_fragment([node]);
-	fragment.metadata = { ...(fragment.metadata || {}), native_tsrx: true };
+	fragment.metadata = {
+		...(fragment.metadata || {}),
+		native_tsrx: true,
+		tsrx_generated_wrapper: true,
+	};
 	return fragment;
 }
 
 /**
- * Wrap a bare JSX control-flow directive that sits directly in an expression
- * position — an expression-bodied arrow (`() => @switch (…) { … }`), a
- * `return @switch (…) { … }`, an unused expression statement,
- * assignment to a variable
- * (`const x = @switch (…) { … }`, `x = @switch (…) { … }`), or a call/`new`
- * argument (`render(@if (…) { … })`) — in a native TSRX fragment.
+ * An AUTHORED `<> … </>` fragment (not a compiler-generated wrapper, nor a Ripple
+ * code-block-chain wrapper). These are kept verbatim in the output instead of
+ * being unwrapped to their single child.
+ * @param {any} node
+ * @returns {boolean}
+ */
+function is_authored_native_fragment(node) {
+	return (
+		node?.type === 'JSXFragment' &&
+		node.metadata?.native_tsrx === true &&
+		node.metadata?.tsrx_generated_wrapper !== true
+	);
+}
+
+/**
+ * Slots whose value is a render child / statement, not a JavaScript value
+ * expression. A control-flow directive (`@if`/`@for`/`@switch`/`@try`) is
+ * legitimate render output in these positions, so it must NOT be treated as a
+ * stray "control flow used as a value". Everything else is a value position:
+ * an unhandled control-flow directive there is the raw-value error case
+ * (a `@for` iterable, an `@if`/`@switch` test, etc.).
+ * @param {any} parent
+ * @param {string} key
+ * @returns {boolean}
+ */
+function is_statement_or_template_slot(parent, key) {
+	// JSX children, and the body of any block/program/function/loop.
+	if (key === 'children' || key === 'body') return true;
+	// A `@{ … }` code block's trailing output (`render`) is render position.
+	if (parent?.type === 'JSXCodeBlock' && key === 'render') return true;
+	// `{ @if … }` containers lower their expression through the render machinery.
+	if (parent?.type === 'JSXExpressionContainer' && key === 'expression') return true;
+	// Switch-case statement lists.
+	if (parent?.type === 'SwitchCase' && key === 'consequent') return true;
+	// An if-node branch is a statement block; its `alternate` is also where the
+	// `@else if` chain (another control-flow node) legitimately lives.
+	if (is_if_control_node(parent) && (key === 'consequent' || key === 'alternate')) return true;
+	return false;
+}
+
+/**
+ * Render-output value slots: the only expression positions a directive may be
+ * the SOLE value of. A control-flow directive here collapses to its rendered
+ * value (wrapped in a native fragment by `wrap_control_flow_expression_values`)
+ * and a `@{ … }` code block self-lowers to an IIFE. These are established forms
+ * (`const x = @switch …`, `() => @if …`, `return @if …`, `render(@for …)`),
+ * distinct from combining a directive INTO an expression (an operator operand, a
+ * `@for` iterable, an `@if`/`@switch` test), which is an error.
+ * @param {any} parent
+ * @param {string} key
+ * @returns {boolean}
+ */
+function is_render_output_value_slot(parent, key) {
+	switch (parent?.type) {
+		case 'ArrowFunctionExpression':
+			return key === 'body';
+		case 'ReturnStatement':
+			return key === 'argument';
+		case 'ExpressionStatement':
+			return key === 'expression';
+		case 'VariableDeclarator':
+			return key === 'init';
+		case 'AssignmentExpression':
+			return key === 'right';
+		case 'CallExpression':
+		case 'NewExpression':
+			return key === 'arguments';
+		default:
+			return false;
+	}
+}
+
+/**
+ * A `<> … </>` is combined INTO a surrounding expression (an operator operand, a
+ * conditional branch, an array element, a template-literal hole) — as opposed to
+ * being the sole value of a render-output slot, where its single-child collapse
+ * is invisible because the value is only rendered. In a combined position the
+ * collapse is NOT invisible: a fragment is always a truthy element, but its
+ * collapsed content may be falsy, so `<>{0}</> || 'x'` (renders `0`) must not turn
+ * into `0 || 'x'` (renders `'x'`). Keep the fragment in these positions.
+ * @param {any} parent
+ * @param {any} child
+ * @returns {boolean}
+ */
+function is_combined_expression_position(parent, child) {
+	if (!parent || !is_template_value_position(parent, child)) return false;
+	switch (parent.type) {
+		// Sole-value render-output slots: the collapse is invisible, keep it.
+		case 'VariableDeclarator':
+			return parent.init !== child;
+		case 'AssignmentExpression':
+			return parent.right !== child;
+		case 'CallExpression':
+		case 'NewExpression':
+			return !(Array.isArray(parent.arguments) && parent.arguments.includes(child));
+		default:
+			return true;
+	}
+}
+
+/**
+ * Re-wrap an already-lowered render value in a `<> … </>` fragment so a fragment
+ * combined into an expression keeps its fragment identity (see
+ * `is_combined_expression_position`). A value that is already a fragment is left
+ * as-is; a JSX element/text nests directly (`<><span /></>`); any other
+ * expression goes in a `{ … }` container (`<>{0}</>`).
+ * @param {any} expression
+ * @param {any} source
+ * @returns {any}
+ */
+function wrap_lowered_value_in_fragment(expression, source) {
+	if (expression?.type === 'JSXFragment') return expression;
+	const child =
+		expression?.type === 'JSXElement' ||
+		expression?.type === 'JSXText' ||
+		expression?.type === 'JSXExpressionContainer'
+			? expression
+			: to_jsx_expression_container(expression, source);
+	return set_loc(b.jsx_fragment([child]), source?.loc ? source : undefined);
+}
+
+/**
+ * Lower bare JSX control-flow directives that sit as the SOLE value of a
+ * render-output slot — an expression-bodied arrow (`() => @switch (…) { … }`), a
+ * `return @switch (…) { … }`, an unused expression statement, a variable
+ * initializer (`const x = @switch (…) { … }`), an assignment
+ * (`x = @switch (…) { … }`), or a call/`new` argument (`render(@if (…) { … })`)
+ * — by wrapping them in a native TSRX fragment so they flow through the same
+ * render machinery as a `<> … </>` output instead of leaking to the printer as a
+ * raw `JSX…Expression`.
+ *
+ * A control-flow directive or `@{ … }` code block used anywhere ELSE in a value
+ * position — COMBINED into an expression (`(@if …) || fallback`, an operator
+ * operand, an array element, a template-literal hole, a `@for` iterable, an
+ * `@if`/`@switch` test) — is likewise wrapped in a native TSRX fragment. In an
+ * operand position the fragment is then KEPT (a fragment is a truthy value, so
+ * `<>{…}</> || x` is preserved); in a "raw value" slot the fragment collapses to
+ * its rendered value. Either way nothing leaks to the printer as a raw
+ * `JSX…Expression`.
+ *
  * @param {any} node
- * @param {TransformContext | null} lower_dynamic_context
+ * @param {TransformContext} transform_context
  * @param {Set<any>} [seen]
  * @returns {void}
  */
-function wrap_control_flow_expression_values(node, lower_dynamic_context, seen = new Set()) {
+function wrap_control_flow_expression_values(node, transform_context, seen = new Set()) {
 	if (!node || typeof node !== 'object' || seen.has(node)) return;
 	seen.add(node);
 
@@ -292,19 +435,40 @@ function wrap_control_flow_expression_values(node, lower_dynamic_context, seen =
 	// `<{'div'}>`) is hoisted to a module-level static const while still
 	// carrying the raw dynamic tag. Alias lowerings return a replacement
 	// fragment, which is swapped into the child's position here.
+	const lower_dynamic = !!transform_context?.platform?.imports?.dynamicFactory;
 	const lower_child = (/** @type {any} */ child) => {
-		if (!lower_dynamic_context || child?.type !== 'JSXElement') return child;
-		return lower_dynamic_jsx_element(child, lower_dynamic_context) ?? child;
+		if (!lower_dynamic || child?.type !== 'JSXElement') return child;
+		return lower_dynamic_jsx_element(child, transform_context) ?? child;
 	};
 
+	// A control-flow directive or `@{ … }` code block combined into an expression
+	// (an operator operand, a `@for` iterable, an `@if`/`@switch` test, …) is
+	// wrapped in a native TSRX fragment so it flows through the render machinery
+	// instead of leaking to the printer as a raw `JSX…Expression`. In an operand
+	// position the fragment is then KEPT (a fragment is a truthy value); in a
+	// "raw value" slot like a `@for` iterable it collapses to its rendered value
+	// (see the JSXFragment visitor and `is_combined_expression_position`).
+	const wrap_directive_in_expression = (/** @type {any} */ value) =>
+		is_jsx_control_flow_expression(value) || value?.type === 'JSXCodeBlock'
+			? wrap_in_native_tsrx_fragment(value)
+			: 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], lower_dynamic_context, seen);
+			wrap_control_flow_expression_values(node[i], transform_context, seen);
 		}
 		return;
 	}
 
+	// Wrap a bare control-flow directive that is the sole value of a render-output
+	// slot in a native TSRX fragment, collapsing to its rendered value. (A `@{ … }`
+	// code block in the same slots already self-lowers to an IIFE, so it is left
+	// as-is.) These render-output slots are the only value positions a directive is
+	// allowed in; see `is_render_output_value_slot`.
+	const wrap_value = (/** @type {any} */ value) =>
+		is_jsx_control_flow_expression(value) ? wrap_in_native_tsrx_fragment(value) : value;
+
 	if (
 		node.type === 'ArrowFunctionExpression' &&
 		node.body?.type !== 'BlockStatement' &&
@@ -326,15 +490,28 @@ function wrap_control_flow_expression_values(node, lower_dynamic_context, seen =
 		(node.type === 'CallExpression' || node.type === 'NewExpression') &&
 		Array.isArray(node.arguments)
 	) {
-		node.arguments = node.arguments.map((/** @type {any} */ arg) =>
-			is_jsx_control_flow_expression(arg) ? wrap_in_native_tsrx_fragment(arg) : arg,
-		);
+		node.arguments = node.arguments.map(wrap_value);
 	}
 
 	for (const key of Object.keys(node)) {
 		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') continue;
-		node[key] = lower_child(node[key]);
-		wrap_control_flow_expression_values(node[key], lower_dynamic_context, seen);
+		// 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];
+		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);
+			}
+		} 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);
+		}
 	}
 }
 
@@ -402,10 +579,7 @@ export function createJsxTransform(platform) {
 		};
 
 		expand_child_code_blocks(/** @type {any} */ (ast));
-		wrap_control_flow_expression_values(
-			/** @type {any} */ (ast),
-			platform.imports.dynamicFactory ? transform_context : null,
-		);
+		wrap_control_flow_expression_values(/** @type {any} */ (ast), transform_context);
 
 		if (!transform_context.typeOnly) {
 			preallocate_lazy_ids(/** @type {any} */ (ast), transform_context);
@@ -429,8 +603,37 @@ export function createJsxTransform(platform) {
 
 				const style_context = prepare_tsrx_fragment_styles(node, state);
 				const target = style_context?.fragment ?? next() ?? node;
-				const in_jsx_child = in_jsx_child_context(path);
-				const expression = tsrx_node_to_jsx_expression(target, state, in_jsx_child);
+				// An EMPTY fragment that is the sole expression of a `{ … }` container in a
+				// JSX child slot (`<b>{<></>}</b>`) must stay `<></>`: the container already
+				// supplies the `{}` wrapper, so lowering it to a bare `null` (the default
+				// expression-position behavior) drops the source fragment. This matches how
+				// the same fragment is preserved in an attribute value (`a={<></>}`).
+				// Non-empty fragments keep their existing lowering.
+				const immediate_parent = /** @type {any} */ (path[path.length - 1]);
+				const is_empty_container_child =
+					immediate_parent?.type === 'JSXExpressionContainer' &&
+					in_jsx_child_context(path.slice(0, -1)) &&
+					!(target.children || []).some(
+						(/** @type {any} */ child) =>
+							child &&
+							child.type !== 'EmptyStatement' &&
+							(child.type !== 'JSXText' || child.value !== ''),
+					);
+				const in_jsx_child = in_jsx_child_context(path) || is_empty_container_child;
+				let expression = tsrx_node_to_jsx_expression(target, state, in_jsx_child);
+				// Keep a fragment's `<> … </>` identity in expression position when it is
+				// either AUTHORED (the author wrote `<>{1}</>`, so it must not unwrap to a
+				// bare `1`) or combined into a surrounding expression (collapsing `<>{0}</>`
+				// to `0` would flip `<>{0}</> || 'x'` from rendering `0` to `'x'` — a
+				// fragment is always truthy). A compiler-generated wrapper (around a
+				// control-flow directive) is NOT authored, so it still collapses.
+				if (
+					!in_jsx_child &&
+					(is_authored_native_fragment(node) ||
+						is_combined_expression_position(path[path.length - 1], node))
+				) {
+					expression = wrap_lowered_value_in_fragment(expression, node);
+				}
 				for (const statement of create_tsrx_style_ref_setup_statements(
 					target,
 					style_context,
@@ -544,6 +747,12 @@ export function createJsxTransform(platform) {
 			inject_try_imports(expanded, transform_context, platform, suspense_source);
 		}
 
+		// Lower any `@{ … }` code blocks left in generated helper bodies before the
+		// 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);
+
 		// Apply lazy destructuring transforms to module-level code (top-level function
 		// declarations, arrow functions, etc.).
 		// In type-only mode, the lazy patterns survive untouched: esrap ignores the
@@ -551,12 +760,25 @@ export function createJsxTransform(platform) {
 		// = expr` prints as `let [a] = expr`, and the bare statement-level form
 		// `&[x] = expr;` (used when `x` is already declared) prints as `[x] =
 		// expr;` — a valid destructuring assignment to the existing binding.
+		//
+		// Re-run `preallocate_lazy_ids` first. The initial pre-walk pass stamps
+		// `metadata.has_lazy_descendants` (the fast-path gate that tells
+		// `apply_lazy_transforms` a function body is worth walking) on the function
+		// boundaries that existed in the source. Lowering `@{ … }` blocks and
+		// `@if`/`@for`/`@switch`/`@try` directives introduces NEW function
+		// boundaries — scoped IIFEs and `.map(...)` callbacks — that wrap those same
+		// lazy patterns but were never stamped. Re-running over the lowered tree
+		// stamps them too (it is idempotent: already-allocated `lazy_id`s are kept),
+		// 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);
+		}
 		const final_program = /** @type {any} */ (
 			transform_context.typeOnly
 				? expanded
 				: apply_lazy_transforms(/** @type {any} */ (expanded), new Map())
 		);
-		lower_remaining_jsx_code_blocks(final_program, transform_context);
 
 		const result = print(/** @type {any} */ (final_program), tsx_with_ts_locations(), {
 			sourceMapSource: filename,
@@ -932,13 +1154,33 @@ function lower_code_block_stream_node(block, transform_context) {
  * @param {any[]} body_nodes
  * @param {boolean} return_null_when_empty
  * @param {TransformContext} transform_context
+ * @param {any} [source_authored_fragment] When the render output is an AUTHORED
+ *   `<> … </>` (`is_authored_native_fragment`), the built return value is re-wrapped
+ *   in a fragment so the author's fragment is kept verbatim (not collapsed to its
+ *   single child), matching value positions. A generated wrapper passes nothing.
  * @returns {any[]}
  */
-function build_render_statements(body_nodes, return_null_when_empty, transform_context) {
+function build_render_statements(
+	body_nodes,
+	return_null_when_empty,
+	transform_context,
+	source_authored_fragment = null,
+) {
 	body_nodes = body_nodes.flatMap((node) =>
 		node?.type === 'JSXCodeBlock' ? lower_code_block_stream_node(node, transform_context) : [node],
 	);
 
+	// When a caller (e.g. a directive branch / loop / switch-case body) passes the
+	// authored `<> … </>` as the trailing body node rather than a pre-unwrapped child
+	// list, detect it here so its wrapper is kept too. A generated wrapper carries
+	// `tsrx_generated_wrapper`, so it is excluded and still collapses.
+	if (!source_authored_fragment) {
+		const last_body_node = body_nodes[body_nodes.length - 1];
+		if (is_authored_native_fragment(last_body_node)) {
+			source_authored_fragment = last_body_node;
+		}
+	}
+
 	const statements = [];
 	const render_nodes = [];
 	let has_terminal_return = false;
@@ -1072,7 +1314,22 @@ function build_render_statements(body_nodes, return_null_when_empty, transform_c
 		hoist_static_render_nodes(render_nodes, transform_context);
 	}
 
-	const return_arg = build_return_expression(render_nodes);
+	let return_arg = build_return_expression(render_nodes);
+	// Keep an authored `<> … </>` render output verbatim instead of collapsing it:
+	// an empty `<></>` stays `<></>` (not `null`), and a single child stays wrapped
+	// (not its bare value). The `!== 'JSXFragment'` guard avoids double-wrapping a
+	// multi-child / nested result already returned as a fragment — matching the value
+	// seam. A generated wrapper is not authored, so it still collapses.
+	if (is_authored_native_fragment(source_authored_fragment)) {
+		if (return_arg === null) {
+			return_arg = set_loc(
+				b.jsx_fragment([]),
+				source_authored_fragment.loc ? source_authored_fragment : undefined,
+			);
+		} else if (return_arg.type !== 'JSXFragment') {
+			return_arg = wrap_lowered_value_in_fragment(return_arg, source_authored_fragment);
+		}
+	}
 	if (return_arg || (return_null_when_empty && !has_terminal_return)) {
 		statements.push(b.return(return_arg || b.literal(null)));
 	}
@@ -1393,10 +1650,15 @@ function transform_return_statement(node, { next, visit, state, path }) {
 function transform_jsx_code_block(node, { state, path, visit }) {
 	const body_nodes = get_jsx_code_block_body_nodes(node, state);
 	const parent = /** @type {any} */ (path.at(-1));
+	// Keep an authored `<> … </>` trailing render output verbatim (a generated
+	// control-flow wrapper carries `tsrx_generated_wrapper`, so it stays null).
+	const render_authored_fragment = is_authored_native_fragment(node.render) ? node.render : null;
 
 	if (parent && parent.body === node && is_function_or_class_boundary(parent)) {
 		const block = b.block(
-			mark_native_pretransformed_jsx(build_render_statements(body_nodes, true, state)),
+			mark_native_pretransformed_jsx(
+				build_render_statements(body_nodes, true, state, render_authored_fragment),
+			),
 			node,
 		);
 		block.metadata = {
@@ -1410,7 +1672,9 @@ function transform_jsx_code_block(node, { state, path, visit }) {
 		b.arrow(
 			[],
 			b.block(
-				mark_native_pretransformed_jsx(build_render_statements(body_nodes, true, state)),
+				mark_native_pretransformed_jsx(
+					build_render_statements(body_nodes, true, state, render_authored_fragment),
+				),
 				node,
 			),
 		),
@@ -1483,7 +1747,11 @@ function lower_jsx_code_block_function_body(node) {
 			// component render output. Wrap it in a native fragment so it flows
 			// through the same children-rendering path as a `<> … </>` render.
 			const fragment = b.jsx_fragment([render]);
-			fragment.metadata = { ...fragment.metadata, native_tsrx: true };
+			fragment.metadata = {
+				...fragment.metadata,
+				native_tsrx: true,
+				tsrx_generated_wrapper: true,
+			};
 			render = fragment;
 		}
 		statements.push(b.return(render, code_block.render));
@@ -2264,7 +2532,7 @@ function create_native_tsrx_render_statements(fragment, transform_context) {
 			target.type === 'JSXFragment' ? get_tsrx_render_children(target) : [target];
 		return [
 			...create_tsrx_style_ref_setup_statements(target, style_context, transform_context),
-			...build_render_statements(render_nodes, true, transform_context),
+			...build_render_statements(render_nodes, true, transform_context, fragment),
 		];
 	});
 }
@@ -2793,7 +3061,12 @@ function lower_remaining_jsx_code_blocks(node, transform_context, seen = new Set
 					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),
+						build_render_statements(
+							body_nodes,
+							true,
+							transform_context,
+							is_authored_native_fragment(child.render) ? child.render : null,
+						),
 					);
 				});
 			}
@@ -4111,9 +4384,22 @@ function tsrx_node_to_jsx_expression(node, transform_context, in_jsx_child = fal
 	/** @type {any} */
 	let expression;
 	if (children.length === 0) {
-		expression = in_jsx_child
-			? set_loc(b.jsx_fragment([]), node.loc ? node : undefined)
-			: create_null_literal();
+		// An empty fragment is a real value: keep it as `<></>` in BOTH child and
+		// expression position. Lowering it to a bare `null` in expression position
+		// (e.g. `let b = <></>`) drops the author's fragment and changes its type;
+		// `<></>` is a valid value and keeps the to_ts/runtime view faithful.
+		expression = set_loc(b.jsx_fragment([]), node.loc ? node : undefined);
+	} else if (
+		children.length === 1 &&
+		(is_empty_jsx_fragment(children[0]) ||
+			(children[0]?.type === 'JSXFragment' && is_authored_native_fragment(node)))
+	) {
+		// `<><X></></>` — a fragment whose only child is a fragment. The generic
+		// single-child collapse below would unwrap it to the bare inner fragment,
+		// dropping the outer fragment the author wrote. Keep both levels. (`<><></></>`
+		// is kept regardless; a non-empty inner is only kept for an authored outer, so
+		// a generated wrapper still collapses.)
+		expression = set_loc(b.jsx_fragment(children), node.loc ? node : undefined);
 	} else {
 		expression = return_value_body_to_expression(children, node, transform_context);
 	}
@@ -5913,17 +6199,17 @@ function value_has_unmappable_jsx_loc(value) {
  * @param {boolean} [in_jsx_child]
  * @returns {any}
  */
-function build_return_expression(render_nodes, in_jsx_child = false) {
+export function build_return_expression(render_nodes, in_jsx_child = false) {
 	if (render_nodes.length === 0) return null;
 	if (render_nodes.length === 1) {
 		const only = render_nodes[0];
 		if (only.type === 'JSXExpressionContainer') {
-			// Reactive-block containers (dynamic tags) must stay expression
-			// children so the host JSX compiler wraps them in a render block;
-			// returning the bare call would evaluate them once.
 			if (only.metadata?.tsrx_reactive_block === true) {
 				return set_loc(b.jsx_fragment([only]), only.loc ? only : undefined);
 			}
+			if (only.expression?.type === 'JSXEmptyExpression') {
+				return set_loc(b.jsx_fragment([]), only.loc ? only : undefined);
+			}
 			return only.expression;
 		}
 		if (only.type === 'JSXText') {

package/src/transform/lazy.js

@@ -99,38 +99,6 @@ function get_lazy_pattern_mapping_range(pattern) {
 	};
 }
 
-/**
- * Synthesize an object-shaped annotation for untyped lazy object params so the
- * virtual TSX can expose prop names to TypeScript completions.
- *
- * @param {any} pattern
- * @returns {any | null}
- */
-function create_lazy_object_type_annotation(pattern) {
-	if (pattern.type !== 'ObjectPattern') return null;
-
-	const members = [];
-	for (const prop of pattern.properties || []) {
-		if (prop.type === 'RestElement' || prop.computed) continue;
-
-		const key = prop.key;
-		if (key.type !== 'Identifier' && key.type !== 'Literal') continue;
-
-		const member_key =
-			key.type === 'Identifier'
-				? create_generated_identifier(key.name, key)
-				: set_source_location({ ...key, metadata: { path: [] } }, key);
-
-		members.push(
-			b.ts_property_signature(member_key, b.ts_type_annotation(b.ts_keyword_type('any'))),
-		);
-	}
-
-	if (members.length === 0) return null;
-
-	return b.ts_type_annotation(b.ts_type_literal(members));
-}
-
 /**
  * @param {any} node
  * @returns {string | null}
@@ -348,12 +316,14 @@ function visit_topmost_lazy_patterns(pattern, visit) {
 
 /**
  * Build the replacement identifier for a lazy pattern. When `is_top` is true
- * (the pattern is itself a function parameter) we attach the original
- * `typeAnnotation`, synthesize an object-shaped annotation for untyped object
- * params so TypeScript sees prop names, and register source-mapping info.
- * Nested replacements (inside a non-lazy outer destructure) can't carry an
- * inline type annotation — that's not valid syntax — so they get a plain
- * identifier with just source-range info.
+ * (the pattern is itself a function parameter) we carry over the author's
+ * `typeAnnotation` if one was written and register source-mapping info. An
+ * untyped lazy object param gets NO synthesized annotation: since the source
+ * specified no type, the generated param is left implicitly `any` rather than
+ * being given a fabricated `{ … : any }` object type. Nested replacements
+ * (inside a non-lazy outer destructure) can't carry an inline type annotation —
+ * that's not valid syntax — so they get a plain identifier with just source-range
+ * info.
  *
  * @param {any} pattern
  * @param {boolean} is_top
@@ -372,9 +342,6 @@ function build_lazy_id_for_pattern(pattern, is_top) {
 	if (!is_top) return lazy_id;
 	if (pattern.typeAnnotation) {
 		lazy_id.typeAnnotation = pattern.typeAnnotation;
-	} else {
-		const type_annotation = create_lazy_object_type_annotation(pattern);
-		if (type_annotation) lazy_id.typeAnnotation = type_annotation;
 	}
 	set_lazy_param_binding_mappings(lazy_id, pattern);
 	return lazy_id;
@@ -511,6 +478,53 @@ export function preallocate_lazy_ids(root, context) {
 	visit(root);
 }
 
+/**
+ * Convert an ESTree member-access chain (`__lazy0.Item`, `__lazy0.a.b`) into the
+ * equivalent JSX element-name node (a `JSXIdentifier` or `JSXMemberExpression`),
+ * so a lazy binding used as a component/element name (`<Item>`) can be rewritten
+ * to `<__lazy0.Item>`. Returns null for a computed access (`__lazy0[0]`, from an
+ * array destructure), which has no JSX-name form.
+ *
+ * @param {any} expr
+ * @param {any} [source]
+ * @returns {any | null}
+ */
+function estree_member_to_jsx_name(expr, source) {
+	if (expr.type === 'Identifier') {
+		return set_source_location(b.jsx_id(expr.name), source);
+	}
+	if (expr.type === 'MemberExpression' && !expr.computed && expr.property?.type === 'Identifier') {
+		const object = estree_member_to_jsx_name(expr.object, source);
+		if (!object) return null;
+		return set_source_location(b.jsx_member(object, b.jsx_id(expr.property.name)), source);
+	}
+	return null;
+}
+
+/**
+ * If a JSX element/component name references a lazy binding, return the rewritten
+ * JSX name (`<Item>` → `<__lazy0.Item>`, `<Item.Sub>` → `<__lazy0.Item.Sub>`).
+ * Returns null when the name does not reference a lazy binding (or the access has
+ * no JSX-name form), so the caller leaves the original name untouched.
+ *
+ * @param {any} name
+ * @param {Map<string, LazyBinding>} lazy_bindings
+ * @returns {any | null}
+ */
+function rewrite_lazy_jsx_name(name, lazy_bindings) {
+	if (!name) return null;
+	if (name.type === 'JSXIdentifier') {
+		const binding = lazy_bindings.get(name.name);
+		if (!binding) return null;
+		return estree_member_to_jsx_name(binding.read(name), name);
+	}
+	if (name.type === 'JSXMemberExpression') {
+		const new_object = rewrite_lazy_jsx_name(name.object, lazy_bindings);
+		return new_object ? { ...name, object: new_object } : null;
+	}
+	return null;
+}
+
 /**
  * Recursively rewrite lazy-binding references in `node`.
  *
@@ -669,16 +683,36 @@ export function apply_lazy_transforms(node, lazy_bindings) {
 	}
 
 	if (node.type === 'SwitchStatement') {
+		// All case consequents share one lexical block scope, and `@switch`
+		// case bodies are flattened (the `{ … }` wrapper is dropped), so a
+		// `let &[x] = …` / `let &{ … } = …` declared in a case body is scoped to
+		// the whole switch block. Collect names and lazy bindings across every
+		// consequent — like the BlockStatement handler does for a block body — so
+		// references in any case resolve to the generated id, and an inner
+		// declaration shadowing an outer lazy name is dropped.
+		const all_consequents = node.cases.flatMap(
+			(/** @type {any} */ switch_case) => switch_case.consequent,
+		);
+		const block_shadowed = collect_block_shadowed_names(all_consequents, lazy_bindings);
+		const after_shadow =
+			block_shadowed.size > 0 ? remove_shadowed(lazy_bindings, block_shadowed) : lazy_bindings;
+
+		/** @type {Map<string, LazyBinding>} */
+		const block_lazy = new Map();
+		collect_lazy_bindings_from_statements(all_consequents, block_lazy);
+		const effective_bindings =
+			block_lazy.size > 0 ? new Map([...after_shadow, ...block_lazy]) : after_shadow;
+
 		let changed = false;
-		const new_discriminant = apply_lazy_transforms(node.discriminant, lazy_bindings);
+		// The discriminant is evaluated before any case body runs, so it sees the
+		// bindings visible at the switch (outer, minus inner shadows), not a lazy
+		// binding declared inside a case body.
+		const new_discriminant = apply_lazy_transforms(node.discriminant, after_shadow);
 		if (new_discriminant !== node.discriminant) changed = true;
 		const new_cases = node.cases.map((/** @type {any} */ switch_case) => {
-			const case_bindings = collect_block_shadowed_names(switch_case.consequent, lazy_bindings);
-			const effective_bindings =
-				case_bindings.size > 0 ? remove_shadowed(lazy_bindings, case_bindings) : lazy_bindings;
 			let case_changed = false;
 			const new_test = switch_case.test
-				? apply_lazy_transforms(switch_case.test, lazy_bindings)
+				? apply_lazy_transforms(switch_case.test, effective_bindings)
 				: null;
 			if (new_test !== switch_case.test) case_changed = true;
 			const new_consequent = switch_case.consequent.map((/** @type {any} */ stmt) => {
@@ -823,6 +857,21 @@ export function apply_lazy_transforms(node, lazy_bindings) {
 		// Skip VariableDeclarator id (already handled above).
 		if (key === 'id' && node.type === 'VariableDeclarator') continue;
 
+		// A JSX element/component name that resolves to a lazy binding becomes a
+		// JSX member expression (`<Item>` → `<__lazy0.Item>`): the bound name is no
+		// longer a local, it is a property of the synthesized lazy source.
+		if (
+			key === 'name' &&
+			(node.type === 'JSXOpeningElement' || node.type === 'JSXClosingElement')
+		) {
+			const jsx_name = rewrite_lazy_jsx_name(node[key], lazy_bindings);
+			if (jsx_name) {
+				clone[key] = jsx_name;
+				changed = true;
+				continue;
+			}
+		}
+
 		const new_value = apply_lazy_transforms(node[key], lazy_bindings);
 		if (new_value !== node[key]) {
 			clone[key] = new_value;

package/types/index.d.ts

@@ -83,6 +83,7 @@ interface BaseNodeMetaData {
 	commentContainerId?: number;
 	parenthesized?: boolean;
 	native_tsrx?: boolean;
+	tsrx_generated_wrapper?: boolean;
 	native_tsrx_template_block?: boolean;
 	dynamicElement?: boolean;
 	templateMode?: 'script' | 'template';
@@ -137,6 +138,7 @@ type AcornTSNode<T> = Omit<T, 'parent' | 'loc' | 'range' | 'expression'> & {
 
 	leadingComments?: AST.Comment[] | undefined;
 	trailingComments?: AST.Comment[] | undefined;
+	append_into?: AST.Identifier;
 };
 
 interface FunctionLikeTS {
@@ -295,6 +297,8 @@ declare module 'estree' {
 		TSAsExpression: TSAsExpression;
 	}
 
+	type TraversableAstNode = AST.Node & Record<string, unknown>;
+
 	// Ripple-normalized template node shapes. The core parser emits JSX-shaped
 	// TSRX nodes; @tsrx/ripple creates these during its normalization pass.
 	interface Attribute extends AST.BaseNode {
@@ -516,6 +520,8 @@ declare module 'estree' {
 		metadata: BaseNodeMetaData;
 
 		comments?: Comment[];
+
+		append_into?: AST.Identifier;
 	}
 
 	interface NodeWithLocation {