@hyperspan/framework 0.3.5 → 0.4.1

package/dist/assets.js

@@ -7,18 +7,49 @@ import { readdir } from "node:fs/promises";
 import { resolve } from "node:path";
 var IS_PROD = false;
 var PWD = import.meta.dir;
+var CLIENTJS_PUBLIC_PATH = "/_hs/js";
+var ISLAND_PUBLIC_PATH = "/_hs/js/islands";
 var clientImportMap = new Map;
 var clientJSFiles = new Map;
 async function buildClientJS() {
   const sourceFile = resolve(PWD, "../", "./src/clientjs/hyperspan-client.ts");
   const output = await Bun.build({
     entrypoints: [sourceFile],
-    outdir: `./public/_hs/js`,
+    outdir: `./public/${CLIENTJS_PUBLIC_PATH}`,
     naming: IS_PROD ? "[dir]/[name]-[hash].[ext]" : undefined,
     minify: IS_PROD
   });
   const jsFile = output.outputs[0].path.split("/").reverse()[0];
-  clientJSFiles.set("_hs", { src: "/_hs/js/" + jsFile });
+  clientJSFiles.set("_hs", { src: `${CLIENTJS_PUBLIC_PATH}/${jsFile}` });
+}
+function renderClientJS(module, onLoad) {
+  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.`);
+  }
+  return html.raw(module.__CLIENT_JS.renderScriptTag({
+    onLoad: onLoad ? functionToString(onLoad) : undefined
+  }));
+}
+function functionToString(fn) {
+  let str = fn.toString().trim();
+  if (!str.includes("function ")) {
+    if (str.includes("async ")) {
+      str = "async function " + str.replace("async ", "");
+    } else {
+      str = "function " + str;
+    }
+  }
+  const lines = str.split(`
+`);
+  const firstLine = lines[0];
+  const lastLine = lines[lines.length - 1];
+  if (!lastLine?.includes("}")) {
+    return str.replace("=> ", "{ return ") + "; }";
+  }
+  if (firstLine.includes("=>")) {
+    return str.replace("=> ", "");
+  }
+  return str;
 }
 var clientCSSFiles = new Map;
 async function buildClientCSS() {
@@ -60,7 +91,6 @@ function hyperspanScriptTags() {
 function assetHash(content) {
   return createHash("md5").update(content).digest("hex");
 }
-var ISLAND_PUBLIC_PATH = "/_hs/js/islands";
 var ISLAND_DEFAULTS = () => ({
   ssr: true,
   loading: undefined
@@ -73,8 +103,10 @@ function renderIsland(Component, props, options = ISLAND_DEFAULTS()) {
 }
 export {
   renderIsland,
+  renderClientJS,
   hyperspanStyleTags,
   hyperspanScriptTags,
+  functionToString,
   clientJSFiles,
   clientImportMap,
   clientCSSFiles,
@@ -82,6 +114,7 @@ export {
   buildClientCSS,
   assetHash,
   ISLAND_PUBLIC_PATH,
-  ISLAND_DEFAULTS
+  ISLAND_DEFAULTS,
+  CLIENTJS_PUBLIC_PATH
 };
 

package/dist/server.js

@@ -1,14 +1,80 @@
 import {
+  CLIENTJS_PUBLIC_PATH,
   assetHash,
   buildClientCSS,
-  buildClientJS
+  buildClientJS,
+  clientImportMap
 } from "./assets.js";
 import"./chunk-atw8cdg1.js";
 
+// src/plugins.ts
+var CLIENT_JS_CACHE = new Map;
+var EXPORT_REGEX = /export\{(.*)\}/g;
+async function clientJSPlugin(config) {
+  await Bun.plugin({
+    name: "Hyperspan Client JS Loader",
+    async setup(build) {
+      build.onLoad({ filter: /\.client\.ts$/ }, async (args) => {
+        const jsId = assetHash(args.path);
+        if (CLIENT_JS_CACHE.has(jsId)) {
+          return {
+            contents: CLIENT_JS_CACHE.get(jsId) || "",
+            loader: "js"
+          };
+        }
+        const result = await Bun.build({
+          entrypoints: [args.path],
+          outdir: `./public/${CLIENTJS_PUBLIC_PATH}`,
+          naming: IS_PROD ? "[dir]/[name]-[hash].[ext]" : undefined,
+          external: Array.from(clientImportMap.keys()),
+          minify: true,
+          format: "esm",
+          target: "browser"
+        });
+        const esmName = String(result.outputs[0].path.split("/").reverse()[0]).replace(".js", "");
+        clientImportMap.set(esmName, `${CLIENTJS_PUBLIC_PATH}/${esmName}.js`);
+        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");
+        const moduleCode = `// hyperspan:processed
+import { functionToString } from '@hyperspan/framework/assets';
+
+// Original file contents
+${contents}
+
+// hyperspan:client-js-plugin
+export const __CLIENT_JS = {
+  id: "${jsId}",
+  esmName: "${esmName}",
+  sourceFile: "${args.path}",
+  outputFile: "${result.outputs[0].path}",
+  renderScriptTag: ({ onLoad }) => {
+    const fn = onLoad ? functionToString(onLoad) : undefined;
+    return \`<script type="module" data-source-id="${jsId}">import ${exports} from "${esmName}";
+\${fn ? \`const fn = \${fn};
+fn(${fnArgs});\` : ''}</script>\`;
+  },
+}
+`;
+        CLIENT_JS_CACHE.set(jsId, moduleCode);
+        return {
+          contents: moduleCode,
+          loader: "js"
+        };
+      });
+    }
+  });
+}
+
 // src/server.ts
