@hyperspan/framework 2.0.0-alpha.15 → 2.0.0-alpha.16

package/package.json

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

package/src/client/js.test.ts

@@ -1,9 +1,10 @@
 import { describe, expect, test, beforeEach } from 'vitest';
-import { mkdtempSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { render } from '@hyperspan/html';
+import { assetHash } from '../utils';
 import { setAssetManifest } from './manifest';
 import {
   buildClientJS,
@@ -12,7 +13,6 @@ import {
   getClientJSEntries,
   registerPathAliases,
   resetClientJSEntriesForTests,
-  stableClientSourceKey,
   streamingClient,
 } from './js';
 
@@ -21,7 +21,7 @@ describe('buildClientJS', () => {
 
   beforeEach(() => {
     resetClientJSEntriesForTests();
-    setAssetManifest({ imports: {}, css: {}, clients: {}, clientSources: {} });
+    setAssetManifest({ imports: {}, css: {}, clients: {} });
     const dir = mkdtempSync(join(tmpdir(), 'hs-client-'));
     clientFile = join(dir, 'picker.ts');
     writeFileSync(
@@ -57,7 +57,6 @@ describe('buildClientJS', () => {
       imports: { [result.esmName]: hashed },
       css: {},
       clients: {},
-      clientSources: {},
     });
     expect(result.publicPath).toBe(hashed);
   });
@@ -96,7 +95,7 @@ describe('buildClientJS', () => {
     expect(tag).toContain('({ mountPicker }) => mountPicker()');
   });
 
-  test('package specifiers and import.meta.resolve of the same file share one hash', async () => {
+  test('package specifiers hash the same wherever the package is installed', async () => {
     const spec = '@hyperspan/framework/client/_hs/hyperspan-streaming.client.ts';
     const first = await buildClientJS(spec, { type: 'iife' });
     resetClientJSEntriesForTests();
@@ -106,21 +105,42 @@ describe('buildClientJS', () => {
     expect(existsSync(getClientJSEntries()[0].absPath)).toBe(true);
   });
 
-  test('import.meta.resolve at the call site registers a real file', async () => {
+  // workerd rejects `import.meta.resolve` after bundling, which crashed Worker startup.
+  test('builtins register without resolving a path at module load', () => {
+    const src = readFileSync(new URL('./js.ts', import.meta.url), 'utf8');
+    const registrations = src.slice(src.indexOf('export const streamingClient'));
+
+    expect(registrations).toContain(
+      "'@hyperspan/framework/client/_hs/hyperspan-streaming.client.ts'"
+    );
+    expect(registrations).toContain(
+      "'@hyperspan/framework/client/_hs/hyperspan-actions.client.ts'"
+    );
+    expect(registrations).not.toContain('import.meta.resolve');
+  });
+
+  // Valid on Node/Bun, which can resolve paths at runtime. Flagged as a path identity
+  // so a Worker build can reject it instead of serving a 404 for a script in dist/.
+  test('import.meta.resolve at the call site registers a real file, flagged as a path identity', async () => {
     const result = await buildClientJS(import.meta.resolve('./_hs/hyperspan-streaming.client.ts'), {
       type: 'iife',
     });
 
-    expect(result.esmName).toBe(streamingClient.esmName);
     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$/);
+    expect(getClientJSEntries()[0].identityFromPath).toBe(true);
+  });
+
+  test('specifier identities are not flagged as path identities', async () => {
+    await buildClientJS('@hyperspan/framework/client/_hs/hyperspan-actions.client.ts');
+    expect(getClientJSEntries()[0].identityFromPath).toBe(false);
   });
 
-  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('relative paths are rejected in favor of an alias', async () => {
+    await expect(buildClientJS('../client/picker.ts')).rejects.toThrow(/tsconfig alias/);
+    await expect(buildClientJS('./picker.ts')).rejects.toThrow(/tsconfig alias/);
   });
 
   test('type iife renders a classic script tag', async () => {
@@ -175,19 +195,16 @@ describe('buildClientJS', () => {
     expect(second.esmName).toBe(result.esmName);
   });
 
-  test('missing files use a build-time hash from clientSources', async () => {
-    const ghost = '/definitely-missing-hyperspan-root/app/client/gone.ts';
-    const builtName = 'client-from-build0123';
-    setAssetManifest({
-      imports: { [builtName]: `/_hs/js/${builtName}.js` },
-      css: {},
-      clients: {},
-      clientSources: { [stableClientSourceKey(ghost)]: builtName },
-    });
+  // A Worker has no filesystem: registration must not read the source to get a URL.
+  test('missing source files still resolve to the built URL', async () => {
+    const spec = 'app/client/gone.ts';
+    const esmName = `client-${assetHash(spec)}`;
+    const hashed = `/_hs/js/${esmName}-a1b2c3d4.js`;
+    setAssetManifest({ imports: { [esmName]: hashed }, css: {}, clients: {} });
 
-    const result = await buildClientJS(ghost);
-    expect(result.esmName).toBe(builtName);
-    expect(result.publicPath).toBe(`/_hs/js/${builtName}.js`);
+    const result = await buildClientJS(spec);
+    expect(result.esmName).toBe(esmName);
+    expect(result.publicPath).toBe(hashed);
   });
 });
 

package/src/client/js.ts

@@ -3,7 +3,7 @@ import { isAbsolute, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { html } from '@hyperspan/html';
 import { assetHash as assetHashFn } from '../utils';
-import { getAssetManifest, getImportMap, registerImport, resolveImport } from './manifest';
+import { getImportMap, registerImport, resolveImport } from './manifest';
 import type { Hyperspan as HS } from '../types';
 
 export { registerImport, resolveImport, getImportMap } from './manifest';
@@ -21,10 +21,17 @@ export type BuildClientJSOptions = {
 export type ClientJSEntry = {
   /** Original path/specifier passed to `buildClientJS`. */
   modulePath: string;
+  /** Resolved file path. Lazy — only a build/dev tool with a filesystem reads this. */
   absPath: string;
-  /** Identities used to look up a stable import-map key when the source file is gone (Workers). */
-  sourceKeys: string[];
-  /** Identity hash of the resolved path (not file contents). */
+  /** Runtime-stable identity of the module. Same value on Vite, Node, and Workers. */
+  identityKey: string;
+  /**
+   * Identity came from a filesystem path rather than a logical specifier. Such an
+   * identity only matches at runtime on a runtime that can resolve paths, so it is
+   * not portable to a Worker.
+   */
+  identityFromPath: boolean;
+  /** Identity hash of `identityKey` (not of file contents). */
   assetHash: string;
   esmName: string;
   publicPath: string;
@@ -33,7 +40,13 @@ export type ClientJSEntry = {
   type: ClientJSType;
 };
 
+export type ClientJSPathIdentity = {
+  modulePath: string;
+  identityKey: string;
+};
+
 const CLIENT_JS_REGISTRY = Symbol.for('@hyperspan/client-js-entries');
+const CLIENT_JS_PATH_IDENTITIES = Symbol.for('@hyperspan/client-js-path-identities');
 const PATH_ALIASES = Symbol.for('@hyperspan/path-aliases');
 
 function getPathAliases(): Record<string, string> {
@@ -63,6 +76,23 @@ function resolveWithAliases(specifier: string): string | undefined {
   return undefined;
 }
 
+/**
+ * Client scripts registered from a path rather than a logical specifier, kept outside
+ * the registry. A path identity can coincide with the equivalent project-relative
+ * specifier (`file:///proj/app/client/x.ts` and `app/client/x.ts` share one identity),
+ * so the registry entry may be replaced by whichever form registered last. Deploy
+ * checks need the record regardless of that order.
+ */
+export function getPathIdentityClientJS(): ClientJSPathIdentity[] {
+  const globalPathIdentities = globalThis as {
+    [CLIENT_JS_PATH_IDENTITIES]?: ClientJSPathIdentity[];
+  };
+  if (!globalPathIdentities[CLIENT_JS_PATH_IDENTITIES]) {
+    globalPathIdentities[CLIENT_JS_PATH_IDENTITIES] = [];
+  }
+  return globalPathIdentities[CLIENT_JS_PATH_IDENTITIES];
+}
+
 function getClientJSRegistry(): Map<string, ClientJSEntry> {
   const globalRegistry = globalThis as {
     [CLIENT_JS_REGISTRY]?: Map<string, ClientJSEntry>;
@@ -102,9 +132,9 @@ export const JS_IMPORT_MAP = {
 };
 
 /**
- * File URLs from `import.meta.resolve` must not use a cwd-relative pnpm path —
- * that changes between install layouts and Workers. Prefer the path after the
- * last `node_modules/` so published packages stay stable.
+ * File paths must not become a cwd-relative pnpm path — that changes between
+ * install layouts and Workers. Prefer the path after the last `node_modules/`
+ * so published packages stay stable.
  */
 export function stableClientSourceKey(absPath: string): string {
   const normalized = absPath.replace(/\\/g, '/');
@@ -146,24 +176,27 @@ function clientPublicPath(esmName: string): string {
 }
 
 /**
- * Resolve to a real file path. The import-map key hashes `stableClientSourceKey(absPath)`
- * so `import.meta.resolve()`, aliases, and package specifiers of the same file share
- * one key. Vite/esbuild attach a content hash to the emitted filename; `publicPath`
- * reads that from the asset manifest. Relative `./` / `../` paths error — resolve
- * them at the call site.
+ * Identity of a client module, computed with string math only — no filesystem and
+ * no `import.meta.resolve`. Workers can therefore build the same identity (and so
+ * the same public URL) that Vite used at build time.
+ *
+ * A logical specifier (package export, tsconfig alias, project-root path) is its
+ * own identity. File URLs and absolute paths fall back to a path identity.
  */
-function resolveClientAbsPath(modulePath: string): string {
-  if (modulePath.startsWith('file://') || isAbsolute(modulePath)) {
-    return toFilePath(modulePath);
+function clientIdentityKey(specifier: string): string {
+  if (specifier.startsWith('file://') || isAbsolute(specifier)) {
+    return stableClientSourceKey(toFilePath(specifier));
   }
+  return specifier;
+}
 
-  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'.`
-    );
+/**
+ * Resolve an identity to a real file path. Only build/dev tooling calls this, so
+ * `import.meta.resolve` never runs during module load on a Worker.
+ */
+function resolveClientAbsPath(specifier: string): string {
+  if (specifier.startsWith('file://') || isAbsolute(specifier)) {
+    return toFilePath(specifier);
   }
 
   const aliased = resolveWithAliases(specifier);
@@ -171,7 +204,9 @@ function resolveClientAbsPath(modulePath: string): string {
     return aliased;
   }
 
-  return tryResolveToFile(specifier) ?? join(process.cwd(), specifier);
+  const cwd =
+    typeof process !== 'undefined' && typeof process.cwd === 'function' ? process.cwd() : '';
+  return tryResolveToFile(specifier) ?? (cwd ? join(cwd, specifier) : specifier);
 }
 
 function readClientSource(absPath: string): string | undefined {
@@ -185,121 +220,105 @@ function readClientSource(absPath: string): string | undefined {
   return undefined;
 }
 
-function clientSourceKeys(modulePath: string, absPath: string): string[] {
-  const keys = new Set<string>([stableClientSourceKey(absPath), modulePath.replace(/\\/g, '/')]);
-  if (modulePath.startsWith('file://')) {
-    keys.add(toFilePath(modulePath));
-  }
-  return [...keys];
-}
-
-function resolveEsmName(sourceKeys: string[], fallbackHash: string): string {
-  const sources = getAssetManifest().clientSources;
-  if (sources) {
-    for (const key of sourceKeys) {
-      if (sources[key]) {
-        return sources[key];
-      }
-    }
-  }
-  return `client-${fallbackHash}`;
-}
-
 export function getClientJSEntries(): ClientJSEntry[] {
   return [...getClientJSRegistry().values()];
 }
 
 export function getClientJSEntryByEsmName(esmName: string): ClientJSEntry | undefined {
-  for (const entry of getClientJSRegistry().values()) {
-    if (currentEsmName(entry) === esmName) {
-      return entry;
-    }
-  }
-  return undefined;
-}
-
-export function getClientJSSourceMap(): Record<string, string> {
-  const map: Record<string, string> = {};
-  for (const entry of getClientJSEntries()) {
-    const esmName = currentEsmName(entry);
-    for (const key of entry.sourceKeys) {
-      map[key] = esmName;
-    }
-  }
-  return map;
+  return getClientJSRegistry().get(esmName);
 }
 
 export function resetClientJSEntriesForTests(): void {
   getClientJSRegistry().clear();
+  getPathIdentityClientJS().length = 0;
   const aliases = getPathAliases();
   for (const key of Object.keys(aliases)) {
     delete aliases[key];
   }
 }
 
-function currentEsmName(entry: ClientJSEntry): string {
-  return resolveEsmName(entry.sourceKeys, entry.assetHash);
-}
-
 function registerClientJS(
   modulePathResolved: string,
   options: BuildClientJSOptions = {}
 ): HS.ClientJSBuildResult {
   const type = options.type ?? 'module';
-  const absPath = resolveClientAbsPath(modulePathResolved);
-  const sourceKeys = clientSourceKeys(modulePathResolved, absPath);
-  const identityKey = stableClientSourceKey(absPath);
+  const specifier = modulePathResolved.replace(/\\/g, '/');
+  if (specifier.startsWith('.')) {
+    throw new Error(
+      `[Hyperspan] buildClientJS(${JSON.stringify(modulePathResolved)}) got a relative path, ` +
+        `which has no stable identity across dev, build, and deploy. Use a tsconfig alias ` +
+        `like '~/app/client/file.ts' — the build resolves it, and every runtime (including ` +
+        `Workers, which cannot resolve paths) matches it in the asset manifest.`
+    );
+  }
+
+  const identityKey = clientIdentityKey(specifier);
+  const identityFromPath = identityKey !== specifier;
   const hash = assetHashFn(identityKey);
-  const source = readClientSource(absPath);
-
-  let exports = '* as _module';
-  let fnArgs = '_module';
-  if (source) {
-    const discovered = discoverClientExports(source);
-    exports = discovered.exports;
-    fnArgs = discovered.fnArgs;
+  const esmName = `client-${hash}`;
+
+  if (identityFromPath) {
+    getPathIdentityClientJS().push({ modulePath: modulePathResolved, identityKey });
+  }
+
+  let absPath: string | undefined;
+  let discovered: { exports: string; fnArgs: string } | undefined;
+
+  // Both are lazy: a Worker renders script tags without a filesystem, and
+  // resolving there would need `import.meta.resolve`, which workerd may reject.
+  function currentAbsPath(): string {
+    return (absPath ??= resolveClientAbsPath(specifier));
+  }
+  function currentExports(): { exports: string; fnArgs: string } {
+    if (!discovered) {
+      const source = readClientSource(currentAbsPath());
+      discovered = source
+        ? discoverClientExports(source)
+        : { exports: '* as _module', fnArgs: '_module' };
+    }
+    return discovered;
   }
 
   const entry: ClientJSEntry = {
     modulePath: modulePathResolved,
-    absPath,
-    sourceKeys,
-    assetHash: hash,
-    get esmName() {
-      return currentEsmName(entry);
+    get absPath() {
+      return currentAbsPath();
     },
+    identityKey,
+    identityFromPath,
+    assetHash: hash,
+    esmName,
     get publicPath() {
-      return clientPublicPath(currentEsmName(entry));
+      return clientPublicPath(esmName);
+    },
+    get exports() {
+      return currentExports().exports;
+    },
+    get fnArgs() {
+      return currentExports().fnArgs;
     },
-    exports,
-    fnArgs,
     type,
   };
-  getClientJSRegistry().set(identityKey, entry);
-  registerImport(entry.esmName, entry.publicPath);
+  getClientJSRegistry().set(esmName, entry);
+  registerImport(esmName, entry.publicPath);
 
   return {
-    get assetHash() {
-      return currentEsmName(entry).replace(/^client-/, '');
-    },
-    get esmName() {
-      return currentEsmName(entry);
-    },
+    assetHash: hash,
+    esmName,
     get publicPath() {
-      return clientPublicPath(currentEsmName(entry));
+      return clientPublicPath(esmName);
     },
     renderScriptTag: (loadScript) => {
-      const esmName = currentEsmName(entry);
-      const tagHash = esmName.replace(/^client-/, '');
       if (type === 'iife') {
         return html`<script src="${clientPublicPath(esmName)}"></script>`;
       }
 
       const t = typeof loadScript;
+      const { exports, fnArgs } = currentExports();
 
       if (t === 'string') {
         return html`
-          <script type="module" data-source-id="${tagHash}">
+          <script type="module" data-source-id="${hash}">
             import ${exports} from '${esmName}';
             (${html.raw(loadScript as string)})(${fnArgs});
           </script>
@@ -307,7 +326,7 @@ function registerClientJS(
       }
       if (t === 'function') {
         return html`
-          <script type="module" data-source-id="${tagHash}">
+          <script type="module" data-source-id="${hash}">
             import ${exports} from '${esmName}';
             (${html.raw(functionToString(loadScript))})(${fnArgs});
           </script>
@@ -315,7 +334,7 @@ function registerClientJS(
       }
 
       return html`
-        <script type="module" data-source-id="${tagHash}">
+        <script type="module" data-source-id="${hash}">
           import '${esmName}';
         </script>
       `;
@@ -325,9 +344,12 @@ function registerClientJS(
 
 /**
  * Register a client JS module for Vite to bundle.
- * Prefer `import.meta.resolve('./file.ts')`, a tsconfig alias, or a project-root path.
- * The import-map key is a stable identity of the resolved file. Vite/esbuild content-hash
- * the emitted filename; `publicPath` uses that URL from the asset manifest when present.
+ * Prefer a package export, tsconfig alias, or project-root path
+ * (`@scope/pkg/file.ts`, `~/app/client/foo.ts`, `app/client/foo.ts`) — those need no
+ * filesystem lookup, so Vite, Node, and Workers all derive the same public URL.
+ * Vite/esbuild content-hash the emitted filename; `publicPath` reads that URL from
+ * the asset manifest. Relative `./` / `../` paths must be resolved at the call site
+ * with `import.meta.resolve('./file.ts')`.
  */
 export async function buildClientJS(
   modulePathResolved: string,
@@ -336,12 +358,14 @@ export async function buildClientJS(
   return registerClientJS(modulePathResolved, options);
 }
 
+// Registered through the same public API an app uses. Package-export specifiers keep
+// module load free of `import.meta.resolve`, which workerd rejects after bundling.
 export const streamingClient = registerClientJS(
-  import.meta.resolve('./_hs/hyperspan-streaming.client.ts'),
+  '@hyperspan/framework/client/_hs/hyperspan-streaming.client.ts',
   { type: 'iife' }
 );
 export const actionsClient = registerClientJS(
-  import.meta.resolve('./_hs/hyperspan-actions.client.ts')
+  '@hyperspan/framework/client/_hs/hyperspan-actions.client.ts'
 );
 
 /**

package/src/client/manifest.ts

@@ -4,15 +4,12 @@ export type AssetManifest = {
   imports: Record<string, string>;
   css: Record<string, string[]>;
   clients: Record<string, string>;
-  /** Resolved path / original specifier → import-map key (`client-{id}`). */
-  clientSources?: Record<string, string>;
 };
 
 let _manifest: AssetManifest = {
   imports: {},
   css: {},
   clients: {},
-  clientSources: {},
 };
 
 /**
@@ -23,7 +20,6 @@ export function setAssetManifest(manifest: AssetManifest): void {
     imports: manifest.imports ?? {},
     css: manifest.css ?? {},
     clients: manifest.clients ?? {},
-    clientSources: { ...(manifest.clientSources ?? {}) },
   };
 }