@octanejs/app-core 0.0.7 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/app-core",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -79,10 +79,10 @@
     "esbuild": "^0.28.1"
   },
   "peerDependencies": {
-    "octane": "0.1.11"
+    "octane": "0.1.12"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
-    "octane": "0.1.11"
+    "octane": "0.1.12"
   }
 }

package/src/codegen.js

@@ -14,6 +14,7 @@ export const SERVER_ONLY_ADAPTER_IDS = new Set([
 	'@ripple-ts/adapter-bun',
 	'@ripple-ts/adapter-vercel',
 	'@octanejs/adapter-vercel',
+	'@octanejs/adapter-cloudflare',
 ]);
 
 /** @type {Map<string, string>} */
@@ -39,6 +40,9 @@ export function webResponseToNodeResponse() {
 export function vercel() {
   throw new Error('[octane] Deploy adapters cannot run in the browser.');
 }
+export function cloudflare() {
+  throw new Error('[octane] Deploy adapters cannot run in the browser.');
+}
 export function adapt() {
   throw new Error('[octane] Deploy adapters cannot run in the browser.');
 }

package/src/resolve-config.js

@@ -123,6 +123,22 @@ export function resolveOctaneConfig(raw, options = {}) {
 		if (raw.adapter.serve !== undefined && typeof raw.adapter.serve !== 'function') {
 			throw new Error('[octane] adapter.serve must be a function.');
 		}
+		if (
+			raw.adapter.serverTarget !== undefined &&
+			raw.adapter.serverTarget !== 'node' &&
+			raw.adapter.serverTarget !== 'webworker'
+		) {
+			throw new Error("[octane] adapter.serverTarget must be 'node' or 'webworker'.");
+		}
+		if (
+			raw.adapter.serverTarget === 'webworker' &&
+			(typeof raw.adapter.runtime?.hash !== 'function' ||
+				typeof raw.adapter.runtime?.createAsyncContext !== 'function')
+		) {
+			throw new Error(
+				'[octane] A webworker adapter must provide runtime.hash and runtime.createAsyncContext functions.',
+			);
+		}
 	}
 
 	if (

package/src/server/middleware.js

@@ -59,15 +59,20 @@ export function compose(middlewares) {
  * Create a context object for the request
  * @param {Request} request
  * @param {Record<string, string>} params
+ * @param {unknown} [platform]
  * @returns {Context}
  */
-export function createContext(request, params) {
-	return {
+export function createContext(request, params, platform) {
+	const context = /** @type {Context} */ ({
 		request,
 		params,
 		url: new URL(request.url),
 		state: new Map(),
-	};
+	});
+	// Preserve the existing context shape for Node and other integrations that
+	// do not supply request-scoped platform bindings.
+	if (platform !== undefined) context.platform = platform;
+	return context;
 }
 
 /**

package/src/server/production.js

@@ -68,8 +68,8 @@ const FETCH_COORDINATOR_KEY = Symbol.for('octane.app-core.fetch-coordinator');
 
 /**
  * @typedef {Object} FetchCoordinator
- * @property {import('@ripple-ts/adapter/rpc').AsyncContext} asyncContext
- * @property {((request: Request) => Promise<Response>) | null} handler
+ * @property {import('@ripple-ts/adapter/rpc').AsyncContext<{ origin?: string, platform?: unknown }>} asyncContext
+ * @property {((request: Request, platform?: unknown) => Promise<Response>) | null} handler
  */
 
 /**
@@ -94,7 +94,7 @@ function getFetchCoordinator(runtime) {
 		if (!shared.handler) {
 			return Promise.resolve(new Response('Octane handler is not ready', { status: 503 }));
 		}
-		return shared.handler(request);
+		return shared.handler(request, shared.asyncContext.getStore()?.platform);
 	});
 	return coordinator;
 }
@@ -112,13 +112,15 @@ function getFetchCoordinator(runtime) {
  * Create the production request handler from a manifest.
  *
  * The returned function is a standard Web `fetch`-style handler:
- * `(request: Request) => Promise<Response>` — the generated server entry boots
- * it behind the adapter's `serve()` (or the built-in Node server), and
- * serverless wrappers import it directly.
+ * `(request: Request, platform?: unknown) => Promise<Response>` — the generated
+ * server entry boots it behind the adapter's `serve()` (or the built-in Node
+ * server), and serverless wrappers import it directly. Integrations can expose
+ * request-scoped platform bindings to middleware and routes via the optional
+ * second argument.
  *
  * @param {ServerManifest} manifest
  * @param {HandlerOptions} deps
- * @returns {(request: Request) => Promise<Response>}
+ * @returns {(request: Request, platform?: unknown) => Promise<Response>}
  */
 export function createHandler(manifest, deps) {
 	const { renderToReadableStream, prerender, htmlTemplate, executeServerFunction } = deps;
@@ -142,7 +144,10 @@ export function createHandler(manifest, deps) {
 	const fetchCoordinator = getFetchCoordinator(runtime);
 	const asyncContext = fetchCoordinator?.asyncContext;
 
-	const handler = async function handler(/** @type {Request} */ request) {
+	const handler = async function handler(
+		/** @type {Request} */ request,
+		/** @type {unknown} */ platform = undefined,
+	) {
 		const url = new URL(request.url);
 		const method = request.method;
 
@@ -153,6 +158,16 @@ export function createHandler(manifest, deps) {
 					headers: { 'Content-Type': 'application/json' },
 				});
 			}
+			/** @type {import('@ripple-ts/adapter/rpc').AsyncContext<{ origin?: string, platform?: unknown }>} */
+			const requestAsyncContext =
+				platform === undefined
+					? asyncContext
+					: {
+							run(store, fn) {
+								return asyncContext.run({ ...store, platform }, fn);
+							},
+							getStore: () => asyncContext.getStore(),
+						};
 			return handle_rpc_request(request, {
 				resolveFunction(/** @type {string} */ hash) {
 					const entry = rpcLookup.get(hash);
@@ -161,7 +176,7 @@ export function createHandler(manifest, deps) {
 					return typeof fn === 'function' ? fn : null;
 				},
 				executeServerFunction,
-				asyncContext,
+				asyncContext: requestAsyncContext,
 				trustProxy,
 			});
 		}
@@ -175,7 +190,7 @@ export function createHandler(manifest, deps) {
 			return new Response('Not Found', { status: 404 });
 		}
 
-		const context = createContext(request, match.params);
+		const context = createContext(request, match.params, platform);
 
 		try {
 			if (match.route.type === 'render') {

package/src/server/server-entry.js

@@ -3,20 +3,29 @@
  * Production server-entry generator.
  *
  * `generateServerEntry` emits the module an integration uses as its server
- * bundle input. The generated module statically
- * imports every RenderRoute entry/layout module (compiled in server mode by
- * the active bundler integration) plus
- * octane.config.ts itself, wires them into `createHandler`, and:
+ * bundle input. The generated module statically imports every RenderRoute
+ * entry/layout module (compiled in server mode by the active bundler
+ * integration) plus octane.config.ts itself. Its mode selects one of three
+ * deployment surfaces:
  *
- *   - exports `handler`  — the Web fetch handler `(Request) => Promise<Response>`
- *   - exports `nodeHandler` — a Node `(req, res)` wrapper for serverless
- *     platforms (e.g. a Vercel Node function does
- *     `export { nodeHandler as default } from '../dist/server/entry.js'`)
- *   - auto-boots when run directly (`node dist/server/entry.js`): the
- *     adapter's `serve()` when configured, else the built-in Node server
- *     (static dist/client assets + the handler).
+ *   - `handler` exports the Web fetch handler and a Node `(req, res)` wrapper
+ *     for serverless platforms, then auto-boots when run directly.
+ *   - `manifest` exports the template-free manifest and renderer dependencies
+ *     consumed by integrations that inject the current HTML themselves.
+ *   - `webworker` exports those manifest values plus a
+ *     `createWebWorkerHandler({ htmlTemplate, clientAssets? })` factory, without
+ *     template filesystem access, a Node HTTP bridge, or automatic boot.
  *
- * It is unused in dev, where the active integration loads modules directly.
+ * The Node handler's wrapper supports platforms such as Vercel, where a
+ * function can do:
+ *
+ *   - `export { nodeHandler as default } from '../dist/server/entry.js'`
+ *
+ * Its direct-execution path uses the adapter's `serve()` when configured,
+ * otherwise the built-in Node server (static dist/client assets + the handler).
+ *
+ * Dev integrations use the manifest shape while loading request modules
+ * directly; the deployment handler shapes are production-only.
  */
 
 /** @import { Route, RootBoundaryOptions } from '@octanejs/app-core' */
@@ -35,7 +44,7 @@ import { get_route_entry_export_name, get_route_entry_path } from '../routes.js'
  * @property {Record<string, string>} [moduleImports] - Stable module ID → bundler import specifier
  * @property {((id: string) => string)} [resolveImport] - Fallback module-specifier mapper
  * @property {string} [configImportPath] - Bundler import specifier for octane.config.ts
- * @property {'handler' | 'manifest'} [mode] - Emit a bootable handler or a template-free manifest module
+ * @property {'handler' | 'manifest' | 'webworker'} [mode] - Emit a bootable handler, template-free manifest, or Web Worker factory module
  * @property {string} [serverRuntimeModuleId] - Renderer server runtime module ID
  * @property {string} [staticRuntimeModuleId] - Renderer static runtime module ID
  * @property {string} [productionModuleId] - App-core production runtime module ID
@@ -160,24 +169,57 @@ export function generateServerEntry(options) {
 		})
 		.join('\n');
 
-	if (mode === 'manifest') {
-		const assetFileImports = clientAssetMapFile
+	if (mode === 'manifest' || mode === 'webworker') {
+		const isWebWorker = mode === 'webworker';
+		const readsAssetFile = !isWebWorker && Boolean(clientAssetMapFile);
+		const assetFileImports = readsAssetFile
 			? `import { readFileSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport { dirname, join } from 'node:path';\n`
 			: '';
-		const assetDirectory = clientAssetMapFile
+		const platformImports = isWebWorker
+			? ''
+			: `import { createHash } from 'node:crypto';\nimport { AsyncLocalStorage } from 'node:async_hooks';\n`;
+		const handlerImport = isWebWorker
+			? `import { createHandler } from ${JSON.stringify(productionModuleId)};\n`
+			: '';
+		const assetDirectory = readsAssetFile
 			? `const __dirname = dirname(fileURLToPath(import.meta.url));\n`
 			: '';
-		const clientAssets = clientAssetMapFile
+		const clientAssets = readsAssetFile
 			? `JSON.parse(readFileSync(join(__dirname, ${JSON.stringify(clientAssetMapFile)}), 'utf-8'))`
 			: JSON.stringify(clientAssetMap, null, '\t');
+		const runtime = isWebWorker
+			? `const runtime = octaneConfig.adapter?.runtime;
+if (!runtime) {
+	throw new Error(
+		"[octane] adapter.serverTarget 'webworker' requires adapter.runtime platform primitives.",
+	);
+}`
+			: `const runtime = octaneConfig.adapter?.runtime ?? {
+	hash: (str) => createHash('sha256').update(str).digest('hex').slice(0, 8),
+	createAsyncContext: () => {
+		const als = new AsyncLocalStorage();
+		return { run: (store, fn) => als.run(store, fn), getStore: () => als.getStore() };
+	},
+};`;
+		const workerFactory = isWebWorker
+			? `
+export function createWebWorkerHandler({ htmlTemplate, clientAssets = manifest.clientAssets }) {
+	return createHandler(
+		{ ...manifest, clientAssets },
+		{ ...rendererDeps, htmlTemplate },
+	);
+}
+`
+			: '';
+		const entryDescription = isWebWorker
+			? 'the Web Worker server entry'
+			: 'the template-free server manifest entry';
 
 		return `\
-// Auto-generated by ${generatedBy} — the template-free server manifest entry.
+// Auto-generated by ${generatedBy} — ${entryDescription}.
 // Do not edit; regenerated by the active app integration.
 
-${assetFileImports}import { createHash } from 'node:crypto';
-import { AsyncLocalStorage } from 'node:async_hooks';
-import {
+${assetFileImports}${platformImports}import {
 	renderToReadableStream,
 	executeServerFunction,
 	Suspense,
@@ -186,19 +228,13 @@ import {
 } from ${JSON.stringify(serverRuntimeModuleId)};
 import { prerender } from ${JSON.stringify(staticRuntimeModuleId)};
 import { resolveOctaneConfig } from ${JSON.stringify(configModuleId)};
-import _rawOctaneConfig from ${JSON.stringify(resolvedConfigImport)};
+${handlerImport}import _rawOctaneConfig from ${JSON.stringify(resolvedConfigImport)};
 
 ${import_lines.join('\n')}
 
 export const octaneConfig = resolveOctaneConfig(_rawOctaneConfig);
 
-const runtime = octaneConfig.adapter?.runtime ?? {
-	hash: (str) => createHash('sha256').update(str).digest('hex').slice(0, 8),
-	createAsyncContext: () => {
-		const als = new AsyncLocalStorage();
-		return { run: (store, fn) => als.run(store, fn), getStore: () => als.getStore() };
-	},
-};
+${runtime}
 
 const components = {
 ${component_entries}
@@ -258,6 +294,7 @@ export const rendererDeps = {
 	ErrorBoundary,
 	createElement,
 };
+${workerFactory}
 `;
 	}
 

package/types/codegen.d.ts

@@ -47,7 +47,8 @@ export interface ServerEntryOptions {
 	moduleImports?: Record<string, string>;
 	resolveImport?: (id: string) => string;
 	configImportPath?: string;
-	mode?: 'handler' | 'manifest';
+	/** Server module shape emitted for the active adapter target. @default 'handler' */
+	mode?: 'handler' | 'manifest' | 'webworker';
 	serverRuntimeModuleId?: string;
 	staticRuntimeModuleId?: string;
 	productionModuleId?: string;
@@ -56,7 +57,7 @@ export interface ServerEntryOptions {
 	generatedBy?: string;
 }
 
-/** Generate a production fetch-handler + optional Node auto-boot entry. */
+/** Generate a production server entry in the requested module shape. */
 export function generateServerEntry(options: ServerEntryOptions): string;
 /** Generate a template-free bundle exporting `manifest` and `rendererDeps`. */
 export function generateServerManifestEntry(options: ServerEntryOptions): string;

package/types/index.d.ts

@@ -108,6 +108,8 @@ export interface Context {
 	 * renderer inline scripts, hydration data, and the hydrate module script.
 	 */
 	state: Map<string, unknown>;
+	/** Request-scoped bindings supplied by the active platform integration. */
+	platform?: unknown;
 }
 
 export type NextFunction = () => Promise<Response>;
@@ -117,7 +119,11 @@ export type RouteHandler = (context: Context) => Response | Promise<Response>;
 export function compose(
 	middlewares: Middleware[],
 ): (context: Context, finalHandler: () => Promise<Response>) => Promise<Response>;
-export function createContext(request: Request, params: Record<string, string>): Context;
+export function createContext(
+	request: Request,
+	params: Record<string, string>,
+	platform?: unknown,
+): Context;
 export function runMiddlewareChain(
 	context: Context,
 	globalMiddlewares: Middleware[],
@@ -402,11 +408,14 @@ export interface AdaptContext {
  *   a deployment target (e.g. @octanejs/adapter-vercel emits `.vercel/output`).
  * - `serve(handler, opts)` — replaces the generated server entry's built-in
  *   Node boot when running `node dist/server/entry.js` / `octane-preview`.
+ * - `serverTarget` — selects the integration's Node or Web Worker server build.
  * - `runtime` — platform primitives (hashing, async context) replacing the
- *   entry's Node defaults; needed on non-Node runtimes.
+ *   entry's Node defaults; required for `serverTarget: 'webworker'`.
  */
 export interface OctaneAdapter {
 	name?: string;
+	/** Server bundle runtime selected by the active app integration. @default 'node' */
+	serverTarget?: 'node' | 'webworker';
 	adapt?: (ctx: AdaptContext) => void | Promise<void>;
 	serve?: AdapterServeFunction;
 	runtime?: RuntimePrimitives;

package/types/production.d.ts

@@ -83,7 +83,7 @@ export interface HandlerOptions {
 export function createHandler(
 	manifest: ServerManifest,
 	options: HandlerOptions,
-): (request: Request) => Promise<Response>;
+): (request: Request, platform?: unknown) => Promise<Response>;
 
 export function createPropsWrapper(Page: Component, pageProps: Record<string, unknown>): Component;
 export function createLayoutWrapper(