@hyperspan/framework 1.0.29 → 2.0.0-alpha.1

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.29",
+  "version": "2.0.0-alpha.1",
   "description": "Hyperspan Web Framework",
+  "type": "module",
   "main": "src/server.ts",
   "types": "src/server.ts",
   "public": true,
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "alpha"
   },
   "exports": {
     ".": {
@@ -37,6 +39,10 @@
       "types": "./src/client/js.ts",
       "default": "./src/client/js.ts"
     },
+    "./client/manifest": {
+      "types": "./src/client/manifest.ts",
+      "default": "./src/client/manifest.ts"
+    },
     "./actions": {
       "types": "./src/actions.ts",
       "default": "./src/actions.ts"
@@ -48,6 +54,15 @@
     "./ssr/mock-dom": {
       "types": "./src/ssr/mock-dom.ts",
       "default": "./src/ssr/mock-dom.ts"
+    },
+    "./client/_hs/hyperspan-streaming.client.ts": {
+      "default": "./src/client/_hs/hyperspan-streaming.client.ts"
+    },
+    "./client/_hs/hyperspan-actions.client.ts": {
+      "default": "./src/client/_hs/hyperspan-actions.client.ts"
+    },
+    "./client/_hs/hyperspan-scripts.client.ts": {
+      "default": "./src/client/_hs/hyperspan-scripts.client.ts"
     }
   },
   "author": "Vance Lucas <vance@vancelucas.com>",
@@ -55,7 +70,7 @@
   "keywords": [
     "framework",
     "node",
-    "bun",
+    "vite",
     "web framework",
     "javascript",
     "typescript",
@@ -71,17 +86,17 @@
     "url": "https://github.com/vlucas/hyperspan/issues"
   },
   "scripts": {
-    "test": "bun test"
+    "test": "vitest run"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.1",
     "@types/debug": "^4.1.12",
     "@types/node": "^24.10.0",
     "prettier": "^3.5.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@hyperspan/html": "^1.0.1",
+    "@hyperspan/html": "^2.0.0-alpha.1",
     "debug": "^4.4.3",
     "isbot": "^5.1.32",
     "zod": "^4.4.3"

package/src/actions.test.ts

@@ -1,4 +1,4 @@
-import { test, expect, describe } from 'bun:test';
+import { test, expect, describe } from 'vitest';
 import { createAction } from './actions';
 import { createRoute } from './server';
 import { html, render, placeholder, type HSHtml } from '@hyperspan/html';

package/src/actions.ts

@@ -3,14 +3,11 @@ import { createRoute, HTTPResponseException, returnHTMLResponse } from './server
 import * as z from 'zod';
 import type { Hyperspan as HS } from './types';
 import { assetHash, formDataToJSON } from './utils';
-import { buildClientJS } from './client/js';
+import { hyperspanActionsScriptTag } from './layout';
 import { validateBody, ZodValidationError } from './middleware';
-import { debug } from 'debug';
+import debug from 'debug';
 
 const log = debug('hyperspan:actions');
-const actionsClientJS = await buildClientJS(
-  import.meta.resolve('./client/_hs/hyperspan-actions.client')
-);
 
 /**
  * Actions = Form + route handler
@@ -138,7 +135,7 @@ export function createAction<S extends z.ZodType>(params: {
       const formContent = api._form ? api._form(c, props || {}) : null;
       return formContent
         ? html`<hs-action url="${this._path()}">${formContent}</hs-action
-            >${actionsClientJS.renderScriptTag()}`
+            >${hyperspanActionsScriptTag()}`
         : null;
     },
     errorHandler(handler) {

package/src/client/js.test.ts

@@ -1,9 +1,10 @@
-import { describe, expect, test } from 'bun:test';
+import { describe, expect, test } from 'vitest';
 import { extractExports } from './js';
 
 describe('extractExports', () => {
   test('extracts aliased export from bundled JS content', () => {
-    const contents = 'function d(n,t){if(t)n.classList.remove("hidden");else n.classList.add("hidden")}function p(){let n=document.querySelector("[data-google-spreadsheet-id]"),t=document.querySelector("[data-google-sheet-select]"),a=document.querySelector("[data-google-sheet-message]");if(console.log("googleSheetsPickerClient",n,t),!n||!t)return;let l=(e)=>{if(!a)return;a.textContent=e||"",d(a,Boolean(e))},h=(e)=>{t.innerHTML="",e.forEach((s)=>{let o=document.createElement("option");o.value=s,o.textContent=s,t.appendChild(o)})},r=(e)=>{d(t,e),t.disabled=!e,t.required=e},c=async()=>{let e=n.value.trim();if(l(null),!e){r(!1);return}try{let s=await fetch(`/api/google-sheets/${encodeURIComponent(e)}`),o=await s.json();if(!s.ok||o.error)throw Error(o.error||"Unable to load sheet names.");let i=(o.sheets||[]).map((u)=>u.title).filter(Boolean);if(i.length===0){l("No sheets found in that spreadsheet."),r(!1);return}h(i),t.value=i[0],r(!0)}catch(s){l(s instanceof Error?s.message:"Unable to load sheet names."),r(!1)}};n.addEventListener("input",c),n.addEventListener("change",c)}export{p as mountGoogleSheetsPicker};';
+    const contents =
+      'function d(n,t){if(t)n.classList.remove("hidden");else n.classList.add("hidden")}function p(){let n=document.querySelector("[data-google-spreadsheet-id]"),t=document.querySelector("[data-google-sheet-select]"),a=document.querySelector("[data-google-sheet-message]");if(console.log("googleSheetsPickerClient",n,t),!n||!t)return;let l=(e)=>{if(!a)return;a.textContent=e||"",d(a,Boolean(e))},h=(e)=>{t.innerHTML="",e.forEach((s)=>{let o=document.createElement("option");o.value=s,o.textContent=s,t.appendChild(o)})},r=(e)=>{d(t,e),t.disabled=!e,t.required=e},c=async()=>{let e=n.value.trim();if(l(null),!e){r(!1);return}try{let s=await fetch(`/api/google-sheets/${encodeURIComponent(e)}`),o=await s.json();if(!s.ok||o.error)throw Error(o.error||"Unable to load sheet names.");let i=(o.sheets||[]).map((u)=>u.title).filter(Boolean);if(i.length===0){l("No sheets found in that spreadsheet."),r(!1);return}h(i),t.value=i[0],r(!0)}catch(s){l(s instanceof Error?s.message:"Unable to load sheet names."),r(!1)}};n.addEventListener("input",c),n.addEventListener("change",c)}export{p as mountGoogleSheetsPicker};';
 
     const result = extractExports(contents);
 
@@ -24,4 +25,3 @@ describe('extractExports', () => {
     });
   });
 });
-

package/src/client/js.ts

@@ -1,97 +1,73 @@
 import { html } from '@hyperspan/html';
-import { assetHash as assetHashFn } from '../utils';
-import { join } from 'node:path';
+import { getImportMap, registerImport, resolveImport } from './manifest';
 import type { Hyperspan as HS } from '../types';
 
-const CWD = process.cwd();
-const IS_PROD = process.env.NODE_ENV === 'production';
+export { registerImport, resolveImport, getImportMap } from './manifest';
 
 export const JS_PUBLIC_PATH = '/_hs/js';
 export const JS_ISLAND_PUBLIC_PATH = '/_hs/js/islands';
-export const JS_IMPORT_MAP = new Map<string, string>();
-const CLIENT_JS_CACHE = new Map<string, { esmName: string, exports: string, fnArgs: string, publicPath: string }>();
-const CLIENT_JS_BUILD_PROMISES = new Map<string, Promise<void>>();
-const EXPORT_REGEX = /export\{(.*)\}/g;
 
 /**
- * Build a client JS module and return a Hyperspan.ClientJSBuildResult object
+ * Backward-compatible import map (backed by asset manifest).
  */
-export async function buildClientJS(modulePathResolved: string): Promise<HS.ClientJSBuildResult> {
-  const modulePath = modulePathResolved.replace('file://', '');
-  const assetHash = assetHashFn(modulePath);
-
-  // Cache: Avoid re-processing the same file
-  if (!CLIENT_JS_CACHE.has(assetHash)) {
-    const existingBuild = CLIENT_JS_BUILD_PROMISES.get(assetHash);
-    // Await the existing build promise if it exists (this can get called in parallel from Bun traversing imports)
-    if (existingBuild) {
-      await existingBuild;
-    } else {
-      const buildPromise = (async () => {
-        // Build the client JS module
-        const result = await Bun.build({
-          entrypoints: [modulePath],
-          outdir: join(CWD, './public', JS_PUBLIC_PATH), // @TODO: Make this configurable... should be read from config file...
-          naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
-          external: Array.from(JS_IMPORT_MAP.keys()),
-          minify: true,
-          format: 'esm',
-          target: 'browser',
-          env: 'APP_PUBLIC_*',
-        });
-
-        // Add output file to import map
-        const esmName = String(result.outputs[0].path.split('/').reverse()[0]).replace('.js', '');
-        const publicPath = `${JS_PUBLIC_PATH}/${esmName}.js`;
-        JS_IMPORT_MAP.set(esmName, publicPath);
-
-        // Get the contents of the file to extract the exports
-        const contents = await result.outputs[0].text();
-        const { exports, fnArgs } = extractExports(contents);
-
-        CLIENT_JS_CACHE.set(assetHash, { esmName, exports, fnArgs, publicPath });
-      })();
-
-      CLIENT_JS_BUILD_PROMISES.set(assetHash, buildPromise);
-      try {
-        await buildPromise;
-      } finally {
-        CLIENT_JS_BUILD_PROMISES.delete(assetHash);
-      }
-    }
-  }
+export const JS_IMPORT_MAP = {
+  get size() {
+    return Object.keys(getImportMap()).length;
+  },
+  keys() {
+    return Object.keys(getImportMap()).values();
+  },
+  has(key: string) {
+    return resolveImport(key) !== undefined;
+  },
+  get(key: string) {
+    return resolveImport(key);
+  },
+  set(key: string, value: string) {
+    registerImport(key, value);
+    return this;
+  },
+  entries() {
+    return Object.entries(getImportMap()).values();
+  },
+  [Symbol.iterator]() {
+    return Object.entries(getImportMap())[Symbol.iterator]();
+  },
+};
 
-  const { esmName, exports, fnArgs, publicPath } = CLIENT_JS_CACHE.get(assetHash)!;
-
-  return {
-    assetHash,
-    esmName,
-    publicPath,
-    renderScriptTag: (loadScript) => {
-      const t = typeof loadScript;
-
-      if (t === 'string') {
-        return html`
-          <script type="module" data-source-id="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(loadScript as string)})(${fnArgs});</script>
-        `;
-      }
-      if (t === 'function') {
-        return html`
-          <script type="module" data-source-id="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(functionToString(loadScript))})(${fnArgs});</script>
-        `;
-      }
+const EXPORT_REGEX = /export\{(.*)\}/g;
 
-      return html`
-        <script type="module" data-source-id="${assetHash}">import "${esmName}";</script>
-      `;
-    }
+/**
+ * @deprecated Use build-time asset manifest via @hyperspan/vite-plugin instead.
+ * Kept for compatibility — returns manifest entry if available.
+ */
+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>`,
+    };
   }
 }
 
 /**
  * Extract the exports from a client JS module
  */
-export function extractExports(contents: string): { exports: string, fnArgs: string } {
+export function extractExports(contents: string): { exports: string; fnArgs: string } {
   const exportLine = EXPORT_REGEX.exec(contents);
   let exports = '{}';
   let fnArgs = '{}';
@@ -111,8 +87,8 @@ export function extractExports(contents: string): { exports: string, fnArgs: str
   fnArgs = exports.replace(/(\w+)\s*as\s*(\w+)/g, '$1: $2').trim();
 
   if (exports === '{}' && fnArgs === '{}') {
-    exports = '* as _module'
-    fnArgs = '_module'
+    exports = '* as _module';
+    fnArgs = '_module';
   }
 
   return { exports, fnArgs };
@@ -120,8 +96,7 @@ export function extractExports(contents: string): { exports: string, fnArgs: str
 
 /**
  * Convert a function to a string (results in loss of context!)
- * Handles named, async, and arrow functions
  */
-export function functionToString(fn: any) {
-  return fn.toString().trim();
-}
+export function functionToString(fn: unknown) {
+  return (fn as (...args: unknown[]) => unknown).toString().trim();
+}

package/src/client/manifest.ts

@@ -0,0 +1,87 @@
+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;
+  };
+};
+
+let _manifest: AssetManifest = {
+  imports: {},
+  css: {},
+  clients: {},
+};
+
+/**
+ * Set the build-time asset manifest (called by Vite plugin or build step).
+ */
+export function setAssetManifest(manifest: AssetManifest): void {
+  _manifest = manifest;
+}
+
+/**
+ * Get the current asset manifest.
+ */
+export function getAssetManifest(): AssetManifest {
+  return _manifest;
+}
+
+/**
+ * Resolve a module import name to its public URL.
+ */
+export function resolveImport(name: string): string | undefined {
+  return _manifest.imports[name];
+}
+
+/**
+ * Get CSS files for a route path.
+ */
+export function getRouteCss(path: string): string[] {
+  return _manifest.css[path] ?? [];
+}
+
+/**
+ * Build import map object for layout script tags.
+ */
+export function getImportMap(): Record<string, string> {
+  return { ..._manifest.imports };
+}
+
+/**
+ * Register a client module URL at runtime (dev fallback).
+ */
+export function registerImport(name: string, publicPath: string): void {
+  _manifest.imports[name] = publicPath;
+}
+
+export type ClientJSBuildResult = HS.ClientJSBuildResult;
+
+/**
+ * Create a ClientJSBuildResult from manifest data (replaces runtime Bun.build).
+ */
+export function getClientJSFromManifest(
+  moduleId: string,
+  _exportNames = 'default'
+): ClientJSBuildResult {
+  const publicPath = _manifest.clients[moduleId as keyof AssetManifest['clients']];
+  if (!publicPath) {
+    throw new Error(
+      `[Hyperspan] Client module "${moduleId}" not found in asset manifest. Run hyperspan build or start dev server.`
+    );
+  }
+
+  const esmName = publicPath.split('/').pop()?.replace('.js', '') ?? moduleId;
+
+  return {
+    assetHash: moduleId,
+    esmName,
+    publicPath,
+    renderScriptTag: () => {
+      throw new Error('renderScriptTag requires html template - use layout helpers instead');
+    },
+  };
+}

package/src/fetch-handler.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from 'vitest';
+import { createRoute, createServer } from './server';
+import { createFetchHandler, compileRoutePath } from './fetch-handler';
+import type { Hyperspan as HS } from './types';
+
+describe('compileRoutePath', () => {
+  test('matches static paths', () => {
+    const { pattern } = compileRoutePath('/about');
+    expect('/about'.match(pattern)).toBeTruthy();
+    expect('/about/'.match(pattern)).toBeTruthy();
+  });
+
+  test('matches dynamic params', () => {
+    const { pattern, paramNames } = compileRoutePath('/users/:id');
+    expect(paramNames).toEqual(['id']);
+    const match = '/users/42'.match(pattern);
+    expect(match?.[1]).toBe('42');
+  });
+
+  test('matches wildcard routes', () => {
+    const { pattern, paramNames } = compileRoutePath('/blog/*');
+    expect(paramNames).toEqual(['...slug']);
+    const match = '/blog/hello/world'.match(pattern);
+    expect(match?.[1]).toBe('hello/world');
+  });
+});
+
+describe('createFetchHandler', () => {
+  test('routes GET requests to matching handler', async () => {
+    const server = await createServer({
+      appDir: './app',
+      publicDir: './public',
+      plugins: [],
+    });
+
+    server.get('/hello', (c: HS.Context) => c.res.html('<h1>Hello</h1>'));
+
+    const fetch = createFetchHandler(server);
+    const response = await fetch(new Request('http://localhost/hello'));
+
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe('<h1>Hello</h1>');
+  });
+
+  test('returns 404 for unknown paths', async () => {
+    const server = await createServer({
+      appDir: './app',
+      publicDir: './public',
+      plugins: [],
+    });
+
+    const fetch = createFetchHandler(server);
+    const response = await fetch(new Request('http://localhost/missing'));
+
+    expect(response.status).toBe(404);
+  });
+
+  test('passes route params to context', async () => {
+    const server = await createServer({
+      appDir: './app',
+      publicDir: './public',
+      plugins: [],
+    });
+
+    const route = createRoute({ path: '/items/:id' }).get((c: HS.Context) =>
+      c.res.text(c.route.params.id ?? '')
+    );
+    server._routes.push(route);
+
+    const fetch = createFetchHandler(server);
+    const response = await fetch(new Request('http://localhost/items/abc'));
+
+    expect(await response.text()).toBe('abc');
+  });
+
+  test('redirects trailing slashes', async () => {
+    const server = await createServer({
+      appDir: './app',
+      publicDir: './public',
+      plugins: [],
+    });
+
+    server.get('/page', (c: HS.Context) => c.res.text('ok'));
+
+    const fetch = createFetchHandler(server);
+    const response = await fetch(new Request('http://localhost/page/', { redirect: 'manual' }));
+
+    expect(response.status).toBe(308);
+  });
+});

package/src/fetch-handler.ts

@@ -0,0 +1,167 @@
+import { createContext } from './server';
+import type { Hyperspan as HS } from './types';
+
+export type FetchHandlerOptions = {
+  /** Called when no route matches (before 404). Return a Response to handle static assets etc. */
+  onNotMatched?: (request: Request) => Promise<Response | undefined>;
+};
+
+type CompiledRoute = {
+  route: HS.Route;
+  pattern: RegExp;
+  paramNames: string[];
+  isWildcard: boolean;
+};
+
+/**
+ * Convert a Hyperspan route path (`/users/:id`, `/blog/*`) into a RegExp + param names.
+ */
+export function compileRoutePath(path: string): {
+  pattern: RegExp;
+  paramNames: string[];
+  isWildcard: boolean;
+} {
+  const paramNames: string[] = [];
+  const isWildcard = path.endsWith('/*');
+
+  if (path === '/') {
+    return { pattern: /^\/$/, paramNames, isWildcard: false };
+  }
+
+  const segments = path.split('/').filter(Boolean);
+  const regexParts = segments.map((segment) => {
+    if (segment === '*') {
+      paramNames.push('...slug');
+      return '(.+)';
+    }
+    if (segment.startsWith(':')) {
+      paramNames.push(segment.slice(1));
+      return '([^/]+)';
+    }
+    return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  });
+
+  const pattern = new RegExp(`^/${regexParts.join('/')}${isWildcard ? '' : '/?'}$`);
+  return { pattern, paramNames, isWildcard };
+}
+
+function mergeRouteMiddleware(server: HS.Server, route: HS.Route): void {
+  route._serverConfig = server._config;
+
+  if (!server._middleware || !route._middleware) {
+    return;
+  }
+
+  for (const method of Object.keys(server._middleware) as HS.MiddlewareMethod[]) {
+    if (Array.isArray(server._middleware[method]) && Array.isArray(route._middleware[method])) {
+      route._middleware[method] = server._middleware[method].concat(route._middleware[method]);
+    }
+  }
+}
+
+function matchRoute(
+  compiledRoutes: CompiledRoute[],
+  pathname: string,
+  method: string
+): { route: HS.Route; params: Record<string, string | undefined> } | null {
+  for (const compiled of compiledRoutes) {
+    const match = pathname.match(compiled.pattern);
+    if (!match) {
+      continue;
+    }
+
+    // Actions and some custom handlers may not expose _methods(); treat as all methods.
+    const routeMethods =
+      typeof compiled.route._methods === 'function' ? compiled.route._methods() : ['*'];
+    const supportsMethod =
+      routeMethods.includes(method) ||
+      routeMethods.includes('*') ||
+      (method === 'HEAD' && routeMethods.includes('GET'));
+
+    if (!supportsMethod) {
+      continue;
+    }
+
+    const params: Record<string, string | undefined> = {};
+    compiled.paramNames.forEach((name, index) => {
+      const value = match[index + 1];
+      if (name.startsWith('...')) {
+        params[name] = value;
+      } else {
+        params[name] = value;
+      }
+    });
+
+    return { route: compiled.route, params };
+  }
+
+  return null;
+}
+
+function trailingSlashRedirect(pathname: string, request: Request): Response | null {
+  if (pathname.length > 1 && pathname.endsWith('/')) {
+    const url = new URL(request.url);
+    url.pathname = pathname.slice(0, -1);
+    return Response.redirect(url.toString(), 308);
+  }
+  return null;
+}
+
+/**
+ * Create a portable fetch handler for a Hyperspan server.
+ * Works on Node, Bun, Cloudflare Workers, and any runtime with Web Fetch API.
+ */
+export function createFetchHandler(
+  server: HS.Server,
+  options: FetchHandlerOptions = {}
+): (request: Request) => Promise<Response> {
+  const compiledRoutes: CompiledRoute[] = server._routes.map((route) => {
+    const path = route._path();
+    mergeRouteMiddleware(server, route);
+    const { pattern, paramNames, isWildcard } = compileRoutePath(path);
+    return { route, pattern, paramNames, isWildcard };
+  });
+
+  // Longer / more specific paths first (more segments wins)
+  compiledRoutes.sort((a, b) => {
+    const aSegments = a.route._path().split('/').filter(Boolean).length;
+    const bSegments = b.route._path().split('/').filter(Boolean).length;
+    return bSegments - aSegments;
+  });
+
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const pathname = url.pathname;
+    const method = request.method.toUpperCase();
+
+    const slashRedirect = trailingSlashRedirect(pathname, request);
+    if (slashRedirect) {
+      return slashRedirect;
+    }
+
+    const matched = matchRoute(compiledRoutes, pathname, method);
+    if (matched) {
+      const reqWithParams = new Request(request);
+      (reqWithParams as Request & { params?: Record<string, string | undefined> }).params =
+        matched.params;
+      return matched.route.fetch(reqWithParams);
+    }
+
+    if (options.onNotMatched) {
+      const staticResponse = await options.onNotMatched(request);
+      if (staticResponse) {
+        return staticResponse;
+      }
+    }
+
+    return createContext(request).res.notFound();
+  };
+}
+
+/**
+ * Create an app object with a fetch method (adapter contract).
+ */
+export function createApp(server: HS.Server, options: FetchHandlerOptions = {}) {
+  const fetch = createFetchHandler(server, options);
+  return { fetch, server };
+}

package/src/index.ts

@@ -9,4 +9,15 @@ export {
   HTTPResponseException,
   hyperspanDisableStreaming,
 } from './server';
+export { createFetchHandler, createApp, compileRoutePath } from './fetch-handler';
+export type { FetchHandlerOptions } from './fetch-handler';
+export {
+  setAssetManifest,
+  getAssetManifest,
+  resolveImport,
+  getRouteCss,
+  getImportMap,
+  registerImport,
+} from './client/manifest';
+export type { AssetManifest } from './client/manifest';
 export type { Hyperspan } from './types';

package/src/layout.ts

@@ -1,19 +1,27 @@
 import { html } from '@hyperspan/html';
-import { JS_IMPORT_MAP, buildClientJS } from './client/js';
-import { CSS_PUBLIC_PATH, CSS_ROUTE_MAP } from './client/css';
+import { CSS_PUBLIC_PATH } from './client/css';
+import { getImportMap, getRouteCss, getClientJSFromManifest } from './client/manifest';
 import type { Hyperspan as HS } from './types';
 
-const clientStreamingJS = await buildClientJS(
-  import.meta.resolve('./client/_hs/hyperspan-streaming.client')
-);
+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
  */
 export function hyperspanScriptTags() {
+  const imports = getImportMap();
+  let streamingPath: string;
+  try {
+    streamingPath = streamingClientPath();
+  } catch {
+    streamingPath = '/_hs/js/hyperspan-streaming.client.js';
+  }
+
   return html`
     <script type="importmap">
-      {"imports": ${Object.fromEntries(JS_IMPORT_MAP)}}
+      {"imports": ${imports}}
     </script>
     <script id="hyperspan-streaming-script">
       // [Hyperspan] Streaming - Load the client streaming JS module only when the first chunk is loaded
@@ -25,7 +33,7 @@ export function hyperspanScriptTags() {
           if (!window._hscLoading) {
             window._hscLoading = true;
             const script = document.createElement('script');
-            script.src = '${clientStreamingJS.publicPath}';
+            script.src = '${streamingPath}';
             document.body.appendChild(script);
           }
         };
@@ -39,11 +47,28 @@ export function hyperspanScriptTags() {
  */
 export function hyperspanStyleTags(context: HS.Context) {
   const styleTags = [];
-  const cssImports = context.route.cssImports ?? CSS_ROUTE_MAP.get(context.route.path) ?? [];
+  const cssImports = context.route.cssImports?.length
+    ? context.route.cssImports
+    : getRouteCss(context.route.path);
 
   for (const cssFile of cssImports) {
-    styleTags.push(html` <link rel="stylesheet" href="${CSS_PUBLIC_PATH}/${cssFile}" /> `);
+    // Absolute Vite/dev URLs (e.g. /app/styles/globals.css) are used as-is;
+    // hashed build artifacts are served under /_hs/css/.
+    const href = cssFile.startsWith('/') ? cssFile : `${CSS_PUBLIC_PATH}/${cssFile}`;
+    styleTags.push(html` <link rel="stylesheet" href="${href}" /> `);
   }
 
   return styleTags;
 }
+
+/**
+ * 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>`;
+  }
+}

package/src/server.test.ts

@@ -1,4 +1,4 @@
-import { test, expect, describe } from 'bun:test';
+import { test, expect, describe } from 'vitest';
 import { createRoute, createServer, createContext } from './server';
 import { createAction } from './actions';
 import { html, placeholder } from '@hyperspan/html';
@@ -199,6 +199,17 @@ test('createContext() can get and set cookies', () => {
   }
 });
 
+test('createContext() url() returns a relative URL string', () => {
+  const request = new Request('http://localhost:3000/posts?sort=asc#top');
+  const context = createContext(request);
+
+  expect(typeof context.url()).toBe('string');
+  expect(context.url()).toBe('/posts?sort=asc#top');
+  expect(context.url({ searchParams: { page: 2 } })).toBe('/posts?sort=asc&page=2#top');
+  expect(context.url({ searchParams: { page: 2 } }, { clean: true })).toBe('/posts?page=2');
+  expect(context.req.url.search).toBe('?sort=asc');
+});
+
 test('createContext() merge() function preserves custom headers when using response methods', async () => {
   // Create a request
   const request = new Request('http://localhost:3000/');

package/src/server.ts

@@ -10,7 +10,7 @@ import {
 } from '@hyperspan/html';
 import { isbot } from 'isbot';
 import { executeMiddleware } from './middleware';
-import { parsePath, removeUndefined } from './utils';
+import { buildUrl, parsePath, removeUndefined } from './utils';
 import { Cookies } from './cookies';
 
 import type { Hyperspan as HS } from './types';
@@ -107,6 +107,10 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
 
   const context: HS.Context = {
     vars: {},
+    url: (diff, options) => {
+      const next = buildUrl(url, diff, options);
+      return `${next.pathname}${next.search}${next.hash}`;
+    },
     route: {
       name: route?._config.name || undefined,
       path,

package/src/ssr/mock-dom.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'bun:test';
+import { describe, expect, test } from 'vitest';
 import { MOCK_DOM_MARK, installMockDom, stubElement } from './mock-dom';
 
 describe('stubElement', () => {

package/src/types.ts

@@ -119,11 +119,23 @@ export namespace Hyperspan {
     merge: (response: Response) => Promise<Response>;
   };
 
+  export type UrlDiff = {
+    pathname?: string | null;
+    searchParams?: Record<string, string | number | boolean | null | undefined> | null;
+    hash?: string | null;
+  };
+
+  export type UrlOptions = {
+    /** When true, start from pathname only (drop current query string and hash). */
+    clean?: boolean;
+  };
+
   export interface Context {
     vars: Record<string, any>;
     route: RouteConfig;
     req: HSRequest;
     res: HSResponse;
+    url: (diff?: UrlDiff, options?: UrlOptions) => string;
   }
 
   export type ClientIslandOptions = {

package/src/utils.test.ts

@@ -1,5 +1,5 @@
-import { test, expect, describe } from 'bun:test';
-import { formDataToJSON, parsePath } from './utils';
+import { test, expect, describe } from 'vitest';
+import { buildUrl, formDataToJSON, parsePath } from './utils';
 
 describe('formDataToJSON', () => {
   test('formDataToJSON returns empty object for empty FormData', () => {
@@ -228,3 +228,73 @@ describe('parsePath', () => {
   });
 });
 
+describe('buildUrl', () => {
+  test('returns a new URL and does not mutate the base', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base, { searchParams: { page: 2 } });
+
+    expect(result).toBeInstanceOf(URL);
+    expect(result.pathname).toBe('/posts');
+    expect(result.search).toBe('?sort=asc&page=2');
+    expect(result.hash).toBe('#top');
+    expect(base.search).toBe('?sort=asc');
+    expect(base.hash).toBe('#top');
+  });
+
+  test('adds and overwrites search params', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base, { searchParams: { page: 2 } });
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/posts?sort=asc&page=2#top');
+  });
+
+  test('removes search params with null values', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc&page=1#top');
+    const result = buildUrl(base, { searchParams: { sort: null, page: 3 } });
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/posts?page=3#top');
+  });
+
+  test('clears all search params when searchParams is null', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base, { searchParams: null });
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/posts#top');
+  });
+
+  test('changes pathname and clears hash', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base, { pathname: '/archive', hash: null, searchParams: null });
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/archive');
+  });
+
+  test('preserves relative parts when diff is omitted', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base);
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/posts?sort=asc#top');
+  });
+
+  test('stringifies boolean and number search values', () => {
+    const base = new URL('http://localhost:3000/posts');
+    const result = buildUrl(base, { searchParams: { active: true, page: 2 } });
+
+    expect(result.searchParams.get('active')).toBe('true');
+    expect(result.searchParams.get('page')).toBe('2');
+  });
+
+  test('clean: true drops existing query and hash before applying diff', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base, { searchParams: { page: 2 } }, { clean: true });
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/posts?page=2');
+  });
+
+  test('pathname null resets to root', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc');
+    const result = buildUrl(base, { pathname: null });
+
+    expect(result.pathname).toBe('/');
+  });
+});

