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

package/package.json

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

package/src/client/js.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test, beforeEach } from 'vitest';
-import { mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { render } from '@hyperspan/html';
@@ -8,6 +8,7 @@ import {
   discoverClientExports,
   extractExports,
   getClientJSEntries,
+  registerPathAliases,
   resetClientJSEntriesForTests,
 } from './js';
 
@@ -63,6 +64,31 @@ describe('buildClientJS', () => {
     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');
@@ -84,6 +110,37 @@ describe('buildClientJS', () => {
       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', () => {

package/src/client/js.ts

@@ -1,5 +1,5 @@
 import { readFileSync, existsSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+import { isAbsolute, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { html } from '@hyperspan/html';
 import { assetHash as assetHashFn } from '../utils';
@@ -11,16 +11,54 @@ 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 = {
+  /** Original path/specifier passed to `buildClientJS`. */
+  modulePath: string;
   absPath: string;
   assetHash: string;
   esmName: string;
   publicPath: string;
   exports: string;
   fnArgs: string;
+  type: ClientJSType;
 };
 
 const CLIENT_JS_REGISTRY = Symbol.for('@hyperspan/client-js-entries');
+const PATH_ALIASES = Symbol.for('@hyperspan/path-aliases');
+
+function getPathAliases(): Record<string, string> {
+  const globalAliases = globalThis as {
+    [PATH_ALIASES]?: Record<string, string>;
+  };
+  if (!globalAliases[PATH_ALIASES]) {
+    globalAliases[PATH_ALIASES] = {};
+  }
+  return globalAliases[PATH_ALIASES];
+}
+
+/** Register tsconfig path aliases (`~/` → project root). Called by the Vite plugin. */
+export function registerPathAliases(aliases: Record<string, string>): void {
+  Object.assign(getPathAliases(), aliases);
+}
+
+function resolveWithAliases(specifier: string): string | undefined {
+  const aliases = getPathAliases();
+  const keys = Object.keys(aliases).sort((a, b) => b.length - a.length);
+  for (const key of keys) {
+    if (specifier === key || specifier.startsWith(key)) {
+      const rest = specifier.slice(key.length).replace(/^\//, '');
+      return join(aliases[key], rest);
+    }
+  }
+  return undefined;
+}
 
 function getClientJSRegistry(): Map<string, ClientJSEntry> {
   const globalRegistry = globalThis as {
@@ -61,38 +99,56 @@ export const JS_IMPORT_MAP = {
 };
 
 /**
- * Resolve import.meta.resolve() / file URL / absolute path to a filesystem path.
+ * Prefer a cwd-relative hash so `import.meta.resolve(...)` and `app/client/foo.ts`
+ * produce the same public URL. Absolute paths outside the project stay as-is.
  */
-export function resolveClientModulePath(modulePathResolved: string): string {
-  if (modulePathResolved.startsWith('file://')) {
-    return fileURLToPath(modulePathResolved);
+function stableHashKey(absPath: string): string {
+  const normalized = absPath.replace(/\\/g, '/');
+  if (typeof process !== 'undefined' && typeof process.cwd === 'function') {
+    const rel = relative(process.cwd(), absPath).replace(/\\/g, '/');
+    if (rel && !rel.startsWith('..') && !isAbsolute(rel)) {
+      return rel;
+    }
+  }
+  const marker = '/node_modules/';
+  const idx = normalized.lastIndexOf(marker);
+  if (idx !== -1) {
+    return normalized.slice(idx + marker.length);
   }
-  return modulePathResolved;
+  return normalized;
+}
+
+function toFilePath(modulePath: string): string {
+  return modulePath.startsWith('file://') ? fileURLToPath(modulePath) : modulePath;
 }
 
 /**
- * Resolve a client module path for hashing and bundling.
- * Logical app-relative paths (e.g. app/client/foo.ts) hash consistently across
- * Node and edge runtimes where absolute paths differ.
+ * `import.meta.resolve('./file.ts')` → file URL or absolute path.
+ * `~/app/client/foo.ts` → registered tsconfig alias.
+ * `app/client/foo.ts` → project root.
+ * Relative `./` / `../` paths error — resolve them at the call site.
  */
-export function resolveClientModulePaths(modulePathResolved: string): {
-  hashKey: string;
-  absPath: string;
-} {
-  const resolved = resolveClientModulePath(modulePathResolved).replace(/\\/g, '/');
-
-  if (!isAbsolute(resolved)) {
-    const hashKey = resolved;
-    if (typeof process !== 'undefined' && typeof process.cwd === 'function') {
-      const candidate = join(process.cwd(), hashKey);
-      if (existsSync(candidate)) {
-        return { hashKey, absPath: candidate };
-      }
-    }
-    return { hashKey, absPath: hashKey };
+function resolveClientModule(modulePath: string): { hashKey: string; absPath: string } {
+  if (modulePath.startsWith('file://') || isAbsolute(modulePath)) {
+    const absPath = toFilePath(modulePath);
+    return { hashKey: stableHashKey(absPath), absPath };
   }
 
-  return { hashKey: resolved, absPath: resolved };
+  const specifier = modulePath.replace(/\\/g, '/');
+  if (specifier.startsWith('.')) {
+    throw new Error(
+      `[Hyperspan] buildClientJS(${JSON.stringify(modulePath)}) got a relative path. ` +
+        `Use import.meta.resolve(${JSON.stringify(modulePath)}) at the call site, ` +
+        `or a tsconfig alias like '~/app/client/file.ts'.`
+    );
+  }
+
+  const aliased = resolveWithAliases(specifier);
+  if (aliased) {
+    return { hashKey: specifier, absPath: aliased };
+  }
+
+  return { hashKey: specifier, absPath: join(process.cwd(), specifier) };
 }
 
 export function getClientJSEntries(): ClientJSEntry[] {
@@ -105,20 +161,18 @@ export function getClientJSEntryByEsmName(esmName: string): ClientJSEntry | unde
 
 export function resetClientJSEntriesForTests(): void {
   getClientJSRegistry().clear();
+  const aliases = getPathAliases();
+  for (const key of Object.keys(aliases)) {
+    delete aliases[key];
+  }
 }
 
-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 { hashKey, absPath } = resolveClientModulePaths(modulePathResolved);
+function registerClientJS(
+  modulePathResolved: string,
+  options: BuildClientJSOptions = {}
+): HS.ClientJSBuildResult {
+  const type = options.type ?? 'module';
+  const { hashKey, absPath } = resolveClientModule(modulePathResolved);
   const hash = assetHashFn(hashKey);
   const esmName = `client-${hash}`;
   const publicPath = resolveImport(esmName) ?? `${JS_PUBLIC_PATH}/${esmName}.js`;
@@ -133,7 +187,16 @@ export async function buildClientJS(modulePathResolved: string): Promise<HS.Clie
     fnArgs = discovered.fnArgs;
   }
 
-  registerClientJSEntry({ absPath, assetHash: hash, esmName, publicPath, exports, fnArgs });
+  getClientJSRegistry().set(esmName, {
+    modulePath: modulePathResolved,
+    absPath,
+    assetHash: hash,
+    esmName,
+    publicPath,
+    exports,
+    fnArgs,
+    type,
+  });
   registerImport(esmName, publicPath);
 
   return {
@@ -141,6 +204,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 +236,27 @@ export async function buildClientJS(modulePathResolved: string): Promise<HS.Clie
   };
 }
 
+/**
+ * Register a client JS module for Vite to bundle.
+ * Prefer a tsconfig alias or project-root path (`~/app/client/foo.ts`,
+ * `app/client/foo.ts`). Relative `./` / `../` paths must be resolved at the
+ * call site with `import.meta.resolve('./file.ts')`.
+ */
+export async function buildClientJS(
+  modulePathResolved: string,
+  options: BuildClientJSOptions = {}
+): Promise<HS.ClientJSBuildResult> {
+  return registerClientJS(modulePathResolved, options);
+}
+
+export const streamingClient = registerClientJS(
+  import.meta.resolve('./_hs/hyperspan-streaming.client.ts'),
+  { type: 'iife' }
+);
+export const actionsClient = registerClientJS(
+  import.meta.resolve('./_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

@@ -19,7 +19,8 @@ export {
   getImportMap,
   registerImport,
 } from './client/manifest';
-export { buildClientJS } from './client/js';
+export { buildClientJS, registerPathAliases } 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>`;
 }