@octanejs/app-core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# `@octanejs/app-core`
+
+Bundler-neutral app primitives shared by Octane's Vite and Rsbuild integrations. Most applications should install the integration for their build tool and import `defineConfig`, routes, and middleware from that package; integration and adapter authors can depend on app-core directly.
+
+## Public surfaces
+
+- `@octanejs/app-core/config` validates and resolves declarative `octane.config.ts` values.
+- `@octanejs/app-core/config-loader` loads TypeScript config files with either an injected development module runner or a neutral esbuild evaluator. `loadOctaneConfigWithMetadata` reports existing and missing dependencies for watch and cache invalidation.
+- `@octanejs/app-core/routes` and `/middleware` provide the router and Fetch API request pipeline.
+- `@octanejs/app-core/html`, `/production`, and `/node` provide streaming HTML composition, the production Fetch handler, and the optional Node HTTP bridge.
+- `@octanejs/app-core/codegen` generates client hydration entries, template-free server manifests, and production server entries. Runtime module IDs, integration module IDs, generated-file directories, and application import specifiers are explicit inputs so generators remain usable across bundlers and renderer targets.
+
+Development integrations should inject their native module runner into `loadOctaneConfigWithMetadata`. The neutral evaluator is intended for configuration/build discovery: it bundles static JS, TS, and server-compiled TSRX helpers, while preserving dynamic application imports as lazy watched references so config loading never traverses renderer-only asset graphs.
+
+```js
+import {
+  create_client_entry_source,
+  generateServerManifestEntry,
+} from '@octanejs/app-core/codegen';
+
+const clientEntry = create_client_entry_source({
+  staticEntries: [{ id: '/src/Page.tsrx', specifier: '/absolute/app/src/Page.tsrx' }],
+});
+
+const serverEntry = generateServerManifestEntry({
+  routes,
+  octaneConfigPath: '/absolute/app/octane.config.ts',
+  moduleImports: {
+    '/src/Page.tsrx': '/absolute/app/src/Page.tsrx',
+  },
+});
+```
+
+Stable application IDs stay in route manifests and hydration data; only generated `import` specifiers are mapped to a bundler-resolvable path.

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@octanejs/app-core",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "Bundler-neutral app runtime, configuration, routing, and code generation for Octane integrations",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/app-core"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "module": "src/index.js",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./config": {
+      "types": "./types/config.d.ts",
+      "import": "./src/config.js",
+      "default": "./src/config.js"
+    },
+    "./config-loader": {
+      "types": "./types/config-loader.d.ts",
+      "import": "./src/config-loader.js",
+      "default": "./src/config-loader.js"
+    },
+    "./routes": {
+      "types": "./types/routes.d.ts",
+      "import": "./src/routes.js",
+      "default": "./src/routes.js"
+    },
+    "./middleware": {
+      "types": "./types/middleware.d.ts",
+      "import": "./src/middleware.js",
+      "default": "./src/middleware.js"
+    },
+    "./html": {
+      "types": "./types/html.d.ts",
+      "import": "./src/html.js",
+      "default": "./src/html.js"
+    },
+    "./codegen": {
+      "types": "./types/codegen.d.ts",
+      "import": "./src/codegen.js",
+      "default": "./src/codegen.js"
+    },
+    "./production": {
+      "types": "./types/production.d.ts",
+      "import": "./src/server/production.js",
+      "default": "./src/server/production.js"
+    },
+    "./node": {
+      "types": "./types/node.d.ts",
+      "import": "./src/server/node-http.js",
+      "default": "./src/server/node-http.js"
+    }
+  },
+  "dependencies": {
+    "@ripple-ts/adapter": "^0.3.86",
+    "esbuild": "^0.28.1"
+  },
+  "peerDependencies": {
+    "octane": "0.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "octane": "0.1.5"
+  }
+}

package/src/codegen.js

