@hyperspan/framework 2.0.0-alpha.1 → 2.0.0-alpha.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.13",
   "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"
@@ -93,10 +101,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.1",
+    "@hyperspan/html": "^2.0.0-alpha.13",
     "debug": "^4.4.3",
     "isbot": "^5.1.32",
     "zod": "^4.4.3"

package/src/adapter.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from 'bun:test';
+import type { Adapter } from './types';
+import { createConfig } from './server';
+
+const cloudflare: Adapter = {
+  name: 'cloudflare',
+  createEntry() {
+    return {
+      fetch: async () => new Response('ok'),
+    };
+  },
+};
+
+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/_hs/hyperspan-actions.client.ts

@@ -59,62 +59,56 @@ function setActionLoading(hsActionTag: HTMLElement | null, loading: boolean) {
   }
 }
 
-const actionFormObserver = new MutationObserver((list) => {
-  list.forEach((mutation) => {
-    mutation.addedNodes.forEach((node) => {
-      if (node && ('closest' in node || node instanceof HTMLFormElement)) {
-        bindHSActionForm(
-          (node as HTMLElement).closest('hs-action') as HSAction,
-          node instanceof HTMLFormElement
-            ? node
-            : ((node as HTMLElement | HTMLFormElement).querySelector('form') as HTMLFormElement)
-        );
-      }
-    });
-  });
-});
-
 /**
- * Server action component to handle the client-side form submission and HTML replacement
+ * Server action component — holds the action URL; form submit is handled via delegation.
  */
-class HSAction extends HTMLElement {
-  constructor() {
-    super();
-  }
-
-  connectedCallback() {
-    actionFormObserver.observe(this, { childList: true, subtree: true });
-    bindHSActionForm(this, this.querySelector('form') as HTMLFormElement);
-  }
-}
+class HSAction extends HTMLElement {}
 window.customElements.define('hs-action', HSAction);
 
