@fictjs/ssr 0.20.0 → 0.22.0

package/dist/experimental.d.cts

@@ -0,0 +1,164 @@
+import { FictNode } from '@fictjs/runtime';
+
+interface SSRDom {
+    window: Window;
+    document: Document;
+}
+interface RenderToStringOptions {
+    /**
+     * Provide a pre-created DOM (document + window). If omitted, a new DOM is
+     * created per render using `html`.
+     */
+    dom?: SSRDom;
+    /**
+     * Provide a document directly. If `window` is omitted, `document.defaultView`
+     * will be used when available.
+     */
+    document?: Document;
+    /**
+     * Provide a window directly. If `document` is omitted, `window.document` is used.
+     */
+    window?: Window;
+    /**
+     * HTML template used when creating a new DOM.
+     */
+    html?: string;
+    /**
+     * Provide a container element to render into.
+     */
+    container?: HTMLElement;
+    /**
+     * Tag name for the auto-created container.
+     */
+    containerTag?: string;
+    /**
+     * id applied to the auto-created container.
+     */
+    containerId?: string;
+    /**
+     * Additional attributes applied to the auto-created container.
+     */
+    containerAttributes?: Record<string, string | number | boolean | null | undefined>;
+    /**
+     * Return the container element including its outer tag.
+     */
+    includeContainer?: boolean;
+    /**
+     * Return a full HTML document string (doctype + documentElement.outerHTML).
+     */
+    fullDocument?: boolean;
+    /**
+     * Override doctype when `fullDocument` is true. Use `null` to omit.
+     */
+    doctype?: string | null;
+    /**
+     * Expose DOM globals (window/document/Node/Element/etc) during render.
+     * Defaults to false. Set to true only for compatibility with components
+     * that still read process-global DOM objects during server rendering.
+     */
+    exposeGlobals?: boolean;
+    /**
+     * Manifest mapping module URLs to built client chunk URLs.
+     * Can be an object or a path to a JSON file.
+     * File path mode requires Deno sync filesystem access or a CommonJS
+     * environment where `require('node:fs')` is available. Pass an object when
+     * rendering from Node ESM or edge runtimes.
+     */
+    manifest?: Record<string, string> | string;
+    /**
+     * Include the SSR snapshot script for resumability.
+     * Defaults to true.
+     */
+    includeSnapshot?: boolean;
+    /**
+     * Script element id for the snapshot.
+     */
+    snapshotScriptId?: string;
+    /**
+     * Where to append the snapshot script when not returning full document.
+     * Defaults to 'container'.
+     */
+    snapshotTarget?: 'container' | 'body' | 'head';
+    /**
+     * Nonce applied to generated <script> tags for CSP compatibility.
+     */
+    scriptNonce?: string;
+}
+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;
+    /**
+     * How to load the streaming patch runtime.
+     * Defaults to 'inline'. Use 'external' with streamRuntimeSrc for strict CSP.
+     */
+    streamRuntime?: 'inline' | 'external';
+    /**
+     * External streaming patch runtime URL when streamRuntime is 'external'.
+     */
+    streamRuntimeSrc?: string;
+    /**
+     * How resolved Suspense patch chunks are applied.
+     * Defaults to 'inline' for inline runtimes and 'observer' for external runtimes.
+     */
+    streamPatchMode?: 'inline' | 'observer';
+}
+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).
+     *
+     * @experimental Preview API for v1.0; the access pattern may change before
+     * this becomes stable.
+     */
+    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;
+    dispose: () => void;
+}
+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;
+/**
+ * @experimental Preview API for v1.0; the return shape may change before this
+ * becomes stable.
+ */
+declare function renderToPartial(view: () => FictNode, options?: RenderToStreamOptions): PartialPrerenderResult;
+
+export { type PipeableStream as P, type PartialPrerenderResult, type RenderToStringOptions as R, type SSRDom as S, renderToString as a, renderToStringAsync as b, createSSRDocument as c, renderToStream as d, renderToPipeableStream as e, type RenderToStreamOptions as f, type RenderToDocumentResult as g, renderToDocument as r, renderToPartial };

package/dist/experimental.d.ts

