octane 0.1.24 → 0.1.25

package/README.md

@@ -17,6 +17,10 @@ wrapper is narrower: the wrapper must be locally declared in a fully compiled
 parameter to a supported hook. This package ships both the runtime and compiler,
 with the compiler exposed at `octane/compiler`.
 
+Direct Node or Bun server scripts can preload `octane/compiler/register` to
+compile imported Octane components without going through Vite. See the
+[SSR guide](https://github.com/octanejs/octane/blob/main/docs/ssr.md#run-an-ssg-script-directly).
+
 For the full story, see the
 [main README](https://github.com/octanejs/octane#readme).
 

package/dist/compiler/bundler.js

@@ -31,6 +31,7 @@ import { findLeadingJsxImportSourcePragma } from './pragma.js';
 import { normalizeUniversalRuntime } from './universal-runtime.js';
 import { formatCompileDiagnostic } from './native-change-diagnostics.js';
 import { findVoidComponentImports, findVoidRootImports, slotHooks } from './slot-hooks.js';
+import { rewriteServerRuntimeRequests } from './runtime-requests.js';
 import { assertStrongMode } from './strong-mode.js';
 import {
 	assertNoLiveClientOnlyImports,
@@ -848,6 +849,20 @@ class OctaneBundlerCompiler {
 			options.universalRuntime ?? this.defaults.universalRuntime,
 		);
 		const filename = this._canonicalModuleId(file);
+		const targetRuntimeRequests = (source, kind) => {
+			if (environment !== 'server' || options.explicitRuntimeRequests !== true) return null;
+			const runtimeResult = rewriteServerRuntimeRequests(source, filename);
+			if (runtimeResult === null) return null;
+			return {
+				code: runtimeResult.code,
+				map: runtimeResult.map,
+				kind,
+				...finishMetadata(collected),
+			};
+		};
+		const passThrough = () => {
+			return targetRuntimeRequests(code, 'runtime-requests') ?? this._passThrough(code, collected);
+		};
 		const clientOnlyImports =
 			environment === 'server' && Array.isArray(options.clientOnlyImports)
 				? options.clientOnlyImports
@@ -974,22 +989,22 @@ class OctaneBundlerCompiler {
 			if (this.requireDirective && !pragmaOwned && this._isProjectOwnedSource(file)) {
 				this._warnUnmarkedOctaneImport(code, filename);
 			}
-			return this._passThrough(code, collected);
+			return passThrough();
 		}
 
 		if (plainHelperSource) {
-			if (/\/\/\s*octane-no-slot\b/.test(code)) return null;
+			if (/\/\/\s*octane-no-slot\b/.test(code)) return passThrough();
 			if (this.exclude.some((path) => file.includes(path))) {
 				// Same conflict diagnostic as the full-compile gate: an ownership
 				// pragma inside an excluded path must not fail silent.
 				if (this.requireDirective) {
 					this._warnExcludedPragmaConflict(file, filename, pragmaOwned);
 				}
-				return null;
+				return passThrough();
 			}
-			if (!/from\s*['"]octane['"]/.test(code)) return null;
+			if (!/from\s*['"]octane['"]/.test(code)) return passThrough();
 			if (!this._isInstalledOctaneSource(file, collected)) {
-				return this._passThrough(code, collected);
+				return passThrough();
 			}
 			// Hook slotting is an Octane-ownership rewrite, so the ownership
 			// gate applies to it exactly as to full compilation: an unmarked
@@ -997,7 +1012,7 @@ class OctaneBundlerCompiler {
 			// pragma diagnostic), a pragma-marked one gets its hook slots.
 			if (this.requireDirective && !pragmaOwned && this._isProjectOwnedSource(file)) {
 				this._warnUnmarkedOctaneImport(code, filename);
-				return this._passThrough(code, collected);
+				return passThrough();
 			}
 			if (this._hasManualHookSlots(file, collected)) {
 				// Hand-slotted bindings still own their authored policy. Opting one
@@ -1008,7 +1023,7 @@ class OctaneBundlerCompiler {
 						strong,
 					});
 				}
-				return this._passThrough(code, collected);
+				return passThrough();
 			}
 			const profileFilename = profile ? this._profileModuleId(file, collected) : undefined;
 			const specializeVoidRoot =
@@ -1025,16 +1040,18 @@ class OctaneBundlerCompiler {
 						}
 					: {}),
 			});
-			if (out === null) return this._passThrough(code, collected);
-			return {
-				code: out.code,
-				map: out.map,
-				kind: 'slots',
-				...finishMetadata(collected),
-			};
+			if (out === null) return passThrough();
+			return (
+				targetRuntimeRequests(out.code, 'slots') ?? {
+					code: out.code,
+					map: out.map,
+					kind: 'slots',
+					...finishMetadata(collected),
+				}
+			);
 		}
 
-		return null;
+		return passThrough();
 	}
 }
 

package/dist/compiler/register.js

@@ -0,0 +1,144 @@
+/**
+ * Synchronous server-script compiler registration.
+ *
+ * Import this module before a Node or Bun entry point to compile authored
+ * `.tsrx`/`.tsx` modules and slot Octane hooks in plain `.ts`/`.js` helpers.
+ * Direct execution is a server pipeline, so authored `octane` runtime imports
+ * resolve to `octane/server`, matching the server code the compiler emits.
+ */
+import * as nodeFs from 'node:fs';
+import * as nodeModule from 'node:module';
+import * as nodePath from 'node:path';
+import * as nodeUrl from 'node:url';
+import { createOctaneCompiler } from './bundler.js';
+
+const compiler = createOctaneCompiler({
+	root: process.cwd(),
+	environment: 'server',
+	hmr: false,
+	dev: false,
+});
+
+const extensionlessCandidates = ['.tsrx', '.tsx', '.ts', '.mts', '.mjs', '.js'];
+
+function isFile(path) {
+	try {
+		return nodeFs.statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+
+function candidateUrl(specifier, parentURL) {
+	if (parentURL === undefined || !parentURL.startsWith('file:')) return null;
+	if (!specifier.startsWith('.') && !specifier.startsWith('/') && !specifier.startsWith('file:')) {
+		return null;
+	}
+
+	let requested;
+	try {
+		requested = new URL(specifier, parentURL);
+	} catch {
+		return null;
+	}
+	if (requested.protocol !== 'file:') return null;
+
+	const requestedPath = nodeUrl.fileURLToPath(requested);
+	const extension = nodePath.extname(requestedPath);
+	const candidates = [];
+	if (extension === '') {
+		for (const candidateExtension of extensionlessCandidates) {
+			candidates.push(requestedPath + candidateExtension);
+		}
+		for (const candidateExtension of extensionlessCandidates) {
+			candidates.push(nodePath.join(requestedPath, 'index' + candidateExtension));
+		}
+	} else if (extension === '.js') {
+		const stem = requestedPath.slice(0, -extension.length);
+		candidates.push(stem + '.ts', stem + '.tsx');
+	} else if (extension === '.mjs') {
+		candidates.push(requestedPath.slice(0, -extension.length) + '.mts');
+	} else if (extension === '.cjs') {
+		candidates.push(requestedPath.slice(0, -extension.length) + '.cts');
+	}
+
+	for (const candidate of candidates) {
+		if (!isFile(candidate)) continue;
+		const resolved = nodeUrl.pathToFileURL(candidate);
+		resolved.search = requested.search;
+		resolved.hash = requested.hash;
+		return resolved.href;
+	}
+	return null;
+}
+
+function sourceText(source) {
+	if (typeof source === 'string') return source;
+	if (source === undefined) return null;
+	return new TextDecoder().decode(source);
+}
+
+function resolve(specifier, context, nextResolve) {
+	const runtimeRequest = compiler.resolveRuntimeRequest(specifier, 'server');
+	if (runtimeRequest !== null) return nextResolve(runtimeRequest, context);
+
+	try {
+		return nextResolve(specifier, context);
+	} catch (error) {
+		const url = candidateUrl(specifier, context.parentURL);
+		if (url !== null) return { url, shortCircuit: true };
+		throw error;
+	}
+}
+
+function load(url, context, nextLoad) {
+	if (!url.startsWith('file:')) return nextLoad(url, context);
+	const filename = nodeUrl.fileURLToPath(url);
+
+	if (filename.endsWith('.tsrx') || filename.endsWith('.tsx')) {
+		const source = nodeFs.readFileSync(filename, 'utf8');
+		const result = compiler.transform(source, filename, { environment: 'server' });
+		if (result === null || result.kind === 'none') return nextLoad(url, context);
+		return { format: 'module', source: result.code, shortCircuit: true };
+	}
+
+	if ((filename.endsWith('.ts') && !filename.endsWith('.d.ts')) || filename.endsWith('.js')) {
+		const loaded = nextLoad(url, context);
+		const source = sourceText(loaded.source);
+		if (source === null) return loaded;
+		const result = compiler.transform(source, filename, { environment: 'server' });
+		if (result === null || result.kind === 'none') return loaded;
+		return { ...loaded, source: result.code, shortCircuit: true };
+	}
+
+	return nextLoad(url, context);
+}
+
+function registerBunPlugin() {
+	globalThis.Bun.plugin({
+		name: 'octane-compiler',
+		setup(build) {
+			build.onLoad({ filter: /\.(?:tsrx|tsx|ts|js)$/, namespace: 'file' }, ({ path }) => {
+				const source = nodeFs.readFileSync(path, 'utf8');
+				const result = compiler.transform(source, path, {
+					environment: 'server',
+					explicitRuntimeRequests: true,
+				});
+				const loader =
+					path.endsWith('.tsx') || path.endsWith('.tsrx')
+						? 'tsx'
+						: path.endsWith('.ts')
+							? 'ts'
+							: 'js';
+				if (result === null || result.kind === 'none') return { contents: source, loader };
+				return {
+					contents: result.code,
+					loader: result.kind === 'slots' || result.kind === 'runtime-requests' ? loader : 'js',
+				};
+			});
+		},
+	});
+}
+
+if (typeof globalThis.Bun === 'object') registerBunPlugin();
+else nodeModule.registerHooks({ resolve, load });

package/dist/compiler/runtime-requests.js

@@ -0,0 +1,36 @@
+import { initSync as initModuleLexer, parse as lexModule } from 'es-module-lexer';
+
+let moduleLexerInitialized = false;
+
+/** Target bare Octane ESM requests at the explicit server runtime. */
+export function rewriteServerRuntimeRequests(source, id) {
+	if (!source.includes('octane')) return null;
+	if (!moduleLexerInitialized) {
+		initModuleLexer();
+		moduleLexerInitialized = true;
+	}
+
+	let imports;
+	try {
+		[imports] = lexModule(source, id);
+	} catch {
+		return null;
+	}
+
+	let code = source;
+	let changed = false;
+	for (let index = imports.length - 1; index >= 0; index--) {
+		const request = imports[index];
+		if (request.n !== 'octane') continue;
+		if (request.d === -1) {
+			code = code.slice(0, request.s) + 'octane/server' + code.slice(request.e);
+			changed = true;
+			continue;
+		}
+		const quote = source[request.s];
+		if (quote !== "'" && quote !== '"' && quote !== '`') continue;
+		code = code.slice(0, request.s) + `${quote}octane/server${quote}` + code.slice(request.e);
+		changed = true;
+	}
+	return changed ? { code, map: null } : null;
+}

package/dist/compiler/slot-hooks.js

@@ -27,6 +27,13 @@ function octaneHookLocals(ast) {
 	let importsHook = false;
 	let hasOctaneImport = false;
 	for (const node of ast.body || []) {
+		if (
+			(node.type === 'ExportNamedDeclaration' || node.type === 'ExportAllDeclaration') &&
+			node.source?.value === 'octane'
+		) {
+			hasOctaneImport = true;
+			continue;
+		}
 		if (node.type !== 'ImportDeclaration' || node.source?.value !== 'octane') continue;
 		hasOctaneImport = true;
 		for (const sp of node.specifiers || []) {
@@ -1025,7 +1032,9 @@ export function slotHooks(source, id, options) {
 		!options?.profile &&
 		typeof options?.isVoidComponentImport === 'function' &&
 		importInfo.hasOctaneImport;
-	if (!importInfo.importsHook && !canSpecializeRoot) return null;
+	if (!importInfo.importsHook && !canSpecializeRoot) {
+		return null;
+	}
 	// The parsed tree is never mutated: annotateHookCalls returns a COW-rebuilt
 	// module whose hook calls carry their `_octane*` props (start/end offsets are
 	// preserved, so the text edits below stay valid), with the dependency
@@ -1072,8 +1081,11 @@ export function slotHooks(source, id, options) {
 	// Apply insertions right-to-left so earlier offsets stay valid.
 	st.edits.sort((a, b) => b.pos - a.pos);
 	let code = source;
-	for (const e of st.edits) {
-		code = code.slice(0, e.pos) + e.text + code.slice(e.end === undefined ? e.pos : e.end);
+	for (const edit of st.edits) {
+		code =
+			code.slice(0, edit.pos) +
+			edit.text +
+			code.slice(edit.end === undefined ? edit.pos : edit.end);
 	}
 
 	// APPEND the slot consts (rather than prepend) so every original line number

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "octane",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
   "engines": {
-    "node": ">=22"
+    "node": ">=22.22.2"
   },
   "description": "A fast, modern UI framework and the successor to Inferno",
   "author": {
@@ -85,6 +85,7 @@
     },
     "./compiler": "./dist/compiler/index.js",
     "./compiler/bundler": "./dist/compiler/bundler.js",
+    "./compiler/register": "./dist/compiler/register.js",
     "./compiler/renderers": "./dist/compiler/renderers.js",
     "./compiler/vite": {
       "types": "./dist/compiler/vite.d.ts",
@@ -99,6 +100,7 @@
     "@tsrx/core": "^0.1.56",
     "@types/react": "^19.2.17",
     "devalue": "^5.8.2",
+    "es-module-lexer": "^1.7.0",
     "esrap": "^2.3.0"
   },
   "peerDependencies": {