@tsrx/core 0.1.59 → 0.1.61

package/README.md

@@ -5,9 +5,10 @@ infrastructure that powers TypeScript UI frameworks.
 
 `@tsrx/core` is framework-agnostic. It provides the parser, AST definitions, scope
 analysis, and code-generation utilities needed to target _any_ framework runtime
-using Ripple's syntax. Framework-specific packages (such as
-[`@tsrx/ripple`](../tsrx-ripple)) build on top of `@tsrx/core` to produce the
-runtime output for Ripple.
+using TSRX syntax. Framework-specific packages—such as
+[`@tsrx/react`](../tsrx-react), [`@tsrx/solid`](../tsrx-solid), and the external
+[`@tsrx/ripple`](https://github.com/Ripple-TS/ripple)—build on `@tsrx/core` to
+produce target-runtime output.
 
 ## What is TSRX?
 

package/package.json

@@ -3,11 +3,11 @@
   "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Ripple-TS/ripple.git",
+    "url": "git+https://github.com/tsrx-org/tsrx.git",
     "directory": "packages/tsrx"
   },
   "exports": {

package/src/analyze/prune.js

@@ -15,6 +15,8 @@ const BACKWARD = 1;
 // since the code is synchronous, this is safe
 /** @type {string} */
 let css_hash;
+/** @type {string} */
+let css_region_hash;
 /** @type {StyleClasses} */
 let style_identifier_classes;
 /** @type {TopScopedClasses} */
@@ -300,6 +302,7 @@ function apply_selector(relative_selectors, rule, element, direction) {
 								start: selector.start,
 								end: selector.end,
 								selector: selector,
+								regionHash: css_region_hash,
 							});
 						}
 					}
@@ -1107,10 +1110,12 @@ function rule_has_animation(rule) {
  * @param {AST.TSRXElementNode} element
  * @param {StyleClasses} styleClasses
  * @param {TopScopedClasses} topScopedClasses
+ * @param {string} [regionHash]
  * @return {void}
  */
-export function prune_css(css, element, styleClasses, topScopedClasses) {
+export function prune_css(css, element, styleClasses, topScopedClasses, regionHash = css.hash) {
 	css_hash = css.hash;
+	css_region_hash = regionHash;
 	style_identifier_classes = styleClasses;
 	top_scoped_classes = topScopedClasses;
 
@@ -1152,6 +1157,7 @@ export function prune_css(css, element, styleClasses, topScopedClasses) {
 							start: class_selector.start,
 							end: class_selector.end,
 							selector: class_selector,
+							regionHash: css_region_hash,
 						});
 					}
 				}

package/src/constants.js

@@ -4,7 +4,7 @@ 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.
+// in a target runtime's constants.
 export const ROOT_CONTROLLED = 1 << 4;
 export const TEMPLATE_SVG_NAMESPACE = 1 << 5;
 export const TEMPLATE_MATHML_NAMESPACE = 1 << 6;

package/src/errors.js

