@hyperspan/framework 0.3.1 → 0.3.3

package/build.ts

@@ -1,6 +1,6 @@
 import { build } from 'bun';
 
-const entrypoints = ['./src/server.ts', './src/assets.ts'];
+const entrypoints = ['./src/server.ts', './src/assets.ts', './src/middleware.ts'];
 const external = ['@hyperspan/html'];
 const outdir = './dist';
 const target = 'node';

package/dist/assets.js

@@ -1,3 +1,5 @@
+import"./chunk-atw8cdg1.js";
+
 // src/assets.ts
 import { html } from "@hyperspan/html";
 import { createHash } from "node:crypto";
@@ -60,17 +62,12 @@ function assetHash(content) {
 }
 var ISLAND_PUBLIC_PATH = "/_hs/js/islands";
 var ISLAND_DEFAULTS = () => ({
-  ssr: true
+  ssr: true,
+  loading: undefined
 });
 function renderIsland(Component, props, options = ISLAND_DEFAULTS()) {
   if (Component.__HS_ISLAND?.render) {
-    return Component.__HS_ISLAND.render(props, options);
-  }
-  if (Component.__HS_ISLAND?.ssr && options.ssr) {
-    return Component.__HS_ISLAND.ssr(props);
-  }
-  if (Component.__HS_ISLAND?.clientOnly) {
-    return Component.__HS_ISLAND.clientOnly(props);
+    return html.raw(Component.__HS_ISLAND.render(props, options));
   }
   throw new Error(`Module ${Component.name} was not loaded with an island plugin! Did you forget to install an island plugin and add it to the createServer() 'islandPlugins' config?`);
 }

package/dist/chunk-atw8cdg1.js

@@ -0,0 +1,19 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+
+export { __toESM, __commonJS };

package/dist/middleware.js

@@ -0,0 +1,178 @@
+import {
+  __commonJS,
+  __toESM
+} from "./chunk-atw8cdg1.js";
+
+// ../../node_modules/timestring/index.js
+var require_timestring = __commonJS((exports, module) => {
+  module.exports = parseTimestring;
+  var DEFAULT_OPTS = {
+    hoursPerDay: 24,
+    daysPerWeek: 7,
+    weeksPerMonth: 4,
+    monthsPerYear: 12,
+    daysPerYear: 365.25
+  };
+  var UNIT_MAP = {
+    ms: ["ms", "milli", "millisecond", "milliseconds"],
+    s: ["s", "sec", "secs", "second", "seconds"],
+    m: ["m", "min", "mins", "minute", "minutes"],
+    h: ["h", "hr", "hrs", "hour", "hours"],
+    d: ["d", "day", "days"],
+    w: ["w", "week", "weeks"],
+    mth: ["mon", "mth", "mths", "month", "months"],
+    y: ["y", "yr", "yrs", "year", "years"]
+  };
+  function parseTimestring(value, returnUnit, opts) {
+    opts = Object.assign({}, DEFAULT_OPTS, opts || {});
+    if (typeof value === "number" || value.match(/^[-+]?[0-9.]+$/g)) {
+      value = parseInt(value) + "ms";
+    }
+    let totalSeconds = 0;
+    const unitValues = getUnitValues(opts);
+    const groups = value.toLowerCase().replace(/[^.\w+-]+/g, "").match(/[-+]?[0-9.]+[a-z]+/g);
+    if (groups === null) {
+      throw new Error(`The value [${value}] could not be parsed by timestring`);
+    }
+    groups.forEach((group) => {
+      const value2 = group.match(/[0-9.]+/g)[0];
+      const unit = group.match(/[a-z]+/g)[0];
+      totalSeconds += getSeconds(value2, unit, unitValues);
+    });
+    if (returnUnit) {
+      return convert(totalSeconds, returnUnit, unitValues);
+    }
+    return totalSeconds;
+  }
+  function getUnitValues(opts) {
+    const unitValues = {
+      ms: 0.001,
+      s: 1,
+      m: 60,
+      h: 3600
+    };
+    unitValues.d = opts.hoursPerDay * unitValues.h;
+    unitValues.w = opts.daysPerWeek * unitValues.d;
+    unitValues.mth = opts.daysPerYear / opts.monthsPerYear * unitValues.d;
+    unitValues.y = opts.daysPerYear * unitValues.d;
+    return unitValues;
+  }
+  function getUnitKey(unit) {
+    for (const key of Object.keys(UNIT_MAP)) {
+      if (UNIT_MAP[key].indexOf(unit) > -1) {
+        return key;
+      }
+    }
+    throw new Error(`The unit [${unit}] is not supported by timestring`);
+  }
+  function getSeconds(value, unit, unitValues) {
+    return value * unitValues[getUnitKey(unit)];
+  }
+  function convert(value, unit, unitValues) {
+    return value / unitValues[getUnitKey(unit)];
+  }
+});
+
+// ../../node_modules/hono/dist/middleware/etag/digest.js
+var mergeBuffers = (buffer1, buffer2) => {
+  if (!buffer1) {
+    return buffer2;
+  }
+  const merged = new Uint8Array(buffer1.byteLength + buffer2.byteLength);
+  merged.set(new Uint8Array(buffer1), 0);
+  merged.set(buffer2, buffer1.byteLength);
+  return merged;
+};
+var generateDigest = async (stream, generator) => {
+  if (!stream) {
+    return null;
+  }
+  let result = undefined;
+  const reader = stream.getReader();
+  for (;; ) {
+    const { value, done } = await reader.read();
+    if (done) {
+      break;
+    }
+    result = await generator(mergeBuffers(result, value));
+  }
+  if (!result) {
+    return null;
+  }
+  return Array.prototype.map.call(new Uint8Array(result), (x) => x.toString(16).padStart(2, "0")).join("");
+};
+
+// ../../node_modules/hono/dist/middleware/etag/index.js
+var RETAINED_304_HEADERS = [
+  "cache-control",
+  "content-location",
+  "date",
+  "etag",
+  "expires",
+  "vary"
+];
+function etagMatches(etag2, ifNoneMatch) {
+  return ifNoneMatch != null && ifNoneMatch.split(/,\s*/).indexOf(etag2) > -1;
+}
+function initializeGenerator(generator) {
+  if (!generator) {
+    if (crypto && crypto.subtle) {
+      generator = (body) => crypto.subtle.digest({
+        name: "SHA-1"
+      }, body);
+    }
+  }
+  return generator;
+}
+var etag = (options) => {
+  const retainedHeaders = options?.retainedHeaders ?? RETAINED_304_HEADERS;
+  const weak = options?.weak ?? false;
+  const generator = initializeGenerator(options?.generateDigest);
+  return async function etag2(c, next) {
+    const ifNoneMatch = c.req.header("If-None-Match") ?? null;
+    await next();
+    const res = c.res;
+    let etag3 = res.headers.get("ETag");
+    if (!etag3) {
+      if (!generator) {
+        return;
+      }
+      const hash = await generateDigest(res.clone().body, generator);
+      if (hash === null) {
+        return;
+      }
+      etag3 = weak ? `W/"${hash}"` : `"${hash}"`;
+    }
+    if (etagMatches(etag3, ifNoneMatch)) {
+      c.res = new Response(null, {
+        status: 304,
+        statusText: "Not Modified",
+        headers: {
+          ETag: etag3
+        }
+      });
+      c.res.headers.forEach((_, key) => {
+        if (retainedHeaders.indexOf(key.toLowerCase()) === -1) {
+          c.res.headers.delete(key);
+        }
+      });
+    } else {
+      c.res.headers.set("ETag", etag3);
+    }
+  };
+};
+
+// src/middleware.ts
+var import_timestring = __toESM(require_timestring(), 1);
+function cacheTime(timeStrOrSeconds) {
+  return (c, next) => etag()(c, () => {
+    if (c.req.method.toUpperCase() === "GET") {
+      const timeInSeconds = typeof timeStrOrSeconds === "number" ? timeStrOrSeconds : import_timestring.default(timeStrOrSeconds);
+      c.header("Cache-Control", `public, max-age=${timeInSeconds}`);
+    }
+    return next();
+  });
+}
+export {
+  cacheTime
+};

