@fictjs/ssr 0.4.0 → 0.5.0

package/README.md

@@ -0,0 +1,619 @@
+# @fictjs/ssr
+
+Fict's Server-Side Rendering (SSR) package, providing high-performance server-side rendering and client-side resumability capabilities.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [API Reference](#api-reference)
+- [Architecture Design](#architecture-design)
+- [Integration with Vite](#integration-with-vite)
+- [Advanced Usage](#advanced-usage)
+- [Performance Optimization](#performance-optimization)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+Fict SSR adopts a **Resumability** architecture, which is fundamentally different from traditional Hydration:
+
+| Feature                   | Traditional Hydration             | Fict Resumability                 |
+| ------------------------- | --------------------------------- | --------------------------------- |
+| Client JS Execution       | Re-executes entire component tree | Only executes on interaction      |
+| Time to Interactive (TTI) | High (waits for hydration)        | Low (Zero JS execution)           |
+| Handler Loading           | All preloaded                     | Lazy loaded on demand             |
+| State Restoration         | Re-calculated                     | Restored from serialized snapshot |
+
+### How it Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Server-Side Rendering                      │
+├─────────────────────────────────────────────────────────────────┤
+│  1. Execute component code                                      │
+│  2. Generate HTML + Serialize state snapshot                    │
+│  3. Inject QRL (Qualified Resource Locator) references          │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Client-Side Resumability                   │
+├─────────────────────────────────────────────────────────────────┤
+│  1. Parse snapshot, store in memory                             │
+│  2. Install event delegation listeners                          │
+│  3. On user interaction:                                        │
+│     a. Lazy load handler chunk                                  │
+│     b. Restore component state (from snapshot)                  │
+│     c. Establish reactive bindings                              │
+│     d. Execute handler                                          │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+pnpm add @fictjs/ssr
+```
+
+## Quick Start
+
+### Basic SSR
+
+```typescript
+import { renderToString } from '@fictjs/ssr'
+import { App } from './App'
+
+// Server-side
+const html = renderToString(() => <App />)
+```
+
+### SSR with Resumability
+
+```typescript
+import { renderToString } from '@fictjs/ssr'
+import { App } from './App'
+
+const html = renderToString(() => <App />, {
+  includeSnapshot: true,  // Include state snapshot (default true)
+  containerId: 'app',
+  manifest: './dist/client/fict.manifest.json',
+})
+```
+
+### Client-Side Resumability
+
+```typescript
+// entry-client.tsx
+import { installResumableLoader } from '@fictjs/runtime/loader'
+
+// Load manifest (production)
+async function loadManifest() {
+  const res = await fetch('/fict.manifest.json')
+  if (res.ok) {
+    globalThis.__FICT_MANIFEST__ = await res.json()
+  }
+}
+
+async function init() {
+  await loadManifest()
+
+  installResumableLoader({
+    events: ['click', 'input', 'change', 'submit'],
+    prefetch: {
+      visibility: true,
+      visibilityMargin: '200px',
+      hover: true,
+      hoverDelay: 50,
+    },
+  })
+}
+
+init()
+```
+
+## Core Concepts
+
+### 1. QRL (Qualified Resource Locator)
+
+QRL is the URL format Fict uses for lazy loading handlers:
+
+```
+virtual:fict-handler:/path/to/file.tsx$$__fict_e0#default
+│                     │                  │         │
+│                     │                  │         └─ Export Name
+│                     │                  └─ Handler ID
+│                     └─ Source File Path
+└─ Virtual Module Prefix
+```
+
+**Representation in HTML:**
+
+```html
+<button on:click="virtual:fict-handler:/src/App.tsx$$__fict_e0#default">Click me</button>
+```
+
+### 2. State Snapshot
+
+During server-side rendering, component state is serialized into JSON and injected into HTML:
+
+```html
+<script id="__FICT_SNAPSHOT__" type="application/json">
+  {
+    "scopes": {
+      "s1": {
+        "id": "s1",
+        "slots": [
+          [0, "sig", 10],      // Index 0: signal, value 10
+          [1, "store", {...}], // Index 1: store
+          [2, "raw", null]     // Index 2: raw value
+        ],
+        "vars": { "count": 0 }
+      }
+    }
+  }
+</script>
+```
+
+**Supported Serialization Types:**
+
+| Type      | Tag                       | Description                |
+| --------- | ------------------------- | -------------------------- |
+| Date      | `__t: 'd'`                | Stored as timestamp        |
+| Map       | `__t: 'm'`                | Stored as entries array    |
+| Set       | `__t: 's'`                | Stored as array            |
+| RegExp    | `__t: 'r'`                | Stored as source + flags   |
+| undefined | `__t: 'u'`                | Special tag                |
+| NaN       | `__t: 'n'`                | Special tag                |
+| Infinity  | `__t: '+i'` / `__t: '-i'` | Positive/Negative Infinity |
+| BigInt    | `__t: 'b'`                | Stored as string           |
+
+### 3. Scope Registration
+
+Each resumable component instance has a unique scope ID:
+
+```html
+<fict-host
+  data-fict-s="s1"                                    <!-- scope ID -->
+  data-fict-h="/assets/index.js#__fict_r0"            <!-- resume handler -->
+  data-fict-t="Counter@file:///src/App.tsx"           <!-- Component Type -->
+>
+  ...
+</fict-host>
+```
+
+### 4. Automatic Handler Extraction
+
+The Fict compiler supports two ways to extract handlers:
+
+**Explicit Extraction (using `$` suffix):**
+
+```tsx
+<button onClick$={() => count++}>  // Always extracted
+```
+
+**Automatic Extraction (enable `autoExtractHandlers`):**
+
+```tsx
+<button onClick={() => count++}>       // Simple, might not extract
+<button onClick={() => fetchData()}>   // Complex, auto-extracted
+<button onClick={handleSubmit}>        // External reference, auto-extracted
+```
+
+**Heuristic Rules for Auto-Extraction:**
+
+| Condition                   | Extracted? |
+| --------------------------- | ---------- |
+| External function reference | ✅         |
+| Contains external calls     | ✅         |
+| Contains async/await        | ✅         |
+| AST node count ≥ threshold  | ✅         |
+| Simple expression           | ❌         |
+
+## API Reference
+
+### renderToString
+
+```typescript
+function renderToString(view: () => FictNode, options?: RenderToStringOptions): string
+```
+
+**Options:**
+
+```typescript
+interface RenderToStringOptions {
+  // DOM Configuration
+  dom?: SSRDom
+  document?: Document
+  window?: Window
+  html?: string
+
+  // Container Configuration
+  container?: HTMLElement
+  containerTag?: string // Default: 'div'
+  containerId?: string
+  containerAttributes?: Record<string, string | number | boolean>
+
+  // Output Configuration
+  includeContainer?: boolean // Include container tag
+  fullDocument?: boolean // Output full HTML document
+  doctype?: string | null
+
+  // Resumability Configuration
+  includeSnapshot?: boolean // Default: true
+  snapshotScriptId?: string // Default: '__FICT_SNAPSHOT__'
+  snapshotTarget?: 'container' | 'body' | 'head'
+
+  // Runtime Configuration
+  exposeGlobals?: boolean // Default: true
+  manifest?: Record<string, string> | string
+}
+```
+
+### renderToDocument
+
+```typescript
+function renderToDocument(
+  view: () => FictNode,
+  options?: RenderToStringOptions,
+): RenderToDocumentResult
+
+interface RenderToDocumentResult extends SSRDom {
+  html: string
+  container: HTMLElement
+  dispose: () => void
+}
+```
+
+Returns a DOM object for further manipulation or streaming rendering.
+
+### createSSRDocument
+
+```typescript
+function createSSRDocument(html?: string): SSRDom
+
+interface SSRDom {
+  window: Window
+  document: Document
+}
+```
+
+Creates a virtual DOM environment for SSR.
+
+### installResumableLoader
+
+```typescript
+function installResumableLoader(options?: ResumableLoaderOptions): void
+
+interface ResumableLoaderOptions {
+  document?: Document
+  snapshotScriptId?: string
+  events?: string[] // Default: DelegatedEvents
+  prefetch?: PrefetchStrategy | false
+}
+
+interface PrefetchStrategy {
+  visibility?: boolean // Default: true
+  visibilityMargin?: string // Default: '200px'
+  hover?: boolean // Default: true
+  hoverDelay?: number // Default: 50
+}
+```
+
+## Architecture Design
+
+### Build Time
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        Fict Compiler                         │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  Source Code                 Build Output                    │
+│  ───────────                 ────────────                    │
+│  onClick$={() => count++}    1. Main bundle (incl resume fn) │
+│                              2. Handler chunk (lazy loaded)  │
+│                              3. QRL Ref (HTML attribute)     │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Generated Code Structure:**
+
+```javascript
+// Main bundle
+const __fict_r0 = (scopeId, host) => {
+  // Resume Function: Restore state + Bind reactivity
+  const scope = __fictGetSSRScope(scopeId)
+  let count = __fictRestoreSignal(scope, 0)
+
+  $effect(() => {
+    /* Bind DOM update */
+  })
+}
+
+__fictRegisterResume('__fict_r0', __fict_r0)
+
+// Handler chunk (separate file)
+export default (scopeId, event, el) => {
+  const [count] = __fictUseLexicalScope(scopeId, ['count'])
+  count++ // Trigger signal update
+}
+```
+
+### Runtime
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Resumable Loader                            │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Parse snapshot ──────────► Store in snapshotState           │
+│                                                                 │
+│  2. Register event delegation ──────► doc.addEventListener      │
+│                                                                 │
+│  3. On Event Trigger:                                           │
+│     ┌─────────────────────────────────────────────────────┐     │
+│     │ a. Look up on:* attribute to get QRL                │     │
+│     │ b. Check if hydrated                                │     │
+│     │ c. If not hydrated:                                 │     │
+│     │    - Load resume module                             │     │
+│     │    - Get resume fn from registry                    │     │
+│     │    - Execute resume (restore state + bind)          │     │
+│     │ d. Load handler chunk                               │     │
+│     │ e. Execute handler                                  │     │
+│     └─────────────────────────────────────────────────────┘     │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Manifest File
+
+Generated detailed `fict.manifest.json` during production build, mapping virtual modules to actual chunks:
+
+```json
+{
+  "virtual:fict-handler:/src/App.tsx$$__fict_e0": "/assets/handler-e0-abc123.js",
+  "virtual:fict-handler:/src/App.tsx$$__fict_e1": "/assets/handler-e1-def456.js",
+  "file:///src/App.tsx": "/assets/index-xyz789.js"
+}
+```
+
+## Integration with Vite
+
+### vite.config.ts
+
+```typescript
+import { defineConfig } from 'vite'
+import fict from '@fictjs/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    fict({
+      resumable: true,
+      autoExtractHandlers: true,
+      autoExtractThreshold: 3,
+    }),
+  ],
+})
+```
+
+### Configuration Options
+
+```typescript
+interface FictPluginOptions {
+  // Resumability
+  resumable?: boolean // Enable resumable mode
+  autoExtractHandlers?: boolean // Auto extract handlers
+  autoExtractThreshold?: number // Auto extract threshold (default: 3)
+
+  // Build Options
+  fineGrainedDom?: boolean // Fine-grained DOM updates
+  optimize?: boolean // HIR Optimization
+  // ...
+}
+```
+
+### Build Output
+
+```
+dist/
+├── client/
+│   ├── index.html
+│   ├── fict.manifest.json
+│   └── assets/
+│       ├── index-abc123.js          # Main bundle
+│       ├── chunk-xyz789.js          # Shared chunk (runtime)
+│       ├── handler-__fict_e0-*.js   # Handler chunk
+│       ├── handler-__fict_e1-*.js
+│       └── handler-__fict_e2-*.js
+└── server/
+    └── entry-server.js              # SSR bundle
+```
+
+## Advanced Usage
+
+### Custom SSR Server
+
+```typescript
+// server.js
+import express from 'express'
+import { renderToString } from '@fictjs/ssr'
+import { App } from './dist/server/entry-server.js'
+
+const app = express()
+
+// Static assets
+app.use('/assets', express.static('dist/client/assets'))
+
+// SSR Route
+app.get('*', async (req, res) => {
+  const manifest = JSON.parse(
+    fs.readFileSync('dist/client/fict.manifest.json', 'utf-8')
+  )
+
+  const appHtml = renderToString(() => <App url={req.url} />, {
+    manifest,
+    containerId: 'app',
+  })
+
+  const html = template.replace('<!--app-html-->', appHtml)
+  res.send(html)
+})
+```
+
+### Streaming Rendering (Experimental)
+
+```typescript
+import { renderToDocument } from '@fictjs/ssr'
+
+app.get('*', async (req, res) => {
+  const result = renderToDocument(() => <App />, {
+    includeSnapshot: true,
+  })
+
+  // Can send in chunks
+  res.write('<!DOCTYPE html><html><head>...</head><body>')
+  res.write(result.html)
+  res.write('</body></html>')
+  res.end()
+
+  result.dispose()
+})
+```
+
+### Prefetch Strategy
+
+```typescript
+installResumableLoader({
+  prefetch: {
+    // Prefetch when element enters viewport
+    visibility: true,
+    visibilityMargin: '500px', // Start prefetch 500px early
+
+    // Prefetch on hover
+    hover: true,
+    hoverDelay: 100, // 100ms debounce
+  },
+})
+```
+
+### Disable Extraction for Specific Handlers
+
+```tsx
+// Use normal onClick and set autoExtractHandlers: false
+// Or ensure handler is simple enough not to trigger auto-extraction
+
+<button onClick={() => count++}>  // Simple, not extracted
+```
+
+## Performance Optimization
+
+### 1. Handler Chunk Size Optimization
+
+```typescript
+// ❌ Not Recommended: Large dependency in handler
+<button onClick$={async () => {
+  const { parse } = await import('large-library')
+  parse(data)
+}}>
+
+// ✅ Recommended: Import at component level
+import { parse } from 'large-library'
+<button onClick$={() => parse(data)}>
+```
+
+### 2. Prefetch Tuning
+
+```typescript
+// For critical interactions, use more aggressive preloading
+installResumableLoader({
+  prefetch: {
+    visibility: true,
+    visibilityMargin: '1000px', // Prefetch even earlier
+  },
+})
+```
+
+### 3. Reduce Serialization Overhead
+
+```tsx
+// ❌ Avoid serializing large objects
+let largeData = $state(hugeArray)
+
+// ✅ Recommended: Serialize only necessary data
+let dataId = $state(id) // Store ID only, fetch on client
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. "Failed to fetch dynamically imported module"
+
+**Cause:** Manifest not loaded correctly or QRL path mismatch.
+
+**Solution:**
+
+```typescript
+// Ensure manifest is loaded before installResumableLoader
+await loadManifest()
+installResumableLoader(...)
+```
+
+#### 2. Handler called but DOM not updating
+
+**Cause:** Resume function not executed or not correctly registered.
+
+**Check:**
+
+```typescript
+// Ensure resume function is registered
+import { __fictGetResume } from '@fictjs/runtime/internal'
+console.log(__fictGetResume('__fict_r0')) // Should return function
+```
+
+#### 3. "ReferenceError: xxx is not defined"
+
+**Cause:** Handler chunk references uncaptured variable.
+
+**Solution:** Ensure all required variables are in closure scope.
+
+#### 4. Snapshot too large
+
+**Cause:** Serializing large amount of data.
+
+**Solution:**
+
+```typescript
+// Use lazy initialization
+let data = $state(null) // Initial null
+onMount(async () => {
+  data = await fetchData() // Fetch on client
+})
+```
+
+### Debugging Tips
+
+```typescript
+// Enable loader logs (during dev)
+// Console.log statements in loader.ts can help debug
+
+// Check manifest content
+console.log(globalThis.__FICT_MANIFEST__)
+
+// Check snapshot content
+const snapshot = document.getElementById('__FICT_SNAPSHOT__')
+console.log(JSON.parse(snapshot.textContent))
+```
+
+## Related Packages
+
+- `@fictjs/runtime` - Core runtime, containing signal/effect system
+- `@fictjs/compiler` - Babel plugin, handling JSX transform and handler extraction
+- `@fictjs/vite-plugin` - Vite integration, handling build and code splitting
+
+## License
+
+MIT

