octane 0.2.2 → 0.2.3

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/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/plain-hook-memo.js

@@ -7,6 +7,7 @@ import { print as esrapPrint } from 'esrap';
 import esrapTsx from 'esrap/languages/tsx';
 import { METHOD_DEP_IMPORT } from './hook-deps.js';
 import { nativeReadActivationIndex } from './native-read-codegen.js';
+import { adaptManualHookProviders } from './manual-hooks.js';
 import {
 	hasInlineMemoDirectEval,
 	inheritHookMemoOrigin,
@@ -126,13 +127,32 @@ function inferredDependencyArray(inferred, state, origin) {
 	);
 }
 
-// Match the surgical pass's BASE-hook-only policy. Custom hooks remain normal
-// calls; their compiled caller owns withSlot. Existing explicit memo slots are
+// Match the surgical pass's base-hook and imported-hook slot policy. Local
+// custom helpers keep their authored boundaries. Existing explicit memo slots are
 // already the effective third argument, so no unused fourth argument is added.
 function slotBaseHooks(ast, state, options) {
 	function visit(node) {
 		if (node === null || typeof node !== 'object') return node;
 		if (Array.isArray(node)) return mapChildren(node, visit);
+		if (!options.manualSlots && node.type === 'CallExpression' && node._octaneCustomHookCall) {
+			const slot = allocateHookSlot(state, node);
+			const mapped = mapChildren(node, visit);
+			const callee = mapped.typeArguments
+				? {
+						type: 'TSInstantiationExpression',
+						expression: mapped.callee,
+						typeArguments: mapped.typeArguments,
+					}
+				: mapped.callee;
+			return {
+				...mapped,
+				callee: b.id(requireHelper(state, 'withSlot', 'octane'), node),
+				typeArguments: null,
+				// Keep foreign/default parameters and arguments.length unchanged;
+				// Octane base aliases resolve their slot from this call's path.
+				arguments: [slot, callee, ...mapped.arguments],
+			};
+		}
 		const imported =
 			node.type === 'CallExpression'
 				? (node._octaneImportedHook ??
@@ -147,13 +167,12 @@ function slotBaseHooks(ast, state, options) {
 			inferred === undefined &&
 			node.arguments.length === 3 &&
 			!node.arguments.some((argument) => argument.type === 'SpreadElement');
-		const slot = explicitMemoSlot ? null : allocateHookSlot(state, node);
+		const slot = options.manualSlots || explicitMemoSlot ? null : allocateHookSlot(state, node);
 		const mapped = mapChildren(node, visit);
 		const args = mapped.arguments.slice();
 		if (inferred !== undefined) {
 			args.splice(inferred.depsIndex, 0, inferredDependencyArray(inferred, state, node));
 		}
-		if (slot !== null) args.push(slot);
 		let callee = mapped.callee;
 		if (options.getterCalls.has(node) && options.stateGetterHelpers[imported]) {
 			callee = b.id(requireHelper(state, options.stateGetterHelpers[imported], 'octane'), node);
@@ -161,6 +180,29 @@ function slotBaseHooks(ast, state, options) {
 		if (node._octaneNativeInferredMemo === true) {
 			callee = b.id(requireHelper(state, 'nativePuMemo'), node);
 		}
+		if (slot !== null) {
+			if (
+				(imported === 'useState' || imported === 'useRef') &&
+				args.some((arg) => arg.type === 'SpreadElement')
+			) {
+				const fn = mapped.typeArguments
+					? {
+							type: 'TSInstantiationExpression',
+							expression: callee,
+							typeArguments: mapped.typeArguments,
+						}
+					: callee;
+				return {
+					...mapped,
+					callee: b.id(requireHelper(state, 'withSlot', 'octane'), node),
+					typeArguments: null,
+					arguments: [slot, fn, ...args],
+				};
+			}
+			if (args.length === 0 && (imported === 'useState' || imported === 'useRef'))
+				args.push(b.id('undefined', node));
+			args.push(slot);
+		}
 		return { ...mapped, callee, arguments: args };
 	}
 	return visit(ast);
@@ -235,7 +277,7 @@ export function inlinePlainHookMemos(ast, source, id, options) {
 		slotBase: null,
 		slotDeclarations: [],
 	};
-	let transformed = options.manualSlots ? ast : slotBaseHooks(ast, state, options);
+	let transformed = slotBaseHooks(ast, state, options);
 	const lowered = lowerSlotMemoFunctions(transformed, {
 		allocateName: (preferred) => allocName(state, preferred),
 		requireRuntime: (imported) => requireHelper(state, imported),
@@ -243,6 +285,13 @@ export function inlinePlainHookMemos(ast, source, id, options) {
 	});
 	if (lowered.lowered === 0) return null;
 	transformed = lowered.ast;
+	if (options.manualSlots) {
+		transformed = adaptManualHookProviders(
+			transformed,
+			(name) => requireHelper(state, name, 'octane'),
+			(preferred) => allocName(state, preferred),
+		);
+	}
 	const origin = ast.body[0] ?? ast;
 	const activation = options.nativeReadActivation
 		? inheritHookMemoOrigin(

package/dist/compiler/slot-hooks.d.ts

@@ -0,0 +1,43 @@
+import type { CompilerProgram, CompileSourceMap } from './index.js';
+
+/** Options for the plain-module hook transform used by compiler adapters. */
+export interface SlotHooksOptions {
+	environment?: 'client' | 'server';
+	strong?: boolean;
+	nativeReads?: boolean;
+	hmr?: boolean;
+	dev?: boolean;
+	profile?: boolean;
+	profileFilename?: string;
+	inlineHookMemo?: boolean;
+	manualSlots?: boolean;
+	/** Opaque activation signal; the transform only checks its presence. */
+	universalRuntime?: unknown;
+	renderer?: { target?: string };
+	isVoidComponentImport?: (request: string, imported: string) => boolean;
+}
+
+export interface SlotHooksResult {
+	code: string;
+	/** The surgical transform preserves source lines and returns no map. */
+	map: CompileSourceMap | null;
+}
+
+export interface VoidComponentImport {
+	request: string;
+	imported: string;
+}
+
+/** Returns null when the module can pass through unchanged. */
+export function slotHooks(
+	source: string,
+	id: string,
+	options?: SlotHooksOptions,
+): SlotHooksResult | null;
+
+export function findVoidRootImports(source: string, id: string): VoidComponentImport[];
+
+export function findVoidComponentImports(
+	source: string | CompilerProgram,
+	id: string,
+): VoidComponentImport[];