@@ -0,0 +1,164 @@
+import { FictNode } from '@fictjs/runtime';
+
+interface SSRDom {
+    window: Window;
+    document: Document;
+}
+interface RenderToStringOptions {
+    /**
+     * Provide a pre-created DOM (document + window). If omitted, a new DOM is
+     * created per render using `html`.
+     */
+    dom?: SSRDom;
+    /**
+     * Provide a document directly. If `window` is omitted, `document.defaultView`
+     * will be used when available.
+     */
+    document?: Document;
+    /**
+     * Provide a window directly. If `document` is omitted, `window.document` is used.
+     */
+    window?: Window;
+    /**
+     * HTML template used when creating a new DOM.
+     */
+    html?: string;
+    /**
+     * Provide a container element to render into.
+     */
+    container?: HTMLElement;
+    /**
+     * Tag name for the auto-created container.
+     */
+    containerTag?: string;
+    /**
+     * id applied to the auto-created container.
+     */
+    containerId?: string;
+    /**
+     * Additional attributes applied to the auto-created container.
+     */
+    containerAttributes?: Record<string, string | number | boolean | null | undefined>;
+    /**
+     * Return the container element including its outer tag.
+     */
+    includeContainer?: boolean;
+    /**
+     * Return a full HTML document string (doctype + documentElement.outerHTML).
+     */
+    fullDocument?: boolean;
+    /**
+     * Override doctype when `fullDocument` is true. Use `null` to omit.
+     */
+    doctype?: string | null;
+    /**
+     * Expose DOM globals (window/document/Node/Element/etc) during render.
+     * Defaults to false. Set to true only for compatibility with components
+     * that still read process-global DOM objects during server rendering.
+     */
+    exposeGlobals?: boolean;
+    /**
+     * Manifest mapping module URLs to built client chunk URLs.
+     * Can be an object or a path to a JSON file.
+     * File path mode requires Deno sync filesystem access or a CommonJS
+     * environment where `require('node:fs')` is available. Pass an object when
+     * rendering from Node ESM or edge runtimes.
+     */
+    manifest?: Record<string, string> | string;
+    /**
+     * Include the SSR snapshot script for resumability.
+     * Defaults to true.
+     */
+    includeSnapshot?: boolean;
+    /**
+     * Script element id for the snapshot.
+     */
+    snapshotScriptId?: string;
+    /**
+     * Where to append the snapshot script when not returning full document.
+     * Defaults to 'container'.
+     */
+    snapshotTarget?: 'container' | 'body' | 'head';
+    /**
+     * Nonce applied to generated <script> tags for CSP compatibility.
+     */
+    scriptNonce?: string;
+}
+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;
+    /**
+     * How to load the streaming patch runtime.
+     * Defaults to 'inline'. Use 'external' with streamRuntimeSrc for strict CSP.
+     */
+    streamRuntime?: 'inline' | 'external';
+    /**
+     * External streaming patch runtime URL when streamRuntime is 'external'.
+     */
+    streamRuntimeSrc?: string;
+    /**
+     * How resolved Suspense patch chunks are applied.
+     * Defaults to 'inline' for inline runtimes and 'observer' for external runtimes.
+     */
+    streamPatchMode?: 'inline' | 'observer';
+}
+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).
+     *
+     * @experimental Preview API for v1.0; the access pattern may change before
+     * this becomes stable.
+     */
+    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;
+    dispose: () => void;
+}
+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;
+/**
+ * @experimental Preview API for v1.0; the return shape may change before this
+ * becomes stable.
+ */
+declare function renderToPartial(view: () => FictNode, options?: RenderToStreamOptions): PartialPrerenderResult;
+
+export { type PipeableStream as P, type PartialPrerenderResult, type RenderToStringOptions as R, type SSRDom as S, renderToString as a, renderToStringAsync as b, createSSRDocument as c, renderToStream as d, renderToPipeableStream as e, type RenderToStreamOptions as f, type RenderToDocumentResult as g, renderToDocument as r, renderToPartial };

package/dist/experimental.js

@@ -0,0 +1,7 @@
+import {
+  renderToPartial
+} from "./chunk-LW7ALN63.js";
+import "./chunk-DI4PFT6R.js";
+export {
+  renderToPartial
+};