octane 0.2.6 → 0.2.8

package/dist/compiler/context-use.js

@@ -0,0 +1,154 @@
+// A direct module const initialized by Octane's createContext is the only
+// context identity we can prove without following values between modules.
+// Reject a name if any nested scope binds it: both compiler pipelines can
+// then use this module-wide proof without guessing which scope owns a use().
+export function collectProvenContextBindings(ast) {
+	const factories = new Set();
+	for (const statement of ast.body || []) {
+		if (
+			statement.type !== 'ImportDeclaration' ||
+			statement.importKind === 'type' ||
+			statement.source?.value !== 'octane'
+		)
+			continue;
+		for (const specifier of statement.specifiers || []) {
+			if (
+				specifier.type === 'ImportSpecifier' &&
+				specifier.importKind !== 'type' &&
+				(specifier.imported?.name ?? specifier.imported?.value) === 'createContext' &&
+				specifier.local?.name
+			)
+				factories.add(specifier.local.name);
+		}
+	}
+	if (factories.size === 0) return new Set();
+
+	const contexts = new Set();
+	for (const original of ast.body || []) {
+		const declaration = unwrapExport(original);
+		if (declaration?.type !== 'VariableDeclaration' || declaration.kind !== 'const') continue;
+		for (const entry of declaration.declarations || []) {
+			if (
+				entry.id?.type === 'Identifier' &&
+				entry.init?.type === 'CallExpression' &&
+				entry.init.optional !== true &&
+				entry.init.callee?.type === 'Identifier' &&
+				factories.has(entry.init.callee.name)
+			)
+				contexts.add(entry.id.name);
+		}
+	}
+	if (contexts.size === 0) return contexts;
+
+	const shadowed = new Set();
+	const seen = new WeakSet();
+	const bind = (pattern) => {
+		if (!pattern) return;
+		switch (pattern.type) {
+			case 'Identifier':
+				if (contexts.has(pattern.name)) shadowed.add(pattern.name);
+				break;
+			case 'ArrayPattern':
+				for (const item of pattern.elements || []) bind(item);
+				break;
+			case 'ObjectPattern':
+				for (const item of pattern.properties || [])
+					bind(item.type === 'RestElement' ? item.argument : item.value);
+				break;
+			case 'AssignmentPattern':
+				bind(pattern.left);
+				break;
+			case 'RestElement':
+				bind(pattern.argument);
+				break;
+			case 'TSParameterProperty':
+				bind(pattern.parameter);
+				break;
+		}
+	};
+	const scan = (node) => {
+		if (!node || typeof node !== 'object') return;
+		if (Array.isArray(node)) {
+			for (const item of node) scan(item);
+			return;
+		}
+		if (seen.has(node)) return;
+		seen.add(node);
+		if (node.type === 'ImportDeclaration') return;
+		switch (node.type) {
+			case 'VariableDeclarator':
+				bind(node.id);
+				break;
+			case 'FunctionDeclaration':
+			case 'FunctionExpression':
+			case 'ArrowFunctionExpression':
+			case 'TSDeclareFunction':
+				bind(node.id);
+				for (const param of node.params || []) bind(param);
+				break;
+			case 'ClassDeclaration':
+			case 'ClassExpression':
+			case 'TSEnumDeclaration':
+			case 'TSModuleDeclaration':
+				bind(node.id);
+				break;
+			case 'CatchClause':
+				bind(node.param);
+				break;
+			case 'JSXForExpression':
+				if (node.left?.type !== 'VariableDeclaration') bind(node.left);
+				bind(node.index);
+				break;
+			case 'JSXTryExpression':
+				bind(node.handler?.param);
+				bind(node.handler?.resetParam);
+				break;
+		}
+		for (const key in node) {
+			if (
+				key === 'loc' ||
+				key === 'start' ||
+				key === 'end' ||
+				key === 'range' ||
+				key === 'parent' ||
+				key === 'metadata' ||
+				key.startsWith('_octane')
+			)
+				continue;
+			scan(node[key]);
+		}
+	};
+	for (const original of ast.body || []) {
+		if (original.type === 'ImportDeclaration') continue;
+		const declaration = unwrapExport(original);
+		if (declaration?.type === 'VariableDeclaration') {
+			// These IDs belong to the module itself, including the proven
+			// contexts. Their initializers can still contain nested shadows.
+			for (const entry of declaration.declarations || []) scan(entry.init);
+		} else {
+			scan(declaration);
+		}
+	}
+	for (const name of shadowed) contexts.delete(name);
+	return contexts;
+}
+
+export function isProvenContextUse(argument, contexts) {
+	let value = argument;
+	while (
+		value?.type === 'TSAsExpression' ||
+		value?.type === 'TSTypeAssertion' ||
+		value?.type === 'TSSatisfiesExpression' ||
+		value?.type === 'TSNonNullExpression' ||
+		value?.type === 'TSInstantiationExpression' ||
+		value?.type === 'ParenthesizedExpression'
+	)
+		value = value.expression;
+	return value?.type === 'Identifier' && contexts.has(value.name);
+}
+
+function unwrapExport(node) {
+	return node?.type === 'ExportNamedDeclaration' || node?.type === 'ExportDefaultDeclaration'
+		? node.declaration
+		: node;
+}

