octane 0.2.12 → 0.2.13

package/dist/compiler/native-attribute-reads.js

@@ -0,0 +1,127 @@
+// Direct native bindings recognize capability syntax, not structural `.get`
+// methods. Share this syntax boundary between runtime and virtual TSX lowering.
+function unwrapExpression(node) {
+	while (
+		node &&
+		(node.type === 'TSAsExpression' ||
+			node.type === 'TSTypeAssertion' ||
+			node.type === 'TSNonNullExpression' ||
+			node.type === 'TSSatisfiesExpression' ||
+			node.type === 'TSInstantiationExpression' ||
+			node.type === 'ChainExpression' ||
+			node.type === 'ParenthesizedExpression')
+	) {
+		node = node.expression;
+	}
+	return node;
+}
+
+export function isDirectSignalHandleExpression(node) {
+	node = unwrapExpression(node);
+	if (!node) return false;
+	if (node.type === 'Identifier') return node.name.endsWith('$');
+	if (node.type === 'MemberExpression' || node.type === 'OptionalMemberExpression') {
+		const name = node.computed
+			? node.property?.type === 'Literal' && typeof node.property.value === 'string'
+				? node.property.value
+				: null
+			: node.property?.name;
+		return typeof name === 'string' && name.endsWith('$');
+	}
+	if (node.type === 'CallExpression' || node.type === 'OptionalCallExpression') {
+		const callee = unwrapExpression(node.callee);
+		const name =
+			callee?.type === 'Identifier'
+				? callee.name
+				: callee?.type === 'MemberExpression' || callee?.type === 'OptionalMemberExpression'
+					? callee.computed
+						? callee.property?.value
+						: callee.property?.name
+					: null;
+		return /^_?\$?__(?:signal|derived|query)At$/.test(name ?? '');
+	}
+	return false;
+}
+
+function rejectNestedHandles(node) {
+	if (!node || typeof node !== 'object') return;
+	if (isDirectSignalHandleExpression(node))
+		throw new Error(
+			'Native JSX signal projections do not support handles inside callbacks, constructors, or tagged templates.',
+		);
+	for (const key of Object.keys(node)) {
+		if (!['metadata', 'loc', 'start', 'end'].includes(key)) rejectNestedHandles(node[key]);
+	}
+}
+
+/** Only an explicitly configured native attribute admits these sampled reads. */
+export function lowerNativeAttributeReads(expression, read) {
+	let reactive = false;
+	const rewrite = (node) => {
+		if (!node || typeof node !== 'object') return node;
+		if (Array.isArray(node)) return node.map(rewrite);
+		if (isDirectSignalHandleExpression(node)) {
+			reactive = true;
+			return read(node);
+		}
+		if (node.type === 'MemberExpression' || node.type === 'OptionalMemberExpression') {
+			if (isDirectSignalHandleExpression(node.object))
+				throw new Error(
+					'Native JSX signal projections require .get() before reading a signal payload property.',
+				);
+			return {
+				...node,
+				object: rewrite(node.object),
+				property: node.computed ? rewrite(node.property) : node.property,
+			};
+		}
+		if (node.type === 'CallExpression' || node.type === 'OptionalCallExpression') {
+			const callee = unwrapExpression(node.callee);
+			const handleGet =
+				(callee?.type === 'MemberExpression' || callee?.type === 'OptionalMemberExpression') &&
+				(callee.computed ? callee.property?.value : callee.property?.name) === 'get' &&
+				isDirectSignalHandleExpression(callee.object);
+			if (handleGet) reactive = true;
+			return {
+				...node,
+				// Keep a method call as a member call so `this` and evaluation order
+				// survive a computed style selection. Explicit get keeps its receiver.
+				callee:
+					!handleGet &&
+					(callee?.type === 'MemberExpression' || callee?.type === 'OptionalMemberExpression')
+						? rewrite(node.callee)
+						: node.callee,
+				arguments: node.arguments.map(rewrite),
+			};
+		}
+		if (
+			[
+				'FunctionExpression',
+				'ArrowFunctionExpression',
+				'ClassExpression',
+				'NewExpression',
+				'TaggedTemplateExpression',
+			].includes(node.type)
+		) {
+			rejectNestedHandles(node);
+			return node;
+		}
+		if (node.type === 'Property') {
+			const value = rewrite(node.value);
+			return value === node.value ? node : { ...node, value, shorthand: false };
+		}
+		let result = node;
+		for (const key of Object.keys(node)) {
+			if (['metadata', 'loc', 'start', 'end'].includes(key)) continue;
+			const value = node[key];
+			if (!value || typeof value !== 'object') continue;
+			const next = rewrite(value);
+			if (next !== value) {
+				if (result === node) result = { ...node };
+				result[key] = next;
+			}
+		}
+		return result;
+	};
+	return { expression: rewrite(expression), reactive };
+}

package/dist/compiler/native-read-diagnostics.js

@@ -5,9 +5,11 @@ export { NATIVE_SIGNAL_NAME, NATIVE_MEMO_READ } from './native-read-facts.js';
 
 const SIGNALS_MODULE = 'octane/signals';
 const CLIENT_MODULE = 'octane/signals/client';
+const SIGNAL_MODULES = new Set([SIGNALS_MODULE, CLIENT_MODULE, 'octane/signals/server']);
 const LOCAL_MODULES = new Set([CLIENT_MODULE, 'octane/signals/server']);
 const HANDLE_TYPES = new Set(['SignalHandle', 'Resource', 'WritableSignal', 'DerivedSignal']);
-const SIGNAL_METHODS = new Set(['signal$', 'derived$', 'asyncSignal$']);
+const SIGNAL_METHODS = new Set(['signal$', 'derived$']);
+const SIGNAL_FACTORIES = new Set(['signal$', 'derived$', 'query$', 'createResource']);
 const LOCAL_HOOKS = new Set(['useSignal$']);
 const FUNCTION_TYPES = new Set([
 	'ArrowFunctionExpression',
@@ -189,8 +191,12 @@ export function analyzeNativeReadDiagnostics(ast, source, filename, options = {}
 		}
 	}
 	function importedValue(module, name) {
+		if (module === 'octane/behavior' && (name === 'adoptBindings' || name === 'mountBindings'))
+			return { kind: 'builtin', name, bindingSource: true };
 		if (module === SIGNALS_MODULE && name === 'createScope')
 			return { kind: 'builtin', name: 'createScope' };
+		if (SIGNAL_MODULES.has(module) && SIGNAL_FACTORIES.has(name))
+			return { kind: 'builtin', name, capability: true };
 		if (LOCAL_MODULES.has(module) && name === 'useDerived$')
 			return { kind: 'unsupportedHook', name };
 		if (LOCAL_MODULES.has(module) && LOCAL_HOOKS.has(name))
@@ -382,7 +388,12 @@ export function analyzeNativeReadDiagnostics(ast, source, filename, options = {}
 			if (callee.kind === 'function') return callee.result;
 			if (callee.kind === 'builtin') {
 				if (callee.name === 'createScope') return SCOPE;
-				if (SIGNAL_METHODS.has(callee.name) || LOCAL_HOOKS.has(callee.name)) return HANDLE;
+				if (
+					SIGNAL_METHODS.has(callee.name) ||
+					SIGNAL_FACTORIES.has(callee.name) ||
+					LOCAL_HOOKS.has(callee.name)
+				)
+					return HANDLE;
 			}
 			return UNKNOWN;
 		}
@@ -464,6 +475,16 @@ export function analyzeNativeReadDiagnostics(ast, source, filename, options = {}
 			}
 		}
 	} while (changed);
+	// BindingSource uses a fixed protocol key even when its snapshot carries
+	// native handles. Exempt only callbacks reached through the source argument
+	// of a directly imported bindings API, never arbitrary getSnapshot methods.
+	const bindingSnapshots = new WeakSet();
+	for (const node of nodes) {
+		if (node.type !== 'CallExpression' && node.type !== 'OptionalCallExpression') continue;
+		if (recordFor(unwrap(node.callee))?.forced?.bindingSource !== true) continue;
+		const snapshot = memberValue(valueOf(node.arguments[2]), 'getSnapshot');
+		if (snapshot.kind === 'function') bindingSnapshots.add(snapshot.fn);
+	}
 	function containsHandle(value, active = new Set()) {
 		if (value.kind === 'handle') return true;
 		if (value.kind !== 'object' || active.has(value)) return false;
@@ -510,6 +531,15 @@ export function analyzeNativeReadDiagnostics(ast, source, filename, options = {}
 			`Native signal handles and functions exposing handles or live reads must end in $. Rename ${JSON.stringify(name)} to ${JSON.stringify(name + '$')}; sampled values keep ordinary names.`,
 		);
 	}