package/dist/index.cjs

@@ -1 +1,282 @@
 "use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createSSRDocument: () => createSSRDocument,
+  renderToDocument: () => renderToDocument,
+  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");
+var DEFAULT_HTML = "<!doctype html><html><head></head><body></body></html>";
+function createSSRDocument(html = DEFAULT_HTML) {
+  const window = (0, import_linkedom.parseHTML)(html);
+  const document = window.document;
+  if (!window || !document) {
+    throw new Error("[fict/ssr] Failed to create DOM. Missing window or document.");
+  }
+  return { window, document };
+}
+function renderToDocument(view, options = {}) {
+  const includeSnapshot = options.includeSnapshot !== false;
+  (0, import_internal.__fictEnableSSR)();
+  let dom;
+  let restoreGlobals2 = () => {
+  };
+  let restoreManifest = () => {
+  };
+  let container;
+  let teardown = () => {
+  };
+  try {
+    dom = resolveDom(options);
+    const { document, window } = dom;
+    const shouldExpose = options.exposeGlobals !== false;
+    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)();
+      injectSnapshot(document, container, state, options);
+    }
+  } catch (error) {
+    (0, import_internal.__fictDisableSSR)();
+    restoreGlobals2();
+    restoreManifest();
+    throw error;
+  }
+  (0, import_internal.__fictDisableSSR)();
+  const html = serializeOutput(dom.document, container, options);
+  const dispose = () => {
+    try {
+      teardown();
+    } finally {
+      restoreGlobals2();
+      restoreManifest();
+    }
+  };
+  return { html, document: dom.document, window: dom.window, container, dispose };
+}
+function renderToString(view, options = {}) {
+  const result = renderToDocument(view, options);
+  const html = result.html;
+  result.dispose();
+  return html;
+}
+async function renderToStringAsync(view, options = {}) {
+  return renderToString(view, options);
+}
+function resolveDom(options) {
+  if (options.dom) {
+    return options.dom;
+  }
+  if (options.document && options.window) {
+    return { document: options.document, window: options.window };
+  }
+  if (options.document) {
+    const window = options.window ?? options.document.defaultView ?? options.document.defaultView ?? void 0;
+    if (!window) {
+      throw new Error(
+        "[fict/ssr] A window is required when providing a document without defaultView."
+      );
+    }
+    return { document: options.document, window };
+  }
+  if (options.window) {
+    return { document: options.window.document, window: options.window };
+  }
+  return createSSRDocument(options.html);
+}
+function resolveContainer(document, options) {
+  if (options.container) {
+    if (options.container.ownerDocument && options.container.ownerDocument !== document) {
+      throw new Error("[fict/ssr] Provided container belongs to a different document.");
+    }
+    return options.container;
+  }
+  const tag = options.containerTag ?? "div";
+  const container = document.createElement(tag);
+  if (options.containerId) {
+    container.setAttribute("id", options.containerId);
+  }
+  if (options.containerAttributes) {
+    for (const [name, value] of Object.entries(options.containerAttributes)) {
+      if (value === null || value === void 0 || value === false) continue;
+      container.setAttribute(name, value === true ? "" : String(value));
+    }
+  }
+  if (document.body) {
+    document.body.appendChild(container);
+  }
+  return container;
+}
+function serializeOutput(document, container, options) {
+  if (options.fullDocument) {
+    const doctype = serializeDoctype(document, options.doctype);
+    const html = document.documentElement ? document.documentElement.outerHTML : container.outerHTML;
+    return doctype ? `${doctype}${html}` : html;
+  }
+  if (options.includeContainer) {
+    return container.outerHTML;
+  }
+  return container.innerHTML;
+}
+function injectSnapshot(document, container, state, options) {
+  const script = document.createElement("script");
+  script.type = "application/json";
+  script.id = options.snapshotScriptId ?? "__FICT_SNAPSHOT__";
+  script.textContent = JSON.stringify(state);
+  if (options.fullDocument) {
+    if (options.snapshotTarget === "head" && document.head) {
+      document.head.appendChild(script);
+      return;
+    }
+    if (document.body) {
+      document.body.appendChild(script);
+      return;
+    }
+  }
+  const target = options.snapshotTarget ?? "container";
+  if (target === "body" && document.body) {
+    document.body.appendChild(script);
+    return;
+  }
+  if (target === "head" && document.head) {
+    document.head.appendChild(script);
+    return;
+  }
+  container.appendChild(script);
+}
+function serializeDoctype(document, override) {
+  if (override === null) return "";
+  if (override !== void 0) return override;
+  const doctype = document.doctype;
+  if (!doctype) return "";
+  const name = doctype.name || "html";
+  const publicId = doctype.publicId;
+  const systemId = doctype.systemId;
+  let id = "";
+  if (publicId) {
+    id = ` PUBLIC "${publicId}"`;
+    if (systemId) {
+      id += ` "${systemId}"`;
+    }
+  } else if (systemId) {
+    id = ` SYSTEM "${systemId}"`;
+  }
+  return `<!DOCTYPE ${name}${id}>`;
+}
+function installGlobals(window, document) {
+  const win = window;
+  const required = {
+    window: win,
+    document,
+    self: win,
+    Node: win.Node,
+    Element: win.Element,
+    HTMLElement: win.HTMLElement,
+    SVGElement: win.SVGElement,
+    Document: win.Document,
+    DocumentFragment: win.DocumentFragment,
+    Text: win.Text,
+    Comment: win.Comment
+  };
+  const optional = {
+    Range: win.Range,
+    Event: win.Event,
+    CustomEvent: win.CustomEvent,
+    MutationObserver: win.MutationObserver,
+    DOMParser: win.DOMParser,
+    getComputedStyle: win.getComputedStyle?.bind(win)
+  };
+  const missing = Object.entries(required).filter(([, value]) => value === void 0).map(([key]) => key);
+  if (missing.length) {
+    throw new Error(`[fict/ssr] Missing DOM globals: ${missing.join(", ")}`);
+  }
+  const globals = { ...required, ...optional };
+  const keys = Object.keys(globals);
+  const snapshot = captureGlobals(keys);
+  for (const key of keys) {
+    const value = globals[key];
+    if (value !== void 0) {
+      ;
+      globalThis[key] = value;
+    }
+  }
+  return () => restoreGlobals(snapshot);
+}
+function captureGlobals(keys) {
+  const snapshot = [];
+  for (const key of keys) {
+    const exists = Object.prototype.hasOwnProperty.call(globalThis, key);
+    const value = globalThis[key];
+    snapshot.push({ key, exists, value });
+  }
+  return snapshot;
+}
+function restoreGlobals(snapshot) {
+  for (const entry of snapshot) {
+    if (entry.exists) {
+      ;
+      globalThis[entry.key] = entry.value;
+    } else {
+      delete globalThis[entry.key];
+    }
+  }
+}
+function installManifest(manifest) {
+  if (!manifest) return () => {
+  };
+  let resolved;
+  if (typeof manifest === "string") {
+    const raw = (0, import_node_fs.readFileSync)(manifest, "utf8");
+    resolved = JSON.parse(raw);
+  } else {
+    resolved = manifest;
+  }
+  const key = "__FICT_MANIFEST__";
+  const snapshot = {
+    exists: Object.prototype.hasOwnProperty.call(globalThis, key),
+    value: globalThis[key]
+  };
+  globalThis[key] = resolved;
+  return () => {
+    if (snapshot.exists) {
+      ;
+      globalThis[key] = snapshot.value;
+    } else {
+      delete globalThis[key];
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSSRDocument,
+  renderToDocument,
+  renderToString,
+  renderToStringAsync
+});

package/dist/index.d.cts

@@ -1,2 +1,89 @@
+import { FictNode } from '@fictjs/runtime';
 
-export {  }
+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 true.
+     */
+    exposeGlobals?: boolean;
+    /**
+     * Manifest mapping module URLs to built client chunk URLs.
+     * Can be an object or a path to a JSON file.
+     */
+    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';
+}
+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>;
+
+export { type RenderToDocumentResult, type RenderToStringOptions, type SSRDom, createSSRDocument, renderToDocument, renderToString, renderToStringAsync };

