@tsrx/core 0.1.47 → 0.1.49

package/src/transform/jsx-hoist.js

@@ -1,3 +1,4 @@
+/** @import * as AST from 'estree' */
 /** @import * as ESTreeJSX from 'estree-jsx' */
 
 /**
@@ -104,7 +105,7 @@ export function is_hoist_safe_jsx_attribute(attribute) {
 }
 
 /**
- * @param {ESTreeJSX.JSXElement | ESTreeJSX.JSXFragment} node
+ * @param {AST.TSRXJSXElement | AST.TSRXJSXFragment} node
  * @returns {boolean}
  */
 export function is_hoist_safe_jsx_node(node) {

package/src/transform/jsx-interleave.js

@@ -8,6 +8,11 @@
  * textually after the mutation.
  */
 
+/** @import * as AST from 'estree' */
+/** @import * as ESTreeJSX from 'estree-jsx' */
+
+import * as b from '../utils/builders.js';
+
 /**
  * Returns true when the body contains a non-JSX statement that appears
  * after a JSX child. In that case JSX children must be captured at their
@@ -17,8 +22,8 @@
  * The `is_jsx_child` predicate is target-specific — each target recognizes
  * its JSX-bearing child nodes and template-control expressions.
  *
- * @param {any[]} body_nodes
- * @param {(node: any) => boolean} is_jsx_child
+ * @param {AST.Node[]} body_nodes
+ * @param {(node: AST.Node) => boolean} is_jsx_child
  * @returns {boolean}
  */
 export function is_interleaved_body(body_nodes, is_jsx_child) {
@@ -35,11 +40,12 @@ export function is_interleaved_body(body_nodes, is_jsx_child) {
 
 /**
  * Only JSX nodes that evaluate to a single expression can be hoisted into a
- * `const`. Static text children (`JSXText`) are inert and don't need
- * capturing — their position relative to mutations doesn't change output.
+ * `const`. Static text children (`JSXText`) and comment-only containers
+ * (`{/* … *\/}`) are inert and don't need capturing — their position relative
+ * to mutations doesn't change output, and neither has an expression to bind.
  *
- * @param {any} jsx
- * @returns {boolean}
+ * @param {AST.Node | null | undefined} jsx
+ * @returns {jsx is ESTreeJSX.JSXCapturableChild}
  */
 export function is_capturable_jsx_child(jsx) {
 	if (!jsx) return false;
@@ -48,7 +54,8 @@ export function is_capturable_jsx_child(jsx) {
 	// into a const would evaluate them once.
 	if (jsx.metadata?.tsrx_reactive_block === true) return false;
 	const t = jsx.type;
-	return t === 'JSXElement' || t === 'JSXFragment' || t === 'JSXExpressionContainer';
+	if (t === 'JSXExpressionContainer') return jsx.expression.type !== 'JSXEmptyExpression';
+	return t === 'JSXElement' || t === 'JSXFragment';
 }
 
 /**
@@ -58,45 +65,24 @@ export function is_capturable_jsx_child(jsx) {
  * statements in source order and uses the reference in place of the JSX
  * child inside the returned fragment.
  *
- * @param {any} jsx
+ * @param {ESTreeJSX.JSXCapturableChild} jsx
  * @param {number} capture_index
- * @returns {{ declaration: any, reference: any }}
+ * @param {(id: AST.Identifier, init: AST.Expression) => AST.Identifier} [anchor_id] gives the
+ *   capture's NAME an authored origin — the only anchorable token when the captured
+ *   expression itself starts with punctuation
+ * @returns {{ declaration: AST.VariableDeclaration, reference: ESTreeJSX.JSXExpressionContainer }}
  */
-export function capture_jsx_child(jsx, capture_index) {
+export function capture_jsx_child(jsx, capture_index, anchor_id) {
 	const name = `_tsrx_child_${capture_index}`;
 	const init = jsx.type === 'JSXExpressionContainer' ? jsx.expression : jsx;
 
-	const declaration = /** @type {any} */ ({
-		type: 'VariableDeclaration',
-		kind: 'const',
-		declarations: [
-			/** @type {any} */ ({
-				type: 'VariableDeclarator',
-				id: /** @type {any} */ ({
-					type: 'Identifier',
-					name,
-					metadata: { path: [] },
-				}),
-				init,
-				metadata: { path: [] },
-			}),
-		],
-		metadata: { path: [] },
-	});
+	const declaration = b.const(anchor_id ? anchor_id(b.id(name), init) : b.id(name), init);
 
 	// NOTE: JSXExpressionContainer nodes are intentionally created without
 	// loc — they're synthetic wrappers whose source positions don't
 	// correspond to source-map entries and adding loc causes Volar mapping
 	// failures.
-	const reference = /** @type {any} */ ({
-		type: 'JSXExpressionContainer',
-		expression: /** @type {any} */ ({
-			type: 'Identifier',
-			name,
-			metadata: { path: [] },
-		}),
-		metadata: { path: [] },
-	});
+	const reference = b.jsx_expression_container(b.id(name));
 
 	return { declaration, reference };
 }

package/src/transform/scoping.js

@@ -5,6 +5,8 @@
  * `.foo.hash`) match after rendering.
  */
 
+/** @import * as AST from 'estree' */
+
 import { walk } from 'zimmerframe';
 import * as b from '../utils/builders.js';
 import { mark_class_map_selectors } from './style-ref.js';
@@ -91,8 +93,8 @@ function is_unreachable_via_class_map(complex_selector, path) {
 }
 
 /**
- * @param {any} node
- * @returns {boolean}
+ * @param {AST.Node | null | undefined} node
+ * @returns {node is AST.JSXStyleElement}
  */
 export function is_style_element(node) {
 	return !!node && node.type === 'JSXStyleElement';

package/src/transform/segments.js

@@ -68,6 +68,7 @@ import { should_preserve_comment } from '../comment-utils.js';
 import { has_location } from '../utils/ast.js';
 
 const LAZY_PARAM_IDENTIFIER_REGEX = /^__lazy\d+$/;
+const RETURN_KEYWORD = 'return';
 
 /**
  * @param {string} value
@@ -1506,18 +1507,31 @@ export function convert_source_map_to_mappings(
 					visit(node.argument);
 				}
 
-				if (node.type === 'ReturnStatement' && has_location(node)) {
+				// Map only the `return` KEYWORD: a whole-statement mapping is too broad
+				// and shadows the finer mappings of everything inside it.
+				//
+				// That clamp is only meaningful when the author actually wrote the
+				// keyword there. A SYNTHESIZED return — every template arm in a
+				// `.tsrx` file (`@case`/`@default`/`@empty`/`@else` bodies, a `@{ … }`
+				// body) — carries the arm's authored range instead, whose text is the
+				// arm's own syntax. Clamping that to six characters pairs an arbitrary
+				// slice of source (`@defau`) with an arbitrary slice of output
+				// (`defaul`), which then wins any narrowest-match lookup. A
+				// synthesized return has no authored keyword to point at, so it
+				// contributes no mapping.
+				if (
+					node.type === 'ReturnStatement' &&
+					has_location(node) &&
+					source.startsWith(RETURN_KEYWORD, node.start)
+				) {
 					const mapping = get_mapping_from_node(
 						node,
 						src_to_gen_map,
 						gen_line_offsets,
 						mapping_data_verify_only,
 					);
-					// We're only mapping the 'return' keyword, otherwise the mapping would be too broad
-					// and likely may cause issues with partial mappings of something inside the return statement that we need
-					const return_keyword_length = 'return'.length;
-					mapping.lengths = [return_keyword_length];
-					mapping.generatedLengths = [return_keyword_length];
+					mapping.lengths = [RETURN_KEYWORD.length];
+					mapping.generatedLengths = [RETURN_KEYWORD.length];
 
 					mappings.push(mapping);
 				}

package/src/utils/ast.js

@@ -20,6 +20,43 @@
 
 import * as b from './builders.js';
 
+/**
+ * @param {unknown} value
+ * @returns {value is AST.Node}
+ */
+export function is_ast_node(value) {
+	return !!value && typeof value === 'object' && 'type' in value;
+}
+
+/**
+ * The child nodes reachable from `node`'s own properties, flattening node
+ * arrays. Positional and metadata keys are skipped: they never hold children,
+ * and `metadata` in particular can hold memoized lowerings of nodes that are
+ * already reachable elsewhere in the tree.
+ *
+ * @param {AST.Node} node
+ * @param {string} [skip_key] an extra own key to skip
+ * @returns {AST.Node[]}
+ */
+export function child_nodes(node, skip_key) {
+	/** @type {AST.Node[]} */
+	const children = [];
+	const entries = /** @type {AST.TraversableAstNode} */ (node);
+	for (const key of Object.keys(entries)) {
+		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') continue;
+		if (key === skip_key) continue;
+		const value = entries[key];
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				if (is_ast_node(item)) children.push(item);
+			}
+		} else if (is_ast_node(value)) {
+			children.push(value);
+		}
+	}
+	return children;
+}
+
 /**
  * @template {object} T
  * @param {T | null | undefined} node

package/src/utils/builders.js

@@ -605,13 +605,17 @@ export function ts_type_literal(members, loc_info) {
 }
 
 /**
+ * `@types/estree`'s `Statement` union has no TS declarations in it, so the
+ * result is typed as both: a `type X = …` alias occupies a statement slot
+ * everywhere the transforms emit one.
+ *
  * @param {AST.Identifier} id
  * @param {AST.Node} type_annotation
  * @param {AST.NodeWithLocation} [loc_info]
- * @returns {AST.TSTypeAliasDeclaration}
+ * @returns {AST.TSTypeAliasDeclaration & AST.Statement}
  */
 export function ts_type_alias(id, type_annotation, loc_info) {
-	const node = /** @type {AST.TSTypeAliasDeclaration} */ ({
+	const node = /** @type {AST.TSTypeAliasDeclaration & AST.Statement} */ ({
 		type: 'TSTypeAliasDeclaration',
 		id,
 		typeParameters: undefined,
@@ -1090,8 +1094,8 @@ export function try_builder(block, handler = null, finalizer = null, pending = n
 }
 
 /**
- * @param {AST.Pattern | null} param
- * @param {AST.Pattern | null} reset_param
+ * @param {AST.Pattern | null | undefined} param
+ * @param {AST.Pattern | null | undefined} reset_param
  * @param {AST.BlockStatement} body
  * @param {AST.NodeWithLocation} [loc_info]
  * @return {AST.CatchClause}
@@ -1100,8 +1104,8 @@ export function catch_clause_builder(param, reset_param, body, loc_info) {
 	/** @type {AST.CatchClause} */
 	const node = {
 		type: 'CatchClause',
-		param,
-		resetParam: reset_param,
+		param: param ?? null,
+		resetParam: reset_param ?? null,
 		body,
 		metadata: { path: [] },
 	};
@@ -1147,7 +1151,7 @@ export function jsx_attribute(name, value = null, shorthand = false, loc_info) {
  * @param {boolean} [self_closing]
  * @param {ESTreeJSX.JSXOpeningElement['typeArguments']} [type_arguments]
  * @param {AST.NodeWithLocation} [loc_info]
- * @returns {ESTreeJSX.JSXOpeningElement}
+ * @returns {ESTreeJSX.TSRXJSXOpeningElement}
  */
 export function jsx_opening_element(
 	name,
@@ -1156,7 +1160,7 @@ export function jsx_opening_element(
 	type_arguments = undefined,
 	loc_info,
 ) {
-	const node = /** @type {ESTreeJSX.JSXOpeningElement} */ ({
+	const node = /** @type {ESTreeJSX.TSRXJSXOpeningElement} */ ({
 		type: 'JSXOpeningElement',
 		name,
 		attributes,
@@ -1173,10 +1177,10 @@ export function jsx_opening_element(
  *
  * @param {ESTreeJSX.TSRXJSXClosingElement['name']} name
  * @param {AST.NodeWithLocation} [loc_info]
- * @returns {ESTreeJSX.JSXClosingElement}
+ * @returns {ESTreeJSX.TSRXJSXClosingElement}
  */
 export function jsx_closing_element(name, loc_info) {
-	const node = /** @type {ESTreeJSX.JSXClosingElement} */ ({
+	const node = /** @type {ESTreeJSX.TSRXJSXClosingElement} */ ({
 		type: 'JSXClosingElement',
 		name,
 		metadata: { path: [] },
@@ -1191,11 +1195,14 @@ export function jsx_closing_element(name, loc_info) {
  * derived from an existing source node, use `jsx_element` (which spreads
  * the source's name and metadata).
  *
- * @param {ESTreeJSX.JSXOpeningElement} opening_element
- * @param {ESTreeJSX.JSXClosingElement | null} [closing_element]
- * @param {ESTreeJSX.JSXElement['children']} [children]
+ * Carries the parser's widened TSRX shape (dynamic-tag names, lowered template
+ * children) — see {@link jsx_element}.
+ *
+ * @param {ESTreeJSX.TSRXJSXOpeningElement} opening_element
+ * @param {ESTreeJSX.TSRXJSXClosingElement | null} [closing_element]
+ * @param {AST.TSRXJSXElement['children']} [children]
  * @param {AST.NodeWithLocation} [loc_info]
- * @returns {ESTreeJSX.JSXElement}
+ * @returns {AST.TSRXJSXElement}
  */
 export function jsx_element_fresh(
 	opening_element,
@@ -1203,7 +1210,7 @@ export function jsx_element_fresh(
 	children = [],
 	loc_info,
 ) {
-	const node = /** @type {ESTreeJSX.JSXElement} */ ({
+	const node = /** @type {AST.TSRXJSXElement} */ ({
 		type: 'JSXElement',
 		openingElement: opening_element,
 		closingElement: closing_element,

package/types/helpers.d.ts

@@ -1,6 +1,5 @@
 export type RequireAllOrNone<T, K extends keyof T> =
-	| (T & Required<Pick<T, K>>)
-	| (T & { [P in K]?: never });
+	(T & Required<Pick<T, K>>) | (T & { [P in K]?: never });
 
 export type RequiredPresent<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
 

package/types/index.d.ts

@@ -5,6 +5,7 @@ import type { Parse } from './parse.js';
 import type * as ESRap from 'esrap';
 import type { Position } from 'acorn';
 import type { RequireAllOrNone } from './helpers';
+import type { Context as ZimmerframeContext } from 'zimmerframe';
 import type {
 	JsxPlatform,
 	JsxPlatformHooks,
@@ -27,7 +28,8 @@ export { createJsxTransform };
 /** Result of extracting a branch body into a generated helper component. */
 export interface JsxHelperComponent {
 	setup_statements: AST.Statement[];
-	component_element: ESTreeJSX.JSXElement;
+	/** The parser's widened TSRX element shape — see {@link AST.TSRXJSXElement}. */
+	component_element: AST.TSRXJSXElement;
 }
 
 export function collectStyleRefAttributes(
@@ -86,7 +88,7 @@ export interface CompileOptions {
 }
 
 export type NameSpace = 'html' | 'svg' | 'mathml';
-interface BaseNodeMetaData {
+export interface BaseNodeMetaData {
 	scoped?: boolean;
 	path: AST.Node[];
 	has_template?: boolean;
@@ -105,6 +107,8 @@ interface BaseNodeMetaData {
 	commentContainerId?: number;
 	parenthesized?: boolean;
 	native_tsrx?: boolean;
+	/** The function's body came from a `@{ … }` code block that has been lowered. */
+	native_tsrx_body?: boolean;
 	tsrx_generated_wrapper?: boolean;
 	native_tsrx_template_block?: boolean;
 	dynamicElement?: boolean;
@@ -155,9 +159,19 @@ interface BaseNodeMetaData {
 	disable_verification?: boolean;
 	extra_source_mappings?: AST.NodeWithLocation[];
 	generated_setup_declarations?: AST.Statement[];
+	/** Helper components lifted out of a component; read back by `expand_component_helpers`. */
+	generated_helpers?: AST.Statement[];
+	/** Module-level static JSX hoisted out of a component. */
+	generated_statics?: AST.Statement[];
 	has_unmappable_value?: boolean;
 	synthetic_ref?: boolean;
 	tsrx_reactive_block?: boolean;
+	/** Generated dynamic-tag render-block closure, not a user component boundary. */
+	tsrx_dynamic_wrapper?: boolean;
+	/** Scoped-class definition sites, for editor definitions/hover on `style.x`. */
+	styleClasses?: StyleClasses;
+	/** Top-level scoped classes collected while pruning the component's CSS. */
+	topScopedClasses?: TopScopedClasses;
 	vapor_pending_fallback?: ESTreeJSX.JSXRenderNode;
 	lazy_param_binding_mappings?: Array<{
 		source: AST.Identifier;
@@ -165,7 +179,7 @@ interface BaseNodeMetaData {
 	}>;
 }
 
-interface FunctionMetaData extends BaseNodeMetaData {
+export interface FunctionMetaData extends BaseNodeMetaData {
 	native_tsrx?: boolean;
 	native_tsrx_function?: boolean;
 	is_method?: boolean;
@@ -173,11 +187,7 @@ interface FunctionMetaData extends BaseNodeMetaData {
 	has_lazy_descendants?: boolean;
 	/** The component's extracted `<style>` stylesheet (element-level scoped-class info lives on BaseNodeMetaData's `css`). */
 	component_css?: AST.CSS.StyleSheet | null;
-	/** Top-level scoped classes collected while pruning the component's CSS. */
-	topScopedClasses?: TopScopedClasses;
 	synthetic_children?: boolean;
-	generated_helpers?: AST.Statement[];
-	generated_statics?: AST.Statement[];
 }
 
 // Strip parent, loc, and range from TSESTree nodes to match @sveltejs/acorn-typescript output
@@ -310,6 +320,7 @@ declare module 'estree' {
 	// Include TypeScript node types and TSRX-specific nodes in NodeMap
 	interface NodeMap {
 		JSXSpreadChild: ESTreeJSX.JSXSpreadChild;
+		TSRXImportDeclaration: TSRXImportDeclaration;
 		TSRXJSXElement: TSRXJSXElement;
 		TSRXJSXFragment: TSRXJSXFragment;
 		TSRXJSXOpeningElement: ESTreeJSX.TSRXJSXOpeningElement;
@@ -404,6 +415,8 @@ declare module 'estree' {
 		test: AST.Expression;
 		consequent: AST.Statement;
 		alternate: AST.Statement | null;
+		/** Span of the `@else` keyword; only present when `alternate` is. */
+		alternateKeyword?: AST.NodeWithLocation | null;
 		metadata: BaseNodeMetaData;
 	}
 
@@ -414,6 +427,11 @@ declare module 'estree' {
 		index?: AST.Identifier | null;
 		key?: AST.Expression | null;
 		empty?: AST.BlockStatement | null;
+		/**
+		 * Span of the `@empty` keyword; only present when `empty` is. The clause's
+		 * block starts at its `{`, so this is the only pointer to the keyword text.
+		 */
+		emptyKeyword?: AST.NodeWithLocation | null;
 		metadata: BaseNodeMetaData;
 	}
 
@@ -460,10 +478,7 @@ declare module 'estree' {
 
 	/** A `@if`/`@for`/`@switch`/`@try` template control-flow directive. */
 	type JSXTemplateDirective =
-		| JSXIfExpression
-		| JSXForExpression
-		| JSXSwitchExpression
-		| JSXTryExpression;
+		JSXIfExpression | JSXForExpression | JSXSwitchExpression | JSXTryExpression;
 
 	/** A statement-form template directive after its parser node has been retyped. */
 	type JSXTemplateStatement =
@@ -524,16 +539,27 @@ declare module 'estree' {
 	interface TryStatement {
 		statementType?: 'TryStatement';
 		pending?: AST.BlockStatement | null;
+		/** Span of the `@pending` keyword; only present when `pending` is. */
+		pendingKeyword?: AST.NodeWithLocation | null;
+		/** Span of the `@catch` keyword; only present when `handler` is. */
+		handlerKeyword?: AST.NodeWithLocation | null;
 	}
 
 	interface IfStatement {
 		statementType?: 'IfStatement';
+		/** Span of the `@else` keyword; only present when `alternate` is. */
+		alternateKeyword?: AST.NodeWithLocation | null;
 	}
 
 	interface SwitchStatement {
 		statementType?: 'SwitchStatement';
 	}
 
+	interface SwitchCase {
+		/** Span of the arm's `@case`/`@default` keyword. */
+		keyword?: AST.NodeWithLocation | null;
+	}
+
 	interface CatchClause {
 		resetParam?: AST.Pattern | null;
 	}
@@ -543,10 +569,19 @@ declare module 'estree' {
 		index?: AST.Identifier | null;
 		key?: AST.Expression | null;
 		empty?: AST.BlockStatement | null;
+		/** Span of the `@empty` keyword; only present when `empty` is. */
+		emptyKeyword?: AST.NodeWithLocation | null;
 	}
 
 	interface ImportDeclaration {
 		importKind: TSESTree.ImportDeclaration['importKind'];
+		phase?: 'defer' | null;
+	}
+	interface TSRXImportDeclaration extends Omit<ImportDeclaration, 'source'> {
+		source: AST.Literal | AST.Identifier;
+	}
+	interface ImportExpression {
+		phase?: 'defer' | null;
 	}
 	interface ImportSpecifier {
 		importKind: TSESTree.ImportSpecifier['importKind'];
@@ -788,8 +823,21 @@ declare module 'estree-jsx' {
 	/** A node that can be returned from a platform hook into a JSX render slot. */
 	type JSXRenderNode = AST.Expression | JSXExpressionContainer | JSXText | JSXSpreadChild;
 
-	/** A JSX child produced by the transform's render-body lowering. */
-	type JSXRenderChild = JSXElement | JSXFragment | JSXExpressionContainer | JSXText;
+	/**
+	 * A JSX child produced by the transform's render-body lowering. Elements and
+	 * fragments carry the parser's widened TSRX shape, which plain estree-jsx
+	 * elements are assignable to.
+	 */
+	type JSXRenderChild = AST.TSRXJSXElement | AST.TSRXJSXFragment | JSXExpressionContainer | JSXText;
+
+	/**
+	 * A JSX child that evaluates to a single expression, so it can be captured
+	 * into a `const` at its source position.
+	 */
+	type JSXCapturableChild =
+		| AST.TSRXJSXElement
+		| AST.TSRXJSXFragment
+		| (JSXExpressionContainer & { expression: AST.Expression });
 
 	/** An attribute accepted by and emitted from the shared JSX transformer. */
 	type JSXAttributeNode = JSXAttribute | JSXSpreadAttribute;
@@ -802,9 +850,7 @@ declare module 'estree-jsx' {
 
 	/** A child accepted while TSRX JSX is being lowered to standard ESTree JSX. */
 	type JSXTransformChild =
-		| JSXElement['children'][number]
-		| AST.TSRXJSXElement
-		| AST.TSRXJSXFragment;
+		JSXElement['children'][number] | AST.TSRXJSXElement | AST.TSRXJSXFragment;
 
 	interface JSXAttribute {
 		shorthand: boolean;
@@ -1391,7 +1437,7 @@ export interface AnalysisResult {
 	component_metadata: Array<{ id: string }>;
 	metadata: {
 		serverImportsPresent: boolean;
-		serverImportDeclarations: AST.ImportDeclaration[];
+		serverImportDeclarations: AST.TSRXImportDeclaration[];
 		serverModule: AST.TSModuleDeclaration | null;
 	};
 	errors: CompileError[];
@@ -1671,6 +1717,14 @@ export interface TransformClientState extends BaseState {
 	ref_target_type?: AST.TypeNode;
 }
 
+/** Accumulator for the helper components and statics a component lift produces. */
+export interface JsxHelperState {
+	base_name: string;
+	next_id: number;
+	helpers: AST.Statement[];
+	statics: AST.Statement[];
+}
+
 /** Override zimmerframe types and provide our own */
 /**
  * Where stock `@types/estree-jsx` and the TSRX parser shapes share a `type`
@@ -1740,6 +1794,13 @@ export type VisitorClientContext = TransformClientContext & {
 	value_position?: boolean;
 };
 
+/**
+ * The zimmerframe visitor context the JSX transform's visitors receive. Walked
+ * over the `Node` union rather than `Program`, since only that union admits a
+ * visitor per node type.
+ */
+export type JsxVisitorContext = ZimmerframeContext<AST.Node, JsxTransformContext>;
+
 /**
  * Delegated event result
  */
@@ -1758,6 +1819,16 @@ export type TopScopedClasses = Map<
 
 export type StyleClasses = Map<string, AST.MemberExpression['property']>;
 
+/**
+ * The scoped-CSS work for one native TSRX node: its stylesheet, the `style.x`
+ * ref attributes that reference it, and a hash-annotated copy of the node.
+ */
+export interface JsxStyleContext {
+	css: AST.CSS.StyleSheet;
+	style_refs: ESTreeJSX.JSXAttribute[];
+	fragment: AST.NativeTSRXNode;
+}
+
 /**
  * Event handling types
  */

package/types/jsx-platform.d.ts

@@ -1,7 +1,7 @@
 import type * as AST from 'estree';
 import type * as ESTreeJSX from 'estree-jsx';
 import type { RawSourceMap } from 'source-map';
-import type { CompileError, JsxHelperComponent } from './index';
+import type { CompileError, JsxHelperComponent, JsxHelperState } from './index';
 
 /**
  * Result returned by a JSX platform transform (React, Preact, Solid).
@@ -53,12 +53,7 @@ export interface JsxTransformContext {
 	stylesheets: AST.CSS.StyleSheet[];
 	type_only_style_anchors: AST.Statement[];
 	module_scoped_hook_components: boolean;
-	helper_state: {
-		base_name: string;
-		next_id: number;
-		helpers: AST.Statement[];
-		statics: AST.Statement[];
-	} | null;
+	helper_state: JsxHelperState | null;
 	hook_helpers_enabled: boolean;
 	available_bindings: Map<string, AST.Identifier>;
 	lazy_next_id: number;
@@ -75,6 +70,12 @@ export interface JsxTransformContext {
 	comments: AST.CommentWithLocation[] | undefined;
 	/** True when emitting a type-only virtual TSX module; preserves lazy destructuring patterns. */
 	typeOnly: boolean;
+	/**
+	 * True when generated nodes may be anchored on the directive keyword that
+	 * produced them. Off by default; the emitted code and its source map are
+	 * unchanged when clear.
+	 */
+	inspect: boolean;
 }
 
 /**
@@ -121,6 +122,15 @@ export interface JsxTransformOptions {
 	 * bindings.
 	 */
 	typeOnly?: boolean;
+	/**
+	 * Anchor generated nodes on the directive keyword that produced them, so
+	 * navigation tooling can trace an authored `@for` / `@empty` to the code it
+	 * became. Off by default — a directive is lowered away entirely, so nothing
+	 * in the source map otherwise reaches its keyword. With the flag clear the
+	 * output bytes and every mapping derived from them are unaffected, which is
+	 * why the editor pipeline never asks for it.
+	 */
+	inspect?: boolean;
 }
 
 /**
@@ -303,7 +313,7 @@ export interface JsxPlatformHooks {
 	 * otherwise statically safe. Targets can use this to keep runtime-sensitive
 	 * JSX, such as component invocations, inside render/setup execution.
 	 */
-	canHoistStaticNode?: (node: ESTreeJSX.JSXElement, ctx: JsxTransformContext) => boolean;
+	canHoistStaticNode?: (node: AST.TSRXJSXElement, ctx: JsxTransformContext) => boolean;
 	/**
 	 * Custom validation for a component body that uses top-level `await`.
 	 * Default: enforce `validation.requireUseServerForAwait`. Solid rejects