@fictjs/ssr 0.19.0 → 0.21.0

package/dist/index.cjs

@@ -30,10 +30,11 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_runtime = require("@fictjs/runtime");
-var import_internal = require("@fictjs/runtime/internal");
+var import_internal2 = require("@fictjs/runtime/internal");
 var import_linkedom = require("linkedom");
 
 // src/globals.ts
+var import_internal = require("@fictjs/runtime/internal");
 function installGlobals(window, document) {
   const win = window;
   const required = {
@@ -83,6 +84,14 @@ function installManifest(manifest) {
   } else {
     resolved = manifest;
   }
+  const session = (0, import_internal.__fictGetCurrentSSRSession)();
+  if (session) {
+    const previous = session.manifest;
+    session.manifest = resolved;
+    return () => {
+      session.manifest = previous;
+    };
+  }
   const key = "__FICT_MANIFEST__";
   const snapshot = {
     exists: Object.prototype.hasOwnProperty.call(globalThis, key),
@@ -146,12 +155,33 @@ function getNodeRequire() {
 }
 
 // src/stream-bridge.ts
-function createQueuedTextStream() {
+function createQueuedTextStream(options = {}) {
   const encoder = new TextEncoder();
   const queue = [];
   let controller = null;
   let closed = false;
   let aborted;
+  const readyResolvers = [];
+  const resolveReady = () => {
+    if (!controller || (controller.desiredSize ?? 1) <= 0) return;
+    while (readyResolvers.length > 0) {
+      readyResolvers.shift()?.();
+    }
+  };
+  const drainReady = () => {
+    while (readyResolvers.length > 0) {
+      readyResolvers.shift()?.();
+    }
+  };
+  const abortQueue = (reason, notifyController = true) => {
+    if (closed || aborted !== void 0) return;
+    aborted = reason ?? new Error("Stream aborted");
+    queue.length = 0;
+    drainReady();
+    if (notifyController) {
+      controller?.error(aborted);
+    }
+  };
   const stream = new ReadableStream({
     start(ctrl) {
       controller = ctrl;
@@ -166,6 +196,13 @@ function createQueuedTextStream() {
       if (closed) {
         ctrl.close();
       }
+    },
+    pull() {
+      resolveReady();
+    },
+    cancel(reason) {
+      abortQueue(reason, false);
+      options.onCancel?.(reason);
     }
   });
   const writer = {
@@ -174,19 +211,24 @@ function createQueuedTextStream() {
       const data = encoder.encode(chunk);
       if (controller) {
         controller.enqueue(data);
+        if ((controller.desiredSize ?? 1) <= 0) {
+          return new Promise((resolve) => {
+            readyResolvers.push(resolve);
+          });
+        }
       } else {
         queue.push(data);
       }
+      return void 0;
     },
     close() {
       if (closed || aborted !== void 0) return;
       closed = true;
+      drainReady();
       controller?.close();
     },
     abort(reason) {
-      if (closed || aborted !== void 0) return;
-      aborted = reason ?? new Error("Stream aborted");
-      controller?.error(aborted);
+      abortQueue(reason);
     }
   };
   return { stream, writer };
@@ -200,9 +242,20 @@ function createPipeBridge() {
   let abortReason = null;
   const safeWrite = (target, chunk) => {
     try {
-      target.write(chunk);
+      const ready = target.write(chunk);
+      if (ready === false) {
+        return new Promise((resolve) => {
+          const withOnce = target;
+          if (typeof withOnce.once === "function") {
+            withOnce.once("drain", resolve);
+          } else {
+            resolve();
+          }
+        });
+      }
     } catch {
     }
+    return void 0;
   };
   const safeEnd = (target) => {
     try {
@@ -242,9 +295,12 @@ function createPipeBridge() {
         buffer.push(chunk);
         return;
       }
+      const pending = [];
       for (const target of targets) {
-        safeWrite(target, chunk);
+        const result = safeWrite(target, chunk);
+        if (result) pending.push(result);
       }
+      return pending.length > 0 ? Promise.all(pending).then(() => void 0) : void 0;
     },
     close() {
       if (state !== "open") return;
@@ -274,22 +330,78 @@ function createNodePipeBridge() {
     const streamModule = nodeRequire("node:stream");
     if (!streamModule.PassThrough) return null;
     const passThrough = new streamModule.PassThrough();
+    const buffer = [];
+    let piped = false;
+    let state = "open";
+    let abortReason = null;
+    const writeToPassThrough = (chunk) => {
+      if (passThrough.write(chunk) === false) {
+        return new Promise((resolve) => {
+          const withOnce = passThrough;
+          if (typeof withOnce.once === "function") {
+            withOnce.once("drain", resolve);
+          } else {
+            resolve();
+          }
+        });
+      }
+      return void 0;
+    };
+    const flushBuffer = () => {
+      if (buffer.length === 0) return void 0;
+      const pending = [];
+      for (const chunk of buffer) {
+        const result = writeToPassThrough(chunk);
+        if (result) pending.push(result);
+      }
+      buffer.length = 0;
+      return pending.length > 0 ? Promise.all(pending).then(() => void 0) : void 0;
+    };
+    const destroyPassThrough = (error) => {
+      if (typeof passThrough.destroy === "function") {
+        passThrough.destroy(error);
+      } else {
+        passThrough.end();
+      }
+    };
     return {
       pipe(writable) {
+        piped = true;
         passThrough.pipe(writable);
+        if (state === "aborted") {
+          destroyPassThrough(abortReason ?? new Error("Stream aborted"));
+          return;
+        }
+        const flushed = flushBuffer();
+        if (state === "closed") {
+          if (flushed) {
+            void flushed.then(() => passThrough.end());
+          } else {
+            passThrough.end();
+          }
+        }
       },
       write(chunk) {
-        passThrough.write(chunk);
+        if (state !== "open") return;
+        if (!piped) {
+          buffer.push(chunk);
+          return void 0;
+        }
+        return writeToPassThrough(chunk);
       },
       close() {
+        if (state !== "open") return;
+        state = "closed";
+        if (!piped) return;
         passThrough.end();
       },
       abort(reason) {
-        const error = reason instanceof Error ? reason : new Error("Stream aborted");
-        if (typeof passThrough.destroy === "function") {
-          passThrough.destroy(error);
-        } else {
-          passThrough.end();
+        if (state !== "open") return;
+        state = "aborted";
+        abortReason = reason instanceof Error ? reason : new Error("Stream aborted");
+        buffer.length = 0;
+        if (piped) {
+          destroyPassThrough(abortReason);
         }
       }
     };
@@ -310,6 +422,13 @@ function getNodeRequire2() {
   }
 }
 
+// src/stream-runtime.ts
+function createStreamRuntimeCode(options = {}) {
+  const observerMode = options.observerMode ?? true;
+  return `(function(){if(window.__FICT_STREAM)return;var cache=new Map();function find(id){var hit=cache.get(id);if(hit)return hit;var start=null,end=null;var w=document.createTreeWalker(document,NodeFilter.SHOW_COMMENT);while(w.nextNode()){var n=w.currentNode;var d=n.data;if(d==="fict:suspense-start:"+id)start=n;else if(d==="fict:suspense-end:"+id)end=n;if(start&&end)break;}if(start&&end){hit={start:start,end:end};cache.set(id,hit);}return hit;}function apply(id){var tpl=document.querySelector('template[data-fict-suspense="' + id + '"]');if(!tpl)return;var b=find(id);if(!b)return;var node=b.start.nextSibling;while(node&&node!==b.end){var next=node.nextSibling;node.parentNode&&node.parentNode.removeChild(node);node=next;}b.end.parentNode&&b.end.parentNode.insertBefore(tpl.content,b.end);tpl.parentNode&&tpl.parentNode.removeChild(tpl);}window.__FICT_STREAM={apply:apply};` + (observerMode ? 'function scan(root){var list=(root&&root.querySelectorAll?root:document).querySelectorAll("template[data-fict-suspense]");for(var i=0;i<list.length;i++){apply(list[i].getAttribute("data-fict-suspense"));}}if(typeof MutationObserver==="function"){new MutationObserver(function(muts){for(var i=0;i<muts.length;i++){for(var j=0;j<muts[i].addedNodes.length;j++){var n=muts[i].addedNodes[j];if(n.nodeType===1){if(n.matches&&n.matches("template[data-fict-suspense]"))apply(n.getAttribute("data-fict-suspense"));scan(n);}}}}).observe(document.documentElement||document,{childList:true,subtree:true});}if(document.readyState==="loading"){document.addEventListener("DOMContentLoaded",function(){scan(document);},{once:true});}else{scan(document);}' : "") + "})();";
+}
+var FICT_STREAM_RUNTIME_CODE = createStreamRuntimeCode({ observerMode: true });
+
 // src/index.ts
 var DEFAULT_HTML = "<!doctype html><html><head></head><body></body></html>";
 function createSSRDocument(html = DEFAULT_HTML) {
@@ -321,8 +440,12 @@ function createSSRDocument(html = DEFAULT_HTML) {
   return { window, document };
 }
 function renderToDocument(view, options = {}) {
+  const session = (0, import_internal2.__fictCreateSSRSession)();
+  return (0, import_internal2.__fictRunWithSSRSession)(session, () => renderToDocumentInSession(view, options));
+}
+function renderToDocumentInSession(view, options) {
   const includeSnapshot = options.includeSnapshot !== false;
-  (0, import_internal.__fictEnableSSR)();
+  (0, import_internal2.__fictEnableSSR)();
   let dom;
   let restoreGlobals2 = () => {
   };
@@ -334,23 +457,23 @@ function renderToDocument(view, options = {}) {
   try {
     dom = resolveDom(options);
     const { document, window } = dom;
-    const shouldExpose = options.exposeGlobals !== false;
+    const shouldExpose = options.exposeGlobals === true;
     restoreGlobals2 = shouldExpose ? installGlobals(window, document) : () => {
     };
     restoreManifest = installManifest(options.manifest);
     container = resolveContainer(document, options);
     teardown = (0, import_runtime.render)(view, container);
     if (includeSnapshot) {
-      const state = (0, import_internal.__fictSerializeSSRState)();
+      const state = (0, import_internal2.__fictSerializeSSRState)();
       injectSnapshot(document, container, state, options);
     }
   } catch (error) {
-    (0, import_internal.__fictDisableSSR)();
+    (0, import_internal2.__fictDisableSSR)();
     restoreGlobals2();
     restoreManifest();
     throw error;
   }
-  (0, import_internal.__fictDisableSSR)();
+  (0, import_internal2.__fictDisableSSR)();
   const html = serializeOutput(dom.document, container, options);
   const dispose = () => {
     try {
@@ -374,6 +497,37 @@ async function renderToStringAsync(view, options = {}) {
 function renderToStream(view, options = {}) {
   const encoder = new TextEncoder();
   let controller = null;
+  let abortRender = null;
+  const readyResolvers = [];
+  const drainBackpressure = () => {
+    while (readyResolvers.length > 0) {
+      readyResolvers.shift()?.();
+    }
+  };
+  const resolveBackpressure = () => {
+    if (!controller || (controller.desiredSize ?? 1) <= 0) return;
+    drainBackpressure();
+  };
+  const closeController = () => {
+    abortRender = null;
+    drainBackpressure();
+    if (!controller) return;
+    try {
+      controller.close();
+    } finally {
+      controller = null;
+    }
+  };
+  const errorController = (reason) => {
+    abortRender = null;
+    drainBackpressure();
+    if (!controller) return;
+    try {
+      controller.error(reason);
+    } finally {
+      controller = null;
+    }
+  };
   const stream = new ReadableStream({
     start(ctrl) {
       controller = ctrl;
@@ -381,15 +535,32 @@ function renderToStream(view, options = {}) {
         write(chunk) {
           if (!controller) return;
           controller.enqueue(encoder.encode(chunk));
+          if ((controller.desiredSize ?? 1) <= 0) {
+            return new Promise((resolve) => {
+              readyResolvers.push(resolve);
+            });
+          }
+          return void 0;
         },
         close() {
-          controller?.close();
+          closeController();
         },
         abort(reason) {
-          controller?.error(reason);
+          errorController(reason);
         }
       });
+      abortRender = started.abort;
+      started.shellReady.catch(() => void 0);
       started.allReady.catch(() => void 0);
+    },
+    pull() {
+      resolveBackpressure();
+    },
+    cancel(reason) {
+      const abort = abortRender;
+      controller = null;
+      drainBackpressure();
+      abort?.(reason ?? new Error("Stream canceled"));
     }
   });
   return stream;
@@ -398,7 +569,7 @@ function renderToPipeableStream(view, options = {}) {
   const bridge = createPipeBridge();
   const { shellReady, allReady, abort } = startStreamingRender(view, options, {
     write(chunk) {
-      bridge.write(chunk);
+      return bridge.write(chunk);
     },
     close() {
       bridge.close();
@@ -424,7 +595,12 @@ function renderToPartial(view, options = {}) {
   };
   let shell = "";
   let shellPhase = true;
-  const queued = createQueuedTextStream();
+  let abortPartial = null;
+  const queued = createQueuedTextStream({
+    onCancel(reason) {
+      abortPartial?.(reason ?? new Error("Stream canceled"));
+    }
+  });
   const { shellReady, allReady, abort } = startStreamingRender(
     view,
     partialOptions,
@@ -434,7 +610,7 @@ function renderToPartial(view, options = {}) {
           shell += chunk;
           return;
         }
-        queued.writer.write(chunk);
+        return queued.writer.write(chunk);
       },
       close() {
         queued.writer.close();
@@ -450,6 +626,7 @@ function renderToPartial(view, options = {}) {
       }
     }
   );
+  abortPartial = abort;
   return {
     shell,
     stream: queued.stream,
@@ -479,17 +656,39 @@ function resolveDom(options) {
   }
   return createSSRDocument(options.html);
 }
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && typeof value.then === "function";
+}
 function startStreamingRender(view, options, writer, control = {}) {
+  const session = (0, import_internal2.__fictCreateSSRSession)();
+  return (0, import_internal2.__fictRunWithSSRSession)(
+    session,
+    () => startStreamingRenderInSession(session, view, options, writer, control)
+  );
+}
+function startStreamingRenderInSession(session, view, options, writer, control = {}) {
+  const runInSession = (fn) => (0, import_internal2.__fictRunWithSSRSession)(session, fn);
   const resolvedOptions = {
     ...options,
     // Streaming requires a real document; default to fullDocument when unspecified.
     fullDocument: options.fullDocument ?? true
   };
   let resolveShell;
+  let rejectShell;
   let resolveAll;
   let rejectAll;
-  const shellReady = new Promise((res) => {
-    resolveShell = res;
+  let shellSettled = false;
+  const shellReady = new Promise((res, rej) => {
+    resolveShell = () => {
+      if (shellSettled) return;
+      shellSettled = true;
+      res();
+    };
+    rejectShell = (err) => {
+      if (shellSettled) return;
+      shellSettled = true;
+      rej(err);
+    };
   });
   const allReady = new Promise((res, rej) => {
     resolveAll = res;
@@ -507,44 +706,129 @@ function startStreamingRender(view, options, writer, control = {}) {
   let tailHtml = "";
   let wroteShell = false;
   let shellCarriesTail = false;
+  let writeChain = null;
+  let writeFailed = false;
+  let removeAbortListener = () => {
+  };
   const mode = options.mode ?? "shell";
   const includeSnapshot = options.includeSnapshot !== false;
   const sentScopes = /* @__PURE__ */ new Set();
   const boundaryMap = /* @__PURE__ */ new Map();
   let boundaryId = 0;
   let pendingCount = 0;
-  const writeSnapshotForScopes = (scopeIds) => {
-    if (!includeSnapshot || scopeIds.length === 0) return;
-    const registry = (0, import_internal.__fictGetScopeRegistry)();
-    const pending = scopeIds.filter((id) => registry.has(id) && !sentScopes.has(id));
-    if (pending.length === 0) return;
-    const snapshot = (0, import_internal.__fictSerializeSSRStateForScopes)(pending);
-    const ids = Object.keys(snapshot.scopes);
-    if (ids.length === 0) return;
-    const chunk = buildIncrementalSnapshotChunk(snapshot, resolvedOptions);
-    if (chunk) {
-      writer.write(chunk);
+  const handleWriteError = (error) => {
+    if (writeFailed) return;
+    writeFailed = true;
+    options.onError?.(error);
+    writer.abort(error);
+    cleanup();
+    rejectShell(error);
+    rejectAll(error);
+  };
+  const enqueueWrite = (chunk) => {
+    if (writeFailed) return;
+    const trackWrite = (promise) => {
+      const tracked = promise.then(
+        () => {
+          if (writeChain === tracked) {
+            writeChain = null;
+          }
+        },
+        (error) => {
+          if (writeChain === tracked) {
+            writeChain = null;
+          }
+          handleWriteError(error);
+        }
+      );
+      writeChain = tracked;
+    };
+    const writeAsync = () => Promise.resolve(writer.write(chunk)).then(() => void 0);
+    if (writeChain) {
+      trackWrite(writeChain.then(writeAsync));
+      return;
+    }
+    try {
+      const result = writer.write(chunk);
+      if (isPromiseLike(result)) {
+        trackWrite(
+          result.then(
+            () => void 0,
+            (error) => {
+              throw error;
+            }
+          )
+        );
+      }
+    } catch (error) {
+      handleWriteError(error);
     }
-    for (const id of ids) {
-      sentScopes.add(id);
+  };
+  const afterWrites = (fn) => {
+    const pending = writeChain;
+    if (!pending) {
+      if (!writeFailed) {
+        fn();
+      }
+      return;
     }
+    void pending.then(() => {
+      if (!writeFailed) {
+        fn();
+      }
+    });
+  };
+  const markShellReady = () => {
+    afterWrites(() => {
+      control.onShellFlushed?.();
+      resolveShell();
+      options.onShellReady?.();
+    });
+  };
+  const writeSnapshotForScopes = (scopeIds) => {
+    runInSession(() => {
+      if (!includeSnapshot || scopeIds.length === 0) return;
+      const registry = (0, import_internal2.__fictGetScopeRegistry)();
+      const pending = scopeIds.filter((id) => registry.has(id) && !sentScopes.has(id));
+      if (pending.length === 0) return;
+      const snapshot = (0, import_internal2.__fictSerializeSSRStateForScopes)(pending);
+      const ids = Object.keys(snapshot.scopes);
+      if (ids.length === 0) return;
+      const chunk = buildIncrementalSnapshotChunk(snapshot, resolvedOptions);
+      if (chunk) {
+        enqueueWrite(chunk);
+      }
+      for (const id of ids) {
+        sentScopes.add(id);
+      }
+    });
   };
   const writeSnapshotForBoundary = (boundary) => {
-    const scopes = (0, import_internal.__fictGetScopesForBoundary)(boundary);
-    writeSnapshotForScopes(scopes);
+    runInSession(() => {
+      const scopes = (0, import_internal2.__fictGetScopesForBoundary)(boundary);
+      writeSnapshotForScopes(scopes);
+    });
   };
   const writeRemainingSnapshots = () => {
-    const scopes = Array.from((0, import_internal.__fictGetScopeRegistry)().keys());
-    writeSnapshotForScopes(scopes);
+    runInSession(() => {
+      const scopes = Array.from((0, import_internal2.__fictGetScopeRegistry)().keys());
+      writeSnapshotForScopes(scopes);
+    });
   };
   const cleanup = () => {
-    (0, import_internal.__fictSetSSRStreamHooks)(null);
-    (0, import_internal.__fictDisableSSR)();
-    restoreGlobals2();
-    restoreManifest();
+    removeAbortListener();
+    removeAbortListener = () => {
+    };
+    runInSession(() => {
+      (0, import_internal2.__fictSetSSRStreamHooks)(null);
+      (0, import_internal2.__fictDisableSSR)();
+    });
     try {
       teardown();
     } catch {
+    } finally {
+      restoreGlobals2();
+      restoreManifest();
     }
   };
   const finalize = () => {
@@ -552,27 +836,31 @@ function startStreamingRender(view, options, writer, control = {}) {
     closed = true;
     if (mode === "all" && dom && container && !wroteShell) {
       if (includeSnapshot) {
-        const snapshot = (0, import_internal.__fictSerializeSSRState)();
+        const snapshot = (0, import_internal2.__fictSerializeSSRState)();
         injectSnapshot(dom.document, container, snapshot, resolvedOptions);
       }
       const fullHtml = serializeOutput(dom.document, container, resolvedOptions);
-      writer.write(fullHtml);
-      writer.close();
-      cleanup();
-      resolveShell();
-      resolveAll();
-      options.onShellReady?.();
-      options.onAllReady?.();
+      enqueueWrite(fullHtml);
+      afterWrites(() => {
+        writer.close();
+        cleanup();
+        resolveShell();
+        resolveAll();
+        options.onShellReady?.();
+        options.onAllReady?.();
+      });
       return;
     }
     writeRemainingSnapshots();
     if (tailHtml) {
-      writer.write(tailHtml);
+      enqueueWrite(tailHtml);
     }
-    writer.close();
-    cleanup();
-    resolveAll();
-    options.onAllReady?.();
+    afterWrites(() => {
+      writer.close();
+      cleanup();
+      resolveAll();
+      options.onAllReady?.();
+    });
   };
   const maybeFinalize = () => {
     if (pendingCount === 0) {
@@ -602,7 +890,7 @@ function startStreamingRender(view, options, writer, control = {}) {
         writeSnapshotForBoundary(id);
         if (dom) {
           const html = serializeBetween(dom.document, entry.start, entry.end);
-          writer.write(buildPatchChunk(id, html));
+          enqueueWrite(buildPatchChunk(id, html, resolvedOptions));
         }
       }
       maybeFinalize();
@@ -615,22 +903,28 @@ function startStreamingRender(view, options, writer, control = {}) {
   const abort = (reason) => {
     if (closed) return;
     closed = true;
+    writeFailed = true;
     writer.abort(reason);
     cleanup();
-    rejectAll(reason ?? new Error("Stream aborted"));
+    const abortReason = reason ?? new Error("Stream aborted");
+    rejectShell(abortReason);
+    rejectAll(abortReason);
   };
   if (options.signal) {
     if (options.signal.aborted) {
       abort(options.signal.reason);
+      return { shellReady, allReady, abort };
     } else {
-      options.signal.addEventListener("abort", () => abort(options.signal?.reason), { once: true });
+      const onAbort = () => abort(options.signal?.reason);
+      options.signal.addEventListener("abort", onAbort, { once: true });
+      removeAbortListener = () => options.signal?.removeEventListener("abort", onAbort);
     }
   }
   try {
-    (0, import_internal.__fictEnableSSR)();
-    (0, import_internal.__fictSetSSRStreamHooks)(hooks);
+    (0, import_internal2.__fictEnableSSR)();
+    (0, import_internal2.__fictSetSSRStreamHooks)(hooks);
     dom = resolveDom(resolvedOptions);
-    restoreGlobals2 = resolvedOptions.exposeGlobals !== false ? installGlobals(dom.window, dom.document) : () => {
+    restoreGlobals2 = resolvedOptions.exposeGlobals === true ? installGlobals(dom.window, dom.document) : () => {
     };
     restoreManifest = installManifest(resolvedOptions.manifest);
     container = resolveContainer(dom.document, resolvedOptions);
@@ -642,33 +936,31 @@ function startStreamingRender(view, options, writer, control = {}) {
       return { shellReady, allReady, abort };
     }
     const shellHtml = serializeOutput(dom.document, container, resolvedOptions);
-    const streamRuntime = boundaryMap.size > 0 ? buildStreamRuntimeScript() : "";
+    const streamRuntime = boundaryMap.size > 0 ? buildStreamRuntimeScript(resolvedOptions) : "";
     if (resolvedOptions.fullDocument) {
       const split = splitDocumentHtml(shellHtml);
       if (!split) {
         throw new Error("[fict/ssr] Failed to locate </body> for streaming output.");
       }
       if (control.includeTailInShell) {
-        writer.write(split.head + streamRuntime);
+        enqueueWrite(split.head + streamRuntime);
         tailHtml = split.tail;
         shellCarriesTail = true;
       } else {
-        writer.write(split.head + streamRuntime);
+        enqueueWrite(split.head + streamRuntime);
         tailHtml = split.tail;
       }
     } else {
-      writer.write(shellHtml + streamRuntime);
+      enqueueWrite(shellHtml + streamRuntime);
     }
     wroteShell = true;
-    writeSnapshotForScopes(Array.from((0, import_internal.__fictGetScopeRegistry)().keys()));
+    writeSnapshotForScopes(Array.from((0, import_internal2.__fictGetScopeRegistry)().keys()));
     if (shellCarriesTail && tailHtml) {
-      writer.write(tailHtml);
+      enqueueWrite(tailHtml);
       tailHtml = "";
       shellCarriesTail = false;
     }
-    control.onShellFlushed?.();
-    resolveShell();
-    options.onShellReady?.();
+    markShellReady();
     maybeFinalize();
   } catch (err) {
     options.onError?.(err);
@@ -699,11 +991,28 @@ function resolveContainer(document, options) {
   }
   return container;
 }
-function buildStreamRuntimeScript() {
-  return `<script>(function(){if(window.__FICT_STREAM)return;var cache=new Map();function find(id){var hit=cache.get(id);if(hit)return hit;var start=null,end=null;var w=document.createTreeWalker(document,NodeFilter.SHOW_COMMENT);while(w.nextNode()){var n=w.currentNode;var d=n.data;if(d==="fict:suspense-start:"+id)start=n;else if(d==="fict:suspense-end:"+id)end=n;if(start&&end)break;}if(start&&end){hit={start:start,end:end};cache.set(id,hit);}return hit;}function apply(id){var tpl=document.querySelector('template[data-fict-suspense="' + id + '"]');if(!tpl)return;var b=find(id);if(!b)return;var node=b.start.nextSibling;while(node&&node!==b.end){var next=node.nextSibling;node.parentNode&&node.parentNode.removeChild(node);node=next;}b.end.parentNode&&b.end.parentNode.insertBefore(tpl.content,b.end);tpl.parentNode&&tpl.parentNode.removeChild(tpl);}window.__FICT_STREAM={apply:apply};})();</script>`;
+function buildStreamRuntimeScript(options) {
+  const nonce = renderNonceAttribute(options);
+  if (options.streamRuntime === "external") {
+    if (!options.streamRuntimeSrc) {
+      throw new Error('[fict/ssr] streamRuntimeSrc is required when streamRuntime is "external".');
+    }
+    return `<script${nonce} src="${escapeAttribute(options.streamRuntimeSrc)}" data-fict-stream-runtime data-fict-stream-observer></script>`;
+  }
+  return `<script${nonce}>${createStreamRuntimeCode({
+    observerMode: resolveStreamPatchMode(options) === "observer"
+  })}</script>`;
 }
-function buildPatchChunk(id, html) {
-  return `<template data-fict-suspense="${id}">` + html + `</template><script>__FICT_STREAM.apply("${id}")</script>`;
+function buildPatchChunk(id, html, options) {
+  const template = `<template data-fict-suspense="${escapeAttribute(id)}">${html}</template>`;
+  if (resolveStreamPatchMode(options) === "observer") {
+    return template;
+  }
+  return `${template}<script${renderNonceAttribute(options)}>__FICT_STREAM.apply("${escapeScriptString(id)}")</script>`;
+}
+function resolveStreamPatchMode(options) {
+  if (options.streamPatchMode) return options.streamPatchMode;
+  return options.streamRuntime === "external" ? "observer" : "inline";
 }
 function serializeBetween(document, start, end) {
   const wrapper = document.createElement("div");
@@ -722,11 +1031,13 @@ function splitDocumentHtml(html) {
 }
 function buildIncrementalSnapshotChunk(state, options) {
   const json = serializeSnapshotForScript(state);
+  const nonce = renderNonceAttribute(options);
   if (options.snapshotTarget === "head") {
     const jsonLiteral = JSON.stringify(json);
-    return `<script>(function(){var s=document.createElement('script');s.type='application/json';s.setAttribute('data-fict-snapshot','');s.textContent=${jsonLiteral};(document.head||document.documentElement).appendChild(s);}())</script>`;
+    const setNonce = options.scriptNonce !== void 0 ? `s.setAttribute('nonce',${serializeScriptStringLiteral(options.scriptNonce)});` : "";
+    return `<script${nonce}>(function(){var s=document.createElement('script');s.type='application/json';s.setAttribute('data-fict-snapshot','');${setNonce}s.textContent=${jsonLiteral};(document.head||document.documentElement).appendChild(s);}())</script>`;
   }
-  return `<script type="application/json" data-fict-snapshot>${json}</script>`;
+  return `<script${nonce} type="application/json" data-fict-snapshot>${json}</script>`;
 }
 function serializeOutput(document, container, options) {
   if (options.fullDocument) {
@@ -743,6 +1054,9 @@ function injectSnapshot(document, container, state, options) {
   const script = document.createElement("script");
   script.type = "application/json";
   script.id = options.snapshotScriptId ?? "__FICT_SNAPSHOT__";
+  if (options.scriptNonce !== void 0) {
+    script.setAttribute("nonce", options.scriptNonce);
+  }
   script.textContent = serializeSnapshotForScript(state);
   if (options.fullDocument) {
     if (options.snapshotTarget === "head" && document.head) {
@@ -768,6 +1082,18 @@ function injectSnapshot(document, container, state, options) {
 function serializeSnapshotForScript(state) {
   return JSON.stringify(state).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
 }
+function serializeScriptStringLiteral(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+function renderNonceAttribute(options) {
+  return options.scriptNonce === void 0 ? "" : ` nonce="${escapeAttribute(options.scriptNonce)}"`;
+}
+function escapeAttribute(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeScriptString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
 function serializeDoctype(document, override) {
   if (override === null) return "";
   if (override !== void 0) return override;