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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.2",
   "description": "Hyperspan Web Framework",
   "type": "module",
   "main": "src/server.ts",
@@ -96,7 +96,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@hyperspan/html": "^2.0.0-alpha.1",
+    "@hyperspan/html": "^2.0.0-alpha.2",
     "debug": "^4.4.3",
     "isbot": "^5.1.32",
     "zod": "^4.4.3"

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

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

package/src/client/js.test.ts

@@ -1,5 +1,68 @@
-import { describe, expect, test } from 'vitest';
-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', () => {
@@ -14,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 +88,14 @@ describe('extractExports', () => {
     });
   });
 });
+
+describe('discoverClientExports', () => {
+  test('discovers named exports from source', () => {
+    const result = discoverClientExports(
+      `export function mountPicker() {}\nexport const VERSION = 1;`
+    );
+
+    expect(result.exports).toBe('{mountPicker, VERSION}');
+    expect(result.fnArgs).toBe('{mountPicker, VERSION}');
+  });
+});

package/src/client/js.ts

@@ -1,4 +1,7 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { html } from '@hyperspan/html';
+import { assetHash as assetHashFn } from '../utils';
 import { getImportMap, registerImport, resolveImport } from './manifest';
 import type { Hyperspan as HS } from '../types';
 
@@ -7,6 +10,27 @@ export { registerImport, resolveImport, getImportMap } from './manifest';
 export const JS_PUBLIC_PATH = '/_hs/js';
 export const JS_ISLAND_PUBLIC_PATH = '/_hs/js/islands';
 
+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).
  */
@@ -35,40 +59,149 @@ export const JS_IMPORT_MAP = {
   },
 };
 
-const EXPORT_REGEX = /export\{(.*)\}/g;
+/**
+ * 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 (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 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;
+  }
+
+  registerClientJSEntry({ absPath, assetHash: hash, esmName, publicPath, exports, fnArgs });
+  registerImport(esmName, publicPath);
+
+  return {
+    assetHash: hash,
+    esmName,
+    publicPath,
+    renderScriptTag: (loadScript) => {
+      const t = typeof loadScript;
+
+      if (t === 'string') {
+        return html`
+          <script type="module" data-source-id="${hash}">
+            import ${exports} from '${esmName}';
+            (${html.raw(loadScript as string)})(${fnArgs});
+          </script>
+        `;
+      }
+      if (t === 'function') {
+        return html`
+          <script type="module" data-source-id="${hash}">
+            import ${exports} from '${esmName}';
+            (${html.raw(functionToString(loadScript))})(${fnArgs});
+          </script>
+        `;
+      }
+
+      return html`
+        <script type="module" data-source-id="${hash}">
+          import '${esmName}';
+        </script>
+      `;
+    },
+  };
+}
 
 /**
- * @deprecated Use build-time asset manifest via @hyperspan/vite-plugin instead.
- * Kept for compatibility — returns manifest entry if available.
+ * Discover export names from source or bundled client JS.
+ * Prefers bundled `export{...}` form, then common source export patterns.
  */
-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>`,
-    };
+export function discoverClientExports(contents: string): { exports: string; fnArgs: string } {
+  const bundled = extractExports(contents);
+  if (bundled.exports !== '* as _module') {
+    return bundled;
   }
+
+  const names: string[] = [];
+  const seen = new Set<string>();
+
+  for (const re of [
+    /export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g,
+    /export\s+const\s+([A-Za-z_$][\w$]*)/g,
+    /export\s+class\s+([A-Za-z_$][\w$]*)/g,
+    /export\s+let\s+([A-Za-z_$][\w$]*)/g,
+  ]) {
+    let match: RegExpExecArray | null;
+    while ((match = re.exec(contents)) !== null) {
+      if (!seen.has(match[1])) {
+        names.push(match[1]);
+        seen.add(match[1]);
+      }
+    }
+  }
+
+  const exportBlock = /export\s*\{([^}]+)\}/g;
+  let block: RegExpExecArray | null;
+  while ((block = exportBlock.exec(contents)) !== null) {
+    for (const part of block[1].split(',')) {
+      const trimmed = part.trim();
+      if (!trimmed || trimmed.startsWith('type ')) continue;
+      const asMatch = trimmed.match(/^(?:([\w$]+)\s+as\s+)?([\w$]+)$/);
+      const name = asMatch?.[2] ?? trimmed;
+      if (name && name !== 'default' && !seen.has(name)) {
+        names.push(name);
+        seen.add(name);
+      }
+    }
+  }
+
+  if (names.length === 0) {
+    if (/export\s+default\b/.test(contents)) {
+      return { exports: 'DefaultExport', fnArgs: 'DefaultExport' };
+    }
+    return { exports: '* as _module', fnArgs: '_module' };
+  }
+
+  const exports = `{${names.join(', ')}}`;
+  return { exports, fnArgs: exports };
 }
 
 /**
- * Extract the exports from a client JS module
+ * Extract the exports from a client JS module (bundled `export{a as b}` form).
  */
 export function extractExports(contents: string): { exports: string; fnArgs: string } {
-  const exportLine = EXPORT_REGEX.exec(contents);
+  const exportRegex = /export\{(.*)\}/g;
+  const exportLine = exportRegex.exec(contents);
   let exports = '{}';
   let fnArgs = '{}';
 

package/src/index.ts

@@ -19,5 +19,8 @@ export {
   getImportMap,
   registerImport,
 } from './client/manifest';
+export { buildClientJS } from './client/js';
 export type { AssetManifest } from './client/manifest';
+export { renderIsland } from './island';
+export type { IslandRenderOptions } from './island';
 export type { Hyperspan } from './types';

package/src/island.test.ts

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

package/src/island.ts

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

package/src/server.ts

@@ -541,7 +541,7 @@ export async function returnHTMLResponse(
       if (!disableStreaming && (routeContent as HSHtml).asyncContent?.length > 0) {
         return new StreamResponse(
           renderStream(routeContent as HSHtml, {
-            renderChunk: (chunk) => {
+            renderChunk: (chunk: { id: string; content: string }) => {
               // Trailing <!--/hs:chunk--> marks the end of a streaming chunk boundary.
               return html`
                 <template id="${chunk.id}_content">${html.raw(chunk.content)}<!--end--></template>

package/tsconfig.json

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