@hyperspan/framework 2.0.0-alpha.6 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "2.0.0-alpha.6",
+  "version": "2.0.0",
   "description": "Hyperspan Web Framework",
   "type": "module",
   "main": "src/server.ts",
@@ -8,7 +8,7 @@
   "public": true,
   "publishConfig": {
     "access": "public",
-    "tag": "alpha"
+    "tag": "latest"
   },
   "exports": {
     ".": {
@@ -35,6 +35,10 @@
       "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"
@@ -51,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"
@@ -97,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.4",
+    "@hyperspan/html": "^2.0.0",
     "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

@@ -4,11 +4,7 @@ import { createConfig } from './server';
 
 const cloudflare: Adapter = {
   name: 'cloudflare',
-  createEntry() {
-    return {
-      fetch: async () => new Response('ok'),
-    };
-  },
+  renderServerEntry: (template) => template(),
 };
 
 describe('createConfig deployAdapter', () => {

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()');
   });
 
@@ -63,15 +95,52 @@ describe('buildClientJS', () => {
     expect(tag).toContain('({ mountPicker }) => mountPicker()');
   });
 
-  test('package export specifiers resolve on disk like app logical paths', async () => {
-    const result = await buildClientJS(
-      '@hyperspan/framework/client/_hs/hyperspan-streaming.client.ts',
-      { type: 'iife' }
+  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 () => {
@@ -104,6 +173,39 @@ describe('buildClientJS', () => {
       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,7 +1,7 @@
 import { readFileSync, existsSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+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';
@@ -19,7 +19,19 @@ export type BuildClientJSOptions = {
 };
 
 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;
@@ -28,7 +40,58 @@ export type ClientJSEntry = {
   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 {
@@ -69,46 +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 resolveClientModulePath(modulePathResolved: string): string {
-  if (modulePathResolved.startsWith('file://')) {
-    return fileURLToPath(modulePathResolved);
+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 modulePathResolved;
+  return normalized;
 }
 
-/**
- * Resolve a client module path for hashing and bundling.
- * Logical app-relative paths (e.g. app/client/foo.ts) hash consistently across
- * Node and edge runtimes where absolute paths differ.
- */
-export function resolveClientModulePaths(modulePathResolved: string): {
-  hashKey: string;
-  absPath: string;
-} {
-  const resolved = resolveClientModulePath(modulePathResolved).replace(/\\/g, '/');
-
-  if (!isAbsolute(resolved)) {
-    const hashKey = resolved;
-    if (typeof process !== 'undefined' && typeof process.cwd === 'function') {
-      const candidate = join(process.cwd(), hashKey);
-      if (existsSync(candidate)) {
-        return { hashKey, absPath: candidate };
-      }
+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;
     }
-    try {
-      const url = import.meta.resolve(resolved);
-      if (typeof url === 'string' && url.startsWith('file://')) {
-        return { hashKey, absPath: fileURLToPath(url) };
-      }
-    } catch {
-      // Bare specifiers that aren't installed yet still hash stably.
+    const resolved = import.meta.resolve(specifier);
+    if (typeof resolved === 'string' && (resolved.startsWith('file://') || isAbsolute(resolved))) {
+      return toFilePath(resolved);
     }
-    return { hashKey, absPath: hashKey };
+  } 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.
+ */
+function resolveClientAbsPath(specifier: string): string {
+  if (specifier.startsWith('file://') || isAbsolute(specifier)) {
+    return toFilePath(specifier);
+  }
+
+  const aliased = resolveWithAliases(specifier);
+  if (aliased) {
+    return aliased;
   }
 
-  return { hashKey: resolved, absPath: resolved };
+  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[] {
@@ -121,10 +230,11 @@ export function getClientJSEntryByEsmName(esmName: string): ClientJSEntry | unde
 
 export function resetClientJSEntriesForTests(): void {
   getClientJSRegistry().clear();
-}
-
-function registerClientJSEntry(entry: ClientJSEntry): void {
-  getClientJSRegistry().set(entry.esmName, entry);
+  getPathIdentityClientJS().length = 0;
+  const aliases = getPathAliases();
+  for (const key of Object.keys(aliases)) {
+    delete aliases[key];
+  }
 }
 
 function registerClientJS(
@@ -132,34 +242,79 @@ function registerClientJS(
   options: BuildClientJSOptions = {}
 ): HS.ClientJSBuildResult {
   const type = options.type ?? 'module';
-  const { hashKey, absPath } = resolveClientModulePaths(modulePathResolved);
-  const hash = assetHashFn(hashKey);
+  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.`
+    );
+  }
+
+  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';
-  const sourcePath = existsSync(absPath) ? absPath : null;
-  if (sourcePath) {
-    const source = readFileSync(sourcePath, '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, type });
-  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="${publicPath}"></script>`;
+        return html`<script src="${clientPublicPath(esmName)}"></script>`;
       }
 
       const t = typeof loadScript;
+      const { exports, fnArgs } = currentExports();
 
       if (t === 'string') {
         return html`
@@ -188,10 +343,13 @@ function registerClientJS(
 }
 
 /**
- * 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.
+ * 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,
@@ -200,7 +358,8 @@ export async function buildClientJS(
   return registerClientJS(modulePathResolved, options);
 }
 
-/** Same `buildClientJS` path an app would use for a package export. */
+// 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' }

package/src/client/manifest.ts

@@ -6,52 +6,61 @@ export type AssetManifest = {
   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;
@@ -63,7 +72,7 @@ export function getClientJSFromManifest(
   moduleId: string,
   _exportNames = 'default'
 ): ClientJSBuildResult {
-  const publicPath = _manifest.clients[moduleId];
+  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,7 +20,7 @@ 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';
@@ -34,4 +35,6 @@ export type {
   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

@@ -1,5 +1,5 @@
 import { test, expect } from 'vitest';
-import { render } from '@hyperspan/html';
+import { render } from './html';
 import { hyperspanScriptTags } from './layout';
 import { streamingClient } from './client/js';
 

package/src/layout.ts

@@ -1,4 +1,4 @@
-import { html } from '@hyperspan/html';
+import { html } from './html';
 import { CSS_PUBLIC_PATH } from './client/css';
 import { getImportMap, getRouteCss } from './client/manifest';
 import { actionsClient, streamingClient } from './client/js';

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,13 +1,5 @@
 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';
@@ -75,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(
@@ -95,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,
@@ -124,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() {
@@ -141,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(
@@ -504,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';
 
 /**
@@ -69,8 +69,12 @@ export namespace Hyperspan {
     outDir: string;
   };
 
+  export type ServerCreateContext = {
+    env: unknown;
+  };
+
   export type DeployEntryContext = {
-    createHyperspanServer: () => Promise<Server>;
+    createHyperspanServer: (ctx: ServerCreateContext) => Promise<Server>;
     config: Config;
   };
 
@@ -79,6 +83,18 @@ export namespace Hyperspan {
     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;
@@ -88,18 +104,17 @@ export namespace Hyperspan {
      */
     devModule?: string;
     resolveDevEnv?(root: string): Promise<unknown>;
-    /** Platform entry (`start` and/or `fetch`). Called from generated `dist/server.ts`. */
-    createEntry(ctx: DeployEntryContext): DeployEntry;
+    /**
+     * 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 ServerCreateContext = {
-    env: unknown;
-  };
-
   export type Config = {
     appDir: string;
     publicDir: string;
@@ -118,8 +133,8 @@ export namespace Hyperspan {
      */
     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;
   };
 
@@ -415,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
     /**
@@ -443,6 +458,8 @@ 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 {