package/src/utils.ts

@@ -1,20 +1,36 @@
-import { createHash, randomBytes } from "node:crypto";
+import type { Hyperspan as HS } from './types';
+
+/**
+ * FNV-1a 64-bit hash — portable sync hash for asset IDs (works on Node, Bun, Workers).
+ */
+function fnv1a64(input: string): string {
+  let hash = BigInt('0xcbf29ce484222325');
+  const prime = BigInt('0x100000001b3');
+  const mask = BigInt('0xffffffffffffffff');
+  for (let i = 0; i < input.length; i++) {
+    hash ^= BigInt(input.charCodeAt(i));
+    hash = (hash * prime) & mask;
+  }
+  return hash.toString(16).padStart(16, '0');
+}
 
 export function assetHash(content: string): string {
-  return createHash('md5').update(content).digest('hex');
+  return fnv1a64(content);
 }
 
 export function randomHash(): string {
-  return createHash('md5').update(randomBytes(32).toString('hex')).digest('hex');
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  return fnv1a64(hex);
 }
 
-
 /**
  * Normalize URL path
  * Removes trailing slash and lowercases path
  */
 const ROUTE_SEGMENT_REGEX = /(\[[a-zA-Z_\.]+\])/g;
-export function parsePath(urlPath: string): { path: string, params: string[] } {
+export function parsePath(urlPath: string): { path: string; params: string[] } {
   const params: string[] = [];
   urlPath = urlPath.replace('index', '').replace('.ts', '').replace('.js', '');
 
@@ -46,15 +62,14 @@ export function parsePath(urlPath: string): { path: string, params: string[] } {
 
   // Only lowercase non-param segments (do not lowercase after ':')
   return {
-    path: (
+    path:
       '/' +
       urlPath
         .split('/')
         .map((segment) =>
           segment.startsWith(':') || segment === '*' ? segment : segment.toLowerCase()
         )
-        .join('/')
-    ),
+        .join('/'),
     params,
   };
 }
@@ -75,7 +90,9 @@ export function isValidRoutePath(path: string): boolean {
  *
  * @link https://stackoverflow.com/a/75406413
  */
-export function formDataToJSON(formData: FormData | URLSearchParams): Record<string, string | string[]> {
+export function formDataToJSON(
+  formData: FormData | URLSearchParams
+): Record<string, string | string[]> {
   let object = {};
 
   /**
@@ -170,4 +187,43 @@ export function formDataToJSON(formData: FormData | URLSearchParams): Record<str
  */
 export function removeUndefined(obj: Record<string, any>): Record<string, any> {
   return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
-}
+}
+
+/**
+ * Build a new URL from a base URL and an optional diff.
+ * Does not mutate the base URL.
+ */
+export function buildUrl(base: URL, diff?: HS.UrlDiff, options?: HS.UrlOptions): URL {
+  const next = new URL(base);
+
+  if (options?.clean) {
+    next.search = '';
+    next.hash = '';
+  }
+
+  if (diff?.pathname === null) {
+    next.pathname = '/';
+  } else if (diff?.pathname !== undefined) {
+    next.pathname = diff.pathname;
+  }
+
+  if (diff?.searchParams === null) {
+    next.search = '';
+  } else if (diff?.searchParams !== undefined) {
+    for (const [key, value] of Object.entries(diff.searchParams)) {
+      if (value === null || value === undefined) {
+        next.searchParams.delete(key);
+      } else {
+        next.searchParams.set(key, String(value));
+      }
+    }
+  }
+
+  if (diff?.hash === null) {
+    next.hash = '';
+  } else if (diff?.hash !== undefined) {
+    next.hash = diff.hash;
+  }
+
+  return next;
+}

package/tsconfig.json

@@ -2,7 +2,7 @@
   "compileOnSave": true,
   "compilerOptions": {
     "outDir": "dist",
-    "target": "es2019",
+    "target": "ES2020",
     "lib": ["ESNext", "dom", "dom.iterable"],
     "module": "esnext",
     "moduleResolution": "bundler",