@@ -57,12 +57,7 @@ export function error(message, filename, node, errors, comments, code) {
  */
 function is_error_suppress_comment(comment) {
 	const text = comment.value.trim();
-	return (
-		text.startsWith('@tsrx-ignore') ||
-		text.startsWith('@tsrx-expect-error') ||
-		text.startsWith('@ripple-ignore') ||
-		text.startsWith('@ripple-expect-error')
-	);
+	return text.startsWith('@tsrx-ignore') || text.startsWith('@tsrx-expect-error');
 }
 
 /**

package/src/plugin.js

@@ -246,7 +246,7 @@ function looks_like_generic_arrow(input, pos) {
 }
 
 /**
- * Acorn parser plugin for Ripple syntax extensions.
+ * Acorn parser plugin for TSRX syntax extensions.
  * Adds support for: native TSRX templates, &[]/&{} lazy destructuring,
  * submodule imports, TSRX directives, and enhanced JSX handling.
  *
@@ -358,7 +358,7 @@ export function TSRXPlugin(config) {
 			constructor(options, input) {
 				super(options, input);
 				this.context ??= [b_stat];
-				const tsrx_options = options?.tsrxOptions ?? options?.rippleOptions;
+				const tsrx_options = options?.tsrxOptions;
 				this.#collect = tsrx_options?.collect === true || tsrx_options?.loose === true;
 				this.#loose = tsrx_options?.loose === true;
 				this.#errors = tsrx_options?.errors;
@@ -2222,7 +2222,7 @@ export function TSRXPlugin(config) {
 			 * is exposed twice: verbatim on `content`, and as a single `JSXText` child so
 			 * generic element paths (factory targets, static hoisting, printers) emit the
 			 * body without knowing about raw-text elements. Consumers that handle
-			 * `content` directly (the Ripple transforms, the prettier plugin) must skip
+			 * `content` directly (target transforms, the Prettier plugin) must skip
 			 * the children instead of emitting both.
 			 *
 			 * @param {ESTreeJSX.TSRXJSXOpeningElement & AST.NodeWithLocation} open
@@ -2956,7 +2956,7 @@ export function TSRXPlugin(config) {
 			}
 
 			/**
-			 * Get token from character code - handles Ripple-specific tokens
+			 * Get token from character code - handles TSRX-specific tokens
 			 * @type {Parse.Parser['getTokenFromCode']}
 			 */
 			getTokenFromCode(code) {

package/src/transform/jsx/helpers.js

@@ -41,7 +41,7 @@ export function is_empty_jsx_fragment(node) {
 }
 
 /**
- * Match Ripple's transform path metadata shape: every node seen by the walker
+ * Maintain TSRX transform path metadata: every node seen by the walker
  * carries its current ancestor path for downstream CSS pruning and mapping
  * helpers.
  *

package/src/transform/jsx/index.js

@@ -268,7 +268,7 @@ function wrap_in_native_tsrx_fragment(node) {
 }
 
 /**
- * An AUTHORED `<> … </>` fragment (not a compiler-generated wrapper, nor a Ripple
+ * An AUTHORED `<> … </>` fragment (not a compiler-generated wrapper, nor a TSRX
  * code-block-chain wrapper). These are kept verbatim in the output instead of
  * being unwrapped to their single child.
  * @param {AST.Node | null | undefined} node
@@ -728,9 +728,24 @@ export function createJsxTransform(platform) {
 				// hooks can inspect the original JSX child shape.
 				const raw_children = node_children(node).map((child) => ({ ...child }));
 				const inner = /** @type {AST.TSRXJSXElement} */ (next() ?? node);
+				const in_jsx_child = in_jsx_child_context(path);
 				const hook = platform.hooks?.transformElement;
-				if (hook) return hook(inner, state, raw_children);
-				return to_jsx_element(inner, state, raw_children, in_jsx_child_context(path));
+				const produced = hook
+					? hook(inner, state, raw_children)
+					: to_jsx_element(inner, state, raw_children, in_jsx_child);
+				// A host element carrying `ref` plus a spread lowers to a generated
+				// `let X = __normalize_spread_props_for_ref_attr(…)` that rides on the
+				// element's metadata for a later pass to hoist. Only the render-block
+				// statement builder and the native-directive path hoist it, so an
+				// element in plain-JS expression position — a ternary arm, a concise
+				// arrow body, a declarator init, a callback body, an attribute value, an
+				// array element — reaches neither: the declaration is dropped while the
+				// rewritten attributes still reference the name, and the type-only print
+				// carries an undefined identifier (TS2304). Wrap it in the same IIFE the
+				// native-directive path already uses.
+				return state.typeOnly && produced.type !== 'JSXSpreadChild' && produced.type !== 'JSXText'
+					? wrap_jsx_setup_declarations(produced, in_jsx_child)
+					: produced;
 			},
 
 			JSXExpressionContainer(node, { next, state }) {
@@ -791,7 +806,7 @@ export function createJsxTransform(platform) {
 					return visited;
 				}
 				const is_component = is_component_like_jsx_name(visited.name);
-				return b.jsx_opening_element(
+				const lowered = b.jsx_opening_element(
 					visited.name,
 					merge_duplicate_refs(
 						normalize_host_ref_spreads(visited.attributes || [], !is_component, transform_context),
@@ -801,6 +816,17 @@ export function createJsxTransform(platform) {
 					visited.typeArguments,
 					has_location(visited) ? visited : undefined,
 				);
+				// `normalize_host_ref_spreads` is NOT idempotent: run twice it reads the
+				// `ref={[authored, __spread_props1.ref]}` array it just produced as an
+				// AUTHORED ref and lowers again, emitting a second helper binding and a
+				// nested ref array. The attribute list cannot answer "already lowered"
+				// on its own — `merge_duplicate_refs` rebuilds the merged `ref` without
+				// the `synthetic_ref` marker — so record it on the element instead.
+				lowered.metadata = {
+					...(lowered.metadata || {}),
+					host_ref_spread_lowered: true,
+				};
+				return lowered;
 			},
 		});
 
@@ -1065,6 +1091,7 @@ function inject_dynamic_import(program, transform_context) {
  * @param {AST.CSS.StyleSheet} css
  * @param {TransformContext} transform_context
  * @param {boolean} [export_top_scoped_classes]
+ * @param {string} [region_hash]
  * @returns {void}
  */
 function apply_css_definition_metadata(
@@ -1072,6 +1099,7 @@ function apply_css_definition_metadata(
 	css,
 	transform_context,
 	export_top_scoped_classes = false,
+	region_hash = css.hash,
 ) {
 	analyze_css(css);
 
@@ -1082,7 +1110,7 @@ function apply_css_definition_metadata(
 
 	const prune = () => {
 		for (const element of elements) {
-			prune_css(css, element, style_classes, top_scoped_classes);
+			prune_css(css, element, style_classes, top_scoped_classes, region_hash);
 		}
 	};
 
@@ -2291,19 +2319,20 @@ function node_contains_native_tsrx_template(node) {
 
 /**
  * @param {AST.NativeTSRXNode} node
- * @returns {AST.CSS.StyleSheet | null}
+ * @param {boolean} allow_multiple
+ * @returns {AST.CSS.StyleSheet[] | null}
  */
-function collect_tsrx_stylesheet(node) {
+function collect_tsrx_stylesheets(node, allow_multiple) {
 	/** @type {AST.CSS.StyleSheet[]} */
 	const styles = [];
 	collect_style_elements(node_children(node), styles);
 
 	if (styles.length === 0) return null;
-	if (styles.length > 1) {
+	if (styles.length > 1 && !allow_multiple) {
 		throw new Error('TSRX fragments can only have one style tag');
 	}
 
-	return styles[0];
+	return styles;
 }
 
 /**
@@ -2312,14 +2341,37 @@ function collect_tsrx_stylesheet(node) {
  * @returns {JsxStyleContext | null}
  */
 function prepare_tsrx_fragment_styles(node, transform_context) {
-	const css = collect_tsrx_stylesheet(node);
-	if (!css) return null;
-
+	// Type-only output must stay analyzable: a throw here makes language hosts
+	// (tsrx-tsc, editors) fall back to presenting the RAW source as the virtual
+	// TSX, so every CSS brace in the file becomes a TSX parse error. Platforms
+	// whose runtime dialect allows one scope to split its CSS across several
+	// `<style>` tags are valid input here, and platforms that forbid it still
+	// report the rule through their own runtime compiler.
+	const sheets = collect_tsrx_stylesheets(node, transform_context.typeOnly);
+	if (!sheets) return null;
+
+	const css = sheets[0];
 	const style_refs = collect_style_ref_attributes(node);
-	// `prune_css` inside marks the matching selectors as used/scoped; selectors
-	// that match no element render commented out, like the Ripple target.
-	apply_css_definition_metadata(node, css, transform_context, style_refs.length > 0);
-	transform_context.stylesheets.push(css);
+	// A component scope keeps ONE hash even when its CSS is split across
+	// several `<style>` tags: rebase every sheet onto the first sheet's hash
+	// before scoping, so selector rewriting and the DOM hash annotation below
+	// agree. `apply_css_definition_metadata` accumulates into the component's
+	// `styleClasses`/`topScopedClasses` metadata, so per-sheet calls compose
+	// into one class map for style refs.
+	for (const sheet of sheets) {
+		const region_hash = sheet.hash;
+		sheet.hash = css.hash;
+		// `prune_css` inside marks the matching selectors as used/scoped; selectors
+		// that match no element render commented out, matching target behavior.
+		apply_css_definition_metadata(
+			node,
+			sheet,
+			transform_context,
+			style_refs.length > 0,
+			region_hash,
+		);
+		transform_context.stylesheets.push(sheet);
+	}
 	const fragment = annotate_tsrx_with_hash(
 		node,
 		css.hash,
@@ -6120,8 +6172,16 @@ function transform_element_attributes_dispatch(attrs, transform_context, element
 	}
 	const hook = transform_context.platform.hooks?.transformElementAttributes;
 	const result = hook ? hook(attrs, transform_context, element) : attrs;
+	// An element in plain-JS expression position reaches BOTH lowering sites —
+	// the JSXOpeningElement visitor above and this dispatch — so without the
+	// marker its host ref/spread is lowered twice. Scoped to the type-only
+	// print: runtime emit for the other platforms sharing this transform keeps
+	// its existing output.
+	const already_lowered =
+		transform_context.typeOnly &&
+		element?.openingElement?.metadata?.host_ref_spread_lowered === true;
 	return merge_duplicate_refs(
-		normalize_host_ref_spreads(result, !is_component, transform_context),
+		already_lowered ? result : normalize_host_ref_spreads(result, !is_component, transform_context),
 		transform_context,
 	);
 }

package/src/transform/segments.js

@@ -625,7 +625,7 @@ export function convert_source_map_to_mappings(
 				if (node.name && node.loc) {
 					/** @type {MappingToken} */
 					let token;
-					// Check if this identifier was changed in metadata (e.g., #Map -> RippleMap)
+					// Check if this identifier was changed in metadata (for example, #Map -> ReactiveMap)
 					// Or if it was capitalized during transformation
 					if (node.metadata?.source_name) {
 						token = {
@@ -885,7 +885,7 @@ export function convert_source_map_to_mappings(
 										definition: {
 											description: `CSS class selector for '.${name}'`,
 											location: {
-												embeddedId: get_style_region_id(css.hash),
+												embeddedId: get_style_region_id(cssLocation.regionHash ?? css.hash),
 												start: cssLocation.start,
 												end: cssLocation.end,
 											},
@@ -933,7 +933,7 @@ export function convert_source_map_to_mappings(
 				// text itself — and get_mapping_from_node just takes the first, so its generated length
 				// spans the wrong region and the editor can't map a completion's edit back to source
 				// (it then drops the item). The token resolves to the position whose generated text
-				// matches the node's value, giving a well-formed same-length mapping. Ripple keeps text
+				// matches the node's value, giving a well-formed same-length mapping. TSRX keeps text
 				// verbatim in to_ts, so `source` and `generated` are identical. Other text stays unmapped.
 				if (node.loc && typeof node.value === 'string' && node.value.trimStart().startsWith('@')) {
 					tokens.push({
@@ -1299,14 +1299,14 @@ export function convert_source_map_to_mappings(
 				);
 				return;
 			} else if (node.type === 'ForOfStatement' || node.type === 'ForInStatement') {
-				// Visit in source order: left, right, index (Ripple-specific), body
+				// Visit in source order: left, right, TSRX index extension, body
 				if (node.left) {
 					visit(node.left);
 				}
 				if (node.right) {
 					visit(node.right);
 				}
-				// Ripple-specific: index variable
+				// TSRX index extension: index variable
 				if (/** @type {AST.ForOfStatement} */ (node).index) {
 					visit(/** @type {AST.Node} */ (/** @type {AST.ForOfStatement} */ (node).index));
 				}

package/types/index.d.ts

@@ -352,7 +352,7 @@ declare module 'estree' {
 		lazy?: boolean;
 	}
 
-	// Ripple analysis may mark a whole member expression as tracked metadata.
+	// Target analysis may mark a whole member expression as tracked metadata.
 	interface MemberExpression {
 		tracked?: boolean;
 	}
@@ -425,7 +425,7 @@ declare module 'estree' {
 		 * `#parseScriptElement` (analogous to {@link JSXStyleElement.css}). Present only
 		 * on `<script>` elements that have a body. The parser also mirrors the body as
 		 * a single `JSXText` child so generic element consumers emit it; consumers that
-		 * handle `content` directly (the Ripple transforms, the prettier plugin, the
+		 * handle `content` directly (target transforms, the Prettier plugin, the
 		 * type-only editor output) skip the children instead of emitting both.
 		 */
 		content?: string;
@@ -989,6 +989,8 @@ declare module 'estree-jsx' {
 	interface JSXOpeningElement {
 		metadata: BaseNodeMetaData & {
 			native_tsrx_pretransformed?: boolean;
+			/** Type-only host ref/spread normalization has already run for this element. */
+			host_ref_spread_lowered?: boolean;
 		};
 	}
 
@@ -1628,7 +1630,7 @@ export interface Binding {
 	/** Additional metadata for this binding */
 	metadata: {
 		pattern?: AST.Identifier;
-		is_ripple_object?: boolean;
+		is_tsrx_object?: boolean;
 		is_template_value?: boolean;
 		lazy_array_source?: string;
 		lazy_array_index?: number;
@@ -2090,6 +2092,8 @@ export type TopScopedClasses = Map<
 		start: number;
 		end: number;
 		selector: AST.CSS.ClassSelector;
+		/** Source `<style>` region for editor definition navigation. */
+		regionHash?: string;
 	}
 >;
 
@@ -2228,7 +2232,7 @@ export type RuntimeImportMode = 'compiler' | 'direct';
 
 /**
  * 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
+ * Targets that need extra knobs (for example Ripple's `mode`/`dev`/`hmr`, Preact's
  * `suspenseSource`) intersect their own option type with this base when
  * declaring their `compile` export.
  */
@@ -2252,7 +2256,7 @@ export interface BaseCompileOptions {
  * @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)
+ *   targets may add fields (for example Ripple's deprecated `js` compatibility field)
  *   via intersection.
  */
 export type CompileFn<

package/types/jsx-platform.d.ts

@@ -158,7 +158,7 @@ export interface JsxTransformOptions {
 export interface JsxPlatformHooks {
 	/**
 	 * Per-statement control-flow rewrites. Each hook receives the original
-	 * Ripple statement (with children already walked) and returns a JSX
+	 * TSRX statement (with children already walked) and returns a JSX
 	 * child (or an expression container wrapping one).
 	 */
 	controlFlow?: {
@@ -205,7 +205,7 @@ export interface JsxPlatformHooks {
 	 */
 	injectImports?: (program: AST.Program, ctx: JsxTransformContext, suspenseSource: string) => void;
 	/**
-	 * Transform a Ripple element's parser-native JSX attributes. The result
+	 * Transform a TSRX element's parser-native JSX attributes. The result
 	 * is passed through the shared multi-`ref` merge. Platforms that own a
 	 * `transformElement` hook (e.g. Solid) run their own attribute pass inside
 	 * that hook.
@@ -343,7 +343,7 @@ export interface JsxPlatformHooks {
 
 /**
  * A JSX platform descriptor is the parameter to `createJsxTransform`. It
- * declares how to render a Ripple AST as valid TSX for the target platform
+ * declares how to render a TSRX AST as valid TSX for the target platform
  * (React, Preact, Solid). The shared transformer in `@tsrx/core` reads this
  * descriptor at each platform-specific decision point instead of branching
  * on the platform name.
@@ -432,7 +432,7 @@ export interface JsxPlatform {
 
 	jsx: {
 		/**
-		 * Rewrite Ripple's `class` attribute to `className` for legacy targets
+		 * Rewrite TSRX's `class` attribute to `className` for targets
 		 * that require it. First-party targets keep authored `class`.
 		 */
 		rewriteClassAttr: boolean;
@@ -527,7 +527,7 @@ export interface JsxPlatform {
 
 /**
  * Build a `transform()` function for a specific JSX platform. The returned
- * function takes a parsed Ripple AST and produces a TSX module plus source
+ * function takes a parsed TSRX AST and produces a TSX module plus source
  * map and optional CSS.
  */
 export function createJsxTransform(

package/types/parse.d.ts

@@ -193,12 +193,6 @@ export namespace Parse {
 			errors: CoreCompiler.CompileError[] | undefined;
 			filename: string | undefined;
 		};
-		rippleOptions?: {
-			collect: boolean;
-			loose: boolean;
-			errors: CoreCompiler.CompileError[] | undefined;
-			filename: string | undefined;
-		};
 		// The type has "latest" but it's converted to 1e8 at runtime
 		// and if (ecmaVersion >= 2015) { ecmaVersion -= 2009 }
 		// so we're making it always a number to reflect the runtime values
@@ -1666,7 +1660,7 @@ export namespace Parse {
 		/**
 		 * Check if a local export refers to a defined variable.
 		 * Acorn's default implementation only checks the top-level module scope,
-		 * but Ripple overrides this to check all scopes (for submodules).
+		 * but TSRX overrides this to check all scopes (for submodules).
 		 * @param id The identifier being exported
 		 */
 		checkLocalExport(id: AST.Identifier): void;