@hyperspan/framework 1.0.26 → 1.0.27

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.27",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",

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

@@ -138,16 +138,8 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
 /** 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 +199,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 +227,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-->
               `;
             },
           }),