-/**
- * Bind the form inside an hs-action element to the action URL and submit handler
- */
-function bindHSActionForm(hsActionElement: HSAction, form: HTMLFormElement) {
-  if (!hsActionElement || !form) {
+let actionDelegationInitialized = false;
+
+/** One document-level handler so morphs never leave forms without listeners or stack duplicates. */
+function initHSActionFormDelegation() {
+  if (actionDelegationInitialized) {
     return;
   }
+  actionDelegationInitialized = true;
 
-  form.setAttribute('action', hsActionElement.getAttribute('url') || '');
-  const submitHandler = (e: Event) => {
-    e.preventDefault();
-    formSubmitToRoute(e, form as HTMLFormElement, {
-      afterResponse: () => bindHSActionForm(hsActionElement, form),
-    });
-    form.removeEventListener('submit', submitHandler);
-  };
-  form.addEventListener('submit', submitHandler);
+  document.addEventListener(
+    'submit',
+    (e) => {
+      const form = e.target;
+      if (!(form instanceof HTMLFormElement)) {
+        return;
+      }
+
+      const hsAction = form.closest('hs-action');
+      if (!hsAction) {
+        return;
+      }
+
+      e.preventDefault();
+
+      const url = hsAction.getAttribute('url') || '';
+      if (url) {
+        form.setAttribute('action', url);
+      }
+
+      formSubmitToRoute(form);
+    },
+    true
+  );
 }
 
+initHSActionFormDelegation();
+
 /**
  * Submit form data to route and replace contents with response
  */
-type TFormSubmitOptons = { afterResponse: () => any };
-function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOptons) {
+function formSubmitToRoute(form: HTMLFormElement) {
   const formData = new FormData(form);
-  const formUrl = form.getAttribute('action') || '';
+  const hsActionTag = form.closest('hs-action') as HTMLElement | null;
+  const formUrl = hsActionTag?.getAttribute('url') || form.getAttribute('action') || '';
   const method = form.getAttribute('method')?.toUpperCase() || 'POST';
   const confirmMessage = form.getAttribute('data-confirm') || '';
   const headers = {
@@ -129,7 +123,6 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
     }
   }
 
-  const hsActionTag = form.closest('hs-action') as HTMLElement | null;
   const eventTarget: EventTarget = hsActionTag || document;
   const fetchDetail: HS.ActionFetchDetail = {
     form,
@@ -185,7 +178,6 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
 
     dispatchActionEvent(eventTarget, HS_ACTION_AFTER_SWAP, swapDetail);
 
-    opts.afterResponse && opts.afterResponse();
     lazyLoadScripts();
   }
 

package/src/client/js.test.ts

@@ -1,5 +1,147 @@
-import { describe, expect, test } from 'vitest';
-import { extractExports } from './js';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { mkdtempSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { render } from '@hyperspan/html';
+import {
+  buildClientJS,
+  discoverClientExports,
+  extractExports,
+  getClientJSEntries,
+  registerPathAliases,
+  resetClientJSEntriesForTests,
+} from './js';
+
+describe('buildClientJS', () => {
+  let clientFile: string;
+
+  beforeEach(() => {
+    resetClientJSEntriesForTests();
+    const dir = mkdtempSync(join(tmpdir(), 'hs-client-'));
+    clientFile = join(dir, 'picker.ts');
+    writeFileSync(
+      clientFile,
+      `export function mountPicker() {
+  document.getElementById('picker')?.classList.add('ready');
+}
+`
+    );
+  });
+
+  test('registers entry and returns stable esmName from path hash', async () => {
+    const result = await buildClientJS(clientFile);
+
+    expect(result.esmName).toMatch(/^client-[0-9a-f]{16}$/);
+    expect(result.publicPath).toBe(`/_hs/js/${result.esmName}.js`);
+    expect(getClientJSEntries()).toHaveLength(1);
+    expect(getClientJSEntries()[0].absPath).toBe(clientFile);
+  });
+
+  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(`data-source-id="${result.assetHash}"`);
+  });
+
+  test('renderScriptTag with function inlines bootstrap code', async () => {
+    const result = await buildClientJS(clientFile);
+    const tag = render(
+      result.renderScriptTag(({ mountPicker }: { mountPicker: () => void }) => {
+        mountPicker();
+      })
+    );
+
+    expect(tag).toContain(`import {mountPicker} from "${result.esmName}"`);
+    expect(tag).toContain('mountPicker()');
+  });
+
+  test('renderScriptTag with string inlines bootstrap code', async () => {
+    const result = await buildClientJS(clientFile);
+    const tag = render(result.renderScriptTag('({ mountPicker }) => mountPicker()'));
+
+    expect(tag).toContain('({ mountPicker }) => mountPicker()');
+  });
+
+  test('import.meta.resolve at the call site registers a real file', 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$/);
+  });
+
+  test('relative paths must be resolved at the call site', async () => {
+    await expect(buildClientJS('../client/picker.ts')).rejects.toThrow(/import\.meta\.resolve/);
+    await expect(buildClientJS('./picker.ts')).rejects.toThrow(/import\.meta\.resolve/);
+  });
+
+  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);
+  });
+
+  test('aliased specifiers keep a stable hash when the file is missing', async () => {
+    registerPathAliases({ '~/': '/definitely-missing-hyperspan-root/' });
+    const first = await buildClientJS('~/app/client/missing.ts');
+    resetClientJSEntriesForTests();
+    registerPathAliases({ '~/': '/definitely-missing-hyperspan-root/' });
+    const second = await buildClientJS('~/app/client/missing.ts');
+    expect(first.esmName).toBe(second.esmName);
+    expect(existsSync(getClientJSEntries()[0].absPath)).toBe(false);
+  });
+});
 
 describe('extractExports', () => {
   test('extracts aliased export from bundled JS content', () => {
@@ -14,7 +156,7 @@ describe('extractExports', () => {
     });
   });
 
-  test('returns empty exports when none found', () => {
+  test('returns namespace export when none found', () => {
     const contents = 'function noop(){return 1}const value=2;';
 
     const result = extractExports(contents);
@@ -25,3 +167,14 @@ describe('extractExports', () => {
     });
   });
 });
+
+describe('discoverClientExports', () => {
+  test('discovers named exports from source', () => {
+    const result = discoverClientExports(
+      `export function mountPicker() {}\nexport const VERSION = 1;`
+    );
+
+    expect(result.exports).toBe('{mountPicker, VERSION}');
+    expect(result.fnArgs).toBe('{mountPicker, VERSION}');
+  });
+});

package/src/client/js.ts

@@ -1,4 +1,8 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { html } from '@hyperspan/html';
+import { assetHash as assetHashFn } from '../utils';
 import { getImportMap, registerImport, resolveImport } from './manifest';
 import type { Hyperspan as HS } from '../types';
 
@@ -7,6 +11,65 @@ 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;
+  absPath: string;
+  assetHash: string;
+  esmName: string;
+  publicPath: string;
+  exports: string;
+  fnArgs: string;
+  type: ClientJSType;
+};
+
+const CLIENT_JS_REGISTRY = Symbol.for('@hyperspan/client-js-entries');
+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;
+}
+
+function getClientJSRegistry(): Map<string, ClientJSEntry> {
+  const globalRegistry = globalThis as {
+    [CLIENT_JS_REGISTRY]?: Map<string, ClientJSEntry>;
+  };
+  if (!globalRegistry[CLIENT_JS_REGISTRY]) {
+    globalRegistry[CLIENT_JS_REGISTRY] = new Map();
+  }
+  return globalRegistry[CLIENT_JS_REGISTRY];
+}
+
 /**
  * Backward-compatible import map (backed by asset manifest).
  */
