@octanejs/app-core 0.0.50 → 0.0.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/app-core",
-  "version": "0.0.50",
+  "version": "0.0.51",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -75,14 +75,14 @@
     }
   },
   "dependencies": {
-    "@ripple-ts/adapter": "^0.3.125",
+    "@ripple-ts/adapter": "^0.4.0",
     "esbuild": "^0.28.1"
   },
   "peerDependencies": {
-    "octane": "^0.1.51 || ^0.2.0"
+    "octane": "^0.2.13"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "octane": "0.2.7"
+    "octane": "0.2.13"
   }
 }

package/src/codegen.js

@@ -135,6 +135,10 @@ export function write_project_generated_file(options, name, source) {
  * @param {{
  *   configPath?: string,
  *   staticEntries?: Array<string | { id: string, specifier: string }>,
+ *   independentEntries?: Array<{ id: string, specifier: string }>,
+ *   clientBuildId?: string,
+ *   clientBuildIdExpression?: string,
+ *   devClientBuild?: boolean,
  *   resolveImport?: (id: string) => string,
  *   runtimeModuleId?: string,
  *   generatedBy?: string,
@@ -142,6 +146,12 @@ export function write_project_generated_file(options, name, source) {
  * @returns {string}
  */
 export function create_client_entry_source(options = {}) {
+	if (options.clientBuildId !== undefined && options.clientBuildIdExpression !== undefined) {
+		throw new TypeError('Provide one executing client build identity, not both forms.');
+	}
+	if (options.clientBuildId === '' || options.clientBuildIdExpression === '') {
+		throw new TypeError('The executing client build identity must not be empty.');
+	}
 	const staticEntries = new Map();
 	for (const entry of options.staticEntries ?? []) {
 		const id = typeof entry === 'string' ? entry : entry.id;
@@ -156,20 +166,74 @@ export function create_client_entry_source(options = {}) {
 			([id, specifier]) => `  ${JSON.stringify(id)}: () => import(${JSON.stringify(specifier)}),`,
 		)
 		.join('\n');
+	const independent_map_lines = (options.independentEntries ?? [])
+		.map(
+			({ id, specifier }) => `  ${JSON.stringify(id)}: () => import(${JSON.stringify(specifier)}),`,
+		)
+		.join('\n');
 
 	return `// Auto-generated by ${generatedBy}.
 // This file is written to the active integration's project cache.
 
 import { hydrateRoot, initializeHydrationEventCapture, Suspense, ErrorBoundary, createElement } from ${JSON.stringify(runtimeModuleId)};
 
+// Capture once: an HMR runtime hash may change, this document's authority must not.
+const clientBuildId = ${options.clientBuildIdExpression ?? JSON.stringify(options.clientBuildId ?? null)};
 initializeHydrationEventCapture();
 
+let independentCapability = false;
+let independentTarget;
+let signalOwner;
+let streamedHydration;
+let signalHydrationModule;
+let documentData;
+let documentLifecycle;
+let lifecycleBootstrap;
+let independentBootstrap;
+let disposeIndependentHydration;
+let incompatibleBuild = false;
+${
+	options.devClientBuild
+		? `
+if (import.meta.hot) {
+  import.meta.hot.on('octane:independent-hydration', (data) => {
+    if (data.buildId !== clientBuildId) {
+      incompatibleBuild = true;
+      documentLifecycle?.dispose();
+      disposeIndependentHydration?.();
+      streamedHydration?.dispose();
+      globalThis.location.reload();
+      return;
+    }
+    if (data.enabled !== true || incompatibleBuild) return;
+    independentCapability = true;
+    if (independentTarget) {
+      void bootstrapIndependentIslands(independentTarget).catch((error) => {
+        console.error('[octane] Independent Hydrate bootstrap failed.', error);
+      });
+    }
+  });
+  // Subscribe before asking for the current snapshot: discovery may predate entry evaluation.
+  import.meta.hot.send('octane:independent-hydration');
+}
+`
+		: ''
+}
+
 // Static import map (production): every module the server may name in
 // #__octane_data, as bundle-analyzable dynamic imports. Empty in dev.
 const routeModules = {
 ${static_map_lines}
 };
 
+// Strict independent islands are separate graph roots. Their loader closures
+// live in this bootstrap entry, never in the lexical parent component, so an
+// early interaction can fetch one widget without evaluating its parent/sibling
+// modules. The build manifest's opaque moduleId selects this registry entry.
+const independentModules = {
+${independent_map_lines}
+};
+
 // Keep the fallback native and canonical. Vite serves static \`.tsrx\` imports
 // through \`?import\`, but ordinary JS/TS imports without it. Resolve that same
 // root-absolute URL against the browsing context's real location (not a
@@ -190,6 +254,96 @@ function importModule(path) {
   return loader ? loader() : dynamicImport(path);
 }
 
+const independentStyles = new Map();
+
+function clientAssetPath(path) {
+  return path.startsWith('/') ? path : '/' + path;
+}
+
+function loadIndependentStyle(path) {
+  const href = new URL(clientAssetPath(path), globalThis.location.href).href;
+  let pending = independentStyles.get(href);
+  if (pending) return pending;
+  pending = new Promise((resolve, reject) => {
+    let link = null;
+    for (const candidate of document.querySelectorAll('link[rel="stylesheet"]')) {
+      if (candidate.href === href) {
+        link = candidate;
+        break;
+      }
+    }
+    if (link?.sheet) {
+      resolve();
+      return;
+    }
+    const owned = link === null;
+    if (!link) {
+      link = document.createElement('link');
+      link.rel = 'stylesheet';
+      link.href = href;
+    }
+    link.addEventListener('load', resolve, { once: true });
+    link.addEventListener('error', () => {
+      independentStyles.delete(href);
+      // A later activation may retry, but authored/SSR links belong to the document.
+      if (owned) link.remove();
+      reject(new Error('[octane] Failed to load independent Hydrate stylesheet: ' + href));
+    }, { once: true });
+    if (!link.isConnected) document.head.appendChild(link);
+  });
+  independentStyles.set(href, pending);
+  return pending;
+}
+
+async function bootstrapIndependentIslands(target) {
+  independentTarget = target;
+  if (incompatibleBuild) return;
+  // A supported widget may arrive during later navigation, after initial HTML.
+  // Keep its observer ready without loading optional code in feature-free apps.
+  if (
+    !independentCapability &&
+    Object.keys(independentModules).length === 0 &&
+    (!globalThis.__OCTANE_INDEPENDENT_MODULES__ || Object.keys(globalThis.__OCTANE_INDEPENDENT_MODULES__).length === 0) &&
+    !target.querySelector('script[data-octane-independent]')
+  ) return;
+  await bootstrapDocumentLifecycle();
+  if (documentLifecycle && !await documentLifecycle.whenActive()) return;
+  if (independentBootstrap) return independentBootstrap;
+  independentBootstrap = import('octane/hydration').then(async ({ bootstrapIndependentHydration }) => {
+    if (incompatibleBuild) return;
+    if (documentLifecycle && !await documentLifecycle.whenActive()) return;
+    disposeIndependentHydration = bootstrapIndependentHydration(target, {
+    ...(clientBuildId === null ? {} : { buildId: clientBuildId }),
+    ...(signalOwner === undefined ? {} : { signalOwner }),
+    loadModule: (moduleId) => {
+      const loader = independentModules[moduleId] ?? globalThis.__OCTANE_INDEPENDENT_MODULES__?.[moduleId];
+      return loader ? loader() : dynamicImport(clientAssetPath(moduleId));
+    },
+    loadStyles: (styles) => Promise.all(styles.map(loadIndependentStyle)).then(() => undefined),
+    onError: (error) => console.error('[octane] Independent Hydrate activation failed.', error),
+    });
+  });
+  return independentBootstrap;
+}
+
+async function bootstrapDocumentLifecycle() {
+  if (clientBuildId === null || !documentData?.streamedSignals) return;
+  if (lifecycleBootstrap) return lifecycleBootstrap;
+  lifecycleBootstrap = (async () => {
+    signalHydrationModule ??= await import('octane/hydration/streamed-signals');
+    if (incompatibleBuild) return;
+    documentLifecycle = signalHydrationModule.installSignalDocumentLifecycle({
+      document, buildId: clientBuildId, documentId: documentData.streamedSignals.documentId,
+      ...(signalOwner === undefined ? {} : { signalOwner }),
+      get streamedHydration() { return streamedHydration; },
+      get independentHydration() { return disposeIndependentHydration; },
+      onMismatch() { incompatibleBuild = true; globalThis.location.reload(); },
+    });
+    signalOwner = documentLifecycle.signalOwner;
+  })();
+  return lifecycleBootstrap;
+}
+
 function getComponentExport(module, exportName) {
   // Explicit export name requires an exact match; do NOT fall back, so a
   // typo'd route renders nothing rather than the wrong component.
@@ -231,12 +385,41 @@ function withRootBoundary(content, boundary) {
       return;
     }
     const data = JSON.parse(el.textContent || '{}'); // { entry, exportName, layout, params, url, preHydrate }
+    documentData = data;
+    if (incompatibleBuild) return;
+    if (clientBuildId !== null || data.clientBuild != null) {
+      if (
+        typeof clientBuildId !== 'string' || !clientBuildId ||
+        data.clientBuild?.version !== 1 || data.clientBuild.buildId !== clientBuildId ||
+        !['production', 'development'].includes(data.clientBuild.mode) ||
+        typeof data.clientBuild.capabilities?.independentHydration !== 'boolean'
+      ) throw new Error('[octane] Client build identity does not match the server document.');
+      independentCapability ||= data.clientBuild.capabilities.independentHydration;
+    }
+    if (data.streamedSignals !== undefined && (
+      !data.clientBuild || data.streamedSignals?.buildId !== clientBuildId ||
+      typeof data.streamedSignals.documentId !== 'string' || !data.streamedSignals.documentId
+    )) throw new Error('[octane] Invalid streamed signal document identity.');
+    if (globalThis.__octaneStreamedSignalSelections !== undefined) {
+      if (!data.streamedSignals) throw new Error('[octane] Missing streamed signal document identity.');
+      signalHydrationModule = await import('octane/hydration/streamed-signals');
+      if (incompatibleBuild) return;
+      streamedHydration = signalHydrationModule.bootstrapStreamedSignalHydration(data.streamedSignals);
+      signalOwner = streamedHydration.signalOwner;
+      await bootstrapDocumentLifecycle();
+    }
     if (!data.entry) {
       console.error('[octane] Unable to hydrate: no route entry in #__octane_data.');
       return;
     }
 
+    await bootstrapIndependentIslands(target);
+    if (incompatibleBuild) return;
+    if (documentLifecycle && !await documentLifecycle.whenActive()) return;
+
     const pageMod = await importModule(data.entry);
+    if (incompatibleBuild) return;
+    if (documentLifecycle && !await documentLifecycle.whenActive()) return;
     const Component = getComponentExport(pageMod, data.exportName ?? undefined);
     if (!Component) {
       console.error('[octane] Unable to hydrate: no component export for', data.entry);
@@ -251,14 +434,20 @@ function withRootBoundary(content, boundary) {
     // so hydration adopts the same resolved tree the server rendered.
     if (data.preHydrate) {
       const preMod = await importModule(data.preHydrate);
+      if (incompatibleBuild) return;
+      if (documentLifecycle && !await documentLifecycle.whenActive()) return;
       const hook = preMod.default;
       if (typeof hook === 'function') await hook({ url, params });
     }
+    if (incompatibleBuild) return;
+    if (documentLifecycle && !await documentLifecycle.whenActive()) return;
 
     // Build the same props-closing root wrapper as the server.
     let Content;
     if (data.layout) {
       const layoutMod = await importModule(data.layout);
+      if (incompatibleBuild) return;
+      if (documentLifecycle && !await documentLifecycle.whenActive()) return;
       const Layout = getComponentExport(layoutMod);
       if (Layout) {
         // children is a ComponentBody closing over the page props; octane's
@@ -279,6 +468,8 @@ function withRootBoundary(content, boundary) {
       const entry = data.rootBoundary?.[kind];
       if (!entry) continue;
       const module = await importModule(entry.path);
+      if (incompatibleBuild) return;
+      if (documentLifecycle && !await documentLifecycle.whenActive()) return;
       const Boundary = getComponentExport(module, entry.exportName ?? undefined);
       if (!Boundary) {
         console.error('[octane] Unable to hydrate: no rootBoundary component for', entry.path);
@@ -287,7 +478,10 @@ function withRootBoundary(content, boundary) {
       rootBoundary[kind] = Boundary;
     }
 
-    hydrateRoot(target, withRootBoundary(Content, rootBoundary));
+    if (incompatibleBuild) return;
+    if (documentLifecycle && !await documentLifecycle.whenActive()) return;
+    hydrateRoot(target, withRootBoundary(Content, rootBoundary), undefined,
+      signalOwner === undefined ? undefined : { signalOwner });
   } catch (error) {
     console.error('[octane] Failed to bootstrap client hydration.', error);
   }

package/src/html.js

@@ -5,6 +5,7 @@ export {
 	getContextNonce,
 	injectHydrationEntry,
 	nonceAttribute,
+	prepareStreamingHydrationTemplate,
 	splitSsrTemplate,
 	validateSsrTemplate,
 } from './server/html-template.js';

package/src/index.js

@@ -17,5 +17,11 @@ export {
 	runMiddlewareChain,
 } from './middleware.js';
 export { handleRpcRequest } from './server/rpc.js';
-export { getRequestContext, tryGetRequestContext } from './server/request-context.js';
+export {
+	getRequestContext,
+	tryGetRequestContext,
+	setRequestContextSource,
+} from './server/request-context.js';
+export { runServerRequest } from './server/signal-owners.js';
+export { createServerCallHost } from './server/server-calls.js';
 export { createRpcRegistry } from './server/rpc-registry.js';

package/src/resolve-config.js

@@ -223,6 +223,26 @@ export function resolveOctaneConfig(raw, options = {}) {
 		throw new Error('[octane] server.rpc.allowedOrigins must be an array.');
 	}
 	const allowedRpcOrigins = [...new Set((rawRpc?.allowedOrigins ?? []).map(normalize_rpc_origin))];
+	if (rawRpc?.resultLimits !== undefined) {
+		const limits = rawRpc.resultLimits;
+		if (limits === null || typeof limits !== 'object' || Array.isArray(limits)) {
+			throw new Error('[octane] server.rpc.resultLimits must be an object.');
+		}
+		for (const [key, value] of Object.entries(limits)) {
+			if (
+				!['maxFrameBytes', 'maxTotalBytes', 'timeoutMs'].includes(key) ||
+				!Number.isSafeInteger(value) ||
+				value <= 0
+			) {
+				throw new Error(
+					'[octane] server.rpc.resultLimits requires positive integer frame, total, and timeout limits.',
+				);
+			}
+		}
+		if ((limits.maxFrameBytes ?? 1048576) > (limits.maxTotalBytes ?? 16777216)) {
+			throw new Error('[octane] server.rpc.resultLimits frame limit exceeds the total limit.');
+		}
+	}
 
 	// ------------------------------------------------------------------
 	// Apply defaults
@@ -253,6 +273,7 @@ export function resolveOctaneConfig(raw, options = {}) {
 			rpc: {
 				allowedOrigins: allowedRpcOrigins,
 				maxBodyBytes: rawRpc?.maxBodyBytes ?? DEFAULT_RPC_MAX_BODY_BYTES,
+				...(rawRpc?.resultLimits === undefined ? {} : { resultLimits: { ...rawRpc.resultLimits } }),
 			},
 		},
 	};

package/src/server/html-stream.js

@@ -9,13 +9,15 @@
  * @param {string} prefix
  * @param {ReadableStream<Uint8Array>} renderStream
  * @param {string} suffix
+ * @param {string} [afterShell] Owned bootstrap after the renderer's first complete shell chunk.
  * @returns {ReadableStream<Uint8Array>}
  */
-export function composeHtmlStream(prefix, renderStream, suffix) {
+export function composeHtmlStream(prefix, renderStream, suffix, afterShell = '') {
 	const encoder = new TextEncoder();
 	const reader = renderStream.getReader();
 	let phase = 0; // 0 prefix, 1 renderer, 2 suffix, 3 closed
 	let released = false;
+	let shellWritten = false;
 
 	function release() {
 		if (released) return;
@@ -37,8 +39,14 @@ export function composeHtmlStream(prefix, renderStream, suffix) {
 						}
 
 						if (phase === 1) {
+							if (shellWritten && afterShell !== '') {
+								controller.enqueue(encoder.encode(afterShell));
+								afterShell = '';
+								return;
+							}
 							const { done, value } = await reader.read();
 							if (!done) {
+								shellWritten = true;
 								controller.enqueue(value);
 								return;
 							}

package/src/server/html-template.js

@@ -73,6 +73,61 @@ export function splitSsrTemplate(html) {
 	return [html.slice(0, at), html.slice(at + BODY_MARKER.length)];
 }
 
+/**
+ * Separate the owned bootstrap so a streaming host can publish it after its
+ * complete shell, without waiting for long-lived result channels to finish.
+ * Unrelated authored scripts keep their position and scheduling attributes.
+ * @param {string} html
+ * @returns {{ html: string, afterShell: string }}
+ */
+export function prepareStreamingHydrationTemplate(html) {
+	const scripts = html.match(/<script\b[^>]*>[\s\S]*?<\/script\s*>/gi) ?? [];
+	const entries = scripts.filter((script) =>
+		/\bdata-octane-hydrate(?:\s|=|>)/i.test(script.slice(0, script.indexOf('>') + 1)),
+	);
+	if (entries.length !== 1) {
+		throw new Error('[octane] Early hydration requires one separately identified bootstrap entry.');
+	}
+	const entry = entries[0];
+	const end = entry.indexOf('>');
+	let tag = entry
+		.slice(0, end + 1)
+		.replace(/\s(?:async|defer)(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?(?=\s|>)/gi, '')
+		.replace(/^<script\b/i, '<script data-octane-stream');
+	if (/\stype\s*=\s*(?:"module"|'module'|module)(?=\s|>)/i.test(tag)) {
+		if (
+			/\sintegrity(?:\s|=|>)/i.test(tag) ||
+			/\sreferrerpolicy(?:\s|=|>)/i.test(tag) ||
+			/\scrossorigin\s*=\s*(?:"use-credentials"|'use-credentials'|use-credentials)(?=\s|>)/i.test(
+				tag,
+			)
+		) {
+			throw new Error(
+				'[octane] Early module hydration cannot preserve integrity, referrerpolicy, or credentialed script attributes.',
+			);
+		}
+		if (!/\ssrc\s*=/i.test(tag)) {
+			throw new Error('[octane] Early module hydration requires an external bootstrap entry.');
+		}
+		// WebKit can defer even async module scripts until an open HTML stream
+		// ends. A classic, nonce-bearing import kick runs after this complete
+		// shell instead. Keep the URL in an HTML attribute so the browser handles
+		// entities and relative URLs exactly as it did for the original src.
+		tag = tag
+			.replace(/\stype\s*=\s*(?:"module"|'module'|module)(?=\s|>)/i, '')
+			.replace(/\snomodule(?=\s|>)/i, '')
+			.replace(/\ssrc\s*=/i, ' data-octane-hydrate-src=');
+		return {
+			html: html.replace(entry, ''),
+			afterShell:
+				tag +
+				'import(new URL(document.currentScript.getAttribute("data-octane-hydrate-src"),document.baseURI).href).catch(function(e){console.error("[octane] Failed to load client hydration.",e);});</script>',
+		};
+	}
+	// Classic bundler entries must execute now as well, not wait for EOF.
+	return { html: html.replace(entry, ''), afterShell: tag + entry.slice(end + 1) };
+}
+
 /**
  * Add the request nonce to the production hydrate script the integration built. The
  * data attribute is inserted before build so this remains robust after the