@hyperspan/framework 1.0.29 → 2.0.0-alpha.2

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.29",
+  "version": "2.0.0-alpha.2",
   "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.2",
     "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/_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,9 +1,73 @@
-import { describe, expect, test } from 'bun:test';
-import { extractExports } from './js';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { render } from '@hyperspan/html';
+import {
+  buildClientJS,
+  discoverClientExports,
+  extractExports,
+  getClientJSEntries,
+  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()');
+  });
+});
 
 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);
 
@@ -13,7 +77,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 +89,13 @@ 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,70 +1,116 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 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;
+
+export type ClientJSEntry = {
+  absPath: string;
+  assetHash: string;
+  esmName: string;
+  publicPath: string;
+  exports: string;
+  fnArgs: string;
+};
+
+const CLIENT_JS_REGISTRY = Symbol.for('@hyperspan/client-js-entries');
+
+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).
+ */
+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]();
+  },
+};
+
+/**
+ * Resolve import.meta.resolve() / file URL / absolute path to a filesystem path.
+ */
+export function resolveClientModulePath(modulePathResolved: string): string {
+  if (modulePathResolved.startsWith('file://')) {
+    return fileURLToPath(modulePathResolved);
+  }
+  return modulePathResolved;
+}
+
+export function getClientJSEntries(): ClientJSEntry[] {
+  return [...getClientJSRegistry().values()];
+}
+
+export function getClientJSEntryByEsmName(esmName: string): ClientJSEntry | undefined {
+  return getClientJSRegistry().get(esmName);
+}
+
+export function resetClientJSEntriesForTests(): void {
+  getClientJSRegistry().clear();
+}
+
+function registerClientJSEntry(entry: ClientJSEntry): void {
+  getClientJSRegistry().set(entry.esmName, entry);
+}
 
 /**
- * Build a client JS module and return a Hyperspan.ClientJSBuildResult object
+ * Build (or look up) a client JS module and return a helper for rendering script tags.
+ *
+ * Never evaluates the module on the server — only registers the path for Vite to bundle
+ * and returns URLs / script-tag helpers for the browser.
  */
 export async function buildClientJS(modulePathResolved: string): Promise<HS.ClientJSBuildResult> {
-  const 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);
-      }
-    }
+  const absPath = resolveClientModulePath(modulePathResolved);
+  const hash = assetHashFn(absPath);
+  const esmName = `client-${hash}`;
+  const publicPath = resolveImport(esmName) ?? `${JS_PUBLIC_PATH}/${esmName}.js`;
+
+  let exports = '* as _module';
+  let fnArgs = '_module';
+  if (existsSync(absPath)) {
+    const source = readFileSync(absPath, 'utf-8');
+    const discovered = discoverClientExports(source);
+    exports = discovered.exports;
+    fnArgs = discovered.fnArgs;
   }
 
-  const { esmName, exports, fnArgs, publicPath } = CLIENT_JS_CACHE.get(assetHash)!;
+  registerClientJSEntry({ absPath, assetHash: hash, esmName, publicPath, exports, fnArgs });
+  registerImport(esmName, publicPath);
 
   return {
-    assetHash,
+    assetHash: hash,
     esmName,
     publicPath,
     renderScriptTag: (loadScript) => {
@@ -72,27 +118,90 @@ export async function buildClientJS(modulePathResolved: string): Promise<HS.Clie
 
       if (t === 'string') {
         return html`
-          <script type="module" data-source-id="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(loadScript as string)})(${fnArgs});</script>
+          <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="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(functionToString(loadScript))})(${fnArgs});</script>
+          <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="${assetHash}">import "${esmName}";</script>
+        <script type="module" data-source-id="${hash}">
+          import '${esmName}';
+        </script>
       `;
+    },
+  };
+}
+
+/**
+ * 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);
+export function extractExports(contents: string): { exports: string; fnArgs: string } {
+  const exportRegex = /export\{(.*)\}/g;
+  const exportLine = exportRegex.exec(contents);
   let exports = '{}';
   let fnArgs = '{}';
 
@@ -111,8 +220,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 +229,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();
+}