@@ -35,40 +98,225 @@ export const JS_IMPORT_MAP = {
   },
 };
 
-const EXPORT_REGEX = /export\{(.*)\}/g;
+/**
+ * Prefer a cwd-relative hash so `import.meta.resolve(...)` and `app/client/foo.ts`
+ * produce the same public URL. Absolute paths outside the project stay as-is.
+ */
+function stableHashKey(absPath: string): string {
+  const normalized = absPath.replace(/\\/g, '/');
+  if (typeof process !== 'undefined' && typeof process.cwd === 'function') {
+    const rel = relative(process.cwd(), absPath).replace(/\\/g, '/');
+    if (rel && !rel.startsWith('..') && !isAbsolute(rel)) {
+      return rel;
+    }
+  }
+  const marker = '/node_modules/';
+  const idx = normalized.lastIndexOf(marker);
+  if (idx !== -1) {
+    return normalized.slice(idx + marker.length);
+  }
+  return normalized;
+}
+
+function toFilePath(modulePath: string): string {
+  return modulePath.startsWith('file://') ? fileURLToPath(modulePath) : modulePath;
+}
 
 /**
- * @deprecated Use build-time asset manifest via @hyperspan/vite-plugin instead.
- * Kept for compatibility — returns manifest entry if available.
+ * `import.meta.resolve('./file.ts')` → file URL or absolute path.
+ * `~/app/client/foo.ts` → registered tsconfig alias.
+ * `app/client/foo.ts` → project root.
+ * Relative `./` / `../` paths error — resolve them at the call site.
  */