+	function createsCapability(node, value) {
+		node = unwrap(node);
+		if (!node || !isCapability(value)) return false;
+		return (
+			node.type === 'CallExpression' ||
+			node.type === 'OptionalCallExpression' ||
+			FUNCTION_TYPES.has(node.type)
+		);
+	}
 	function isDomStyleProperty(node) {
 		let object = parents.get(node);
 		let container = parents.get(object);
@@ -533,7 +563,13 @@ export function analyzeNativeReadDiagnostics(ast, source, filename, options = {}
 	}
 	for (const record of allRecords) {
 		const value = recordValue(record);
-		for (const declaration of record.declarations) checkName(declaration, record.name, value);
+		if (
+			record.expressions.some(({ expression }) =>
+				createsCapability(expression, valueOf(expression)),
+			)
+		) {
+			for (const declaration of record.declarations) checkName(declaration, record.name, value);
+		}
 	}
 	for (const node of nodes) {
 		if (
@@ -547,14 +583,17 @@ export function analyzeNativeReadDiagnostics(ast, source, filename, options = {}
 				'useDerived$ is not available. Create derived$ on an explicitly owned Scope and pass the handle to the component.',
 			);
 		} else if (node.type === 'Property' && parents.get(node)?.type === 'ObjectExpression') {
-			if (!isDomStyleProperty(node))
-				checkName(node.key, propertyName(node.key, node.computed), valueOf(node.value));
+			const value = valueOf(node.value);
+			const bindingSnapshot =
+				propertyName(node.key, node.computed) === 'getSnapshot' &&
+				bindingSnapshots.has(unwrap(node.value));
+			if (!isDomStyleProperty(node) && !bindingSnapshot && createsCapability(node.value, value))
+				checkName(node.key, propertyName(node.key, node.computed), value);
 		} else if (node.type === 'AssignmentExpression' && node.operator === '=') {
 			const left = unwrap(node.left);
-			if (left?.type === 'MemberExpression')
-				checkName(left.property, propertyName(left.property, left.computed), valueOf(node.right));
-		} else if (node.type === 'ExportSpecifier' && parents.get(node)?.source == null) {
-			checkName(node.exported, node.exported.name ?? node.exported.value, valueOf(node.local));
+			const value = valueOf(node.right);
+			if (left?.type === 'MemberExpression' && createsCapability(node.right, value))
+				checkName(left.property, propertyName(left.property, left.computed), value);
 		} else if (node.type === 'CallExpression' || node.type === 'OptionalCallExpression') {
 			const callee = valueOf(node.callee);
 			if (callee.kind === 'builtin' && callee.name === 'useMemo') {

package/dist/compiler/native-read-types.js

@@ -57,6 +57,22 @@ export function validateNativeSignalNames(program, file) {
 			if (property) recordSignatures(symbolType(property), nativeReadSignatures);
 		}
 	}
+	function recordFactory(exports, name) {
+		const factory = exports.get(name);
+		const type = factory && symbolType(factory);
+		if (!type) return;
+		for (const signature of checker.getSignaturesOfType(type, ts.SignatureKind.Call)) {
+			const returned = checker.getReturnTypeOfSignature(signature);
+			recordReads(returned, ['get', 'latest', 'snapshot']);
+			for (const property of checker.getPropertiesOfType(returned)) {
+				for (const declaration of property.declarations ?? []) {
+					if (!declaration.name || !ts.isComputedPropertyName(declaration.name)) continue;
+					const marker = canonical(checker.getSymbolAtLocation(declaration.name.expression));
+					if (marker?.name === 'SIGNAL_HANDLE') brands.add(marker);
+				}
+			}
+		}
+	}
 	function inspectModule(symbol, request) {
 		symbol = canonical(symbol);
 		if (!symbol || inspectedModules.has(symbol)) return;
@@ -77,24 +93,14 @@ export function validateNativeSignalNames(program, file) {
 			if (type)
 				for (const signature of checker.getSignaturesOfType(type, ts.SignatureKind.Call))
 					recordReads(checker.getReturnTypeOfSignature(signature), ['get']);
+			for (const name of ['signal$', 'derived$', 'query$']) recordFactory(exports, name);
 		} else if (NATIVE_MODULES.has(request)) {
 			// A project may import only the optional local hook entry. Follow the
 			// trusted export's actual return type to the same nominal declaration;
 			// do not require a redundant bare-engine import or brand lookalikes.
-			const hook = exports.get('useSignal$');
-			const type = hook && symbolType(hook);
-			if (type)
-				for (const signature of checker.getSignaturesOfType(type, ts.SignatureKind.Call)) {
-					const returned = checker.getReturnTypeOfSignature(signature);
-					recordReads(returned, ['get', 'latest', 'snapshot']);
-					for (const property of checker.getPropertiesOfType(returned)) {
-						for (const declaration of property.declarations ?? []) {
-							if (!declaration.name || !ts.isComputedPropertyName(declaration.name)) continue;
-							const marker = canonical(checker.getSymbolAtLocation(declaration.name.expression));
-							if (marker?.name === 'SIGNAL_HANDLE') brands.add(marker);
-						}
-					}
-				}
+			for (const name of ['useSignal$', 'signal$', 'derived$', 'query$']) {
+				recordFactory(exports, name);
+			}
 		} else if (request === 'octane') {
 			const memo = exports.get('useMemo');
 			if (memo) recordSignatures(symbolType(memo), memoSignatures);
@@ -265,10 +271,27 @@ export function validateNativeSignalNames(program, file) {
 				`Native signal handles and functions exposing handles or live reads must end in $. Rename ${JSON.stringify(text)} to ${JSON.stringify(text + '$')}; sampled values keep ordinary names.`,
 			);
 	}
-	function valueExport(node) {
-		if (node.isTypeOnly || node.parent.parent.isTypeOnly) return false;
-		const symbol = canonical(checker.getSymbolAtLocation(node.name));
-		return symbol && (symbol.flags & ts.SymbolFlags.Value) !== 0;
+	function unwrapExpression(node) {
+		while (
+			node &&
+			(ts.isParenthesizedExpression(node) ||
+				ts.isAsExpression(node) ||
+				ts.isTypeAssertionExpression(node) ||
+				ts.isNonNullExpression(node) ||
+				ts.isSatisfiesExpression(node))
+		) {
+			node = node.expression;
+		}
+		return node;
+	}
+	function createsCapability(node) {
+		node = unwrapExpression(node);
+		if (!node) return false;
+		if (ts.isCallExpression(node)) return exposesHandle(checker.getTypeAtLocation(node));
+		return (
+			(ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
+			(exposesHandle(checker.getTypeAtLocation(node)) || exposesLiveRead(node))
+		);
 	}
 	function isDomStyleProperty(node) {
 		let object = node.parent;
@@ -297,17 +320,15 @@ export function validateNativeSignalNames(program, file) {
 		return ts.isIdentifier(tag) && /^[a-z]/.test(tag.text);
 	}
 	function visit(node) {
-		if (ts.isVariableDeclaration(node) || ts.isParameter(node) || ts.isBindingElement(node)) {
-			checkName(node.name);
-		} else if (ts.isImportSpecifier(node)) {
-			if (!node.isTypeOnly && !node.parent.parent.isTypeOnly) checkName(node.name);
-		} else if (ts.isExportSpecifier(node)) {
-			if (valueExport(node)) checkName(node.name, node.propertyName ?? node.name);
-		} else if (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node)) {
-			if (!isDomStyleProperty(node))
-				checkName(node.name, ts.isPropertyAssignment(node) ? node.initializer : node.name);
-		} else if (ts.isPropertyDeclaration(node) || ts.isPropertySignature(node)) {
-			checkName(node.name);
+		if (ts.isVariableDeclaration(node)) {
+			if (node.initializer && createsCapability(node.initializer))
+				checkName(node.name, node.initializer);
+		} else if (ts.isPropertyAssignment(node)) {
+			if (!isDomStyleProperty(node) && createsCapability(node.initializer))
+				checkName(node.name, node.initializer);
+		} else if (ts.isPropertyDeclaration(node)) {
+			if (node.initializer && createsCapability(node.initializer))
+				checkName(node.name, node.initializer);
 		} else if (
 			ts.isFunctionDeclaration(node) ||
 			ts.isMethodDeclaration(node) ||
@@ -318,9 +339,11 @@ export function validateNativeSignalNames(program, file) {
 			ts.isBinaryExpression(node) &&
 			node.operatorToken.kind === ts.SyntaxKind.EqualsToken
 		) {
-			if (ts.isPropertyAccessExpression(node.left)) checkName(node.left.name, node.right);
-			else if (ts.isElementAccessExpression(node.left))
-				checkName(node.left.argumentExpression, node.right);
+			if (createsCapability(node.right)) {
+				if (ts.isPropertyAccessExpression(node.left)) checkName(node.left.name, node.right);
+				else if (ts.isElementAccessExpression(node.left))
+					checkName(node.left.argumentExpression, node.right);
+			}
 		} else if (ts.isCallExpression(node)) {
 			const declaration = checker.getResolvedSignature(node)?.declaration;
 			if (

package/dist/compiler/server-context.js

@@ -0,0 +1,118 @@
+// Shared syntax-level recognition for runtime server registration and editor call signatures.
+export function unwrapServerFunctionInitializer(node) {
+	let current = node;
+	while (
+		current &&
+		(current.type === 'TSAsExpression' ||
+			current.type === 'TSSatisfiesExpression' ||
+			current.type === 'TSNonNullExpression' ||
+			current.type === 'TypeCastExpression' ||
+			current.type === 'ParenthesizedExpression')
+	) {
+		current = current.expression;
+	}
+	return current;
+}
+
+export function collectServerFunctionNodes(statements) {
+	const functions = new Map();
+	const aliases = new Map();
+	for (const statement of statements) {
+		const declaration =
+			statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+		if (!declaration) continue;
+		if (declaration.type === 'FunctionDeclaration' && declaration.id) {
+			functions.set(declaration.id.name, declaration);
+			continue;
+		}
+		if (declaration.type !== 'VariableDeclaration') continue;
+		for (const item of declaration.declarations ?? []) {
+			if (item.id?.type !== 'Identifier' || !item.init) continue;
+			const init = unwrapServerFunctionInitializer(item.init);
+			if (init?.type === 'FunctionExpression' || init?.type === 'ArrowFunctionExpression') {
+				functions.set(item.id.name, init);
+			} else if (init?.type === 'Identifier') {
+				aliases.set(item.id.name, init.name);
+			}
+		}
+	}
+	for (const [local, target] of aliases) {
+		let name = target;
+		const seen = new Set([local]);
+		while (!seen.has(name)) {
+			seen.add(name);
+			const fn = functions.get(name);
+			if (fn !== undefined) {
+				functions.set(local, fn);
+				break;
+			}
+			name = aliases.get(name);
+			if (name === undefined) break;
+		}
+	}
+	return functions;
+}
+
+export function serverContextTypeImports(statements) {
+	const named = new Set();
+	const namespaces = new Set();
+	for (const statement of statements) {
+		if (statement.type !== 'ImportDeclaration' || statement.source?.value !== 'octane/server') {
+			continue;
+		}
+		for (const specifier of statement.specifiers ?? []) {
+			if (specifier.type === 'ImportNamespaceSpecifier') {
+				namespaces.add(specifier.local.name);
+				continue;
+			}
+			if (specifier.type !== 'ImportSpecifier') continue;
+			const imported = specifier.imported?.name ?? specifier.imported?.value;
+			if (imported === 'ServerCallContext') named.add(specifier.local.name);
+		}
+	}
+	return { named, namespaces };
+}
+
+export function serverContextTypeName(type, imports) {
+	while (
+		type &&
+		(type.type === 'TSTypeAnnotation' ||
+			type.type === 'TSParenthesizedType' ||
+			type.type === 'TSOptionalType')
+	) {
+		type = type.typeAnnotation;
+	}
+	if (type?.type !== 'TSTypeReference') return false;
+	const name = type.typeName;
+	if (name?.type === 'Identifier') return imports.named.has(name.name);
+	if (name?.type === 'TSQualifiedName') {
+		return (
+			name.left?.type === 'Identifier' &&
+			imports.namespaces.has(name.left.name) &&
+			name.right?.name === 'ServerCallContext'
+		);
+	}
+	return (
+		name?.type === 'MemberExpression' &&
+		name.object?.type === 'Identifier' &&
+		imports.namespaces.has(name.object.name) &&
+		name.property?.name === 'ServerCallContext'
+	);
+}
+
+export function serverFunctionContextIndex(fn, imports, filename) {
+	let contextIndex = -1;
+	const params = fn.params ?? [];
+	for (let index = 0; index < params.length; index++) {
+		let parameter = params[index];
+		if (parameter.type === 'AssignmentPattern') parameter = parameter.left;
+		if (!serverContextTypeName(parameter.typeAnnotation, imports)) continue;
+		if (index !== params.length - 1) {
+			throw new Error(
+				`ServerCallContext must be the final parameter of a \`module server\` function (${filename}).`,
+			);
+		}
+		contextIndex = index;
+	}
+	return contextIndex;
+}