octane 0.1.24 → 0.1.26

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/dist/runtime.js

@@ -100,6 +100,14 @@ function profilePortalComponent(rawBody) {
 function ensureHooks(scope) {
   return scope.hooks ?? (scope.hooks = /* @__PURE__ */ new Map());
 }
+function registerHookCleanup(scope, cleanup) {
+  if (process.env.NODE_ENV !== "production") {
+    if (scope.block.body[HMR] !== void 0) {
+      cleanup[HMR] = true;
+    }
+  }
+  (scope.cleanups ??= []).push(cleanup);
+}
 let nextHookSlot = 0;
 function hookSlots(count) {
   const base = nextHookSlot;
@@ -2446,7 +2454,7 @@ function unmountScope(scope, detachDom = true) {
     unmountScopeChildrenAndSlots(scope, detachDom);
   });
 }
-function unmountScopeChildrenAndSlots(scope, detachDom) {
+function runScopeCleanups(scope) {
   const c = scope.cleanups;
   if (c !== null)
     for (let i = c.length - 1; i >= 0; i--) {
@@ -2456,6 +2464,12 @@ function unmountScopeChildrenAndSlots(scope, detachDom) {
         reportTeardownError(err);
       }
     }
+}
+function unmountScopeChildrenAndSlots(scope, detachDom) {
+  runScopeCleanups(scope);
+  unmountScopeChildrenAndSlotsOnly(scope, detachDom);
+}
+function unmountScopeChildrenAndSlotsOnly(scope, detachDom) {
   const children = scope.children;
   if (children !== null)
     for (let i = 0, n = children.length; i < n; i++) unmountScope(children[i].scope, detachDom);
@@ -3123,7 +3137,7 @@ function useEffectEvent(fn, slot) {
     s = { impl: fn, active: true };
     ensureHooks(scope).set(slot, s);
     const cell2 = s;
-    (scope.cleanups ??= []).push(() => {
+    registerHookCleanup(scope, () => {
       cell2.active = false;
     });
   } else {
@@ -3205,6 +3219,87 @@ function scopedChildrenAsBody(props) {
   return (_props, scope, extra) => childrenAsBody(props.children)(void 0, scope, extra);
 }
 const CHILDREN_DIALECT_SLOT = /* @__PURE__ */ Symbol("octane.childrenDialect");
+function hasResettableHmrRange(block) {
+  const start = block.startMarker;
+  const end = block.endMarker;
+  if (start === void 0 || end === void 0) return false;
+  if (start === null || end === null) {
+    return start === null && end === null && (block.kind === "root" || block.exclusiveMarkers === true);
+  }
+  if (start !== end) {
+    return start.parentNode === block.parentNode && end.parentNode === block.parentNode;
+  }
+  for (let parent = block.parentBlock; parent !== null; parent = parent.parentBlock) {
+    if (parent.startMarker === start && parent.endMarker === end) return false;
+  }
+  return start.parentNode === block.parentNode;
+}
+function promoteHmrBlockRange(block) {
+  const root = block.startMarker;
+  if (root === null || root !== block.endMarker) return;
+  const parent = block.parentNode;
+  const rangeStart = document.createComment("hmr");
+  const rangeEnd = document.createComment("/hmr");
+  parent.insertBefore(rangeStart, root);
+  parent.insertBefore(rangeEnd, root.nextSibling);
+  block.startMarker = rangeStart;
+  block.endMarker = rangeEnd;
+  block.exclusiveMarkers = false;
+}
+function resetHmrBlock(block) {
+  if (TEARDOWN_DEPTH === 0) {
+    TEARDOWN_HANDLER = findTryHandler(block.parentBlock) ?? rendererRegionTryHandler(block);
+  }
+  TEARDOWN_DEPTH++;
+  let abortedRefs = null;
+  if (!block.mounted) {
+    abortedRefs = [];
+    collectVisibleSubtreeRefs(block, abortedRefs);
+  }
+  try {
+    withRefDetachSuppression(abortedRefs, () => {
+      if (block.deoptNode !== null) detachDeoptTreeRefs(block.deoptNode, null);
+      const cleanups = block.cleanups;
+      let preserved = null;
+      if (cleanups !== null) {
+        for (let i = cleanups.length - 1; i >= 0; i--) {
+          const cleanup = cleanups[i];
+          if (cleanup[HMR] === true) continue;
+          try {
+            runEffectLifecycleCallback(cleanup);
+          } catch (err) {
+            reportTeardownError(err);
+          }
+        }
+        for (let i = 0; i < cleanups.length; i++) {
+          const cleanup = cleanups[i];
+          if (cleanup[HMR] === true) (preserved ??= []).push(cleanup);
+        }
+      }
+      unmountScopeChildrenAndSlotsOnly(block, true);
+      removeRange(
+        block.startMarker !== null ? block.startMarker.nextSibling : block.parentNode.firstChild,
+        block.endMarker
+      );
+      block.children = null;
+      block.cleanups = preserved;
+      block._slots = null;
+      block.refFields = null;
+      block.slots = [];
+      block.deoptNode = null;
+    });
+    const hooks = block.hooks;
+    if (hooks !== null) {
+      for (const value of hooks.values()) {
+        if (value !== null && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, "deps")) {
+          value.deps = void 0;
+        }
+      }
+    }
+  } finally {
+    if (--TEARDOWN_DEPTH === 0) dispatchTeardownErrors();
+  }
+}
 function resetScopeChildren(scope) {
   const block = scope.block;
   if (TEARDOWN_DEPTH === 0) {
@@ -10559,6 +10654,13 @@ function hmr(fn) {
       const nextFn = incomingMeta ? incomingMeta.fn : incoming;
       if (meta.fn.__octaneReturnedOutput !== nextFn.__octaneReturnedOutput)
         return false;
+      for (const b of meta.liveBlocks) {
+        if (b.disposed) {
+          meta.liveBlocks.delete(b);
+          continue;
+        }
+        if (!hasResettableHmrRange(b)) return false;
+      }
       meta.fn = nextFn;
       if (typeof __OCTANE_PROFILE_ENABLED__ !== "undefined" && __OCTANE_PROFILE_ENABLED__)
         __profileComponentSource(wrapper, meta.fn);
@@ -10573,6 +10675,8 @@ function hmr(fn) {
         b.body = wrapper;
         if (typeof __OCTANE_PROFILE_ENABLED__ !== "undefined" && __OCTANE_PROFILE_ENABLED__)
           __profileSchedule(b, "hmr");
+        promoteHmrBlockRange(b);
+        resetHmrBlock(b);
         scheduleRender(b);
       }
       return true;
@@ -11684,7 +11788,7 @@ function useTransition(slot) {
       }
     };
     TRANSITION_LISTENERS.add(listener);
-    (scope.cleanups ??= []).push(() => TRANSITION_LISTENERS.delete(listener));
+    registerHookCleanup(scope, () => TRANSITION_LISTENERS.delete(listener));
   }
   return [s.isPending, s.start];
 }
@@ -11786,7 +11890,7 @@ function useFormStatus(slot) {
     s = { form: null, listener: null };
     const slotRef = s;
     ensureHooks(scope).set(slot, slotRef);
-    (scope.cleanups ??= []).push(() => {
+    registerHookCleanup(scope, () => {
       if (slotRef.form && slotRef.listener)
         FORM_STATUS_LISTENERS.get(slotRef.form)?.delete(slotRef.listener);
     });
@@ -11861,7 +11965,7 @@ function useOptimistic(passthrough, updateFnOrSlot, slot) {
       if (TRANSITION_PENDING_COUNT === 0 && slotRef.armed) clear();
     };
     TRANSITION_LISTENERS.add(listener);
-    (scope.cleanups ??= []).push(() => TRANSITION_LISTENERS.delete(listener));
+    registerHookCleanup(scope, () => TRANSITION_LISTENERS.delete(listener));
   }
   s.updateFn = updateFn;
   let optimistic = passthrough;

package/dist/universal-core.d.ts

@@ -611,6 +611,7 @@ export interface ObjectHostInstance {
 }
 interface ObjectDriverState {
     instances: Map<number, ObjectHostInstance>;
+    parents: Map<number, number | null>;
     events: Map<number, Map<string, UniversalEventListenerDescriptor>>;
     lifecycles: Map<number, Map<string, UniversalListenerDescriptor>>;
     localCallbacks: Map<number, Map<string, UniversalListenerDescriptor>>;