-export async function buildClientJS(_modulePathResolved: string): Promise<HS.ClientJSBuildResult> {
-  const { getClientJSFromManifest } = await import('./manifest');
-  const moduleId = _modulePathResolved.includes('streaming')
-    ? 'streaming'
-    : _modulePathResolved.includes('actions')
-      ? 'actions'
-      : 'scripts';
-
-  try {
-    return getClientJSFromManifest(moduleId);
-  } catch {
-    const esmName = moduleId;
-    const publicPath = `${JS_PUBLIC_PATH}/hyperspan-${moduleId}.client.js`;
-    registerImport(esmName, publicPath);
-    return {
-      assetHash: moduleId,
-      esmName,
-      publicPath,
-      renderScriptTag: () => html`<script type="module" src="${publicPath}"></script>`,
-    };
+function resolveClientModule(modulePath: string): { hashKey: string; absPath: string } {
+  if (modulePath.startsWith('file://') || isAbsolute(modulePath)) {
+    const absPath = toFilePath(modulePath);
+    return { hashKey: stableHashKey(absPath), absPath };
   }
+
+  const specifier = modulePath.replace(/\\/g, '/');
+  if (specifier.startsWith('.')) {
+    throw new Error(
+      `[Hyperspan] buildClientJS(${JSON.stringify(modulePath)}) got a relative path. ` +
+        `Use import.meta.resolve(${JSON.stringify(modulePath)}) at the call site, ` +
+        `or a tsconfig alias like '~/app/client/file.ts'.`
+    );
+  }
+
+  const aliased = resolveWithAliases(specifier);
+  if (aliased) {
+    return { hashKey: specifier, absPath: aliased };
+  }
+
+  return { hashKey: specifier, absPath: join(process.cwd(), specifier) };
+}
+
+export function getClientJSEntries(): ClientJSEntry[] {
+  return [...getClientJSRegistry().values()];
+}
+
+export function getClientJSEntryByEsmName(esmName: string): ClientJSEntry | undefined {
+  return getClientJSRegistry().get(esmName);
+}
+
+export function resetClientJSEntriesForTests(): void {
+  getClientJSRegistry().clear();
+  const aliases = getPathAliases();
+  for (const key of Object.keys(aliases)) {
+    delete aliases[key];
+  }
+}
+
+function registerClientJS(
+  modulePathResolved: string,
+  options: BuildClientJSOptions = {}
+): HS.ClientJSBuildResult {
+  const type = options.type ?? 'module';
+  const { hashKey, absPath } = resolveClientModule(modulePathResolved);
+  const hash = assetHashFn(hashKey);
+  const esmName = `client-${hash}`;
+  const publicPath = resolveImport(esmName) ?? `${JS_PUBLIC_PATH}/${esmName}.js`;
+
+  let exports = '* as _module';
+  let fnArgs = '_module';
+  const sourcePath = existsSync(absPath) ? absPath : null;
+  if (sourcePath) {
+    const source = readFileSync(sourcePath, 'utf-8');
+    const discovered = discoverClientExports(source);
+    exports = discovered.exports;
+    fnArgs = discovered.fnArgs;
+  }
+
+  getClientJSRegistry().set(esmName, {
+    modulePath: modulePathResolved,
+    absPath,
+    assetHash: hash,
+    esmName,
+    publicPath,
+    exports,
+    fnArgs,
+    type,
+  });
+  registerImport(esmName, publicPath);
+
+  return {
+    assetHash: hash,
+    esmName,
+    publicPath,
+    renderScriptTag: (loadScript) => {
+      if (type === 'iife') {
+        return html`<script src="${publicPath}"></script>`;
+      }
+
+      const t = typeof loadScript;
+
+      if (t === 'string') {
+        return html`
+          <script type="module" data-source-id="${hash}">
+            import ${exports} from '${esmName}';
+            (${html.raw(loadScript as string)})(${fnArgs});
+          </script>
+        `;
+      }
+      if (t === 'function') {
+        return html`
+          <script type="module" data-source-id="${hash}">
+            import ${exports} from '${esmName}';
+            (${html.raw(functionToString(loadScript))})(${fnArgs});
+          </script>
+        `;
+      }
+
+      return html`
+        <script type="module" data-source-id="${hash}">
+          import '${esmName}';
+        </script>
+      `;
+    },
+  };
+}
+
+/**
+ * Register a client JS module for Vite to bundle.
+ * Prefer a tsconfig alias or project-root path (`~/app/client/foo.ts`,
+ * `app/client/foo.ts`). 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);
+}
+
+export const streamingClient = registerClientJS(
+  import.meta.resolve('./_hs/hyperspan-streaming.client.ts'),
+  { type: 'iife' }
+);
+export const actionsClient = registerClientJS(
+  import.meta.resolve('./_hs/hyperspan-actions.client.ts')
+);
+
+/**
+ * Discover export names from source or bundled client JS.
+ * Prefers bundled `export{...}` form, then common source export patterns.
+ */
+export function discoverClientExports(contents: string): { exports: string; fnArgs: string } {
+  const bundled = extractExports(contents);
+  if (bundled.exports !== '* as _module') {
+    return bundled;
+  }
+
+  const names: string[] = [];
+  const seen = new Set<string>();
+
+  for (const re of [
+    /export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g,
+    /export\s+const\s+([A-Za-z_$][\w$]*)/g,
+    /export\s+class\s+([A-Za-z_$][\w$]*)/g,
+    /export\s+let\s+([A-Za-z_$][\w$]*)/g,
+  ]) {
+    let match: RegExpExecArray | null;
+    while ((match = re.exec(contents)) !== null) {
+      if (!seen.has(match[1])) {
+        names.push(match[1]);
+        seen.add(match[1]);
+      }
+    }
+  }
+
+  const exportBlock = /export\s*\{([^}]+)\}/g;
+  let block: RegExpExecArray | null;
+  while ((block = exportBlock.exec(contents)) !== null) {
+    for (const part of block[1].split(',')) {
+      const trimmed = part.trim();
+      if (!trimmed || trimmed.startsWith('type ')) continue;
+      const asMatch = trimmed.match(/^(?:([\w$]+)\s+as\s+)?([\w$]+)$/);
+      const name = asMatch?.[2] ?? trimmed;
+      if (name && name !== 'default' && !seen.has(name)) {
+        names.push(name);
+        seen.add(name);
+      }
+    }
+  }
+
+  if (names.length === 0) {
+    if (/export\s+default\b/.test(contents)) {
+      return { exports: 'DefaultExport', fnArgs: 'DefaultExport' };
+    }
+    return { exports: '* as _module', fnArgs: '_module' };
+  }
+
+  const exports = `{${names.join(', ')}}`;
+  return { exports, fnArgs: exports };
 }
 
 /**
- * Extract the exports from a client JS module
+ * Extract the exports from a client JS module (bundled `export{a as b}` form).
  */
 export function extractExports(contents: string): { exports: string; fnArgs: string } {
-  const exportLine = EXPORT_REGEX.exec(contents);
+  const exportRegex = /export\{(.*)\}/g;
+  const exportLine = exportRegex.exec(contents);
   let exports = '{}';
   let fnArgs = '{}';
 

package/src/client/manifest.ts

@@ -3,11 +3,7 @@ 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 = {
@@ -67,7 +63,7 @@ export function getClientJSFromManifest(
   moduleId: string,
   _exportNames = 'default'
 ): ClientJSBuildResult {
-  const publicPath = _manifest.clients[moduleId as keyof AssetManifest['clients']];
+  const publicPath = _manifest.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/index.ts

@@ -3,6 +3,7 @@ export {
   createContext,
   createRoute,
   createServer,
+  initServerRoutes,
   getRunnableRoute,
   StreamResponse,
   IS_PROD,
@@ -19,5 +20,19 @@ export {
   getImportMap,
   registerImport,
 } from './client/manifest';
+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 type { Hyperspan } from './types';
+export { renderIsland } from './island';
+export type { IslandRenderOptions } from './island';
+export type {
+  Hyperspan,
+  ServerCreateContext,
+  DeployAdapter,
+  Adapter,
+  AdapterAfterBuildContext,
+  DeployEntry,
+  DeployEntryContext,
+} from './types';

package/src/island.test.ts

@@ -0,0 +1,30 @@
+import { describe, test, expect } from 'vitest';
+import { renderIsland } from './island';
+
+describe('renderIsland', () => {
+  test('throws when component has no __HS_ISLAND', () => {
+    expect(() => renderIsland({ name: 'Bare' } as never, {})).toThrow(/not a Hyperspan island/i);
+  });
+
+  test('returns html.raw for sync island render', () => {
+    const component = {
+      name: 'Counter',
+      __HS_ISLAND: {
+        render: () => '<div id="x">1</div>',
+      },
+    };
+    const result = renderIsland(component, { count: 1 });
+    expect(result).toHaveProperty('_kind', 'html_safe');
+    expect((result as { content: string }).content).toContain('<div id="x">1</div>');
+  });
+
+  test('awaits async island render', async () => {
+    const component = {
+      __HS_ISLAND: {
+        render: async () => '<div>async</div>',
+      },
+    };
+    const result = await renderIsland(component, {});
+    expect(result.content).toContain('<div>async</div>');
+  });
+});

package/src/island.ts

@@ -0,0 +1,37 @@
+import { html } from '@hyperspan/html';
+
+type IslandComponent = {
+  __HS_ISLAND?: {
+    render: (props: unknown, options: unknown) => string | Promise<string>;
+  };
+  name?: string;
+};
+
+export type IslandRenderOptions = {
+  ssr?: boolean;
+  loading?: 'lazy' | undefined;
+};
+
+/**
+ * Render any Hyperspan island component (Preact, Svelte, Vue).
+ * Proxies to `Component.__HS_ISLAND.render` injected by the island Vite plugin.
+ */
+export function renderIsland(
+  Component: IslandComponent,
+  props: Record<string, unknown> = {},
+  options: IslandRenderOptions = { ssr: true }
+) {
+  if (!Component?.__HS_ISLAND?.render) {
+    const label = Component?.name ?? 'Component';
+    throw new Error(
+      `${label} is not a Hyperspan island. Import it with \`with { island: 'preact' | 'svelte' | 'vue' }\` ` +
+        `and ensure the matching plugin is listed in hyperspan.config.ts plugins.`
+    );
+  }
+
+  const result = Component.__HS_ISLAND.render(props, options);
+  if (result != null && typeof (result as Promise<string>).then === 'function') {
+    return (result as Promise<string>).then((s) => html.raw(s));
+  }
+  return html.raw(result as string);
+}

package/src/layout.test.ts

@@ -0,0 +1,12 @@
+import { test, expect } from 'vitest';
+import { render } from '@hyperspan/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 { 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,5 +1,5 @@
 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 type { Hyperspan as HS } from './types';
@@ -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

@@ -12,6 +12,7 @@ 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 +52,7 @@ export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
     appDir: './app',
     publicDir: './public',
     plugins: [],
+    deployAdapter: config.deployAdapter ?? nodeAdapter(),
     responseOptions: {
       disableStreaming: hyperspanDisableStreaming,
     },
@@ -58,6 +60,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 +75,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 +96,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 +134,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 +151,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 +514,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
  */
@@ -541,7 +568,7 @@ export async function returnHTMLResponse(
       if (!disableStreaming && (routeContent as HSHtml).asyncContent?.length > 0) {
         return new StreamResponse(
           renderStream(routeContent as HSHtml, {
-            renderChunk: (chunk) => {
+            renderChunk: (chunk: { id: string; content: string }) => {
               // Trailing <!--/hs:chunk--> marks the end of a streaming chunk boundary.
               return html`
                 <template id="${chunk.id}_content">${html.raw(chunk.content)}<!--end--></template>

package/src/types.ts

@@ -63,13 +63,63 @@ export namespace Hyperspan {
     disableStreaming?: DisableStreamingFn;
   };
 
+  export type AdapterAfterBuildContext = {
+    root: string;
+    appDir: string;
+    outDir: string;
+  };
+
+  export type DeployEntryContext = {
+    createHyperspanServer: () => Promise<Server>;
+    config: Config;
+  };
+
+  export type DeployEntry = {
+    start?(options?: { port?: number }): unknown | Promise<unknown>;
+    fetch?(request: Request, env?: unknown, ctx?: unknown): Response | Promise<Response>;
+  };
+
+  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>;
+    /** Platform entry (`start` and/or `fetch`). Called from generated `dist/server.ts`. */
+    createEntry(ctx: DeployEntryContext): DeployEntry;
+    afterBuild?(ctx: AdapterAfterBuildContext): void | Promise<void>;
+  };
+
+  /** Runtime adapter object (`nodeAdapter()`, `cloudflareAdapter()`, …). */
+  export type DeployAdapter = Adapter;
+
+  export type ServerCreateContext = {
+    env: unknown;
+  };
+
   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;
   };
 
@@ -387,6 +437,13 @@ 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;
+
 declare global {
   interface DocumentEventMap {
     'hs:action:before-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;

package/tsconfig.json

@@ -1,5 +1,6 @@
 {
   "compileOnSave": true,
+  "include": ["src/**/*.ts"],
   "compilerOptions": {
     "outDir": "dist",
     "target": "ES2020",
@@ -10,7 +11,6 @@
     "esModuleInterop": true,
     "allowImportingTsExtensions": true,
     "noEmit": true,
-    "composite": true,
     "strict": true,
     "declaration": true,
     "sourceMap": true,
@@ -19,11 +19,7 @@
     "allowSyntheticDefaultImports": true,
     "forceConsistentCasingInFileNames": true,
     "allowJs": true,
-    "baseUrl": ".",
-    "paths": {
-      "@hyperspan/html": ["../html/src/html.ts"]
-    }
+    "baseUrl": "."
   },
-  "references": [{ "path": "../html" }],
-  "exclude": ["node_modules", "__tests__", "*.test.ts"]
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }