@hyperspan/framework 1.0.26 → 1.0.28

package/.claude/settings.local.json

@@ -1,5 +1,9 @@
 {
   "permissions": {
-    "allow": ["Bash(bun test:*)"]
+    "allow": [
+      "Bash(bun test:*)",
+      "Bash(npx tsc *)",
+      "Bash(echo \"exit: $?\")"
+    ]
   }
 }

package/package.json

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

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

@@ -1,5 +1,63 @@
 import { Idiomorph } from './idiomorph';
 import { lazyLoadScripts } from './hyperspan-scripts.client';
+import type { Hyperspan as HS } from '../../types';
+
+const HS_ACTION_BEFORE_FETCH: HS.ActionEventName = 'hs:action:before-fetch';
+const HS_ACTION_AFTER_FETCH: HS.ActionEventName = 'hs:action:after-fetch';
+const HS_ACTION_BEFORE_SWAP: HS.ActionEventName = 'hs:action:before-swap';
+const HS_ACTION_AFTER_SWAP: HS.ActionEventName = 'hs:action:after-swap';
+const HS_ACTION_BEFORE_NAVIGATE: HS.ActionEventName = 'hs:action:before-navigate';
+
+function dispatchActionEvent<T>(
+  target: EventTarget,
+  name: HS.ActionEventName,
+  detail: T,
+  cancelable = false
+): boolean {
+  return target.dispatchEvent(
+    new CustomEvent(name, {
+      detail,
+      bubbles: true,
+      cancelable,
+      composed: true,
+    })
+  );
+}
+
+/** No box by default (`display: contents`) — style `:has(hs-action-loading)` for loading UI. */
+function ensureActionLoadingStyles() {
+  if (document.getElementById('hs-action-loading-style')) {
+    return;
+  }
+  const style = document.createElement('style');
+  style.id = 'hs-action-loading-style';
+  style.textContent = 'hs-action-loading{display:contents}';
+  document.head.appendChild(style);
+}
+
+class HSActionLoading extends HTMLElement {
+  connectedCallback() {
+    ensureActionLoadingStyles();
+  }
+}
+
+if (!customElements.get('hs-action-loading')) {
+  customElements.define('hs-action-loading', HSActionLoading);
+}
+
+function setActionLoading(hsActionTag: HTMLElement | null, loading: boolean) {
+  if (!hsActionTag) {
+    return;
+  }
+  const existing = hsActionTag.querySelector('hs-action-loading');
+  if (loading) {
+    if (!existing) {
+      hsActionTag.appendChild(document.createElement('hs-action-loading'));
+    }
+  } else if (existing) {
+    existing.remove();
+  }
+}
 
 const actionFormObserver = new MutationObserver((list) => {
   list.forEach((mutation) => {
@@ -71,7 +129,24 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
     }
   }
 
-  const hsActionTag = form.closest('hs-action');
+  const hsActionTag = form.closest('hs-action') as HTMLElement | null;
+  const eventTarget: EventTarget = hsActionTag || document;
+  const fetchDetail: HS.ActionFetchDetail = {
+    form,
+    action: hsActionTag,
+    url: formUrl,
+    method,
+    loadingElement: true,
+  };
+
+  if (!dispatchActionEvent(eventTarget, HS_ACTION_BEFORE_FETCH, fetchDetail, true)) {
+    return;
+  }
+
+  if (fetchDetail.loadingElement) {
+    setActionLoading(hsActionTag, true);
+  }
+
   const submitBtn = form.querySelector('button[type=submit],input[type=submit]');
   if (submitBtn) {
     submitBtn.setAttribute('disabled', 'disabled');
@@ -82,6 +157,18 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
     if (isFullDocument) {
       html = html.replace(/^[\s\uFEFF]*<!DOCTYPE[^>]*>/i, '');
     }
+
+    const swapDetail: HS.ActionSwapDetail = {
+      form,
+      action: hsActionTag,
+      html,
+      fullDocument: isFullDocument,
+    };
+
+    if (!dispatchActionEvent(eventTarget, HS_ACTION_BEFORE_SWAP, swapDetail, true)) {
+      return;
+    }
+
     const target = isFullDocument ? window.document : hsActionTag || form;
     const options = isFullDocument ? undefined : { morphStyle: 'innerHTML' };
 
@@ -96,10 +183,42 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
 
     activateScriptsIn(isFullDocument ? document.body : (target as ParentNode));
 
+    dispatchActionEvent(eventTarget, HS_ACTION_AFTER_SWAP, swapDetail);
+
     opts.afterResponse && opts.afterResponse();
     lazyLoadScripts();
   }
 
+  async function navigateTo(url: string, preferHard: boolean) {
+    const navigateDetail: HS.ActionNavigateDetail = {
+      form,
+      action: hsActionTag,
+      url,
+      hard: preferHard,
+    };
+
+    if (!dispatchActionEvent(eventTarget, HS_ACTION_BEFORE_NAVIGATE, navigateDetail, true)) {
+      return;
+    }
+
+    if (navigateDetail.hard) {
+      window.location.assign(navigateDetail.url);
+      return;
+    }
+
+    // Soft morph requires same-origin (CORS / Idiomorph are not safe across domains).
+    const resolved = new URL(navigateDetail.url, window.location.href);
+    if (resolved.origin !== window.location.origin) {
+      window.location.assign(navigateDetail.url);
+      return;
+    }
+
+    const pageRes = await fetch(navigateDetail.url, {
+      headers: { Accept: 'text/html' },
+    });
+    await consumeStreamingHtmlResponse(pageRes, applyResponseHtml);
+  }
+
   fetch(formUrl, { body: formData, method, headers })
     .then(async (res: Response) => {
       // Look for special header that indicates a redirect.
@@ -109,21 +228,13 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
         if (newUrl) {
           const resolved = new URL(newUrl, window.location.href);
 
-          // Same-origin + same path: fetch updated HTML and morph in place. Cross-origin redirects
-          // must use full navigation (CORS and Idiomorph are not safe across domains).
-          if (
-            resolved.origin === window.location.origin &&
-            resolved.pathname === window.location.pathname
-          ) {
-            const pageRes = await fetch(resolved.href, {
-              headers: { Accept: 'text/html' },
-            });
-            await consumeStreamingHtmlResponse(pageRes, applyResponseHtml);
-            return;
-          }
-
-          // If the new URL is different, we need to redirect the user to the new URL
-          window.location.assign(newUrl);
+          // Default: same-origin + same path → soft morph; anything else → hard navigation.
+          // Listeners can flip detail.hard on hs:action:before-navigate to override.
+          const preferHard =
+            resolved.origin !== window.location.origin ||
+            resolved.pathname !== window.location.pathname;
+
+          await navigateTo(newUrl, preferHard);
         }
         return;
       }
@@ -132,22 +243,18 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
     })
     .catch((error) => {
       console.error('[Hyperspan] Error submitting form action:', error);
+    })
+    .finally(() => {
+      setActionLoading(hsActionTag, false);
+      dispatchActionEvent(eventTarget, HS_ACTION_AFTER_FETCH, fetchDetail);
     });
 }
 
 /** Streaming async chunks use template ids ending in `_content`. */
 const STREAM_CHUNK_MARKER = /<template id="[^"]+_content">/;
 
-function splitInitialStreamHtml(html: string): { initial: string; streamTail: string | null } {
-  const match = STREAM_CHUNK_MARKER.exec(html);
-  if (!match || match.index === 0) {
-    return { initial: html, streamTail: null };
-  }
-  return {
-    initial: html.slice(0, match.index),
-    streamTail: html.slice(match.index),
-  };
-}
+/** Marks the end of a streaming chunk boundary. */
+const CHUNK_END = '<!--/hs:chunk-->';
 
 /** Clone a script node so the browser will execute it (preserves module type). */
 function cloneScriptForExecution(script: HTMLScriptElement): HTMLScriptElement {
@@ -207,8 +314,18 @@ function appendHtmlToBody(html: string) {
 }
 
 /**
- * Read a (possibly streaming) HTML response: Idiomorph the initial page HTML, then append
- * later stream chunks to document.body so streaming scripts run and placeholders resolve.
+ * Read a (possibly streaming) HTML response. The stream is shaped as:
+ *   [full initial page HTML, including <slot> placeholders]
+ *   <template id="X_content">…<!--end--></template><script>…_hsc.push({id:'X'})…</script>
+ *   …one <template>/<script> pair per async chunk…
+ *
+ * Network reads do NOT align with these logical boundaries, so we buffer instead of assuming
+ * the whole initial page (or a whole chunk) arrives in a single read:
+ *   1. Accumulate until the first stream-chunk <template> marker appears (or the stream ends),
+ *      then Idiomorph the everything-before-it as the initial page HTML - exactly once.
+ *   2. After that, append only COMPLETE chunks (each terminated by the server's <!--/hs:chunk-->
+ *      delimiter) to document.body so their scripts run and placeholders resolve. Any partial
+ *      trailing chunk stays buffered until the rest of it arrives.
  */
 async function consumeStreamingHtmlResponse(
   res: Response,
@@ -225,34 +342,59 @@ async function consumeStreamingHtmlResponse(
 
   const reader = body.getReader();
   const decoder = new TextDecoder();
-  let isFirstChunk = true;
-
-  function processChunk(html: string) {
-    if (!html) {
-      return;
+  let buffer = '';
+  let initialApplied = false;
+
+  function pump(isFinal: boolean) {
+    // Phase 1: split off and morph the initial page HTML (everything before the first chunk).
+    if (!initialApplied) {
+      const match = STREAM_CHUNK_MARKER.exec(buffer);
+      if (match) {
+        const initial = buffer.slice(0, match.index);
+        buffer = buffer.slice(match.index);
+        initialApplied = true;
+        if (initial) {
+          applyInitialHtml(initial);
+        }
+      } else if (isFinal) {
+        // No stream chunks at all - the whole response is the page HTML.
+        initialApplied = true;
+        if (buffer) {
+          applyInitialHtml(buffer);
+        }
+        buffer = '';
+        return;
+      } else {
+        // Marker not here yet; keep buffering the (possibly large) initial HTML.
+        return;
+      }
     }
 
-    if (isFirstChunk) {
-      isFirstChunk = false;
-      const { initial, streamTail } = splitInitialStreamHtml(html);
-      if (initial) {
-        applyInitialHtml(initial);
-      }
-      if (streamTail) {
-        appendHtmlToBody(streamTail);
+    // Phase 2: flush complete chunks; hold back any partial trailing chunk.
+    if (isFinal) {
+      if (buffer) {
+        appendHtmlToBody(buffer);
+        buffer = '';
       }
       return;
     }
-
-    appendHtmlToBody(html);
+    const lastEnd = buffer.lastIndexOf(CHUNK_END);
+    if (lastEnd === -1) {
+      return;
+    }
+    const flushEnd = lastEnd + CHUNK_END.length;
+    appendHtmlToBody(buffer.slice(0, flushEnd));
+    buffer = buffer.slice(flushEnd);
   }
 
   while (true) {
     const { done, value } = await reader.read();
     if (done) {
-      processChunk(decoder.decode());
+      buffer += decoder.decode();
+      pump(true);
       break;
     }
-    processChunk(decoder.decode(value, { stream: true }));
+    buffer += decoder.decode(value, { stream: true });
+    pump(false);
   }
 }

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

@@ -33,7 +33,12 @@ async function waitForContent(
 function renderStreamChunk(chunk: { id: string }) {
   const slotId = chunk.id;
   const slotEl = document.getElementById(slotId);
-  const templateEl = document.getElementById(`${slotId}_content`) as HTMLTemplateElement;
+  const templateEl = document.getElementById(`${slotId}_content`) as HTMLTemplateElement | null;
+
+  // Content template is gone (e.g. this chunk was already rendered and re-queued). Nothing to do.
+  if (!templateEl) {
+    return;
+  }
 
   if (slotEl) {
     // Content AND slot are present - let's insert the content into the slot
@@ -72,6 +77,8 @@ declare global {
       push: (e: { id: string }) => void;
       forEach: (callback: (e: { id: string }) => void) => void;
     };
+    _hscInit?: boolean;
+    _hscLoading?: boolean;
   }
 }
 

package/src/layout.ts

@@ -3,7 +3,9 @@ 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'));
+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
@@ -16,14 +18,18 @@ export function hyperspanScriptTags() {
     <script id="hyperspan-streaming-script">
       // [Hyperspan] Streaming - Load the client streaming JS module only when the first chunk is loaded
       window._hsc = window._hsc || [];
-      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);
-        }
-      };
+      if (!window._hscInit) {
+        window._hscInit = true;
+        window._hsc.push = function (e) {
+          Array.prototype.push.call(window._hsc, e);
+          if (!window._hscLoading) {
+            window._hscLoading = true;
+            const script = document.createElement('script');
+            script.src = '${clientStreamingJS.publicPath}';
+            document.body.appendChild(script);
+          }
+        };
+      }
     </script>
   `;
 }
@@ -36,10 +42,8 @@ export function hyperspanStyleTags(context: HS.Context) {
   const cssImports = context.route.cssImports ?? CSS_ROUTE_MAP.get(context.route.path) ?? [];
 
   for (const cssFile of cssImports) {
-    styleTags.push(html`
-      <link rel="stylesheet" href="${CSS_PUBLIC_PATH}/${cssFile}" />
-    `);
+    styleTags.push(html` <link rel="stylesheet" href="${CSS_PUBLIC_PATH}/${cssFile}" /> `);
   }
 
   return styleTags;
-}
+}

package/src/server.ts

@@ -538,12 +538,14 @@ export async function returnHTMLResponse(
         return new StreamResponse(
           renderStream(routeContent as HSHtml, {
             renderChunk: (chunk) => {
+              // Trailing <!--/hs:chunk--> marks the end of a streaming chunk boundary.
               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>
+                <!--/hs:chunk-->
               `;
             },
           }),

package/src/types.ts

@@ -299,6 +299,56 @@ export namespace Hyperspan {
     fetch: (request: Request) => Promise<Response>;
   }
 
+  /**
+   * Client-side action lifecycle events (dispatched from `<hs-action>`, bubbles to document).
+   *
+   * - `hs:action:before-fetch` — before the action request starts (cancelable).
+   * - `hs:action:after-fetch` — after the action request finishes (success or error).
+   * - `hs:action:before-swap` — before HTML morph (cancelable). Close modals here.
+   * - `hs:action:after-swap` — after HTML morph.
+   * - `hs:action:before-navigate` — before redirect soft/hard navigation (cancelable).
+   *   Set `detail.hard = true` for a full page load, or `false` to fetch+morph in place.
+   */
+  export type ActionEventName =
+    | 'hs:action:before-fetch'
+    | 'hs:action:after-fetch'
+    | 'hs:action:before-swap'
+    | 'hs:action:after-swap'
+    | 'hs:action:before-navigate';
+
+  export type ActionFetchDetail = {
+    form: HTMLFormElement;
+    /** The current `<hs-action>` element, if present. */
+    action: HTMLElement | null;
+    url: string;
+    method: string;
+    /**
+     * Mutable. When `true` (default), appends `<hs-action-loading>` inside `<hs-action>` for the
+     * duration of the request. Set to `false` in `hs:action:before-fetch` to skip it.
+     */
+    loadingElement: boolean;
+  };
+
+  export type ActionSwapDetail = {
+    form: HTMLFormElement;
+    /** The current `<hs-action>` element, if present. */
+    action: HTMLElement | null;
+    html: string;
+    fullDocument: boolean;
+  };
+
+  export type ActionNavigateDetail = {
+    form: HTMLFormElement;
+    /** The current `<hs-action>` element, if present. */
+    action: HTMLElement | null;
+    url: string;
+    /**
+     * Mutable. Default is soft (false) for same-origin+same-path redirects, hard (true) otherwise.
+     * Set to `true` for `window.location.assign`, or `false` to fetch + morph in place.
+     */
+    hard: boolean;
+  };
+
   /**
    * Client JS Module = ESM Module + Public Path + Render Script Tag
    */
@@ -324,3 +374,20 @@ export namespace Hyperspan {
     formErrors: unknown[];
   }
 }
+
+declare global {
+  interface DocumentEventMap {
+    'hs:action:before-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;
+    'hs:action:after-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;
+    'hs:action:before-swap': CustomEvent<Hyperspan.ActionSwapDetail>;
+    'hs:action:after-swap': CustomEvent<Hyperspan.ActionSwapDetail>;
+    'hs:action:before-navigate': CustomEvent<Hyperspan.ActionNavigateDetail>;
+  }
+  interface HTMLElementEventMap {
+    'hs:action:before-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;
+    'hs:action:after-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;
+    'hs:action:before-swap': CustomEvent<Hyperspan.ActionSwapDetail>;
+    'hs:action:after-swap': CustomEvent<Hyperspan.ActionSwapDetail>;
+    'hs:action:before-navigate': CustomEvent<Hyperspan.ActionNavigateDetail>;
+  }
+}