@fictjs/ssr 0.26.0 → 0.28.0

package/README.md

@@ -1,6 +1,13 @@
 # @fictjs/ssr
 
-Fict's Server-Side Rendering (SSR) package, providing high-performance server-side rendering and client-side resumability capabilities.
+Fict's Satellite Server-Side Rendering (SSR) package, providing supported
+string and streaming rendering plus opt-in client resumability.
+
+> **Preview** — resumability, snapshot schema v2, and partial prerendering have no
+> semver guarantee and are excluded from Core 1.0. They require
+> `includeSnapshot: true`, compiler `resumable: true`, and the
+> `fict/experimental/loader` entrypoint. Basic string and streaming SSR does not
+> enable them by default.
 
 ## Table of Contents
 
@@ -20,7 +27,9 @@ Fict's Server-Side Rendering (SSR) package, providing high-performance server-si
 
 ## Overview
 
-Fict SSR adopts a **Resumability** architecture, which is fundamentally different from traditional Hydration:
+Supported SSR produces HTML without a resumability snapshot by default. The
+optional **Preview Resumability** architecture is fundamentally different from
+traditional hydration:
 
 | Feature                   | Traditional Hydration             | Fict Resumability                 |
 | ------------------------- | --------------------------------- | --------------------------------- |
@@ -29,7 +38,7 @@ Fict SSR adopts a **Resumability** architecture, which is fundamentally differen
 | Handler Loading           | All preloaded                     | Lazy loaded on demand             |
 | State Restoration         | Re-calculated                     | Restored from serialized snapshot |
 
-### How it Works
+### How Preview Resumability Works
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -79,7 +88,7 @@ import { renderToString } from '@fictjs/ssr'
 import { App } from './App'
 
 const html = renderToString(() => <App />, {
-  includeSnapshot: true,  // Include state snapshot (default true)
+  includeSnapshot: true, // Explicit Preview snapshot opt-in (default false)
   containerId: 'app',
   manifest: './dist/client/fict.manifest.json',
 })
