octane 0.2.2 → 0.2.4

package/dist/compiler/hook-deps.js

@@ -24,6 +24,7 @@ const STABLE_TUPLE_RESULTS = new Map([
 	['useReducer', new Set([1, 2])],
 	['useTransition', new Set([1])],
 	['useActionState', new Set([1])],
+	['useFormState', new Set([1])],
 	['useOptimistic', new Set([1])],
 ]);
 
@@ -57,6 +58,7 @@ function declareName(scope, name, details = null) {
 			octaneNamespace: false,
 			hookRuntimeImport: null,
 			hookRuntimeNamespace: false,
+			customHookImport: null,
 		};
 		scope.bindings.set(name, binding);
 	}
@@ -66,6 +68,7 @@ function declareName(scope, name, details = null) {
 	if (details?.octaneNamespace) binding.octaneNamespace = true;
 	if (details?.hookRuntimeImport) binding.hookRuntimeImport = details.hookRuntimeImport;
 	if (details?.hookRuntimeNamespace) binding.hookRuntimeNamespace = true;
+	if (details?.customHookImport) binding.customHookImport = details.customHookImport;
 	return binding;
 }
 
@@ -133,6 +136,13 @@ function predeclareDirect(statements, scope, hookRuntimeModules, bindingsOnly =
 					octaneNamespace: isOctane && specifier.type === 'ImportNamespaceSpecifier',
 					hookRuntimeImport: isHookRuntime ? imported : null,
 					hookRuntimeNamespace: isHookRuntime && specifier.type === 'ImportNamespaceSpecifier',
+					customHookImport:
+						!isHookRuntime &&
+						original.importKind !== 'type' &&
+						specifier.importKind !== 'type' &&
+						(/^use[A-Z]/.test(imported ?? '') || /^use[A-Z]/.test(specifier.local.name))
+							? (imported ?? specifier.local.name)
+							: null,
 				});
 			}
 			continue;
