octane 0.2.12 → 0.2.13

package/dist/compiler/signal-start-reads.js

@@ -0,0 +1,413 @@
+import { builders as b } from '@tsrx/core';
+import { createLexicalAnalysis } from './compile-universal.js';
+import { inheritHookMemoOrigin } from './inline-hook-memo.js';
+
+const SIGNAL_MODULES = new Set([
+	'octane/signals',
+	'octane/signals/client',
+	'octane/signals/server',
+]);
+const METADATA = new Set([
+	'loc',
+	'start',
+	'end',
+	'range',
+	'metadata',
+	'parent',
+	'comments',
+	'leadingComments',
+	'trailingComments',
+	'innerComments',
+]);
+
+function children(node, visit) {
+	for (const key in node) {
+		if (METADATA.has(key) || key.startsWith('_octane')) continue;
+		const value = node[key];
+		if (Array.isArray(value)) {
+			for (const child of value) if (child?.type) visit(child);
+		} else if (value?.type) visit(value);
+	}
+}
+
+function unwrap(node) {
+	while (
+		[
+			'TSAsExpression',
+			'TSTypeAssertion',
+			'TSSatisfiesExpression',
+			'TSNonNullExpression',
+			'ParenthesizedExpression',
+		].includes(node?.type)
+	)
+		node = node.expression;
+	return node;
+}
+
+function isFunction(node) {
+	return ['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'].includes(
+		node.type,
+	);
+}
+
+function hasRender(node) {
+	if (node.type.startsWith('JSX')) return true;
+	if (isFunction(node)) return false;
+	let found = false;
+	children(node, (child) => {
+		found ||= hasRender(child);
+	});
+	return found;
+}
+
+/**
+ * Start adjacent strict reads or complete static native output reads of
+ * lexically proven immutable descriptors.
+ * Original reads remain the suspension/error/observation points. In particular,
+ * this does not hoist declarations, evaluate member receivers, cross statements,
+ * or enter a conditional arm before its authored control-flow boundary.
+ */
+export function startIndependentSignalReads(ast, isText = null) {
+	if (
+		!(ast.body ?? []).some(
+			(node) => node.type === 'ImportDeclaration' && SIGNAL_MODULES.has(node.source?.value),
+		)
+	)
+		return ast;
+	const lexical = createLexicalAnalysis(ast);
+	const imports = new Map();
+	const declarations = new Map();
+	const names = new Set();
+	const binding = (node) =>
+		node?.type === 'Identifier'
+			? lexical.resolveBinding(lexical.nodeScopes.get(node) ?? lexical.rootScope, node.name)
+			: null;
+	const recordFor = (node) => declarations.get(binding(node)?.scope)?.get(node.name);
+	function register(id, record, declarationScope) {
+		if (id?.type !== 'Identifier') return;
+		const scope = declarationScope
+			? lexical.resolveBinding(declarationScope, id.name)?.scope
+			: binding(id)?.scope;
+		if (!scope) return;
+		let records = declarations.get(scope);
+		if (!records) declarations.set(scope, (records = new Map()));
+		records.set(id.name, record);
+	}
+	function collect(node, ownerFunction = null) {
+		if (node.type === 'Identifier') names.add(node.name);
+		if (
+			node.type === 'ImportDeclaration' &&
+			node.importKind !== 'type' &&
+			SIGNAL_MODULES.has(node.source?.value)
+		) {
+			for (const specifier of node.specifiers ?? []) {
+				if (specifier.importKind === 'type') continue;
+				const factory = specifier.imported?.name ?? specifier.imported?.value;
+				if (
+					factory === 'query$' ||
+					factory === 'derived$' ||
+					specifier.type === 'ImportNamespaceSpecifier'
+				)
+					imports.set(specifier.local.name, {
+						factory,
+						source: node.source.value,
+						declaration: node,
+					});
+			}
+		}
+		if (node.type === 'VariableDeclaration') {
+			for (const declaration of node.declarations)
+				register(declaration.id, {
+					init: declaration.init,
+					kind: node.kind,
+					declaration,
+					ownerFunction,
+				});
+		} else if (node.type === 'FunctionDeclaration')
+			register(
+				node.id,
+				{ init: node, kind: 'function', declaration: node },
+				lexical.nodeScopes.get(node),
+			);
+		children(node, (child) => collect(child, isFunction(node) ? node : ownerFunction));
+	}
+	collect(ast);
+	// Initializer reachability is insufficient when a selector was reassigned or
+	// installed in a mutable object. Fence any result captured by an already
+	// available closure, without attempting heap or assignment reconstruction.
+	const capturedResults = new Map();
+	const opaqueFunctions = new Set();
+	function collectCaptures(node, stack = []) {
+		const nested =
+			isFunction(node) || node.type === 'ClassDeclaration' || node.type === 'ClassExpression'
+				? [...stack, node]
+				: stack;
+		if (node.type === 'Identifier' && !lexical.bindingNodes.has(node)) {
+			const record = recordFor(node);
+			const owner = record?.ownerFunction;
+			const index = owner ? nested.indexOf(owner) : -1;
+			const closure = index < 0 ? null : nested[index + 1];
+			if (closure) {
+				let captured = capturedResults.get(record);
+				if (!captured) capturedResults.set(record, (captured = new Set()));
+				captured.add(closure);
+			}
+		}
+		const callee = unwrap(node.callee);
+		if (
+			(node.type === 'CallExpression' || node.type === 'NewExpression') &&
+			callee?.type === 'Identifier' &&
+			(callee.name === 'eval' || callee.name === 'Function')
+		) {
+			for (const owner of nested) opaqueFunctions.add(owner);
+		}
+		children(node, (child) => collectCaptures(child, nested));
+	}
+	collectCaptures(ast);
+	function capturedBefore(result, position) {
+		for (const closure of capturedResults.get(recordFor(result)) ?? []) {
+			if (
+				closure.type === 'FunctionDeclaration' ||
+				(closure.start ?? -Infinity) < (position ?? Infinity)
+			)
+				return true;
+		}
+		return false;
+	}
+	function factoryOf(init) {
+		const call = unwrap(init);
+		if (call?.type !== 'CallExpression' || call.optional) return null;
+		const callee = unwrap(call.callee);
+		const identifier =
+			callee?.type === 'Identifier'
+				? callee
+				: callee?.type === 'MemberExpression' && !callee.computed && !callee.optional
+					? callee.object
+					: null;
+		if (identifier?.type !== 'Identifier') return null;
+		const record = imports.get(identifier.name);
+		const resolved = binding(identifier);
+		if (
+			!record ||
+			resolved?.scope !== lexical.rootScope ||
+			resolved.importSource?.value !== record.source
+		)
+			return null;
+		const factory =
+			callee === identifier
+				? record.factory
+				: record.factory === undefined
+					? callee.property.name
+					: null;
+		return factory === 'query$' || factory === 'derived$' ? record : null;
+	}
+	function strictExpression(expression) {
+		const call = unwrap(expression);
+		if (call?.type !== 'CallExpression' || call.optional || call.arguments.length !== 0)
+			return null;
+		const member = unwrap(call.callee);
+		if (
+			member?.type !== 'MemberExpression' ||
+			member.optional ||
+			member.computed ||
+			member.property.name !== 'get' ||
+			member.object.type !== 'Identifier'
+		)
+			return null;
+		const descriptor = recordFor(member.object);
+		if (descriptor?.kind !== 'const') return null;
+		const factory = factoryOf(descriptor.init);
+		return factory ? { handle: member.object, descriptor, factory } : null;
+	}
+	function strictRead(statement) {
+		if (
+			statement.type !== 'VariableDeclaration' ||
+			statement.kind !== 'const' ||
+			statement.declarations.length !== 1
+		)
+			return null;
+		const declaration = statement.declarations[0];
+		if (declaration.id.type !== 'Identifier') return null;
+		const read = strictExpression(declaration.init);
+		return read ? { ...read, result: declaration.id } : null;
+	}
+	// Only complete static native output is traversed. Mount phases can evaluate
+	// an attribute or typed text before an earlier generic child, so a lexical
+	// prefix before an opaque node (or a mix of hole kinds) is not sufficient.
+	function outputReads(output) {
+		if (isText === null) return [];
+		const reads = [];
+		let text;
+		function visit(node) {
+			if (node.type === 'JSXText') return true;
+			if (node.type === 'JSXExpressionContainer') {
+				if (node.expression.type === 'JSXEmptyExpression') return true;
+				const read = strictExpression(node.expression);
+				if (read === null) return false;
+				const kind = isText(node.expression);
+				if (text !== undefined && text !== kind) return false;
+				text = kind;
+				reads.push(read);
+				return true;
+			}
+			if (node.type === 'JSXElement') {
+				const opening = node.openingElement;
+				const tag = opening.name;
+				if (
+					tag.type !== 'JSXIdentifier' ||
+					!/^[a-z][a-z0-9]*$/.test(tag.name) ||
+					/^(?:html|head|body|base|meta|link|title|style|script|template|noscript|svg|math|input|select|textarea|option|optgroup|iframe|object|embed|img|image|audio|video|source|track)$/.test(
+						tag.name,
+					)
+				)
+					return false;
+				for (const attribute of opening.attributes ?? []) {
+					if (
+						attribute.type !== 'JSXAttribute' ||
+						attribute.name.type !== 'JSXIdentifier' ||
+						/^(?:ref|key|is|style|children|innerHTML|dangerouslySetInnerHTML|on.*)$/i.test(
+							attribute.name.name,
+						) ||
+						(attribute.value !== null && attribute.value.type !== 'Literal')
+					)
+						return false;
+				}
+			} else if (node.type !== 'JSXFragment') return false;
+			return (node.children ?? []).every(visit);
+		}
+		return output && visit(output) ? reads : [];
+	}
+	// Follow local aliases/helpers as well as direct captures: a later selector
+	// closing over an earlier read's result must run after that result is assigned.
+	function dependsOn(node, results, seen = new Set()) {
+		if (!node || seen.has(node)) return false;
+		seen.add(node);
+		if (node.type === 'Identifier' && !lexical.bindingNodes.has(node)) {
+			const resolved = binding(node);
+			if (
+				results.some(
+					(result) => result.name === node.name && binding(result)?.scope === resolved?.scope,
+				)
+			)
+				return true;
+			if (dependsOn(recordFor(node)?.init, results, seen)) return true;
+		}
+		let found = false;
+		children(node, (child) => {
+			found ||= dependsOn(child, results, seen);
+		});
+		return found;
+	}
+	let helperName = '_$startSignalReads';
+	while (names.has(helperName)) helperName += '$';
+	let helperImport = null;
+	function start(reads, origin, primitive = false) {
+		helperImport ??= reads[0].factory.declaration;
+		return inheritHookMemoOrigin(
+			// Guard only speculative receiver evaluation (including module TDZ).
+			// The original reads retain their normal observation/error boundary.
+			b.try(
+				b.block([
+					b.stmt(
+						b.call(
+							b.id(helperName),
+							b.array(reads.map((read) => b.id(read.handle.name))),
+							...(primitive ? [b.literal(true)] : []),
+						),
+					),
+				]),
+				b.catch_clause(null, null, b.block([])),
+			),
+			origin,
+		);
+	}
+	function statements(body) {
+		let out = null;
+		for (let i = 0; i < body.length;) {
+			const first = strictRead(body[i]);
+			if (!first) {
+				const reads = outputReads(body[i]);
+				if (reads.length > 1) {
+					out ??= body.slice(0, i);
+					out.push(start(reads, body[i], true));
+				}
+				if (out) out.push(body[i]);
+				i++;
+				continue;
+			}
+			const run = [first];
+			let end = i + 1;
+			for (; end < body.length; end++) {
+				const next = strictRead(body[end]);
+				if (
+					!next ||
+					run.some((read) => capturedBefore(read.result, body[i].start)) ||
+					dependsOn(
+						next.descriptor.init,
+						run.map((read) => read.result),
+					)
+				)
+					break;
+				run.push(next);
+			}
+			if (run.length > 1) {
+				out ??= body.slice(0, i);
+				out.push(start(run, body[i]));
+			}
+			if (out) out.push(...body.slice(i, end));
+			i = end;
+		}
+		return out ?? body;
+	}
+	function transform(node, rendering = false, functionBody = false) {
+		if (node === null || typeof node !== 'object') return node;
+		if (Array.isArray(node)) {
+			const mapped = node.map((child) => transform(child, rendering));
+			return mapped.some((child, index) => child !== node[index]) ? mapped : node;
+		}
+		if (isFunction(node)) rendering = !opaqueFunctions.has(node) && hasRender(node.body);
+		let out = node;
+		for (const key in node) {
+			if (METADATA.has(key) || key.startsWith('_octane')) continue;
+			const mapped = transform(node[key], rendering, isFunction(node) && key === 'body');
+			if (mapped !== node[key]) {
+				if (out === node) out = { ...node };
+				out[key] = mapped;
+			}
+		}
+		if (
+			rendering &&
+			(node.type === 'BlockStatement' || node.type === 'JSXCodeBlock') &&
+			Array.isArray(node.body)
+		) {
+			// Analyze original nodes, whose lexical binding identities are known.
+			const body = statements(node.body);
+			if (body !== node.body) {
+				const mapped = new Map(node.body.map((statement, index) => [statement, out.body[index]]));
+				out = { ...out, body: body.map((statement) => mapped.get(statement) ?? statement) };
+			}
+			// Do not turn a transparent render-only child block into a new scope.
+			if (node.type === 'JSXCodeBlock' && (functionBody || node.body.length > 0)) {
+				const reads = outputReads(node.render);
+				if (reads.length > 1)
+					out = { ...out, body: [...out.body, start(reads, node.render, true)] };
+			}
+		}
+		return out;
+	}
+	const lowered = transform(ast);
+	if (helperImport === null) return ast;
+	return {
+		...lowered,
+		body: lowered.body.flatMap((statement) => {
+			if (statement !== helperImport) return [statement];
+			const helper = inheritHookMemoOrigin(
+				b.import_specifier('__startSignalReads', helperName),
+				statement,
+			);
+			return statement.specifiers.some((specifier) => specifier.type === 'ImportNamespaceSpecifier')
+				? [statement, { ...statement, specifiers: [helper] }]
+				: [{ ...statement, specifiers: [...statement.specifiers, helper] }];
+		}),
+	};
+}

