@hyperspan/framework 2.0.0-alpha.2 → 2.0.0-alpha.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.0-alpha.20",
   "description": "Hyperspan Web Framework",
   "type": "module",
   "main": "src/server.ts",
@@ -27,10 +27,18 @@
       "types": "./src/utils.ts",
       "default": "./src/utils.ts"
     },
+    "./routes": {
+      "types": "./src/register-routes.ts",
+      "default": "./src/register-routes.ts"
+    },
     "./layout": {
       "types": "./src/layout.ts",
       "default": "./src/layout.ts"
     },
+    "./dev-bindings": {
+      "types": "./src/dev-bindings.ts",
+      "default": "./src/dev-bindings.ts"
+    },
     "./client/css": {
       "types": "./src/client/css.ts",
       "default": "./src/client/css.ts"
@@ -47,6 +55,10 @@
       "types": "./src/actions.ts",
       "default": "./src/actions.ts"
     },
+    "./html": {
+      "types": "./src/html.ts",
+      "default": "./src/html.ts"
+    },
     "./ssr/install-server-dom-mock": {
       "types": "./src/ssr/install-server-dom-mock.ts",
       "default": "./src/ssr/install-server-dom-mock.ts"
@@ -93,10 +105,10 @@
     "@types/node": "^24.10.0",
     "prettier": "^3.5.2",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.10"
   },
   "dependencies": {
-    "@hyperspan/html": "^2.0.0-alpha.2",
+    "@hyperspan/html": "^2.0.0-alpha.20",
     "debug": "^4.4.3",
     "isbot": "^5.1.32",
     "zod": "^4.4.3"

package/src/actions.test.ts

@@ -1,7 +1,7 @@
 import { test, expect, describe } from 'vitest';
 import { createAction } from './actions';
 import { createRoute } from './server';
-import { html, render, placeholder, type HSHtml } from '@hyperspan/html';
+import { html, render, placeholder, type HSHtml } from './html';
 import { createContext } from './server';
 import * as z from 'zod';
 

package/src/actions.ts

@@ -1,4 +1,4 @@
-import { html } from '@hyperspan/html';
+import { html } from './html';
 import { createRoute, HTTPResponseException, returnHTMLResponse } from './server';
 import * as z from 'zod';
 import type { Hyperspan as HS } from './types';

package/src/adapter.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from 'bun:test';
+import type { Adapter } from './types';
+import { createConfig } from './server';
+
+const cloudflare: Adapter = {
+  name: 'cloudflare',
+  renderServerEntry: (template) => template(),
+};
+
+describe('createConfig deployAdapter', () => {
+  test('defaults to Node when omitted or undefined', () => {
+    expect(createConfig({}).deployAdapter.name).toBe('node');
+    expect(createConfig({ deployAdapter: undefined }).deployAdapter.name).toBe('node');
+  });
+
+  test('keeps an explicit adapter', () => {
+    expect(createConfig({ deployAdapter: cloudflare }).deployAdapter).toBe(cloudflare);
+  });
+});

package/src/client/js.test.ts

@@ -1,14 +1,19 @@
 import { describe, expect, test, beforeEach } from 'vitest';
-import { mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { render } from '@hyperspan/html';
+import { pathToFileURL } from 'node:url';
+import { render } from '../html';
+import { assetHash } from '../utils';
+import { setAssetManifest } from './manifest';
 import {
   buildClientJS,
   discoverClientExports,
   extractExports,
   getClientJSEntries,
+  registerPathAliases,
   resetClientJSEntriesForTests,
+  streamingClient,
 } from './js';
 
 describe('buildClientJS', () => {
@@ -16,6 +21,7 @@ describe('buildClientJS', () => {
 
   beforeEach(() => {
     resetClientJSEntriesForTests();
+    setAssetManifest({ imports: {}, css: {}, clients: {} });
     const dir = mkdtempSync(join(tmpdir(), 'hs-client-'));
     clientFile = join(dir, 'picker.ts');
     writeFileSync(
@@ -27,7 +33,7 @@ describe('buildClientJS', () => {
     );
   });
 
-  test('registers entry and returns stable esmName from path hash', async () => {
+  test('registers entry with a stable path identity', async () => {
     const result = await buildClientJS(clientFile);
 
     expect(result.esmName).toMatch(/^client-[0-9a-f]{16}$/);
@@ -36,11 +42,37 @@ describe('buildClientJS', () => {
     expect(getClientJSEntries()[0].absPath).toBe(clientFile);
   });
 
+  test('changing file contents does not change the import-map key', async () => {
+    const first = await buildClientJS(clientFile);
+    writeFileSync(clientFile, `export function mountPicker() { return 2; }\n`);
+    resetClientJSEntriesForTests();
+    const second = await buildClientJS(clientFile);
+    expect(second.esmName).toBe(first.esmName);
+  });
+
+  test('publicPath uses the Vite-hashed URL from the import map', async () => {
+    const result = await buildClientJS(clientFile);
+    const hashed = `/_hs/js/${result.esmName}-a1b2c3d4.js`;
+    setAssetManifest({
+      imports: { [result.esmName]: hashed },
+      css: {},
+      clients: {},
+    });
+    expect(result.publicPath).toBe(hashed);
+  });
+
+  test('absolute path and file URL of the same file share one hash', async () => {
+    const viaAbs = await buildClientJS(clientFile);
+    resetClientJSEntriesForTests();
+    const viaUrl = await buildClientJS(pathToFileURL(clientFile).href);
+    expect(viaUrl.esmName).toBe(viaAbs.esmName);
+  });
+
   test('renderScriptTag with no loader uses import map key', async () => {
     const result = await buildClientJS(clientFile);
     const tag = render(result.renderScriptTag());
 
-    expect(tag).toContain(`import "${result.esmName}"`);
+    expect(tag).toContain(`import '${result.esmName}'`);
     expect(tag).toContain(`data-source-id="${result.assetHash}"`);
   });
 
@@ -52,7 +84,7 @@ describe('buildClientJS', () => {
       })
     );
 
-    expect(tag).toContain(`import {mountPicker} from "${result.esmName}"`);
+    expect(tag).toContain(`import {mountPicker} from '${result.esmName}'`);
     expect(tag).toContain('mountPicker()');
   });
 
@@ -62,6 +94,118 @@ describe('buildClientJS', () => {
 
     expect(tag).toContain('({ mountPicker }) => mountPicker()');
   });
+
+  test('package specifiers hash the same wherever the package is installed', async () => {
+    const spec = '@hyperspan/framework/client/_hs/hyperspan-streaming.client.ts';
+    const first = await buildClientJS(spec, { type: 'iife' });
+    resetClientJSEntriesForTests();
+    const second = await buildClientJS(spec, { type: 'iife' });
+    expect(first.esmName).toBe(second.esmName);
+    expect(first.esmName).toBe(streamingClient.esmName);
+    expect(existsSync(getClientJSEntries()[0].absPath)).toBe(true);
+  });
+
+  // workerd rejects `import.meta.resolve` after bundling, which crashed Worker startup.
+  test('builtins register without resolving a path at module load', () => {
+    const src = readFileSync(new URL('./js.ts', import.meta.url), 'utf8');
+    const registrations = src.slice(src.indexOf('export const streamingClient'));
+
+    expect(registrations).toContain(
+      "'@hyperspan/framework/client/_hs/hyperspan-streaming.client.ts'"
+    );
+    expect(registrations).toContain(
+      "'@hyperspan/framework/client/_hs/hyperspan-actions.client.ts'"
+    );
+    expect(registrations).not.toContain('import.meta.resolve');
+  });
+
+  // Valid on Node/Bun, which can resolve paths at runtime. Flagged as a path identity
+  // so a Worker build can reject it instead of serving a 404 for a script in dist/.
+  test('import.meta.resolve at the call site registers a real file, flagged as a path identity', async () => {
+    const result = await buildClientJS(import.meta.resolve('./_hs/hyperspan-streaming.client.ts'), {
+      type: 'iife',
+    });
+
+    expect(result.publicPath).toMatch(/^\/_hs\/js\/client-[0-9a-f]{16}\.js$/);
+    expect(getClientJSEntries()[0].type).toBe('iife');
+    expect(existsSync(getClientJSEntries()[0].absPath)).toBe(true);
+    expect(getClientJSEntries()[0].absPath).toMatch(/hyperspan-streaming\.client\.ts$/);
+    expect(getClientJSEntries()[0].identityFromPath).toBe(true);
+  });
+
+  test('specifier identities are not flagged as path identities', async () => {
+    await buildClientJS('@hyperspan/framework/client/_hs/hyperspan-actions.client.ts');
+    expect(getClientJSEntries()[0].identityFromPath).toBe(false);
+  });
+
+  test('relative paths are rejected in favor of an alias', async () => {
+    await expect(buildClientJS('../client/picker.ts')).rejects.toThrow(/tsconfig alias/);
+    await expect(buildClientJS('./picker.ts')).rejects.toThrow(/tsconfig alias/);
+  });
+
+  test('type iife renders a classic script tag', async () => {
+    const result = await buildClientJS(clientFile, { type: 'iife' });
+    const tag = render(result.renderScriptTag());
+
+    expect(tag).toContain(`<script src="${result.publicPath}"`);
+    expect(tag).not.toContain('type="module"');
+    expect(getClientJSEntries()[0].type).toBe('iife');
+  });
+
+  test('logical app-relative paths hash consistently and resolve on disk when present', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'hs-client-logical-'));
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(join(dir, 'app/client'), { recursive: true });
+    const logicalPath = join(dir, 'app/client/stats.ts');
+    writeFileSync(logicalPath, `export function mountStats() {}\n`);
+
+    const cwd = process.cwd();
+    process.chdir(dir);
+    try {
+      const first = await buildClientJS('app/client/stats.ts');
+      resetClientJSEntriesForTests();
+      const second = await buildClientJS('app/client/stats.ts');
+      expect(first.esmName).toBe(second.esmName);
+      expect(getClientJSEntries()[0].absPath.replace(/^\/private/, '')).toBe(
+        logicalPath.replace(/^\/private/, '')
+      );
+    } finally {
+      process.chdir(cwd);
+    }
+  });
+
+  test('tsconfig aliases resolve inside buildClientJS without import.meta.resolve', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'hs-client-alias-'));
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(join(dir, 'app/client'), { recursive: true });
+    const absPath = join(dir, 'app/client/stats.ts');
+    writeFileSync(absPath, `export function mountStats() {}\n`);
+
+    registerPathAliases({ '~/': `${dir}/`, '~': dir });
+
+    const result = await buildClientJS('~/app/client/stats.ts');
+    expect(getClientJSEntries()[0].absPath.replace(/^\/private/, '')).toBe(
+      absPath.replace(/^\/private/, '')
+    );
+    expect(getClientJSEntries()[0].modulePath).toBe('~/app/client/stats.ts');
+
+    resetClientJSEntriesForTests();
+    registerPathAliases({ '~/': `${dir}/`, '~': dir });
+    const second = await buildClientJS('~/app/client/stats.ts');
+    expect(second.esmName).toBe(result.esmName);
+  });
+
+  // A Worker has no filesystem: registration must not read the source to get a URL.
+  test('missing source files still resolve to the built URL', async () => {
+    const spec = 'app/client/gone.ts';
+    const esmName = `client-${assetHash(spec)}`;
+    const hashed = `/_hs/js/${esmName}-a1b2c3d4.js`;
+    setAssetManifest({ imports: { [esmName]: hashed }, css: {}, clients: {} });
+
+    const result = await buildClientJS(spec);
+    expect(result.esmName).toBe(esmName);
+    expect(result.publicPath).toBe(hashed);
+  });
 });
 
 describe('extractExports', () => {

package/src/client/js.ts

@@ -1,6 +1,7 @@
 import { readFileSync, existsSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { html } from '@hyperspan/html';
+import { html } from '../html';
 import { assetHash as assetHashFn } from '../utils';
 import { getImportMap, registerImport, resolveImport } from './manifest';
 import type { Hyperspan as HS } from '../types';
@@ -10,16 +11,87 @@ export { registerImport, resolveImport, getImportMap } from './manifest';
 export const JS_PUBLIC_PATH = '/_hs/js';
 export const JS_ISLAND_PUBLIC_PATH = '/_hs/js/islands';
 
+export type ClientJSType = 'module' | 'iife';
+
+export type BuildClientJSOptions = {
+  /** `iife` emits a classic <script> (runs during HTML streaming). Default `module`. */
+  type?: ClientJSType;
+};
+
 export type ClientJSEntry = {
+  /** Original path/specifier passed to `buildClientJS`. */
+  modulePath: string;
+  /** Resolved file path. Lazy — only a build/dev tool with a filesystem reads this. */
   absPath: string;
+  /** Runtime-stable identity of the module. Same value on Vite, Node, and Workers. */
+  identityKey: string;
+  /**
+   * Identity came from a filesystem path rather than a logical specifier. Such an
+   * identity only matches at runtime on a runtime that can resolve paths, so it is
+   * not portable to a Worker.
+   */
+  identityFromPath: boolean;
+  /** Identity hash of `identityKey` (not of file contents). */
   assetHash: string;
   esmName: string;
   publicPath: string;
   exports: string;
   fnArgs: string;
+  type: ClientJSType;
+};
+
+export type ClientJSPathIdentity = {
+  modulePath: string;
+  identityKey: string;
 };
 
 const CLIENT_JS_REGISTRY = Symbol.for('@hyperspan/client-js-entries');
+const CLIENT_JS_PATH_IDENTITIES = Symbol.for('@hyperspan/client-js-path-identities');
+const PATH_ALIASES = Symbol.for('@hyperspan/path-aliases');
+
+function getPathAliases(): Record<string, string> {
+  const globalAliases = globalThis as {
+    [PATH_ALIASES]?: Record<string, string>;
+  };
+  if (!globalAliases[PATH_ALIASES]) {
+    globalAliases[PATH_ALIASES] = {};
+  }
+  return globalAliases[PATH_ALIASES];
+}
+
+/** Register tsconfig path aliases (`~/` → project root). Called by the Vite plugin. */
+export function registerPathAliases(aliases: Record<string, string>): void {
+  Object.assign(getPathAliases(), aliases);
+}
+
+function resolveWithAliases(specifier: string): string | undefined {
+  const aliases = getPathAliases();
+  const keys = Object.keys(aliases).sort((a, b) => b.length - a.length);
+  for (const key of keys) {
+    if (specifier === key || specifier.startsWith(key)) {
+      const rest = specifier.slice(key.length).replace(/^\//, '');
+      return join(aliases[key], rest);
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Client scripts registered from a path rather than a logical specifier, kept outside
+ * the registry. A path identity can coincide with the equivalent project-relative
+ * specifier (`file:///proj/app/client/x.ts` and `app/client/x.ts` share one identity),
+ * so the registry entry may be replaced by whichever form registered last. Deploy
+ * checks need the record regardless of that order.
+ */
+export function getPathIdentityClientJS(): ClientJSPathIdentity[] {
+  const globalPathIdentities = globalThis as {
+    [CLIENT_JS_PATH_IDENTITIES]?: ClientJSPathIdentity[];
+  };
+  if (!globalPathIdentities[CLIENT_JS_PATH_IDENTITIES]) {
+    globalPathIdentities[CLIENT_JS_PATH_IDENTITIES] = [];
+  }
+  return globalPathIdentities[CLIENT_JS_PATH_IDENTITIES];
+}
 
 function getClientJSRegistry(): Map<string, ClientJSEntry> {
   const globalRegistry = globalThis as {
@@ -60,13 +132,92 @@ export const JS_IMPORT_MAP = {
 };
 
 /**
- * Resolve import.meta.resolve() / file URL / absolute path to a filesystem path.
+ * File paths must not become a cwd-relative pnpm path — that changes between
+ * install layouts and Workers. Prefer the path after the last `node_modules/`
+ * so published packages stay stable.
+ */
+export function stableClientSourceKey(absPath: string): string {
+  const normalized = absPath.replace(/\\/g, '/');
+  const marker = '/node_modules/';
+  const idx = normalized.lastIndexOf(marker);
+  if (idx !== -1) {
+    return normalized.slice(idx + marker.length);
+  }
+  if (typeof process !== 'undefined' && typeof process.cwd === 'function') {
+    const rel = relative(process.cwd(), absPath).replace(/\\/g, '/');
+    if (rel && !rel.startsWith('..') && !isAbsolute(rel)) {
+      return rel;
+    }
+  }
+  return normalized;
+}
+
+function toFilePath(modulePath: string): string {
+  return modulePath.startsWith('file://') ? fileURLToPath(modulePath) : modulePath;
+}
+
+function tryResolveToFile(specifier: string): string | undefined {
+  try {
+    if (typeof import.meta.resolve !== 'function') {
+      return undefined;
+    }
+    const resolved = import.meta.resolve(specifier);
+    if (typeof resolved === 'string' && (resolved.startsWith('file://') || isAbsolute(resolved))) {
+      return toFilePath(resolved);
+    }
+  } catch {
+    // Workers and unresolved package specifiers — Vite already emitted the asset.
+  }
+  return undefined;
+}
+
+function clientPublicPath(esmName: string): string {
+  return resolveImport(esmName) ?? `${JS_PUBLIC_PATH}/${esmName}.js`;
+}
+
+/**
+ * Identity of a client module, computed with string math only — no filesystem and
+ * no `import.meta.resolve`. Workers can therefore build the same identity (and so
+ * the same public URL) that Vite used at build time.
+ *
+ * A logical specifier (package export, tsconfig alias, project-root path) is its
+ * own identity. File URLs and absolute paths fall back to a path identity.
+ */
+function clientIdentityKey(specifier: string): string {
+  if (specifier.startsWith('file://') || isAbsolute(specifier)) {
+    return stableClientSourceKey(toFilePath(specifier));
+  }
+  return specifier;
+}
+
+/**
+ * Resolve an identity to a real file path. Only build/dev tooling calls this, so
+ * `import.meta.resolve` never runs during module load on a Worker.
  */
-export function resolveClientModulePath(modulePathResolved: string): string {
-  if (modulePathResolved.startsWith('file://')) {
-    return fileURLToPath(modulePathResolved);
+function resolveClientAbsPath(specifier: string): string {
+  if (specifier.startsWith('file://') || isAbsolute(specifier)) {
+    return toFilePath(specifier);
   }
-  return modulePathResolved;
+
+  const aliased = resolveWithAliases(specifier);
+  if (aliased) {
+    return aliased;
+  }
+
+  const cwd =
+    typeof process !== 'undefined' && typeof process.cwd === 'function' ? process.cwd() : '';
+  return tryResolveToFile(specifier) ?? (cwd ? join(cwd, specifier) : specifier);
+}
+
+function readClientSource(absPath: string): string | undefined {
+  try {
+    if (existsSync(absPath)) {
+      return readFileSync(absPath, 'utf-8');
+    }
+  } catch {
+    // Workers have no filesystem; Vite already bundled from this entry.
+  }
+  return undefined;
 }
 
 export function getClientJSEntries(): ClientJSEntry[] {
@@ -79,42 +230,91 @@ export function getClientJSEntryByEsmName(esmName: string): ClientJSEntry | unde
 
 export function resetClientJSEntriesForTests(): void {
   getClientJSRegistry().clear();
+  getPathIdentityClientJS().length = 0;
+  const aliases = getPathAliases();
+  for (const key of Object.keys(aliases)) {
+    delete aliases[key];
+  }
 }
 
-function registerClientJSEntry(entry: ClientJSEntry): void {
-  getClientJSRegistry().set(entry.esmName, entry);
-}
+function registerClientJS(
+  modulePathResolved: string,
+  options: BuildClientJSOptions = {}
+): HS.ClientJSBuildResult {
+  const type = options.type ?? 'module';
+  const specifier = modulePathResolved.replace(/\\/g, '/');
+  if (specifier.startsWith('.')) {
+    throw new Error(
+      `[Hyperspan] buildClientJS(${JSON.stringify(modulePathResolved)}) got a relative path, ` +
+        `which has no stable identity across dev, build, and deploy. Use a tsconfig alias ` +
+        `like '~/app/client/file.ts' — the build resolves it, and every runtime (including ` +
+        `Workers, which cannot resolve paths) matches it in the asset manifest.`
+    );
+  }
 
-/**
- * Build (or look up) a client JS module and return a helper for rendering script tags.
- *
- * Never evaluates the module on the server — only registers the path for Vite to bundle
- * and returns URLs / script-tag helpers for the browser.
- */
-export async function buildClientJS(modulePathResolved: string): Promise<HS.ClientJSBuildResult> {
-  const absPath = resolveClientModulePath(modulePathResolved);
-  const hash = assetHashFn(absPath);
+  const identityKey = clientIdentityKey(specifier);
+  const identityFromPath = identityKey !== specifier;
+  const hash = assetHashFn(identityKey);
   const esmName = `client-${hash}`;
-  const publicPath = resolveImport(esmName) ?? `${JS_PUBLIC_PATH}/${esmName}.js`;
 
-  let exports = '* as _module';
-  let fnArgs = '_module';
-  if (existsSync(absPath)) {
-    const source = readFileSync(absPath, 'utf-8');
-    const discovered = discoverClientExports(source);
-    exports = discovered.exports;
-    fnArgs = discovered.fnArgs;
+  if (identityFromPath) {
+    getPathIdentityClientJS().push({ modulePath: modulePathResolved, identityKey });
+  }
+
+  let absPath: string | undefined;
+  let discovered: { exports: string; fnArgs: string } | undefined;
+
+  // Both are lazy: a Worker renders script tags without a filesystem, and
+  // resolving there would need `import.meta.resolve`, which workerd may reject.
+  function currentAbsPath(): string {
+    return (absPath ??= resolveClientAbsPath(specifier));
+  }
+  function currentExports(): { exports: string; fnArgs: string } {
+    if (!discovered) {
+      const source = readClientSource(currentAbsPath());
+      discovered = source
+        ? discoverClientExports(source)
+        : { exports: '* as _module', fnArgs: '_module' };
+    }
+    return discovered;
   }
 
-  registerClientJSEntry({ absPath, assetHash: hash, esmName, publicPath, exports, fnArgs });
-  registerImport(esmName, publicPath);
+  const entry: ClientJSEntry = {
+    modulePath: modulePathResolved,
+    get absPath() {
+      return currentAbsPath();
+    },
+    identityKey,
+    identityFromPath,
+    assetHash: hash,
+    esmName,
+    get publicPath() {
+      return clientPublicPath(esmName);
+    },
+    get exports() {
+      return currentExports().exports;
+    },
+    get fnArgs() {
+      return currentExports().fnArgs;
+    },
+    type,
+  };
+  getClientJSRegistry().set(esmName, entry);
+  registerImport(esmName, entry.publicPath);
 
   return {
     assetHash: hash,
     esmName,
-    publicPath,
+    get publicPath() {
+      return clientPublicPath(esmName);
+    },
     renderScriptTag: (loadScript) => {
+      if (type === 'iife') {
+        return html`<script src="${clientPublicPath(esmName)}"></script>`;
+      }
+
       const t = typeof loadScript;
+      const { exports, fnArgs } = currentExports();
 
       if (t === 'string') {
         return html`
@@ -142,6 +342,32 @@ export async function buildClientJS(modulePathResolved: string): Promise<HS.Clie
   };
 }
 
+/**
+ * Register a client JS module for Vite to bundle.
+ * Prefer a package export, tsconfig alias, or project-root path
+ * (`@scope/pkg/file.ts`, `~/app/client/foo.ts`, `app/client/foo.ts`) — those need no
+ * filesystem lookup, so Vite, Node, and Workers all derive the same public URL.
+ * Vite/esbuild content-hash the emitted filename; `publicPath` reads that URL from
+ * the asset manifest. Relative `./` / `../` paths must be resolved at the call site
+ * with `import.meta.resolve('./file.ts')`.
+ */
+export async function buildClientJS(
+  modulePathResolved: string,
+  options: BuildClientJSOptions = {}
+): Promise<HS.ClientJSBuildResult> {
+  return registerClientJS(modulePathResolved, options);
+}
+
+// Registered through the same public API an app uses. Package-export specifiers keep
+// module load free of `import.meta.resolve`, which workerd rejects after bundling.
+export const streamingClient = registerClientJS(
+  '@hyperspan/framework/client/_hs/hyperspan-streaming.client.ts',
+  { type: 'iife' }
+);
+export const actionsClient = registerClientJS(
+  '@hyperspan/framework/client/_hs/hyperspan-actions.client.ts'
+);
+
 /**
  * Discover export names from source or bundled client JS.
  * Prefers bundled `export{...}` form, then common source export patterns.

package/src/client/manifest.ts

@@ -3,59 +3,64 @@ import type { Hyperspan as HS } from '../types';
 export type AssetManifest = {
   imports: Record<string, string>;
   css: Record<string, string[]>;
-  clients: {
-    streaming?: string;
-    actions?: string;
-    scripts?: string;
-  };
+  clients: Record<string, string>;
 };
 
-let _manifest: AssetManifest = {
-  imports: {},
-  css: {},
-  clients: {},
-};
+const MANIFEST_KEY = Symbol.for('@hyperspan/asset-manifest');
+
+function sharedManifest(): AssetManifest {
+  const globalStore = globalThis as typeof globalThis & {
+    [MANIFEST_KEY]?: AssetManifest;
+  };
+  if (!globalStore[MANIFEST_KEY]) {
+    globalStore[MANIFEST_KEY] = { imports: {}, css: {}, clients: {} };
+  }
+  return globalStore[MANIFEST_KEY];
+}
 
 /**
  * Set the build-time asset manifest (called by Vite plugin or build step).
  */
 export function setAssetManifest(manifest: AssetManifest): void {
-  _manifest = manifest;
+  const store = sharedManifest();
+  store.imports = { ...(manifest.imports ?? {}) };
+  store.css = { ...(manifest.css ?? {}) };
+  store.clients = { ...(manifest.clients ?? {}) };
 }
 
 /**
  * Get the current asset manifest.
  */
 export function getAssetManifest(): AssetManifest {
-  return _manifest;
+  return sharedManifest();
 }
 
 /**
  * Resolve a module import name to its public URL.
  */
 export function resolveImport(name: string): string | undefined {
-  return _manifest.imports[name];
+  return sharedManifest().imports[name];
 }
 
 /**
  * Get CSS files for a route path.
  */
 export function getRouteCss(path: string): string[] {
-  return _manifest.css[path] ?? [];
+  return sharedManifest().css[path] ?? [];
 }
 
 /**
  * Build import map object for layout script tags.
  */
 export function getImportMap(): Record<string, string> {
-  return { ..._manifest.imports };
+  return { ...sharedManifest().imports };
 }
 
 /**
  * Register a client module URL at runtime (dev fallback).
  */
 export function registerImport(name: string, publicPath: string): void {
-  _manifest.imports[name] = publicPath;
+  sharedManifest().imports[name] = publicPath;
 }
 
 export type ClientJSBuildResult = HS.ClientJSBuildResult;
@@ -67,7 +72,7 @@ export function getClientJSFromManifest(
   moduleId: string,
   _exportNames = 'default'
 ): ClientJSBuildResult {
-  const publicPath = _manifest.clients[moduleId as keyof AssetManifest['clients']];
+  const publicPath = sharedManifest().clients[moduleId];
   if (!publicPath) {
     throw new Error(
       `[Hyperspan] Client module "${moduleId}" not found in asset manifest. Run hyperspan build or start dev server.`

package/src/dev-bindings.ts

@@ -0,0 +1,14 @@
+/** Dev-only platform bindings (D1, KV, etc.) shared across Vite SSR modules. */
+let devBindings: unknown;
+
+export function setDevBindings(env: unknown): void {
+  devBindings = env;
+}
+
+export function getDevBindings(): unknown {
+  return devBindings;
+}
+
+export function clearDevBindingsForTests(): void {
+  devBindings = undefined;
+}

package/src/fetch-handler.test.ts

@@ -73,6 +73,29 @@ describe('createFetchHandler', () => {
     expect(await response.text()).toBe('abc');
   });
 
+  test('preserves Cookie on the request passed to the route', async () => {
+    const server = await createServer({
+      appDir: './app',
+      publicDir: './public',
+      plugins: [],
+    });
+
+    const route = createRoute({ path: '/session' }).get((c: HS.Context) =>
+      c.res.text(c.req.raw.headers.get('cookie') ?? '')
+    );
+    server._routes.push(route);
+
+    const headers = new Headers({ cookie: 'session=abc' });
+    const request = new Request('http://localhost/session', { headers });
+    // Node's Request constructor strips Cookie; re-attach like Vite's nodeToWebRequest.
+    Object.defineProperty(request, 'headers', { value: headers });
+
+    const fetch = createFetchHandler(server);
+    const response = await fetch(request);
+
+    expect(await response.text()).toBe('session=abc');
+  });
+
   test('redirects trailing slashes', async () => {
     const server = await createServer({
       appDir: './app',

package/src/fetch-handler.ts

@@ -141,10 +141,11 @@ export function createFetchHandler(
 
     const matched = matchRoute(compiledRoutes, pathname, method);
     if (matched) {
-      const reqWithParams = new Request(request);
-      (reqWithParams as Request & { params?: Record<string, string | undefined> }).params =
+      // Attach params on the original request. `new Request(request)` clones
+      // through Node's Request constructor, which strips Cookie/Origin/Host.
+      (request as Request & { params?: Record<string, string | undefined> }).params =
         matched.params;
-      return matched.route.fetch(reqWithParams);
+      return matched.route.fetch(request);
     }
 
     if (options.onNotMatched) {

package/src/html.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from 'vitest';
+import { html, placeholder, render, type HSHtml } from './html';
+
+describe('@hyperspan/framework/html', () => {
+  test('re-exports html helpers and types from @hyperspan/html', () => {
+    const tmpl: HSHtml = html`<p>
+      ${placeholder(html`<span>loading</span>`, Promise.resolve('ok'))}
+    </p>`;
+
+    expect(render(tmpl)).toContain('<p>');
+    expect(render(tmpl)).toContain('loading');
+  });
+});

package/src/html.ts

@@ -0,0 +1 @@
+export * from '@hyperspan/html';

package/src/index.ts

@@ -3,6 +3,7 @@ export {
   createContext,
   createRoute,
   createServer,
+  initServerRoutes,
   getRunnableRoute,
   StreamResponse,
   IS_PROD,
@@ -19,8 +20,21 @@ export {
   getImportMap,
   registerImport,
 } from './client/manifest';
-export { buildClientJS } from './client/js';
+export { buildClientJS, registerPathAliases } from './client/js';
+export type { BuildClientJSOptions, ClientJSType } from './client/js';
+export { registerRouteModule, registerRouteModules } from './register-routes';
+export type { RouteModuleEntry } from './register-routes';
 export type { AssetManifest } from './client/manifest';
 export { renderIsland } from './island';
 export type { IslandRenderOptions } from './island';
-export type { Hyperspan } from './types';
+export type {
+  Hyperspan,
+  ServerCreateContext,
+  DeployAdapter,
+  Adapter,
+  AdapterAfterBuildContext,
+  DeployEntry,
+  DeployEntryContext,
+  ServerEntrySlots,
+  ServerEntryTemplate,
+} from './types';

package/src/island.ts

@@ -1,4 +1,4 @@
-import { html } from '@hyperspan/html';
+import { html } from './html';
 
 type IslandComponent = {
   __HS_ISLAND?: {

package/src/layout.test.ts

@@ -0,0 +1,12 @@
+import { test, expect } from 'vitest';
+import { render } from './html';
+import { hyperspanScriptTags } from './layout';
+import { streamingClient } from './client/js';
+
+test('streaming bootstrap injects a classic script so chunks swap in during parse', () => {
+  const html = render(hyperspanScriptTags());
+  expect(html).toContain("document.createElement('script')");
+  expect(html).toContain(`script.src = '${streamingClient.publicPath}'`);
+  expect(html).not.toContain("type = 'module'");
+  expect(html).not.toContain(`import('${streamingClient.publicPath}')`);
+});

package/src/layout.ts

@@ -1,23 +1,20 @@
-import { html } from '@hyperspan/html';
+import { html } from './html';
 import { CSS_PUBLIC_PATH } from './client/css';
-import { getImportMap, getRouteCss, getClientJSFromManifest } from './client/manifest';
+import { getImportMap, getRouteCss } from './client/manifest';
+import { actionsClient, streamingClient } from './client/js';
 import type { Hyperspan as HS } from './types';
 
-function streamingClientPath(): string {
-  return getClientJSFromManifest('streaming').publicPath;
-}
-
 /**
- * Output the importmap for the client so we can use ESModules on the client to load JS files on demand
+ * Output the importmap for the client so we can use ESModules on the client to load JS files on demand.
+ *
+ * The streaming client MUST be loaded as a classic <script>, not type=module.
+ * Browsers defer all ESM until the document finishes parsing, which would hold
+ * every streaming chunk until the whole page is done. A dynamically inserted
+ * classic script runs as soon as it downloads.
  */
 export function hyperspanScriptTags() {
   const imports = getImportMap();
-  let streamingPath: string;
-  try {
-    streamingPath = streamingClientPath();
-  } catch {
-    streamingPath = '/_hs/js/hyperspan-streaming.client.js';
-  }
+  const streamingPath = streamingClient.publicPath;
 
   return html`
     <script type="importmap">
@@ -65,10 +62,5 @@ export function hyperspanStyleTags(context: HS.Context) {
  * Render the actions client script tag (used by createAction).
  */
 export function hyperspanActionsScriptTag() {
-  try {
-    const actions = getClientJSFromManifest('actions');
-    return html`<script type="module" src="${actions.publicPath}"></script>`;
-  } catch {
-    return html`<script type="module" src="/_hs/js/hyperspan-actions.client.js"></script>`;
-  }
+  return html`<script type="module" src="${actionsClient.publicPath}"></script>`;
 }

package/src/register-routes.ts

@@ -0,0 +1,64 @@
+import { getRunnableRoute } from './server';
+import { isValidRoutePath, parsePath } from './utils';
+import type { AssetManifest } from './client/manifest';
+import type { Hyperspan as HS } from './types';
+
+export type RouteModuleEntry = {
+  file: string;
+  mod: unknown;
+};
+
+/**
+ * Register a route or action module on a Hyperspan server.
+ * Shared by the CLI, Vite plugin, and the generated production server entry.
+ */
+export function registerRouteModule(
+  server: HS.Server,
+  relativeFilePath: string,
+  mod: unknown,
+  manifest?: AssetManifest
+): HS.Route | null {
+  if (!isValidRoutePath(relativeFilePath)) {
+    return null;
+  }
+
+  const route = getRunnableRoute(mod);
+  const parsedPath = parsePath(relativeFilePath);
+
+  let path = parsedPath.path;
+  if (typeof route._path === 'function') {
+    const routePath = route._path();
+    if (routePath && routePath !== '/') path = routePath;
+  }
+
+  if (!route._config.path) {
+    route._config.path = path;
+    if (parsedPath.params.length > 0) {
+      const params = route._config.params ?? {};
+      parsedPath.params.forEach((param) => {
+        params[param] = undefined;
+      });
+      route._config.params = params;
+    }
+  }
+
+  if (manifest) {
+    const cssFiles = manifest.css?.[path] ?? manifest.css?.['*'];
+    if (cssFiles?.length) {
+      route._config.cssImports = cssFiles;
+    }
+  }
+
+  server._routes.push(route);
+  return route;
+}
+
+export function registerRouteModules(
+  server: HS.Server,
+  modules: RouteModuleEntry[],
+  manifest?: AssetManifest
+): void {
+  for (const { file, mod } of modules) {
+    registerRouteModule(server, file, mod, manifest);
+  }
+}

package/src/server.test.ts

@@ -1,7 +1,7 @@
 import { test, expect, describe } from 'vitest';
-import { createRoute, createServer, createContext } from './server';
+import { createRoute, createServer, createContext, initServerRoutes } from './server';
 import { createAction } from './actions';
-import { html, placeholder } from '@hyperspan/html';
+import { html, placeholder } from './html';
 import type { Hyperspan as HS } from './types';
 
 test('route fetch() returns a Response', async () => {
@@ -92,6 +92,25 @@ test('server returns a route with a POST request', async () => {
   expect(await response.text()).toBe('<h1>POST /users</h1>');
 });
 
+test('POST HTML response does not inherit request Content-Length', async () => {
+  const route = createRoute().post((context: HS.Context) => {
+    return context.res.html('<h1>hello world this is longer than the form body</h1>');
+  });
+  const body = 'email=a@b.com&password=secret';
+  const request = new Request('http://localhost:3000/', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/x-www-form-urlencoded',
+      'content-length': String(body.length),
+    },
+    body,
+  });
+  const response = await route.fetch(request);
+  const text = await response.text();
+  expect(text).toBe('<h1>hello world this is longer than the form body</h1>');
+  expect(Number(response.headers.get('content-length') ?? text.length)).toBe(text.length);
+});
+
 test('server returns a route with a ALL request', async () => {
   const server = await createServer({
     appDir: './app',
@@ -566,3 +585,31 @@ describe('when streaming is disabled', () => {
     expect(text).not.toContain('hs:loading');
   });
 });
+
+test('initServerRoutes runs beforeRoutesAdded, then addRoutes, then afterRoutesAdded', async () => {
+  const order: string[] = [];
+  const server = await createServer({
+    appDir: './app',
+    publicDir: './public',
+    plugins: [],
+  });
+
+  await initServerRoutes(
+    server,
+    {
+      beforeRoutesAdded(s) {
+        order.push('before');
+        s.use(async (_c, next) => next());
+      },
+      afterRoutesAdded() {
+        order.push('after');
+      },
+    },
+    () => {
+      order.push('routes');
+    }
+  );
+
+  expect(order).toEqual(['before', 'routes', 'after']);
+  expect(server._middleware['*']).toHaveLength(1);
+});

package/src/server.ts

@@ -1,17 +1,10 @@
 import './ssr/install-server-dom-mock';
-import {
-  HSHtml,
-  html,
-  isHSHtml,
-  renderStream,
-  renderAsync,
-  render,
-  _typeOf,
-} from '@hyperspan/html';
+import { HSHtml, html, isHSHtml, renderStream, renderAsync, render, _typeOf } from './html';
 import { isbot } from 'isbot';
 import { executeMiddleware } from './middleware';
 import { buildUrl, parsePath, removeUndefined } from './utils';
 import { Cookies } from './cookies';
+import { nodeAdapter } from '@hyperspan/adapter-node';
 
 import type { Hyperspan as HS } from './types';
 
@@ -51,6 +44,7 @@ export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
     appDir: './app',
     publicDir: './public',
     plugins: [],
+    deployAdapter: config.deployAdapter ?? nodeAdapter(),
     responseOptions: {
       disableStreaming: hyperspanDisableStreaming,
     },
@@ -58,6 +52,7 @@ export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
   return {
     ...defaultConfig,
     ...config,
+    deployAdapter: config.deployAdapter ?? defaultConfig.deployAdapter,
     responseOptions: {
       ...defaultConfig.responseOptions,
       ...config.responseOptions,
@@ -72,7 +67,8 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
   const url = new URL(req.url);
   const query = new URLSearchParams(url.search);
   const method = req.method.toUpperCase();
-  const headers = new Headers(req.headers);
+  const requestHeaders = new Headers(req.headers);
+  const responseHeaders = new Headers();
   const path = route?._path() || '/';
   const requestParams = (req as Request & { params?: Record<string, string | undefined> }).params;
   const params: Record<string, string | undefined> = Object.assign(
@@ -92,12 +88,21 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
   // Status override for the response. Will use if set. (e.g. c.res.status = 400)
   let status: number | undefined = undefined;
 
+  const copyHeaders = (source: Headers, target: Headers) => {
+    source.forEach((value, key) => {
+      if (key.toLowerCase() === 'set-cookie') return;
+      target.set(key, value);
+    });
+    const cookies = typeof source.getSetCookie === 'function' ? source.getSetCookie() : [];
+    for (const cookie of cookies) {
+      target.append('Set-Cookie', cookie);
+    }
+  };
+
   const merge = async (response: Response) => {
-    // Convert headers to plain objects and merge (response headers override context headers)
-    const mergedHeaders = {
-      ...Object.fromEntries(headers.entries()),
-      ...Object.fromEntries(response.headers.entries()),
-    };
+    const mergedHeaders = new Headers();
+    copyHeaders(responseHeaders, mergedHeaders);
+    copyHeaders(response.headers, mergedHeaders);
 
     return new Response(await response.text(), {
       status: context.res.status ?? response.status,
@@ -121,7 +126,7 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
       raw: req,
       url,
       method,
-      headers,
+      headers: requestHeaders,
       query,
       cookies: new Cookies(req),
       async text() {
@@ -138,8 +143,8 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
       },
     },
     res: {
-      cookies: new Cookies(req, headers),
-      headers,
+      cookies: new Cookies(req, responseHeaders),
+      headers: responseHeaders,
       status,
       html: (html: string, options?: ResponseInit) =>
         merge(
@@ -501,6 +506,20 @@ export async function createServer(config: HS.Config = {} as HS.Config): Promise
   return api;
 }
 
+/**
+ * Shared route lifecycle for Vite dev, production entries, and `hyperspan start`.
+ * Always: `beforeRoutesAdded` → add routes → `afterRoutesAdded`.
+ */
+export async function initServerRoutes(
+  server: HS.Server,
+  config: Pick<HS.Config, 'beforeRoutesAdded' | 'afterRoutesAdded'>,
+  addRoutes: (server: HS.Server) => void | Promise<void>
+): Promise<void> {
+  await config.beforeRoutesAdded?.(server);
+  await addRoutes(server);
+  await config.afterRoutesAdded?.(server);
+}
+
 /**
  * Checks if a response is HTML content
  */

package/src/types.ts

@@ -1,4 +1,4 @@
-import { HSHtml } from '@hyperspan/html';
+import { HSHtml } from './html';
 import * as z from 'zod';
 
 /**
@@ -63,13 +63,78 @@ export namespace Hyperspan {
     disableStreaming?: DisableStreamingFn;
   };
 
+  export type AdapterAfterBuildContext = {
+    root: string;
+    appDir: string;
+    outDir: string;
+  };
+
+  export type ServerCreateContext = {
+    env: unknown;
+  };
+
+  export type DeployEntryContext = {
+    createHyperspanServer: (ctx: ServerCreateContext) => Promise<Server>;
+    config: Config;
+  };
+
+  export type DeployEntry = {
+    start?(options?: { port?: number }): unknown | Promise<unknown>;
+    fetch?(request: Request, env?: unknown, ctx?: unknown): Response | Promise<Response>;
+  };
+
+  /** Optional snippets interpolated into generated `dist/server.ts`. Null/omitted slots emit nothing. */
+  export type ServerEntrySlots = {
+    beforeFileContent?: string | null;
+    beforeCreateServer?: string | null;
+    afterCreateServer?: string | null;
+    beforeRoutes?: string | null;
+    afterRoutes?: string | null;
+    afterFileContent?: string | null;
+  };
+
+  export type ServerEntryTemplate = (slots?: ServerEntrySlots) => string;
+
+  export type Adapter = {
+    /** Diagnostic name, e.g. `node`, `cloudflare`. */
+    name: string;
+    /**
+     * Native ESM specifier exporting `resolveDevEnv(root)`.
+     * Imported by the Vite plugin so platform SDKs like wrangler load correctly.
+     */
+    devModule?: string;
+    resolveDevEnv?(root: string): Promise<unknown>;
+    /**
+     * Render generated `dist/server.ts` from the shared bootstrap template.
+     * Fill slots (especially `afterFileContent`) for the platform entry.
+     */
+    renderServerEntry(template: ServerEntryTemplate): string | Promise<string>;
+    afterBuild?(ctx: AdapterAfterBuildContext): void | Promise<void>;
+  };
+
+  /** Runtime adapter object (`nodeAdapter()`, `cloudflareAdapter()`, …). */
+  export type DeployAdapter = Adapter;
+
   export type Config = {
     appDir: string;
     publicDir: string;
-    plugins: Array<Hyperspan.Plugin>; // Loaders for client islands
+    /** Island plugins (`preactPlugin()`, `sveltePlugin()`, …). */
+    plugins: Array<Hyperspan.Plugin>;
+    /**
+     * Deployment adapter. Pass `cloudflareAdapter()` or `bunAdapter()`.
+     * Omit (or pass `nodeAdapter()`) to deploy to Node.
+     */
+    deployAdapter: Adapter;
+    /**
+     * Called before the server is created, with platform bindings.
+     * - Vite/`hyperspan dev`: adapter `devModule` `resolveDevEnv(root)` when present; else `process.env`
+     * - Node/Bun production entry: `process.env`
+     * - Cloudflare Workers entry: Worker `env` bindings
+     */
+    beforeServerCreate?: (ctx: ServerCreateContext) => void | Promise<void>;
     // For customizing the routes and adding your own...
-    beforeRoutesAdded?: (server: Hyperspan.Server) => void;
-    afterRoutesAdded?: (server: Hyperspan.Server) => void;
+    beforeRoutesAdded?: (server: Hyperspan.Server) => void | Promise<void>;
+    afterRoutesAdded?: (server: Hyperspan.Server) => void | Promise<void>;
     responseOptions?: ResponseOptions;
   };
 
@@ -365,7 +430,7 @@ export namespace Hyperspan {
    * Client JS Module = ESM Module + Public Path + Render Script Tag
    */
   export type ClientJSBuildResult = {
-    assetHash: string; // Asset hash of the module path
+    assetHash: string; // Identity of the resolved path; production file hash comes from Vite
     esmName: string; // Filename of the built JavaScript file without the extension
     publicPath: string; // Full public path of the built JavaScript file
     /**
@@ -387,6 +452,15 @@ export namespace Hyperspan {
   }
 }
 
+export type DeployAdapter = Hyperspan.DeployAdapter;
+export type ServerCreateContext = Hyperspan.ServerCreateContext;
+export type Adapter = Hyperspan.Adapter;
+export type AdapterAfterBuildContext = Hyperspan.AdapterAfterBuildContext;
+export type DeployEntry = Hyperspan.DeployEntry;
+export type DeployEntryContext = Hyperspan.DeployEntryContext;
+export type ServerEntrySlots = Hyperspan.ServerEntrySlots;
+export type ServerEntryTemplate = Hyperspan.ServerEntryTemplate;
+
 declare global {
   interface DocumentEventMap {
     'hs:action:before-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;