ripple 0.2.177 → 0.2.179

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.2.177",
+  "version": "0.2.179",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -80,9 +80,10 @@
     "@types/estree-jsx": "^1.0.5",
     "@types/node": "^24.3.0",
     "typescript": "^5.9.2",
-    "@volar/language-core": "~2.4.23"
+    "@volar/language-core": "~2.4.23",
+    "vscode-languageserver-types": "^3.17.5"
   },
   "peerDependencies": {
-    "ripple": "0.2.177"
+    "ripple": "0.2.179"
   }
 }

package/src/compiler/index.d.ts

@@ -3,6 +3,7 @@ import type {
 	CodeInformation as VolarCodeInformation,
 	Mapping as VolarMapping,
 } from '@volar/language-core';
+import type { DocumentHighlightKind } from 'vscode-languageserver-types';
 
 // ============================================================================
 // Compiler API Exports
@@ -22,7 +23,28 @@ export interface CompileResult {
 	css: string;
 }
 
-export interface CustomMappingData {
+export interface PluginActionOverrides {
+	/** Whether to enable word document highlighting for this mapping */
+	wordHighlight?: {
+		kind: DocumentHighlightKind;
+	};
+	/** TypeScript diagnostic codes to suppress for this mapping */
+	suppressedDiagnostics?: number[];
+	/** Custom hover documentation for this mapping, false to disable */
+	hover?:
+		| {
+				contents: string;
+		  }
+		| false;
+	/** Custom definition info for this mapping, false to disable */
+	definition?:
+		| {
+				description: string;
+		  }
+		| false;
+}
+
+export interface CustomMappingData extends PluginActionOverrides {
 	generatedLengths: number[];
 }
 
@@ -34,9 +56,6 @@ export interface CodeMapping extends VolarMapping<MappingData> {
 	data: MappingData;
 }
 
-/**
- * Result of Volar mappings compilation
- */
 export interface VolarMappingsResult {
 	code: string;
 	mappings: CodeMapping[];
@@ -47,42 +66,30 @@ export interface VolarMappingsResult {
 /**
  * Compilation options
  */
-export interface CompileOptions {
-	/** Compilation mode: 'client' or 'server' */
+
+interface SharedCompileOptions {
+	minify_css?: boolean;
+}
+export interface CompileOptions extends SharedCompileOptions {
 	mode?: 'client' | 'server';
 }
 
 export interface ParseOptions {
-	/** Enable loose mode */
 	loose?: boolean;
 }
 
-/**
- * Parse Ripple source code to ESTree AST
- * @param source - The Ripple source code to parse
- * @param options - Parse options
- * @returns The parsed ESTree Program AST
- */
+export interface AnalyzeOptions extends ParseOptions, Pick<CompileOptions, 'mode'> {
+	to_ts?: boolean;
+}
+
+export interface VolarCompileOptions extends ParseOptions, SharedCompileOptions {}
+
 export function parse(source: string, options?: ParseOptions): Program;
 
-/**
- * Compile Ripple source code to JS/CSS output
- * @param source - The Ripple source code to compile
- * @param filename - The filename for source map generation
- * @param options - Compilation options (mode: 'client' or 'server')
- * @returns The compilation result with AST, JS, and CSS
- */
 export function compile(source: string, filename: string, options?: CompileOptions): CompileResult;
 
-/**
- * Compile Ripple source to Volar mappings for editor integration
- * @param source - The Ripple source code
- * @param filename - The filename for source map generation
- * @param options - Parse options
- * @returns Volar mappings object for editor integration
- */
 export function compile_to_volar_mappings(
 	source: string,
 	filename: string,
-	options?: ParseOptions,
+	options?: VolarCompileOptions,
 ): VolarMappingsResult;

package/src/compiler/index.js

@@ -1,5 +1,4 @@
 /** @import { Program } from 'estree' */
-/** @import { ParseOptions } from 'ripple/compiler' */
 
 import { parse as parse_module } from './phases/1-parse/index.js';
 import { analyze } from './phases/2-analyze/index.js';
@@ -20,7 +19,7 @@ export function parse(source) {
  * Compile Ripple source code to JS/CSS output
  * @param {string} source
  * @param {string} filename
- * @param {{ mode?: 'client' | 'server' }} [options]
+ * @param {CompileOptions} [options]
  * @returns {object}
  */
 export function compile(source, filename, options = {}) {
@@ -28,26 +27,32 @@ export function compile(source, filename, options = {}) {
 	const analysis = analyze(ast, filename, options);
 	const result =
 		options.mode === 'server'
-			? transform_server(filename, source, analysis)
-			: transform_client(filename, source, analysis, false);
+			? transform_server(filename, source, analysis, options?.minify_css ?? false)
+			: transform_client(filename, source, analysis, false, options?.minify_css ?? false);
 
 	return result;
 }
 
 /** @import { PostProcessingChanges, LineOffsets } from './phases/3-transform/client/index.js' */
-/** @import { VolarMappingsResult } from 'ripple/compiler' */
+/** @import { VolarMappingsResult, VolarCompileOptions, CompileOptions } from 'ripple/compiler' */
 
 /**
  * Compile Ripple component to Volar virtual code with TypeScript mappings
  * @param {string} source
  * @param {string} filename
- * @param {ParseOptions} [options] - Compiler options
+ * @param {VolarCompileOptions} [options] - Compiler options
  * @returns {VolarMappingsResult} Volar mappings object
  */
 export function compile_to_volar_mappings(source, filename, options) {
 	const ast = parse_module(source, options);
 	const analysis = analyze(ast, filename, { to_ts: true, loose: !!options?.loose });
-	const transformed = transform_client(filename, source, analysis, true);
+	const transformed = transform_client(
+		filename,
+		source,
+		analysis,
+		true,
+		options?.minify_css ?? false,
+	);
 
 	// Create volar mappings with esrap source map for accurate positioning
 	return convert_source_map_to_mappings(

package/src/compiler/phases/1-parse/index.js

@@ -2115,9 +2115,12 @@ function get_comment_handlers(source, comments, index = 0) {
 						}
 						// Handle empty Element nodes the same way as empty BlockStatements
 						if (node.type === 'Element' && (!node.children || node.children.length === 0)) {
-							if (comments[0].start < node.end && comments[0].end < node.end) {
+							// Collect all comments that fall within this empty element
+							while (comments[0] && comments[0].start < node.end && comments[0].end < node.end) {
 								comment = /** @type {CommentWithLocation} */ (comments.shift());
 								(node.innerComments ||= []).push(comment);
+							}
+							if (node.innerComments && node.innerComments.length > 0) {
 								return;
 							}
 						}

package/src/compiler/phases/1-parse/style.js

@@ -1,3 +1,5 @@
+/** @import * as AST from 'estree' */
+
 import { hash } from '../../utils.js';
 
 const REGEX_MATCHER = /^[~^$*|]?=/;
@@ -17,6 +19,10 @@ const regex_whitespace = /\s/;
 class Parser {
 	index = 0;
 
+	/**
+	 * @param {string} template
+	 * @param {boolean} loose
+	 */
 	constructor(template, loose) {
 		if (typeof template !== 'string') {
 			throw new TypeError('Template must be a string');
@@ -27,6 +33,7 @@ class Parser {
 		this.template = template.trimEnd();
 	}
 
+	/** @param {string} str */
 	match(str) {
 		const length = str.length;
 		if (length === 1) {
@@ -37,6 +44,11 @@ class Parser {
 		return this.template.slice(this.index, this.index + length) === str;
 	}
 
+	/**
+	 * @param {string} str
+	 * @param {boolean} required
+	 * @param {boolean} required_in_loose
+	 */
 	eat(str, required = false, required_in_loose = true) {
 		if (this.match(str)) {
 			this.index += str.length;
@@ -50,6 +62,10 @@ class Parser {
 		return false;
 	}
 
+	/**
+	 * Match a regex at the current index
+	 * @param {RegExp} pattern  Should have a ^ anchor at the start so the regex doesn't search past the beginning, resulting in worse performance
+	 */
 	match_regex(pattern) {
 		const match = pattern.exec(this.template.slice(this.index));
 		if (!match || match.index !== 0) return null;
@@ -57,6 +73,10 @@ class Parser {
 		return match[0];
 	}
 
+	/**
+	 * Search for a regex starting at the current index and return the result if it matches
+	 * @param {RegExp} pattern  Should have a ^ anchor at the start so the regex doesn't search past the beginning, resulting in worse performance
+	 */
 	read(pattern) {
 		const result = this.match_regex(pattern);
 		if (result) this.index += result.length;
@@ -69,6 +89,7 @@ class Parser {
 		}
 	}
 
+	/** @param {RegExp} pattern */
 	read_until(pattern) {
 		if (this.index >= this.template.length) {
 			if (this.loose) return '';
@@ -88,6 +109,11 @@ class Parser {
 	}
 }
 
+/**
+ * @param {string} content
+ * @param {{ loose?: boolean }} options
+ * @returns {Partial<AST.CSS.StyleSheet>}
+ */
 export function parse_style(content, options) {
 	const parser = new Parser(content, options.loose || false);
 
@@ -95,10 +121,11 @@ export function parse_style(content, options) {
 		source: content,
 		hash: `ripple-${hash(content)}`,
 		type: 'StyleSheet',
-		body: read_body(parser),
+		children: read_body(parser),
 	};
 }
 
+/** @param {Parser} parser */
 function allow_comment_or_whitespace(parser) {
 	parser.allow_whitespace();
 	while (parser.match('/*') || parser.match('<!--')) {
@@ -116,7 +143,12 @@ function allow_comment_or_whitespace(parser) {
 	}
 }
 
+/**
+ * @param {Parser} parser
+ * @returns {Array<AST.CSS.Rule | AST.CSS.Atrule>}
+ */
 function read_body(parser) {
+	/** @type {Array<AST.CSS.Rule | AST.CSS.Atrule>} */
 	const children = [];
 
 	while (parser.index < parser.template.length) {
@@ -132,6 +164,10 @@ function read_body(parser) {
 	return children;
 }
 
+/**
+ * @param {Parser} parser
+ * @returns {AST.CSS.Atrule}
+ */
 function read_at_rule(parser) {
 	const start = parser.index;
 	parser.eat('@', true);
@@ -161,6 +197,10 @@ function read_at_rule(parser) {
 	};
 }
 
+/**
+ * @param {Parser} parser
+ * @returns {AST.CSS.Rule}
+ */
 function read_rule(parser) {
 	const start = parser.index;
 
@@ -178,6 +218,10 @@ function read_rule(parser) {
 	};
 }
 
+/**
+ * @param {Parser} parser
+ * @returns {AST.CSS.Block}
+ */
 function read_block(parser) {
 	const start = parser.index;
 
@@ -206,6 +250,12 @@ function read_block(parser) {
 	};
 }
 
+/**
+ * Reads a declaration, rule or at-rule
+ *
+ * @param {Parser} parser
+ * @returns {AST.CSS.Declaration | AST.CSS.Rule | AST.CSS.Atrule}
+ */
 function read_block_item(parser) {
 	if (parser.match('@')) {
 		return read_at_rule(parser);
@@ -221,6 +271,10 @@ function read_block_item(parser) {
 	return char === '{' ? read_rule(parser) : read_declaration(parser);
 }
 
+/**
+ * @param {Parser} parser
+ * @returns {AST.CSS.Declaration}
+ */
 function read_declaration(parser) {
 	const start = parser.index;
 
@@ -251,6 +305,10 @@ function read_declaration(parser) {
 	};
 }
 
+/**
+ * @param {Parser} parser
+ * @returns {string}
+ */
 function read_value(parser) {
 	let value = '';
 	let escaped = false;
@@ -287,6 +345,11 @@ function read_value(parser) {
 	throw new Error('Unexpected end of input');
 }
 
+/**
+ * @param {Parser} parser
+ * @param {boolean} [inside_pseudo_class]
+ * @returns {AST.CSS.SelectorList}
+ */
 function read_selector_list(parser, inside_pseudo_class = false) {
 	/** @type {AST.CSS.ComplexSelector[]} */
 	const children = [];
@@ -318,6 +381,10 @@ function read_selector_list(parser, inside_pseudo_class = false) {
 	throw new Error('Unexpected end of input');
 }
 
+/**
+ * @param {Parser} parser
+ * @returns {AST.CSS.Combinator | null}
+ */
 function read_combinator(parser) {
 	const start = parser.index;
 	parser.allow_whitespace();
@@ -349,6 +416,11 @@ function read_combinator(parser) {
 	return null;
 }
 
+/**
+ * @param {Parser} parser
+ * @param {boolean} [inside_pseudo_class]
+ * @returns {AST.CSS.ComplexSelector}
+ */
 function read_selector(parser, inside_pseudo_class = false) {
 	const list_start = parser.index;
 
@@ -547,7 +619,7 @@ function read_selector(parser, inside_pseudo_class = false) {
 			parser.allow_whitespace();
 
 			if (parser.match(',') || (inside_pseudo_class ? parser.match(')') : parser.match('{'))) {
-				e.css_selector_invalid(parser.index);
+				throw new Error(`Invalid selector at parser.index: ${parser.index}`);
 			}
 		}
 	}
@@ -588,6 +660,10 @@ function read_attribute_value(parser) {
 	throw new Error('Unexpected end of input');
 }
 
+/**
+ * https://www.w3.org/TR/css-syntax-3/#ident-token-diagram
+ * @param {Parser} parser
+ */
 function read_identifier(parser) {
 	const start = parser.index;
 

package/src/compiler/phases/2-analyze/index.js

@@ -1,3 +1,6 @@
+/** @import {AnalyzeOptions} from 'ripple/compiler'  */
+/** @import * as AST from 'estree' */
+
 import * as b from '../../../utils/builders.js';
 import { walk } from 'zimmerframe';
 import { create_scopes, ScopeRoot } from '../../scope.js';
@@ -564,14 +567,15 @@ const visitors = {
 	 * @returns
 	 */
 	TryStatement(node, context) {
+		const { state } = context;
 		if (!is_inside_component(context)) {
 			return context.next();
 		}
 
 		if (node.pending) {
 			// Try/pending blocks indicate async operations
-			if (context.state.metadata?.await === false) {
-				context.state.metadata.await = true;
+			if (state.metadata?.await === false) {
+				state.metadata.await = true;
 			}
 
 			node.metadata = {
@@ -579,12 +583,12 @@ const visitors = {
 				has_template: false,
 			};
 
-			context.visit(node.block, context.state);
+			context.visit(node.block, state);
 
-			if (!node.metadata.has_template) {
+			if (!node.metadata.has_template && !state.loose) {
 				error(
 					'Component try statements must contain a template in their main body. Move the try statement into an effect if it does not render anything.',
-					context.state.analysis.module.filename,
+					state.analysis.module.filename,
 					node,
 				);
 			}
@@ -594,19 +598,19 @@ const visitors = {
 				has_template: false,
 			};
 
-			context.visit(node.pending, context.state);
+			context.visit(node.pending, state);
 
-			if (!node.metadata.has_template) {
+			if (!node.metadata.has_template && !state.loose) {
 				error(
 					'Component try statements must contain a template in their "pending" body. Rendering a pending fallback is required to have a template.',
-					context.state.analysis.module.filename,
+					state.analysis.module.filename,
 					node,
 				);
 			}
 		}
 
 		if (node.finalizer) {
-			context.visit(node.finalizer, context.state);
+			context.visit(node.finalizer, state);
 		}
 	},
 
@@ -856,6 +860,12 @@ const visitors = {
 	},
 };
 
+/**
+ *
+ * @param {AST.Program} ast
+ * @param {string} filename
+ * @param {AnalyzeOptions} options
+ */
 export function analyze(ast, filename, options = {}) {
 	const scope_root = new ScopeRoot();
 

package/src/compiler/phases/3-transform/client/index.js

@@ -2192,6 +2192,18 @@ function transform_ts_child(node, context) {
 			catch_handler = b.catch_clause(node.handler.param || null, catch_body);
 		}
 
+		let pending_block = null;
+		if (node.pending) {
+			const pending_scope = context.state.scopes.get(node.pending);
+			pending_block = b.try_item_block(
+				transform_body(node.pending.body, {
+					...context,
+					state: { ...context.state, scope: pending_scope },
+				}),
+				node.pending.loc,
+			);
+		}
+
 		let finally_block = null;
 		if (node.finalizer) {
 			const finally_scope = context.state.scopes.get(node.finalizer);
@@ -2203,7 +2215,7 @@ function transform_ts_child(node, context) {
 			);
 		}
 
-		state.init.push(b.try(try_body, catch_handler, finally_block));
+		state.init.push(b.try(try_body, catch_handler, finally_block, pending_block));
 	} else if (node.type === 'Component') {
 		const component = visit(node, state);
 
@@ -2809,6 +2821,38 @@ function create_tsx_with_typescript_support() {
 				context.visit(node.body);
 			}
 		},
+		// Custom handler for TryStatement to support Ripple's pending block
+		TryStatement(node, context) {
+			context.write('try ');
+			context.visit(node.block);
+
+			if (node.pending) {
+				// Output the pending block with source mapping for the 'pending' keyword
+				context.write(' ');
+				context.location(
+					node.pending.loc.start.line,
+					node.pending.loc.start.column - 'pending '.length,
+				);
+				context.write('pending ');
+				context.visit(node.pending);
+			}
+
+			if (node.handler) {
+				context.write(' catch');
+				if (node.handler.param) {
+					context.write(' (');
+					context.visit(node.handler.param);
+					context.write(')');
+				}
+				context.write(' ');
+				context.visit(node.handler.body);
+			}
+
+			if (node.finalizer) {
+				context.write(' finally ');
+				context.visit(node.finalizer);
+			}
+		},
 	};
 }
 
@@ -2818,9 +2862,10 @@ function create_tsx_with_typescript_support() {
  * @param {string} source - Original source code
  * @param {any} analysis - Analysis result
  * @param {boolean} to_ts - Whether to generate TypeScript output
+ * @param {boolean} minify_css - Whether to minify CSS output
  * @returns {{ ast: any, js: { code: string, map: any, post_processing_changes?: PostProcessingChanges, line_offsets?: LineOffsets }, css: any }}
  */
-export function transform_client(filename, source, analysis, to_ts) {
+export function transform_client(filename, source, analysis, to_ts, minify_css) {
 	/**
 	 * User's named imports from 'ripple' so we can reuse them in TS output
 	 * when transforming shorthand syntax. E.g., if the user has already imported
@@ -2966,7 +3011,7 @@ export function transform_client(filename, source, analysis, to_ts) {
 		js.line_offsets = line_offsets;
 	}
 
-	const css = render_stylesheets(state.stylesheets);
+	const css = render_stylesheets(state.stylesheets, minify_css);
 
 	return {
 		ast: program,

package/src/compiler/phases/3-transform/segments.js

@@ -1,7 +1,4 @@
-/**
- * @typedef {Object} CustomMappingData
- * @property {number[]} generatedLengths
- */
+/** @import { CustomMappingData, PluginActionOverrides } from 'ripple/compiler'; */
 
 /**
  * @typedef {import('estree').Position} Position
@@ -19,6 +16,7 @@
 
 import { walk } from 'zimmerframe';
 import { build_source_to_generated_map, get_generated_position } from '../../source-map-utils.js';
+import { DocumentHighlightKind } from 'vscode-languageserver-types';
 
 /** @type {VolarCodeMapping['data']} */
 export const mapping_data = {
@@ -152,6 +150,7 @@ export function convert_source_map_to_mappings(
 	 *		is_full_import_statement?: boolean,
 	 *		loc: Location,
 	 *		end_loc?: Location,
+	 *		metadata?: PluginActionOverrides
 	 * }>}
 	 */
 	const tokens = [];
@@ -503,10 +502,53 @@ export function convert_source_map_to_mappings(
 				}
 				return;
 			} else if (node.type === 'TryStatement') {
-				// Visit in source order: block, handler, finalizer
+				// Visit in source order: block, pending, handler, finalizer
 				if (node.block) {
 					visit(node.block);
 				}
+				if (node.pending) {
+					// Add a special token for the 'pending' keyword with customData
+					// to suppress TypeScript diagnostics and provide custom hover/definition
+					const pendingKeywordLoc = {
+						start: {
+							line: node.pending.loc.start.line,
+							column: node.pending.loc.start.column - 'pending '.length,
+						},
+						end: {
+							line: node.pending.loc.start.line,
+							column: node.pending.loc.start.column - 1,
+						},
+					};
+					tokens.push({
+						source: 'pending',
+						generated: 'pending',
+						loc: pendingKeywordLoc,
+						metadata: {
+							wordHighlight: {
+								kind: DocumentHighlightKind.Text,
+							},
+							suppressedDiagnostics: [
+								1472, // 'catch' or 'finally' expected
+								2304, // Cannot find name 'pending'
+							],
+							// suppress all hovers
+							hover: false,
+
+							// Example of a custom hover contents (uses markdown)
+							// hover: {
+							// 	contents:
+							// 		'```ripple\npending\n```\n\nRipple-specific keyword for try/pending blocks.\n\nThe `pending` block executes while async operations inside the `try` block are awaiting. This provides a built-in loading state for async components.',
+							// },
+
+							// TODO: Definition is not implemented yet, leaving for future use
+							// definition: {
+							// 	description:
+							// 		'Ripple pending block - executes during async operations in the try block',
+							// },
+						},
+					});
+					visit(node.pending);
+				}
 				if (node.handler) {
 					visit(node.handler);
 				}
@@ -1333,11 +1375,31 @@ export function convert_source_map_to_mappings(
 			);
 			gen_start = gen_loc_to_offset(gen_line_col.line, gen_line_col.column);
 
+			/** @type {CustomMappingData} */
+			const customData = {
+				generatedLengths: [gen_length],
+			};
+
+			// Add optional metadata from token if present
+			if (token.metadata) {
+				if ('wordHighlight' in token.metadata) {
+					customData.wordHighlight = token.metadata.wordHighlight;
+				}
+
+				if ('suppressedDiagnostics' in token.metadata) {
+					customData.suppressedDiagnostics = token.metadata.suppressedDiagnostics;
+				}
+				if ('hover' in token.metadata) {
+					customData.hover = token.metadata.hover;
+				}
+				if ('definition' in token.metadata) {
+					customData.definition = token.metadata.definition;
+				}
+			}
+
 			data = {
 				...mapping_data,
-				customData: {
-					generatedLengths: [gen_length],
-				},
+				customData,
 			};
 		}
 

package/src/compiler/phases/3-transform/server/index.js

@@ -1,3 +1,5 @@
+/** @import * as ESTree from 'estree' */
+
 import * as b from '../../../../utils/builders.js';
 import { walk } from 'zimmerframe';
 import ts from 'esrap/languages/ts';
@@ -804,7 +806,7 @@ const visitors = {
 	},
 };
 
-export function transform_server(filename, source, analysis) {
+export function transform_server(filename, source, analysis, minify_css) {
 	// Use component metadata collected during the analyze phase
 	const component_metadata = analysis.component_metadata || [];
 
@@ -823,7 +825,7 @@ export function transform_server(filename, source, analysis) {
 		walk(analysis.ast, { ...state, namespace: 'html' }, visitors)
 	);
 
-	const css = render_stylesheets(state.stylesheets);
+	const css = render_stylesheets(state.stylesheets, minify_css);
 
 	// Add CSS registration if there are stylesheets
 	if (state.stylesheets.length > 0 && css) {

package/src/compiler/phases/3-transform/stylesheet.js

@@ -1,25 +1,58 @@
+/** @import * as AST from 'estree' */
+/** @import { Visitors } from 'zimmerframe' */
+
+/**
+ * @typedef {{
+ *   code: MagicString;
+ *   hash: string;
+ *   minify: boolean;
+ *   selector: string;
+ *   keyframes: Record<string, {
+ *     indexes: number[];
+ *     local: boolean | undefined;
+ *   }>;
+ *   specificity: {
+ *     bumped: boolean
+ *   }
+ * }} State
+ */
+
 import MagicString from 'magic-string';
 import { walk } from 'zimmerframe';
 
 const regex_css_browser_prefix = /^-((webkit)|(moz)|(o)|(ms))-/;
 const regex_css_name_boundary = /^[\s,;}]$/;
 
+/** @param {AST.CSS.Atrule} node */
 const is_keyframes_node = (node) => remove_css_prefix(node.name) === 'keyframes';
 
+/**
+ * @param {string} name
+ * @returns {string}
+ */
 function remove_css_prefix(name) {
 	return name.replace(regex_css_browser_prefix, '');
 }
 
+/**
+ * Walk backwards until we find a non-whitespace character
+ * @param {number} end
+ * @param {State} state
+ */
 function remove_preceding_whitespace(end, state) {
 	let start = end;
 	while (/\s/.test(state.code.original[start - 1])) start--;
 	if (start < end) state.code.remove(start, end);
 }
 
+/** @param {AST.CSS.Rule} rule */
 function is_used(rule) {
 	return rule.prelude.children.some((selector) => selector.metadata.used);
 }
 
+/**
+ * @param {Array<AST.CSS.Node>} path
+ */
 function is_in_global_block(path) {
 	return path.some((node) => node.type === 'Rule' && node.metadata.is_global_block);
 }
@@ -27,7 +60,7 @@ function is_in_global_block(path) {
 /**
  * Check if we're inside a pseudo-class selector that's INSIDE a :global() wrapper
  * or adjacent to a :global modifier
- * @param {any[]} path
+ * @param {AST.CSS.Node[]} path
  */
 function is_in_global_pseudo(path) {
 	// Walk up the path to find if we're inside a :global() pseudo-class selector with args
@@ -83,6 +116,11 @@ function has_global_in_middle(rule) {
 	return false;
 }
 
+/**
+ * @param {AST.CSS.PseudoClassSelector} selector
+ * @param {AST.CSS.Combinator | null} combinator
+ * @param {State} state
+ */
 function remove_global_pseudo_class(selector, combinator, state) {
 	if (selector.args === null) {
 		let start = selector.start;
@@ -98,6 +136,10 @@ function remove_global_pseudo_class(selector, combinator, state) {
 	}
 }
 
+/**
+ * @param {AST.CSS.Rule} node
+ * @param {MagicString} code
+ */
 function escape_comment_close(node, code) {
 	let escaped = false;
 	let in_comment = false;
@@ -121,12 +163,16 @@ function escape_comment_close(node, code) {
 	}
 }
 
+/**
+ * @param {State} state
+ * @param {number} index
+ */
 function append_hash(state, index) {
 	state.code.prependRight(index, `${state.hash}-`);
 }
 
 /**
- *  @param {AST.CSS.Rule} rule
+ * @param {AST.CSS.Rule} rule
  * @param {boolean} is_in_global_block
  */
 function is_empty(rule, is_in_global_block) {
@@ -159,6 +205,7 @@ function is_empty(rule, is_in_global_block) {
 	return true;
 }
 
+/** @type {Visitors<AST.CSS.Node, State>} */
 const visitors = {
 	_: (node, context) => {
 		context.state.code.addSourcemapLocation(node.start);
@@ -189,6 +236,7 @@ const visitors = {
 		const property = node.property && remove_css_prefix(node.property.toLowerCase());
 		if (property === 'animation' || property === 'animation-name') {
 			let index = node.start + node.property.length + 1;
+			/** @type {string} */
 			let name = '';
 
 			while (index < state.code.original.length) {
@@ -368,7 +416,10 @@ const visitors = {
 				) {
 					// Now check if this pseudo-class is part of a global RelativeSelector
 					for (let j = i - 2; j >= 0; j--) {
-						if (parentPath[j].type === 'RelativeSelector' && parentPath[j].metadata?.is_global) {
+						if (
+							parentPath[j].type === 'RelativeSelector' &&
+							/** @type {AST.CSS.RelativeSelector} */ (parentPath[j]).metadata?.is_global
+						) {
 							insideScopingPseudo = true;
 							break;
 						}
@@ -462,7 +513,13 @@ const visitors = {
 	},
 };
 
-export function render_stylesheets(stylesheets) {
+/**
+ * Render stylesheets to CSS string
+ * @param {AST.CSS.StyleSheet[]} stylesheets
+ * @param {boolean} [minify]
+ * @returns {string}
+ */
+export function render_stylesheets(stylesheets, minify = false) {
 	let css = '';
 
 	for (const stylesheet of stylesheets) {
@@ -470,6 +527,7 @@ export function render_stylesheets(stylesheets) {
 		const state = {
 			code,
 			hash: stylesheet.hash,
+			minify,
 			selector: `.${stylesheet.hash}`,
 			keyframes: {},
 			specificity: {

package/src/compiler/types/index.d.ts

@@ -1,4 +1,4 @@
-import type { SourceLocation } from 'estree';
+import type * as ESTree from 'estree';
 
 // Ripple augmentation for ESTree function nodes
 declare module 'estree' {
@@ -20,6 +20,178 @@ declare module 'estree' {
 		params: Pattern[];
 		body: BlockStatement;
 	}
+
+	interface TryStatement {
+		pending?: BlockStatement | null;
+	}
+
+	export namespace CSS {
+		export interface BaseNode {
+			start: number;
+			end: number;
+		}
+
+		export interface StyleSheet extends BaseNode {
+			type: 'StyleSheet';
+			children: Array<Atrule | Rule>;
+			source: string;
+			hash: string;
+		}
+
+		export interface Atrule extends BaseNode {
+			type: 'Atrule';
+			name: string;
+			prelude: string;
+			block: Block | null;
+		}
+
+		export interface Rule extends BaseNode {
+			type: 'Rule';
+			prelude: SelectorList;
+			block: Block;
+			metadata: {
+				parent_rule: Rule | null;
+				has_local_selectors: boolean;
+				is_global_block: boolean;
+			};
+		}
+
+		/**
+		 * A list of selectors, e.g. `a, b, c {}`
+		 */
+		export interface SelectorList extends BaseNode {
+			type: 'SelectorList';
+			/**
+			 * The `a`, `b` and `c` in `a, b, c {}`
+			 */
+			children: ComplexSelector[];
+		}
+
+		/**
+		 * A complex selector, e.g. `a b c {}`
+		 */
+		export interface ComplexSelector extends BaseNode {
+			type: 'ComplexSelector';
+			/**
+			 * The `a`, `b` and `c` in `a b c {}`
+			 */
+			children: RelativeSelector[];
+			metadata: {
+				rule: Rule | null;
+				used: boolean;
+			};
+		}
+
+		/**
+		 * A relative selector, e.g the `a` and `> b` in `a > b {}`
+		 */
+		export interface RelativeSelector extends BaseNode {
+			type: 'RelativeSelector';
+			/**
+			 * In `a > b`, `> b` forms one relative selector, and `>` is the combinator. `null` for the first selector.
+			 */
+			combinator: null | Combinator;
+			/**
+			 * The `b:is(...)` in `> b:is(...)`
+			 */
+			selectors: SimpleSelector[];
+
+			metadata: {
+				is_global: boolean;
+				is_global_like: boolean;
+				scoped: boolean;
+			};
+		}
+
+		export interface TypeSelector extends BaseNode {
+			type: 'TypeSelector';
+			name: string;
+		}
+
+		export interface IdSelector extends BaseNode {
+			type: 'IdSelector';
+			name: string;
+		}
+
+		export interface ClassSelector extends BaseNode {
+			type: 'ClassSelector';
+			name: string;
+		}
+
+		export interface AttributeSelector extends BaseNode {
+			type: 'AttributeSelector';
+			name: string;
+			matcher: string | null;
+			value: string | null;
+			flags: string | null;
+		}
+
+		export interface PseudoElementSelector extends BaseNode {
+			type: 'PseudoElementSelector';
+			name: string;
+		}
+
+		export interface PseudoClassSelector extends BaseNode {
+			type: 'PseudoClassSelector';
+			name: string;
+			args: SelectorList | null;
+		}
+
+		export interface Percentage extends BaseNode {
+			type: 'Percentage';
+			value: string;
+		}
+
+		export interface NestingSelector extends BaseNode {
+			type: 'NestingSelector';
+			name: '&';
+		}
+
+		export interface Nth extends BaseNode {
+			type: 'Nth';
+			value: string;
+		}
+
+		export type SimpleSelector =
+			| TypeSelector
+			| IdSelector
+			| ClassSelector
+			| AttributeSelector
+			| PseudoElementSelector
+			| PseudoClassSelector
+			| Percentage
+			| Nth
+			| NestingSelector;
+
+		export interface Combinator extends BaseNode {
+			type: 'Combinator';
+			name: string;
+		}
+
+		export interface Block extends BaseNode {
+			type: 'Block';
+			children: Array<Declaration | Rule | Atrule>;
+		}
+
+		export interface Declaration extends BaseNode {
+			type: 'Declaration';
+			property: string;
+			value: string;
+		}
+
+		// for zimmerframe
+		export type Node =
+			| StyleSheet
+			| Rule
+			| Atrule
+			| SelectorList
+			| Block
+			| ComplexSelector
+			| RelativeSelector
+			| Combinator
+			| SimpleSelector
+			| Declaration;
+	}
 }
 
 declare module 'estree-jsx' {
@@ -28,11 +200,11 @@ declare module 'estree-jsx' {
 	}
 
 	interface JSXOpeningElement {
-		loc: SourceLocation;
+		loc: ESTree.SourceLocation;
 	}
 
 	interface JSXClosingElement {
-		loc: SourceLocation;
+		loc: ESTree.SourceLocation;
 	}
 }
 

package/src/runtime/internal/client/composite.js

@@ -1,7 +1,7 @@
 /** @import { Block } from '#client' */
 
 import { branch, destroy_block, render, render_spread } from './blocks.js';
-import { COMPOSITE_BLOCK, NAMESPACE_URI, DEFAULT_NAMESPACE } from './constants.js';
+import { COMPOSITE_BLOCK, DEFAULT_NAMESPACE, NAMESPACE_URI } from './constants.js';
 import { active_block, active_namespace, with_ns } from './runtime.js';
 import { top_element_to_ns } from './utils.js';
 
@@ -32,8 +32,8 @@ export function composite(get_component, node, props) {
 					var block = active_block;
 					/** @type {ComponentFunction} */ (component)(anchor, props, block);
 				});
-			} else {
-				// Custom element
+			} else if (component != null) {
+				// Custom element - only create if component is not null/undefined
 				var run = () => {
 					var block = /** @type {Block} */ (active_block);
 

package/src/utils/builders.js

@@ -106,6 +106,15 @@ export function block(body) {
 	return { type: 'BlockStatement', body };
 }
 
+/**
+ * @param {ESTree.Statement[]} body
+ * @param {ESTree.SourceLocation} loc
+ * @returns {ESTree.BlockStatement}
+ */
+export function try_item_block(body, loc) {
+	return { type: 'BlockStatement', body, loc };
+}
+
 /**
  * @param {string} name
  * @param {ESTree.Statement} body
@@ -681,21 +690,23 @@ export function throw_error(str) {
  * @param {ESTree.BlockStatement} block
  * @param {ESTree.CatchClause | null} handler
  * @param {ESTree.BlockStatement | null} finalizer
+ * @param {ESTree.BlockStatement | null} pending
  * @returns {ESTree.TryStatement}
  */
-export function try_builder(block, handler = null, finalizer = null) {
+export function try_builder(block, handler = null, finalizer = null, pending = null) {
 	return {
 		type: 'TryStatement',
 		block,
 		handler,
 		finalizer,
+		pending,
 	};
 }
 
 /**
  * @param {ESTree.Pattern | null} param
  * @param {ESTree.BlockStatement} body
- * @returns {ESTree.CatchClause}
+ * @return {ESTree.CatchClause}
  */
 export function catch_clause_builder(param, body) {
 	return {

package/tests/client/composite/composite.render.test.ripple

@@ -59,7 +59,6 @@ describe('composite > render', () => {
 			let name = 'Click Me';
 
 			<Child class="my-button">{name}</Child>
-
 		}
 
 		component Child({ children, ...rest }: { children: string; class: string }) {
@@ -82,4 +81,25 @@ describe('composite > render', () => {
 
 		render(ArrayTest);
 	});
+
+	it('should not render <undefined> tag when a passed in component is undefined', () => {
+		component Child({ children, NonExistent, ...props }) {
+			<div {...props}>
+				<children />
+				<NonExistent />
+			</div>
+		}
+
+		component App() {
+			<Child />
+		}
+
+		render(App);
+
+		const div = container.querySelector('div');
+		const undefinedTag = container.querySelector('undefined');
+
+		expect(undefinedTag).toBeNull();
+		expect(div.innerHTML).not.toContain('<undefined');
+	});
 });