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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.0-alpha.4",
   "description": "Hyperspan Web Framework",
   "type": "module",
   "main": "src/server.ts",
@@ -27,6 +27,10 @@
       "types": "./src/utils.ts",
       "default": "./src/utils.ts"
     },
+    "./routes": {
+      "types": "./src/register-routes.ts",
+      "default": "./src/register-routes.ts"
+    },
     "./layout": {
       "types": "./src/layout.ts",
       "default": "./src/layout.ts"
@@ -96,7 +100,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@hyperspan/html": "^2.0.0-alpha.2",
+    "@hyperspan/html": "^2.0.0-alpha.4",
     "debug": "^4.4.3",
     "isbot": "^5.1.32",
     "zod": "^4.4.3"

package/src/client/js.test.ts

@@ -62,6 +62,28 @@ describe('buildClientJS', () => {
 
     expect(tag).toContain('({ mountPicker }) => mountPicker()');
   });
+
+  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');
+    mkdirSync(join(dir, 'app/client'), { recursive: true });
+    const logicalPath = join(dir, 'app/client/stats.ts');
+    writeFileSync(logicalPath, `export function mountStats() {}\n`);
+
+    const cwd = process.cwd();
+    process.chdir(dir);
+    try {
+      const first = await buildClientJS('app/client/stats.ts');
+      resetClientJSEntriesForTests();
+      const second = await buildClientJS('app/client/stats.ts');
+      expect(first.esmName).toBe(second.esmName);
+      expect(getClientJSEntries()[0].absPath.replace(/^\/private/, '')).toBe(
+        logicalPath.replace(/^\/private/, '')
+      );
+    } finally {
+      process.chdir(cwd);
+    }
+  });
 });
 
 describe('extractExports', () => {

package/src/client/js.ts

@@ -1,4 +1,5 @@
 import { readFileSync, existsSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { html } from '@hyperspan/html';
 import { assetHash as assetHashFn } from '../utils';
@@ -69,6 +70,31 @@ export function resolveClientModulePath(modulePathResolved: string): string {
   return modulePathResolved;
 }
 
+/**
+ * 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.
+ */
+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 };
+  }
+
+  return { hashKey: resolved, absPath: resolved };
+}
+
 export function getClientJSEntries(): ClientJSEntry[] {
   return [...getClientJSRegistry().values()];
 }
@@ -92,15 +118,16 @@ function registerClientJSEntry(entry: ClientJSEntry): void {
  * and returns URLs / script-tag helpers for the browser.
  */
 export async function buildClientJS(modulePathResolved: string): Promise<HS.ClientJSBuildResult> {
-  const absPath = resolveClientModulePath(modulePathResolved);
-  const hash = assetHashFn(absPath);
+  const { hashKey, absPath } = resolveClientModulePaths(modulePathResolved);
+  const hash = assetHashFn(hashKey);
   const esmName = `client-${hash}`;
   const publicPath = resolveImport(esmName) ?? `${JS_PUBLIC_PATH}/${esmName}.js`;
 
   let exports = '* as _module';
   let fnArgs = '_module';
-  if (existsSync(absPath)) {
-    const source = readFileSync(absPath, 'utf-8');
+  const sourcePath = existsSync(absPath) ? absPath : null;
+  if (sourcePath) {
+    const source = readFileSync(sourcePath, 'utf-8');
     const discovered = discoverClientExports(source);
     exports = discovered.exports;
     fnArgs = discovered.fnArgs;

package/src/index.ts

@@ -20,7 +20,9 @@ export {
   registerImport,
 } from './client/manifest';
 export { buildClientJS } 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 } from './types';
+export type { Hyperspan, ServerCreateContext, DeployTarget } from './types';

package/src/register-routes.ts

@@ -0,0 +1,64 @@
+import { getRunnableRoute } from './server';
+import { isValidRoutePath, parsePath } from './utils';
+import type { AssetManifest } from './client/manifest';
+import type { Hyperspan as HS } from './types';
+
+export type RouteModuleEntry = {
+  file: string;
+  mod: unknown;
+};
+
+/**
+ * Register a route or action module on a Hyperspan server.
+ * Shared by the CLI, Vite plugin, and the generated production server entry.
+ */
+export function registerRouteModule(
+  server: HS.Server,
+  relativeFilePath: string,
+  mod: unknown,
+  manifest?: AssetManifest
+): HS.Route | null {
+  if (!isValidRoutePath(relativeFilePath)) {
+    return null;
+  }
+
+  const route = getRunnableRoute(mod);
+  const parsedPath = parsePath(relativeFilePath);
+
+  let path = parsedPath.path;
+  if (typeof route._path === 'function') {
+    const routePath = route._path();
+    if (routePath && routePath !== '/') path = routePath;
+  }
+
+  if (!route._config.path) {
+    route._config.path = path;
+    if (parsedPath.params.length > 0) {
+      const params = route._config.params ?? {};
+      parsedPath.params.forEach((param) => {
+        params[param] = undefined;
+      });
+      route._config.params = params;
+    }
+  }
+
+  if (manifest) {
+    const cssFiles = manifest.css?.[path] ?? manifest.css?.['*'];
+    if (cssFiles?.length) {
+      route._config.cssImports = cssFiles;
+    }
+  }
+
+  server._routes.push(route);
+  return route;
+}
+
+export function registerRouteModules(
+  server: HS.Server,
+  modules: RouteModuleEntry[],
+  manifest?: AssetManifest
+): void {
+  for (const { file, mod } of modules) {
+    registerRouteModule(server, file, mod, manifest);
+  }
+}

package/src/server.ts

@@ -51,6 +51,7 @@ export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
     appDir: './app',
     publicDir: './public',
     plugins: [],
+    deployTarget: 'node',
     responseOptions: {
       disableStreaming: hyperspanDisableStreaming,
     },

package/src/types.ts

@@ -63,10 +63,25 @@ export namespace Hyperspan {
     disableStreaming?: DisableStreamingFn;
   };
 
+  export type DeployTarget = 'node' | 'bun' | 'cloudflare';
+
+  export type ServerCreateContext = {
+    env: unknown;
+  };
+
   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;
+    /**
+     * Called before the server is created, with platform bindings.
+     * - Vite/`hyperspan dev`: adapter `/dev` `resolveDevEnv(root)` when present; else `process.env`
+     * - Node/Bun production entry: `process.env`
+     * - Cloudflare Workers entry: Worker `env` bindings
+     */
+    beforeServerCreate?: (ctx: ServerCreateContext) => void | Promise<void>;
     // For customizing the routes and adding your own...
     beforeRoutesAdded?: (server: Hyperspan.Server) => void;
     afterRoutesAdded?: (server: Hyperspan.Server) => void;
@@ -387,6 +402,9 @@ export namespace Hyperspan {
   }
 }
 
+export type DeployTarget = Hyperspan.DeployTarget;
+export type ServerCreateContext = Hyperspan.ServerCreateContext;
+
 declare global {
   interface DocumentEventMap {
     'hs:action:before-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;