@@ -89,11 +98,15 @@ const html = renderToString(() => <App />, {
 
 ```typescript
 // entry-client.tsx
-import { installResumableLoader } from 'fict/loader'
+import { render } from 'fict'
+import { installResumableLoader } from 'fict/experimental/loader'
+import { App } from './App'
 
 // Load manifest (production)
 async function loadManifest() {
-  const res = await fetch('/fict.manifest.json')
+  // Prefer a build-scoped URL. If the manifest has a fixed name, revalidate it
+  // instead of allowing it to become stale independently from the HTML.
+  const res = await fetch('/fict.manifest.json', { cache: 'no-store' })
   if (res.ok) {
     globalThis.__FICT_MANIFEST__ = await res.json()
   }
@@ -104,6 +117,12 @@ async function init() {
 
   installResumableLoader({
     events: ['click', 'input', 'change', 'submit'],
+    onSnapshotIssue: issue => reportSnapshotIssue(issue),
+    onSnapshotRejected: () => {
+      const root = document.getElementById('app')!
+      root.replaceChildren()
+      render(() => <App />, root)
+    },
     prefetch: {
       visibility: true,
       visibilityMargin: '200px',
@@ -123,18 +142,22 @@ init()
 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:fict-handler:h0123456789abcdef0123456789abcdef$$__fict_e0#default
+│                    │                                  │         │
+│                    │                                  │         └─ Export Name
+│                    │                                  └─ Handler Export
+│                    └─ Opaque Source Identity
 └─ Virtual Module Prefix
 ```
 
+Production identities are checkout-independent and do not contain source paths.
+
 **Representation in HTML:**
 
 ```html
-<button on:click="virtual:fict-handler:/src/App.tsx$$__fict_e0#default">Click me</button>
+<button on:click="virtual:fict-handler:h0123456789abcdef0123456789abcdef$$__fict_e0#default">
+  Click me
+</button>
 ```
 
 ### 2. State Snapshot
@@ -144,10 +167,10 @@ During server-side rendering, component state is serialized into JSON and inject
 ```html
 <script id="__FICT_SNAPSHOT__" type="application/json">
   {
-    "v": 1,
+    "v": 2,
     "scopes": {
-      "s1": {
-        "id": "s1",
+      "account_scope:s1": {
+        "id": "account_scope:s1",
         "slots": [
           [0, "sig", 10],      // Index 0: signal, value 10
           [1, "store", {...}], // Index 1: store
@@ -162,16 +185,25 @@ During server-side rendering, component state is serialized into JSON and inject
 
 **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           |
+| Type / shape                  | Tag                         | Preserved detail                                  |
+| ----------------------------- | --------------------------- | ------------------------------------------------- |
+| Date                          | `__t: 'd'`                  | Timestamp or invalid-date marker                  |
+| Map / Set                     | `__t: 'm'` / `__t: 's'`     | Recursively encoded entries/items                 |
+| RegExp                        | `__t: 'r'`                  | Source, flags, and `lastIndex`                    |
+| Global/well-known Symbol      | `__t: 'sym'`                | Symbol registry kind and name                     |
+| Special object representation | `__t: 'o'`                  | Symbol keys, null prototype, or literal `__t` key |
+| Array hole                    | `__t: 'h'`                  | Distinguishes a hole from `undefined`             |
+| undefined / NaN / negative 0  | `__t: 'u'` / `'n'` / `'-0'` | Values JSON cannot represent faithfully           |
+| Infinity                      | `__t: '+i'` / `__t: '-i'`   | Positive/negative infinity                        |
+| BigInt                        | `__t: 'b'`                  | Decimal string                                    |
+| Shared/circular reference     | `__t: 'ref'`                | Path to an already encoded object                 |
+
+Schema v2 escapes plain objects that themselves contain `__t`, so literal user
+data cannot be confused with a serialization marker. Unsupported object shapes
+and functions stored inside value-bearing containers fail serialization rather
+than being silently corrupted. Function-valued component-prop properties and
+function-valued raw slots are intentionally omitted by the existing compiler
+ABI.
 
 ### 3. Scope Registration
 
@@ -179,14 +211,31 @@ Each resumable component instance has a unique scope ID:
 
 ```html
 <fict-host
-  data-fict-s="s1"                                    <!-- scope ID -->
+  data-fict-s="account_scope:s1"                      <!-- scope ID -->
   data-fict-h="/assets/index.js#__fict_r0"            <!-- resume handler -->
-  data-fict-t="Counter@file:///src/App.tsx"           <!-- Component Type -->
+  data-fict-t="Counter@fict:module:m0123456789abcdef0123456789abcdef" <!-- Component Type -->
 >
   ...
 </fict-host>
 ```
 
+Every SSR render receives an automatic unique namespace for these host and
+snapshot scope IDs. For deterministic cached output, or when fragments from
+multiple services can share a document, pass a stable `scopeIdentifierPrefix`
+that is unique within the final document:
+
+```typescript
+renderToString(() => <App />, {
+  scopeIdentifierPrefix: 'account_scope',
+})
+```
+
+This option is shared by string, document, Web Stream, pipeable, async-string,
+and partial render entry points. It does not affect Suspense patch IDs; use
+`streamIdentifierPrefix` for those. Reusing a scope prefix in one document can
+make loader state ambiguous. Prefixes accept 1-128 ASCII letters, digits, `_`,
+`.`, `:`, or `-`, but may not contain `--`.
+
 ### 4. Automatic Handler Extraction
 
 The Fict compiler supports two ways to extract handlers:
@@ -245,7 +294,7 @@ interface RenderToStringOptions {
   doctype?: string | null
 
   // Resumability Configuration
-  includeSnapshot?: boolean // Default: true
+  includeSnapshot?: boolean // Preview opt-in; default: false
   snapshotScriptId?: string // Default: '__FICT_SNAPSHOT__'
   snapshotTarget?: 'container' | 'body' | 'head'
 
@@ -259,7 +308,22 @@ By default SSR does not write `window`, `document`, `Node`, or related DOM const
 `globalThis`. This keeps concurrent renders from racing over process-global DOM state. Components
 should use Fict's render-provided document/ownerDocument paths; set `exposeGlobals: true` only for
 legacy code that still reads DOM globals during server render. That compatibility mode is restored
-on `dispose()`, but it is not concurrency-safe while overlapping renders are active.
+on `dispose()`. Default renders may overlap each other, but a compatibility render is exclusive
+with every other SSR render so no request can observe another request's process-global DOM. On a
+non-extensible hardened global object, ordinary render-local SSR remains available without a
+process marker; compatibility mode remains unavailable because it cannot acquire its exclusive
+lease or install DOM globals.
+
+### renderToStringAsync
+
+```typescript
+function renderToStringAsync(view: () => FictNode, options?: RenderToStringOptions): Promise<string>
+```
+
+Waits until all Suspense boundaries have resolved, then serializes their final content. Its output
+options and defaults match `renderToString`; in particular, it returns the rendered container's
+children unless `fullDocument` or `includeContainer` is requested. Use `renderToString` when a
+synchronous fallback shell is desired instead.
 
 ### renderToDocument
 
@@ -316,6 +380,28 @@ Trusted Types deployments should use this external observer runtime. The patch
 runtime moves `<template>` content with DOM APIs (`content` + `insertBefore`) and
 does not call `innerHTML`, `insertAdjacentHTML`, `eval`, or `Function`.
 
+When Preview snapshots are enabled on a nonce-free strict-CSP route, keep
+`snapshotTarget` at `container` or `body`. Incremental `head` snapshots require a
+small executable mover; external runtime mode rejects that combination unless
+`scriptNonce` is non-empty.
+
+Each shell stream receives an automatic unique namespace for its Suspense patch
+identifiers. When independently cached fragments or streams from multiple
+services can be composed into one document, pass a stable
+`streamIdentifierPrefix` that is unique within that final document:
+
+```typescript
+renderToStream(() => <App />, {
+  mode: 'shell',
+  streamIdentifierPrefix: 'account_shell',
+})
+```
+
+The prefix only affects streaming patch identifiers; resumable scope IDs are
+unchanged. Reusing a prefix for two live streams in the same document can make
+their patches ambiguous. Prefixes accept 1-128 ASCII letters, digits, `_`, `.`,
+`:`, or `-`, but may not contain `--`.
+
 ### renderToPipeableStream
 
 Node.js-style stream variant (compatible with `pipe()`).
@@ -372,21 +458,47 @@ interface ResumableLoaderOptions {
   document?: Document
   snapshotScriptId?: string
   events?: string[] // Default: DelegatedEvents
+  snapshotMigrations?: Record<number, SnapshotMigration>
   onSnapshotIssue?: (issue: SnapshotIssue) => void
+  onSnapshotRejected?: (issue: SnapshotIssue) => void | Promise<void>
   prefetch?: PrefetchStrategy | false
 }
 
+type SnapshotMigration = (
+  snapshot: Record<string, unknown>,
+  context: SnapshotMigrationContext,
+) => unknown
+
+interface SnapshotMigrationContext {
+  fromVersion: number
+  toVersion: number
+  source: string
+}
+
 interface SnapshotIssue {
   code:
     | 'snapshot_parse_error'
     | 'snapshot_invalid_shape'
     | 'snapshot_unsupported_version'
+    | 'snapshot_migration_failed'
+    | 'snapshot_fallback_failed'
     | 'scope_snapshot_missing'
+    | 'resume_import_failed'
+    | 'resume_function_missing'
+    | 'resume_failed'
+    | 'handler_import_failed'
+    | 'handler_missing'
+    | 'handler_failed'
   message: string
   source: string
   expectedVersion: number
   actualVersion?: number
   scopeId?: string
+  qrl?: string
+  url?: string
+  exportName?: string
+  eventType?: string
+  error?: unknown
 }
 
 interface PrefetchStrategy {
@@ -395,8 +507,23 @@ interface PrefetchStrategy {
   hover?: boolean // Default: true
   hoverDelay?: number // Default: 50
 }
+
+type LegacySnapshotFormat = 'raw-props' | 'encoded-props'
+const UNVERSIONED_SNAPSHOT_MIGRATION_KEY = 0
+function createLegacySnapshotMigration(format: LegacySnapshotFormat): SnapshotMigration
 ```
 
+The current writer emits v2. Missing `v` and v1 fail closed unless the
+application explicitly selects the matching historical writer dialect. The
+loader cannot infer whether v1 `{ "__t": "u" }` bytes mean literal data or an
+encoded `undefined` value. See the
+[SSR / Resume Stability Contract](../../docs/ssr-resume-stability-contract.md)
+for the version map and migration examples.
+
+`onSnapshotIssue` is telemetry-only. `onSnapshotRejected` runs once after the
+loader disengages; the application must mount the CSR root. Fict does not mount
+CSR automatically, and it does not route QRL failures to an ErrorBoundary.
+
 ## Architecture Design
 
 ### Build Time
@@ -417,26 +544,12 @@ interface PrefetchStrategy {
 
 **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
-}
-```
+The exact generated ABI is compiler-owned and may change while resumability is
+Preview. Conceptually, the main bundle registers a resume function that restores
+the scope and reconnects reactive bindings. Each extracted handler chunk exports
+the function named by its QRL; the loader restores the lexical scope before it
+invokes that handler. Use compiler fixture output and package tests—not copied
+generated snippets—as the compatibility source of truth.
 
 ### Runtime
 
@@ -470,12 +583,20 @@ Generated detailed `fict.manifest.json` during production build, mapping virtual
 
 ```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"
+  "fict:module:m0123456789abcdef0123456789abcdef": "/assets/index-xyz789.js",
+  "virtual:fict-handler:h0123456789abcdef0123456789abcdef$$__fict_e0": "/assets/handler-e0-abc123.js",
+  "virtual:fict-handler:h0123456789abcdef0123456789abcdef$$__fict_e1": "/assets/handler-e1-def456.js"
 }
 ```
 
+Only modules that own a resumable QRL are listed. Physical filenames and
+unrelated Rollup modules are deliberately excluded.
+
+Treat the manifest, SSR server, HTML snapshots, client loader, QRL chunks, and
+external stream runtime as one build. Prefer a build-scoped manifest URL. If a
+fixed `/fict.manifest.json` is unavoidable, serve it with `no-store` or mandatory
+revalidation; do not let it use stale-while-revalidate independently from HTML.
+
 ## Integration with Vite
 
 ## Partial Prerendering
@@ -486,6 +607,8 @@ Generated detailed `fict.manifest.json` during production build, mapping virtual
 2. **Deferred phase**: deliver `stream` patches for resolved Suspense boundaries.
 
 This keeps shell TTFB low while still allowing server-resolved dynamic islands.
+The shell and every deferred patch must come from the same build and snapshot
+schema; never combine a cached shell with a newer server's patch stream.
 
 ## Edge Runtime
 
@@ -706,13 +829,25 @@ console.log(__fictGetResume('__fict_r0')) // Should return function
 
 **Solution:**
 
-```typescript
-// Use lazy initialization
-let data = $state(null) // Initial null
-onMount(async () => {
-  data = await fetchData() // Fetch on client
-})
-```
+```tsx
+// Serialize only lightweight state, then load details from a resumable client interaction.
+let data = $state(null)
+
+return (
+  <button
+    onClick$={async () => {
+      data = await fetchData(itemId)
+    }}
+  >
+    Load details
+  </button>
+)
+```
+
+`onMount` is synchronous and also runs during server rendering. Do not use an async `onMount`
+callback for client bootstrapping: returned promises are not awaited, and a cleanup resolved from a
+promise is not registered. If data must load automatically on the client, use an explicit
+client-only/CSR bootstrap instead.
 
 ### Debugging Tips
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fictjs/ssr",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Fict server-side rendering",
   "publishConfig": {
     "access": "public",
@@ -12,17 +12,25 @@
     "directory": "packages/ssr"
   },
   "type": "module",
-  "main": "dist/index.cjs",
+  "main": "dist/index.node.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "node": {
+        "import": "./dist/index.node.js",
+        "require": "./dist/index.node.cjs"
+      },
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
     "./experimental": {
       "types": "./dist/experimental.d.ts",
+      "node": {
+        "import": "./dist/experimental.node.js",
+        "require": "./dist/experimental.node.cjs"
+      },
       "import": "./dist/experimental.js",
       "require": "./dist/experimental.cjs"
     },
@@ -38,11 +46,11 @@
   ],
   "dependencies": {
     "linkedom": "^0.18.12",
-    "@fictjs/runtime": "0.26.0"
+    "@fictjs/runtime": "0.28.0"
   },
   "devDependencies": {
     "tsdown": "^0.22.3",
-    "fict": "0.26.0"
+    "fict": "0.28.0"
   },
   "keywords": [
     "fict",
@@ -58,8 +66,10 @@
     "build:stream-runtime": "node scripts/write-stream-runtime-asset.mjs",
     "dev": "tsdown --watch --on-success \"pnpm run build:stream-runtime\"",
     "test": "vitest run",
+    "test:node": "node test/node-runtime.smoke.mjs",
     "test:edge": "node test/edge-runtime.smoke.mjs",
-    "test:matrix": "pnpm run test && pnpm run test:edge",
+    "test:cjs": "node test/cjs-runtime.smoke.cjs",
+    "test:matrix": "pnpm run test && pnpm run test:node && pnpm run test:edge && pnpm run test:cjs",
     "test:coverage": "vitest run --coverage",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",

package/dist/experimental.cjs

@@ -1,3 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_render_core = require("./render-core-CWudV9yi.cjs");
-exports.renderToPartial = require_render_core.renderToPartial;

package/dist/experimental.d.cts

@@ -1,2 +0,0 @@
-import { l as renderToPartial, t as PartialPrerenderResult } from "./render-core-BCYvLfHF.cjs";
-export { type PartialPrerenderResult, renderToPartial };

package/dist/experimental.d.ts

@@ -1,2 +0,0 @@
-import { l as renderToPartial, t as PartialPrerenderResult } from "./render-core-BCYvLfHF.js";
-export { type PartialPrerenderResult, renderToPartial };

package/dist/experimental.js

@@ -1,2 +0,0 @@
-import { r as renderToPartial } from "./render-core-BLLUhkYy.js";
-export { renderToPartial };

package/dist/fict-stream-runtime.js

@@ -1 +0,0 @@
-(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};function scan(root){var list=(root&&root.querySelectorAll?root:document).querySelectorAll("template[data-fict-suspense]");for(var i=0;i<list.length;i++){apply(list[i].getAttribute("data-fict-suspense"));}}if(typeof MutationObserver==="function"){new MutationObserver(function(muts){for(var i=0;i<muts.length;i++){for(var j=0;j<muts[i].addedNodes.length;j++){var n=muts[i].addedNodes[j];if(n.nodeType===1){if(n.matches&&n.matches("template[data-fict-suspense]"))apply(n.getAttribute("data-fict-suspense"));scan(n);}}}}).observe(document.documentElement||document,{childList:true,subtree:true});}if(document.readyState==="loading"){document.addEventListener("DOMContentLoaded",function(){scan(document);},{once:true});}else{scan(document);}})();

package/dist/index.cjs

@@ -1,8 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_render_core = require("./render-core-CWudV9yi.cjs");
-exports.createSSRDocument = require_render_core.createSSRDocument;
-exports.renderToDocument = require_render_core.renderToDocument;
-exports.renderToPipeableStream = require_render_core.renderToPipeableStream;
-exports.renderToStream = require_render_core.renderToStream;
-exports.renderToString = require_render_core.renderToString;
-exports.renderToStringAsync = require_render_core.renderToStringAsync;

package/dist/index.d.cts

@@ -1,2 +0,0 @@
-import { a as RenderToStringOptions, c as renderToDocument, d as renderToStream, f as renderToString, i as RenderToStreamOptions, n as PipeableStream, o as SSRDom, p as renderToStringAsync, r as RenderToDocumentResult, s as createSSRDocument, u as renderToPipeableStream } from "./render-core-BCYvLfHF.cjs";
-export { type PipeableStream, type RenderToDocumentResult, type RenderToStreamOptions, type RenderToStringOptions, type SSRDom, createSSRDocument, renderToDocument, renderToPipeableStream, renderToStream, renderToString, renderToStringAsync };

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-import { a as RenderToStringOptions, c as renderToDocument, d as renderToStream, f as renderToString, i as RenderToStreamOptions, n as PipeableStream, o as SSRDom, p as renderToStringAsync, r as RenderToDocumentResult, s as createSSRDocument, u as renderToPipeableStream } from "./render-core-BCYvLfHF.js";
-export { type PipeableStream, type RenderToDocumentResult, type RenderToStreamOptions, type RenderToStringOptions, type SSRDom, createSSRDocument, renderToDocument, renderToPipeableStream, renderToStream, renderToString, renderToStringAsync };

package/dist/index.js

@@ -1,2 +0,0 @@
-import { a as renderToStream, i as renderToPipeableStream, n as renderToDocument, o as renderToString, s as renderToStringAsync, t as createSSRDocument } from "./render-core-BLLUhkYy.js";
-export { createSSRDocument, renderToDocument, renderToPipeableStream, renderToStream, renderToString, renderToStringAsync };