package/dist/server.js

@@ -2,6 +2,7 @@ import {
   buildClientCSS,
   buildClientJS
 } from "./assets.js";
+import"./chunk-atw8cdg1.js";
 
 // src/server.ts
 import { readdir } from "node:fs/promises";
@@ -1847,18 +1848,6 @@ function createRoute(handler) {
       _handlers["POST"] = handler2;
       return api;
     },
-    put(handler2) {
-      _handlers["PUT"] = handler2;
-      return api;
-    },
-    delete(handler2) {
-      _handlers["DELETE"] = handler2;
-      return api;
-    },
-    patch(handler2) {
-      _handlers["PATCH"] = handler2;
-      return api;
-    },
     middleware(middleware) {
       _middleware = middleware;
       return api;
@@ -1881,7 +1870,7 @@ function createRoute(handler) {
             const streamOpt = context.req.query("__nostream");
             const streamingEnabled = !userIsBot && (streamOpt !== undefined ? streamOpt : true);
             if (isHSHtml(routeContent)) {
-              if (streamingEnabled) {
+              if (streamingEnabled && routeContent.asyncContent?.length > 0) {
                 return new StreamResponse(renderStream(routeContent));
               } else {
                 const output = await renderAsync(routeContent);
@@ -1909,7 +1898,7 @@ function createAPIRoute(handler) {
     _handlers["GET"] = handler;
   }
   const api = {
-    _kind: "hsRoute",
+    _kind: "hsAPIRoute",
     get(handler2) {
       _handlers["GET"] = handler2;
       return api;
@@ -1988,21 +1977,40 @@ function getRunnableRoute(route) {
   throw new Error(`Route not runnable. Use "export default createRoute()" to create a Hyperspan route. Exported methods found were: ${Object.keys(route).join(", ")}`);
 }
 function isRunnableRoute(route) {
-  return typeof route === "object" && "_getRouteHandlers" in route;
+  if (typeof route !== "object") {
+    return false;
+  }
+  const obj = route;
+  const runnableKind = ["hsRoute", "hsAPIRoute", "hsAction"].includes(obj?._kind);
+  return runnableKind && "_getRouteHandlers" in obj;
 }
 async function showErrorReponse(context, err) {
-  const output = render(html`
-    <main>
-      <h1>Error</h1>
-      <pre>${err.message}</pre>
-      <pre>${!IS_PROD && err.stack ? err.stack.split(`
+  let status = 500;
+  const message = err.message || "Internal Server Error";
+  if (err instanceof HTTPException) {
+    status = err.status;
+  }
+  const stack = !IS_PROD && err.stack ? err.stack.split(`
 `).slice(1).join(`
-`) : ""}</pre>
-    </main>
+`) : "";
+  const output = render(html`
+    <!DOCTYPE html>
+    <html lang="en">
+      <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Application Error</title>
+      </head>
+      <body>
+        <main>
+          <h1>Application Error</h1>
+          <strong>${message}</strong>
+          ${stack ? html`<pre>${stack}</pre>` : ""}
+        </main>
+      </body>
+    </html>
   `);
-  return context.html(output, {
-    status: 500
-  });
+  return context.html(output, { status });
 }
 var ROUTE_SEGMENT = /(\[[a-zA-Z_\.]+\])/g;
 async function buildRoutes(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Hyperspan Web Framework",
   "main": "dist/server.ts",
   "types": "src/server.ts",
@@ -17,13 +17,17 @@
       "types": "./src/server.ts",
       "default": "./dist/server.js"
     },
-    "./actions": {
-      "types": "./src/actions.ts",
-      "default": "./src/actions.ts"
-    },
     "./assets": {
       "types": "./src/assets.ts",
       "default": "./dist/assets.js"
+    },
+    "./middleware": {
+      "types": "./src/middleware.ts",
+      "default": "./dist/middleware.js"
+    },
+    "./unstable/actions": {
+      "types": "./src/actions.ts",
+      "default": "./src/actions.ts"
     }
   },
   "author": "Vance Lucas <vance@vancelucas.com>",
@@ -56,6 +60,7 @@
     "@types/bun": "^1.2.14",
     "@types/node": "^22.15.20",
     "@types/react": "^19.1.5",
+    "@types/timestring": "^7.0.0",
     "prettier": "^3.5.3",
     "typescript": "^5.8.3"
   },
@@ -63,6 +68,7 @@
     "@hyperspan/html": "^0.1.7",
     "hono": "^4.7.10",
     "isbot": "^5.1.28",
-    "zod": "^3.25.42"
+    "timestring": "^7.0.0",
+    "zod": "^3.25.67"
   }
 }

package/src/actions.test.ts

@@ -1,5 +1,5 @@
-import z from 'zod/v4';
-import { createAction } from './actions';
+import { z } from 'zod';
+import { unstable__createAction } from './actions';
 import { describe, it, expect } from 'bun:test';
 import { html, render, type HSHtml } from '@hyperspan/html';
 import type { Context } from 'hono';
@@ -22,7 +22,7 @@ describe('createAction', () => {
       const schema = z.object({
         name: z.string(),
       });
-      const action = createAction(schema, formWithNameOnly);
+      const action = unstable__createAction(schema, formWithNameOnly);
 
       const formResponse = render(action.render({ data: { name: 'John' } }) as HSHtml);
       expect(formResponse).toContain('value="John"');
@@ -34,7 +34,7 @@ describe('createAction', () => {
       const schema = z.object({
         name: z.string().nonempty(),
       });
-      const action = createAction(schema, formWithNameOnly)
+      const action = unstable__createAction(schema, formWithNameOnly)
         .post((c, { data }) => {
           return html`<div>Thanks for submitting the form, ${data?.name}!</div>`;
         })
@@ -65,7 +65,7 @@ describe('createAction', () => {
       const schema = z.object({
         name: z.string().nonempty(),
       });
-      const action = createAction(schema)
+      const action = unstable__createAction(schema)
         .form(formWithNameOnly)
         .post((c, { data }) => {
           return html`<div>Thanks for submitting the form, ${data?.name}!</div>`;

package/src/actions.ts

@@ -32,7 +32,7 @@ export interface HSAction<T extends z.ZodTypeAny> {
   run(method: 'GET' | 'POST', c: Context): Promise<THSResponseTypes>;
 }
 
-export function createAction<T extends z.ZodTypeAny>(
+export function unstable__createAction<T extends z.ZodTypeAny>(
   schema: T | null = null,
   form: Parameters<HSAction<T>['form']>[0] | null = null
 ) {
@@ -87,7 +87,7 @@ export function createAction<T extends z.ZodTypeAny>(
       }
 
       const formData = await c.req.formData();
-      const jsonData = formDataToJSON(formData);
+      const jsonData = unstable__formDataToJSON(formData);
       const schemaData = schema ? schema.safeParse(jsonData) : null;
       const data = schemaData?.success ? (schemaData.data as z.infer<T>) : undefined;
       let error: z.ZodError | Error | null = null;
@@ -128,7 +128,7 @@ export type THSHandlerResponse = (context: Context) => THSResponseTypes | Promis
  *
  * @link https://stackoverflow.com/a/75406413
  */
-export function formDataToJSON(formData: FormData): Record<string, string | string[]> {
+export function unstable__formDataToJSON(formData: FormData): Record<string, string | string[]> {
   let object = {};
 
   /**

package/src/assets.ts

@@ -3,6 +3,11 @@ import { createHash } from 'node:crypto';
 import { readdir } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
+export type THSIslandOptions = {
+  ssr?: boolean;
+  loading?: 'lazy' | undefined;
+};
+
 const IS_PROD = process.env.NODE_ENV === 'production';
 const PWD = import.meta.dir;
 
@@ -97,24 +102,15 @@ export function assetHash(content: string): string {
  * Island defaults
  */
 export const ISLAND_PUBLIC_PATH = '/_hs/js/islands';
-export const ISLAND_DEFAULTS = () => ({
+export const ISLAND_DEFAULTS: () => THSIslandOptions = () => ({
   ssr: true,
+  loading: undefined,
 });
 
 export function renderIsland(Component: any, props: any, options = ISLAND_DEFAULTS()) {
-  // Render is an OPTIONAL override that allows you to render the island with your own logic
+  // Render island with its own logic
   if (Component.__HS_ISLAND?.render) {
-    return Component.__HS_ISLAND.render(props, options);
-  }
-
-  // If ssr is true, render the island with the ssr function
-  if (Component.__HS_ISLAND?.ssr && options.ssr) {
-    return Component.__HS_ISLAND.ssr(props);
-  }
-
-  // If ssr is false, render the island with the clientOnly function
-  if (Component.__HS_ISLAND?.clientOnly) {
-    return Component.__HS_ISLAND.clientOnly(props);
+    return html.raw(Component.__HS_ISLAND.render(props, options));
   }
 
   throw new Error(

package/src/clientjs/hyperspan-client.ts

@@ -1,5 +1,5 @@
 import { html } from '@hyperspan/html';
-import { Idiomorph } from './idiomorph.esm';
+import { Idiomorph } from './idiomorph';
 
 /**
  * Used for streaming content from the server to the client.
@@ -31,6 +31,9 @@ function htmlAsyncContentObserver() {
               Idiomorph.morph(slotEl, el.content.cloneNode(true));
               el.parentNode.removeChild(el);
             });
+
+            // Lazy load scripts (if any) after the content is inserted
+            lazyLoadScripts();
           }
         } catch (e) {
           console.error(e);
@@ -122,5 +125,37 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement) {
     });
 }
 
+/**
+ * Intersection observer for lazy loading <script> tags
+ */
+const lazyLoadScriptObserver = new IntersectionObserver(
+  (entries, observer) => {
+    entries
+      .filter((entry) => entry.isIntersecting)
+      .forEach((entry) => {
+        observer.unobserve(entry.target);
+        // @ts-ignore
+        if (entry.target.children[0]?.content) {
+          // @ts-ignore
+          entry.target.replaceWith(entry.target.children[0].content);
+        }
+      });
+  },
+  { rootMargin: '0px 0px -200px 0px' }
+);
+
+/**
+ * Lazy load <script> tags in the current document
+ */
+function lazyLoadScripts() {
+  document
+    .querySelectorAll('div[data-loading=lazy]')
+    .forEach((el) => lazyLoadScriptObserver.observe(el));
+}
+
+window.addEventListener('load', () => {
+  lazyLoadScripts();
+});
+
 // @ts-ignore
 window.html = html;

package/src/clientjs/{idiomorph.esm.js → idiomorph.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck
 /**
  * @typedef {object} ConfigHead
  *
@@ -206,9 +207,8 @@ var Idiomorph = (function () {
    */
   function saveAndRestoreFocus(ctx, fn) {
     if (!ctx.config.restoreFocus) return fn();
-    let activeElement = /** @type {HTMLInputElement|HTMLTextAreaElement|null} */ (
-      document.activeElement
-    );
+    let activeElement =
+      /** @type {HTMLInputElement|HTMLTextAreaElement|null} */ document.activeElement;
 
     // don't bother if the active element is not an input or textarea
     if (
@@ -324,7 +324,7 @@ var Idiomorph = (function () {
       if (ctx.callbacks.beforeNodeAdded(newChild) === false) return null;
       if (ctx.idMap.has(newChild)) {
         // node has children with ids with possible state so create a dummy elt of same type and apply full morph algorithm
-        const newEmptyChild = document.createElement(/** @type {Element} */ (newChild).tagName);
+        const newEmptyChild = document.createElement(/** @type {Element} */ newChild.tagName);
         oldParent.insertBefore(newEmptyChild, insertionPoint);
         morphNode(newEmptyChild, newChild, ctx);
         ctx.callbacks.afterNodeAdded(newEmptyChild);
@@ -431,8 +431,8 @@ var Idiomorph = (function () {
        */
       function isSoftMatch(oldNode, newNode) {
         // ok to cast: if one is not element, `id` and `tagName` will be undefined and we'll just compare that.
-        const oldElt = /** @type {Element} */ (oldNode);
-        const newElt = /** @type {Element} */ (newNode);
+        const oldElt = /** @type {Element} */ oldNode;
+        const newElt = /** @type {Element} */ newNode;
 
         return (
           oldElt.nodeType === newElt.nodeType &&
@@ -483,7 +483,7 @@ var Idiomorph = (function () {
       let cursor = startInclusive;
       // remove nodes until the endExclusive node
       while (cursor && cursor !== endExclusive) {
-        let tempNode = /** @type {Node} */ (cursor);
+        let tempNode = /** @type {Node} */ cursor;
         cursor = cursor.nextSibling;
         removeNode(ctx, tempNode);
       }
@@ -503,11 +503,9 @@ var Idiomorph = (function () {
     function moveBeforeById(parentNode, id, after, ctx) {
       const target =
         /** @type {Element} - will always be found */
-        (
-          (ctx.target.id === id && ctx.target) ||
-            ctx.target.querySelector(`[id="${id}"]`) ||
-            ctx.pantry.querySelector(`[id="${id}"]`)
-        );
+        (ctx.target.id === id && ctx.target) ||
+        ctx.target.querySelector(`[id="${id}"]`) ||
+        ctx.pantry.querySelector(`[id="${id}"]`);
       removeElementFromAncestorsIdMaps(target, ctx);
       moveBefore(parentNode, target, after);
       return target;
@@ -587,7 +585,7 @@ var Idiomorph = (function () {
         // ignore the head element
       } else if (oldNode instanceof HTMLHeadElement && ctx.head.style !== 'morph') {
         // ok to cast: if newContent wasn't also a <head>, it would've got caught in the `!isSoftMatch` branch above
-        handleHeadElement(oldNode, /** @type {HTMLHeadElement} */ (newContent), ctx);
+        handleHeadElement(oldNode, /** @type {HTMLHeadElement} */ newContent, ctx);
       } else {
         morphAttributes(oldNode, newContent, ctx);
         if (!ignoreValueOfActiveElement(oldNode, ctx)) {
@@ -613,8 +611,8 @@ var Idiomorph = (function () {
       // if is an element type, sync the attributes from the
       // new node into the new node
       if (type === 1 /* element type */) {
-        const oldElt = /** @type {Element} */ (oldNode);
-        const newElt = /** @type {Element} */ (newNode);
+        const oldElt = /** @type {Element} */ oldNode;
+        const newElt = /** @type {Element} */ newNode;
 
         const oldAttributes = oldElt.attributes;
         const newAttributes = newElt.attributes;
@@ -868,9 +866,9 @@ var Idiomorph = (function () {
     let promises = [];
     for (const newNode of nodesToAppend) {
       // TODO: This could theoretically be null, based on type
-      let newElt = /** @type {ChildNode} */ (
-        document.createRange().createContextualFragment(newNode.outerHTML).firstChild
-      );
+      let newElt = /** @type {ChildNode} */ document
+        .createRange()
+        .createContextualFragment(newNode.outerHTML).firstChild;
       if (ctx.callbacks.beforeNodeAdded(newElt) !== false) {
         if (('href' in newElt && newElt.href) || ('src' in newElt && newElt.src)) {
           /** @type {(result?: any) => void} */ let resolve;
@@ -1116,16 +1114,16 @@ var Idiomorph = (function () {
         return document.createElement('div'); // dummy parent element
       } else if (typeof newContent === 'string') {
         return normalizeParent(parseContent(newContent));
-      } else if (generatedByIdiomorph.has(/** @type {Element} */ (newContent))) {
+      } else if (generatedByIdiomorph.has(/** @type {Element} */ newContent)) {
         // the template tag created by idiomorph parsing can serve as a dummy parent
-        return /** @type {Element} */ (newContent);
+        return /** @type {Element} */ newContent;
       } else if (newContent instanceof Node) {
         if (newContent.parentNode) {
           // we can't use the parent directly because newContent may have siblings
           // that we don't want in the morph, and reparenting might be expensive (TODO is it?),
           // so instead we create a fake parent node that only sees a slice of its children.
           /** @type {Element} */
-          return /** @type {any} */ (new SlicedParentNode(newContent));
+          return /** @type {any} */ new SlicedParentNode(newContent);
         } else {
           // a single node is added as a child to a dummy parent
           const dummyParent = document.createElement('div');
@@ -1154,7 +1152,7 @@ var Idiomorph = (function () {
       /** @param {Node} node */
       constructor(node) {
         this.originalNode = node;
-        this.realParentNode = /** @type {Element} */ (node.parentNode);
+        this.realParentNode = /** @type {Element} */ node.parentNode;
         this.previousSibling = node.previousSibling;
         this.nextSibling = node.nextSibling;
       }
@@ -1178,16 +1176,19 @@ var Idiomorph = (function () {
        * @returns {Element[]}
        */
       querySelectorAll(selector) {
-        return this.childNodes.reduce((results, node) => {
-          if (node instanceof Element) {
-            if (node.matches(selector)) results.push(node);
-            const nodeList = node.querySelectorAll(selector);
-            for (let i = 0; i < nodeList.length; i++) {
-              results.push(nodeList[i]);
+        return this.childNodes.reduce(
+          (results, node) => {
+            if (node instanceof Element) {
+              if (node.matches(selector)) results.push(node);
+              const nodeList = node.querySelectorAll(selector);
+              for (let i = 0; i < nodeList.length; i++) {
+                results.push(nodeList[i]);
+              }
             }
-          }
-          return results;
-        }, /** @type {Element[]} */ ([]));
+            return results;
+          },
+          /** @type {Element[]} */ []
+        );
       }
 
       /**
@@ -1255,9 +1256,8 @@ var Idiomorph = (function () {
           '<body><template>' + newContent + '</template></body>',
           'text/html'
         );
-        let content = /** @type {HTMLTemplateElement} */ (
-          responseDoc.body.querySelector('template')
-        ).content;
+        let content =
+          /** @type {HTMLTemplateElement} */ responseDoc.body.querySelector('template').content;
         generatedByIdiomorph.add(content);
         return content;
       }

package/src/middleware.ts

@@ -0,0 +1,19 @@
+import { Context, Next } from 'hono';
+import { etag } from 'hono/etag';
+import timestring from 'timestring';
+
+/**
+ * Cache the response for a given time length ('30s', '1d', '1w', '1m', etc) or given number of seconds
+ */
+export function cacheTime(timeStrOrSeconds: string | number) {
+  return (c: Context, next: Next) =>
+    etag()(c, () => {
+      // Only cache GET requests
+      if (c.req.method.toUpperCase() === 'GET') {
+        const timeInSeconds =
+          typeof timeStrOrSeconds === 'number' ? timeStrOrSeconds : timestring(timeStrOrSeconds);
+        c.header('Cache-Control', `public, max-age=${timeInSeconds}`);
+      }
+      return next();
+    });
+}

package/src/server.ts

@@ -6,7 +6,9 @@ import { buildClientJS, buildClientCSS } from './assets';
 import { Hono, type Context } from 'hono';
 import { serveStatic } from 'hono/bun';
 import { HTTPException } from 'hono/http-exception';
+
 import type { HandlerResponse, MiddlewareHandler } from 'hono/types';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
 
 export const IS_PROD = process.env.NODE_ENV === 'production';
 const CWD = process.cwd();
@@ -22,9 +24,6 @@ export type THSRoute = {
   _kind: 'hsRoute';
   get: (handler: THSRouteHandler) => THSRoute;
   post: (handler: THSRouteHandler) => THSRoute;
-  put: (handler: THSRouteHandler) => THSRoute;
-  delete: (handler: THSRouteHandler) => THSRoute;
-  patch: (handler: THSRouteHandler) => THSRoute;
   middleware: (middleware: Array<MiddlewareHandler>) => THSRoute;
   _getRouteHandlers: () => Array<MiddlewareHandler | ((context: Context) => HandlerResponse<any>)>;
 };
@@ -57,26 +56,23 @@ export function createRoute(handler?: THSRouteHandler): THSRoute {
 
   const api: THSRoute = {
     _kind: 'hsRoute',
+    /**
+     * Add a GET route handler (primary page display)
+     */
     get(handler: THSRouteHandler) {
       _handlers['GET'] = handler;
       return api;
     },
+    /**
+     * Add a POST route handler (typically to process form data)
+     */
     post(handler: THSRouteHandler) {
       _handlers['POST'] = handler;
       return api;
     },
-    put(handler: THSRouteHandler) {
-      _handlers['PUT'] = handler;
-      return api;
-    },
-    delete(handler: THSRouteHandler) {
-      _handlers['DELETE'] = handler;
-      return api;
-    },
-    patch(handler: THSRouteHandler) {
-      _handlers['PATCH'] = handler;
-      return api;
-    },
+    /**
+     * Add middleware specific to this route
+     */
     middleware(middleware: Array<MiddlewareHandler>) {
       _middleware = middleware;
       return api;
@@ -107,7 +103,8 @@ export function createRoute(handler?: THSRouteHandler): THSRoute {
 
             // Render HSHtml if returned from route handler
             if (isHSHtml(routeContent)) {
-              if (streamingEnabled) {
+              // Stream only if enabled and there is async content to stream
+              if (streamingEnabled && (routeContent as HSHtml).asyncContent?.length > 0) {
                 return new StreamResponse(renderStream(routeContent as HSHtml)) as Response;
               } else {
                 const output = await renderAsync(routeContent as HSHtml);
@@ -147,7 +144,7 @@ export function createAPIRoute(handler?: THSAPIRouteHandler): THSAPIRoute {
   }
 
   const api: THSAPIRoute = {
-    _kind: 'hsRoute',
+    _kind: 'hsAPIRoute',
     get(handler: THSAPIRouteHandler) {
       _handlers['GET'] = handler;
       return api;
@@ -256,9 +253,18 @@ export function getRunnableRoute(route: unknown): THSRoute {
   );
 }
 
+/**
+ * Check if a route is runnable by Hyperspan
+ */
 export function isRunnableRoute(route: unknown): boolean {
-  // @ts-ignore
-  return typeof route === 'object' && '_getRouteHandlers' in route;
+  if (typeof route !== 'object') {
+    return false;
+  }
+
+  const obj = route as { _kind: string; _getRouteHandlers: any };
+  const runnableKind = ['hsRoute', 'hsAPIRoute', 'hsAction'].includes(obj?._kind);
+
+  return runnableKind && '_getRouteHandlers' in obj;
 }
 
 /**
@@ -266,17 +272,35 @@ export function isRunnableRoute(route: unknown): boolean {
  * @TODO: Should check for and load user-customizeable template with special name (app/__error.ts ?)
  */
 async function showErrorReponse(context: Context, err: Error) {
+  let status: ContentfulStatusCode = 500;
+  const message = err.message || 'Internal Server Error';
+
+  // Send correct status code if HTTPException
+  if (err instanceof HTTPException) {
+    status = err.status as ContentfulStatusCode;
+  }
+
+  const stack = !IS_PROD && err.stack ? err.stack.split('\n').slice(1).join('\n') : '';
+
   const output = render(html`
-    <main>
-      <h1>Error</h1>
-      <pre>${err.message}</pre>
-      <pre>${!IS_PROD && err.stack ? err.stack.split('\n').slice(1).join('\n') : ''}</pre>
-    </main>
+    <!DOCTYPE html>
+    <html lang="en">
+      <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Application Error</title>
+      </head>
+      <body>
+        <main>
+          <h1>Application Error</h1>
+          <strong>${message}</strong>
+          ${stack ? html`<pre>${stack}</pre>` : ''}
+        </main>
+      </body>
+    </html>
   `);
 
-  return context.html(output, {
-    status: 500,
-  });
+  return context.html(output, { status });
 }
 
 export type THSServerConfig = {

package/src/clientjs/md5.js

@@ -1,176 +0,0 @@
-/**
- * Fast browser md5 function (used for static asset hashing)
- * @link https://www.myersdaily.org/joseph/javascript/md5.js
- */
-function md5cycle(x, k) {
-  var a = x[0],
-    b = x[1],
-    c = x[2],
-    d = x[3];
-
-  a = ff(a, b, c, d, k[0], 7, -680876936);
-  d = ff(d, a, b, c, k[1], 12, -389564586);
-  c = ff(c, d, a, b, k[2], 17, 606105819);
-  b = ff(b, c, d, a, k[3], 22, -1044525330);
-  a = ff(a, b, c, d, k[4], 7, -176418897);
-  d = ff(d, a, b, c, k[5], 12, 1200080426);
-  c = ff(c, d, a, b, k[6], 17, -1473231341);
-  b = ff(b, c, d, a, k[7], 22, -45705983);
-  a = ff(a, b, c, d, k[8], 7, 1770035416);
-  d = ff(d, a, b, c, k[9], 12, -1958414417);
-  c = ff(c, d, a, b, k[10], 17, -42063);
-  b = ff(b, c, d, a, k[11], 22, -1990404162);
-  a = ff(a, b, c, d, k[12], 7, 1804603682);
-  d = ff(d, a, b, c, k[13], 12, -40341101);
-  c = ff(c, d, a, b, k[14], 17, -1502002290);
-  b = ff(b, c, d, a, k[15], 22, 1236535329);
-
-  a = gg(a, b, c, d, k[1], 5, -165796510);
-  d = gg(d, a, b, c, k[6], 9, -1069501632);
-  c = gg(c, d, a, b, k[11], 14, 643717713);
-  b = gg(b, c, d, a, k[0], 20, -373897302);
-  a = gg(a, b, c, d, k[5], 5, -701558691);
-  d = gg(d, a, b, c, k[10], 9, 38016083);
-  c = gg(c, d, a, b, k[15], 14, -660478335);
-  b = gg(b, c, d, a, k[4], 20, -405537848);
-  a = gg(a, b, c, d, k[9], 5, 568446438);
-  d = gg(d, a, b, c, k[14], 9, -1019803690);
-  c = gg(c, d, a, b, k[3], 14, -187363961);
-  b = gg(b, c, d, a, k[8], 20, 1163531501);
-  a = gg(a, b, c, d, k[13], 5, -1444681467);
-  d = gg(d, a, b, c, k[2], 9, -51403784);
-  c = gg(c, d, a, b, k[7], 14, 1735328473);
-  b = gg(b, c, d, a, k[12], 20, -1926607734);
-
-  a = hh(a, b, c, d, k[5], 4, -378558);
-  d = hh(d, a, b, c, k[8], 11, -2022574463);
-  c = hh(c, d, a, b, k[11], 16, 1839030562);
-  b = hh(b, c, d, a, k[14], 23, -35309556);
-  a = hh(a, b, c, d, k[1], 4, -1530992060);
-  d = hh(d, a, b, c, k[4], 11, 1272893353);
-  c = hh(c, d, a, b, k[7], 16, -155497632);
-  b = hh(b, c, d, a, k[10], 23, -1094730640);
-  a = hh(a, b, c, d, k[13], 4, 681279174);
-  d = hh(d, a, b, c, k[0], 11, -358537222);
-  c = hh(c, d, a, b, k[3], 16, -722521979);
-  b = hh(b, c, d, a, k[6], 23, 76029189);
-  a = hh(a, b, c, d, k[9], 4, -640364487);
-  d = hh(d, a, b, c, k[12], 11, -421815835);
-  c = hh(c, d, a, b, k[15], 16, 530742520);
-  b = hh(b, c, d, a, k[2], 23, -995338651);
-
-  a = ii(a, b, c, d, k[0], 6, -198630844);
-  d = ii(d, a, b, c, k[7], 10, 1126891415);
-  c = ii(c, d, a, b, k[14], 15, -1416354905);
-  b = ii(b, c, d, a, k[5], 21, -57434055);
-  a = ii(a, b, c, d, k[12], 6, 1700485571);
-  d = ii(d, a, b, c, k[3], 10, -1894986606);
-  c = ii(c, d, a, b, k[10], 15, -1051523);
-  b = ii(b, c, d, a, k[1], 21, -2054922799);
-  a = ii(a, b, c, d, k[8], 6, 1873313359);
-  d = ii(d, a, b, c, k[15], 10, -30611744);
-  c = ii(c, d, a, b, k[6], 15, -1560198380);
-  b = ii(b, c, d, a, k[13], 21, 1309151649);
-  a = ii(a, b, c, d, k[4], 6, -145523070);
-  d = ii(d, a, b, c, k[11], 10, -1120210379);
-  c = ii(c, d, a, b, k[2], 15, 718787259);
-  b = ii(b, c, d, a, k[9], 21, -343485551);
-
-  x[0] = add32(a, x[0]);
-  x[1] = add32(b, x[1]);
-  x[2] = add32(c, x[2]);
-  x[3] = add32(d, x[3]);
-}
-
-function cmn(q, a, b, x, s, t) {
-  a = add32(add32(a, q), add32(x, t));
-  return add32((a << s) | (a >>> (32 - s)), b);
-}
-
-function ff(a, b, c, d, x, s, t) {
-  return cmn((b & c) | (~b & d), a, b, x, s, t);
-}
-
-function gg(a, b, c, d, x, s, t) {
-  return cmn((b & d) | (c & ~d), a, b, x, s, t);
-}
-
-function hh(a, b, c, d, x, s, t) {
-  return cmn(b ^ c ^ d, a, b, x, s, t);
-}
-
-function ii(a, b, c, d, x, s, t) {
-  return cmn(c ^ (b | ~d), a, b, x, s, t);
-}
-
-function md51(s) {
-  var txt = '';
-  var n = s.length,
-    state = [1732584193, -271733879, -1732584194, 271733878],
-    i;
-  for (i = 64; i <= s.length; i += 64) {
-    md5cycle(state, md5blk(s.substring(i - 64, i)));
-  }
-  s = s.substring(i - 64);
-  var tail = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
-  for (i = 0; i < s.length; i++) tail[i >> 2] |= s.charCodeAt(i) << (i % 4 << 3);
-  tail[i >> 2] |= 0x80 << (i % 4 << 3);
-  if (i > 55) {
-    md5cycle(state, tail);
-    for (i = 0; i < 16; i++) tail[i] = 0;
-  }
-  tail[14] = n * 8;
-  md5cycle(state, tail);
-  return state;
-}
-
-/* there needs to be support for Unicode here,
- * unless we pretend that we can redefine the MD-5
- * algorithm for multi-byte characters (perhaps
- * by adding every four 16-bit characters and
- * shortening the sum to 32 bits). Otherwise
- * I suggest performing MD-5 as if every character
- * was two bytes--e.g., 0040 0025 = @%--but then
- * how will an ordinary MD-5 sum be matched?
- * There is no way to standardize text to something
- * like UTF-8 before transformation; speed cost is
- * utterly prohibitive. The JavaScript standard
- * itself needs to look at this: it should start
- * providing access to strings as preformed UTF-8
- * 8-bit unsigned value arrays.
- */
-function md5blk(s) {
-  /* I figured global was faster.   */
-  var md5blks = [],
-    i; /* Andy King said do it this way. */
-  for (i = 0; i < 64; i += 4) {
-    md5blks[i >> 2] =
-      s.charCodeAt(i) +
-      (s.charCodeAt(i + 1) << 8) +
-      (s.charCodeAt(i + 2) << 16) +
-      (s.charCodeAt(i + 3) << 24);
-  }
-  return md5blks;
-}
-
-var hex_chr = '0123456789abcdef'.split('');
-
-function rhex(n) {
-  var s = '',
-    j = 0;
-  for (; j < 4; j++) s += hex_chr[(n >> (j * 8 + 4)) & 0x0f] + hex_chr[(n >> (j * 8)) & 0x0f];
-  return s;
-}
-
-function hex(x) {
-  for (var i = 0; i < x.length; i++) x[i] = rhex(x[i]);
-  return x.join('');
-}
-
-function add32(a, b) {
-  return (a + b) & 0xffffffff;
-}
-
-export function md5(s) {
-  return hex(md51(s));
-}

package/src/clientjs/preact.ts

@@ -1,3 +0,0 @@
-export * from 'preact/compat';
-export * from 'preact/hooks';
-export { h, render, hydrate } from 'preact';