octane 0.2.12 → 0.2.13

package/dist/compiler/template-ir.js

@@ -0,0 +1,200 @@
+// ---------------------------------------------------------------------------
+// Template IR + origin recording (`inspect: true`). Static template HTML is
+// runtime DATA, not JavaScript syntax: the browser-facing `template(html)` ABI
+// intentionally stays a string. The compiler represents that data as a
+// structured tree of elements and typed data chunks until allocTemplate
+// serializes the completed template exactly once. Child templates compose by
+// transferring nodes, so no intermediate HTML is joined and no origin offsets
+// need to be shifted during construction. Origin spans remain local to their
+// chunk; the one serializer shifts them into final logical-HTML coordinates.
+//
+// Origin collection stays gated on `ctx.inspect`. The normal compile path pays
+// for the template chunks (the structural representation replacing string
+// concatenation) but not for source-span arrays.
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ start: number, end: number, srcStart: number, srcEnd: number,
+ *   kind: 'tag-open' | 'tag-close' | 'attr-name' | 'attr-value' | 'text' }} TemplateOrigin
+ */
+
+/**
+ * @typedef {'syntax' | 'tag-open' | 'tag-close' | 'attribute' | 'text' |
+ *   'anchor' | 'fragment-open' | 'fragment-close' | 'raw'} TemplatePartKind
+ */
+
+/**
+ * @typedef {{
+ *   type: 'TemplatePart',
+ *   kind: TemplatePartKind,
+ *   value: string,
+ *   origins: TemplateOrigin[] | null,
+ *   length: number,
+ * }} TemplatePart
+ */
+
+/**
+ * @typedef {{
+ *   type: 'TemplateElement',
+ *   tag: string,
+ *   namespace: string,
+ *   synthetic: boolean,
+ *   opening: TemplatePart,
+ *   attributes: TemplatePart[],
+ *   openingEnd: TemplatePart,
+ *   children: TemplateNode[],
+ *   closing: TemplatePart | null,
+ *   length: number,
+ * }} TemplateElement
+ */
+
+/** @typedef {TemplatePart | TemplateElement} TemplateNode */
+
+/**
+ * @typedef {{
+ *   type: 'Template',
+ *   parts: TemplateNode[],
+ *   length: number,
+ * }} TemplateIR
+ */
+
+/** @returns {TemplateIR} */
+export function createTemplateIr() {
+	return { type: 'Template', parts: [], length: 0 };
+}
+
+/**
+ * @param {string} value
+ * @param {TemplatePartKind} [kind]
+ * @param {TemplateOrigin[] | null} [origins]
+ * @returns {TemplatePart}
+ */
+export function createTemplatePart(value, kind = 'raw', origins = null) {
+	return { type: 'TemplatePart', kind, value, origins, length: value.length };
+}
+
+/** @param {TemplateIR} template @param {TemplateNode} node */
+export function appendTemplateNode(template, node) {
+	template.parts.push(node);
+	template.length += node.length;
+}
+
+/**
+ * @param {TemplateIR} template
+ * @param {string} value
+ * @param {TemplatePartKind} [kind]
+ * @param {TemplateOrigin[] | null} [origins]
+ */
+export function appendTemplatePart(template, value, kind = 'raw', origins = null) {
+	if (value === '') return;
+	appendTemplateNode(template, createTemplatePart(value, kind, origins));
+}
+
+/** @param {TemplateIR} into @param {TemplateIR} child */
+export function appendTemplateIr(into, child) {
+	if (child.length === 0) return;
+	for (const part of child.parts) into.parts.push(part);
+	into.length += child.length;
+}
+
+/**
+ * @param {string} value
+ * @param {TemplatePartKind} [kind]
+ * @param {TemplateOrigin[] | null} [origins]
+ * @returns {TemplateIR}
+ */
+export function templatePart(value, kind = 'raw', origins = null) {
+	const template = createTemplateIr();
+	appendTemplatePart(template, value, kind, origins);
+	return template;
+}
+
+/**
+ * @param {string} tag
+ * @param {string} namespace
+ * @param {boolean} voidElement
+ * @param {TemplateIR} attributes
+ * @param {TemplateIR} children
+ * @param {TemplateOrigin[] | null} openOrigins
+ * @param {TemplateOrigin[] | null} closeOrigins
+ * @param {boolean} [synthetic]
+ * @returns {TemplateIR}
+ */
+export function templateElement(
+	tag,
+	namespace,
+	voidElement,
+	attributes,
+	children,
+	openOrigins,
+	closeOrigins,
+	synthetic = false,
+) {
+	const opening = createTemplatePart(`<${tag}`, 'tag-open', openOrigins);
+	const openingEnd = createTemplatePart(voidElement ? '/>' : '>', 'syntax');
+	const closing = voidElement ? null : createTemplatePart(`</${tag}>`, 'tag-close', closeOrigins);
+	const node = {
+		type: 'TemplateElement',
+		tag,
+		namespace,
+		synthetic,
+		opening,
+		attributes: /** @type {TemplatePart[]} */ (attributes.parts),
+		openingEnd,
+		children: children.parts,
+		closing,
+		length:
+			opening.value.length +
+			attributes.length +
+			openingEnd.value.length +
+			children.length +
+			(closing === null ? 0 : closing.value.length),
+	};
+	const template = createTemplateIr();
+	appendTemplateNode(template, node);
+	return template;
+}
+
+/**
+ * Serialize the completed template once. The IR already contains the exact
+ * runtime bytes; this pass only joins them and converts chunk-local origins to
+ * final logical-HTML offsets.
+ *
+ * @param {TemplateIR} template
+ */
+export function serializeTemplateIr(template) {
+	const values = [];
+	let origins = null;
+	let offset = 0;
+	const appendPart = (part) => {
+		values.push(part.value);
+		if (part.origins !== null) {
+			origins ??= [];
+			for (const origin of part.origins) {
+				origins.push({
+					start: origin.start + offset,
+					end: origin.end + offset,
+					srcStart: origin.srcStart,
+					srcEnd: origin.srcEnd,
+					kind: origin.kind,
+				});
+			}
+		}
+		offset += part.value.length;
+	};
+	const visit = (node) => {
+		if (node.type === 'TemplatePart') {
+			appendPart(node);
+			return;
+		}
+		appendPart(node.opening);
+		for (const attribute of node.attributes) appendPart(attribute);
+		appendPart(node.openingEnd);
+		for (const child of node.children) visit(child);
+		if (node.closing !== null) appendPart(node.closing);
+	};
+	for (const node of template.parts) {
+		visit(node);
+	}
+	return { html: values.join(''), origins };
+}

