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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "2.0.0-alpha.14",
+  "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.14",
+    "@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,8 +1,11 @@
 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,
   discoverClientExports,
@@ -10,6 +13,7 @@ import {
   getClientJSEntries,
   registerPathAliases,
   resetClientJSEntriesForTests,
+  streamingClient,
 } from './js';
 
 describe('buildClientJS', () => {
@@ -17,6 +21,7 @@ describe('buildClientJS', () => {
 
   beforeEach(() => {
     resetClientJSEntriesForTests();
+    setAssetManifest({ imports: {}, css: {}, clients: {} });
     const dir = mkdtempSync(join(tmpdir(), 'hs-client-'));
     clientFile = join(dir, 'picker.ts');
     writeFileSync(
@@ -28,7 +33,7 @@ describe('buildClientJS', () => {
     );
   });
 
-  test('registers entry and returns stable esmName from path hash', async () => {
+  test('registers entry with a stable path identity', async () => {
     const result = await buildClientJS(clientFile);
 
     expect(result.esmName).toMatch(/^client-[0-9a-f]{16}$/);
@@ -37,11 +42,37 @@ describe('buildClientJS', () => {
     expect(getClientJSEntries()[0].absPath).toBe(clientFile);
   });
 
+  test('changing file contents does not change the import-map key', async () => {
+    const first = await buildClientJS(clientFile);
+    writeFileSync(clientFile, `export function mountPicker() { return 2; }\n`);
+    resetClientJSEntriesForTests();
+    const second = await buildClientJS(clientFile);
+    expect(second.esmName).toBe(first.esmName);
+  });
+
+  test('publicPath uses the Vite-hashed URL from the import map', async () => {
+    const result = await buildClientJS(clientFile);
+    const hashed = `/_hs/js/${result.esmName}-a1b2c3d4.js`;
+    setAssetManifest({
+      imports: { [result.esmName]: hashed },
+      css: {},
+      clients: {},
+    });
+    expect(result.publicPath).toBe(hashed);
+  });
+
+  test('absolute path and file URL of the same file share one hash', async () => {
+    const viaAbs = await buildClientJS(clientFile);
+    resetClientJSEntriesForTests();
+    const viaUrl = await buildClientJS(pathToFileURL(clientFile).href);
+    expect(viaUrl.esmName).toBe(viaAbs.esmName);
+  });
+
   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(`import '${result.esmName}'`);
     expect(tag).toContain(`data-source-id="${result.assetHash}"`);
   });
 
@@ -53,7 +84,7 @@ describe('buildClientJS', () => {
       })
     );
 
-    expect(tag).toContain(`import {mountPicker} from "${result.esmName}"`);
+    expect(tag).toContain(`import {mountPicker} from '${result.esmName}'`);
     expect(tag).toContain('mountPicker()');
   });
 
@@ -64,7 +95,33 @@ describe('buildClientJS', () => {
     expect(tag).toContain('({ mountPicker }) => mountPicker()');
   });
 
-  test('import.meta.resolve at the call site registers a real file', 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();
+    const second = await buildClientJS(spec, { type: 'iife' });
+    expect(first.esmName).toBe(second.esmName);
+    expect(first.esmName).toBe(streamingClient.esmName);
+    expect(existsSync(getClientJSEntries()[0].absPath)).toBe(true);
+  });
+
+  // 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',
     });
@@ -73,11 +130,17 @@ describe('buildClientJS', () => {
     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 () => {
@@ -132,14 +195,16 @@ describe('buildClientJS', () => {
     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);
+  // 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(spec);
+    expect(result.esmName).toBe(esmName);
+    expect(result.publicPath).toBe(hashed);
   });
 });
 

package/src/client/js.ts

@@ -21,7 +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;
+  /** 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;
@@ -30,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> {
@@ -60,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>;
@@ -99,22 +132,23 @@ export const JS_IMPORT_MAP = {
 };
 
 /**
- * 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.
+ * 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.
  */
-function stableHashKey(absPath: string): string {
+export function stableClientSourceKey(absPath: string): string {
   const normalized = absPath.replace(/\\/g, '/');
+  const marker = '/node_modules/';
+  const idx = normalized.lastIndexOf(marker);
+  if (idx !== -1) {
+    return normalized.slice(idx + marker.length);
+  }
   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 normalized;
 }
 
@@ -122,33 +156,68 @@ function toFilePath(modulePath: string): string {
   return modulePath.startsWith('file://') ? fileURLToPath(modulePath) : modulePath;
 }
 
+function tryResolveToFile(specifier: string): string | undefined {
+  try {
+    if (typeof import.meta.resolve !== 'function') {
+      return undefined;
+    }
+    const resolved = import.meta.resolve(specifier);
+    if (typeof resolved === 'string' && (resolved.startsWith('file://') || isAbsolute(resolved))) {
+      return toFilePath(resolved);
+    }
+  } catch {
+    // Workers and unresolved package specifiers — Vite already emitted the asset.
+  }
+  return undefined;
+}
+
+function clientPublicPath(esmName: string): string {
+  return resolveImport(esmName) ?? `${JS_PUBLIC_PATH}/${esmName}.js`;
+}
+
 /**
- * `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.
+ * 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 resolveClientModule(modulePath: string): { hashKey: string; absPath: string } {
-  if (modulePath.startsWith('file://') || isAbsolute(modulePath)) {
-    const absPath = toFilePath(modulePath);
-    return { hashKey: stableHashKey(absPath), absPath };
+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);
   if (aliased) {
-    return { hashKey: specifier, absPath: aliased };
+    return aliased;
   }
 
-  return { hashKey: specifier, absPath: 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 {
+  try {
+    if (existsSync(absPath)) {
+      return readFileSync(absPath, 'utf-8');
+    }
+  } catch {
+    // Workers have no filesystem; Vite already bundled from this entry.
+  }
+  return undefined;
 }
 
 export function getClientJSEntries(): ClientJSEntry[] {
@@ -161,6 +230,7 @@ export function getClientJSEntryByEsmName(esmName: string): ClientJSEntry | unde
 
 export function resetClientJSEntriesForTests(): void {
   getClientJSRegistry().clear();
+  getPathIdentityClientJS().length = 0;
   const aliases = getPathAliases();
   for (const key of Object.keys(aliases)) {
     delete aliases[key];
@@ -172,43 +242,79 @@ function registerClientJS(
   options: BuildClientJSOptions = {}
 ): HS.ClientJSBuildResult {
   const type = options.type ?? 'module';
-  const { hashKey, absPath } = resolveClientModule(modulePathResolved);
-  const hash = assetHashFn(hashKey);
+  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 esmName = `client-${hash}`;
-  const publicPath = resolveImport(esmName) ?? `${JS_PUBLIC_PATH}/${esmName}.js`;
-
-  let exports = '* as _module';
-  let fnArgs = '_module';
-  const sourcePath = existsSync(absPath) ? absPath : null;
-  if (sourcePath) {
-    const source = readFileSync(sourcePath, 'utf-8');
-    const discovered = discoverClientExports(source);
-    exports = discovered.exports;
-    fnArgs = discovered.fnArgs;
+
+  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;
   }
 
-  getClientJSRegistry().set(esmName, {
+  const entry: ClientJSEntry = {
     modulePath: modulePathResolved,
-    absPath,
+    get absPath() {
+      return currentAbsPath();
+    },
+    identityKey,
+    identityFromPath,
     assetHash: hash,
     esmName,
-    publicPath,
-    exports,
-    fnArgs,
+    get publicPath() {
+      return clientPublicPath(esmName);
+    },
+    get exports() {
+      return currentExports().exports;
+    },
+    get fnArgs() {
+      return currentExports().fnArgs;
+    },
     type,
-  });
-  registerImport(esmName, publicPath);
+  };
+  getClientJSRegistry().set(esmName, entry);
+  registerImport(esmName, entry.publicPath);
 
   return {
     assetHash: hash,
     esmName,
-    publicPath,
+    get publicPath() {
+      return clientPublicPath(esmName);
+    },
     renderScriptTag: (loadScript) => {
       if (type === 'iife') {
-        return html`<script src="${publicPath}"></script>`;
+        return html`<script src="${clientPublicPath(esmName)}"></script>`;
       }
 
       const t = typeof loadScript;
+      const { exports, fnArgs } = currentExports();
 
       if (t === 'string') {
         return html`
@@ -238,9 +344,12 @@ function registerClientJS(
 
 /**
  * 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')`.
+ * 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,
@@ -249,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

@@ -16,7 +16,11 @@ let _manifest: AssetManifest = {
  * Set the build-time asset manifest (called by Vite plugin or build step).
  */
 export function setAssetManifest(manifest: AssetManifest): void {
-  _manifest = manifest;
+  _manifest = {
+    imports: manifest.imports ?? {},
+    css: manifest.css ?? {},
+    clients: manifest.clients ?? {},
+  };
 }
 
 /**

package/src/types.ts

@@ -430,7 +430,7 @@ export namespace Hyperspan {
    * Client JS Module = ESM Module + Public Path + Render Script Tag
    */
   export type ClientJSBuildResult = {
-    assetHash: string; // Asset hash of the module path
+    assetHash: string; // Identity of the resolved path; production file hash comes from Vite
     esmName: string; // Filename of the built JavaScript file without the extension
     publicPath: string; // Full public path of the built JavaScript file
     /**