@hyperspan/framework 1.0.0-alpha.13 → 1.0.0-alpha.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.15",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",
@@ -37,10 +37,6 @@
       "types": "./src/client/js.ts",
       "default": "./src/client/js.ts"
     },
-    "./plugins": {
-      "types": "./src/plugins.ts",
-      "default": "./src/plugins.ts"
-    },
     "./actions": {
       "types": "./src/actions.ts",
       "default": "./src/actions.ts"
@@ -77,6 +73,7 @@
   },
   "dependencies": {
     "@hyperspan/html": "^1.0.0-alpha",
+    "isbot": "^5.1.32",
     "zod": "^4.1.12"
   }
 }

package/src/actions.ts

@@ -1,10 +1,12 @@
-import { html, HSHtml } from '@hyperspan/html';
+import { html } from '@hyperspan/html';
 import { createRoute, returnHTMLResponse } from './server';
 import * as z from 'zod/v4';
 import type { Hyperspan as HS } from './types';
 import { assetHash, formDataToJSON } from './utils';
-import * as actionsClient from './client/_hs/hyperspan-actions.client';
-import { renderClientJS } from './client/js';
+import { buildClientJS } from './client/js';
+import { validateBody } from './middleware';
+
+const actionsClientJS = await buildClientJS(import.meta.resolve('./client/_hs/hyperspan-actions.client'));
 
 /**
  * Actions = Form + route handler
@@ -19,7 +21,7 @@ import { renderClientJS } from './client/js';
  * 5. Replaces form content in place with HTML response content from server via the Idiomorph library
  * 6. Handles any Exception thrown on server as error displayed back to user on the page
  */