@@ -579,10 +589,20 @@ function buildScopes(ast, onlyImported, hookRuntimeModules, bindingsOnly = false
 			const name = canonicalHookName(node, scope, onlyImported);
 			const config = DEPENDENCY_HOOKS.get(name);
 			const hookRuntimeImportedName = canonicalHookName(node, scope, true);
-			if (octaneImportedName !== null || unboundCallee || hookRuntimeImportedName !== null) {
+			const customHookImport =
+				node.optional !== true && callee?.type === 'Identifier'
+					? resolveBinding(scope, callee.name)?.customHookImport
+					: null;
+			if (
+				octaneImportedName !== null ||
+				unboundCallee ||
+				hookRuntimeImportedName !== null ||
+				customHookImport
+			) {
 				const props = {};
 				if (octaneImportedName !== null) props._octaneImportedHook = octaneImportedName;
 				if (unboundCallee) props._octaneUnboundCallee = true;
+				if (customHookImport) props._octaneCustomHookCall = customHookImport;
 				if (octaneImportedName === null && hookRuntimeImportedName !== null) {
 					props._octaneHookRuntimeImportedHook = hookRuntimeImportedName;
 				}
@@ -665,8 +685,9 @@ function buildScopes(ast, onlyImported, hookRuntimeModules, bindingsOnly = false
 		declarationBindings,
 	};
 	if (bindingsOnly) return analysis;
-	// The surgical plain-TS pass slots base hooks only; without a custom-hook
-	// withSlot boundary, two local wrapper calls would share their inner slots.
+	if (onlyImported) annotateLocalHookAliases(analysis);
+	// The plain-TS pass slots base hooks and imported/aliased hook values. Local
+	// custom-hook functions still own their authored slot boundaries.
 	// Restrict custom-call inference to the full TSRX/TSX compiler, which emits
 	// that boundary for every plain-identifier custom hook call.
 	const customHooks = onlyImported ? new Map() : discoverCustomDependencyHooks(analysis);
@@ -687,6 +708,82 @@ function buildScopes(ast, onlyImported, hookRuntimeModules, bindingsOnly = false
 	return analysis;
 }
 
+// An immutable alias may select a base hook directly, or a zero-argument local
+// factory may return that selection (the usual isomorphic-effect pattern).
+// Follow only value aliases, never the body of an ordinary custom hook. This
+// proof needs the completed lexical graph so declaration order and shadowing
+// cannot change a call's identity.
+function annotateLocalHookAliases(analysis) {
+	// Ordinary modules with only direct imported hooks need no alias tables.
+	if (
+		!analysis.calls.some(({ call, scope }) => {
+			const binding = directCallBinding(call, scope);
+			return binding !== null && !binding.imported;
+		})
+	)
+		return;
+	const values = new Map();
+	const factories = new Map();
+	for (const { decl, bindings, kind } of analysis.declarators) {
+		if (kind !== 'const' || decl.id.type !== 'Identifier') continue;
+		const binding = bindings[0]?.binding;
+		if (binding && !binding.reassigned) values.set(binding, unwrapValue(decl.init));
+	}
+	if (values.size === 0) return;
+	for (const record of analysis.functions) {
+		if (record.binding && record.stableDefinition && !record.binding.reassigned) {
+			factories.set(record.binding, record.node);
+		}
+	}
+	function referencesHook(node, seen) {
+		const value = unwrapValue(node);
+		if (!value) return false;
+		if (value.type === 'Identifier') {
+			const binding = resolveBinding(analysis.nodeScopes.get(value), value.name);
+			if (!binding || binding.reassigned || seen.has(binding)) return false;
+			if (/^use[A-Z]/.test(binding.hookRuntimeImport ?? '') || binding.customHookImport)
+				return true;
+			seen.add(binding);
+			return referencesHook(values.get(binding), seen);
+		}
+		if (value.type === 'ConditionalExpression') {
+			return referencesHook(value.consequent, seen) || referencesHook(value.alternate, seen);
+		}
+		if (value.type === 'LogicalExpression') {
+			return referencesHook(value.left, seen) || referencesHook(value.right, seen);
+		}
+		if (
+			value.type === 'CallExpression' &&
+			value.optional !== true &&
+			value.arguments.length === 0
+		) {
+			const binding = directCallBinding(value, analysis.nodeScopes.get(value));
+			const factory = factories.get(binding);
+			if (!factory || factory.params.length !== 0 || seen.has(binding)) return false;
+			seen.add(binding);
+			const body = factory.body;
+			return referencesHook(
+				body.type === 'BlockStatement'
+					? body.body.length === 1 && body.body[0].type === 'ReturnStatement'
+						? body.body[0].argument
+						: null
+					: body,
+				seen,
+			);
+		}
+		return false;
+	}
+	for (const { call, scope } of analysis.calls) {
+		if (call.optional === true || call.callee.type !== 'Identifier') continue;
+		const binding = directCallBinding(call, scope);
+		if (!values.has(binding) || !referencesHook(values.get(binding), new Set([binding]))) continue;
+		analysis.callAnnotations.set(call, {
+			...analysis.callAnnotations.get(call),
+			_octaneCustomHookCall: binding.name,
+		});
+	}
+}
+
 function collectPatternBindings(pattern, scope, into) {
 	if (!pattern) return;
 	if (pattern.type === 'Identifier') {

package/dist/compiler/hook-names.js

@@ -17,6 +17,7 @@ export const HOOK_NAMES = new Set([
 	'useSyncExternalStore',
 	// React 19 Actions bundle.
 	'useActionState',
+	'useFormState',
 	'useFormStatus',
 	'useOptimistic',
 ]);

package/dist/compiler/hydrate-boundaries.js

@@ -30,7 +30,14 @@ function inheritGeneratedOrigin(root, origin) {
 			for (const item of value) visit(item);
 			return;
 		}
-		if (typeof value.type === 'string' && value.loc == null && origin?.loc != null) {
+		// Adopted parser nodes (including StyleSheet subtrees) may be frozen
+		// and already carry CSS-relative positions; only stamp generated nodes.
+		if (
+			typeof value.type === 'string' &&
+			value.loc == null &&
+			origin?.loc != null &&
+			!Object.isFrozen(value)
+		) {
 			value.start = origin.start;
 			value.end = origin.end;
 			value.loc = origin.loc;
@@ -440,6 +447,161 @@ function isHookCall(node, hookNames) {
 	);
 }
 
+function collectSubtreeNodes(value, output) {
+	if (!value || typeof value !== 'object') return;
+	if (Array.isArray(value)) {
+		for (const child of value) collectSubtreeNodes(child, output);
+		return;
+	}
+	if (output.has(value)) return;
+	output.add(value);
+	for (const [key, child] of Object.entries(value)) {
+		if (!SKIP_KEYS.has(key)) collectSubtreeNodes(child, output);
+	}
+}
+
+function subtreeContainsNode(root, target) {
+	if (root === target) return true;
+	const seen = new WeakSet();
+	const visit = (value) => {
+		if (!value || typeof value !== 'object') return false;
+		if (Array.isArray(value)) {
+			for (const child of value) {
+				if (visit(child)) return true;
+			}
+			return false;
+		}
+		if (seen.has(value)) return false;
+		seen.add(value);
+		if (value === target) return true;
+		for (const [key, child] of Object.entries(value)) {
+			if (!SKIP_KEYS.has(key) && visit(child)) return true;
+		}
+		return false;
+	};
+	return visit(root);
+}
+
+function collectOwnStyleBlocks(nodes) {
+	const blocks = [];
+	for (const node of nodes ?? []) {
+		if (node?.type === 'JSXStyleElement' && !isFloatStyleResource(node)) blocks.push(node);
+	}
+	return blocks;
+}
+
+function isFloatStyleResource(node) {
+	let hasHref = false;
+	let hasPrecedence = false;
+	for (const attribute of node.openingElement?.attributes ?? []) {
+		if (attribute?.type !== 'JSXAttribute' && attribute?.type !== 'Attribute') continue;
+		const name = jsxAttributeName(attribute);
+		if (name === 'href') hasHref = true;
+		else if (name === 'precedence') hasPrecedence = true;
+	}
+	return hasHref && hasPrecedence;
+}
+
+function isStampableHost(node) {
+	if (node?.type !== 'JSXElement' && node?.type !== 'Element') return false;
+	if (node.metadata?.dynamicElement) return true;
+	const name = node.openingElement?.name ?? node.name;
+	if (!name) return false;
+	if (name.type === 'JSXIdentifier' || name.type === 'Identifier') {
+		return name.name !== 'style' && !/^[A-Z]/.test(name.name);
+	}
+	// Namespaced hosts (`svg:rect`) are stamped by the style-scope pass;
+	// member expressions are composites and are not.
+	return name.type === 'JSXNamespacedName' || name.type === 'NamespacedName';
+}
+
+function walkStampableHosts(node, visitHost) {
+	if (!node || typeof node !== 'object') return;
+	if (Array.isArray(node)) {
+		for (const child of node) walkStampableHosts(child, visitHost);
+		return;
+	}
+	if (isFunction(node)) return;
+	if (isStampableHost(node)) visitHost(node);
+	for (const [key, child] of Object.entries(node)) {
+		if (!SKIP_KEYS.has(key)) walkStampableHosts(child, visitHost);
+	}
+}
+
+/**
+ * A children list that holds standalone `<style>` blocks is one lexical style
+ * scope (plan S8.5 / RFC sibling scopes). Extraction is safe when that whole
+ * scope — its blocks and the host elements they stamp — sits inside the split
+ * boundary, because both compiles keep the authored-position hash. A scope
+ * that has blocks or stamped hosts on both sides of the boundary would emit
+ * disagreeing class lists; that is still `OCTANE_HYDRATE_SPLIT_STYLE`. Styles
+ * nested in functions never joined the enclosing scopes and are not checked.
+ */
+function styleScopeStraddlesBoundary(list, own, inside) {
+	let hasInside = false;
+	let hasOutside = false;
+	const mark = (node) => {
+		if (inside.has(node)) hasInside = true;
+		else hasOutside = true;
+	};
+	for (const block of own) mark(block);
+	for (const item of list) {
+		if (own.includes(item)) continue;
+		walkStampableHosts(item, mark);
+	}
+	return hasInside && hasOutside;
+}
+
+function assertHydrateStyleScopes(boundary, filename) {
+	const inside = new WeakSet();
+	collectSubtreeNodes(boundary.node.children, inside);
+	const seenLists = new WeakSet();
+	const seen = new WeakSet();
+	const visit = (node, inFunction) => {
+		if (!node || typeof node !== 'object') return;
+		if (Array.isArray(node)) {
+			for (const child of node) visit(child, inFunction);
+			return;
+		}
+		if (seen.has(node)) return;
+		seen.add(node);
+		if (TRANSPARENT_TS_EXPRESSIONS.has(node.type)) {
+			visit(node.expression, inFunction);
+			return;
+		}
+		if (!inFunction && isFunction(node)) {
+			const nested = !subtreeContainsNode(node, boundary.node);
+			for (const [key, child] of Object.entries(node)) {
+				if (!SKIP_KEYS.has(key)) visit(child, nested);
+			}
+			return;
+		}
+		if (
+			!inFunction &&
+			(node.type === 'JSXElement' || node.type === 'JSXFragment' || node.type === 'Element') &&
+			Array.isArray(node.children)
+		) {
+			const own = collectOwnStyleBlocks(node.children);
+			if (own.length > 0 && !seenLists.has(node.children)) {
+				seenLists.add(node.children);
+				if (styleScopeStraddlesBoundary(node.children, own, inside)) {
+					const reported = own.find((block) => inside.has(block)) ?? own[0];
+					throw extractionError(
+						'OCTANE_HYDRATE_SPLIT_STYLE',
+						filename,
+						reported,
+						'a scoped <style> cannot straddle a split Hydrate boundary — its style scope has blocks or stamped elements on both sides. Keep the whole scope inside the boundary, move it entirely outside, extract a child component, or set `split={false}`',
+					);
+				}
+			}
+		}
+		for (const [key, child] of Object.entries(node)) {
+			if (!SKIP_KEYS.has(key)) visit(child, inFunction);
+		}
+	};
+	visit(boundary.ast ?? boundary.node, false);
+}
+
 function validateBoundary(boundary, filename, hookNames) {
 	for (const child of boundary.node.children ?? []) {
 		if (child?.type === 'JSXExpressionContainer' && isFunction(child.expression)) {
@@ -489,20 +651,6 @@ function validateBoundary(boundary, filename, hookNames) {
 				'direct hook calls cannot move into a split child. Call the hook in a child component or set `split={false}`',
 			);
 		}
-		// `directHooks` also marks the owning component's direct render scope: a
-		// scoped <style> there belongs to that component's single style scope,
-		// which extraction would tear in half (the server annotates the whole
-		// component with one scope hash; the split chunk would compile the sheet
-		// under another). Styles nested inside functions never joined the
-		// component scope, so they move freely.
-		if (directHooks && node.type === 'JSXStyleElement') {
-			throw extractionError(
-				'OCTANE_HYDRATE_SPLIT_STYLE',
-				filename,
-				node,
-				'a scoped <style> cannot move into a split child — its rules belong to the owning component’s style scope. Move the <style> outside the boundary, into a child component, or set `split={false}`',
-			);
-		}
 		if (isFunction(node)) {
 			// A nested function keeps hook calls in its own invocation. Ordinary
 			// functions also bind their own receiver; arrows still capture `this`
@@ -530,6 +678,7 @@ function validateBoundary(boundary, filename, hookNames) {
 		}
 	};
 	visit(boundary.node.children);
+	assertHydrateStyleScopes(boundary, filename);
 }
 
 /** Resolve Hydrate boundaries and assign source-order paths under their nearest boundary. */
@@ -1607,6 +1756,7 @@ export function prepareHydrateBoundaries(source, filename, boundaryPath = null,
 	for (const boundary of analysis.boundaries) {
 		boundary.filename = filename;
 		boundary.hookNames = analysis.imports.hookNames;
+		boundary.ast = analysis.ast;
 	}
 	const request = sameSourceRequest(filename);
 	const moduleMovePlan = createModuleMovePlanAst(analysis, request);

package/dist/compiler/manual-hooks.js

@@ -0,0 +1,171 @@
+// Manual hook packages own their explicit sub-slot layout. Adapt exported or
+// escaping hook definitions at their owner, so bound/forwarded imports retain
+// that protocol without changing ordinary custom-hook argument lists.
+import { builders as b } from '@tsrx/core';
+
+const META = new Set([
+	'loc',
+	'start',
+	'end',
+	'range',
+	'metadata',
+	'parent',
+	'comments',
+	'leadingComments',
+	'trailingComments',
+	'innerComments',
+]);
+const isHook = (name) =>
+	typeof name === 'string' && /^(?:(?:experimental|unstable|UNSTABLE)_)?use[A-Z]/.test(name);
+const isFunction = (node) =>
+	node?.type === 'FunctionDeclaration' ||
+	node?.type === 'FunctionExpression' ||
+	node?.type === 'ArrowFunctionExpression';
+
+function children(node, visit) {
+	for (const key in node) {
+		if (META.has(key) || key.startsWith('_octane')) continue;
+		const value = node[key];
+		if (Array.isArray(value)) for (const child of value) visit(child, node, key);
+		else if (value && typeof value === 'object') visit(value, node, key);
+	}
+}
+
+export function findManualHookProviders(ast) {
+	const escaping = new Set();
+	const definitions = new Map();
+	function scan(node, parent, key) {
+		if (!node || typeof node !== 'object') return;
+		if (isFunction(node) && node.body) {
+			const bindingName = parent?.type === 'VariableDeclarator' ? parent.id?.name : undefined;
+			const name = isHook(bindingName) ? bindingName : node.id?.name;
+			if (isHook(name)) {
+				// A named expression can have a private implementation name while its
+				// exported binding establishes the hook contract. Keep its public
+				// Function.name when installing the provider boundary.
+				definitions.set(node, { name, displayName: node.id?.name ?? name });
+				if (
+					parent?.type === 'ExportNamedDeclaration' ||
+					parent?.type === 'ExportDefaultDeclaration'
+				)
+					escaping.add(name);
+				if (parent?.type === 'ReturnStatement') escaping.add(name);
+			}
+		}
+		if (node.type === 'Identifier' && isHook(node.name)) {
+			const binding =
+				(isFunction(parent) && (key === 'id' || key === 'params')) ||
+				(parent?.type === 'VariableDeclarator' && key === 'id') ||
+				parent?.type === 'ImportSpecifier' ||
+				parent?.type === 'ImportDefaultSpecifier' ||
+				parent?.type === 'ImportNamespaceSpecifier';
+			const directCall = parent?.type === 'CallExpression' && key === 'callee';
+			const property =
+				(parent?.type === 'MemberExpression' && key === 'property' && !parent.computed) ||
+				(parent?.type === 'Property' && key === 'key' && !parent.computed);
+			if (!binding && !directCall && !property) escaping.add(node.name);
+		}
+		if (
+			node.type === 'ExportNamedDeclaration' &&
+			node.declaration?.type === 'VariableDeclaration'
+		) {
+			for (const declaration of node.declaration.declarations) {
+				if (isHook(declaration.id?.name)) escaping.add(declaration.id.name);
+			}
+		}
+		children(node, scan);
+	}
+	scan(ast, null, null);
+	return new Map(
+		[...definitions]
+			.filter(([, { name }]) => escaping.has(name))
+			.map(([node, { displayName }]) => [node, displayName]),
+	);
+}
+
+function declarationOf(statement) {
+	return statement?.type === 'ExportNamedDeclaration' ||
+		statement?.type === 'ExportDefaultDeclaration'
+		? statement.declaration
+		: statement;
+}
+
+// Only the parameters before the first default/rest contribute to Function.length.
+// The public wrapper must not evaluate authored defaults or destructuring; the
+// private implementation receives the original arguments after slot adaptation.
+export function manualHookWrapperParameters(node) {
+	const parameters = [];
+	for (const param of node.params) {
+		if (param.type === 'Identifier' && param.name === 'this') continue;
+		if (param.type === 'AssignmentPattern' || param.type === 'RestElement') break;
+		parameters.push(b.id(`_$arg${parameters.length}`));
+	}
+	return parameters;
+}
+
+export function adaptManualHookProviders(ast, requireHelper, allocateName) {
+	const providers = findManualHookProviders(ast);
+	if (!providers.size) return ast;
+	function visit(node) {
+		if (!node || typeof node !== 'object') return node;
+		if (Array.isArray(node)) {
+			let changed = false;
+			const result = node.map((item) => {
+				const next = visit(item);
+				changed ||= next !== item;
+				return next;
+			});
+			return changed ? result : node;
+		}
+		let result = node;
+		for (const key in node) {
+			if (META.has(key) || key.startsWith('_octane')) continue;
+			const value = node[key];
+			if (!value || typeof value !== 'object') continue;
+			const next = visit(value);
+			if (next !== value) {
+				if (result === node) result = { ...node };
+				result[key] = next;
+			}
+		}
+		if (node.type === 'Program' || node.type === 'BlockStatement') {
+			let changed = false;
+			const body = result.body.flatMap((statement, index) => {
+				const original = declarationOf(node.body[index]);
+				if (original?.type !== 'FunctionDeclaration' || !providers.has(original))
+					return [statement];
+				changed = true;
+				const declaration = declarationOf(statement);
+				const implementation = allocateName(`_$manual_${original.id.name}`);
+				const wrapper = b.function_declaration(
+					original.id,
+					manualHookWrapperParameters(original),
+					b.block([
+						b.return(
+							b.call(
+								requireHelper('invokeManualHook'),
+								b.id(implementation),
+								b.this,
+								b.id('arguments'),
+							),
+						),
+					]),
+				);
+				// Both declarations hoist. Keep the exported binding stable even for
+				// cyclic imports and aliases captured before the textual declaration.
+				return [
+					statement === declaration ? wrapper : { ...statement, declaration: wrapper },
+					{ ...declaration, id: b.id(implementation) },
+				];
+			});
+			if (changed) result = { ...result, body };
+		}
+		return providers.has(node) && node.type !== 'FunctionDeclaration'
+			? {
+					...b.call(requireHelper('manualHook'), result, b.literal(providers.get(node))),
+					__octanePure: true,
+				}
+			: result;
+	}
+	return visit(ast);
+}

package/dist/compiler/parser.node.js

@@ -40,9 +40,41 @@ function publishOutput(options, selected) {
 	}
 }
 
+/**
+ * `<style>` with an expression child — `<style>{css}</style>`, an ordinary
+ * element rather than a scoped block. The compat facade reads every `<style>`
+ * element's raw text as CSS after its own error translation, so this shape
+ * surfaces as a bare `Error` from that CSS reader instead of a `SyntaxError`.
+ */
+const STYLE_EXPRESSION_CHILD = /<style\b[^>]*>\s*\{/;
+
+/**
+ * A native rejection the JavaScript parser may still accept: a `SyntaxError`
+ * the facade translated, or the bare `Error` its CSS reader raises for a
+ * `<style>` expression child. Operational failures keep their own name or
+ * code and stay visible, and so does any other bare `Error`: without the
+ * `<style …>{` shape in the source there is nothing the CSS reader could have
+ * rejected.
+ * @param {unknown} error
+ * @param {string} source
+ * @returns {boolean}
+ */
+function isNativeSyntaxRejection(error, source) {
+	if (!(error instanceof Error)) return false;
+	if (error.name === 'ParserOperationalError') return false;
+	if ('code' in error && typeof error.code === 'string' && error.code.startsWith('ERR_TSRX_')) {
+		return false;
+	}
+	if (error instanceof SyntaxError) return true;
+	return (
+		error.name === 'Error' && error.constructor === Error && STYLE_EXPRESSION_CHILD.test(source)
+	);
+}
+
 /**
  * Keep native parsing first while accepting authored syntax already supported
- * by the JavaScript parser, such as literal less-than text in TSRX children.
+ * by the JavaScript parser, such as literal less-than text in TSRX children
+ * or a `<style>` element with an expression child.
  * @param {string} source
  * @param {string} [filename]
  * @param {ParseOptions} [options]
@@ -56,13 +88,7 @@ export function parseModule(source, filename = 'module.tsrx', options) {
 		program = parseNativeModule(source, resolvedFilename, nativeOptions);
 	} catch (nativeError) {
 		// Operational failures must stay visible, even if given a syntax subclass.
-		if (
-			!(nativeError instanceof SyntaxError) ||
-			nativeError.name === 'ParserOperationalError' ||
-			('code' in nativeError &&
-				typeof nativeError.code === 'string' &&
-				nativeError.code.startsWith('ERR_TSRX_'))
-		) {
+		if (!isNativeSyntaxRejection(nativeError, source)) {
 			publishOutput(options, nativeOptions);
 			throw nativeError;
 		}