@tsrx/core 0.0.25 → 0.0.27

package/package.json

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

package/src/analyze/validation.js

@@ -19,6 +19,10 @@ export const COMPONENT_WHILE_STATEMENT_ERROR =
 	'While loops are not supported in components. Move the while loop into a function.';
 export const COMPONENT_DO_WHILE_STATEMENT_ERROR =
 	'Do...while loops are not supported in components. Move the do...while loop into a function.';
+export const CLASS_COMPONENT_AS_NON_ARROW_PROPERTY_ERROR =
+	'Components declared inside a class must be defined as an arrow function class property (e.g. `Foo = component() => { ... }`). Non-arrow component property values are not allowed.';
+export const COMPONENT_MULTIPLE_PARAMS_ERROR =
+	'Components accept a single props parameter. Move additional inputs into the props object instead.';
 
 const invalid_nestings = {
 	// <p> cannot contain block-level elements
@@ -247,6 +251,61 @@ export function validate_component_unsupported_loop_statement(node, filename, er
 	error(message, filename ?? null, node, errors, comments);
 }
 
+/**
+ * Validates that a component declares at most a single (props) parameter.
+ * Components have one slot for props; additional positional parameters are
+ * silently dropped or naively passed through depending on the target, so
+ * reject them at analysis time. Reports one error per extra parameter so
+ * every offending input gets its own TS diagnostic squiggle. In throwing
+ * mode the first call raises and aborts before the loop continues.
+ *
+ * @param {AST.Component} component
+ * @param {string | null | undefined} filename
+ * @param {CompileError[]} [errors]
+ * @param {AST.CommentWithLocation[]} [comments]
+ */
+export function validate_component_params(component, filename, errors, comments) {
+	const params = /** @type {AST.Pattern[] | undefined} */ (component.params);
+	if (!params || params.length <= 1) {
+		return;
+	}
+
+	for (let i = 1; i < params.length; i++) {
+		error(COMPONENT_MULTIPLE_PARAMS_ERROR, filename ?? null, params[i], errors, comments);
+	}
+}
+
+/**
+ * Validates that components declared at the top level of a class body use the
+ * only allowed form: an arrow function class property (regular or static).
+ * Reports an error for non-arrow component property values such as
+ * `Foo = component() { ... }`. The method form (`component foo() {}` inside
+ * a class body) is rejected at parse time and never reaches this check.
+ *
+ * @param {AST.ClassBody} class_body
+ * @param {string | null | undefined} filename
+ * @param {CompileError[]} [errors]
+ * @param {AST.CommentWithLocation[]} [comments]
+ */
+export function validate_class_component_declarations(class_body, filename, errors, comments) {
+	for (const member of class_body.body) {
+		if (member.type !== 'PropertyDefinition') {
+			continue;
+		}
+
+		const value = /** @type {any} */ (member).value;
+		if (value && value.type === 'Component' && !value.metadata?.arrow) {
+			error(
+				CLASS_COMPONENT_AS_NON_ARROW_PROPERTY_ERROR,
+				filename ?? null,
+				member,
+				errors,
+				comments,
+			);
+		}
+	}
+}
+
 /**
  * @param {AST.Element} element
  * @param {AnalysisContext} context

package/src/index.js

@@ -164,12 +164,16 @@ export {
 	flatten_switch_consequent,
 	get_for_of_iteration_params,
 	identifier_to_jsx_name,
+	is_bare_render_expression,
 	is_dynamic_element_id,
 	is_jsx_child,
 	set_loc,
 	to_text_expression,
 } from './transform/jsx/ast-builders.js';
-export { render_stylesheets as renderStylesheets } from './transform/stylesheet.js';
+export {
+	render_stylesheets as renderStylesheets,
+	render_css_result as renderCssResult,
+} from './transform/stylesheet.js';
 export {
 	prepare_stylesheet_for_render as prepareStylesheetForRender,
 	is_style_element as isStyleElement,
@@ -213,17 +217,21 @@ export {
 // Analyze
 export { analyze_css as analyzeCss } from './analyze/css-analyze.js';
 export {
+	CLASS_COMPONENT_AS_NON_ARROW_PROPERTY_ERROR,
 	COMPONENT_DO_WHILE_STATEMENT_ERROR,
 	COMPONENT_FOR_IN_STATEMENT_ERROR,
 	COMPONENT_FOR_STATEMENT_ERROR,
 	COMPONENT_LOOP_BREAK_ERROR,
 	COMPONENT_LOOP_RETURN_ERROR,
+	COMPONENT_MULTIPLE_PARAMS_ERROR,
 	COMPONENT_RETURN_VALUE_ERROR,
 	COMPONENT_WHILE_STATEMENT_ERROR,
 	get_return_keyword_node as getReturnKeywordNode,
 	get_statement_keyword_node as getStatementKeywordNode,
+	validate_class_component_declarations as validateClassComponentDeclarations,
 	validate_component_loop_break_statement as validateComponentLoopBreakStatement,
 	validate_component_loop_return_statement as validateComponentLoopReturnStatement,
+	validate_component_params as validateComponentParams,
 	validate_component_return_statement as validateComponentReturnStatement,
 	validate_component_unsupported_loop_statement as validateComponentUnsupportedLoopStatement,
 	validate_nesting as validateNesting,

package/src/plugin.js

@@ -559,65 +559,6 @@ export function TSRXPlugin(config) {
 				return super.parseProperty(isPattern, refDestructuringErrors);
 			}
 
-			/**
-			 * Override parseClassElement to support component methods in classes.
-			 * Handles syntax like `class Foo { component something() { <div /> } }`
-			 * Also supports computed names: `class Foo { component ['something']() { <div /> } }`
-			 * @type {Parse.Parser['parseClassElement']}
-			 */
-			parseClassElement(constructorAllowsSuper) {
-				// Check if this is a component method: component name( ... ) { ... }
-				if (this.type === tt.name && this.value === 'component') {
-					// Look ahead to see if this is "component identifier(",
-					// "component identifier<", "component [", or "component 'string'"
-					const lookahead = this.input.slice(this.pos).match(/^\s*(?:(\w+)\s*[(<]|\[|['"])/);
-					if (lookahead) {
-						// This is a component method definition
-						const node = /** @type {AST.MethodDefinition} */ (this.startNode());
-						const isComputed = lookahead[0].trim().startsWith('[');
-						const isStringLiteral = /^['"]/.test(lookahead[0].trim());
-
-						if (isComputed) {
-							// For computed names, consume 'component'
-							// parse the key, then parse component without name
-							this.next(); // consume 'component'
-							this.next(); // consume '['
-							node.key = this.parseExpression();
-							this.expect(tt.bracketR);
-							node.computed = true;
-
-							// Parse component without name (skipName: true)
-							const component_node = this.parseComponent({ skipName: true });
-							/** @type {AST.TSRXMethodDefinition} */ (node).value = component_node;
-						} else if (isStringLiteral) {
-							// For string literal names, consume 'component'
-							// parse the string key, then parse component without name
-							this.next(); // consume 'component'
-							node.key = /** @type {AST.Literal} */ (this.parseExprAtom());
-							node.computed = false;
-
-							// Parse component without name (skipName: true)
-							const component_node = this.parseComponent({ skipName: true });
-							/** @type {AST.TSRXMethodDefinition} */ (node).value = component_node;
-						} else {
-							// Use parseComponent which handles consuming 'component', parsing name, params, and body
-							const component_node = this.parseComponent({ requireName: true });
-
-							node.key = /** @type {AST.Identifier} */ (component_node.id);
-							/** @type {AST.TSRXMethodDefinition} */ (node).value = component_node;
-							node.computed = false;
-						}
-
-						node.static = false;
-						node.kind = 'method';
-
-						return this.finishNode(node, 'MethodDefinition');
-					}
-				}
-
-				return super.parseClassElement(constructorAllowsSuper);
-			}
-
 			/**
 			 * Override parsePropertyValue to support TypeScript generic methods in object literals.
 			 * By default, acorn-typescript doesn't handle `{ method<T>() {} }` syntax.
@@ -1371,8 +1312,8 @@ export function TSRXPlugin(config) {
 			 */
 			checkUnreserved(ref) {
 				if (ref.name === 'component') {
-					// Allow 'component' when it's followed by an identifier and '(' or '<' (component method in object literal or class)
-					// e.g., { component something() { ... } } or class Foo { component something<T>() { ... } }
+					// Allow 'component' when it's followed by an identifier and '(' or '<' (component method in object literal)
+					// e.g., { component something() { ... } }
 					// Also allow computed names: { component ['name']() { ... } }
 					// Also allow string literal names: { component 'name'() { ... } }
 					const nextChars = this.input.slice(this.pos).match(/^\s*(?:(\w+)\s*[(<]|\[|['"])/);

package/src/transform/jsx/ast-builders.js

@@ -187,6 +187,57 @@ export function is_jsx_child(node) {
 	);
 }
 
+/**
+ * The parser represents `<>{expr}</>` / `<tsx>{expr}</tsx>` as a Tsx node,
+ * and expression-position lowering unwraps that to the inner expression.
+ * When such a node appears directly in a component or statement render body,
+ * the unwrapped expression is still render output rather than an executable
+ * statement.
+ *
+ * @param {any} node
+ * @returns {boolean}
+ */
+export function is_bare_render_expression(node) {
+	if (!node || typeof node !== 'object') {
+		return false;
+	}
+
+	switch (node.type) {
+		case 'ArrayExpression':
+		case 'ArrowFunctionExpression':
+		case 'AssignmentExpression':
+		case 'AwaitExpression':
+		case 'BinaryExpression':
+		case 'CallExpression':
+		case 'ChainExpression':
+		case 'ClassExpression':
+		case 'ConditionalExpression':
+		case 'FunctionExpression':
+		case 'Identifier':
+		case 'ImportExpression':
+		case 'Literal':
+		case 'LogicalExpression':
+		case 'MemberExpression':
+		case 'MetaProperty':
+		case 'NewExpression':
+		case 'ObjectExpression':
+		case 'ParenthesizedExpression':
+		case 'SequenceExpression':
+		case 'TaggedTemplateExpression':
+		case 'TemplateLiteral':
+		case 'ThisExpression':
+		case 'TSAsExpression':
+		case 'TSSatisfiesExpression':
+		case 'TSNonNullExpression':
+		case 'UnaryExpression':
+		case 'UpdateExpression':
+		case 'YieldExpression':
+			return true;
+		default:
+			return false;
+	}
+}
+
 /**
  * A dynamic element id is one whose identifier is `tracked` — i.e. it was
  * introduced by reactive destructuring so its value can change at runtime.

package/src/transform/jsx/index.js

@@ -20,12 +20,13 @@ import {
 	flatten_switch_consequent,
 	get_for_of_iteration_params,
 	identifier_to_jsx_name,
+	is_bare_render_expression,
 	is_dynamic_element_id,
 	is_jsx_child,
 	set_loc,
 	to_text_expression,
 } from './ast-builders.js';
-import { render_stylesheets as renderStylesheets } from '../stylesheet.js';
+import { render_css_result } from '../stylesheet.js';
 import {
 	set_location as setLocation,
 	jsx_attribute as build_jsx_attribute,
@@ -41,8 +42,10 @@ import {
 import { find_first_top_level_await_in_component_body } from '../await.js';
 import { prepare_stylesheet_for_render, annotate_component_with_hash } from '../scoping.js';
 import {
+	validate_class_component_declarations,
 	validate_component_loop_break_statement,
 	validate_component_loop_return_statement,
+	validate_component_params,
 	validate_component_return_statement,
 	validate_component_unsupported_loop_statement,
 } from '../../analyze/validation.js';
@@ -167,6 +170,8 @@ export function createJsxTransform(platform) {
 			needs_suspense: false,
 			needs_merge_refs: false,
 			needs_fragment: false,
+			module_scoped_hook_components:
+				options?.moduleScopedHookComponents ?? !!platform.hooks?.moduleScopedHookComponents,
 			helper_state: null,
 			available_bindings: new Map(),
 			lazy_next_id: 0,
@@ -175,12 +180,15 @@ export function createJsxTransform(platform) {
 			collect,
 			errors: collect ? options?.errors : undefined,
 			comments: options?.comments,
+			typeOnly: !!options?.typeOnly,
 			// Platforms can seed their own tracking state (e.g. solid's
 			// needs_show / needs_for flags) via `hooks.initialState`.
 			...(platform.hooks?.initialState?.() ?? {}),
 		};
 
-		preallocate_lazy_ids(/** @type {any} */ (ast), transform_context);
+		if (!transform_context.typeOnly) {
+			preallocate_lazy_ids(/** @type {any} */ (ast), transform_context);
+		}
 
 		walk(/** @type {any} */ (ast), transform_context, {
 			ReturnStatement(node, { next, path }) {
@@ -270,9 +278,26 @@ export function createJsxTransform(platform) {
 				return next();
 			},
 
+			ClassBody(node, { next }) {
+				validate_class_component_declarations(
+					/** @type {any} */ (node),
+					filename,
+					transform_context.errors,
+					transform_context.comments,
+				);
+				return next();
+			},
+
 			Component(node, { next, state }) {
 				const as_any = /** @type {any} */ (node);
 
+				validate_component_params(
+					as_any,
+					filename,
+					transform_context.errors,
+					transform_context.comments,
+				);
+
 				const await_expression = find_first_top_level_await_in_component_body(as_any.body || []);
 
 				if (await_expression) {
@@ -420,8 +445,15 @@ export function createJsxTransform(platform) {
 		// declarations, arrow functions, etc.). Component bodies have already been
 		// transformed inside component_to_function_declaration; this catches plain
 		// functions outside components and any lazy patterns in module scope.
+		// In type-only mode, the lazy patterns survive untouched: esrap ignores the
+		// non-standard `lazy` flag, so `&{ a, b }` prints as `{ a, b }`, `let &[a]
+		// = 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.
 		const final_program = /** @type {any} */ (
-			apply_lazy_transforms(/** @type {any} */ (expanded), new Map())
+			transform_context.typeOnly
+				? expanded
+				: apply_lazy_transforms(/** @type {any} */ (expanded), new Map())
 		);
 
 		const result = print(/** @type {any} */ (final_program), tsx_with_ts_locations(), {
@@ -429,17 +461,11 @@ export function createJsxTransform(platform) {
 			sourceMapContent: source,
 		});
 
-		const css =
-			stylesheets.length > 0
-				? {
-						code: renderStylesheets(
-							/** @type {any} */ (stylesheets.map(prepare_stylesheet_for_render)),
-						),
-						hash: stylesheets.map((s) => s.hash).join(' '),
-					}
-				: null;
+		const { css, cssHash } = render_css_result(
+			/** @type {any} */ (stylesheets.map(prepare_stylesheet_for_render)),
+		);
 
-		return { ast: final_program, code: result.code, map: result.map, css };
+		return { ast: final_program, code: result.code, map: result.map, css, cssHash };
 	}
 
 	return transform;
@@ -503,7 +529,11 @@ export function component_to_function_declaration(component, transform_context,
 	// Collect lazy binding info WITHOUT mutating patterns. Stores lazy_id on metadata
 	// for later replacement. Body bindings (count, setCount, etc.) are still in the
 	// original patterns, so collect_statement_bindings during build will find them.
-	const lazy_bindings = collect_lazy_bindings_from_component(params, body, transform_context);
+	// In type-only mode the lazy rewrite is skipped entirely so destructuring
+	// patterns survive into the virtual TSX and TypeScript can flow real types.
+	const lazy_bindings = transform_context.typeOnly
+		? new Map()
+		: collect_lazy_bindings_from_component(params, body, transform_context);
 
 	// Save and set context for this component scope
 	const saved_helper_state = transform_context.helper_state;
@@ -624,6 +654,10 @@ function build_render_statements(body_nodes, return_null_when_empty, transform_c
 	// any JSX is constructed, and every JSX child would observe the final
 	// state of mutable variables.
 	const interleaved = is_interleaved_body(body_nodes);
+	const capture_static_early_return_nodes =
+		!interleaved &&
+		!transform_context.platform.hooks?.isTopLevelSetupCall &&
+		body_nodes.filter(is_returning_if_statement).length > 1;
 	let capture_index = 0;
 
 	for (let i = 0; i < body_nodes.length; i += 1) {
@@ -648,6 +682,15 @@ function build_render_statements(body_nodes, return_null_when_empty, transform_c
 				true,
 			);
 
+			if (capture_static_early_return_nodes) {
+				capture_index = capture_static_early_return_render_nodes(
+					render_nodes,
+					statements,
+					capture_index,
+					transform_context,
+				);
+			}
+
 			if (branch_has_hooks || continuation_has_hooks) {
 				if (transform_context.platform.hooks?.isTopLevelSetupCall) {
 					statements.push(
@@ -870,6 +913,8 @@ function build_render_statements(body_nodes, return_null_when_empty, transform_c
 			} else {
 				render_nodes.push(jsx);
 			}
+		} else if (is_bare_render_expression(child)) {
+			render_nodes.push(to_jsx_expression_container(child, child));
 		} else {
 			statements.push(child);
 			collect_statement_bindings(child, transform_context.available_bindings);
@@ -1157,6 +1202,25 @@ function create_helper_state(base_name) {
 	};
 }
 
+/**
+ * @param {TransformContext} transform_context
+ * @returns {boolean}
+ */
+function should_use_module_scoped_hook_components(transform_context) {
+	return !!(transform_context.helper_state && transform_context.module_scoped_hook_components);
+}
+
+/**
+ * @param {AST.Identifier} helper_id
+ * @param {TransformContext} transform_context
+ * @returns {AST.Identifier}
+ */
+function create_module_scoped_hook_component_id(helper_id, transform_context) {
+	return create_generated_identifier(
+		`${transform_context.helper_state?.base_name || 'Component'}__${helper_id.name}`,
+	);
+}
+
 /**
  * @param {any[]} params
  * @returns {Map<string, AST.Identifier>}
@@ -1325,6 +1389,59 @@ function hoist_static_render_nodes(render_nodes, transform_context) {
 	}
 }
 
+/**
+ * Static JSX that appears before multiple early-return guards is otherwise
+ * cloned into every generated return. Capture it once at its source position
+ * and reuse the reference, matching the interleaved-statement capture path
+ * without moving dynamic render-time expressions across guards.
+ *
+ * @param {any[]} render_nodes
+ * @param {any[]} statements
+ * @param {number} capture_index
+ * @param {TransformContext} transform_context
+ * @returns {number}
+ */
+function capture_static_early_return_render_nodes(
+	render_nodes,
+	statements,
+	capture_index,
+	transform_context,
+) {
+	for (let i = 0; i < render_nodes.length; i += 1) {
+		const node = render_nodes[i];
+		if (!is_static_early_return_capture_node(node, transform_context)) {
+			continue;
+		}
+
+		const { declaration, reference } = captureJsxChild(node, capture_index++);
+		statements.push(declaration);
+		render_nodes[i] = reference;
+	}
+
+	return capture_index;
+}
+
+/**
+ * @param {any} node
+ * @param {TransformContext} transform_context
+ * @returns {boolean}
+ */
+function is_static_early_return_capture_node(node, transform_context) {
+	if (node?.type !== 'JSXElement' && node?.type !== 'JSXFragment') {
+		return false;
+	}
+	if (!is_hoist_safe_jsx_node(node)) {
+		return false;
+	}
+	if (
+		transform_context.platform.hooks?.canHoistStaticNode &&
+		!transform_context.platform.hooks.canHoistStaticNode(node, transform_context)
+	) {
+		return false;
+	}
+	return !references_scope_bindings(node, transform_context.available_bindings);
+}
+
 /**
  * @param {AST.Program} program
  * @returns {AST.Program}
@@ -2083,25 +2200,33 @@ function build_hoisted_for_of_with_hooks(node, continuation_body, transform_cont
 	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),
-	);
+	const use_module_scoped_component = should_use_module_scoped_hook_components(transform_context);
+	const component_id = use_module_scoped_component
+		? create_module_scoped_hook_component_id(helper_id, transform_context)
+		: helper_id;
+
+	const outer_aliases = use_module_scoped_component
+		? []
+		: outer_bindings.map((binding) => create_helper_type_alias_declaration(helper_id, binding));
+	const loop_aliases = use_module_scoped_component
+		? []
+		: 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 every
 	// loop-helper return can append the tail helper on the last iteration.
 	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'),
-				),
-			}
+		? use_module_scoped_component
+			? null
+			: {
+					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];
@@ -2115,7 +2240,7 @@ function build_hoisted_for_of_with_hooks(node, continuation_body, transform_cont
 	const signature_use_typeof = has_tail ? [...ordered_use_typeof, false] : ordered_use_typeof;
 
 	const props_type =
-		signature_bindings.length > 0
+		signature_bindings.length > 0 && !use_module_scoped_component
 			? create_helper_props_type_literal_with_typeof_flags(
 					signature_bindings,
 					signature_aliases,
@@ -2123,7 +2248,13 @@ function build_hoisted_for_of_with_hooks(node, continuation_body, transform_cont
 				)
 			: null;
 	const params =
-		props_type !== null ? [create_typed_helper_props_pattern(signature_bindings, props_type)] : [];
+		signature_bindings.length > 0
+			? [
+					props_type !== null
+						? create_typed_helper_props_pattern(signature_bindings, props_type)
+						: create_helper_props_pattern(signature_bindings),
+				]
+			: [];
 
 	const fn_saved_bindings = transform_context.available_bindings;
 	transform_context.available_bindings = new Map(fn_saved_bindings);
@@ -2141,12 +2272,17 @@ function build_hoisted_for_of_with_hooks(node, continuation_body, transform_cont
 	transform_context.available_bindings = fn_saved_bindings;
 
 	const helper_fn = /** @type {any} */ (
-		b.function(clone_identifier(helper_id), params, b.block(fn_body_statements))
+		b.function(clone_identifier(component_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) {
+	if (transform_context.helper_state && use_module_scoped_component) {
+		transform_context.helper_state.helpers.push(
+			create_helper_declaration(component_id, helper_fn, node, transform_context),
+		);
+		helper_decl = null;
+	} else if (transform_context.helper_state) {
 		const cache_id = create_generated_identifier(
 			`${transform_context.helper_state.base_name}__${helper_id.name}`,
 		);
@@ -2163,7 +2299,7 @@ function build_hoisted_for_of_with_hooks(node, continuation_body, transform_cont
 	transform_context.available_bindings = saved_bindings;
 
 	const callback_invocation_element = create_helper_component_element(
-		helper_id,
+		component_id,
 		ordered_bindings,
 		node,
 		{ mapWrapper: false, mapBindingNames: false, mapBindingValues: false },
@@ -2244,7 +2380,9 @@ function build_hoisted_for_of_with_hooks(node, continuation_body, transform_cont
 	if (has_tail && tail_isLast_alias) {
 		hoist_statements.push(tail_isLast_alias.declaration);
 	}
-	hoist_statements.push(helper_decl);
+	if (helper_decl) {
+		hoist_statements.push(helper_decl);
+	}
 
 	return {
 		hoist_statements,
@@ -2704,8 +2842,8 @@ function create_local_statement_component_name(transform_context) {
 /**
  * Wraps a list of body nodes into a component and returns
  * statements that return `<ComponentName prop1={prop1} ... />`.
- * The component is hoisted to module level via helper_state to avoid
- * recreating the component identity on every render.
+ * Targets can either emit the helper component at module scope or cache the
+ * component identity in module state while initializing it from the parent.
  * Used when a control flow branch contains hook calls that must be moved
  * into their own component boundary to satisfy the Rules of Hooks.
  *
@@ -2778,24 +2916,36 @@ function create_hook_safe_helper(
 	const helper_id =
 		preallocated_helper_id ??
 		create_generated_identifier(create_local_statement_component_name(transform_context));
+	const use_module_scoped_component = should_use_module_scoped_hook_components(transform_context);
+	const component_id = use_module_scoped_component
+		? create_module_scoped_hook_component_id(helper_id, transform_context)
+		: helper_id;
 	const helper_bindings = get_referenced_helper_bindings(
 		body_nodes,
 		transform_context.available_bindings,
 	);
-	const aliases = helper_bindings.map((binding) =>
-		create_helper_type_alias_declaration(helper_id, binding),
-	);
+	const aliases = use_module_scoped_component
+		? []
+		: helper_bindings.map((binding) => create_helper_type_alias_declaration(helper_id, binding));
 	const props_type =
-		helper_bindings.length > 0 ? create_helper_props_type_literal(helper_bindings, aliases) : null;
+		helper_bindings.length > 0 && !use_module_scoped_component
+			? create_helper_props_type_literal(helper_bindings, aliases)
+			: null;
 	const params =
-		props_type !== null ? [create_typed_helper_props_pattern(helper_bindings, props_type)] : [];
+		helper_bindings.length > 0
+			? [
+					props_type !== null
+						? create_typed_helper_props_pattern(helper_bindings, props_type)
+						: create_helper_props_pattern(helper_bindings),
+				]
+			: [];
 
 	const saved_bindings = transform_context.available_bindings;
 	transform_context.available_bindings = new Map(saved_bindings);
 
 	const helper_fn = /** @type {any} */ ({
 		type: 'FunctionExpression',
-		id: clone_identifier(helper_id),
+		id: clone_identifier(component_id),
 		params,
 		body: {
 			type: 'BlockStatement',
@@ -2814,7 +2964,7 @@ function create_hook_safe_helper(
 	transform_context.available_bindings = saved_bindings;
 
 	const component_element = create_helper_component_element(
-		helper_id,
+		component_id,
 		helper_bindings,
 		source_node,
 		{
@@ -2845,6 +2995,16 @@ function create_hook_safe_helper(
 		};
 	}
 
+	if (use_module_scoped_component) {
+		transform_context.helper_state.helpers.push(
+			create_helper_declaration(component_id, helper_fn, source_node, transform_context),
+		);
+		return {
+			setup_statements: [],
+			component_element,
+		};
+	}
+
 	const cache_id = create_generated_identifier(
 		`${transform_context.helper_state.base_name}__${helper_id.name}`,
 	);
@@ -4196,6 +4356,8 @@ function create_render_switch_case(switch_case, transform_context) {
 
 		if (is_jsx_child(child)) {
 			render_nodes.push(to_jsx_child(child, transform_context));
+		} else if (is_bare_render_expression(child)) {
+			render_nodes.push(to_jsx_expression_container(child, child));
 		} else {
 			case_body.push(child);
 		}

package/src/transform/segments.js

@@ -439,7 +439,6 @@ export function convert_source_map_to_mappings(
 	}
 
 	/**
-	 * @typedef {AST.MethodDefinition & {value: {metadata: {is_component: true}}}} MethodIsComponent
 	 * @typedef {AST.Property & {value: AST.FunctionExpression, method: true} & {value: {metadata: {is_component: true}}}} PropertyIsComponent
 	 */
 
@@ -447,7 +446,7 @@ export function convert_source_map_to_mappings(
 	 * Maps `component` to the identifier's location
 	 * e.g. const obj = { component something() { } }
 	 * since there is no function keyword in source maps
-	 * @param {MethodIsComponent | PropertyIsComponent} node
+	 * @param {PropertyIsComponent} node
 	 * @returns {void}
 	 */
 	function set_component_mapping_to_name(node) {
@@ -1530,15 +1529,8 @@ export function convert_source_map_to_mappings(
 					set_bracket_computed_mapping(node, mappings);
 				}
 
-				if (node.value.metadata.is_component) {
-					set_component_mapping_to_name(/** @type {MethodIsComponent} */ (node));
-				}
-
 				if (node.key.type === 'Literal') {
-					handle_literal(
-						node.key,
-						/** @type {AST.FunctionExpression} */ (node.value).metadata.is_component,
-					);
+					handle_literal(node.key);
 				} else {
 					visit(node.key);
 				}

package/src/transform/stylesheet.js

@@ -543,3 +543,22 @@ export function render_stylesheets(stylesheets, minify = false) {
 
 	return css;
 }
+
+/**
+ * Render the `{ css, cssHash }` slice of a `CompileResult` from a list of
+ * stylesheets. Returns `{ css: '', cssHash: null }` when the list is empty
+ * so consumers can pass the result straight into a flat compile result.
+ *
+ * @param {AST.CSS.StyleSheet[]} stylesheets
+ * @param {boolean} [minify]
+ * @returns {{ css: string, cssHash: string | null }}
+ */
+export function render_css_result(stylesheets, minify = false) {
+	if (stylesheets.length === 0) {
+		return { css: '', cssHash: null };
+	}
+	return {
+		css: render_stylesheets(stylesheets, minify),
+		cssHash: stylesheets.map((s) => s.hash).join(' '),
+	};
+}

package/types/index.d.ts

@@ -463,10 +463,6 @@ declare module 'estree' {
 		body: (Program['body'][number] | Component | FunctionExpression)[];
 	}
 
-	interface TSRXMethodDefinition extends Omit<AST.MethodDefinition, 'value'> {
-		value: AST.MethodDefinition['value'] | Component;
-	}
-
 	interface TSRXProperty extends Omit<AST.Property, 'value'> {
 		value: AST.Property['value'] | Component;
 	}
@@ -1575,15 +1571,17 @@ export interface VolarMappingsResult {
  * Result of compilation operation
  */
 export interface CompileResult {
-	/** The transformed AST */
-	ast: AST.Program;
-	/** The generated JavaScript code with source map */
-	js: {
-		code: string;
-		map: import('source-map').RawSourceMap;
-	};
-	/** The generated CSS */
+	/** The generated JavaScript code */
+	code: string;
+	/** Source map for the generated code */
+	map: import('source-map').RawSourceMap;
+	/** Rendered CSS for the module, or `''` when the module emits no styles. */
 	css: string;
+	/**
+	 * Space-separated scope hashes for the rendered CSS, or `null` when the
+	 * module emits no styles.
+	 */
+	cssHash: string | null;
 	/**
 	 * Non-fatal errors collected during compilation. Populated only when the
 	 * caller passes `collect: true` or `loose: true`; empty otherwise.
@@ -1599,6 +1597,46 @@ export interface VolarCompileOptions extends Omit<ParseOptions, 'errors' | 'comm
 	dev?: boolean;
 }
 
+/**
+ * Common base options accepted by every TSRX target's `compile` entry point.
+ * Targets that need extra knobs (e.g. ripple's `mode`/`dev`/`hmr`, preact's
+ * `suspenseSource`) intersect their own option type with this base when
+ * declaring their `compile` export.
+ */
+export interface BaseCompileOptions {
+	collect?: boolean;
+	loose?: boolean;
+}
+
+/**
+ * Shared `compile` signature for every TSRX target package. Per-target
+ * `compile` declarations should be `CompileFn<TOptions, TResult>` so any
+ * drift in the shared contract becomes a typecheck error in every package.
+ *
+ * @template TOptions Per-target options accepted as the third argument.
+ *   Defaults to {@link BaseCompileOptions}.
+ * @template TResult Per-target result type. Must extend {@link CompileResult};
+ *   targets may add fields (e.g. ripple's deprecated `js` back-compat field)
+ *   via intersection.
+ */
+export type CompileFn<
+	TOptions = BaseCompileOptions,
+	TResult extends CompileResult = CompileResult,
+> = (source: string, filename?: string, options?: TOptions) => TResult;
+
+/**
+ * Shared `compile_to_volar_mappings` signature for every TSRX target package.
+ *
+ * @template TOptions Per-target options accepted as the third argument.
+ *   Defaults to {@link ParseOptions}; targets may intersect their own option
+ *   type to add e.g. `suspenseSource`.
+ */
+export type VolarCompileFn<TOptions = ParseOptions> = (
+	source: string,
+	filename?: string,
+	options?: TOptions,
+) => VolarMappingsResult;
+
 /**
  * Source map transformation types
  */

package/types/jsx-platform.d.ts

@@ -14,7 +14,14 @@ export interface JsxTransformResult {
 	 * downstream Vite / Rollup plugins to chain source maps.
 	 */
 	map: RawSourceMap;
-	css: { code: string; hash: string } | null;
+	/** Rendered CSS for the module, or `''` when the module emits no styles. */
+	css: string;
+	/**
+	 * Space-separated scope hashes for the rendered CSS, or `null` when the
+	 * module emits no styles. When multiple `<style>` blocks contribute, the
+	 * hashes appear in source order.
+	 */
+	cssHash: string | null;
 }
 
 /**
@@ -30,6 +37,7 @@ export interface JsxTransformContext {
 	needs_suspense: boolean;
 	needs_merge_refs: boolean;
 	needs_fragment: boolean;
+	module_scoped_hook_components: boolean;
 	helper_state: {
 		base_name: string;
 		next_id: number;
@@ -48,6 +56,8 @@ export interface JsxTransformContext {
 	errors: CompileError[] | undefined;
 	/** Module-level comments used to honor `@tsrx-ignore` / `@tsrx-expect-error`. */
 	comments: AST.CommentWithLocation[] | undefined;
+	/** True when emitting a type-only virtual TSX module; preserves lazy destructuring patterns. */
+	typeOnly: boolean;
 }
 
 /**
@@ -80,6 +90,20 @@ export interface JsxTransformOptions {
 	 * `@tsrx-expect-error` line comments.
 	 */
 	comments?: AST.CommentWithLocation[];
+	/**
+	 * Override whether hook-isolation helper components are emitted directly at
+	 * module scope. React runtime compilation enables this, while editor tooling
+	 * can disable it to preserve lexical `typeof` helper prop types.
+	 */
+	moduleScopedHookComponents?: boolean;
+	/**
+	 * Emit a type-only virtual TSX module — output is fed to TypeScript for
+	 * editor diagnostics / completions and never executed. Skips the lazy
+	 * destructuring rewrite (`&{ a, b }` → `__lazy0: { a: any; b: any }`) so
+	 * destructuring patterns survive and TypeScript can flow real types to the
+	 * bindings.
+	 */
+	typeOnly?: boolean;
 }
 
 /**
@@ -135,6 +159,13 @@ export interface JsxPlatformHooks {
 	 * state behaves like normal component state.
 	 */
 	wrapHelperComponent?: (helperFn: any, helperId: any, ctx: any, sourceNode: any) => any;
+	/**
+	 * Emit hook-isolation helper components as unique module-scope declarations
+	 * instead of lazily creating and caching them from the parent component body.
+	 * React enables this so generated branches stay compatible with the React
+	 * Compiler's Rules of Hooks validation.
+	 */
+	moduleScopedHookComponents?: boolean;
 	/**
 	 * Inject module-level imports after the main walk. Default: import
 	 * `Suspense` from `platform.imports.suspense` and `TsrxErrorBoundary`
@@ -162,7 +193,7 @@ export interface JsxPlatformHooks {
 	 * Optionally replace the default React-style `.map(...)` lowering for a
 	 * `for...of` body after the shared transform has already produced its render
 	 * statements and applied any explicit or implicit keys. Vue uses this to hand
-	 * the loop to the downstream Vapor JSX compiler as a native `v-for` template.
+	 * the loop to the downstream Vapor JSX compiler as a typed `VaporFor` component.
 	 */
 	renderForOf?: (node: any, loopParams: any[], bodyStatements: any[], ctx: any) => any | null;
 	/**