package/dist/compiler/slot-hooks.js

@@ -26,6 +26,7 @@ import { nativeReadActivationIndex } from './native-read-codegen.js';
 import { findManualHookProviders, manualHookWrapperParameters } from './manual-hooks.js';
 import { findLeadingJsxImportSourcePragma } from './pragma.js';
 import { collectProvenContextBindings, isProvenContextUse } from './context-use.js';
+import { signalDeclarationSourceEdits } from './signal-declarations.js';
 import {
 	hookMethodName,
 	hasHookMethods,
@@ -1337,7 +1338,7 @@ function parseHookSource(source, id) {
  *   `inlineHookMemo: true` enables the production-client whole-AST memo path;
  *   the default remains surgical. `manualSlots: true` permits memo and observed
  *   getter rewrites without injecting or changing the authored slot policy.
- * @returns {{ code: string, map: any, diagnostics?: any[] } | null}
+ * @returns {{ code: string, map: any, streamedSignals?: true, diagnostics?: any[] } | null}
  */
 export function slotHooks(source, id, options) {
 	const environment = options?.environment ?? 'client';
@@ -1381,6 +1382,7 @@ export function slotHooks(source, id, options) {
 		);
 	const manualProviders = options?.manualSlots ? findManualHookProviders(ast) : new Map();
 	const nativeReadActivation = options?.nativeReads === true && importsNativeRenderer(ast);
+	const signalLowering = signalDeclarationSourceEdits(ast, id, source);
 	const canSpecializeRoot =
 		!options?.manualSlots &&
 		!options?.hmr &&
@@ -1391,6 +1393,7 @@ export function slotHooks(source, id, options) {
 		!importInfo.importsHook &&
 		!canSpecializeRoot &&
 		!nativeReadActivation &&
+		!signalLowering.usesSignals &&
 		!manualProviders.size
 	) {
 		return strongAnalysis?.diagnostics.length ? { code: source, map: null, ...strongHints } : null;
@@ -1417,6 +1420,8 @@ export function slotHooks(source, id, options) {
 	const getterCalls = importInfo.importsHook ? collectStateGetterCalls(ast) : new WeakSet();
 	if (
 		!strongAnalysis?.enabled &&
+		// The whole-AST memo path does not apply declaration identity edits.
+		!signalLowering.usesSignals &&
 		canPrint &&
 		options?.inlineHookMemo === true &&
 		environment === 'client' &&
@@ -1465,7 +1470,7 @@ export function slotHooks(source, id, options) {
 		hash: hookSlotHash(id),
 		nextId: 0,
 		nextPuId: 0,
-		edits: [],
+		edits: [...signalLowering.edits],
 		decls: [],
 		parallelHelpers: new Map(),
 		provenContextBindings: collectProvenContextBindings(ast),
@@ -1485,7 +1490,7 @@ export function slotHooks(source, id, options) {
 	if (canSpecializeRoot) {
 		collectVoidRootEdits(ast, st, options.isVoidComponentImport);
 	}
-	if (st.edits.length === 0 && !nativeReadActivation)
+	if (st.edits.length === 0 && !nativeReadActivation && !signalLowering.usesSignals)
 		return strongAnalysis?.diagnostics.length ? { code: source, map: null, ...strongHints } : null;
 	const activation = nativeReadActivation
 		? requireParallelHelper(st, 'enableNativeReadCollection')
@@ -1526,6 +1531,35 @@ export function slotHooks(source, id, options) {
 	const otherHelperImports = [...otherHelpers]
 		.map(([request, specifiers]) => `import { ${specifiers.join(', ')} } from '${request}';\n`)
 		.join('');
+	const signalHelperImports = new Map();
+	for (const helper of signalLowering.imports) {
+		let specifiers = signalHelperImports.get(helper.source);
+		if (specifiers === undefined) signalHelperImports.set(helper.source, (specifiers = []));
+		specifiers.push(`${helper.imported} as ${helper.local}`);
+	}
+	let signalActivation = '';
+	if (signalLowering.usesSignals) {
+		const request =
+			environment === 'server'
+				? 'octane/internal/server'
+				: nativeReadActivation
+					? 'octane/internal/client'
+					: 'octane/signals';
+		const imported =
+			environment === 'server'
+				? 'enableServerSignalBindings'
+				: nativeReadActivation
+					? 'enableSignalBindings'
+					: '__enableSignalDocument';
+		const local = allocSlotName(st, `_$${imported}`);
+		let specifiers = signalHelperImports.get(request);
+		if (specifiers === undefined) signalHelperImports.set(request, (specifiers = []));
+		specifiers.push(`${imported} as ${local}`);
+		signalActivation = `${local}(1);\n`;
+	}
+	const signalImports = [...signalHelperImports]
+		.map(([request, specifiers]) => `import { ${specifiers.join(', ')} } from '${request}';\n`)
+		.join('');
 	const profileImport =
 		st.profile && !st.manualSlots
 			? "import { __profileHook as _$__profileHook } from 'octane/profiling';\n"
@@ -1535,15 +1569,22 @@ export function slotHooks(source, id, options) {
 			? `const ${st.slotBaseName} = /* @__PURE__ */ ${st.hookSlotsName}(${st.nextId});\n`
 			: '';
 	const block =
-		helperImport + otherHelperImports + profileImport + slotBase + st.decls.join('\n') + '\n';
-	if (activation !== null) {
-		// Native plain modules can render a local function during evaluation.
-		// Its slots and invocation collector must already exist at that call.
+		helperImport +
+		otherHelperImports +
+		signalImports +
+		profileImport +
+		slotBase +
+		st.decls.join('\n') +
+		'\n' +
+		signalActivation;
+	if (activation !== null || signalLowering.usesSignals) {
+		// Plain modules may read global signals or render during evaluation.
+		// Their document capability and any render slots must already exist.
 		// No newline is inserted, retaining the surgical pass's line mapping.
 		const index = nativeReadActivationIndex(ast.body);
 		st.edits.push({
 			pos: ast.body[index]?.start ?? source.length,
-			text: `;${block.replace(/\n/g, ' ')}${activation}(1); `,
+			text: `;${block.replace(/\n/g, ' ')}${activation === null ? '' : `${activation}(1); `}`,
 		});
 	}
 	// Assemble disjoint edits once instead of copying the growing module for
@@ -1574,6 +1615,12 @@ export function slotHooks(source, id, options) {
 		chunks.push(source.slice(0, cursor));
 		code = chunks.reverse().join('');
 	}
-	if (activation === null) code = code.endsWith('\n') ? code + block : code + '\n' + block;
-	return { code, map: null, ...strongHints };
+	if (activation === null && !signalLowering.usesSignals)
+		code = code.endsWith('\n') ? code + block : code + '\n' + block;
+	return {
+		code,
+		map: null,
+		...(signalLowering.usesSignals || nativeReadActivation ? { streamedSignals: true } : null),
+		...strongHints,
+	};
 }