octane 0.2.11 → 0.2.13

package/dist/compiler/hydrate-boundaries.js

@@ -7,7 +7,7 @@
  * module cache is required. This is important for Rspack, whose loader is
  * intentionally instantiated afresh for every resource query.
  */
-import { builders as b, parseModule } from '@tsrx/core';
+import { builders as b, parseModule, strongHash } from '@tsrx/core';
 
 export const HYDRATE_QUERY_PARAM = 'octane-hydrate';
 
@@ -117,6 +117,49 @@ function jsxExpressionAttribute(name, expression, origin) {
 	);
 }
 
+function objectProperty(name, value) {
+	return b.prop('init', b.id(name), value);
+}
+
+function independentManifestExpression(manifest, captures, origin) {
+	const template = b.object([
+		objectProperty('version', b.literal(1)),
+		objectProperty(
+			'boundaryId',
+			b.literal(manifest.boundaryId, JSON.stringify(manifest.boundaryId)),
+		),
+		objectProperty(
+			'exportName',
+			b.literal(manifest.exportName, JSON.stringify(manifest.exportName)),
+		),
+		objectProperty(
+			'captureSchema',
+			b.array(
+				manifest.captureSchema.map((capture) =>
+					b.object([
+						objectProperty('name', b.literal(capture.name, JSON.stringify(capture.name))),
+						objectProperty('type', b.literal('json', "'json'")),
+					]),
+				),
+			),
+		),
+		objectProperty('hookSeed', b.literal(manifest.hookSeed)),
+		objectProperty('idSeed', b.literal(manifest.idSeed)),
+		objectProperty(
+			'signalSites',
+			b.array(manifest.signalSites.map((site) => b.literal(site, JSON.stringify(site)))),
+		),
+		objectProperty('parentDependencies', b.literal(false, 'false')),
+	]);
+	return inheritGeneratedOrigin(
+		b.object([
+			objectProperty('manifestTemplate', template),
+			objectProperty('captures', b.array(captures.map((name) => b.id(name)))),
+		]),
+		origin,
+	);
+}
+
 function hydrateLoaderExpression(boundary, request) {
 	const query = `${request}?${HYDRATE_QUERY_PARAM}=${encodeURIComponent(boundary.path)}`;
 	return inheritGeneratedOrigin(
@@ -340,6 +383,52 @@ function literalSplitDisabled(node) {
 	return value?.type === 'Literal' && value.value === false;
 }
 
+function literalIndependentEnabled(node, filename) {
+	let independent = null;
+	let hasSpread = false;
+	for (const attribute of node.openingElement?.attributes ?? []) {
+		if (attribute.type === 'JSXSpreadAttribute' || attribute.type === 'SpreadAttribute') {
+			hasSpread = true;
+			continue;
+		}
+		if (jsxAttributeName(attribute) === 'independent') independent = attribute;
+	}
+	if (independent === null) return false;
+	const raw =
+		independent.value == null
+			? null
+			: independent.value.type === 'JSXExpressionContainer'
+				? unwrapExpression(independent.value.expression)
+				: independent.value;
+	const enabled = independent.value == null || (raw?.type === 'Literal' && raw.value === true);
+	const disabled = raw?.type === 'Literal' && raw.value === false;
+	if (!enabled && !disabled) {
+		throw extractionError(
+			'OCTANE_HYDRATE_INDEPENDENT_LITERAL',
+			filename,
+			independent,
+			'`independent` must be the literal `true` or `false` so standalone ownership is decided at build time',
+		);
+	}
+	if (enabled && hasSpread) {
+		throw extractionError(
+			'OCTANE_HYDRATE_INDEPENDENT_SPREAD',
+			filename,
+			independent,
+			'an independent boundary cannot combine its ownership request with Hydrate prop spreads; author the boundary options directly',
+		);
+	}
+	if (enabled && literalSplitDisabled(node)) {
+		throw extractionError(
+			'OCTANE_HYDRATE_INDEPENDENT_SPLIT',
+			filename,
+			independent,
+			'an independent boundary requires its own split client entry; remove `split={false}` or remove `independent`',
+		);
+	}
+	return enabled;
+}
+
 /**
  * Recognize only the exact server-only form whose client subtree may be erased.
  * Spreads and indirect strategies stay on the ordinary persistent-wrapper path:
@@ -719,9 +808,11 @@ export function analyzeHydrateBoundaries(source, filename = 'unknown.tsrx', pars
 				const siblings = parentBoundary === null ? roots : parentBoundary.children;
 				const index = siblings.length;
 				const path = parentBoundary === null ? String(index) : `${parentBoundary.path}.${index}`;
+				const independent = literalIndependentEnabled(node, filename);
 				boundary = {
 					children: [],
 					disabled: literalSplitDisabled(node),
+					independent,
 					permanentStatic: isPermanentStaticBoundary(node, imports.neverNames, shadowed),
 					node,
 					parent: parentBoundary,
@@ -1024,6 +1115,158 @@ function collectCaptures(
 	return [...captures];
 }
 
+function bindingInitializers(ast) {
+	const initializers = new Map();
+	const seen = new WeakSet();
+	const visit = (node) => {
+		if (!node || typeof node !== 'object' || seen.has(node)) return;
+		seen.add(node);
+		if (Array.isArray(node)) {
+			for (const child of node) visit(child);
+			return;
+		}
+		if (node.type === 'VariableDeclarator') {
+			const names = new Set();
+			collectBindingNames(node.id, names);
+			for (const name of names) initializers.set(name, node.init ?? null);
+		}
+		for (const [key, child] of Object.entries(node)) {
+			if (!SKIP_KEYS.has(key)) visit(child);
+		}
+	};
+	visit(ast);
+	return initializers;
+}
+
+function assignedNamesOutsideBoundary(ast, boundary) {
+	const assigned = new Set();
+	const inside = new WeakSet();
+	collectSubtreeNodes(boundary.node.children, inside);
+	const seen = new WeakSet();
+	const visit = (node) => {
+		if (!node || typeof node !== 'object' || seen.has(node) || inside.has(node)) return;
+		seen.add(node);
+		if (Array.isArray(node)) {
+			for (const child of node) visit(child);
+			return;
+		}
+		if (node.type === 'AssignmentExpression' || node.type === 'UpdateExpression') {
+			const names = new Set();
+			collectBindingNames(node.type === 'AssignmentExpression' ? node.left : node.argument, names);
+			for (const name of names) assigned.add(name);
+		}
+		for (const [key, child] of Object.entries(node)) {
+			if (!SKIP_KEYS.has(key)) visit(child);
+		}
+	};
+	visit(ast);
+	return assigned;
+}
+
+function unsupportedIndependentInitializer(node, hookNames) {
+	const value = unwrapExpression(node);
+	if (value == null) return false;
+	if (isFunction(value) || value.type === 'ClassExpression' || value.type === 'NewExpression') {
+		return true;
+	}
+	if (value.type !== 'CallExpression' && value.type !== 'OptionalCallExpression') return false;
+	if (isHookCall(value, hookNames)) return true;
+	// Calls can create request, DOM, class, store, or closure identity. A future
+	// proof may admit a pure JSON constructor; strict independent activation
+	// must not serialize the result merely because the local has a friendly name.
+	return true;
+}
+
+function signalSitesInBoundary(boundary) {
+	const sites = new Set();
+	const seen = new WeakSet();
+	const visit = (node) => {
+		if (!node || typeof node !== 'object' || seen.has(node)) return;
+		seen.add(node);
+		if (Array.isArray(node)) {
+			for (const child of node) visit(child);
+			return;
+		}
+		if (node.type === 'CallExpression' || node.type === 'OptionalCallExpression') {
+			const callee = node.callee;
+			const name =
+				callee?.type === 'Identifier'
+					? callee.name
+					: callee?.type === 'MemberExpression' || callee?.type === 'OptionalMemberExpression'
+						? nameOf(callee.property)
+						: null;
+			const site = node.arguments?.[0];
+			if (
+				/^_?\$?__(?:signal|derived|query)At$/.test(name ?? '') &&
+				site?.type === 'Literal' &&
+				typeof site.value === 'string'
+			) {
+				sites.add(site.value);
+			}
+		}
+		for (const [key, child] of Object.entries(node)) {
+			if (!SKIP_KEYS.has(key)) visit(child);
+		}
+	};
+	visit(boundary.node.children);
+	return [...sites].sort();
+}
+
+function independentWidgetMetadata(analysis, filename, moduleMovePlan) {
+	const initializers = bindingInitializers(analysis.ast);
+	const widgets = [];
+	for (const boundary of analysis.boundaries) {
+		if (!boundary.independent) continue;
+		if (hasPermanentStaticAncestor(boundary)) {
+			throw extractionError(
+				'OCTANE_HYDRATE_INDEPENDENT_STATIC_PARENT',
+				filename,
+				boundary.node,
+				'an independent boundary cannot be nested below a permanently static Hydrate owner',
+			);
+		}
+		assertDirectChildren(boundary, filename);
+		validateBoundary(boundary, filename, analysis.imports.hookNames);
+		const moduleBindings = moduleMovePlan.bindingsByPath.get(boundary.path) ?? new Set();
+		const captures = collectCaptures(
+			boundary.node.children,
+			analysis.imports.importBindings,
+			boundary.shadowedImports,
+			moduleBindings.size === 0 ? null : moduleBindings,
+		);
+		const assigned = assignedNamesOutsideBoundary(analysis.ast, boundary);
+		for (const capture of captures) {
+			const initializer = initializers.get(capture);
+			if (
+				assigned.has(capture) ||
+				unsupportedIndependentInitializer(initializer, analysis.imports.hookNames)
+			) {
+				throw extractionError(
+					'OCTANE_HYDRATE_INDEPENDENT_OWNER_CAPTURE',
+					filename,
+					boundary.node,
+					`independent activation cannot preserve parent-owned runtime capture \`${capture}\`. Pass serializable data, move the lifecycle into the widget, or use ordinary parent-first Hydrate`,
+				);
+			}
+		}
+		const boundaryId = `w:${strongHash(`octane:independent-boundary:1\0${filename}\0${boundary.path}`)}`;
+		widgets.push({
+			version: 1,
+			boundaryId,
+			moduleId: filename,
+			exportName: 'default',
+			request: `${sameSourceRequest(filename)}?${HYDRATE_QUERY_PARAM}=${encodeURIComponent(boundary.path)}`,
+			captureSchema: captures.map((name) => ({ name, type: 'json' })),
+			hookSeed: Number.parseInt(strongHash(`${boundaryId}\0hook`), 16),
+			idSeed: Number.parseInt(strongHash(`${boundaryId}\0id`), 16),
+			signalSites: signalSitesInBoundary(boundary),
+			styles: [],
+			parentDependencies: false,
+		});
+	}
+	return widgets;
+}
+
 function declarationBindingSet(node) {
 	const bindings = new Set();
 	if (node?.type === 'VariableDeclaration') {
@@ -1286,6 +1529,7 @@ function hydrateBoundaryElement(
 	request,
 	importBindings,
 	additionalModuleBindings = new Set(),
+	referencesOnly = false,
 ) {
 	const node = boundary.node;
 	const opening = node.openingElement;
@@ -1320,18 +1564,41 @@ function hydrateBoundaryElement(
 		boundary.shadowedImports,
 		additionalModuleBindings.size === 0 ? null : additionalModuleBindings,
 	);
-	const attributes = [
-		...(opening.attributes ?? []),
-		jsxExpressionAttribute('__load', hydrateLoaderExpression(boundary, request), opening),
-	];
-	if (captures.length > 0) {
+	const attributes = [...(opening.attributes ?? [])];
+	if (boundary.independent) {
 		attributes.push(
 			jsxExpressionAttribute(
-				'__data',
-				inheritGeneratedOrigin(b.array(captures.map((name) => b.id(name))), opening),
+				'__independent',
+				// Move planning precedes manifest validation, but still needs every capture
+				// reference to distinguish eager declarations from widget-owned code.
+				referencesOnly
+					? inheritGeneratedOrigin(b.array(captures.map((name) => b.id(name))), opening)
+					: independentManifestExpression(boundary.independentManifest, captures, opening),
 				opening,
 			),
 		);
+		attributes.push(
+			jsxExpressionAttribute(
+				'__independentLoad',
+				hydrateLoaderExpression(boundary, request),
+				opening,
+			),
+		);
+	} else {
+		attributes.push(
+			jsxExpressionAttribute('__load', hydrateLoaderExpression(boundary, request), opening),
+		);
+	}
+	if (captures.length > 0) {
+		if (!boundary.independent) {
+			attributes.push(
+				jsxExpressionAttribute(
+					'__data',
+					inheritGeneratedOrigin(b.array(captures.map((name) => b.id(name))), opening),
+					opening,
+				),
+			);
+		}
 	}
 	attributes.push(jsxExpressionAttribute('children', b.literal(null, 'null'), opening));
 	return {
@@ -1347,6 +1614,7 @@ function transformHydrateAst(
 	request,
 	bindingsByPath = new Map(),
 	removedRecords = [],
+	referencesOnly = false,
 ) {
 	const replacements = new WeakMap();
 	for (const boundary of extractionFrontier(analysis.roots)) {
@@ -1357,6 +1625,7 @@ function transformHydrateAst(
 				request,
 				analysis.imports.importBindings,
 				bindingsByPath.get(boundary.path),
+				referencesOnly,
 			),
 		);
 	}
@@ -1424,6 +1693,7 @@ function extractedModuleAst(
 	const pathName = boundary.path.replace(/[^A-Za-z0-9_$]/g, '_');
 	const componentName = uniqueGeneratedName(source, `__OctaneHydrateBoundary_${pathName}`);
 	const captureName = uniqueGeneratedName(source, `__octaneHydrateCaptures_${pathName}`);
+	const activatorName = uniqueGeneratedName(source, '__octaneCreateIndependentHydrateActivator');
 	const nestedAnalysis = {
 		...analysis,
 		roots: boundary.children,
@@ -1438,6 +1708,8 @@ function extractedModuleAst(
 		nestedAnalysis,
 		request,
 		moduleBindingsByPath,
+		[],
+		true,
 	).body;
 	const setup =
 		captures.length === 0
@@ -1457,16 +1729,37 @@ function extractedModuleAst(
 		},
 		boundary.node,
 	);
-	const generatedExport = inheritGeneratedOrigin(
-		b.export_default(b.function_declaration(b.id(componentName), [b.id(captureName)], codeBlock)),
+	const generatedComponent = inheritGeneratedOrigin(
+		b.function_declaration(b.id(componentName), [b.id(captureName)], codeBlock),
 		boundary.node,
 	);
+	const generatedNodes = boundary.independent
+		? [
+				generatedComponent,
+				inheritGeneratedOrigin(
+					b.export_default(b.call(b.id(activatorName), b.id(componentName))),
+					boundary.node,
+				),
+			]
+		: [inheritGeneratedOrigin(b.export_default(generatedComponent), boundary.node)];
+	const activatorImport = boundary.independent
+		? [
+				inheritGeneratedOrigin(
+					b.import_declaration(
+						[b.import_specifier('createIndependentHydrateActivator', activatorName)],
+						'octane/internal/client',
+					),
+					boundary.node,
+				),
+			]
+		: [];
 	const program = {
 		...analysis.ast,
 		body: [
 			...analysis.imports.declarations,
+			...activatorImport,
 			...(moduleDeclarationsByPath.get(boundary.path) ?? []).map((record) => record.node),
-			generatedExport,
+			...generatedNodes,
 		],
 	};
 	return pruneUnusedImportsAst(program, false);
@@ -1522,6 +1815,7 @@ function createModuleMovePlanAst(analysis, request) {
 		request,
 		allBindingsByPath,
 		candidates.records,
+		true,
 	);
 	const eagerReferences = new Set(
 		collectCaptures(
@@ -1760,6 +2054,13 @@ export function prepareHydrateBoundaries(source, filename, boundaryPath = null,
 	}
 	const request = sameSourceRequest(filename);
 	const moduleMovePlan = createModuleMovePlanAst(analysis, request);
+	const independentWidgets = independentWidgetMetadata(analysis, filename, moduleMovePlan);
+	let independentIndex = 0;
+	for (const boundary of analysis.boundaries) {
+		if (boundary.independent) {
+			boundary.independentManifest = independentWidgets[independentIndex++];
+		}
+	}
 	const permanentStaticRemoved =
 		boundaryPath === null
 			? createPermanentStaticRemovalPlanAst(analysis, request, moduleMovePlan)
@@ -1793,6 +2094,7 @@ export function prepareHydrateBoundaries(source, filename, boundaryPath = null,
 	return {
 		ast,
 		boundaryPath,
+		independentWidgets,
 	};
 }
 
@@ -1893,13 +2195,33 @@ export function prepareServerHydrateBoundaries(source, filename, parsedAst = nul
 	if (!source.includes('Hydrate') || !source.includes('octane')) return null;
 	const analysis = analyzeHydrateBoundaries(source, filename, parsedAst);
 	if (analysis.boundaries.length === 0) return 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);
+	const independentWidgets = independentWidgetMetadata(analysis, filename, moduleMovePlan);
+	let independentIndex = 0;
+	for (const boundary of analysis.boundaries) {
+		if (!boundary.independent) continue;
+		boundary.independentManifest = independentWidgets[independentIndex++];
+		const moduleBindings = moduleMovePlan.bindingsByPath.get(boundary.path) ?? new Set();
+		boundary.independentCaptures = collectCaptures(
+			boundary.node.children,
+			analysis.imports.importBindings,
+			boundary.shadowedImports,
+			moduleBindings.size === 0 ? null : moduleBindings,
+		);
+	}
 	const constObjects = collectSingleUseConstObjects(analysis.ast);
 	const elementUpdates = new Map();
 	const objectUpdates = new Map();
 	const updateElement = (node) => {
 		let update = elementUpdates.get(node);
 		if (update === undefined) {
-			update = { permanentStatic: false, removedAttributes: new Set() };
+			update = { permanentStatic: false, independent: null, removedAttributes: new Set() };
 			elementUpdates.set(node, update);
 		}
 		return update;
@@ -1914,6 +2236,12 @@ export function prepareServerHydrateBoundaries(source, filename, parsedAst = nul
 		}
 	};
 	for (const boundary of analysis.boundaries) {
+		if (boundary.independent) {
+			updateElement(boundary.node).independent = {
+				manifest: boundary.independentManifest,
+				captures: boundary.independentCaptures,
+			};
+		}
 		if (boundary.permanentStatic) {
 			updateElement(boundary.node).permanentStatic = true;
 		}
@@ -1947,13 +2275,27 @@ export function prepareServerHydrateBoundaries(source, filename, parsedAst = nul
 		const elementUpdate = elementUpdates.get(original);
 		if (elementUpdate !== undefined) {
 			const opening = node.openingElement;
+			const attributes = (opening.attributes ?? []).filter(
+				(attribute) => !elementUpdate.removedAttributes.has(attribute),
+			);
+			if (elementUpdate.independent !== null) {
+				attributes.push(
+					jsxExpressionAttribute(
+						'__independent',
+						independentManifestExpression(
+							elementUpdate.independent.manifest,
+							elementUpdate.independent.captures,
+							opening,
+						),
+						opening,
+					),
+				);
+			}
 			return {
 				...node,
 				openingElement: {
 					...opening,
-					attributes: (opening.attributes ?? []).filter(
-						(attribute) => !elementUpdate.removedAttributes.has(attribute),
-					),
+					attributes,
 					name: elementUpdate.permanentStatic
 						? permanentStaticName(opening.name, opening.name)
 						: opening.name,
@@ -1979,5 +2321,6 @@ export function prepareServerHydrateBoundaries(source, filename, parsedAst = nul
 	return {
 		ast,
 		boundaryPath: null,
+		independentWidgets,
 	};
 }

package/dist/compiler/index.d.ts

@@ -33,6 +33,9 @@ export interface OctaneCssModuleConstants {
 /** The version checked by compiler-emitted external Valdi adapter calls. */
 export const VALDI_COMPILER_ABI_VERSION: 1;
 
+/** Compiler-owned native presentation, known-shape spreads, and direct signal artifacts. */
+export const DOM_BINDING_COMPILER_ABI_VERSION: 1;
+
 export type ValdiWriterEffectiveType = 'boolean' | 'number' | 'string' | 'function' | 'style';
 
 /** An exact authored-expression fact supplied by an integration's type checker. */
@@ -51,6 +54,25 @@ export interface ValdiWriterFacts {
 	expressions: readonly ValdiWriterExpressionFact[];
 }
 
+/**
+ * A provider guarantee for a pure factory returning nullish or an object with
+ * exactly these own data fields. Result fields must remain stable throughout
+ * the render; getters or a shared result mutated during render are not valid.
+ */
+export interface KnownAttributeSpread {
+	/** Exact module specifier and imported export (`*` for a namespace). */
+	source: string;
+	imported: string;
+	/** Statically named member path from the imported binding to the factory. */
+	members?: readonly string[];
+	/** Exact stable own native presentation data fields; never accessors. */
+	fields: readonly string[];
+	/** Use signal-aware style-object bindings; fields must include style. Omitted retains CSS text. */
+	style?: 'object';
+	/** Opt-in native JSX expression shorthand, passed as one argument to this factory. */
+	jsxAttribute?: string;
+}
+
 export interface CompileOptions {
 	mode?: 'client' | 'server';
 	hmr?: boolean | 'vite' | 'webpack';
@@ -67,6 +89,8 @@ export interface CompileOptions {
 	dataCallbackHooks?: readonly string[];
 	/** Exact authored-source facts from octane/compiler/typescript. */
 	textTypeFacts?: TextTypeFacts;
+	/** Trusted provider contracts for pure, fixed-shape native attribute factories. */
+	knownAttributeSpreads?: readonly KnownAttributeSpread[];
 	/** Optional exact attribute-expression proofs; used only by the Valdi target. */
 	valdiWriterFacts?: ValdiWriterFacts;
 	/**
@@ -107,7 +131,7 @@ export interface CompilePosition {
 
 export interface CompileDiagnostic {
 	code: string;
-	severity: 'warning' | 'error';
+	severity: 'warning' | 'error' | 'hint';
 	message: string;
 	filename: string;
 	start: CompilePosition;
@@ -203,6 +227,14 @@ export interface CompileResult {
 	diagnostics: readonly CompileDiagnostic[];
 	inspect?: CompileInspection;
 	universalRuntime?: CompileOptions['universalRuntime'];
+	/** This module contains compiler-proven signal declarations or native reads. */
+	streamedSignals?: true;
+	/** Production client constants used by compiled binding views; build-time adapter metadata. */
+	bindingConstants?: {
+		version: 1;
+		source: string;
+		names: readonly string[];
+	};
 }
 
 /** Compile authored TSRX/JSX to Octane client or server JavaScript. */
@@ -217,7 +249,12 @@ export function compile(source: string, filename: string, options?: CompileOptio
 export function compileToVolarMappings(
 	source: string,
 	filename?: string,
-	options?: { loose?: boolean; renderers?: unknown; strong?: boolean },
+	options?: {
+		loose?: boolean;
+		renderers?: unknown;
+		strong?: boolean;
+		knownAttributeSpreads?: readonly KnownAttributeSpread[];
+	},
 ): VolarCompileResult;
 
 /** @internal Shared authored-JSX diagnostic analysis for compiler integrations. */

package/dist/compiler/index.js

@@ -3,6 +3,7 @@
 // `@octanejs/vite-plugin`), which is where its `node:fs`/`node:path` graph
 // belongs.
 export { compile } from './compile.js';
+export { DOM_BINDING_COMPILER_ABI_VERSION } from './dom-bindings.js';
 export { VALDI_COMPILER_ABI_VERSION } from './compile-valdi.js';
 export { analyzeNativeChangeDiagnostics as __analyzeNativeChangeDiagnostics } from './native-change-diagnostics.js';
 export { compileToVolarMappings } from './volar.js';