npm - @fictjs/ssr - Versions diffs - 0.5.1 → 0.5.2 - Mend

@fictjs/ssr 0.5.1 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -10,9 +10,12 @@ Fict's Server-Side Rendering (SSR) package, providing high-performance server-si
 - [Core Concepts](#core-concepts)
 - [API Reference](#api-reference)
 - [Architecture Design](#architecture-design)
+- [Partial Prerendering](#partial-prerendering)
+- [Edge Runtime](#edge-runtime)
 - [Integration with Vite](#integration-with-vite)
 - [Advanced Usage](#advanced-usage)
 - [Performance Optimization](#performance-optimization)
+- [Production Guides](#production-guides)
 - [Troubleshooting](#troubleshooting)
 ## Overview
@@ -268,6 +271,54 @@ interface RenderToDocumentResult extends SSRDom {
 Returns a DOM object for further manipulation or streaming rendering.
+### renderToStream
+Stream HTML to a Web `ReadableStream`. In `shell` mode, the fallback shell is
+sent immediately and Suspense boundaries patch in as they resolve.
+> Note: In `shell` mode, resumable snapshots are emitted incrementally as
+> `data-fict-snapshot` scripts (shell + each resolved boundary). When
+> `snapshotTarget: 'head'`, each chunk injects into `<head>` via a small script.
+```typescript
+import { renderToStream } from '@fictjs/ssr'
+const stream = renderToStream(() => <App />, { mode: 'shell' })
+```
+### renderToPipeableStream
+Node.js-style stream variant (compatible with `pipe()`).
+```typescript
+import { renderToPipeableStream } from '@fictjs/ssr'
+const { pipe, shellReady, allReady } = renderToPipeableStream(() => <App />, { mode: 'shell' })
+pipe(res)
+await shellReady
+await allReady
+```
+> Use `renderToStream()` in Edge runtimes (Cloudflare Workers, Vercel Edge, Deno Deploy).
+### renderToPartial
+Generate a complete shell HTML plus a deferred patch stream for Partial Prerendering workflows.
+This is an advanced API and currently considered **Preview** in v1.0.
+```typescript
+import { renderToPartial } from '@fictjs/ssr'
+const { shell, stream, shellReady, allReady } = renderToPartial(() => <App />, {
+  mode: 'shell',
+  fullDocument: true,
+})
+```
+- `shell`: complete HTML document (fallbacks + boundary markers + initial snapshots)
+- `stream`: patch chunks (`data-fict-suspense` + incremental snapshots) for deferred delivery
+- `shellReady` / `allReady`: readiness signals for orchestration
 ### createSSRDocument
 ```typescript
@@ -382,6 +433,25 @@ Generated detailed `fict.manifest.json` during production build, mapping virtual
 ## Integration with Vite
+## Partial Prerendering
+`renderToPartial()` enables a PPR-style split:
+1. **Shell phase**: serve/cache `shell` as static-first HTML.
+2. **Deferred phase**: deliver `stream` patches for resolved Suspense boundaries.
+This keeps shell TTFB low while still allowing server-resolved dynamic islands.
+## Edge Runtime
+`@fictjs/ssr` can run in Edge environments via `renderToStream()` and `renderToString()`.
+Notes:
+- `manifest` as an object works in all runtimes.
+- `manifest` as a file path string requires Node.js or Deno sync file access.
+- Prefer `renderToStream()` over `renderToPipeableStream()` for Edge.
 ### vite.config.ts
 ```typescript
@@ -463,23 +533,21 @@ app.get('*', async (req, res) => {
 })
 ```
-### Streaming Rendering (Experimental)
+### Streaming Rendering
 ```typescript
-import { renderToDocument } from '@fictjs/ssr'
+import { renderToPipeableStream } from '@fictjs/ssr'
 app.get('*', async (req, res) => {
-  const result = renderToDocument(() => <App />, {
-    includeSnapshot: true,
+  const { pipe, shellReady, allReady } = renderToPipeableStream(() => <App />, {
+    mode: 'shell',
   })
-  // Can send in chunks
-  res.write('<!DOCTYPE html><html><head>...</head><body>')
-  res.write(result.html)
-  res.write('</body></html>')
-  res.end()
+  res.setHeader('Content-Type', 'text/html; charset=utf-8')
+  pipe(res)
-  result.dispose()
+  await shellReady
+  await allReady
 })
 ```
@@ -546,6 +614,12 @@ let largeData = $state(hugeArray)
 let dataId = $state(id) // Store ID only, fetch on client
 ```
+## Production Guides
+- [SSR SEO Guide](../../docs/ssr-seo.md)
+- [SSR Performance Tuning](../../docs/ssr-performance.md)
+- [SSR Deployment Guide](../../docs/ssr-deployment.md)
 ## Troubleshooting
 ### Common Issues
@@ -604,8 +678,15 @@ onMount(async () => {
 console.log(globalThis.__FICT_MANIFEST__)
 // Check snapshot content
-const snapshot = document.getElementById('__FICT_SNAPSHOT__')
-console.log(JSON.parse(snapshot.textContent))
+const fullSnapshot = document.getElementById('__FICT_SNAPSHOT__')
+if (fullSnapshot?.textContent) {
+  console.log(JSON.parse(fullSnapshot.textContent))
+}
+// In streaming shell mode, snapshots are chunked:
+const snapshots = document.querySelectorAll('script[data-fict-snapshot]')
+for (const script of snapshots) {
+  console.log(JSON.parse(script.textContent || '{}'))
+}
 ```
 ## Related Packages

package/dist/index.cjs CHANGED Viewed

@@ -22,11 +22,13 @@ var index_exports = {};
 __export(index_exports, {
   createSSRDocument: () => createSSRDocument,
   renderToDocument: () => renderToDocument,
+  renderToPartial: () => renderToPartial,
+  renderToPipeableStream: () => renderToPipeableStream,
+  renderToStream: () => renderToStream,
   renderToString: () => renderToString,
   renderToStringAsync: () => renderToStringAsync
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_fs = require("fs");
 var import_runtime = require("@fictjs/runtime");
 var import_internal = require("@fictjs/runtime/internal");
 var import_linkedom = require("linkedom");
@@ -90,6 +92,93 @@ function renderToString(view, options = {}) {
 async function renderToStringAsync(view, options = {}) {
   return renderToString(view, options);
 }
+function renderToStream(view, options = {}) {
+  const encoder = new TextEncoder();
+  let controller = null;
+  const stream = new ReadableStream({
+    start(ctrl) {
+      controller = ctrl;
+      const started = startStreamingRender(view, options, {
+        write(chunk) {
+          if (!controller) return;
+          controller.enqueue(encoder.encode(chunk));
+        },
+        close() {
+          controller?.close();
+        },
+        abort(reason) {
+          controller?.error(reason);
+        }
+      });
+      started.allReady.catch(() => void 0);
+    }
+  });
+  return stream;
+}
+function renderToPipeableStream(view, options = {}) {
+  const bridge = createPipeBridge();
+  const { shellReady, allReady, abort } = startStreamingRender(view, options, {
+    write(chunk) {
+      bridge.write(chunk);
+    },
+    close() {
+      bridge.close();
+    },
+    abort(reason) {
+      bridge.abort(reason);
+    }
+  });
+  return {
+    pipe(writable) {
+      bridge.pipe(writable);
+    },
+    abort,
+    shellReady,
+    allReady
+  };
+}
+function renderToPartial(view, options = {}) {
+  const partialOptions = {
+    ...options,
+    mode: "shell",
+    fullDocument: options.fullDocument ?? true
+  };
+  let shell = "";
+  let shellPhase = true;
+  const queued = createQueuedTextStream();
+  const { shellReady, allReady, abort } = startStreamingRender(
+    view,
+    partialOptions,
+    {
+      write(chunk) {
+        if (shellPhase) {
+          shell += chunk;
+          return;
+        }
+        queued.writer.write(chunk);
+      },
+      close() {
+        queued.writer.close();
+      },
+      abort(reason) {
+        queued.writer.abort(reason);
+      }
+    },
+    {
+      includeTailInShell: true,
+      onShellFlushed() {
+        shellPhase = false;
+      }
+    }
+  );
+  return {
+    shell,
+    stream: queued.stream,
+    shellReady,
+    allReady,
+    abort
+  };
+}
 function resolveDom(options) {
   if (options.dom) {
     return options.dom;
@@ -111,6 +200,354 @@ function resolveDom(options) {
   }
   return createSSRDocument(options.html);
 }
+function createQueuedTextStream() {
+  const encoder = new TextEncoder();
+  const queue = [];
+  let controller = null;
+  let closed = false;
+  let aborted;
+  const stream = new ReadableStream({
+    start(ctrl) {
+      controller = ctrl;
+      for (const chunk of queue) {
+        ctrl.enqueue(chunk);
+      }
+      queue.length = 0;
+      if (aborted !== void 0) {
+        ctrl.error(aborted);
+        return;
+      }
+      if (closed) {
+        ctrl.close();
+      }
+    }
+  });
+  const writer = {
+    write(chunk) {
+      if (closed || aborted !== void 0) return;
+      const data = encoder.encode(chunk);
+      if (controller) {
+        controller.enqueue(data);
+      } else {
+        queue.push(data);
+      }
+    },
+    close() {
+      if (closed || aborted !== void 0) return;
+      closed = true;
+      controller?.close();
+    },
+    abort(reason) {
+      if (closed || aborted !== void 0) return;
+      aborted = reason ?? new Error("Stream aborted");
+      controller?.error(aborted);
+    }
+  };
+  return { stream, writer };
+}
+function createPipeBridge() {
+  const nodeBridge = createNodePipeBridge();
+  if (nodeBridge) return nodeBridge;
+  const targets = /* @__PURE__ */ new Set();
+  const buffer = [];
+  let state = "open";
+  let abortReason = null;
+  const safeWrite = (target, chunk) => {
+    try {
+      target.write(chunk);
+    } catch {
+    }
+  };
+  const safeEnd = (target) => {
+    try {
+      target.end();
+    } catch {
+    }
+  };
+  const safeDestroy = (target, reason) => {
+    const withDestroy = target;
+    if (typeof withDestroy.destroy === "function") {
+      try {
+        withDestroy.destroy(reason);
+      } catch {
+      }
+      return;
+    }
+    safeEnd(target);
+  };
+  return {
+    pipe(writable) {
+      targets.add(writable);
+      if (buffer.length > 0) {
+        for (const chunk of buffer) {
+          safeWrite(writable, chunk);
+        }
+        buffer.length = 0;
+      }
+      if (state === "closed") {
+        safeEnd(writable);
+      } else if (state === "aborted") {
+        safeDestroy(writable, abortReason ?? new Error("Stream aborted"));
+      }
+    },
+    write(chunk) {
+      if (state !== "open") return;
+      if (targets.size === 0) {
+        buffer.push(chunk);
+        return;
+      }
+      for (const target of targets) {
+        safeWrite(target, chunk);
+      }
+    },
+    close() {
+      if (state !== "open") return;
+      state = "closed";
+      for (const target of targets) {
+        safeEnd(target);
+      }
+      if (targets.size > 0) {
+        buffer.length = 0;
+      }
+    },
+    abort(reason) {
+      if (state !== "open") return;
+      state = "aborted";
+      abortReason = reason instanceof Error ? reason : new Error("Stream aborted");
+      for (const target of targets) {
+        safeDestroy(target, abortReason);
+      }
+      buffer.length = 0;
+    }
+  };
+}
+function createNodePipeBridge() {
+  const nodeRequire = getNodeRequire();
+  if (!nodeRequire) return null;
+  try {
+    const streamModule = nodeRequire("node:stream");
+    if (!streamModule.PassThrough) return null;
+    const passThrough = new streamModule.PassThrough();
+    return {
+      pipe(writable) {
+        passThrough.pipe(writable);
+      },
+      write(chunk) {
+        passThrough.write(chunk);
+      },
+      close() {
+        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();
+        }
+      }
+    };
+  } catch {
+    return null;
+  }
+}
+function startStreamingRender(view, options, writer, control = {}) {
+  const resolvedOptions = {
+    ...options,
+    // Streaming requires a real document; default to fullDocument when unspecified.
+    fullDocument: options.fullDocument ?? true
+  };
+  let resolveShell;
+  let resolveAll;
+  let rejectAll;
+  const shellReady = new Promise((res) => {
+    resolveShell = res;
+  });
+  const allReady = new Promise((res, rej) => {
+    resolveAll = res;
+    rejectAll = rej;
+  });
+  let dom = null;
+  let restoreGlobals2 = () => {
+  };
+  let restoreManifest = () => {
+  };
+  let teardown = () => {
+  };
+  let container = null;
+  let closed = false;
+  let tailHtml = "";
+  let wroteShell = false;
+  let shellCarriesTail = false;
+  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);
+    }
+    for (const id of ids) {
+      sentScopes.add(id);
+    }
+  };
+  const writeSnapshotForBoundary = (boundary) => {
+    const scopes = (0, import_internal.__fictGetScopesForBoundary)(boundary);
+    writeSnapshotForScopes(scopes);
+  };
+  const writeRemainingSnapshots = () => {
+    const scopes = Array.from((0, import_internal.__fictGetScopeRegistry)().keys());
+    writeSnapshotForScopes(scopes);
+  };
+  const cleanup = () => {
+    (0, import_internal.__fictSetSSRStreamHooks)(null);
+    (0, import_internal.__fictDisableSSR)();
+    restoreGlobals2();
+    restoreManifest();
+    try {
+      teardown();
+    } catch {
+    }
+  };
+  const finalize = () => {
+    if (closed) return;
+    closed = true;
+    if (mode === "all" && dom && container && !wroteShell) {
+      if (includeSnapshot) {
+        const snapshot = (0, import_internal.__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?.();
+      return;
+    }
+    writeRemainingSnapshots();
+    if (tailHtml) {
+      writer.write(tailHtml);
+    }
+    writer.close();
+    cleanup();
+    resolveAll();
+    options.onAllReady?.();
+  };
+  const maybeFinalize = () => {
+    if (pendingCount === 0) {
+      finalize();
+    }
+  };
+  const hooks = {
+    registerBoundary(start, end) {
+      const id = `s${++boundaryId}`;
+      boundaryMap.set(id, { start, end, pending: false });
+      return id;
+    },
+    boundaryPending(id) {
+      const entry = boundaryMap.get(id);
+      if (!entry || entry.pending) return;
+      entry.pending = true;
+      pendingCount++;
+    },
+    boundaryResolved(id) {
+      const entry = boundaryMap.get(id);
+      if (!entry) return;
+      if (entry.pending) {
+        entry.pending = false;
+        pendingCount = Math.max(0, pendingCount - 1);
+      }
+      if (mode === "shell") {
+        writeSnapshotForBoundary(id);
+        if (dom) {
+          const html = serializeBetween(dom.document, entry.start, entry.end);
+          writer.write(buildPatchChunk(id, html));
+        }
+      }
+      maybeFinalize();
+    },
+    onError(err) {
+      options.onError?.(err);
+      abort(err);
+    }
+  };
+  const abort = (reason) => {
+    if (closed) return;
+    closed = true;
+    writer.abort(reason);
+    cleanup();
+    rejectAll(reason ?? new Error("Stream aborted"));
+  };
+  if (options.signal) {
+    if (options.signal.aborted) {
+      abort(options.signal.reason);
+    } else {
+      options.signal.addEventListener("abort", () => abort(options.signal?.reason), { once: true });
+    }
+  }
+  try {
+    (0, import_internal.__fictEnableSSR)();
+    (0, import_internal.__fictSetSSRStreamHooks)(hooks);
+    dom = resolveDom(resolvedOptions);
+    restoreGlobals2 = resolvedOptions.exposeGlobals !== false ? installGlobals(dom.window, dom.document) : () => {
+    };
+    restoreManifest = installManifest(resolvedOptions.manifest);
+    container = resolveContainer(dom.document, resolvedOptions);
+    teardown = (0, import_runtime.render)(view, container);
+    if (mode === "all") {
+      if (pendingCount === 0) {
+        finalize();
+      }
+      return { shellReady, allReady, abort };
+    }
+    const shellHtml = serializeOutput(dom.document, container, resolvedOptions);
+    const streamRuntime = boundaryMap.size > 0 ? buildStreamRuntimeScript() : "";
+    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);
+        tailHtml = split.tail;
+        shellCarriesTail = true;
+      } else {
+        writer.write(split.head + streamRuntime);
+        tailHtml = split.tail;
+      }
+    } else {
+      writer.write(shellHtml + streamRuntime);
+    }
+    wroteShell = true;
+    writeSnapshotForScopes(Array.from((0, import_internal.__fictGetScopeRegistry)().keys()));
+    if (shellCarriesTail && tailHtml) {
+      writer.write(tailHtml);
+      tailHtml = "";
+      shellCarriesTail = false;
+    }
+    control.onShellFlushed?.();
+    resolveShell();
+    options.onShellReady?.();
+    maybeFinalize();
+  } catch (err) {
+    options.onError?.(err);
+    abort(err);
+  }
+  return { shellReady, allReady, abort };
+}
 function resolveContainer(document, options) {
   if (options.container) {
     if (options.container.ownerDocument && options.container.ownerDocument !== document) {
@@ -134,6 +571,35 @@ 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 buildPatchChunk(id, html) {
+  return `<template data-fict-suspense="${id}">` + html + `</template><script>__FICT_STREAM.apply("${id}")</script>`;
+}
+function serializeBetween(document, start, end) {
+  const wrapper = document.createElement("div");
+  let node = start.nextSibling;
+  while (node && node !== end) {
+    wrapper.appendChild(node.cloneNode(true));
+    node = node.nextSibling;
+  }
+  return wrapper.innerHTML;
+}
+function splitDocumentHtml(html) {
+  const lower = html.toLowerCase();
+  const idx = lower.lastIndexOf("</body>");
+  if (idx === -1) return null;
+  return { head: html.slice(0, idx), tail: html.slice(idx) };
+}
+function buildIncrementalSnapshotChunk(state, options) {
+  const json = JSON.stringify(state);
+  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>`;
+  }
+  return `<script type="application/json" data-fict-snapshot>${json}</script>`;
+}
 function serializeOutput(document, container, options) {
   if (options.fullDocument) {
     const doctype = serializeDoctype(document, options.doctype);
@@ -248,12 +714,39 @@ function restoreGlobals(snapshot) {
     }
   }
 }
+function readTextFileFromPath(path) {
+  const g = globalThis;
+  const deno = g.Deno;
+  if (deno && typeof deno.readTextFileSync === "function") {
+    return deno.readTextFileSync(path);
+  }
+  const nodeRequire = getNodeRequire();
+  if (nodeRequire) {
+    const fs = nodeRequire("node:fs");
+    return fs.readFileSync(path, "utf8");
+  }
+  throw new Error(
+    "[fict/ssr] `manifest` as file path is only supported in Node.js or Deno. Pass a manifest object in edge runtimes."
+  );
+}
+function getNodeRequire() {
+  const g = globalThis;
+  const direct = g.require;
+  if (typeof direct === "function") {
+    return direct;
+  }
+  try {
+    return Function('return typeof require === "function" ? require : null')();
+  } catch {
+    return null;
+  }
+}
 function installManifest(manifest) {
   if (!manifest) return () => {
   };
   let resolved;
   if (typeof manifest === "string") {
-    const raw = (0, import_node_fs.readFileSync)(manifest, "utf8");
+    const raw = readTextFileFromPath(manifest);
     resolved = JSON.parse(raw);
   } else {
     resolved = manifest;
@@ -277,6 +770,9 @@ function installManifest(manifest) {
 0 && (module.exports = {
   createSSRDocument,
   renderToDocument,
+  renderToPartial,
+  renderToPipeableStream,
+  renderToStream,
   renderToString,
   renderToStringAsync
 });

package/dist/index.d.cts CHANGED Viewed

@@ -59,6 +59,7 @@ interface RenderToStringOptions {
     /**
      * Manifest mapping module URLs to built client chunk URLs.
      * Can be an object or a path to a JSON file.
+     * File path mode requires Node.js or Deno filesystem access.
      */
     manifest?: Record<string, string> | string;
     /**
@@ -76,6 +77,49 @@ interface RenderToStringOptions {
      */
     snapshotTarget?: 'container' | 'body' | 'head';
 }
+interface RenderToStreamOptions extends RenderToStringOptions {
+    /**
+     * Streaming mode:
+     * - 'shell': send fallback shell first, then patch resolved boundaries
+     * - 'all': wait for all suspense boundaries, then send full HTML
+     */
+    mode?: 'shell' | 'all';
+    /**
+     * Called once the initial shell has been written.
+     */
+    onShellReady?: () => void;
+    /**
+     * Called once all pending boundaries resolve and the stream completes.
+     */
+    onAllReady?: () => void;
+    /**
+     * Called when an error occurs during streaming.
+     */
+    onError?: (err: unknown) => void;
+    /**
+     * Abort signal to cancel the stream.
+     */
+    signal?: AbortSignal;
+}
+interface PipeableStream {
+    pipe: (writable: NodeJS.WritableStream) => void;
+    abort: (reason?: unknown) => void;
+    shellReady: Promise<void>;
+    allReady: Promise<void>;
+}
+interface PartialPrerenderResult {
+    /**
+     * Complete shell HTML (fallbacks + markers + initial snapshot scripts).
+     */
+    shell: string;
+    /**
+     * Stream of deferred patch chunks and incremental snapshots.
+     */
+    stream: ReadableStream<Uint8Array>;
+    shellReady: Promise<void>;
+    allReady: Promise<void>;
+    abort: (reason?: unknown) => void;
+}
 interface RenderToDocumentResult extends SSRDom {
     html: string;
     container: HTMLElement;
@@ -85,5 +129,8 @@ declare function createSSRDocument(html?: string): SSRDom;
 declare function renderToDocument(view: () => FictNode, options?: RenderToStringOptions): RenderToDocumentResult;
 declare function renderToString(view: () => FictNode, options?: RenderToStringOptions): string;
 declare function renderToStringAsync(view: () => FictNode, options?: RenderToStringOptions): Promise<string>;
+declare function renderToStream(view: () => FictNode, options?: RenderToStreamOptions): ReadableStream<Uint8Array>;
+declare function renderToPipeableStream(view: () => FictNode, options?: RenderToStreamOptions): PipeableStream;
+declare function renderToPartial(view: () => FictNode, options?: RenderToStreamOptions): PartialPrerenderResult;
-export { type RenderToDocumentResult, type RenderToStringOptions, type SSRDom, createSSRDocument, renderToDocument, renderToString, renderToStringAsync };
+export { type PartialPrerenderResult, type PipeableStream, type RenderToDocumentResult, type RenderToStreamOptions, type RenderToStringOptions, type SSRDom, createSSRDocument, renderToDocument, renderToPartial, renderToPipeableStream, renderToStream, renderToString, renderToStringAsync };

package/dist/index.d.ts CHANGED Viewed

@@ -59,6 +59,7 @@ interface RenderToStringOptions {
     /**
      * Manifest mapping module URLs to built client chunk URLs.
      * Can be an object or a path to a JSON file.
+     * File path mode requires Node.js or Deno filesystem access.
      */
     manifest?: Record<string, string> | string;
     /**
@@ -76,6 +77,49 @@ interface RenderToStringOptions {
      */
     snapshotTarget?: 'container' | 'body' | 'head';
 }
+interface RenderToStreamOptions extends RenderToStringOptions {
+    /**
+     * Streaming mode:
+     * - 'shell': send fallback shell first, then patch resolved boundaries
+     * - 'all': wait for all suspense boundaries, then send full HTML
+     */
+    mode?: 'shell' | 'all';
+    /**
+     * Called once the initial shell has been written.
+     */
+    onShellReady?: () => void;
+    /**
+     * Called once all pending boundaries resolve and the stream completes.
+     */
+    onAllReady?: () => void;
+    /**
+     * Called when an error occurs during streaming.
+     */
+    onError?: (err: unknown) => void;
+    /**
+     * Abort signal to cancel the stream.
+     */
+    signal?: AbortSignal;
+}
+interface PipeableStream {
+    pipe: (writable: NodeJS.WritableStream) => void;
+    abort: (reason?: unknown) => void;
+    shellReady: Promise<void>;
+    allReady: Promise<void>;
+}
+interface PartialPrerenderResult {
+    /**
+     * Complete shell HTML (fallbacks + markers + initial snapshot scripts).
+     */
+    shell: string;
+    /**
+     * Stream of deferred patch chunks and incremental snapshots.
+     */
+    stream: ReadableStream<Uint8Array>;
+    shellReady: Promise<void>;
+    allReady: Promise<void>;
+    abort: (reason?: unknown) => void;
+}
 interface RenderToDocumentResult extends SSRDom {
     html: string;
     container: HTMLElement;
@@ -85,5 +129,8 @@ declare function createSSRDocument(html?: string): SSRDom;
 declare function renderToDocument(view: () => FictNode, options?: RenderToStringOptions): RenderToDocumentResult;
 declare function renderToString(view: () => FictNode, options?: RenderToStringOptions): string;
 declare function renderToStringAsync(view: () => FictNode, options?: RenderToStringOptions): Promise<string>;
+declare function renderToStream(view: () => FictNode, options?: RenderToStreamOptions): ReadableStream<Uint8Array>;
+declare function renderToPipeableStream(view: () => FictNode, options?: RenderToStreamOptions): PipeableStream;
+declare function renderToPartial(view: () => FictNode, options?: RenderToStreamOptions): PartialPrerenderResult;
-export { type RenderToDocumentResult, type RenderToStringOptions, type SSRDom, createSSRDocument, renderToDocument, renderToString, renderToStringAsync };
+export { type PartialPrerenderResult, type PipeableStream, type RenderToDocumentResult, type RenderToStreamOptions, type RenderToStringOptions, type SSRDom, createSSRDocument, renderToDocument, renderToPartial, renderToPipeableStream, renderToStream, renderToString, renderToStringAsync };

package/dist/index.js CHANGED Viewed

@@ -1,10 +1,13 @@
 // src/index.ts
-import { readFileSync } from "fs";
 import { render } from "@fictjs/runtime";
 import {
   __fictDisableSSR,
   __fictEnableSSR,
-  __fictSerializeSSRState
+  __fictGetScopeRegistry,
+  __fictGetScopesForBoundary,
+  __fictSerializeSSRState,
+  __fictSerializeSSRStateForScopes,
+  __fictSetSSRStreamHooks
 } from "@fictjs/runtime/internal";
 import { parseHTML } from "linkedom";
 var DEFAULT_HTML = "<!doctype html><html><head></head><body></body></html>";
@@ -67,6 +70,93 @@ function renderToString(view, options = {}) {
 async function renderToStringAsync(view, options = {}) {
   return renderToString(view, options);
 }
+function renderToStream(view, options = {}) {
+  const encoder = new TextEncoder();
+  let controller = null;
+  const stream = new ReadableStream({
+    start(ctrl) {
+      controller = ctrl;
+      const started = startStreamingRender(view, options, {
+        write(chunk) {
+          if (!controller) return;
+          controller.enqueue(encoder.encode(chunk));
+        },
+        close() {
+          controller?.close();
+        },
+        abort(reason) {
+          controller?.error(reason);
+        }
+      });
+      started.allReady.catch(() => void 0);
+    }
+  });
+  return stream;
+}
+function renderToPipeableStream(view, options = {}) {
+  const bridge = createPipeBridge();
+  const { shellReady, allReady, abort } = startStreamingRender(view, options, {
+    write(chunk) {
+      bridge.write(chunk);
+    },
+    close() {
+      bridge.close();
+    },
+    abort(reason) {
+      bridge.abort(reason);
+    }
+  });
+  return {
+    pipe(writable) {
+      bridge.pipe(writable);
+    },
+    abort,
+    shellReady,
+    allReady
+  };
+}
+function renderToPartial(view, options = {}) {
+  const partialOptions = {
+    ...options,
+    mode: "shell",
+    fullDocument: options.fullDocument ?? true
+  };
+  let shell = "";
+  let shellPhase = true;
+  const queued = createQueuedTextStream();
+  const { shellReady, allReady, abort } = startStreamingRender(
+    view,
+    partialOptions,
+    {
+      write(chunk) {
+        if (shellPhase) {
+          shell += chunk;
+          return;
+        }
+        queued.writer.write(chunk);
+      },
+      close() {
+        queued.writer.close();
+      },
+      abort(reason) {
+        queued.writer.abort(reason);
+      }
+    },
+    {
+      includeTailInShell: true,
+      onShellFlushed() {
+        shellPhase = false;
+      }
+    }
+  );
+  return {
+    shell,
+    stream: queued.stream,
+    shellReady,
+    allReady,
+    abort
+  };
+}
 function resolveDom(options) {
   if (options.dom) {
     return options.dom;
@@ -88,6 +178,354 @@ function resolveDom(options) {
   }
   return createSSRDocument(options.html);
 }
+function createQueuedTextStream() {
+  const encoder = new TextEncoder();
+  const queue = [];
+  let controller = null;
+  let closed = false;
+  let aborted;
+  const stream = new ReadableStream({
+    start(ctrl) {
+      controller = ctrl;
+      for (const chunk of queue) {
+        ctrl.enqueue(chunk);
+      }
+      queue.length = 0;
+      if (aborted !== void 0) {
+        ctrl.error(aborted);
+        return;
+      }
+      if (closed) {
+        ctrl.close();
+      }
+    }
+  });
+  const writer = {
+    write(chunk) {
+      if (closed || aborted !== void 0) return;
+      const data = encoder.encode(chunk);
+      if (controller) {
+        controller.enqueue(data);
+      } else {
+        queue.push(data);
+      }
+    },
+    close() {
+      if (closed || aborted !== void 0) return;
+      closed = true;
+      controller?.close();
+    },
+    abort(reason) {
+      if (closed || aborted !== void 0) return;
+      aborted = reason ?? new Error("Stream aborted");
+      controller?.error(aborted);
+    }
+  };
+  return { stream, writer };
+}
+function createPipeBridge() {
+  const nodeBridge = createNodePipeBridge();
+  if (nodeBridge) return nodeBridge;
+  const targets = /* @__PURE__ */ new Set();
+  const buffer = [];
+  let state = "open";
+  let abortReason = null;
+  const safeWrite = (target, chunk) => {
+    try {
+      target.write(chunk);
+    } catch {
+    }
+  };
+  const safeEnd = (target) => {
+    try {
+      target.end();
+    } catch {
+    }
+  };
+  const safeDestroy = (target, reason) => {
+    const withDestroy = target;
+    if (typeof withDestroy.destroy === "function") {
+      try {
+        withDestroy.destroy(reason);
+      } catch {
+      }
+      return;
+    }
+    safeEnd(target);
+  };
+  return {
+    pipe(writable) {
+      targets.add(writable);
+      if (buffer.length > 0) {
+        for (const chunk of buffer) {
+          safeWrite(writable, chunk);
+        }
+        buffer.length = 0;
+      }
+      if (state === "closed") {
+        safeEnd(writable);
+      } else if (state === "aborted") {
+        safeDestroy(writable, abortReason ?? new Error("Stream aborted"));
+      }
+    },
+    write(chunk) {
+      if (state !== "open") return;
+      if (targets.size === 0) {
+        buffer.push(chunk);
+        return;
+      }
+      for (const target of targets) {
+        safeWrite(target, chunk);
+      }
+    },
+    close() {
+      if (state !== "open") return;
+      state = "closed";
+      for (const target of targets) {
+        safeEnd(target);
+      }
+      if (targets.size > 0) {
+        buffer.length = 0;
+      }
+    },
+    abort(reason) {
+      if (state !== "open") return;
+      state = "aborted";
+      abortReason = reason instanceof Error ? reason : new Error("Stream aborted");
+      for (const target of targets) {
+        safeDestroy(target, abortReason);
+      }
+      buffer.length = 0;
+    }
+  };
+}
+function createNodePipeBridge() {
+  const nodeRequire = getNodeRequire();
+  if (!nodeRequire) return null;
+  try {
+    const streamModule = nodeRequire("node:stream");
+    if (!streamModule.PassThrough) return null;
+    const passThrough = new streamModule.PassThrough();
+    return {
+      pipe(writable) {
+        passThrough.pipe(writable);
+      },
+      write(chunk) {
+        passThrough.write(chunk);
+      },
+      close() {
+        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();
+        }
+      }
+    };
+  } catch {
+    return null;
+  }
+}
+function startStreamingRender(view, options, writer, control = {}) {
+  const resolvedOptions = {
+    ...options,
+    // Streaming requires a real document; default to fullDocument when unspecified.
+    fullDocument: options.fullDocument ?? true
+  };
+  let resolveShell;
+  let resolveAll;
+  let rejectAll;
+  const shellReady = new Promise((res) => {
+    resolveShell = res;
+  });
+  const allReady = new Promise((res, rej) => {
+    resolveAll = res;
+    rejectAll = rej;
+  });
+  let dom = null;
+  let restoreGlobals2 = () => {
+  };
+  let restoreManifest = () => {
+  };
+  let teardown = () => {
+  };
+  let container = null;
+  let closed = false;
+  let tailHtml = "";
+  let wroteShell = false;
+  let shellCarriesTail = false;
+  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 = __fictGetScopeRegistry();
+    const pending = scopeIds.filter((id) => registry.has(id) && !sentScopes.has(id));
+    if (pending.length === 0) return;
+    const snapshot = __fictSerializeSSRStateForScopes(pending);
+    const ids = Object.keys(snapshot.scopes);
+    if (ids.length === 0) return;
+    const chunk = buildIncrementalSnapshotChunk(snapshot, resolvedOptions);
+    if (chunk) {
+      writer.write(chunk);
+    }
+    for (const id of ids) {
+      sentScopes.add(id);
+    }
+  };
+  const writeSnapshotForBoundary = (boundary) => {
+    const scopes = __fictGetScopesForBoundary(boundary);
+    writeSnapshotForScopes(scopes);
+  };
+  const writeRemainingSnapshots = () => {
+    const scopes = Array.from(__fictGetScopeRegistry().keys());
+    writeSnapshotForScopes(scopes);
+  };
+  const cleanup = () => {
+    __fictSetSSRStreamHooks(null);
+    __fictDisableSSR();
+    restoreGlobals2();
+    restoreManifest();
+    try {
+      teardown();
+    } catch {
+    }
+  };
+  const finalize = () => {
+    if (closed) return;
+    closed = true;
+    if (mode === "all" && dom && container && !wroteShell) {
+      if (includeSnapshot) {
+        const snapshot = __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?.();
+      return;
+    }
+    writeRemainingSnapshots();
+    if (tailHtml) {
+      writer.write(tailHtml);
+    }
+    writer.close();
+    cleanup();
+    resolveAll();
+    options.onAllReady?.();
+  };
+  const maybeFinalize = () => {
+    if (pendingCount === 0) {
+      finalize();
+    }
+  };
+  const hooks = {
+    registerBoundary(start, end) {
+      const id = `s${++boundaryId}`;
+      boundaryMap.set(id, { start, end, pending: false });
+      return id;
+    },
+    boundaryPending(id) {
+      const entry = boundaryMap.get(id);
+      if (!entry || entry.pending) return;
+      entry.pending = true;
+      pendingCount++;
+    },
+    boundaryResolved(id) {
+      const entry = boundaryMap.get(id);
+      if (!entry) return;
+      if (entry.pending) {
+        entry.pending = false;
+        pendingCount = Math.max(0, pendingCount - 1);
+      }
+      if (mode === "shell") {
+        writeSnapshotForBoundary(id);
+        if (dom) {
+          const html = serializeBetween(dom.document, entry.start, entry.end);
+          writer.write(buildPatchChunk(id, html));
+        }
+      }
+      maybeFinalize();
+    },
+    onError(err) {
+      options.onError?.(err);
+      abort(err);
+    }
+  };
+  const abort = (reason) => {
+    if (closed) return;
+    closed = true;
+    writer.abort(reason);
+    cleanup();
+    rejectAll(reason ?? new Error("Stream aborted"));
+  };
+  if (options.signal) {
+    if (options.signal.aborted) {
+      abort(options.signal.reason);
+    } else {
+      options.signal.addEventListener("abort", () => abort(options.signal?.reason), { once: true });
+    }
+  }
+  try {
+    __fictEnableSSR();
+    __fictSetSSRStreamHooks(hooks);
+    dom = resolveDom(resolvedOptions);
+    restoreGlobals2 = resolvedOptions.exposeGlobals !== false ? installGlobals(dom.window, dom.document) : () => {
+    };
+    restoreManifest = installManifest(resolvedOptions.manifest);
+    container = resolveContainer(dom.document, resolvedOptions);
+    teardown = render(view, container);
+    if (mode === "all") {
+      if (pendingCount === 0) {
+        finalize();
+      }
+      return { shellReady, allReady, abort };
+    }
+    const shellHtml = serializeOutput(dom.document, container, resolvedOptions);
+    const streamRuntime = boundaryMap.size > 0 ? buildStreamRuntimeScript() : "";
+    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);
+        tailHtml = split.tail;
+        shellCarriesTail = true;
+      } else {
+        writer.write(split.head + streamRuntime);
+        tailHtml = split.tail;
+      }
+    } else {
+      writer.write(shellHtml + streamRuntime);
+    }
+    wroteShell = true;
+    writeSnapshotForScopes(Array.from(__fictGetScopeRegistry().keys()));
+    if (shellCarriesTail && tailHtml) {
+      writer.write(tailHtml);
+      tailHtml = "";
+      shellCarriesTail = false;
+    }
+    control.onShellFlushed?.();
+    resolveShell();
+    options.onShellReady?.();
+    maybeFinalize();
+  } catch (err) {
+    options.onError?.(err);
+    abort(err);
+  }
+  return { shellReady, allReady, abort };
+}
 function resolveContainer(document, options) {
   if (options.container) {
     if (options.container.ownerDocument && options.container.ownerDocument !== document) {
@@ -111,6 +549,35 @@ 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 buildPatchChunk(id, html) {
+  return `<template data-fict-suspense="${id}">` + html + `</template><script>__FICT_STREAM.apply("${id}")</script>`;
+}
+function serializeBetween(document, start, end) {
+  const wrapper = document.createElement("div");
+  let node = start.nextSibling;
+  while (node && node !== end) {
+    wrapper.appendChild(node.cloneNode(true));
+    node = node.nextSibling;
+  }
+  return wrapper.innerHTML;
+}
+function splitDocumentHtml(html) {
+  const lower = html.toLowerCase();
+  const idx = lower.lastIndexOf("</body>");
+  if (idx === -1) return null;
+  return { head: html.slice(0, idx), tail: html.slice(idx) };
+}
+function buildIncrementalSnapshotChunk(state, options) {
+  const json = JSON.stringify(state);
+  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>`;
+  }
+  return `<script type="application/json" data-fict-snapshot>${json}</script>`;
+}
 function serializeOutput(document, container, options) {
   if (options.fullDocument) {
     const doctype = serializeDoctype(document, options.doctype);
@@ -225,12 +692,39 @@ function restoreGlobals(snapshot) {
     }
   }
 }
+function readTextFileFromPath(path) {
+  const g = globalThis;
+  const deno = g.Deno;
+  if (deno && typeof deno.readTextFileSync === "function") {
+    return deno.readTextFileSync(path);
+  }
+  const nodeRequire = getNodeRequire();
+  if (nodeRequire) {
+    const fs = nodeRequire("node:fs");
+    return fs.readFileSync(path, "utf8");
+  }
+  throw new Error(
+    "[fict/ssr] `manifest` as file path is only supported in Node.js or Deno. Pass a manifest object in edge runtimes."
+  );
+}
+function getNodeRequire() {
+  const g = globalThis;
+  const direct = g.require;
+  if (typeof direct === "function") {
+    return direct;
+  }
+  try {
+    return Function('return typeof require === "function" ? require : null')();
+  } catch {
+    return null;
+  }
+}
 function installManifest(manifest) {
   if (!manifest) return () => {
   };
   let resolved;
   if (typeof manifest === "string") {
-    const raw = readFileSync(manifest, "utf8");
+    const raw = readTextFileFromPath(manifest);
     resolved = JSON.parse(raw);
   } else {
     resolved = manifest;
@@ -253,6 +747,9 @@ function installManifest(manifest) {
 export {
   createSSRDocument,
   renderToDocument,
+  renderToPartial,
+  renderToPipeableStream,
+  renderToStream,
   renderToString,
   renderToStringAsync
 };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@fictjs/ssr",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Fict server-side rendering",
   "publishConfig": {
     "access": "public",
@@ -27,7 +27,7 @@
   ],
   "dependencies": {
     "linkedom": "^0.18.12",
-    "@fictjs/runtime": "0.5.1"
+    "@fictjs/runtime": "0.5.2"
   },
   "devDependencies": {
     "tsup": "^8.5.1"
@@ -45,6 +45,7 @@
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
+    "test:edge": "node test/edge-runtime.smoke.mjs",
     "test:coverage": "vitest run --coverage",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",