@fictjs/ssr 0.7.0 → 0.9.0

package/README.md

@@ -144,6 +144,7 @@ During server-side rendering, component state is serialized into JSON and inject
 ```html
 <script id="__FICT_SNAPSHOT__" type="application/json">
   {
+    "v": 1,
     "scopes": {
       "s1": {
         "id": "s1",
@@ -341,9 +342,23 @@ interface ResumableLoaderOptions {
   document?: Document
   snapshotScriptId?: string
   events?: string[] // Default: DelegatedEvents
+  onSnapshotIssue?: (issue: SnapshotIssue) => void
   prefetch?: PrefetchStrategy | false
 }
 
+interface SnapshotIssue {
+  code:
+    | 'snapshot_parse_error'
+    | 'snapshot_invalid_shape'
+    | 'snapshot_unsupported_version'
+    | 'scope_snapshot_missing'
+  message: string
+  source: string
+  expectedVersion: number
+  actualVersion?: number
+  scopeId?: string
+}
+
 interface PrefetchStrategy {
   visibility?: boolean // Default: true
   visibilityMargin?: string // Default: '200px'
@@ -619,6 +634,7 @@ let dataId = $state(id) // Store ID only, fetch on client
 - [SSR SEO Guide](../../docs/ssr-seo.md)
 - [SSR Performance Tuning](../../docs/ssr-performance.md)
 - [SSR Deployment Guide](../../docs/ssr-deployment.md)
+- [SSR / Resume Stability Contract](../../docs/ssr-resume-stability-contract.md)
 
 ## Troubleshooting
 

package/dist/index.cjs

@@ -593,7 +593,7 @@ function splitDocumentHtml(html) {
   return { head: html.slice(0, idx), tail: html.slice(idx) };
 }
 function buildIncrementalSnapshotChunk(state, options) {
-  const json = JSON.stringify(state);
+  const json = serializeSnapshotForScript(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>`;
@@ -615,7 +615,7 @@ 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);
+  script.textContent = serializeSnapshotForScript(state);
   if (options.fullDocument) {
     if (options.snapshotTarget === "head" && document.head) {
       document.head.appendChild(script);
@@ -637,6 +637,9 @@ function injectSnapshot(document, container, state, options) {
   }
   container.appendChild(script);
 }
+function serializeSnapshotForScript(state) {
+  return JSON.stringify(state).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
 function serializeDoctype(document, override) {
   if (override === null) return "";
   if (override !== void 0) return override;

package/dist/index.js

@@ -571,7 +571,7 @@ function splitDocumentHtml(html) {
   return { head: html.slice(0, idx), tail: html.slice(idx) };
 }
 function buildIncrementalSnapshotChunk(state, options) {
-  const json = JSON.stringify(state);
+  const json = serializeSnapshotForScript(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>`;
@@ -593,7 +593,7 @@ 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);
+  script.textContent = serializeSnapshotForScript(state);
   if (options.fullDocument) {
     if (options.snapshotTarget === "head" && document.head) {
       document.head.appendChild(script);
@@ -615,6 +615,9 @@ function injectSnapshot(document, container, state, options) {
   }
   container.appendChild(script);
 }
+function serializeSnapshotForScript(state) {
+  return JSON.stringify(state).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
 function serializeDoctype(document, override) {
   if (override === null) return "";
   if (override !== void 0) return override;

package/package.json

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