@hyperspan/framework 1.0.29 → 2.0.0-alpha.13

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.29",
+  "version": "2.0.0-alpha.13",
   "description": "Hyperspan Web Framework",
+  "type": "module",
   "main": "src/server.ts",
   "types": "src/server.ts",
   "public": true,
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "alpha"
   },
   "exports": {
     ".": {
@@ -25,10 +27,18 @@
       "types": "./src/utils.ts",
       "default": "./src/utils.ts"
     },
+    "./routes": {
+      "types": "./src/register-routes.ts",
+      "default": "./src/register-routes.ts"
+    },
     "./layout": {
       "types": "./src/layout.ts",
       "default": "./src/layout.ts"
     },
+    "./dev-bindings": {
+      "types": "./src/dev-bindings.ts",
+      "default": "./src/dev-bindings.ts"
+    },
     "./client/css": {
       "types": "./src/client/css.ts",
       "default": "./src/client/css.ts"
@@ -37,6 +47,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 +62,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 +78,7 @@
   "keywords": [
     "framework",
     "node",
-    "bun",
+    "vite",
     "web framework",
     "javascript",
     "typescript",
@@ -71,17 +94,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": "^4.1.10"
   },
   "dependencies": {
-    "@hyperspan/html": "^1.0.1",
+    "@hyperspan/html": "^2.0.0-alpha.13",
     "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/adapter.test.ts

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

package/src/client/_hs/hyperspan-actions.client.ts

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

package/src/client/js.test.ts

@@ -1,9 +1,152 @@
-import { describe, expect, test } from 'bun:test';
-import { extractExports } from './js';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { mkdtempSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { render } from '@hyperspan/html';
+import {
+  buildClientJS,
+  discoverClientExports,
+  extractExports,
+  getClientJSEntries,
+  registerPathAliases,
+  resetClientJSEntriesForTests,
+} from './js';
+
+describe('buildClientJS', () => {
+  let clientFile: string;
+
+  beforeEach(() => {
+    resetClientJSEntriesForTests();
+    const dir = mkdtempSync(join(tmpdir(), 'hs-client-'));
+    clientFile = join(dir, 'picker.ts');
+    writeFileSync(
+      clientFile,
+      `export function mountPicker() {
+  document.getElementById('picker')?.classList.add('ready');
+}
+`
+    );
+  });
+
+  test('registers entry and returns stable esmName from path hash', async () => {
+    const result = await buildClientJS(clientFile);
+
+    expect(result.esmName).toMatch(/^client-[0-9a-f]{16}$/);
+    expect(result.publicPath).toBe(`/_hs/js/${result.esmName}.js`);
+    expect(getClientJSEntries()).toHaveLength(1);
+    expect(getClientJSEntries()[0].absPath).toBe(clientFile);
+  });
+
+  test('renderScriptTag with no loader uses import map key', async () => {
+    const result = await buildClientJS(clientFile);
+    const tag = render(result.renderScriptTag());
+
+    expect(tag).toContain(`import "${result.esmName}"`);
+    expect(tag).toContain(`data-source-id="${result.assetHash}"`);
+  });
+
+  test('renderScriptTag with function inlines bootstrap code', async () => {
+    const result = await buildClientJS(clientFile);
+    const tag = render(
+      result.renderScriptTag(({ mountPicker }: { mountPicker: () => void }) => {
+        mountPicker();
+      })
+    );
+
+    expect(tag).toContain(`import {mountPicker} from "${result.esmName}"`);
+    expect(tag).toContain('mountPicker()');
+  });
+
+  test('renderScriptTag with string inlines bootstrap code', async () => {
+    const result = await buildClientJS(clientFile);
+    const tag = render(result.renderScriptTag('({ mountPicker }) => mountPicker()'));
+
+    expect(tag).toContain('({ mountPicker }) => mountPicker()');
+  });
+
+  test('import.meta.resolve at the call site registers a real file', async () => {
+    const result = await buildClientJS(import.meta.resolve('./_hs/hyperspan-streaming.client.ts'), {
+      type: 'iife',
+    });
+
+    expect(result.publicPath).toMatch(/^\/_hs\/js\/client-[0-9a-f]{16}\.js$/);
+    expect(getClientJSEntries()[0].type).toBe('iife');
+    expect(existsSync(getClientJSEntries()[0].absPath)).toBe(true);
+    expect(getClientJSEntries()[0].absPath).toMatch(/hyperspan-streaming\.client\.ts$/);
+  });
+
+  test('relative paths must be resolved at the call site', async () => {
+    await expect(buildClientJS('../client/picker.ts')).rejects.toThrow(/import\.meta\.resolve/);
+    await expect(buildClientJS('./picker.ts')).rejects.toThrow(/import\.meta\.resolve/);
+  });
+
+  test('type iife renders a classic script tag', async () => {
+    const result = await buildClientJS(clientFile, { type: 'iife' });
+    const tag = render(result.renderScriptTag());
+
+    expect(tag).toContain(`<script src="${result.publicPath}"`);
+    expect(tag).not.toContain('type="module"');
+    expect(getClientJSEntries()[0].type).toBe('iife');
+  });
+
+  test('logical app-relative paths hash consistently and resolve on disk when present', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'hs-client-logical-'));
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(join(dir, 'app/client'), { recursive: true });
+    const logicalPath = join(dir, 'app/client/stats.ts');
+    writeFileSync(logicalPath, `export function mountStats() {}\n`);
+
+    const cwd = process.cwd();
+    process.chdir(dir);
+    try {
+      const first = await buildClientJS('app/client/stats.ts');
+      resetClientJSEntriesForTests();
+      const second = await buildClientJS('app/client/stats.ts');
+      expect(first.esmName).toBe(second.esmName);
+      expect(getClientJSEntries()[0].absPath.replace(/^\/private/, '')).toBe(
+        logicalPath.replace(/^\/private/, '')
+      );
+    } finally {
+      process.chdir(cwd);
+    }
+  });
+
+  test('tsconfig aliases resolve inside buildClientJS without import.meta.resolve', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'hs-client-alias-'));
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(join(dir, 'app/client'), { recursive: true });
+    const absPath = join(dir, 'app/client/stats.ts');
+    writeFileSync(absPath, `export function mountStats() {}\n`);
+
+    registerPathAliases({ '~/': `${dir}/`, '~': dir });
+
+    const result = await buildClientJS('~/app/client/stats.ts');
+    expect(getClientJSEntries()[0].absPath.replace(/^\/private/, '')).toBe(
+      absPath.replace(/^\/private/, '')
+    );
+    expect(getClientJSEntries()[0].modulePath).toBe('~/app/client/stats.ts');
+
+    resetClientJSEntriesForTests();
+    registerPathAliases({ '~/': `${dir}/`, '~': dir });
+    const second = await buildClientJS('~/app/client/stats.ts');
+    expect(second.esmName).toBe(result.esmName);
+  });
+
+  test('aliased specifiers keep a stable hash when the file is missing', async () => {
+    registerPathAliases({ '~/': '/definitely-missing-hyperspan-root/' });
+    const first = await buildClientJS('~/app/client/missing.ts');
+    resetClientJSEntriesForTests();
+    registerPathAliases({ '~/': '/definitely-missing-hyperspan-root/' });
+    const second = await buildClientJS('~/app/client/missing.ts');
+    expect(first.esmName).toBe(second.esmName);
+    expect(existsSync(getClientJSEntries()[0].absPath)).toBe(false);
+  });
+});
 
 describe('extractExports', () => {
   test('extracts aliased export from bundled JS content', () => {
-    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 +156,7 @@ describe('extractExports', () => {
     });
   });
 
-  test('returns empty exports when none found', () => {
+  test('returns namespace export when none found', () => {
     const contents = 'function noop(){return 1}const value=2;';
 
     const result = extractExports(contents);
@@ -25,3 +168,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}');
+  });
+});