@@ -0,0 +1,297 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+
+export { generateServerEntry, generateServerManifestEntry } from './server/server-entry.js';
+
+export const RESOLVED_ADAPTER_BROWSER_STUB_ID = '\0octane:adapter-browser-stub';
+// Server-only deploy/adapter packages: client-side imports of these specifiers
+// resolve to the browser stub below instead of the real module (whose graph
+// pulls node builtins). Every published adapter package MUST be listed here,
+// and its public exports added to the stub.
+export const SERVER_ONLY_ADAPTER_IDS = new Set([
+	'@ripple-ts/adapter-node',
+	'@ripple-ts/adapter-bun',
+	'@ripple-ts/adapter-vercel',
+	'@octanejs/adapter-vercel',
+]);
+
+/** @type {Map<string, string>} */
+const generated_file_cache = new Map();
+
+/**
+ * The browser stand-in shared by every SERVER_ONLY_ADAPTER_IDS package — it
+ * must export the UNION of their public names, each failing loudly on use
+ * (never at import, so merely reaching the module keeps the app alive).
+ * @returns {string}
+ */
+export function create_adapter_browser_stub_source() {
+	return `export const runtime = undefined;
+export function serve() {
+  throw new Error('[octane] Server adapters cannot run in the browser.');
+}
+export function nodeRequestToWebRequest() {
+  throw new Error('[octane] Node request helpers cannot run in the browser.');
+}
+export function webResponseToNodeResponse() {
+  throw new Error('[octane] Node response helpers cannot run in the browser.');
+}
+export function vercel() {
+  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.');
+}
+`;
+}
+
+/**
+ * Resolve the directory used for generated project entries. Integrations may
+ * supply an explicit `generatedDir`; otherwise their cache directory is used.
+ * The shape intentionally accepts Vite/Rsbuild resolved configs without
+ * importing either package's types.
+ *
+ * @param {{ root: string, cacheDir?: string, generatedDir?: string }} options
+ * @returns {string}
+ */
+export function get_project_generated_dir(options) {
+	if (options.generatedDir) return path.resolve(options.root, options.generatedDir);
+	const cacheDir = options.cacheDir ?? path.join(options.root, 'node_modules/.cache/octane');
+	return path.join(cacheDir, 'project');
+}
+
+/**
+ * @param {{ root: string, cacheDir?: string, generatedDir?: string }} options
+ * @param {string} name
+ * @param {string} source
+ * @returns {string}
+ */
+export function write_project_generated_file(options, name, source) {
+	const dir = get_project_generated_dir(options);
+	const file = path.join(dir, name);
+
+	if (generated_file_cache.get(file) === source && fs.existsSync(file)) {
+		return file;
+	}
+
+	fs.mkdirSync(dir, { recursive: true });
+	if (!fs.existsSync(file) || fs.readFileSync(file, 'utf-8') !== source) {
+		fs.writeFileSync(file, source);
+	}
+	generated_file_cache.set(file, source);
+	return file;
+}
+
+/**
+ * Generate the client hydration entry (served at virtual:octane-hydrate).
+ *
+ * CONFIG-FREE: it does NOT import octane.config.ts. Importing the config into
+ * the browser would drag the plugin (and the server adapter) — with their
+ * `node:fs` imports — into the client graph and throw at module-eval. Instead
+ * the server serializes everything needed into #__octane_data ({ entry,
+ * exportName, layout, params, url, preHydrate }), and this entry
+ * dynamic-imports the page/layout from there.
+ *
+ * `staticEntries` (production builds) lists every module path the server can
+ * name in #__octane_data — page entries, layouts, and the preHydrate hook.
+ * Each becomes a STATIC `() => import('/src/…')` in a lookup map, so Rollup
+ * sees, chunks, and hashes them; the runtime falls back to the hidden dynamic
+ * import only for paths outside the map (the dev case, where the map is empty
+ * and the integration serves any module by URL).
+ *
+ * octane specifics:
+ *   - `import { hydrateRoot } from 'octane'` (NO `mount`).
+ *   - `hydrateRoot(container, body, props)` signature (container FIRST, React-18
+ *     shape) — no `{ target, props }` wrapper.
+ *   - The layout `children` is a props-first ComponentBody whose closure calls
+ *     `Page({ params, url }, scope, extra)`, NOT a 0-arg thunk: octane's
+ *     `childSlot` invokes a bare function child with `{}` props, so page data
+ *     rides the closure — mirroring the server `createLayoutWrapper`.
+ *   - hydrateRoot() itself locates/consumes the <script data-octane-suspense>
+ *     seed inside #root, so the entry does nothing special for suspense.
+ *   - `preHydrate` (config `router.preHydrate`, a project-root module ID) is
+ *     imported and its default export awaited BEFORE hydrateRoot — the hook an
+ *     app-level client router uses to commit its match tree so the first
+ *     hydration pass adopts the same resolved tree the server rendered.
+ *
+ * `getComponentExport` mirrors routes.js `get_component_export` (route named
+ * export > default > first PascalCase) so server and client pick the SAME
+ * component.
+ *
+ * @param {{
+ *   configPath?: string,
+ *   staticEntries?: Array<string | { id: string, specifier: string }>,
+ *   resolveImport?: (id: string) => string,
+ *   runtimeModuleId?: string,
+ *   generatedBy?: string,
+ * }} [options]
+ * @returns {string}
+ */
+export function create_client_entry_source(options = {}) {
+	const staticEntries = new Map();
+	for (const entry of options.staticEntries ?? []) {
+		const id = typeof entry === 'string' ? entry : entry.id;
+		const specifier =
+			typeof entry === 'string' ? (options.resolveImport?.(id) ?? id) : entry.specifier;
+		staticEntries.set(id, specifier);
+	}
+	const runtimeModuleId = options.runtimeModuleId ?? 'octane';
+	const generatedBy = options.generatedBy ?? '@octanejs/app-core';
+	const static_map_lines = [...staticEntries]
+		.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, Suspense, ErrorBoundary, createElement } from ${JSON.stringify(runtimeModuleId)};
+
+// 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}
+};
+
+// Keep the fallback hidden from static import analysis. Some integrations
+// rewrite variable dynamic imports into queried URLs, which can evaluate as a
+// SECOND browser module instance and stop pages/preHydrate hooks sharing
+// singletons with statically imported copies of the same files.
+const dynamicImport = new Function('specifier', 'return import(specifier)');
+
+function importModule(path) {
+  const loader = routeModules[path];
+  return loader ? loader() : dynamicImport(path);
+}
+
+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.
+  if (exportName) return typeof module[exportName] === 'function' ? module[exportName] : undefined;
+  if (typeof module.default === 'function') return module.default;
+  return Object.entries(module).find(([key, value]) => typeof value === 'function' && /^[A-Z]/.test(key))?.[1];
+}
+
+function withRootBoundary(content, boundary) {
+  let body = content;
+  if (boundary.pending) {
+    const child = body;
+    const Pending = boundary.pending;
+    body = (props, scope) => Suspense({
+      fallback: createElement(Pending, {}),
+      children: (_props, childScope) => child(props, childScope),
+    }, scope);
+  }
+  if (boundary.catch) {
+    const child = body;
+    const Catch = boundary.catch;
+    body = (props, scope) => ErrorBoundary({
+      fallback: (error, reset) => createElement(Catch, { error, reset }),
+      children: (_props, childScope) => child(props, childScope),
+    }, scope);
+  }
+  return body;
+}
+
+(async () => {
+  try {
+    const el = document.getElementById('__octane_data');
+    const target = document.getElementById('root');
+    if (!el || !target) {
+      console.error('[octane] Unable to hydrate: missing #__octane_data or #root.');
+      return;
+    }
+    const data = JSON.parse(el.textContent || '{}'); // { entry, exportName, layout, params, url, preHydrate }
+    if (!data.entry) {
+      console.error('[octane] Unable to hydrate: no route entry in #__octane_data.');
+      return;
+    }
+
+    const pageMod = await importModule(data.entry);
+    const Component = getComponentExport(pageMod, data.exportName ?? undefined);
+    if (!Component) {
+      console.error('[octane] Unable to hydrate: no component export for', data.entry);
+      return;
+    }
+
+    const params = data.params;
+    const url = data.url;
+
+    // Run the app's pre-hydrate hook (config \`router.preHydrate\`) before the
+    // first hydration render — e.g. a client router committing its match tree
+    // so hydration adopts the same resolved tree the server rendered.
+    if (data.preHydrate) {
+      const preMod = await importModule(data.preHydrate);
+      const hook = preMod.default;
+      if (typeof hook === 'function') await hook({ url, params });
+    }
+
+    // Build the same props-closing root wrapper as the server.
+    let Content;
+    if (data.layout) {
+      const layoutMod = await importModule(data.layout);
+      const Layout = getComponentExport(layoutMod);
+      if (Layout) {
+        // children is a ComponentBody closing over the page props; octane's
+        // childSlot invokes a function child PROPS-FIRST as \`({}, block, extra)\`,
+        // so we ignore the empty props and render the page with its real
+        // \`{ params, url }\`, threading the scope + extra — mirroring the server
+        // createLayoutWrapper so the markers line up.
+        const children = (_props, scope, extra) => Component({ params, url }, scope, extra);
+        Content = (_props, scope, extra) => Layout({ params, url, children }, scope, extra);
+      }
+    }
+    if (!Content) {
+      Content = (_props, scope, extra) => Component({ params, url }, scope, extra);
+    }
+
+    const rootBoundary = { pending: null, catch: null };
+    for (const kind of ['pending', 'catch']) {
+      const entry = data.rootBoundary?.[kind];
+      if (!entry) continue;
+      const module = await importModule(entry.path);
+      const Boundary = getComponentExport(module, entry.exportName ?? undefined);
+      if (!Boundary) {
+        console.error('[octane] Unable to hydrate: no rootBoundary component for', entry.path);
+        return;
+      }
+      rootBoundary[kind] = Boundary;
+    }
+
+    hydrateRoot(target, withRootBoundary(Content, rootBoundary));
+  } catch (error) {
+    console.error('[octane] Failed to bootstrap client hydration.', error);
+  }
+})();
+`;
+}
+
+/**
+ * @param {string} filename
+ * @param {string} root
+ * @returns {string}
+ */
+export function normalize_module_reference(filename, root) {
+	const normalizedRoot = path.resolve(root);
+	const normalizedFile = path.resolve(filename);
+	const relative = path.relative(normalizedRoot, normalizedFile);
+	const withinRoot =
+		relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+	return withinRoot
+		? `/${relative.split(path.sep).join('/')}`
+		: normalizedFile.split(path.sep).join('/');
+}
+
+/**
+ * Compatibility alias for the Vite integration. Module references themselves
+ * are bundler-neutral; a project-root absolute `/src/...` ID is understood by
+ * both Vite and Rsbuild/Rspack aliases.
+ *
+ * @param {string} filename
+ * @param {string} root
+ * @returns {string}
+ */
+export function to_vite_root_import(filename, root) {
+	return normalize_module_reference(filename, root);
+}