@hyperspan/framework 0.1.6 → 0.1.8

package/build.ts

@@ -1,4 +1,4 @@
-import {build} from 'bun';
+import { build } from 'bun';
 
 const entrypoints = ['./src/server.ts', './src/assets.ts'];
 const external = ['@hyperspan/html'];

package/dist/assets.js

@@ -1,5 +1,6 @@
 // src/assets.ts
 import { html } from "@hyperspan/html";
+import { createHash } from "node:crypto";
 import { readdir } from "node:fs/promises";
 import { resolve } from "node:path";
 var IS_PROD = false;
@@ -45,15 +46,7 @@ function hyperspanScriptTags() {
   const jsFiles = Array.from(clientJSFiles.entries());
   return html`
     <script type="importmap">
-      {
-        "imports": {
-          "preact": "https://esm.sh/preact@10.26.4",
-          "preact/": "https://esm.sh/preact@10.26.4/",
-          "react": "https://esm.sh/preact@10.26.4/compat",
-          "react/": "https://esm.sh/preact@10.26.4/compat/",
-          "react-dom": "https://esm.sh/preact@10.26.4/compat"
-        }
-      }
+      {"imports": ${Object.fromEntries(clientImportMap)}}
     </script>
     ${jsFiles.map(([key, file]) => html`<script
           id="js-${key}"
@@ -62,9 +55,63 @@ function hyperspanScriptTags() {
         ></script>`)}
   `;
 }
+var PREACT_PUBLIC_FILE_PATH = "/_hs/js/preact.js";
+function md5(content) {
+  return createHash("md5").update(content).digest("hex");
+}
+async function copyPreactToPublicFolder() {
+  const sourceFile = resolve(PWD, "../", "./src/clientjs/preact.ts");
+  await Bun.build({
+    entrypoints: [sourceFile],
+    outdir: "./public/_hs/js",
+    minify: true,
+    format: "esm",
+    target: "browser"
+  });
+}
+async function createPreactIsland(file) {
+  let filePath = file.replace("file://", "");
+  const jsId = md5(filePath);
+  if (!clientImportMap.has("preact")) {
+    await copyPreactToPublicFolder();
+    clientImportMap.set("preact", "" + PREACT_PUBLIC_FILE_PATH);
+    clientImportMap.set("preact/compat", "" + PREACT_PUBLIC_FILE_PATH);
+    clientImportMap.set("preact/hooks", "" + PREACT_PUBLIC_FILE_PATH);
+    clientImportMap.set("preact/jsx-runtime", "" + PREACT_PUBLIC_FILE_PATH);
+  }
+  if (!clientImportMap.has("react")) {
+    clientImportMap.set("react", "." + PREACT_PUBLIC_FILE_PATH);
+    clientImportMap.set("react-dom", "." + PREACT_PUBLIC_FILE_PATH);
+  }
+  let resultStr = 'import{h,render}from"preact";';
+  const buildResult = await Bun.build({
+    entrypoints: [filePath],
+    minify: true,
+    external: ["react", "preact"],
+    env: "APP_PUBLIC_*"
+  });
+  for (const output of buildResult.outputs) {
+    resultStr += await output.text();
+  }
+  const r = /export\{([a-zA-Z]+) as default\}/g;
+  const matchExport = r.exec(resultStr);
+  if (!matchExport) {
+    throw new Error("File does not have a default export! Ensure a function has export default to use this.");
+  }
+  const fn = matchExport[1];
+  let _mounted = false;
+  return (props) => {
+    if (!_mounted) {
+      _mounted = true;
+      resultStr += `render(h(${fn}, ${JSON.stringify(props)}), document.getElementById("${jsId}"));`;
+    }
+    return html.raw(`<div id="${jsId}"></div><script type="module" data-source-id="${jsId}">${resultStr}</script>`);
+  };
+}
 export {
   hyperspanStyleTags,
   hyperspanScriptTags,
+  createPreactIsland,
   clientJSFiles,
   clientImportMap,
   clientCSSFiles,

package/dist/server.js

@@ -6,7 +6,7 @@ import {
 // src/server.ts
 import { readdir } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
-import { TmplHtml, html, renderStream, renderAsync, render } from "@hyperspan/html";
+import { html, isHSHtml, renderStream, renderAsync, render } from "@hyperspan/html";
 
 // node_modules/isbot/index.mjs
 var fullPattern = " daum[ /]| deusu/| yadirectfetcher|(?:^|[^g])news(?!sapphire)|(?<! (?:channel/|google/))google(?!(app|/google| pixel))|(?<! cu)bots?(?:\\b|_)|(?<!(?:lib))http|(?<![hg]m)score|@[a-z][\\w-]+\\.|\\(\\)|\\.com\\b|\\btime/|\\||^<|^[\\w \\.\\-\\(?:\\):%]+(?:/v?\\d+(?:\\.\\d+)?(?:\\.\\d{1,10})*?)?(?:,|$)|^[^ ]{50,}$|^\\d+\\b|^\\w*search\\b|^\\w+/[\\w\\(\\)]*$|^active|^ad muncher|^amaya|^avsdevicesdk/|^biglotron|^bot|^bw/|^clamav[ /]|^client/|^cobweb/|^custom|^ddg[_-]android|^discourse|^dispatch/\\d|^downcast/|^duckduckgo|^email|^facebook|^getright/|^gozilla/|^hobbit|^hotzonu|^hwcdn/|^igetter/|^jeode/|^jetty/|^jigsaw|^microsoft bits|^movabletype|^mozilla/\\d\\.\\d\\s[\\w\\.-]+$|^mozilla/\\d\\.\\d\\s\\(compatible;?(?:\\s\\w+\\/\\d+\\.\\d+)?\\)$|^navermailapp|^netsurf|^offline|^openai/|^owler|^php|^postman|^python|^rank|^read|^reed|^rest|^rss|^snapchat|^space bison|^svn|^swcd |^taringa|^thumbor/|^track|^w3c|^webbandit/|^webcopier|^wget|^whatsapp|^wordpress|^xenu link sleuth|^yahoo|^yandex|^zdm/\\d|^zoom marketplace/|^{{.*}}$|adscanner/|analyzer|archive|ask jeeves/teoma|audit|bit\\.ly/|bluecoat drtr|browsex|burpcollaborator|capture|catch|check\\b|checker|chrome-lighthouse|chromeframe|classifier|cloudflare|convertify|cookiehubscan|crawl|cypress/|dareboost|datanyze|dejaclick|detect|dmbrowser|download|evc-batch/|exaleadcloudview|feed|firephp|functionize|gomezagent|headless|httrack|hubspot marketing grader|hydra|ibisbrowser|infrawatch|insight|inspect|iplabel|ips-agent|java(?!;)|jsjcw_scanner|library|linkcheck|mail\\.ru/|manager|measure|neustar wpm|node|nutch|offbyone|onetrust|optimize|pageburst|pagespeed|parser|perl|phantomjs|pingdom|powermarks|preview|proxy|ptst[ /]\\d|retriever|rexx;|rigor|rss\\b|scanner\\.|scrape|server|sogou|sparkler/|speedcurve|spider|splash|statuscake|supercleaner|synapse|synthetic|tools|torrent|transcoder|url|validator|virtuoso|wappalyzer|webglance|webkit2png|whatcms/|zgrab";
@@ -1862,7 +1862,7 @@ function createRoute(handler) {
       const streamOpt = context.req.query("__nostream");
       const streamingEnabled = !userIsBot && (streamOpt !== undefined ? streamOpt : true);
       const routeKind = typeof routeContent;
-      if (routeContent && routeKind === "object" && (routeContent instanceof TmplHtml || routeContent.constructor.name === "TmplHtml" || routeContent?._kind === "TmplHtml")) {
+      if (isHSHtml(routeContent)) {
         if (streamingEnabled) {
           return new StreamResponse(renderStream(routeContent));
         } else {
@@ -1946,6 +1946,9 @@ function getRunnableRoute(route) {
 function isRunnableRoute(route) {
   return typeof route === "object" && "run" in route;
 }
+function createLayout(layout) {
+  return layout;
+}
 async function showErrorReponse(context, err) {
   const output = render(html`
     <main>
@@ -1963,7 +1966,6 @@ async function showErrorReponse(context, err) {
 var ROUTE_SEGMENT = /(\[[a-zA-Z_\.]+\])/g;
 async function buildRoutes(config) {
   const routesDir = join(config.appDir, "routes");
-  console.log(routesDir);
   const files = await readdir(routesDir, { recursive: true });
   const routes = [];
   for (const file of files) {
@@ -2090,6 +2092,7 @@ export {
   createRouteFromModule,
   createRoute,
   createReadableStreamFromAsyncGenerator,
+  createLayout,
   createAPIRoute,
   buildRoutes,
   StreamResponse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Hyperspan Web Framework",
   "main": "dist/server.js",
   "types": "src/server.ts",
@@ -64,10 +64,10 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "@hyperspan/html": "^0.1.5",
-    "@preact/compat": "^18.3.1",
+    "@hyperspan/html": "^0.1.6",
     "hono": "^4.7.4",
     "isbot": "^5.1.25",
+    "preact": "^10.26.5",
     "zod": "^4.0.0-beta.20250415T232143"
   }
 }

package/src/actions.test.ts

@@ -1,7 +1,7 @@
 import z from 'zod';
 import { createAction } from './actions';
 import { describe, it, expect } from 'bun:test';
-import { html, render, type TmplHtml } from '@hyperspan/html';
+import { html, render, type HSHtml } from '@hyperspan/html';
 import type { Context } from 'hono';
 
 describe('createAction', () => {
@@ -24,7 +24,7 @@ describe('createAction', () => {
       });
       const action = createAction(schema, formWithNameOnly);
 
-      const formResponse = render(action.render({ data: { name: 'John' } }) as TmplHtml);
+      const formResponse = render(action.render({ data: { name: 'John' } }) as HSHtml);
       expect(formResponse).toContain('value="John"');
     });
   });
@@ -55,7 +55,7 @@ describe('createAction', () => {
 
       const response = await action.run('POST', mockContext);
 
-      const formResponse = render(response as TmplHtml);
+      const formResponse = render(response as HSHtml);
       expect(formResponse).toContain('Thanks for submitting the form, John!');
     });
   });
@@ -87,7 +87,7 @@ describe('createAction', () => {
 
       const response = await action.run('POST', mockContext);
 
-      const formResponse = render(response as TmplHtml);
+      const formResponse = render(response as HSHtml);
       expect(formResponse).toContain('There was an error!');
     });
   });

package/src/actions.ts

@@ -1,4 +1,4 @@
-import { html, TmplHtml } from '@hyperspan/html';
+import { html, HSHtml } from '@hyperspan/html';
 import * as z from 'zod';
 import { HTTPException } from 'hono/http-exception';
 
@@ -20,7 +20,7 @@ import type { Context } from 'hono';
  */
 export interface HSAction<T extends z.ZodTypeAny> {
   _kind: string;
-  form(renderForm: ({ data }: { data?: z.infer<T> }) => TmplHtml): HSAction<T>;
+  form(renderForm: ({ data }: { data?: z.infer<T> }) => HSHtml): HSAction<T>;
   post(handler: (c: Context, { data }: { data?: z.infer<T> }) => THSResponseTypes): HSAction<T>;
   error(
     handler: (

package/src/assets.ts

@@ -1,4 +1,5 @@
 import { html } from '@hyperspan/html';
+import { createHash } from 'node:crypto';
 import { readdir } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
@@ -75,15 +76,7 @@ export function hyperspanScriptTags() {
 
   return html`
     <script type="importmap">
-      {
-        "imports": {
-          "preact": "https://esm.sh/preact@10.26.4",
-          "preact/": "https://esm.sh/preact@10.26.4/",
-          "react": "https://esm.sh/preact@10.26.4/compat",
-          "react/": "https://esm.sh/preact@10.26.4/compat/",
-          "react-dom": "https://esm.sh/preact@10.26.4/compat"
-        }
-      }
+      {"imports": ${Object.fromEntries(clientImportMap)}}
     </script>
     ${jsFiles.map(
       ([key, file]) =>
@@ -95,3 +88,83 @@ export function hyperspanScriptTags() {
     )}
   `;
 }
+
+// External ESM = https://esm.sh/preact@10.26.4/compat
+const PREACT_PUBLIC_FILE_PATH = '/_hs/js/preact.js';
+
+function md5(content: string): string {
+  return createHash('md5').update(content).digest('hex');
+}
+
+/**
+ * Build Preact client JS and copy to public folder
+ */
+async function copyPreactToPublicFolder() {
+  const sourceFile = resolve(PWD, '../', './src/clientjs/preact.ts');
+  await Bun.build({
+    entrypoints: [sourceFile],
+    outdir: './public/_hs/js',
+    minify: true,
+    format: 'esm',
+    target: 'browser',
+  });
+}
+
+/**
+ * Return a Preact component, mounted as an island in a <script> tag so it can be embedded into the page response.
+ */
+export async function createPreactIsland(file: string) {
+  let filePath = file.replace('file://', '');
+  const jsId = md5(filePath);
+
+  // Add Preact to client import map if not already present
+  if (!clientImportMap.has('preact')) {
+    await copyPreactToPublicFolder();
+    clientImportMap.set('preact', '' + PREACT_PUBLIC_FILE_PATH);
+    clientImportMap.set('preact/compat', '' + PREACT_PUBLIC_FILE_PATH);
+    clientImportMap.set('preact/hooks', '' + PREACT_PUBLIC_FILE_PATH);
+    clientImportMap.set('preact/jsx-runtime', '' + PREACT_PUBLIC_FILE_PATH);
+  }
+  if (!clientImportMap.has('react')) {
+    clientImportMap.set('react', '.' + PREACT_PUBLIC_FILE_PATH);
+    clientImportMap.set('react-dom', '.' + PREACT_PUBLIC_FILE_PATH);
+  }
+
+  let resultStr = 'import{h,render}from"preact";';
+  const buildResult = await Bun.build({
+    entrypoints: [filePath],
+    minify: true,
+    external: ['react', 'preact'],
+    // @ts-ignore
+    env: 'APP_PUBLIC_*', // Inlines any ENV that starts with 'APP_PUBLIC_'
+  });
+
+  for (const output of buildResult.outputs) {
+    resultStr += await output.text(); // string
+  }
+
+  // Find default export - this is our component
+  const r = /export\{([a-zA-Z]+) as default\}/g;
+  const matchExport = r.exec(resultStr);
+
+  if (!matchExport) {
+    throw new Error(
+      'File does not have a default export! Ensure a function has export default to use this.'
+    );
+  }
+
+  // Preact render/mount component
+  const fn = matchExport[1];
+  let _mounted = false;
+
+  // Return HTML that will embed this component
+  return (props: any) => {
+    if (!_mounted) {
+      _mounted = true;
+      resultStr += `render(h(${fn}, ${JSON.stringify(props)}), document.getElementById("${jsId}"));`;
+    }
+    return html.raw(
+      `<div id="${jsId}"></div><script type="module" data-source-id="${jsId}">${resultStr}</script>`
+    );
+  };
+}

package/src/clientjs/hyperspan-client.ts

@@ -26,14 +26,10 @@ function htmlAsyncContentObserver() {
           const slotEl = document.getElementById(slotId);
 
           if (slotEl) {
-            // Wait until next paint for streaming content to finish writing to DOM
-            // @TODO: Need a more guaranteed way to know HTML element is done streaming in...
-            // Maybe some ".end" element that is hidden and then removed before insertion?
-            requestAnimationFrame(() => {
-              setTimeout(() => {
-                Idiomorph.morph(slotEl, el.content.cloneNode(true));
-                el.parentNode.removeChild(el);
-              }, 100);
+            // Only insert the content if it is done streaming in
+            waitForEndContent(el.content).then(() => {
+              Idiomorph.morph(slotEl, el.content.cloneNode(true));
+              el.parentNode.removeChild(el);
             });
           }
         } catch (e) {
@@ -46,6 +42,25 @@ function htmlAsyncContentObserver() {
 }
 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.
+ */
+async function waitForEndContent(el: HTMLElement) {
+  return new Promise((resolve) => {
+    const interval = setInterval(() => {
+      const endComment = Array.from(el.childNodes).find((node) => {
+        return node.nodeType === Node.COMMENT_NODE && node.nodeValue === 'end';
+      });
+      if (endComment) {
+        el.removeChild(endComment);
+        clearInterval(interval);
+        resolve(true);
+      }
+    }, 10);
+  });
+}
+
 /**
  * Server action component to handle the client-side form submission and HTML replacement
  */

package/src/clientjs/preact.ts

@@ -1 +1,2 @@
-export * from '@preact/compat';
+export * from 'preact/compat';
+export { h, render } from 'preact';

package/src/server.ts

@@ -1,6 +1,6 @@
 import { readdir } from 'node:fs/promises';
 import { basename, extname, join } from 'node:path';
-import { TmplHtml, html, renderStream, renderAsync, render } from '@hyperspan/html';
+import { HSHtml, html, isHSHtml, renderStream, renderAsync, render } from '@hyperspan/html';
 import { isbot } from 'isbot';
 import { buildClientJS, buildClientCSS } from './assets';
 import { Hono, type Context } from 'hono';
@@ -13,8 +13,10 @@ const CWD = process.cwd();
 /**
  * Types
  */
-export type THSResponseTypes = TmplHtml | Response | string | null;
+export type THSResponseTypes = HSHtml | Response | string | null;
 export type THSRouteHandler = (context: Context) => THSResponseTypes | Promise<THSResponseTypes>;
+export type THSAPIResponseTypes = Response | Record<any, any> | void;
+export type THSAPIRouteHandler = (context: Context) => THSResponseTypes | Promise<THSResponseTypes>;
 
 export type THSRoute = {
   _kind: 'hsRoute';
@@ -28,7 +30,7 @@ export type THSRoute = {
 
 /**
  * Define a route that can handle a direct HTTP request.
- * Route handlers should return a TmplHtml or Response object
+ * Route handlers should return a HSHtml or Response object
  */
 export function createRoute(handler?: THSRouteHandler): THSRoute {
   let _handlers: Record<string, THSRouteHandler> = {};
@@ -78,19 +80,12 @@ export function createRoute(handler?: THSRouteHandler): THSRoute {
       const streamingEnabled = !userIsBot && (streamOpt !== undefined ? streamOpt : true);
       const routeKind = typeof routeContent;
 
-      // Render TmplHtml if returned from route handler
-      if (
-        routeContent &&
-        routeKind === 'object' &&
-        (routeContent instanceof TmplHtml ||
-          routeContent.constructor.name === 'TmplHtml' ||
-          // @ts-ignore
-          routeContent?._kind === 'TmplHtml')
-      ) {
+      // Render HSHtml if returned from route handler
+      if (isHSHtml(routeContent)) {
         if (streamingEnabled) {
-          return new StreamResponse(renderStream(routeContent as TmplHtml)) as Response;
+          return new StreamResponse(renderStream(routeContent as HSHtml)) as Response;
         } else {
-          const output = await renderAsync(routeContent as TmplHtml);
+          const output = await renderAsync(routeContent as HSHtml);
           return context.html(output);
         }
       }
@@ -107,8 +102,8 @@ export function createRoute(handler?: THSRouteHandler): THSRoute {
  * Create new API Route
  * API Route handlers should return a JSON object or a Response
  */
-export function createAPIRoute(handler?: THSRouteHandler): THSRoute {
-  let _handlers: Record<string, THSRouteHandler> = {};
+export function createAPIRoute(handler?: THSAPIRouteHandler): THSRoute {
+  let _handlers: Record<string, THSAPIRouteHandler> = {};
 
   if (handler) {
     _handlers['GET'] = handler;
@@ -116,23 +111,23 @@ export function createAPIRoute(handler?: THSRouteHandler): THSRoute {
 
   const api: THSRoute = {
     _kind: 'hsRoute',
-    get(handler: THSRouteHandler) {
+    get(handler: THSAPIRouteHandler) {
       _handlers['GET'] = handler;
       return api;
     },
-    post(handler: THSRouteHandler) {
+    post(handler: THSAPIRouteHandler) {
       _handlers['POST'] = handler;
       return api;
     },
-    put(handler: THSRouteHandler) {
+    put(handler: THSAPIRouteHandler) {
       _handlers['PUT'] = handler;
       return api;
     },
-    delete(handler: THSRouteHandler) {
+    delete(handler: THSAPIRouteHandler) {
       _handlers['DELETE'] = handler;
       return api;
     },
-    patch(handler: THSRouteHandler) {
+    patch(handler: THSAPIRouteHandler) {
       _handlers['PATCH'] = handler;
       return api;
     },
@@ -209,6 +204,14 @@ export function isRunnableRoute(route: unknown): boolean {
   return typeof route === 'object' && 'run' in route;
 }
 
+/**
+ * Create a layout for a Hyperspan app. Passthrough for now.
+ * Future intent is to be able to conditionally render a layout for full page content vs. partial content.
+ */
+export function createLayout<T>(layout: (props: T) => HSHtml | Promise<HSHtml>) {
+  return layout;
+}
+
 /**
  * Basic error handling
  * @TODO: Should check for and load user-customizeable template with special name (app/__error.ts ?)
@@ -249,7 +252,6 @@ const ROUTE_SEGMENT = /(\[[a-zA-Z_\.]+\])/g;
 export async function buildRoutes(config: THSServerConfig): Promise<THSRouteMap[]> {
   // Walk all pages and add them as routes
   const routesDir = join(config.appDir, 'routes');
-  console.log(routesDir);
   const files = await readdir(routesDir, { recursive: true });
   const routes: THSRouteMap[] = [];