package/dist/compiler/typescript.d.ts

@@ -23,6 +23,8 @@ export interface TextTypeProjectOptions {
 	root?: string;
 	/** The same renderer configuration used by the Octane compiler. */
 	renderers?: unknown;
+	/** The same native attribute contracts used by runtime compilation. */
+	knownAttributeSpreads?: readonly import('./index.js').KnownAttributeSpread[];
 }
 
 export interface TextTypeProject {

package/dist/compiler/typescript.js

@@ -421,6 +421,7 @@ export function createTextTypeProject(options) {
 		try {
 			compilation = compileToVolarMappings(source, rendererFilename(file, rendererRoot), {
 				renderers,
+				knownAttributeSpreads: options.knownAttributeSpreads,
 			});
 		} catch {
 			// Broken authored syntax is not evidence. Passing the authored text
@@ -495,6 +496,7 @@ export function createTextTypeProject(options) {
 				options: program.getCompilerOptions(),
 				references: loadConfig().projectReferences ?? [],
 				renderers: renderers.signature,
+				knownAttributeSpreads: options.knownAttributeSpreads,
 				rendererRoot,
 				roots: roots(),
 				inputs,

package/dist/compiler/vite.d.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from 'vite';
-import type { OctaneCssModuleConstants } from './index.js';
+import type { KnownAttributeSpread, OctaneCssModuleConstants } from './index.js';
 
 export type { OctaneCssModuleConstants } from './index.js';
 
@@ -87,6 +87,8 @@ export interface OctaneVitePluginOptions {
 	 * @default false
 	 */
 	strong?: boolean;
+	/** Trusted adapter output shapes; imported calls keep one evaluation per native host. */
+	knownAttributeSpreads?: readonly KnownAttributeSpread[];
 	/**
 	 * @experimental Infer primitive child text from a TypeScript project in
 	 * one-shot production builds. Serve and watched builds retain syntax

package/dist/compiler/vite.js

@@ -19,6 +19,7 @@ import * as nodePath from 'node:path';
 import { parseModule } from '@tsrx/core';
 import {
 	CLIENT_REFERENCE_MANIFEST_FILENAME,
+	INDEPENDENT_HYDRATION_MANIFEST_FILENAME,
 	cleanModuleId,
 	createClientReferenceManifest,
 	createOctaneCompiler,
@@ -40,6 +41,7 @@ const PROFILE_DEFINE = '__OCTANE_PROFILE_ENABLED__';
 const VOID_EXPORTS_META = 'octane:void-component-exports';
 const DESCRIPTOR_CHILDREN_EXPORTS_META = 'octane:descriptor-children-exports';
 const CLIENT_REFERENCE_META = 'octane:client-reference';
+const INDEPENDENT_WIDGETS_META = 'octane:independent-widgets';
 const DESCRIPTOR_PREFLIGHT_AUTHORITY = Symbol('octane.descriptor-preflight');
 
 function realRoot(path) {
@@ -68,6 +70,77 @@ function clientReferenceManifest(context, bundle) {
 	return createClientReferenceManifest(entries);
 }
 
+function independentWidgetManifest(context, bundle, clientBuildId) {
+	if (
+		clientBuildId !== undefined &&
+		(typeof clientBuildId !== 'string' || clientBuildId.length === 0)
+	) {
+		throw new Error('Octane client build identity must be a non-empty string.');
+	}
+	const chunks = Object.values(bundle).filter((output) => output.type === 'chunk');
+	const chunksByFile = new Map(chunks.map((chunk) => [chunk.fileName, chunk]));
+	const collectStyles = (chunk, seen = new Set()) => {
+		if (seen.has(chunk.fileName)) return [];
+		seen.add(chunk.fileName);
+		const styles = [...(chunk.viteMetadata?.importedCss ?? [])];
+		for (const imported of [...(chunk.imports ?? []), ...(chunk.dynamicImports ?? [])]) {
+			const dependency = chunksByFile.get(imported);
+			if (dependency !== undefined) styles.push(...collectStyles(dependency, seen));
+		}
+		return styles;
+	};
+	const widgets = {};
+	for (const sourceChunk of chunks) {
+		for (const sourceModuleId of Object.keys(sourceChunk.modules ?? {})) {
+			const templates = context.getModuleInfo(sourceModuleId)?.meta?.[INDEPENDENT_WIDGETS_META];
+			if (!Array.isArray(templates)) continue;
+			for (const template of templates) {
+				const query = template.request.slice(template.request.indexOf('?'));
+				const entry = chunks.find((chunk) =>
+					Object.keys(chunk.modules ?? {}).some(
+						(moduleId) =>
+							cleanModuleId(moduleId) === cleanModuleId(sourceModuleId) && moduleId.includes(query),
+					),
+				);
+				if (entry === undefined) {
+					throw new Error(
+						`Octane independent Hydrate ${JSON.stringify(template.boundaryId)} has no emitted activation chunk.`,
+					);
+				}
+				widgets[template.boundaryId] = {
+					version: 1,
+					boundaryId: template.boundaryId,
+					moduleId: entry.fileName,
+					exportName: template.exportName,
+					captureSchema: template.captureSchema,
+					hookSeed: template.hookSeed,
+					idSeed: template.idSeed,
+					signalSites: template.signalSites,
+					styles: [...new Set(collectStyles(entry))].sort(),
+					parentDependencies: false,
+				};
+			}
+		}
+	}
+	const records = Object.fromEntries(
+		Object.entries(widgets).sort(([left], [right]) => left.localeCompare(right)),
+	);
+	const buildId =
+		clientBuildId ??
+		nodeCrypto
+			.createHash('sha256')
+			.update(
+				JSON.stringify(
+					chunks
+						.map((chunk) => [chunk.fileName, chunk.code])
+						.sort(([a], [b]) => a.localeCompare(b)),
+				),
+			)
+			.digest('base64url')
+			.slice(0, 16);
+	return { version: 1, buildId, widgets: records };
+}
+
 function voidImportKey(request, imported) {
 	return `${request}\0${imported}`;
 }
@@ -684,6 +757,7 @@ export function octane(options = {}) {
 		exclude: options.exclude,
 		profile: profileEnabled,
 		strong: options.strong,
+		knownAttributeSpreads: options.knownAttributeSpreads,
 		renderers: options.renderers,
 		requireDirective,
 		warn,
@@ -704,6 +778,7 @@ export function octane(options = {}) {
 			exclude: options.exclude,
 			profile: profileEnabled,
 			strong: options.strong,
+			knownAttributeSpreads: options.knownAttributeSpreads,
 			renderers: options.renderers,
 			requireDirective,
 			warn,
@@ -813,13 +888,43 @@ export function octane(options = {}) {
 		},
 		generateBundle(_outputOptions, bundle) {
 			if (!emitClientReferenceManifest) return;
-			const manifest = clientReferenceManifest(this, bundle);
-			if (Object.keys(manifest.references).length === 0) return;
+			const clientReferences = clientReferenceManifest(this, bundle);
+			if (Object.keys(clientReferences.references).length > 0) {
+				this.emitFile({
+					type: 'asset',
+					fileName: CLIENT_REFERENCE_MANIFEST_FILENAME,
+					source: JSON.stringify(clientReferences, null, 2) + '\n',
+				});
+			}
+			const independentWidgets = independentWidgetManifest(
+				this,
+				bundle,
+				options.__clientBuildId?.(),
+			);
 			this.emitFile({
 				type: 'asset',
-				fileName: CLIENT_REFERENCE_MANIFEST_FILENAME,
-				source: JSON.stringify(manifest, null, 2) + '\n',
+				fileName: 'octane-client-build.json',
+				source:
+					JSON.stringify(
+						{
+							version: 1,
+							buildId: independentWidgets.buildId,
+							mode: 'production',
+							capabilities: {
+								independentHydration: Object.keys(independentWidgets.widgets).length > 0,
+							},
+						},
+						null,
+						2,
+					) + '\n',
 			});
+			if (Object.keys(independentWidgets.widgets).length > 0) {
+				this.emitFile({
+					type: 'asset',
+					fileName: INDEPENDENT_HYDRATION_MANIFEST_FILENAME,
+					source: JSON.stringify(independentWidgets, null, 2) + '\n',
+				});
+			}
 		},
 		async resolveId(source, importer, resolveOptions) {
 			if (!resolveOptions?.ssr) return null;
@@ -931,6 +1036,7 @@ export function octane(options = {}) {
 							}),
 				});
 				if (result === null) {
+					options.__onIndependentWidgets?.(id, environment, [], false);
 					if (propagatedExports.length === 0) return null;
 					return {
 						code,
@@ -943,11 +1049,23 @@ export function octane(options = {}) {
 					};
 				}
 				cssImports?.consume(result.cssModuleConstantImports);
+				options.__onIndependentWidgets?.(
+					id,
+					environment,
+					Array.isArray(result.independentWidgets) ? result.independentWidgets : [],
+					result.streamedSignals === true,
+				);
 				for (const dependency of result.dependencies) this.addWatchFile?.(dependency);
 				const meta = {};
+				if (result.bindingConstants !== undefined) {
+					meta['octane:binding-constants'] = result.bindingConstants;
+				}
 				if (result.clientReference !== undefined) {
 					meta[CLIENT_REFERENCE_META] = result.clientReference;
 				}
+				if (Array.isArray(result.independentWidgets) && result.independentWidgets.length > 0) {
+					meta[INDEPENDENT_WIDGETS_META] = result.independentWidgets;
+				}
 				if (result.kind === 'compile' && Array.isArray(result.voidComponentExports)) {
 					meta[VOID_EXPORTS_META] = {
 						exports: result.voidComponentExports ?? [],

package/dist/compiler/volar.d.ts

@@ -3,7 +3,12 @@
 export function compileToVolarMappings(
 	source: string,
 	filename?: string,
-	options?: { loose?: boolean; renderers?: unknown; strong?: boolean },
+	options?: {
+		loose?: boolean;
+		renderers?: unknown;
+		strong?: boolean;
+		knownAttributeSpreads?: readonly import('./index.js').KnownAttributeSpread[];
+	},
 ): import('./index.js').VolarCompileResult;
 
 /** Virtual TSX and authored ranges used by compiler inspection tooling. */