package/dist/compiler/hook-deps.js

@@ -178,6 +178,7 @@ function collectHoistedVars(node, functionScope, root = true, bindingsOnly = fal
 	if (
 		bindingsOnly &&
 		(isFunction(node) ||
+			node.type === 'JSXSwitchExpression' ||
 			(!root && node.type === 'StaticBlock') ||
 			node.type === 'ClassDeclaration' ||
 			node.type === 'ClassExpression' ||
@@ -479,7 +480,22 @@ function buildScopes(ast, onlyImported, hookRuntimeModules, bindingsOnly = false
 			return;
 		}
 
-		if (node.type === 'SwitchStatement' || (bindingsOnly && node.type === 'JSXSwitchExpression')) {
+		if (bindingsOnly && node.type === 'JSXSwitchExpression') {
+			// Each template arm is a separate callback. Its `var` declarations
+			// belong to that callback, rather than to the enclosing function or
+			// another arm with a declaration of the same name.
+			walk(node.discriminant, scope);
+			for (const switchCase of node.cases || []) {
+				walk(switchCase.test, scope);
+				const caseScope = createScope(scope, 'function');
+				collectHoistedVars(switchCase.consequent, caseScope, true, true);
+				predeclareDirect(switchCase.consequent, caseScope, hookRuntimeModules, true);
+				for (const statement of switchCase.consequent || []) walk(statement, caseScope);
+			}
+			return;
+		}
+
+		if (node.type === 'SwitchStatement') {
 			// A switch body is one lexical scope shared by every unbraced case.
 			// Predeclare the direct case statements together so let/const/function
 			// captures resolve even when their declaration appears in a case list

package/dist/compiler/index.d.ts

@@ -57,8 +57,6 @@ export interface CompileOptions {
 	dev?: boolean;
 	/** Assert pure immutable-snapshot renders, enable bounded checks, and trust production call memoization. */
 	strong?: boolean;
-	/** Experimental native signal reads in DOM client/server render scopes. */
-	nativeReads?: boolean;
 	profile?: boolean;
 	profileFilename?: string;
 	/** Include out-of-band source-origin inspection data. */
@@ -219,7 +217,7 @@ export function compile(source: string, filename: string, options?: CompileOptio
 export function compileToVolarMappings(
 	source: string,
 	filename?: string,
-	options?: { loose?: boolean; renderers?: unknown; strong?: boolean; nativeReads?: boolean },
+	options?: { loose?: boolean; renderers?: unknown; strong?: boolean },
 ): VolarCompileResult;
 
 /** @internal Shared authored-JSX diagnostic analysis for compiler integrations. */

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

@@ -64,16 +64,30 @@ function propertyName(node, computed = false) {
 		: null;
 }
 
+/**
+ * Native reads are an explicit module capability. A runtime signals import,
+ * including a bare import for opaque readers, opts the entire module into
+ * capturing actual reads. Type-only imports and `$` names alone do not.
+ */
+export function nativeReadOptions(ast, options) {
+	const nativeReads = ast.body.some(
+		(node) =>
+			node.type === 'ImportDeclaration' &&
+			node.importKind !== 'type' &&
+			(node.source?.value === SIGNALS_MODULE || LOCAL_MODULES.has(node.source?.value)) &&
+			(node.specifiers.length === 0 ||
+				node.specifiers.some((specifier) => specifier.importKind !== 'type')),
+	);
+	return { ...options, nativeReads };
+}
+
 export function assertNativeReadOptions(options) {
-	if (options?.nativeReads !== undefined && typeof options.nativeReads !== 'boolean') {
-		throw new TypeError('Octane nativeReads must be a boolean.');
-	}
 	if (
 		options?.nativeReads === true &&
 		options.renderer?.target != null &&
 		options.renderer.target !== 'dom'
 	) {
-		throw new Error('Octane nativeReads currently supports only the DOM client and server.');
+		throw new Error('Octane native signal reads support only the DOM client and server.');
 	}
 }
 
@@ -85,34 +99,7 @@ export function assertNativeReadOptions(options) {
  */
 export function analyzeNativeReadDiagnostics(ast, source, filename, options = {}) {
 	assertNativeReadOptions(options);
-	if (options.nativeReads !== true) {
-		for (const statement of ast.body ?? []) {
-			if (
-				statement.type !== 'ImportDeclaration' ||
-				statement.importKind === 'type' ||
-				!LOCAL_MODULES.has(statement.source?.value)
-			)
-				continue;
-			const capability = (statement.specifiers ?? []).find(
-				(specifier) =>
-					specifier.importKind !== 'type' &&
-					(specifier.type === 'ImportNamespaceSpecifier' ||
-						LOCAL_HOOKS.has(specifier.imported?.name ?? specifier.imported?.value)),
-			);
-			if (capability)
-				return [
-					nativeReadDiagnostic(
-						'OCTANE_NATIVE_READ_OPT_IN',
-						source,
-						filename,
-						capability.start ?? statement.start,
-						capability.end ?? statement.end,
-						'Local native signal hooks require nativeReads: true in the Octane compiler configuration.',
-					),
-				];
-		}
-		return [];
-	}
+	if (!options.nativeReads) return [];
 	if (options.rendererBoundaries && Object.keys(options.rendererBoundaries).length > 0) {
 		const { boundaries } = analyzeRendererBoundaries(source, {
 			ast,
@@ -132,7 +119,7 @@ export function analyzeNativeReadDiagnostics(ast, source, filename, options = {}
 					filename,
 					unsupported.tagRange[0],
 					unsupported.tagRange[1],
-					`Octane nativeReads currently supports only the DOM client and server; renderer ${JSON.stringify(unsupported.childRenderer)} has no native-read integration.`,
+					`Octane native signal reads support only the DOM client and server; renderer ${JSON.stringify(unsupported.childRenderer)} has no native-read integration.`,
 				),
 			];
 	}
@@ -536,7 +523,7 @@ export function analyzeNativeReadDiagnostics(ast, source, filename, options = {}
 			report(
 				'OCTANE_NATIVE_SIGNAL_HOOK',
 				node,
-				'useDerived$ is not available in this experimental integration. Create derived$ on an explicitly owned Scope and pass the handle to the component.',
+				'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') {
 			checkName(node.key, propertyName(node.key, node.computed), valueOf(node.value));

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

@@ -4,7 +4,6 @@ import type { CompilerProgram, CompileSourceMap } from './index.js';
 export interface SlotHooksOptions {
 	environment?: 'client' | 'server';
 	strong?: boolean;
-	nativeReads?: boolean;
 	hmr?: boolean;
 	dev?: boolean;
 	profile?: boolean;

package/dist/compiler/slot-hooks.js

@@ -20,10 +20,11 @@ import { NATIVE_SIGNAL_HOOK_NAMES } from './hook-names.js';
 import { METHOD_DEP_IMPORT, annotateHookCalls } from './hook-deps.js';
 import { inlinePlainHookMemos } from './plain-hook-memo.js';
 import { assertStrongMode } from './strong-mode.js';
-import { assertNativeReadDiagnostics, assertNativeReadOptions } from './native-read-diagnostics.js';
+import { assertNativeReadDiagnostics, nativeReadOptions } from './native-read-diagnostics.js';
 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 {
 	hookMethodName,
 	hasHookMethods,
@@ -868,6 +869,10 @@ function requireParallelHelper(st, imported) {
 
 function emitParallelUseRun(run, owner, st) {
 	if (run.uses.length === 0) return;
+	if (run.uses.every((entry) => isProvenContextUse(entry.arg, st.provenContextBindings))) {
+		// Leave plain source untouched when every read is a proven context.
+		return;
+	}
 	const memoName = st.nativeReads
 		? 'nativePuMemo'
 		: st.environment === 'server'
@@ -1284,7 +1289,7 @@ function parseHookSource(source, id) {
  *
  * @param {string} source raw module text
  * @param {string} id     module id (embedded in the stable Symbol.for key)
- * @param {{ environment?: 'client' | 'server', strong?: boolean, nativeReads?: boolean, hmr?: boolean, dev?: boolean, profile?: boolean, profileFilename?: string, inlineHookMemo?: boolean, manualSlots?: boolean, universalRuntime?: unknown, renderer?: { target?: string }, isVoidComponentImport?: (request: string, imported: string) => boolean }} [options] `hmr: true` (dev serve) emits
+ * @param {{ environment?: 'client' | 'server', strong?: boolean, hmr?: boolean, dev?: boolean, profile?: boolean, profileFilename?: string, inlineHookMemo?: boolean, manualSlots?: boolean, universalRuntime?: unknown, renderer?: { target?: string }, isVoidComponentImport?: (request: string, imported: string) => boolean }} [options] `hmr: true` (dev serve) emits
  *   `Symbol.for(stableKey)` so a re-imported module resolves the same hook
  *   slots (state survives HMR); off (ordinary prod builds and SSR) emits
  *   runtime-ranged Symbols. Profiling retains short described Symbols because
@@ -1295,7 +1300,6 @@ function parseHookSource(source, id) {
  * @returns {{ code: string, map: any } | null}
  */
 export function slotHooks(source, id, options) {
-	assertNativeReadOptions(options);
 	const environment = options?.environment ?? 'client';
 	if (environment !== 'client' && environment !== 'server') {
 		throw new Error(
@@ -1309,6 +1313,7 @@ export function slotHooks(source, id, options) {
 	} catch {
 		return null; // let the normal pipeline surface the parse error
 	}
+	options = nativeReadOptions(ast, options);
 	assertStrongMode(ast, source, id, options);
 	assertNativeReadDiagnostics(ast, source, id, options);
 	const importInfo = octaneHookLocals(
@@ -1396,6 +1401,7 @@ export function slotHooks(source, id, options) {
 		edits: [],
 		decls: [],
 		parallelHelpers: new Map(),
+		provenContextBindings: collectProvenContextBindings(ast),
 		usedNames: collectIdentifierNames(ast),
 		slotBaseName: null,
 		hookSlotsName: null,