+import { html, isHSHtml, renderStream, renderAsync, render } from "@hyperspan/html";
 import { readdir } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
-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|(?<!cam)scan|@[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/|^{{.*}}$|analyzer|archive|ask jeeves/teoma|audit|bit\\.ly/|bluecoat drtr|browsex|burpcollaborator|capture|catch|check\\b|checker|chrome-lighthouse|chromeframe|classifier|cloudflare|convertify|crawl|cypress/|dareboost|datanyze|dejaclick|detect|dmbrowser|download|evc-batch/|exaleadcloudview|feed|firephp|functionize|gomezagent|grab|headless|httrack|hubspot marketing grader|hydra|ibisbrowser|infrawatch|insight|inspect|iplabel|ips-agent|java(?!;)|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|scrape|server|sogou|sparkler/|speedcurve|spider|splash|statuscake|supercleaner|synapse|synthetic|tools|torrent|transcoder|url|validator|virtuoso|wappalyzer|webglance|webkit2png|whatcms/|xtate/";
@@ -1858,8 +1924,25 @@ function createRoute(handler) {
         ..._middleware,
         async (context) => {
           const method = context.req.method.toUpperCase();
+          if (method === "OPTIONS") {
+            return context.html(render(html`
+                <!DOCTYPE html>
+                <html lang="en"></html>
+              `), {
+              status: 200,
+              headers: {
+                "Access-Control-Allow-Origin": "*",
+                "Access-Control-Allow-Methods": [
+                  "HEAD",
+                  "OPTIONS",
+                  ...Object.keys(_handlers)
+                ].join(", "),
+                "Access-Control-Allow-Headers": "Content-Type, Authorization"
+              }
+            });
+          }
           return returnHTMLResponse(context, () => {
-            const handler2 = _handlers[method];
+            const handler2 = method === "HEAD" ? _handlers["GET"] : _handlers[method];
             if (!handler2) {
               throw new HTTPException(405, { message: "Method not allowed" });
             }
@@ -1908,7 +1991,24 @@ function createAPIRoute(handler) {
         ..._middleware,
         async (context) => {
           const method = context.req.method.toUpperCase();
-          const handler2 = _handlers[method];
+          if (method === "OPTIONS") {
+            return context.json({
+              meta: { success: true, dtResponse: new Date },
+              data: {}
+            }, {
+              status: 200,
+              headers: {
+                "Access-Control-Allow-Origin": "*",
+                "Access-Control-Allow-Methods": [
+                  "HEAD",
+                  "OPTIONS",
+                  ...Object.keys(_handlers)
+                ].join(", "),
+                "Access-Control-Allow-Headers": "Content-Type, Authorization"
+              }
+            });
+          }
+          const handler2 = method === "HEAD" ? _handlers["GET"] : _handlers[method];
           if (!handler2) {
             return context.json({
               meta: { success: false, dtResponse: new Date },
@@ -2090,7 +2190,7 @@ function createRouteFromModule(RouteModule) {
   return route._getRouteHandlers();
 }
 async function createServer(config) {
-  await Promise.all([buildClientJS(), buildClientCSS()]);
+  await Promise.all([buildClientJS(), buildClientCSS(), clientJSPlugin(config)]);
   const app = new Hono2;
   config.beforeRoutesAdded && config.beforeRoutesAdded(app);
   const [routes, actions] = await Promise.all([buildRoutes(config), buildActions(config)]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "Hyperspan Web Framework",
   "main": "dist/server.ts",
   "types": "src/server.ts",

package/src/assets.ts

@@ -11,6 +11,8 @@ export type THSIslandOptions = {
 const IS_PROD = process.env.NODE_ENV === 'production';
 const PWD = import.meta.dir;
 
+export const CLIENTJS_PUBLIC_PATH = '/_hs/js';
+export const ISLAND_PUBLIC_PATH = '/_hs/js/islands';
 export const clientImportMap = new Map<string, string>();
 
 /**
@@ -21,14 +23,66 @@ export async function buildClientJS() {
   const sourceFile = resolve(PWD, '../', './src/clientjs/hyperspan-client.ts');
   const output = await Bun.build({
     entrypoints: [sourceFile],
-    outdir: `./public/_hs/js`,
+    outdir: `./public/${CLIENTJS_PUBLIC_PATH}`,
     naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
     minify: IS_PROD,
   });
 
   const jsFile = output.outputs[0].path.split('/').reverse()[0];
 
-  clientJSFiles.set('_hs', { src: '/_hs/js/' + jsFile });
+  clientJSFiles.set('_hs', { src: `${CLIENTJS_PUBLIC_PATH}/${jsFile}` });
+}
+
+/**
+ * Render a client JS module as a script tag
+ */
+export function renderClientJS<T>(module: T, onLoad?: (module: T) => void) {
+  // @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.`
+    );
+  }
+
+  return html.raw(
+    // @ts-ignore
+    module.__CLIENT_JS.renderScriptTag({
+      onLoad: onLoad ? functionToString(onLoad) : undefined,
+    })
+  );
+}
+
+/**
+ * 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;
+    }
+  }
+
+  const lines = str.split('\n');
+  const firstLine = lines[0];
+  const lastLine = lines[lines.length - 1];
+
+  // Arrow function conversion
+  if (!lastLine?.includes('}')) {
+    return str.replace('=> ', '{ return ') + '; }';
+  }
+
+  // Cleanup arrow function
+  if (firstLine.includes('=>')) {
+    return str.replace('=> ', '');
+  }
+
+  return str;
 }
 
 /**
@@ -101,7 +155,6 @@ export function assetHash(content: string): string {
 /**
  * Island defaults
  */
-export const ISLAND_PUBLIC_PATH = '/_hs/js/islands';
 export const ISLAND_DEFAULTS: () => THSIslandOptions = () => ({
   ssr: true,
   loading: undefined,

package/src/clientjs/hyperspan-client.ts

@@ -12,28 +12,46 @@ function htmlAsyncContentObserver() {
       const asyncContent = list
         .map((mutation) =>
           Array.from(mutation.addedNodes).find((node: any) => {
-            return node.id?.startsWith('async_') && node.id?.endsWith('_content');
+            if (!node) {
+              return false;
+            }
+            return node.id?.startsWith('async_loading_') && node.id?.endsWith('_content');
           })
         )
         .filter((node: any) => node);
 
-      asyncContent.forEach((el: any) => {
+      asyncContent.forEach((templateEl: any) => {
         try {
-          // Also observe child nodes for nested async content
-          asyncContentObserver.observe(el.content, { childList: true, subtree: true });
+          // Also observe for content inside the template content (shadow DOM is separate)
+          asyncContentObserver.observe(templateEl.content, { childList: true, subtree: true });
 
-          const slotId = el.id.replace('_content', '');
+          const slotId = templateEl.id.replace('_content', '');
           const slotEl = document.getElementById(slotId);
 
           if (slotEl) {
-            // 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);
+            // 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();
             });
-
-            // Lazy load scripts (if any) after the content is inserted
-            lazyLoadScripts();
           }
         } catch (e) {
           console.error(e);
@@ -49,18 +67,29 @@ 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) => {
+async function waitForContent(
+  el: HTMLElement,
+  waitFn: (
+    node: HTMLElement
+  ) => HTMLElement | HTMLTemplateElement | Node | ChildNode | null | undefined,
+  options: { timeoutMs?: number; intervalMs?: number } = { timeoutMs: 10000, intervalMs: 20 }
+): Promise<HTMLElement | HTMLTemplateElement | Node | ChildNode | null | undefined> {
+  return new Promise((resolve, reject) => {
+    let timeout: NodeJS.Timeout;
     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);
+      const content = waitFn(el);
+      if (content) {
+        if (timeout) {
+          clearTimeout(timeout);
+        }
         clearInterval(interval);
-        resolve(true);
+        resolve(content);
       }
-    }, 10);
+    }, options.intervalMs || 20);
+    timeout = setTimeout(() => {
+      clearInterval(interval);
+      reject(new Error(`[Hyperspan] Timeout waiting for end of streaming content ${el.id}`));
+    }, options.timeoutMs || 10000);
   });
 }
 
@@ -74,6 +103,7 @@ class HSAction extends HTMLElement {
 
   connectedCallback() {
     actionFormObserver.observe(this, { childList: true, subtree: true });
+    bindHSActionForm(this, this.querySelector('form') as HTMLFormElement);
   }
 }
 window.customElements.define('hs-action', HSAction);
@@ -91,6 +121,10 @@ const actionFormObserver = new MutationObserver((list) => {
  * Bind the form inside an hs-action element to the action URL and submit handler
  */
 function bindHSActionForm(hsActionElement: HSAction, form: HTMLFormElement) {
+  if (!hsActionElement || !form) {
+    return;
+  }
+
   form.setAttribute('action', hsActionElement.getAttribute('url') || '');
   const submitHandler = (e: Event) => {
     formSubmitToRoute(e, form as HTMLFormElement, {
@@ -116,8 +150,6 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
     'X-Request-Type': 'partial',
   };
 
-  let response: Response;
-
   const hsActionTag = form.closest('hs-action');
   const submitBtn = form.querySelector('button[type=submit],input[type=submit]');
   if (submitBtn) {
@@ -136,7 +168,6 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
         return '';
       }
 
-      response = res;
       return res.text();
     })
     .then((content: string) => {
@@ -149,6 +180,7 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
 
       Idiomorph.morph(target, content);
       opts.afterResponse && opts.afterResponse();
+      lazyLoadScripts();
     });
 }
 

package/src/plugins.ts

@@ -0,0 +1,89 @@
+import { assetHash, CLIENTJS_PUBLIC_PATH, clientImportMap, clientJSFiles } from './assets';
+import { IS_PROD, type THSServerConfig } from './server';
+
+const CLIENT_JS_CACHE = new Map<string, string>();
+const EXPORT_REGEX = /export\{(.*)\}/g;
+
+/**
+ * Hyperspan Client JS Plugin
+ */
+export async function clientJSPlugin(config: THSServerConfig) {
+  // 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 (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: `./public/${CLIENTJS_PUBLIC_PATH}`,
+          naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
+          external: Array.from(clientImportMap.keys()),
+          minify: true,
+          format: 'esm',
+          target: 'browser',
+        });
+
+        // Add output file to import map
+        const esmName = String(result.outputs[0].path.split('/').reverse()[0]).replace('.js', '');
+        clientImportMap.set(esmName, `${CLIENTJS_PUBLIC_PATH}/${esmName}.js`);
+
+        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/assets';
+
+// Original file contents
+${contents}
+
+// hyperspan:client-js-plugin
+export const __CLIENT_JS = {
+  id: "${jsId}",
+  esmName: "${esmName}",
+  sourceFile: "${args.path}",
+  outputFile: "${result.outputs[0].path}",
+  renderScriptTag: ({ onLoad }) => {
+    const fn = onLoad ? functionToString(onLoad) : undefined;
+    return \`<script type="module" data-source-id="${jsId}">import ${exports} from "${esmName}";\n\${fn ? \`const fn = \${fn};\nfn(${fnArgs});\` : ''}</script>\`;
+  },
+}
+`;
+
+        CLIENT_JS_CACHE.set(jsId, moduleCode);
+
+        return {
+          contents: moduleCode,
+          loader: 'js',
+        };
+      });
+    },
+  });
+}

package/src/server.ts

@@ -1,8 +1,9 @@
+import { buildClientJS, buildClientCSS, assetHash } from './assets';
+import { clientJSPlugin } from './plugins';
+import { HSHtml, html, isHSHtml, renderStream, renderAsync, render } from '@hyperspan/html';
 import { readdir } from 'node:fs/promises';
 import { basename, extname, join } from 'node:path';
-import { HSHtml, html, isHSHtml, renderStream, renderAsync, render } from '@hyperspan/html';
 import { isbot } from 'isbot';
-import { buildClientJS, buildClientCSS, assetHash } from './assets';
 import { Hono, type Context } from 'hono';
 import { serveStatic } from 'hono/bun';
 import { HTTPException } from 'hono/http-exception';
@@ -83,8 +84,32 @@ export function createRoute(handler?: THSRouteHandler): THSRoute {
         async (context: Context) => {
           const method = context.req.method.toUpperCase();
 
+          // Handle CORS preflight requests
+          if (method === 'OPTIONS') {
+            return context.html(
+              render(html`
+                <!DOCTYPE html>
+                <html lang="en"></html>
+              `),
+              {
+                status: 200,
+                headers: {
+                  'Access-Control-Allow-Origin': '*',
+                  'Access-Control-Allow-Methods': [
+                    'HEAD',
+                    'OPTIONS',
+                    ...Object.keys(_handlers),
+                  ].join(', '),
+                  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+                },
+              }
+            );
+          }
+
+          // Handle other requests, HEAD is GET with no body
           return returnHTMLResponse(context, () => {
-            const handler = _handlers[method];
+            const handler = method === 'HEAD' ? _handlers['GET'] : _handlers[method];
+
             if (!handler) {
               throw new HTTPException(405, { message: 'Method not allowed' });
             }
@@ -142,7 +167,31 @@ export function createAPIRoute(handler?: THSAPIRouteHandler): THSAPIRoute {
         ..._middleware,
         async (context: Context) => {
           const method = context.req.method.toUpperCase();
-          const handler = _handlers[method];
+
+          // Handle CORS preflight requests
+          if (method === 'OPTIONS') {
+            return context.json(
+              {
+                meta: { success: true, dtResponse: new Date() },
+                data: {},
+              },
+              {
+                status: 200,
+                headers: {
+                  'Access-Control-Allow-Origin': '*',
+                  'Access-Control-Allow-Methods': [
+                    'HEAD',
+                    'OPTIONS',
+                    ...Object.keys(_handlers),
+                  ].join(', '),
+                  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+                },
+              }
+            );
+          }
+
+          // Handle other requests, HEAD is GET with no body
+          const handler = method === 'HEAD' ? _handlers['GET'] : _handlers[method];
 
           if (!handler) {
             return context.json(
@@ -456,7 +505,7 @@ export function createRouteFromModule(
  */
 export async function createServer(config: THSServerConfig): Promise<Hono> {
   // Build client JS and CSS bundles so they are available for templates when streaming starts
-  await Promise.all([buildClientJS(), buildClientCSS()]);
+  await Promise.all([buildClientJS(), buildClientCSS(), clientJSPlugin(config)]);
 
   const app = new Hono();