-export function createAction<T extends z.ZodTypeAny>(params: { name: string; schema?: T }): HS.Action<T> {
+export function createAction<T extends z.ZodObject<any, any>>(params: { name: string; schema?: T }): HS.Action<T> {
   const { name, schema } = params;
   const path = `/__actions/${assetHash(name)}`;
 
@@ -30,7 +32,7 @@ export function createAction<T extends z.ZodTypeAny>(params: { name: string; sch
     .get((c: HS.Context) => api.render(c))
     .post(async (c: HS.Context) => {
       // Parse form data
-      const formData = await c.req.raw.formData();
+      const formData = await c.req.formData();
       const jsonData = formDataToJSON(formData) as Partial<z.infer<T>>;
       const schemaData = schema ? schema.safeParse(jsonData) : null;
       const data = schemaData?.success ? (schemaData.data as Partial<z.infer<T>>) : jsonData;
@@ -69,7 +71,10 @@ export function createAction<T extends z.ZodTypeAny>(params: { name: string; sch
       }
 
       return await returnHTMLResponse(c, () => api.render(c, { data, error }), { status: 400 });
-    });
+    }, { middleware: schema ? [validateBody(schema)] : [] });
+
+  // Set the name of the action for the route
+  route._config.name = name;
 
   const api: HS.Action<T> = {
     _kind: 'hsAction',
@@ -101,7 +106,7 @@ export function createAction<T extends z.ZodTypeAny>(params: { name: string; sch
      */
     render(c: HS.Context, props?: HS.ActionProps<T>) {
       const formContent = api._form ? api._form(c, props || {}) : null;
-      return formContent ? html`<hs-action url="${this._path()}">${formContent}</hs-action>${renderClientJS(actionsClient)}` : null;
+      return formContent ? html`<hs-action url="${this._path()}">${formContent}</hs-action>${actionsClientJS.renderScriptTag()}` : null;
     },
     errorHandler(handler) {
       _errorHandler = handler;

package/src/client/_hs/hyperspan-streaming.client.ts

@@ -1,68 +1,5 @@
-import { Idiomorph } from './idiomorph';
 import { lazyLoadScripts } from './hyperspan-scripts.client';
 
-/**
- * Used for streaming content from the server to the client.
- */
-function htmlAsyncContentObserver() {
-  if (typeof MutationObserver != 'undefined') {
-    // Hyperspan - Async content loader
-    // Puts streamed content in its place immediately after it is added to the DOM
-    const asyncContentObserver = new MutationObserver((list) => {
-      const asyncContent = list
-        .map((mutation) =>
-          Array.from(mutation.addedNodes).find((node: any) => {
-            if (!node || !node?.id || typeof node.id !== 'string') {
-              return false;
-            }
-            return node.id?.startsWith('async_loading_') && node.id?.endsWith('_content');
-          })
-        )
-        .filter((node: any) => node);
-
-      asyncContent.forEach((templateEl: any) => {
-        try {
-          // Also observe for content inside the template content (shadow DOM is separate)
-          asyncContentObserver.observe(templateEl.content, { childList: true, subtree: true });
-
-          const slotId = templateEl.id.replace('_content', '');
-          const slotEl = document.getElementById(slotId);
-
-          if (slotEl) {
-            // Content AND slot are present - let's insert the content into the slot
-            // Ensure the content is fully done streaming in before inserting it into the slot
-            waitForContent(templateEl.content, (el2) => {
-              return Array.from(el2.childNodes).find(
-                (node) => node.nodeType === Node.COMMENT_NODE && node.nodeValue === 'end'
-              );
-            })
-              .then((endComment) => {
-                templateEl.content.removeChild(endComment);
-                const content = templateEl.content.cloneNode(true);
-                Idiomorph.morph(slotEl, content);
-                templateEl.parentNode.removeChild(templateEl);
-                lazyLoadScripts();
-              })
-              .catch(console.error);
-          } else {
-            // Slot is NOT present - wait for it to be added to the DOM so we can insert the content into it
-            waitForContent(document.body, () => {
-              return document.getElementById(slotId);
-            }).then((slotEl) => {
-              Idiomorph.morph(slotEl, templateEl.content.cloneNode(true));
-              lazyLoadScripts();
-            });
-          }
-        } catch (e) {
-          console.error(e);
-        }
-      });
-    });
-    asyncContentObserver.observe(document.body, { childList: true, subtree: true });
-  }
-}
-htmlAsyncContentObserver();
-
 /**
  * Wait until ALL of the content inside an element is present from streaming in.
  * Large chunks of content can sometimes take more than a single tick to write to DOM.
@@ -91,4 +28,39 @@ async function waitForContent(
       reject(new Error(`[Hyperspan] Timeout waiting for end of streaming content ${el.id}`));
     }, options.timeoutMs || 10000);
   });
-}
+}
+
+function renderStreamChunk(chunk: { id: string }) {
+  const slotId = chunk.id;
+  const slotEl = document.getElementById(slotId);
+  const templateEl = document.getElementById(`${slotId}_content`) as HTMLTemplateElement;
+
+  if (slotEl) {
+    // Content AND slot are present - let's insert the content into the slot
+    // Ensure the content is fully done streaming in before inserting it into the slot
+    waitForContent(templateEl.content as unknown as HTMLElement, (el2) => {
+      return Array.from(el2.childNodes).find(
+        (node) => node.nodeType === Node.COMMENT_NODE && node.nodeValue === 'end'
+      );
+    })
+      .then((endComment) => {
+        templateEl.content.removeChild(endComment as Node);
+        const content = templateEl.content.cloneNode(true);
+        slotEl.replaceWith(content);
+        templateEl.parentNode?.removeChild(templateEl);
+        lazyLoadScripts();
+      })
+      .catch(console.error);
+  } else {
+    // Slot is NOT present - wait for it to be added to the DOM so we can insert the content into it
+    waitForContent(document.body, () => {
+      return document.getElementById(slotId);
+    }).then((slotEl) => {
+      (slotEl as HTMLElement)?.replaceWith(templateEl.content.cloneNode(true));
+      lazyLoadScripts();
+    });
+  }
+}
+
+// @ts-ignore
+window._hscc = renderStreamChunk;

package/src/client/js.test.ts

@@ -0,0 +1,200 @@
+import { test, expect, describe } from 'bun:test';
+import { functionToString } from './js';
+
+describe('functionToString', () => {
+  describe('named functions', () => {
+    test('converts named function to string', () => {
+      function myFunction() {
+        return 'hello';
+      }
+
+      const result = functionToString(myFunction);
+      expect(result).toContain('function');
+      expect(result).toContain('myFunction');
+      expect(result).toContain("return 'hello'");
+    });
+
+    test('converts named function with parameters', () => {
+      function add(a: number, b: number) {
+        return a + b;
+      }
+
+      const result = functionToString(add);
+      expect(result).toContain('function');
+      expect(result).toContain('add');
+      expect(result).toContain('a');
+      expect(result).toContain('b');
+    });
+
+    test('converts named async function', () => {
+      async function fetchData() {
+        const response = await fetch('/api/data');
+        return response.json();
+      }
+
+      const result = functionToString(fetchData);
+      expect(result).toContain('async function');
+      expect(result).toContain('fetchData');
+      expect(result).toContain('await');
+    });
+  });
+
+  describe('anonymous functions', () => {
+    test('converts anonymous function to string', () => {
+      const fn = function () {
+        return 'anonymous';
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain("return 'anonymous'");
+    });
+
+    test('converts anonymous function with parameters', () => {
+      const fn = function (x: number, y: number) {
+        return x * y;
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain('x');
+      expect(result).toContain('y');
+    });
+
+    test('converts anonymous async function', () => {
+      const fn = async function () {
+        await new Promise(resolve => setTimeout(resolve, 100));
+        return 'done';
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('async function');
+      expect(result).toContain('await');
+    });
+  });
+
+  describe('arrow functions', () => {
+    test('converts single-line arrow function without braces', () => {
+      const fn = (x: number) => x * 2;
+
+      const result = functionToString(fn);
+      expect(result).toContain('function(x) { return x * 2; }');
+    });
+
+    test('converts single-line arrow function with single parameter', () => {
+      const fn = (name: string) => `Hello, ${name}!`;
+
+      const result = functionToString(fn);
+      expect(result).toContain('function(name) { return `Hello, ${name}!`; }');
+    });
+
+    test('converts single-line arrow function with multiple parameters', () => {
+      const fn = (a: number, b: number) => a + b;
+
+      const result = functionToString(fn);
+      expect(result).toContain('function(a, b) { return a + b; }');
+    });
+
+    test('converts arrow function with braces', () => {
+      const fn = (x: number) => {
+        const doubled = x * 2;
+        return doubled;
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain('x');
+      expect(result).toContain('doubled');
+    });
+
+    test('converts multi-line arrow function', () => {
+      const fn = (items: string[]) => {
+        const filtered = items.filter(item => item.length > 0);
+        return filtered.map(item => item.toUpperCase());
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain('items');
+      expect(result).toContain('filtered');
+    });
+
+    test('converts async arrow function without braces', () => {
+      const fn = async (id: number) => await fetch(`/api/${id}`);
+
+      const result = functionToString(fn);
+      expect(result).toContain('async function');
+      expect(result).toContain('id');
+      expect(result).toContain('await');
+    });
+
+    test('converts async arrow function with braces', () => {
+      const fn = async (id: number) => {
+        const response = await fetch(`/api/${id}`);
+        return response.json();
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('async function');
+      expect(result).toContain('id');
+      expect(result).toContain('await');
+    });
+
+    test('converts arrow function with no parameters', () => {
+      const fn = () => 'no params';
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain("return 'no params'");
+    });
+
+    test('converts arrow function with complex expression', () => {
+      const fn = (obj: { x: number; y: number }) => obj.x + obj.y;
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain('return');
+      expect(result).toContain('obj.x + obj.y');
+    });
+  });
+
+  describe('edge cases', () => {
+    test('handles function with whitespace', () => {
+      const fn = function () {
+        return 'test';
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain("return 'test'");
+    });
+
+    test('handles arrow function with whitespace', () => {
+      const fn = (x) => x * 2;
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain('return');
+    });
+
+    test('handles function with comments', () => {
+      const fn = function () {
+        // This is a comment
+        return 'commented';
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain("return 'commented'");
+    });
+
+    test('handles nested arrow functions', () => {
+      const fn = (arr: number[]) => arr.map(x => x * 2);
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      // The nested arrow function should also be converted
+      expect(result).toContain('x * 2');
+    });
+  });
+});

package/src/client/js.ts

@@ -1,61 +1,94 @@
 import { html } from '@hyperspan/html';
+import { assetHash as assetHashFn } from '../utils';
+import { join } from 'node:path';
+import type { Hyperspan as HS } from '../types';
+
+const CWD = process.cwd();
+const IS_PROD = process.env.NODE_ENV === 'production';
 
 export const JS_PUBLIC_PATH = '/_hs/js';
 export const JS_ISLAND_PUBLIC_PATH = '/_hs/js/islands';
 export const JS_IMPORT_MAP = new Map<string, string>();
+const CLIENT_JS_CACHE = new Map<string, { esmName: string, exports: string, fnArgs: string, publicPath: string }>();
+const EXPORT_REGEX = /export\{(.*)\}/g;
 
 /**
- * Render a client JS module as a script tag
+ * Build a client JS module and return a Hyperspan.ClientJSBuildResult object
  */
-export function renderClientJS<T>(module: T, loadScript?: ((module: T) => void) | string) {
-  // @ts-ignore
-  if (!module.__CLIENT_JS) {
-    throw new Error(
-      `[Hyperspan] Client JS was not loaded by Hyperspan! Ensure the filename ends with .client.ts to use this render method.`
-    );
-  }
+export async function buildClientJS(modulePathResolved: string): Promise<HS.ClientJSBuildResult> {
+  const modulePath = modulePathResolved.replace('file://', '');
+  const assetHash = assetHashFn(modulePath);
 
-  return html.raw(
-    // @ts-ignore
-    module.__CLIENT_JS.renderScriptTag({
-      loadScript: loadScript
-        ? typeof loadScript === 'string'
-          ? loadScript
-          : functionToString(loadScript)
-        : undefined,
-    })
-  );
-}
+  // Cache: Avoid re-processing the same file
+  if (!CLIENT_JS_CACHE.has(assetHash)) {
+    // Build the client JS module
+    const result = await Bun.build({
+      entrypoints: [modulePath],
+      outdir: join(CWD, './public', JS_PUBLIC_PATH), // @TODO: Make this configurable... should be read from config file...
+      naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
+      external: Array.from(JS_IMPORT_MAP.keys()),
+      minify: true,
+      format: 'esm',
+      target: 'browser',
+      env: 'APP_PUBLIC_*',
+    });
 
-/**
- * Convert a function to a string (results in loss of context!)
- * Handles named, async, and arrow functions
- */
-export function functionToString(fn: any) {
-  let str = fn.toString().trim();
-
-  // Ensure consistent output & handle async
-  if (!str.includes('function ')) {
-    if (str.includes('async ')) {
-      str = 'async function ' + str.replace('async ', '');
-    } else {
-      str = 'function ' + str;
+    // Add output file to import map
+    const esmName = String(result.outputs[0].path.split('/').reverse()[0]).replace('.js', '');
+    const publicPath = `${JS_PUBLIC_PATH}/${esmName}.js`;
+    JS_IMPORT_MAP.set(esmName, publicPath);
+
+    // Get the contents of the file to extract the exports
+    const contents = await result.outputs[0].text();
+    const exportLine = EXPORT_REGEX.exec(contents);
+
+    let exports = '{}';
+    if (exportLine) {
+      const exportName = exportLine[1];
+      exports =
+        '{' +
+        exportName
+          .split(',')
+          .map((name) => name.trim().split(' as '))
+          .map(([name, alias]) => `${alias === 'default' ? 'default as ' + name : alias}`)
+          .join(', ') +
+        '}';
     }
+    const fnArgs = exports.replace(/(\w+)\s*as\s*(\w+)/g, '$1: $2');
+    CLIENT_JS_CACHE.set(assetHash, { esmName, exports, fnArgs, publicPath });
   }
 
-  const lines = str.split('\n');
-  const firstLine = lines[0];
-  const lastLine = lines[lines.length - 1];
+  const { esmName, exports, fnArgs, publicPath } = CLIENT_JS_CACHE.get(assetHash)!;
 
-  // Arrow function conversion
-  if (!lastLine?.includes('}')) {
-    return str.replace('=> ', '{ return ') + '; }';
-  }
+  return {
+    assetHash,
+    esmName,
+    publicPath,
+    renderScriptTag: (loadScript) => {
+      const t = typeof loadScript;
+
+      if (t === 'string') {
+        return html`
+          <script type="module" data-source-id="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(loadScript as string)})(${fnArgs});</script>
+        `;
+      }
+      if (t === 'function') {
+        return html`
+          <script type="module" data-source-id="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(functionToString(loadScript))})(${fnArgs});</script>
+        `;
+      }
 
-  // Cleanup arrow function
-  if (firstLine.includes('=>')) {
-    return str.replace('=> ', '');
+      return html`
+        <script type="module" data-source-id="${assetHash}">import "${esmName}";</script>
+      `;
+    }
   }
+}
 
-  return str;
+/**
+ * Convert a function to a string (results in loss of context!)
+ * Handles named, async, and arrow functions
+ */
+export function functionToString(fn: any) {
+  return fn.toString().trim();
 }

package/src/layout.ts

@@ -1,8 +1,10 @@
 import { html } from '@hyperspan/html';
-import { JS_IMPORT_MAP } from './client/js';
+import { JS_IMPORT_MAP, buildClientJS } from './client/js';
 import { CSS_PUBLIC_PATH, CSS_ROUTE_MAP } from './client/css';
 import type { Hyperspan as HS } from './types';
 
+const clientStreamingJS = await buildClientJS(import.meta.resolve('./client/_hs/hyperspan-streaming.client'));
+
 /**
  * Output the importmap for the client so we can use ESModules on the client to load JS files on demand
  */
@@ -11,6 +13,27 @@ export function hyperspanScriptTags() {
     <script type="importmap">
       {"imports": ${Object.fromEntries(JS_IMPORT_MAP)}}
     </script>
+    <script id="hyperspan-streaming-script">
+      // [Hyperspan] Streaming - Load the client streaming JS module only when the first chunk is loaded
+      window._hsc = window._hsc || [];
+      var hscc = function(e) {
+        if (window._hscc !== undefined) {
+          window._hscc(e);
+        }
+      };
+      window._hsc.push = function(e) {
+        Array.prototype.push.call(window._hsc, e);
+        if (window._hsc.length === 1) {
+          const script = document.createElement('script');
+          script.src = "${clientStreamingJS.publicPath}";
+          document.body.appendChild(script);
+          script.onload = function() {
+            hscc(e);
+          };
+        }
+        hscc(e);
+      };
+    </script>
   `;
 }
 

package/src/middleware.ts

@@ -1,4 +1,91 @@
+import { formDataToJSON } from './utils';
+import { z, flattenError } from 'zod/v4';
+
+import type { ZodAny, ZodObject, ZodError } from 'zod/v4';
 import type { Hyperspan as HS } from './types';
+import { HTTPResponseException } from './server';
+
+export type TValidationType = 'json' | 'form' | 'urlencoded';
+
+/**
+ * Infer the validation type from the request Content-Type header
+ */
+function inferValidationType(headers: Headers): TValidationType {
+  const contentType = headers.get('content-type')?.toLowerCase() || '';
+
+  if (contentType.includes('application/json')) {
+    return 'json';
+  } else if (contentType.includes('multipart/form-data')) {
+    return 'form';
+  } else if (contentType.includes('application/x-www-form-urlencoded')) {
+    return 'urlencoded';
+  }
+
+  // Default to json if content-type is not recognized
+  return 'json';
+}
+
+export class ZodValidationError extends Error {
+  constructor(flattened: ReturnType<typeof flattenError>) {
+    super('Input validation error(s)');
+    this.name = 'ZodValidationError';
+
+    // Copy all properties from flattened error
+    Object.assign(this, flattened);
+  }
+}
+
+export function validateQuery(schema: ZodObject | ZodAny): HS.MiddlewareFunction {
+  return async (context: HS.Context, next: HS.NextFunction) => {
+    const query = formDataToJSON(context.req.query);
+    const validated = schema.safeParse(query);
+
+    if (!validated.success) {
+      const err = formatZodError(validated.error);
+      return context.res.error(err, { status: 400 });
+    }
+
+    // Store the validated query in the context variables
+    context.vars.query = validated.data as z.infer<typeof schema>;
+
+    return next();
+  }
+}
+
+export function validateBody(schema: ZodObject | ZodAny, type?: TValidationType): HS.MiddlewareFunction {
+  return async (context: HS.Context, next: HS.NextFunction) => {
+    // Infer type from Content-Type header if not provided
+    const validationType = type || inferValidationType(context.req.headers);
+
+    let body: unknown = {};
+    if (validationType === 'json') {
+      body = await context.req.raw.json();
+    } else if (validationType === 'form') {
+      const formData = await context.req.formData();
+      body = formDataToJSON(formData as FormData);
+    } else if (validationType === 'urlencoded') {
+      const urlencoded = await context.req.urlencoded();
+      body = formDataToJSON(urlencoded);
+    }
+    const validated = schema.safeParse(body);
+
+    if (!validated.success) {
+      const err = formatZodError(validated.error);
+      throw new HTTPResponseException(err, { status: 400 });
+      //return context.res.error(err, { status: 400 });
+    }
+
+    // Store the validated body in the context variables
+    context.vars.body = validated.data as z.infer<typeof schema>;
+
+    return next();
+  }
+}
+
+export function formatZodError(error: ZodError): ZodValidationError {
+  const zodError = flattenError(error);
+  return new ZodValidationError(zodError);
+}
 
 /**
  * Type guard to check if a handler is a middleware function
@@ -55,4 +142,3 @@ export async function executeMiddleware(
   // Start execution from the first handler
   return await createNext(0)();
 }
-

package/src/server.ts

@@ -1,19 +1,20 @@
-import { HSHtml, html, isHSHtml, renderStream, renderAsync, render } from '@hyperspan/html';
+import { HSHtml, html, isHSHtml, renderStream, renderAsync, render, _typeOf } from '@hyperspan/html';
+import { isbot } from 'isbot';
 import { executeMiddleware } from './middleware';
-import { clientJSPlugin } from './plugins';
 import { parsePath } from './utils';
 import { Cookies } from './cookies';
 
 import type { Hyperspan as HS } from './types';
-import { RequestOptions } from 'node:http';
 
 export const IS_PROD = process.env.NODE_ENV === 'production';
 
 export class HTTPResponseException extends Error {
+  public _error?: Error;
   public _response?: Response;
-  constructor(body: string | undefined, options?: ResponseInit) {
-    super(body);
-    this._response = new Response(body, options);
+  constructor(body: string | Error | undefined, options?: ResponseInit) {
+    super(body instanceof Error ? body.message : body);
+    this._error = body instanceof Error ? body : undefined;
+    this._response = new Response(body instanceof Error ? body.message : body, options);
   }
 }
 
@@ -21,11 +22,22 @@ export class HTTPResponseException extends Error {
  * Ensures a valid config object is returned, even with an empty object or partial object passed in
  */
 export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
+  const defaultConfig: HS.Config = {
+    appDir: './app',
+    publicDir: './public',
+    plugins: [],
+    responseOptions: {
+      // Disable streaming for bots by default
+      disableStreaming: (c) => isbot(c.req.raw.headers.get('user-agent') ?? ''),
+    },
+  };
   return {
+    ...defaultConfig,
     ...config,
-    appDir: config.appDir ?? './app',
-    publicDir: config.publicDir ?? './public',
-    plugins: [clientJSPlugin(), ...(config.plugins ?? [])],
+    responseOptions: {
+      ...defaultConfig.responseOptions,
+      ...config.responseOptions,
+    },
   };
 }
 
@@ -104,6 +116,7 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
  */
 export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
   const _handlers: Record<string, HS.RouteHandler> = {};
+  let _errorHandler: HS.ErrorHandler | undefined = undefined;
   let _middleware: Record<string, Array<HS.MiddlewareFunction>> = { '*': [] };
 
   const api: HS.Route = {
@@ -142,14 +155,6 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
       _middleware['PUT'] = handlerOptions?.middleware || [];
       return api;
     },
-    /**
-     * Add a DELETE route handler (typically to delete existing data)
-     */
-    delete(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
-      _handlers['DELETE'] = handler;
-      _middleware['DELETE'] = handlerOptions?.middleware || [];
-      return api;
-    },
     /**
      * Add a PATCH route handler (typically to update existing data)
      */
@@ -158,6 +163,14 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
       _middleware['PATCH'] = handlerOptions?.middleware || [];
       return api;
     },
+    /**
+     * Add a DELETE route handler (typically to delete existing data)
+     */
+    delete(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
+      _handlers['DELETE'] = handler;
+      _middleware['DELETE'] = handlerOptions?.middleware || [];
+      return api;
+    },
     /**
      * Add a OPTIONS route handler (typically to handle CORS preflight requests)
      */
@@ -166,8 +179,11 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
       _middleware['OPTIONS'] = handlerOptions?.middleware || [];
       return api;
     },
-    errorHandler(handler: HS.RouteHandler) {
-      _handlers['_ERROR'] = handler;
+    /**
+     * Set a custom error handler for this route to fall back to if the route handler throws an error
+     */
+    errorHandler(handler: HS.ErrorHandler) {
+      _errorHandler = handler;
       return api;
     },
     /**
@@ -225,7 +241,14 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
         }
 
         if (isHTMLContent(routeContent)) {
-          return returnHTMLResponse(context, () => routeContent);
+          // Merge server and route-specific response options
+          const responseOptions = { ...(api._serverConfig?.responseOptions ?? {}), ...(api._config?.responseOptions ?? {}) };
+          return returnHTMLResponse(context, () => routeContent, responseOptions);
+        }
+
+        const contentType = _typeOf(routeContent);
+        if (contentType === 'generator') {
+          return new StreamResponse(routeContent as AsyncGenerator);
         }
 
         return routeContent;
@@ -236,8 +259,9 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
       try {
         return await executeMiddleware(context, [...globalMiddleware, ...methodMiddleware, methodHandler]);
       } catch (e) {
-        if (_handlers['_ERROR']) {
-          return await (_handlers['_ERROR'](context) as Promise<Response>);
+        if (_errorHandler !== undefined) {
+          const responseOptions = { ...(api._serverConfig?.responseOptions ?? {}), ...(api._config?.responseOptions ?? {}) };
+          return returnHTMLResponse(context, () => (_errorHandler as HS.ErrorHandler)(context, e as Error), responseOptions);
         }
         throw e;
       }
@@ -325,7 +349,7 @@ function isHTMLContent(response: unknown): response is Response {
 export async function returnHTMLResponse(
   context: HS.Context,
   handlerFn: () => unknown,
-  responseOptions?: { status?: number; headers?: Record<string, string> }
+  responseOptions?: { status?: number; headers?: Record<string, string>; disableStreaming?: (context: HS.Context) => boolean }
 ): Promise<Response> {
   try {
     const routeContent = await handlerFn();
@@ -337,14 +361,22 @@ export async function returnHTMLResponse(
 
     // Render HSHtml if returned from route handler
     if (isHSHtml(routeContent)) {
-      // @TODO: Move this to config or something...
-      const streamOpt = context.req.query.get('__nostream');
-      const streamingEnabled = (streamOpt !== undefined ? streamOpt : true);
+      const disableStreaming = responseOptions?.disableStreaming?.(context) ?? false;
 
       // Stream only if enabled and there is async content to stream
-      if (streamingEnabled && (routeContent as HSHtml).asyncContent?.length > 0) {
+      if (!disableStreaming && (routeContent as HSHtml).asyncContent?.length > 0) {
         return new StreamResponse(
-          renderStream(routeContent as HSHtml),
+          renderStream(routeContent as HSHtml, {
+            renderChunk: (chunk) => {
+              return html`
+              <template id="${chunk.id}_content">${html.raw(chunk.content)}<!--end--></template>
+              <script>
+                window._hsc = window._hsc || [];
+                window._hsc.push({id: "${chunk.id}" });
+              </script>
+            `;
+            }
+          }),
           responseOptions
         ) as Response;
       } else {

package/src/types.ts

@@ -27,6 +27,9 @@ export namespace Hyperspan {
     // For customizing the routes and adding your own...
     beforeRoutesAdded?: (server: Hyperspan.Server) => void;
     afterRoutesAdded?: (server: Hyperspan.Server) => void;
+    responseOptions?: {
+      disableStreaming?: (context: Hyperspan.Context) => boolean;
+    };
   };
 
   export type CookieOptions = {
@@ -92,6 +95,9 @@ export namespace Hyperspan {
     path: string;
     params: Record<string, string | undefined>;
     cssImports: string[];
+    responseOptions?: {
+      disableStreaming?: (context: Hyperspan.Context) => boolean;
+    };
   };
   export type RouteHandler = (context: Hyperspan.Context) => unknown;
   export type RouteHandlerOptions = {
@@ -113,6 +119,11 @@ export namespace Hyperspan {
    */
   export type NextFunction = () => Promise<Response>;
 
+  /**
+   * Error handler function signature
+   */
+  export type ErrorHandler = (context: Hyperspan.Context, error: Error) => unknown | undefined;
+
   /**
    * Middleware function signature
    * Accepts context and next function, returns a Response
@@ -125,6 +136,7 @@ export namespace Hyperspan {
   export interface Route {
     _kind: 'hsRoute';
     _config: Partial<Hyperspan.RouteConfig>;
+    _serverConfig?: Hyperspan.Config;
     _path(): string;
     _methods(): string[];
     get: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
@@ -133,7 +145,7 @@ export namespace Hyperspan {
     patch: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
     delete: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
     options: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
-    errorHandler: (handler: Hyperspan.RouteHandler) => Hyperspan.Route;
+    errorHandler: (handler: Hyperspan.ErrorHandler) => Hyperspan.Route;
     middleware: (middleware: Array<Hyperspan.MiddlewareFunction>) => Hyperspan.Route;
     fetch: (request: Request) => Promise<Response>;
   };
@@ -148,7 +160,7 @@ export namespace Hyperspan {
   ) => ActionResponse;
   export interface Action<T extends z.ZodTypeAny> {
     _kind: 'hsAction';
-    _config: Hyperspan.RouteConfig;
+    _config: Partial<Hyperspan.RouteConfig>;
     _path(): string;
     _form: null | ActionFormHandler<T>;
     form(form: ActionFormHandler<T>): Action<T>;
@@ -158,4 +170,19 @@ export namespace Hyperspan {
     middleware: (middleware: Array<Hyperspan.MiddlewareFunction>) => Action<T>;
     fetch: (request: Request) => Promise<Response>;
   }
+
+  /**
+   * Client JS Module = ESM Module + Public Path + Render Script Tag
+   */
+  export type ClientJSBuildResult = {
+    assetHash: string; // Asset hash of the module path
+    esmName: string; // Filename of the built JavaScript file without the extension
+    publicPath: string; // Full public path of the built JavaScript file
+    /**
+     * Render a <script type="module"> tag for the JS module
+     * @param loadScript - A function that loads the module or a string of code to load the module
+     * @returns HSHtml Template with the <script type="module"> tag
+     */
+    renderScriptTag: (loadScript?: ((module: unknown) => HSHtml | string) | string) => HSHtml;
+  }
 }

package/src/plugins.ts

@@ -1,94 +0,0 @@
-import type { Hyperspan as HS } from './types';
-import { JS_PUBLIC_PATH, JS_IMPORT_MAP } from './client/js';
-import { assetHash } from './utils';
-import { IS_PROD } from './server';
-import { join } from 'node:path';
-
-export const CSS_PUBLIC_PATH = '/_hs/css';
-const CLIENT_JS_CACHE = new Map<string, string>();
-const EXPORT_REGEX = /export\{(.*)\}/g;
-
-/**
- * Hyperspan Client JS Plugin
- */
-export function clientJSPlugin(): HS.Plugin {
-  return async (config: HS.Config) => {
-    // Define a Bun plugin to handle .client.ts files
-    await Bun.plugin({
-      name: 'Hyperspan Client JS Loader',
-      async setup(build) {
-        // when a .client.ts file is imported...
-        build.onLoad({ filter: /\.client\.ts$/ }, async (args) => {
-          const jsId = assetHash(args.path);
-
-          // Cache: Avoid re-processing the same file
-          if (IS_PROD && CLIENT_JS_CACHE.has(jsId)) {
-            return {
-              contents: CLIENT_JS_CACHE.get(jsId) || '',
-              loader: 'js',
-            };
-          }
-
-          // We need to build the file to ensure we can ship it to the client with dependencies
-          // Ironic, right? Calling Bun.build() inside of a plugin that runs on Bun.build()?
-          const result = await Bun.build({
-            entrypoints: [args.path],
-            outdir: join(config.publicDir, JS_PUBLIC_PATH),
-            naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
-            external: Array.from(JS_IMPORT_MAP.keys()),
-            minify: IS_PROD,
-            format: 'esm',
-            target: 'browser',
-            env: 'APP_PUBLIC_*',
-          });
-
-          // Add output file to import map
-          const esmName = String(result.outputs[0].path.split('/').reverse()[0]).replace('.js', '');
-          JS_IMPORT_MAP.set(esmName, `${JS_PUBLIC_PATH}/${esmName}.js`);
-
-          // Get the contents of the file to extract the exports
-          const contents = await result.outputs[0].text();
-          const exportLine = EXPORT_REGEX.exec(contents);
-
-          let exports = '{}';
-          if (exportLine) {
-            const exportName = exportLine[1];
-            exports =
-              '{' +
-              exportName
-                .split(',')
-                .map((name) => name.trim().split(' as '))
-                .map(([name, alias]) => `${alias === 'default' ? 'default as ' + name : alias}`)
-                .join(', ') +
-              '}';
-          }
-          const fnArgs = exports.replace(/(\w+)\s*as\s*(\w+)/g, '$1: $2');
-
-          // Export a special object that can be used to render the client JS as a script tag
-          const moduleCode = `// hyperspan:processed
-import { functionToString } from '@hyperspan/framework/client/js';
-
-// hyperspan:client-js-plugin
-export const __CLIENT_JS = {
-  id: "${jsId}",
-  esmName: "${esmName}",
-  sourceFile: "${args.path}",
-  outputFile: "${result.outputs[0].path}",
-  renderScriptTag: ({ loadScript }) => {
-    const fn = loadScript ? (typeof loadScript === 'string' ? loadScript : \`const fn = \${functionToString(loadScript)}; fn(${fnArgs});\`) : '';
-    return \`<script type="module" data-source-id="${jsId}">import ${exports} from "${esmName}";\n\${fn}</script>\`;
-  },
-}
-`;
-
-          CLIENT_JS_CACHE.set(jsId, moduleCode);
-
-          return {
-            contents: moduleCode,
-            loader: 'js',
-          };
-        });
-      },
-    });
-  };
-}