package/dist/index.d.ts

@@ -1,2 +1,89 @@
+import { FictNode } from '@fictjs/runtime';
 
-export {  }
+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 true.
+     */
+    exposeGlobals?: boolean;
+    /**
+     * Manifest mapping module URLs to built client chunk URLs.
+     * Can be an object or a path to a JSON file.
+     */
+    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';
+}
+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>;
+
+export { type RenderToDocumentResult, type RenderToStringOptions, type SSRDom, createSSRDocument, renderToDocument, renderToString, renderToStringAsync };

package/dist/index.js

@@ -0,0 +1,258 @@
+// src/index.ts
+import { readFileSync } from "fs";
+import { render } from "@fictjs/runtime";
+import {
+  __fictDisableSSR,
+  __fictEnableSSR,
+  __fictSerializeSSRState
+} from "@fictjs/runtime/internal";
+import { parseHTML } from "linkedom";
+var DEFAULT_HTML = "<!doctype html><html><head></head><body></body></html>";
+function createSSRDocument(html = DEFAULT_HTML) {
+  const window = parseHTML(html);
+  const document = window.document;
+  if (!window || !document) {
+    throw new Error("[fict/ssr] Failed to create DOM. Missing window or document.");
+  }
+  return { window, document };
+}
+function renderToDocument(view, options = {}) {
+  const includeSnapshot = options.includeSnapshot !== false;
+  __fictEnableSSR();
+  let dom;
+  let restoreGlobals2 = () => {
+  };
+  let restoreManifest = () => {
+  };
+  let container;
+  let teardown = () => {
+  };
+  try {
+    dom = resolveDom(options);
+    const { document, window } = dom;
+    const shouldExpose = options.exposeGlobals !== false;
+    restoreGlobals2 = shouldExpose ? installGlobals(window, document) : () => {
+    };
+    restoreManifest = installManifest(options.manifest);
+    container = resolveContainer(document, options);
+    teardown = render(view, container);
+    if (includeSnapshot) {
+      const state = __fictSerializeSSRState();
+      injectSnapshot(document, container, state, options);
+    }
+  } catch (error) {
+    __fictDisableSSR();
+    restoreGlobals2();
+    restoreManifest();
+    throw error;
+  }
+  __fictDisableSSR();
+  const html = serializeOutput(dom.document, container, options);
+  const dispose = () => {
+    try {
+      teardown();
+    } finally {
+      restoreGlobals2();
+      restoreManifest();
+    }
+  };
+  return { html, document: dom.document, window: dom.window, container, dispose };
+}
+function renderToString(view, options = {}) {
+  const result = renderToDocument(view, options);
+  const html = result.html;
+  result.dispose();
+  return html;
+}
+async function renderToStringAsync(view, options = {}) {
+  return renderToString(view, options);
+}
+function resolveDom(options) {
+  if (options.dom) {
+    return options.dom;
+  }
+  if (options.document && options.window) {
+    return { document: options.document, window: options.window };
+  }
+  if (options.document) {
+    const window = options.window ?? options.document.defaultView ?? options.document.defaultView ?? void 0;
+    if (!window) {
+      throw new Error(
+        "[fict/ssr] A window is required when providing a document without defaultView."
+      );
+    }
+    return { document: options.document, window };
+  }
+  if (options.window) {
+    return { document: options.window.document, window: options.window };
+  }
+  return createSSRDocument(options.html);
+}
+function resolveContainer(document, options) {
+  if (options.container) {
+    if (options.container.ownerDocument && options.container.ownerDocument !== document) {
+      throw new Error("[fict/ssr] Provided container belongs to a different document.");
+    }
+    return options.container;
+  }
+  const tag = options.containerTag ?? "div";
+  const container = document.createElement(tag);
+  if (options.containerId) {
+    container.setAttribute("id", options.containerId);
+  }
+  if (options.containerAttributes) {
+    for (const [name, value] of Object.entries(options.containerAttributes)) {
+      if (value === null || value === void 0 || value === false) continue;
+      container.setAttribute(name, value === true ? "" : String(value));
+    }
+  }
+  if (document.body) {
+    document.body.appendChild(container);
+  }
+  return container;
+}
+function serializeOutput(document, container, options) {
+  if (options.fullDocument) {
+    const doctype = serializeDoctype(document, options.doctype);
+    const html = document.documentElement ? document.documentElement.outerHTML : container.outerHTML;
+    return doctype ? `${doctype}${html}` : html;
+  }
+  if (options.includeContainer) {
+    return container.outerHTML;
+  }
+  return container.innerHTML;
+}
+function injectSnapshot(document, container, state, options) {
+  const script = document.createElement("script");
+  script.type = "application/json";
+  script.id = options.snapshotScriptId ?? "__FICT_SNAPSHOT__";
+  script.textContent = JSON.stringify(state);
+  if (options.fullDocument) {
+    if (options.snapshotTarget === "head" && document.head) {
+      document.head.appendChild(script);
+      return;
+    }
+    if (document.body) {
+      document.body.appendChild(script);
+      return;
+    }
+  }
+  const target = options.snapshotTarget ?? "container";
+  if (target === "body" && document.body) {
+    document.body.appendChild(script);
+    return;
+  }
+  if (target === "head" && document.head) {
+    document.head.appendChild(script);
+    return;
+  }
+  container.appendChild(script);
+}
+function serializeDoctype(document, override) {
+  if (override === null) return "";
+  if (override !== void 0) return override;
+  const doctype = document.doctype;
+  if (!doctype) return "";
+  const name = doctype.name || "html";
+  const publicId = doctype.publicId;
+  const systemId = doctype.systemId;
+  let id = "";
+  if (publicId) {
+    id = ` PUBLIC "${publicId}"`;
+    if (systemId) {
+      id += ` "${systemId}"`;
+    }
+  } else if (systemId) {
+    id = ` SYSTEM "${systemId}"`;
+  }
+  return `<!DOCTYPE ${name}${id}>`;
+}
+function installGlobals(window, document) {
+  const win = window;
+  const required = {
+    window: win,
+    document,
+    self: win,
+    Node: win.Node,
+    Element: win.Element,
+    HTMLElement: win.HTMLElement,
+    SVGElement: win.SVGElement,
+    Document: win.Document,
+    DocumentFragment: win.DocumentFragment,
+    Text: win.Text,
+    Comment: win.Comment
+  };
+  const optional = {
+    Range: win.Range,
+    Event: win.Event,
+    CustomEvent: win.CustomEvent,
+    MutationObserver: win.MutationObserver,
+    DOMParser: win.DOMParser,
+    getComputedStyle: win.getComputedStyle?.bind(win)
+  };
+  const missing = Object.entries(required).filter(([, value]) => value === void 0).map(([key]) => key);
+  if (missing.length) {
+    throw new Error(`[fict/ssr] Missing DOM globals: ${missing.join(", ")}`);
+  }
+  const globals = { ...required, ...optional };
+  const keys = Object.keys(globals);
+  const snapshot = captureGlobals(keys);
+  for (const key of keys) {
+    const value = globals[key];
+    if (value !== void 0) {
+      ;
+      globalThis[key] = value;
+    }
+  }
+  return () => restoreGlobals(snapshot);
+}
+function captureGlobals(keys) {
+  const snapshot = [];
+  for (const key of keys) {
+    const exists = Object.prototype.hasOwnProperty.call(globalThis, key);
+    const value = globalThis[key];
+    snapshot.push({ key, exists, value });
+  }
+  return snapshot;
+}
+function restoreGlobals(snapshot) {
+  for (const entry of snapshot) {
+    if (entry.exists) {
+      ;
+      globalThis[entry.key] = entry.value;
+    } else {
+      delete globalThis[entry.key];
+    }
+  }
+}
+function installManifest(manifest) {
+  if (!manifest) return () => {
+  };
+  let resolved;
+  if (typeof manifest === "string") {
+    const raw = readFileSync(manifest, "utf8");
+    resolved = JSON.parse(raw);
+  } else {
+    resolved = manifest;
+  }
+  const key = "__FICT_MANIFEST__";
+  const snapshot = {
+    exists: Object.prototype.hasOwnProperty.call(globalThis, key),
+    value: globalThis[key]
+  };
+  globalThis[key] = resolved;
+  return () => {
+    if (snapshot.exists) {
+      ;
+      globalThis[key] = snapshot.value;
+    } else {
+      delete globalThis[key];
+    }
+  };
+}
+export {
+  createSSRDocument,
+  renderToDocument,
+  renderToString,
+  renderToStringAsync
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fictjs/ssr",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Fict server-side rendering",
   "publishConfig": {
     "access": "public",
@@ -26,7 +26,8 @@
     "dist"
   ],
   "dependencies": {
-    "@fictjs/runtime": "0.4.0"
+    "linkedom": "^0.18.12",
+    "@fictjs/runtime": "0.5.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1"