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

package/package.json

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

package/src/adapter.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from 'bun:test';
+import type { Adapter } from './types';
+import { createConfig } from './server';
+
+const cloudflare: Adapter = {
+  name: 'cloudflare',
+  createEntry() {
+    return {
+      fetch: async () => new Response('ok'),
+    };
+  },
+};
+
+describe('createConfig deployAdapter', () => {
+  test('defaults to Node when omitted or undefined', () => {
+    expect(createConfig({}).deployAdapter.name).toBe('node');
+    expect(createConfig({ deployAdapter: undefined }).deployAdapter.name).toBe('node');
+  });
+
+  test('keeps an explicit adapter', () => {
+    expect(createConfig({ deployAdapter: cloudflare }).deployAdapter).toBe(cloudflare);
+  });
+});

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,9 +20,18 @@ 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';
 export { renderIsland } from './island';
 export type { IslandRenderOptions } from './island';
-export type { Hyperspan, ServerCreateContext, DeployTarget } from './types';
+export type {
+  Hyperspan,
+  ServerCreateContext,
+  DeployAdapter,
+  Adapter,
+  AdapterAfterBuildContext,
+  DeployEntry,
+  DeployEntryContext,
+} from './types';

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>`;
 }

package/src/server.ts

@@ -12,6 +12,7 @@ import { isbot } from 'isbot';
 import { executeMiddleware } from './middleware';
 import { buildUrl, parsePath, removeUndefined } from './utils';
 import { Cookies } from './cookies';
+import { nodeAdapter } from '@hyperspan/adapter-node';
 
 import type { Hyperspan as HS } from './types';
 
@@ -51,7 +52,7 @@ export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
     appDir: './app',
     publicDir: './public',
     plugins: [],
-    deployTarget: 'node',
+    deployAdapter: config.deployAdapter ?? nodeAdapter(),
     responseOptions: {
       disableStreaming: hyperspanDisableStreaming,
     },
@@ -59,6 +60,7 @@ export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
   return {
     ...defaultConfig,
     ...config,
+    deployAdapter: config.deployAdapter ?? defaultConfig.deployAdapter,
     responseOptions: {
       ...defaultConfig.responseOptions,
       ...config.responseOptions,

package/src/types.ts

@@ -63,7 +63,38 @@ export namespace Hyperspan {
     disableStreaming?: DisableStreamingFn;
   };
 
-  export type DeployTarget = 'node' | 'bun' | 'cloudflare';
+  export type AdapterAfterBuildContext = {
+    root: string;
+    appDir: string;
+    outDir: string;
+  };
+
+  export type DeployEntryContext = {
+    createHyperspanServer: () => Promise<Server>;
+    config: Config;
+  };
+
+  export type DeployEntry = {
+    start?(options?: { port?: number }): unknown | Promise<unknown>;
+    fetch?(request: Request, env?: unknown, ctx?: unknown): Response | Promise<Response>;
+  };
+
+  export type Adapter = {
+    /** Diagnostic name, e.g. `node`, `cloudflare`. */
+    name: string;
+    /**
+     * Native ESM specifier exporting `resolveDevEnv(root)`.
+     * Imported by the Vite plugin so platform SDKs like wrangler load correctly.
+     */
+    devModule?: string;
+    resolveDevEnv?(root: string): Promise<unknown>;
+    /** Platform entry (`start` and/or `fetch`). Called from generated `dist/server.ts`. */
+    createEntry(ctx: DeployEntryContext): DeployEntry;
+    afterBuild?(ctx: AdapterAfterBuildContext): void | Promise<void>;
+  };
+
+  /** Runtime adapter object (`nodeAdapter()`, `cloudflareAdapter()`, …). */
+  export type DeployAdapter = Adapter;
 
   export type ServerCreateContext = {
     env: unknown;
@@ -72,12 +103,16 @@ export namespace Hyperspan {
   export type Config = {
     appDir: string;
     publicDir: string;
-    plugins: Array<Hyperspan.Plugin>; // Loaders for client islands
-    /** Production runtime target. Controls the generated dist/server entry. */
-    deployTarget?: DeployTarget;
+    /** Island plugins (`preactPlugin()`, `sveltePlugin()`, …). */
+    plugins: Array<Hyperspan.Plugin>;
+    /**
+     * Deployment adapter. Pass `cloudflareAdapter()` or `bunAdapter()`.
+     * Omit (or pass `nodeAdapter()`) to deploy to Node.
+     */
+    deployAdapter: Adapter;
     /**
      * Called before the server is created, with platform bindings.
-     * - Vite/`hyperspan dev`: adapter `/dev` `resolveDevEnv(root)` when present; else `process.env`
+     * - Vite/`hyperspan dev`: adapter `devModule` `resolveDevEnv(root)` when present; else `process.env`
      * - Node/Bun production entry: `process.env`
      * - Cloudflare Workers entry: Worker `env` bindings
      */
@@ -402,8 +437,12 @@ export namespace Hyperspan {
   }
 }
 
-export type DeployTarget = Hyperspan.DeployTarget;
+export type DeployAdapter = Hyperspan.DeployAdapter;
 export type ServerCreateContext = Hyperspan.ServerCreateContext;
+export type Adapter = Hyperspan.Adapter;
+export type AdapterAfterBuildContext = Hyperspan.AdapterAfterBuildContext;
+export type DeployEntry = Hyperspan.DeployEntry;
+export type DeployEntryContext = Hyperspan.DeployEntryContext;
 
 declare global {
   interface DocumentEventMap {