@hyperspan/framework 2.0.0-alpha.5 → 2.0.0-alpha.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "2.0.0-alpha.5",
+  "version": "2.0.0-alpha.6",
   "description": "Hyperspan Web Framework",
   "type": "module",
   "main": "src/server.ts",

package/src/client/js.test.ts

@@ -63,6 +63,26 @@ describe('buildClientJS', () => {
     expect(tag).toContain('({ mountPicker }) => mountPicker()');
   });
 
+  test('package export specifiers resolve on disk like app logical paths', async () => {
+    const result = await buildClientJS(
+      '@hyperspan/framework/client/_hs/hyperspan-streaming.client.ts',
+      { type: 'iife' }
+    );
+
+    expect(result.publicPath).toMatch(/^\/_hs\/js\/client-[0-9a-f]{16}\.js$/);
+    expect(getClientJSEntries()[0].type).toBe('iife');
+    expect(getClientJSEntries()[0].absPath).toMatch(/hyperspan-streaming\.client\.ts$/);
+  });
+
+  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');

package/src/client/js.ts

@@ -11,6 +11,13 @@ export { registerImport, resolveImport, getImportMap } from './manifest';
 export const JS_PUBLIC_PATH = '/_hs/js';
 export const JS_ISLAND_PUBLIC_PATH = '/_hs/js/islands';
 
+export type ClientJSType = 'module' | 'iife';
+
+export type BuildClientJSOptions = {
+  /** `iife` emits a classic <script> (runs during HTML streaming). Default `module`. */
+  type?: ClientJSType;
+};
+
 export type ClientJSEntry = {
   absPath: string;
   assetHash: string;
@@ -18,6 +25,7 @@ export type ClientJSEntry = {
   publicPath: string;
   exports: string;
   fnArgs: string;
+  type: ClientJSType;
 };
 
 const CLIENT_JS_REGISTRY = Symbol.for('@hyperspan/client-js-entries');
@@ -89,6 +97,14 @@ export function resolveClientModulePaths(modulePathResolved: string): {
         return { hashKey, absPath: candidate };
       }
     }
+    try {
+      const url = import.meta.resolve(resolved);
+      if (typeof url === 'string' && url.startsWith('file://')) {
+        return { hashKey, absPath: fileURLToPath(url) };
+      }
+    } catch {
+      // Bare specifiers that aren't installed yet still hash stably.
+    }
     return { hashKey, absPath: hashKey };
   }
 
@@ -111,13 +127,11 @@ 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> {
+function registerClientJS(
+  modulePathResolved: string,
+  options: BuildClientJSOptions = {}
+): HS.ClientJSBuildResult {
+  const type = options.type ?? 'module';
   const { hashKey, absPath } = resolveClientModulePaths(modulePathResolved);
   const hash = assetHashFn(hashKey);
   const esmName = `client-${hash}`;
@@ -133,7 +147,7 @@ export async function buildClientJS(modulePathResolved: string): Promise<HS.Clie
     fnArgs = discovered.fnArgs;
   }
 
-  registerClientJSEntry({ absPath, assetHash: hash, esmName, publicPath, exports, fnArgs });
+  registerClientJSEntry({ absPath, assetHash: hash, esmName, publicPath, exports, fnArgs, type });
   registerImport(esmName, publicPath);
 
   return {
@@ -141,6 +155,10 @@ export async function buildClientJS(modulePathResolved: string): Promise<HS.Clie
     esmName,
     publicPath,
     renderScriptTag: (loadScript) => {
+      if (type === 'iife') {
+        return html`<script src="${publicPath}"></script>`;
+      }
+
       const t = typeof loadScript;
 
       if (t === 'string') {
@@ -169,6 +187,28 @@ export async function buildClientJS(modulePathResolved: string): Promise<HS.Clie
   };
 }
 
+/**
+ * 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,
+  options: BuildClientJSOptions = {}
+): Promise<HS.ClientJSBuildResult> {
+  return registerClientJS(modulePathResolved, options);
+}
+
+/** Same `buildClientJS` path an app would use for a package export. */
+export const streamingClient = registerClientJS(
+  '@hyperspan/framework/client/_hs/hyperspan-streaming.client.ts',
+  { type: 'iife' }
+);
+export const actionsClient = registerClientJS(
+  '@hyperspan/framework/client/_hs/hyperspan-actions.client.ts'
+);
+
 /**
  * Discover export names from source or bundled client JS.
  * Prefers bundled `export{...}` form, then common source export patterns.

package/src/client/manifest.ts

@@ -3,11 +3,7 @@ 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;
-  };
+  clients: Record<string, string>;
 };
 
 let _manifest: AssetManifest = {
@@ -67,7 +63,7 @@ export function getClientJSFromManifest(
   moduleId: string,
   _exportNames = 'default'
 ): ClientJSBuildResult {
-  const publicPath = _manifest.clients[moduleId as keyof AssetManifest['clients']];
+  const publicPath = _manifest.clients[moduleId];
   if (!publicPath) {
     throw new Error(
       `[Hyperspan] Client module "${moduleId}" not found in asset manifest. Run hyperspan build or start dev server.`

package/src/index.ts

@@ -20,6 +20,7 @@ export {
   registerImport,
 } from './client/manifest';
 export { buildClientJS } from './client/js';
+export type { BuildClientJSOptions, ClientJSType } from './client/js';
 export { registerRouteModule, registerRouteModules } from './register-routes';
 export type { RouteModuleEntry } from './register-routes';
 export type { AssetManifest } from './client/manifest';

package/src/layout.test.ts

@@ -0,0 +1,12 @@
+import { test, expect } from 'vitest';
+import { render } from '@hyperspan/html';
+import { hyperspanScriptTags } from './layout';
+import { streamingClient } from './client/js';
+
+test('streaming bootstrap injects a classic script so chunks swap in during parse', () => {
+  const html = render(hyperspanScriptTags());
+  expect(html).toContain("document.createElement('script')");
+  expect(html).toContain(`script.src = '${streamingClient.publicPath}'`);
+  expect(html).not.toContain("type = 'module'");
+  expect(html).not.toContain(`import('${streamingClient.publicPath}')`);
+});

package/src/layout.ts

@@ -1,23 +1,20 @@
 import { html } from '@hyperspan/html';
 import { CSS_PUBLIC_PATH } from './client/css';
-import { getImportMap, getRouteCss, getClientJSFromManifest } from './client/manifest';
+import { getImportMap, getRouteCss } from './client/manifest';
+import { actionsClient, streamingClient } from './client/js';
 import type { Hyperspan as HS } from './types';
 
-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
+ * Output the importmap for the client so we can use ESModules on the client to load JS files on demand.
+ *
+ * The streaming client MUST be loaded as a classic <script>, not type=module.
+ * Browsers defer all ESM until the document finishes parsing, which would hold
+ * every streaming chunk until the whole page is done. A dynamically inserted
+ * classic script runs as soon as it downloads.
  */
 export function hyperspanScriptTags() {
   const imports = getImportMap();
-  let streamingPath: string;
-  try {
-    streamingPath = streamingClientPath();
-  } catch {
-    streamingPath = '/_hs/js/hyperspan-streaming.client.js';
-  }
+  const streamingPath = streamingClient.publicPath;
 
   return html`
     <script type="importmap">
@@ -65,10 +62,5 @@ export function hyperspanStyleTags(context: HS.Context) {
  * 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>`;
-  }
+  return html`<script type="module" src="${actionsClient.publicPath}"></script>`;
 }