@standhigher/react-email-editor 0.5.1 → 0.5.2

package/README.md

@@ -28,10 +28,6 @@ export function EmailPage() {
 }
 ```
 
-With Next.js App Router, add `"use client"` to the integration component and import CSS from an allowed global stylesheet entry. Your app implements persistence, resource uploads and email delivery.
-
-Custom blocks that omit `icon` use the first character of their trimmed `title` as the icon: `Coupon` displays `C` and `优惠券` displays `优`. An explicit `icon` takes precedence.
-
 ## Run locally
 
 Use Node.js 24 LTS (`.nvmrc`; at least 22.18 for the complete test suite):

package/README.zh-CN.md

@@ -28,10 +28,6 @@ export function EmailPage() {
 }
 ```
 
-Next.js App Router 的接入组件需声明 `"use client"`；样式在应用允许的全局样式入口引入。保存、上传资源与发送邮件由你的应用实现。
-
-自定义区块省略 `icon` 时，默认使用 `title` 去除首尾空白后的第一个字符作为图标，例如 `Coupon` 显示 `C`、`优惠券` 显示 `优`；传入的 `icon` 优先使用。
-
 ## 本地启动
 
 推荐 Node.js 24 LTS（`.nvmrc`；完整测试最低需要 22.18）：

package/dist/index.js

@@ -44,7 +44,7 @@ function usePluginEditor() {
 }
 
 // src/shell/EmailEditorShell.tsx
-import { useState as useState18 } from "react";
+import { useState as useState20 } from "react";
 
 // src/editor-dnd/EditorDnd.tsx
 import { useLayoutEffect as useLayoutEffect5, useMemo, useRef as useRef7, useState as useState7 } from "react";
@@ -4615,14 +4615,10 @@ function Inspector({
 }
 
 // src/stage/Stage.tsx
-import { useMemo as useMemo5 } from "react";
+import { useMemo as useMemo4, useState as useState18 } from "react";
 
-// src/stage/canvas/Canvas.tsx
-import { useDroppable } from "@dnd-kit/core";
-import {
-  SortableContext,
-  verticalListSortingStrategy
-} from "@dnd-kit/sortable";
+// src/stage/preview/usePreviewBuffer.ts
+import { useCallback, useEffect as useEffect6, useLayoutEffect as useLayoutEffect9, useReducer, useRef as useRef13, useState as useState16 } from "react";
 
 // src/render/layout.ts
 function surfaceStyle(body) {
@@ -4639,8 +4635,126 @@ function viewportWidth(device, body) {
   return `${emailViewportWidth(device, body.contentWidth)}px`;
 }
 
+// src/stage/preview/buffer.ts
+function createPreviewBuffer() {
+  return { frames: [null, null], front: null, failure: null };
+}
+function previewBufferReducer(state, action) {
+  var _a, _b, _c;
+  switch (action.type) {
+    case "generated": {
+      const match = action.force ? -1 : state.frames.findIndex((frame) => frame && frame.status !== "failed" && frame.html === action.snapshot.html && frame.width === action.snapshot.width);
+      const target = match < 0 ? state.front === 0 ? 1 : 0 : match;
+      const frames = [...state.frames];
+      frames[target] = match < 0 ? action.snapshot : __spreadProps(__spreadValues({}, frames[target]), { source: action.snapshot.source });
+      const ready = ((_a = frames[target]) == null ? void 0 : _a.status) === "ready";
+      return { frames, front: ready ? target : state.front, failure: ready ? null : state.failure };
+    }
+    case "ready": {
+      const index = state.frames.findIndex((frame) => frame && frame.id === action.id && frame.status === "loading");
+      if (index < 0) return state;
+      const frames = [...state.frames];
+      frames[index] = __spreadProps(__spreadValues({}, frames[index]), { status: "ready" });
+      const current = ((_b = frames[index]) == null ? void 0 : _b.source) === action.source;
+      return { frames, front: current ? index : state.front, failure: current ? null : state.failure };
+    }
+    case "failed": {
+      if (action.id === void 0) {
+        const frames2 = [state.frames[0], state.frames[1]];
+        for (const index2 of [0, 1]) {
+          const frame = frames2[index2];
+          if ((frame == null ? void 0 : frame.status) === "loading") frames2[index2] = __spreadProps(__spreadValues({}, frame), { status: "failed" });
+        }
+        return __spreadProps(__spreadValues({}, state), { frames: frames2, failure: action.failure });
+      }
+      const index = state.frames.findIndex((frame) => frame && frame.id === action.id && frame.status === "loading");
+      if (index < 0) return state;
+      const frames = [...state.frames];
+      frames[index] = __spreadProps(__spreadValues({}, frames[index]), { status: "failed" });
+      return __spreadProps(__spreadValues({}, state), { frames, failure: ((_c = frames[index]) == null ? void 0 : _c.source) === action.failure.source ? action.failure : state.failure });
+    }
+  }
+}
+
+// src/stage/preview/constants.ts
+var PREVIEW_DEBOUNCE_MS = 400;
+var PREVIEW_MAX_WAIT_MS = 2e3;
+var PREVIEW_LOAD_TIMEOUT_MS = 15e3;
+var PREVIEW_BUFFER_SLOTS = [0, 1];
+
+// src/stage/preview/usePreviewBuffer.ts
+function usePreviewBuffer(source, requested) {
+  var _a;
+  const [state, dispatch] = useReducer(previewBufferReducer, void 0, createPreviewBuffer);
+  const [request, setRequest] = useState16({ key: requested ? 1 : 0, force: false });
+  const previousRequested = useRef13(requested);
+  const sourceRef = useRef13(source);
+  const pendingSince = useRef13(null);
+  const attempted = useRef13(null);
+  const revision = useRef13(0);
+  useLayoutEffect9(() => {
+    sourceRef.current = source;
+  }, [source]);
+  const flush = useCallback(() => setRequest((value) => __spreadProps(__spreadValues({}, value), { key: value.key + 1, force: false })), []);
+  useEffect6(() => {
+    var _a2, _b, _c;
+    const enteringPreview = requested && !previousRequested.current;
+    previousRequested.current = requested;
+    const newRequest = request.key > 0 && ((_a2 = attempted.current) == null ? void 0 : _a2.requestKey) !== request.key;
+    const force = newRequest && request.force;
+    if (((_b = attempted.current) == null ? void 0 : _b.source) === source && !force) {
+      attempted.current.requestKey = request.key;
+      return;
+    }
+    const immediate = enteringPreview || newRequest;
+    (_c = pendingSince.current) != null ? _c : pendingSince.current = Date.now();
+    const remaining = Math.max(0, PREVIEW_MAX_WAIT_MS - (Date.now() - pendingSince.current));
+    let idle;
+    let cancelled = false;
+    const generate = () => {
+      if (cancelled || sourceRef.current !== source) return;
+      attempted.current = { source, requestKey: request.key };
+      pendingSince.current = null;
+      try {
+        const html = source.config.toHtml(source.document, { resolveHtmlTemplates: true, variables: source.variables });
+        dispatch({ type: "generated", snapshot: { id: ++revision.current, source, html, width: viewportWidth(source.device, source.document.body), status: "loading" }, force });
+      } catch (error) {
+        dispatch({ type: "failed", failure: { source, message: error instanceof Error ? error.message : String(error) || "Email preview failed." } });
+      }
+    };
+    const delay = immediate ? 0 : Math.min(PREVIEW_DEBOUNCE_MS, remaining);
+    const timer = setTimeout(() => {
+      if (immediate || typeof requestIdleCallback !== "function") generate();
+      else idle = requestIdleCallback(generate, { timeout: Math.max(1, remaining - delay) });
+    }, delay);
+    return () => {
+      cancelled = true;
+      clearTimeout(timer);
+      if (idle !== void 0) cancelIdleCallback(idle);
+    };
+  }, [source, requested, request]);
+  const markReady = useCallback((id) => {
+    dispatch({ type: "ready", id, source: sourceRef.current });
+  }, []);
+  const markFailed = useCallback((id, message) => {
+    dispatch({ type: "failed", id, failure: { source: sourceRef.current, message } });
+  }, []);
+  const retry = useCallback(() => setRequest((value) => __spreadProps(__spreadValues({}, value), { key: value.key + 1, force: true })), []);
+  const front = state.front === null ? null : state.frames[state.front];
+  const failure = ((_a = state.failure) == null ? void 0 : _a.source) === source ? state.failure : null;
+  const displayFailure = failure != null ? failure : state.front === null ? state.failure : null;
+  return __spreadProps(__spreadValues({}, state), { failure, displayFailure, ready: (front == null ? void 0 : front.source) === source, markReady, markFailed, flush, retry });
+}
+
+// src/stage/canvas/Canvas.tsx
+import { useDroppable } from "@dnd-kit/core";
+import {
+  SortableContext,
+  verticalListSortingStrategy
+} from "@dnd-kit/sortable";
+
 // src/stage/canvas/CanvasBlock.tsx
-import { useId as useId13, useMemo as useMemo3, useState as useState16 } from "react";
+import { useId as useId13, useMemo as useMemo3, useState as useState17 } from "react";
 import { useSortable } from "@dnd-kit/sortable";
 import { CSS } from "@dnd-kit/utilities";
 
@@ -4996,7 +5110,7 @@ function blockToHtml(node, definitions = DEFAULT_BLOCKS, mode = "email", options
 }
 
 // src/stage/canvas/components/HtmlCanvas.tsx
-import { useCallback, useEffect as useEffect6, useRef as useRef13 } from "react";
+import { useCallback as useCallback2, useEffect as useEffect7, useRef as useRef14 } from "react";
 
 // src/render/head-styles.ts
 function extractHeadStyles(html) {
@@ -5017,10 +5131,10 @@ function frameHtml(html, baseCss) {
 }
 function HtmlCanvas({ html, baseCss = "", onSelect }) {
   const hasHtmlTag = /<\/?[a-z][\w:-]*(?:\s[^>]*)?>/i.test(html);
-  const containerRef = useRef13(null);
-  const frameRef = useRef13(null);
-  const cleanupRef = useRef13();
-  const observeContent = useCallback(() => {
+  const containerRef = useRef14(null);
+  const frameRef = useRef14(null);
+  const cleanupRef = useRef14();
+  const observeContent = useCallback2(() => {
     var _a;
     (_a = cleanupRef.current) == null ? void 0 : _a.call(cleanupRef);
     const container = containerRef.current;
@@ -5061,7 +5175,7 @@ function HtmlCanvas({ html, baseCss = "", onSelect }) {
       window2.cancelAnimationFrame(animationFrame);
     };
   }, []);
-  useEffect6(() => () => {
+  useEffect7(() => () => {
     var _a;
     return (_a = cleanupRef.current) == null ? void 0 : _a.call(cleanupRef);
   }, [hasHtmlTag, html]);
@@ -5233,6 +5347,7 @@ function canvasBlockStyle(block, body) {
 // src/stage/canvas/CanvasBlock.tsx
 import { jsx as jsx51, jsxs as jsxs40 } from "react/jsx-runtime";
 function CanvasBlock({
+  active = true,
   block: sourceBlock,
   body,
   definition,
@@ -5251,9 +5366,9 @@ function CanvasBlock({
   const block = useMemo3(() => __spreadProps(__spreadValues({}, sourceBlock), { style: resolveBlockStyle(sourceBlock.style, definition) }), [sourceBlock, definition]);
   const renderKey = useMemo3(() => ({ definition, templateEngine, variables }), [definition, templateEngine, variables]);
   const toolbarId = useId13();
-  const [toolbarCollapsed, setToolbarCollapsed] = useState16(false);
+  const [toolbarCollapsed, setToolbarCollapsed] = useState17(false);
   const dragData = { kind: "canvas" };
-  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id: block.id, data: dragData });
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id: block.id, data: dragData, disabled: !active });
   const select = (event) => {
     event == null ? void 0 : event.stopPropagation();
     onSelect();
@@ -5323,6 +5438,7 @@ function CanvasBlock({
 // src/stage/canvas/Canvas.tsx
 import { jsx as jsx52 } from "react/jsx-runtime";
 function Canvas({
+  active = true,
   blocks,
   body,
   definitions,
@@ -5341,6 +5457,7 @@ function Canvas({
 }) {
   const { setNodeRef, isOver } = useDroppable({
     id: CANVAS_DROP_ID,
+    disabled: !active,
     data: { kind: "canvas" }
   });
   return /* @__PURE__ */ jsx52(
@@ -5355,9 +5472,9 @@ function Canvas({
         if (!ownerWindow || !(target instanceof ownerWindow.Element)) return;
         if (target.closest(".ree-block")) return;
         onSelect(null);
-        const active = ownerDocument.activeElement;
-        if (active instanceof ownerWindow.HTMLElement && active.closest(".ree-rte")) {
-          active.blur();
+        const active2 = ownerDocument.activeElement;
+        if (active2 instanceof ownerWindow.HTMLElement && active2.closest(".ree-rte")) {
+          active2.blur();
         }
       },
       children: /* @__PURE__ */ jsx52(
@@ -5392,6 +5509,7 @@ function Canvas({
                         CanvasBlock,
                         {
                           block,
+                          active,
                           body,
                           definition: getBlockDefinition(block.type, definitions),
                           selected: block.id === selectedId,
@@ -5420,84 +5538,134 @@ function Canvas({
 }
 
 // src/stage/preview/Preview.tsx
-import { useCallback as useCallback2, useEffect as useEffect7, useMemo as useMemo4, useRef as useRef14 } from "react";
+import { useRef as useRef16 } from "react";
+
+// src/stage/preview/PreviewFrame.tsx
+import { useLayoutEffect as useLayoutEffect10, useRef as useRef15 } from "react";
 import { jsx as jsx53 } from "react/jsx-runtime";
-function Preview({ document, config, variables, device }) {
-  const frameRef = useRef14(null);
-  const cleanupRef = useRef14();
-  const html = useMemo4(
-    () => config.toHtml(document, {
-      resolveHtmlTemplates: true,
-      variables
-    }),
-    [document, config, variables]
-  );
-  const observeContent = useCallback2(() => {
-    var _a;
-    (_a = cleanupRef.current) == null ? void 0 : _a.call(cleanupRef);
+function PreviewFrame({ snapshot, onReady, onFailed }) {
+  const frameRef = useRef15(null);
+  const { id, html } = snapshot;
+  useLayoutEffect10(() => {
     const frame = frameRef.current;
-    const frameDocument = frame == null ? void 0 : frame.contentDocument;
-    const frameWindow = frameDocument == null ? void 0 : frameDocument.defaultView;
-    if (!frame || !(frameDocument == null ? void 0 : frameDocument.body) || !frameWindow) return;
-    let animationFrame = 0;
-    const fit = () => {
-      frame.style.height = `${frameDocument.body.getBoundingClientRect().height}px`;
+    const ownerWindow = frame == null ? void 0 : frame.ownerDocument.defaultView;
+    if (!frame || !ownerWindow) return;
+    let status = "loading";
+    let stopObserving;
+    const fail = (message) => {
+      if (status !== "loading") return;
+      status = "failed";
+      clearTimeout(timer);
+      stopObserving == null ? void 0 : stopObserving();
+      stopObserving = void 0;
+      onFailed(id, message);
     };
-    const scheduleFit = () => {
-      frameWindow.cancelAnimationFrame(animationFrame);
-      animationFrame = frameWindow.requestAnimationFrame(fit);
+    const timer = setTimeout(() => fail("Email preview timed out. Please retry."), PREVIEW_LOAD_TIMEOUT_MS);
+    const observeContent = () => {
+      if (status !== "loading") return;
+      stopObserving == null ? void 0 : stopObserving();
+      stopObserving = void 0;
+      try {
+        const frameDocument = frame.contentDocument;
+        const frameWindow = frameDocument == null ? void 0 : frameDocument.defaultView;
+        if (!(frameDocument == null ? void 0 : frameDocument.body) || !frameWindow) throw new Error("Email preview could not be measured. Please retry.");
+        let animationFrame = 0;
+        let readyFrame = 0;
+        const fit = () => {
+          try {
+            const height = frameDocument.body.getBoundingClientRect().height;
+            if (!Number.isFinite(height) || height < 0) throw new Error("Email preview returned an invalid height. Please retry.");
+            frame.style.height = `${Math.max(1, height)}px`;
+            return true;
+          } catch (error) {
+            fail(error instanceof Error ? error.message : "Email preview could not be measured. Please retry.");
+            return false;
+          }
+        };
+        const scheduleFit = () => {
+          ownerWindow.cancelAnimationFrame(animationFrame);
+          animationFrame = ownerWindow.requestAnimationFrame(fit);
+        };
+        const observer = new frameWindow.ResizeObserver(scheduleFit);
+        stopObserving = () => {
+          observer.disconnect();
+          frameDocument.removeEventListener("load", scheduleFit, true);
+          ownerWindow.cancelAnimationFrame(animationFrame);
+          ownerWindow.cancelAnimationFrame(readyFrame);
+        };
+        observer.observe(frameDocument.body);
+        frameDocument.addEventListener("load", scheduleFit, true);
+        if (!fit()) return;
+        readyFrame = ownerWindow.requestAnimationFrame(() => {
+          if (status !== "loading" || !fit()) return;
+          status = "ready";
+          clearTimeout(timer);
+          onReady(id);
+        });
+      } catch (error) {
+        fail(error instanceof Error ? error.message : "Email preview could not be loaded. Please retry.");
+      }
     };
-    const observer = new frameWindow.ResizeObserver(scheduleFit);
-    observer.observe(frameDocument.body);
-    frameDocument.addEventListener("load", scheduleFit, true);
-    fit();
-    cleanupRef.current = () => {
-      observer.disconnect();
-      frameDocument.removeEventListener("load", scheduleFit, true);
-      frameWindow.cancelAnimationFrame(animationFrame);
+    const loadError = () => fail("Email preview could not be loaded. Please retry.");
+    frame.addEventListener("load", observeContent);
+    frame.addEventListener("error", loadError);
+    return () => {
+      status = "disposed";
+      clearTimeout(timer);
+      stopObserving == null ? void 0 : stopObserving();
+      frame.removeEventListener("load", observeContent);
+      frame.removeEventListener("error", loadError);
     };
-  }, []);
-  useEffect7(() => () => {
-    var _a;
-    return (_a = cleanupRef.current) == null ? void 0 : _a.call(cleanupRef);
-  }, [html]);
-  return /* @__PURE__ */ jsx53("div", { className: "ree-preview-stage", children: /* @__PURE__ */ jsx53(
-    "div",
-    {
-      className: "ree-email-viewport",
-      style: {
-        width: viewportWidth(device, document.body),
-        marginLeft: "auto",
-        marginRight: "auto"
-      },
-      children: /* @__PURE__ */ jsx53(
-        "iframe",
-        {
-          ref: frameRef,
-          className: "ree-preview-frame",
-          title: "Email preview",
-          srcDoc: html,
-          onLoad: observeContent,
-          style: {
-            backgroundColor: "#ffffff"
-          }
-        }
-      )
-    }
-  ) });
+  }, [id, onReady, onFailed]);
+  return /* @__PURE__ */ jsx53("iframe", { ref: frameRef, className: "ree-preview-frame", title: "Email preview", sandbox: "allow-same-origin", srcDoc: html });
 }
 
-// src/stage/StageHeader.tsx
+// src/stage/preview/Preview.tsx
 import { jsx as jsx54, jsxs as jsxs41 } from "react/jsx-runtime";
+function Preview({ frames, front, failure, onReady, onFailed, onRetry }) {
+  const scrollRef = useRef16({ top: 0, left: 0 });
+  return /* @__PURE__ */ jsxs41("div", { className: "ree-preview-buffer", children: [
+    PREVIEW_BUFFER_SLOTS.map((index) => {
+      const snapshot = frames[index];
+      const visible = front === index;
+      return /* @__PURE__ */ jsx54(
+        "div",
+        __spreadProps(__spreadValues({
+          className: `ree-preview-stage${visible ? "" : " is-buffered"}`,
+          "aria-hidden": !visible
+        }, !visible ? { inert: "" } : {}), {
+          ref: (node) => {
+            if (node && visible) {
+              node.scrollTop = scrollRef.current.top;
+              node.scrollLeft = scrollRef.current.left;
+            }
+          },
+          onScroll: (event) => {
+            if (visible) scrollRef.current = { top: event.currentTarget.scrollTop, left: event.currentTarget.scrollLeft };
+          },
+          children: /* @__PURE__ */ jsx54("div", { className: "ree-email-viewport", style: { width: snapshot == null ? void 0 : snapshot.width, marginLeft: "auto", marginRight: "auto" }, children: snapshot ? /* @__PURE__ */ jsx54(PreviewFrame, { snapshot, onReady, onFailed }, snapshot.id) : null })
+        }),
+        index
+      );
+    }),
+    failure ? /* @__PURE__ */ jsxs41("div", { className: "ree-plugin-error ree-preview-error", role: "alert", children: [
+      /* @__PURE__ */ jsx54("p", { children: failure.message }),
+      /* @__PURE__ */ jsx54(Button, { onClick: onRetry, children: "Retry" })
+    ] }) : null
+  ] });
+}
+
+// src/stage/StageHeader.tsx
+import { jsx as jsx55, jsxs as jsxs42 } from "react/jsx-runtime";
 function StageHeader({
   viewMode,
   device,
   onViewModeChange,
   onDeviceChange
 }) {
-  return /* @__PURE__ */ jsxs41("div", { className: "ree-col-head ree-stage-head", children: [
-    /* @__PURE__ */ jsxs41("div", { className: "ree-segment", role: "group", "aria-label": "Editor mode", children: [
-      /* @__PURE__ */ jsx54(
+  return /* @__PURE__ */ jsxs42("div", { className: "ree-col-head ree-stage-head", children: [
+    /* @__PURE__ */ jsxs42("div", { className: "ree-segment", role: "group", "aria-label": "Editor mode", children: [
+      /* @__PURE__ */ jsx55(
         "button",
         {
           type: "button",
@@ -5506,14 +5674,14 @@ function StageHeader({
           "aria-label": "Edit",
           title: "Edit",
           onClick: () => onViewModeChange("edit"),
-          children: /* @__PURE__ */ jsxs41("svg", { viewBox: "0 0 24 24", width: "20", height: "20", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
-            /* @__PURE__ */ jsx54("path", { d: "M12 20h9" }),
-            /* @__PURE__ */ jsx54("path", { d: "M16.5 3.5a2.1 2.1 0 0 1 3 3L8 18l-4 1 1-4 11.5-11.5Z" })
+          children: /* @__PURE__ */ jsxs42("svg", { viewBox: "0 0 24 24", width: "20", height: "20", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
+            /* @__PURE__ */ jsx55("path", { d: "M12 20h9" }),
+            /* @__PURE__ */ jsx55("path", { d: "M16.5 3.5a2.1 2.1 0 0 1 3 3L8 18l-4 1 1-4 11.5-11.5Z" })
           ] })
         }
       ),
-      /* @__PURE__ */ jsx54("span", { className: "ree-segment-divider", "aria-hidden": "true" }),
-      /* @__PURE__ */ jsx54(
+      /* @__PURE__ */ jsx55("span", { className: "ree-segment-divider", "aria-hidden": "true" }),
+      /* @__PURE__ */ jsx55(
         "button",
         {
           type: "button",
@@ -5522,15 +5690,15 @@ function StageHeader({
           "aria-label": "Preview",
           title: "Preview",
           onClick: () => onViewModeChange("preview"),
-          children: /* @__PURE__ */ jsxs41("svg", { viewBox: "0 0 24 24", width: "20", height: "20", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
-            /* @__PURE__ */ jsx54("path", { d: "M2.5 12s3.5-6 9.5-6 9.5 6 9.5 6-3.5 6-9.5 6-9.5-6-9.5-6Z" }),
-            /* @__PURE__ */ jsx54("circle", { cx: "12", cy: "12", r: "2.5" })
+          children: /* @__PURE__ */ jsxs42("svg", { viewBox: "0 0 24 24", width: "20", height: "20", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
+            /* @__PURE__ */ jsx55("path", { d: "M2.5 12s3.5-6 9.5-6 9.5 6 9.5 6-3.5 6-9.5 6-9.5-6-9.5-6Z" }),
+            /* @__PURE__ */ jsx55("circle", { cx: "12", cy: "12", r: "2.5" })
           ] })
         }
       )
     ] }),
-    /* @__PURE__ */ jsxs41("div", { className: "ree-segment", role: "group", "aria-label": "Canvas device", children: [
-      /* @__PURE__ */ jsx54(
+    /* @__PURE__ */ jsxs42("div", { className: "ree-segment", role: "group", "aria-label": "Canvas device", children: [
+      /* @__PURE__ */ jsx55(
         "button",
         {
           type: "button",
@@ -5539,15 +5707,15 @@ function StageHeader({
           "aria-label": "Desktop",
           title: "Desktop",
           onClick: () => onDeviceChange("desktop"),
-          children: /* @__PURE__ */ jsxs41("svg", { viewBox: "0 0 24 24", width: "20", height: "20", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
-            /* @__PURE__ */ jsx54("rect", { x: "3", y: "4", width: "18", height: "12", rx: "1.5" }),
-            /* @__PURE__ */ jsx54("path", { d: "M8 20h8" }),
-            /* @__PURE__ */ jsx54("path", { d: "M12 16v4" })
+          children: /* @__PURE__ */ jsxs42("svg", { viewBox: "0 0 24 24", width: "20", height: "20", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
+            /* @__PURE__ */ jsx55("rect", { x: "3", y: "4", width: "18", height: "12", rx: "1.5" }),
+            /* @__PURE__ */ jsx55("path", { d: "M8 20h8" }),
+            /* @__PURE__ */ jsx55("path", { d: "M12 16v4" })
           ] })
         }
       ),
-      /* @__PURE__ */ jsx54("span", { className: "ree-segment-divider", "aria-hidden": "true" }),
-      /* @__PURE__ */ jsx54(
+      /* @__PURE__ */ jsx55("span", { className: "ree-segment-divider", "aria-hidden": "true" }),
+      /* @__PURE__ */ jsx55(
         "button",
         {
           type: "button",
@@ -5556,9 +5724,9 @@ function StageHeader({
           "aria-label": "Mobile",
           title: "Mobile",
           onClick: () => onDeviceChange("mobile"),
-          children: /* @__PURE__ */ jsxs41("svg", { viewBox: "0 0 24 24", width: "20", height: "20", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
-            /* @__PURE__ */ jsx54("rect", { x: "7", y: "2.5", width: "10", height: "19", rx: "2" }),
-            /* @__PURE__ */ jsx54("path", { d: "M11 18.5h2" })
+          children: /* @__PURE__ */ jsxs42("svg", { viewBox: "0 0 24 24", width: "20", height: "20", fill: "none", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
+            /* @__PURE__ */ jsx55("rect", { x: "7", y: "2.5", width: "10", height: "19", rx: "2" }),
+            /* @__PURE__ */ jsx55("path", { d: "M11 18.5h2" })
           ] })
         }
       )
@@ -5567,7 +5735,7 @@ function StageHeader({
 }
 
 // src/stage/Stage.tsx
-import { jsx as jsx55, jsxs as jsxs42 } from "react/jsx-runtime";
+import { jsx as jsx56, jsxs as jsxs43 } from "react/jsx-runtime";
 function Stage({
   session,
   viewMode,
@@ -5576,64 +5744,70 @@ function Stage({
   onDeviceChange,
   onSelectBlock
 }) {
-  const previewKey = useMemo5(() => ({ config: session.config, variables: session.variables }), [session.config, session.variables]);
+  const source = useMemo4(() => ({ document: session.document, config: session.config, variables: session.variables, device }), [session.document, session.config, session.variables, device]);
+  const requested = viewMode === "preview";
+  const preview = usePreviewBuffer(source, requested);
+  const [previewVisible, setPreviewVisible] = useState18(false);
+  if (!requested && previewVisible) setPreviewVisible(false);
+  if (requested && !previewVisible && (preview.ready || preview.failure)) setPreviewVisible(true);
+  const editing = !requested;
   const { targetId, dropEdge } = useEditorDragState();
-  return /* @__PURE__ */ jsxs42("div", { className: "ree-col ree-col-center", children: [
-    /* @__PURE__ */ jsx55(
+  return /* @__PURE__ */ jsxs43("div", { className: "ree-col ree-col-center", children: [
+    /* @__PURE__ */ jsx56(
       StageHeader,
       {
         viewMode,
         device,
-        onViewModeChange,
+        onViewModeChange: (mode) => {
+          if (mode === "preview") preview.flush();
+          onViewModeChange(mode);
+        },
         onDeviceChange
       }
     ),
-    viewMode === "edit" ? /* @__PURE__ */ jsx55("div", { className: "ree-stage-view", children: /* @__PURE__ */ jsx55(
-      Canvas,
-      {
-        blocks: session.document.blocks,
-        body: session.document.body,
-        definitions: session.definitions,
-        selectedId: session.selectedId,
-        dropTargetId: targetId,
-        dropEdge,
-        variables: session.variables,
-        templateEngine: session.config.templateEngine,
-        device,
-        onSelect: onSelectBlock,
-        onCommitControl: session.updateControl,
-        onCommitControls: session.updateControls,
-        onCommitStyle: session.updateStyle,
-        onDuplicate: session.duplicateBlock,
-        onRemove: session.removeBlock
-      }
-    ) }) : /* @__PURE__ */ jsx55("div", { className: "ree-stage-view", children: /* @__PURE__ */ jsx55(BlockErrorBoundary, { identity: session.document, resetKey: previewKey, children: /* @__PURE__ */ jsx55(
-      Preview,
-      {
-        document: session.document,
-        config: session.config,
-        variables: session.variables,
-        device
-      }
-    ) }) })
+    /* @__PURE__ */ jsxs43("div", { className: "ree-stage-content", "aria-busy": requested && !preview.ready && !preview.failure, children: [
+      /* @__PURE__ */ jsx56("div", __spreadProps(__spreadValues({ className: `ree-stage-view${previewVisible ? " is-buffered" : ""}`, "aria-hidden": previewVisible }, !editing ? { inert: "" } : {}), { children: /* @__PURE__ */ jsx56(
+        Canvas,
+        {
+          blocks: session.document.blocks,
+          body: session.document.body,
+          definitions: session.definitions,
+          active: editing,
+          selectedId: editing ? session.selectedId : null,
+          dropTargetId: targetId,
+          dropEdge,
+          variables: session.variables,
+          templateEngine: session.config.templateEngine,
+          device,
+          onSelect: onSelectBlock,
+          onCommitControl: session.updateControl,
+          onCommitControls: session.updateControls,
+          onCommitStyle: session.updateStyle,
+          onDuplicate: session.duplicateBlock,
+          onRemove: session.removeBlock
+        }
+      ) })),
+      /* @__PURE__ */ jsx56("div", __spreadProps(__spreadValues({ className: `ree-stage-view${previewVisible ? "" : " is-buffered"}`, "aria-hidden": !previewVisible }, !previewVisible ? { inert: "" } : {}), { children: /* @__PURE__ */ jsx56(Preview, { frames: preview.frames, front: preview.front, failure: preview.displayFailure, onReady: preview.markReady, onFailed: preview.markFailed, onRetry: preview.retry }) })),
+      requested && !preview.ready && !preview.failure ? /* @__PURE__ */ jsx56("div", { className: "ree-preview-pending", role: "status", children: "Preparing preview\u2026" }) : null
+    ] })
   ] });
 }
 
 // src/shell/SubjectBar.tsx
-import { useId as useId14, useRef as useRef15 } from "react";
+import { useId as useId14, useRef as useRef17 } from "react";
 
 // src/shell/constants.ts
 var EMPTY_VARIABLES = [];
 var PERSONALIZATION_HINT = "Personalization fields will appear blank if no data is available.";
 
 // src/shell/SubjectBar.tsx
-import { Fragment as Fragment5, jsx as jsx56, jsxs as jsxs43 } from "react/jsx-runtime";
+import { Fragment as Fragment5, jsx as jsx57, jsxs as jsxs44 } from "react/jsx-runtime";
 function SubjectBar({
   subject,
   variables,
   onSubjectChange
 }) {
-  const inputRef = useRef15(null);
+  const inputRef = useRef17(null);
   const subjectId = useId14();
   const countId = useId14();
   const insertVariable = (token) => {
@@ -5653,10 +5827,10 @@ function SubjectBar({
       (_b2 = inputRef.current) == null ? void 0 : _b2.setSelectionRange(cursor, cursor);
     });
   };
-  return /* @__PURE__ */ jsxs43("div", { className: "ree-subject-bar", children: [
-    /* @__PURE__ */ jsx56("label", { className: "ree-subject-label", htmlFor: subjectId, children: "Email subject" }),
-    /* @__PURE__ */ jsxs43("div", { className: "ree-subject-field", children: [
-      /* @__PURE__ */ jsx56(
+  return /* @__PURE__ */ jsxs44("div", { className: "ree-subject-bar", children: [
+    /* @__PURE__ */ jsx57("label", { className: "ree-subject-label", htmlFor: subjectId, children: "Email subject" }),
+    /* @__PURE__ */ jsxs44("div", { className: "ree-subject-field", children: [
+      /* @__PURE__ */ jsx57(
         TextInput,
         {
           id: subjectId,
@@ -5668,21 +5842,21 @@ function SubjectBar({
           onChange: (event) => onSubjectChange(event.target.value)
         }
       ),
-      /* @__PURE__ */ jsxs43("span", { id: countId, className: "ree-subject-count", children: [
+      /* @__PURE__ */ jsxs44("span", { id: countId, className: "ree-subject-count", children: [
         subject.length,
         "/",
         SUBJECT_MAX_LENGTH
       ] })
     ] }),
-    variables.length > 0 ? /* @__PURE__ */ jsxs43(Fragment5, { children: [
-      /* @__PURE__ */ jsx56(PersonalizationMenu, { variables, onInsert: insertVariable }),
-      /* @__PURE__ */ jsx56("p", { className: "ree-subject-hint", children: PERSONALIZATION_HINT })
+    variables.length > 0 ? /* @__PURE__ */ jsxs44(Fragment5, { children: [
+      /* @__PURE__ */ jsx57(PersonalizationMenu, { variables, onInsert: insertVariable }),
+      /* @__PURE__ */ jsx57("p", { className: "ree-subject-hint", children: PERSONALIZATION_HINT })
     ] }) : null
   ] });
 }
 
 // src/shell/useEditorSession.ts
-import { useCallback as useCallback3, useState as useState17, useSyncExternalStore } from "react";
+import { useCallback as useCallback3, useState as useState19, useSyncExternalStore } from "react";
 
 // src/utils/id.ts
 function generateId(prefix = "block") {
@@ -5997,8 +6171,8 @@ function useEditorSession(editor) {
   const store = getEditorStore(editor);
   const { document, config, variables, resetKey } = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
   const definitions = config.definitions;
-  const [selectedId, setSelectedId] = useState17(null);
-  const [previousReset, setPreviousReset] = useState17({ editor, resetKey });
+  const [selectedId, setSelectedId] = useState19(null);
+  const [previousReset, setPreviousReset] = useState19({ editor, resetKey });
   if (previousReset.editor !== editor || previousReset.resetKey !== resetKey) {
     setPreviousReset({ editor, resetKey });
     setSelectedId(null);
@@ -6099,21 +6273,21 @@ function useEditorSession(editor) {
 }
 
 // src/shell/EmailEditorShell.tsx
-import { jsx as jsx57, jsxs as jsxs44 } from "react/jsx-runtime";
+import { jsx as jsx58, jsxs as jsxs45 } from "react/jsx-runtime";
 function EmailEditorShell({ editor, height = "100%" }) {
   var _a;
   const session = useEditorSession(editor);
-  const [activeRichText, setActiveRichText] = useState18(null);
-  const [viewMode, setViewMode] = useState18("edit");
-  const [device, setDevice] = useState18("desktop");
-  const [inspectorPanel, setInspectorPanel] = useState18("body");
-  const [previousReset, setPreviousReset] = useState18({ editor, key: session.resetKey });
+  const [activeRichText, setActiveRichText] = useState20(null);
+  const [viewMode, setViewMode] = useState20("edit");
+  const [device, setDevice] = useState20("desktop");
+  const [inspectorPanel, setInspectorPanel] = useState20("body");
+  const [previousReset, setPreviousReset] = useState20({ editor, key: session.resetKey });
   if (previousReset.editor !== editor || previousReset.key !== session.resetKey) {
     setPreviousReset({ editor, key: session.resetKey });
     setActiveRichText(null);
     setInspectorPanel("body");
   }
-  const [previousSelectedId, setPreviousSelectedId] = useState18(session.selectedId);
+  const [previousSelectedId, setPreviousSelectedId] = useState20(session.selectedId);
   if (previousSelectedId !== session.selectedId) {
     setPreviousSelectedId(session.selectedId);
     if (!session.selectedId) setInspectorPanel("body");
@@ -6137,8 +6311,8 @@ function EmailEditorShell({ editor, height = "100%" }) {
     selectBlock(null);
   };
   const showCanvas = () => setViewMode("edit");
-  return /* @__PURE__ */ jsx57(EditorConfigContext.Provider, { value: session.config, children: /* @__PURE__ */ jsx57(RichTextFocusContext.Provider, { value: { active: activeRichText, activate: setActiveRichText }, children: /* @__PURE__ */ jsxs44("div", { className: "ree-root", style: { height }, onKeyDown: handleKeyDown, children: [
-    /* @__PURE__ */ jsx57(
+  return /* @__PURE__ */ jsx58(EditorConfigContext.Provider, { value: session.config, children: /* @__PURE__ */ jsx58(RichTextFocusContext.Provider, { value: { active: activeRichText, activate: setActiveRichText }, children: /* @__PURE__ */ jsxs45("div", { className: "ree-root", style: { height }, onKeyDown: handleKeyDown, children: [
+    /* @__PURE__ */ jsx58(
       SubjectBar,
       {
         subject: (_a = session.document.subject) != null ? _a : "",
@@ -6146,8 +6320,8 @@ function EmailEditorShell({ editor, height = "100%" }) {
         onSubjectChange: session.setSubject
       }
     ),
-    /* @__PURE__ */ jsxs44("div", { className: "ree-body", children: [
-      /* @__PURE__ */ jsxs44(
+    /* @__PURE__ */ jsxs45("div", { className: "ree-body", children: [
+      /* @__PURE__ */ jsxs45(
         EditorDnd,
         {
           blocks: session.document.blocks,
@@ -6159,7 +6333,7 @@ function EmailEditorShell({ editor, height = "100%" }) {
           onReorder: session.reorderBlocks,
           onLibraryDragStart: showCanvas,
           children: [
-            /* @__PURE__ */ jsx57(
+            /* @__PURE__ */ jsx58(
               BlockLibrary,
               {
                 definitions: session.config.library,
@@ -6169,7 +6343,7 @@ function EmailEditorShell({ editor, height = "100%" }) {
                 }
               }
             ),
-            /* @__PURE__ */ jsx57(
+            /* @__PURE__ */ jsx58(
               Stage,
               {
                 session,
@@ -6183,7 +6357,7 @@ function EmailEditorShell({ editor, height = "100%" }) {
           ]
         }
       ),
-      /* @__PURE__ */ jsx57(
+      /* @__PURE__ */ jsx58(
         Inspector,
         {
           panel: inspectorPanel,
@@ -6203,23 +6377,23 @@ function EmailEditorShell({ editor, height = "100%" }) {
 }
 
 // src/EmailEditor.tsx
-import { jsx as jsx58 } from "react/jsx-runtime";
+import { jsx as jsx59 } from "react/jsx-runtime";
 function EmailEditor(props) {
-  return /* @__PURE__ */ jsx58(EmailEditorShell, __spreadValues({}, props));
+  return /* @__PURE__ */ jsx59(EmailEditorShell, __spreadValues({}, props));
 }
 
 // src/plugins/useEmailEditorConfig.ts
-import { useMemo as useMemo6 } from "react";
+import { useMemo as useMemo5 } from "react";
 function useEmailEditorConfig(options = {}) {
   const { plugins, builtins, pickImage, templateEngine } = options;
-  return useMemo6(() => buildEmailEditorConfig({ plugins, builtins, pickImage, templateEngine }), [plugins, builtins, pickImage, templateEngine]);
+  return useMemo5(() => buildEmailEditorConfig({ plugins, builtins, pickImage, templateEngine }), [plugins, builtins, pickImage, templateEngine]);
 }
 
 // src/shell/useEmailEditor.ts
-import { useEffect as useEffect8, useInsertionEffect, useLayoutEffect as useLayoutEffect9, useState as useState19 } from "react";
-var useOptionsEffect = typeof window === "undefined" ? useEffect8 : useLayoutEffect9;
+import { useEffect as useEffect8, useInsertionEffect, useLayoutEffect as useLayoutEffect11, useState as useState21 } from "react";
+var useOptionsEffect = typeof window === "undefined" ? useEffect8 : useLayoutEffect11;
 function useEmailEditor(options = {}) {
-  const [store] = useState19(() => createEditorStore(options));
+  const [store] = useState21(() => createEditorStore(options));
   useInsertionEffect(() => {
     store.updateOptions(options);
   });
@@ -6235,12 +6409,12 @@ function useEmailEditorState(editor) {
 }
 
 // src/plugins/components/ControlEditor.tsx
-import { jsx as jsx59 } from "react/jsx-runtime";
+import { jsx as jsx60 } from "react/jsx-runtime";
 function ControlEditor({ control }) {
   const context = usePluginEditor();
   const definition = context.controlDefinitions.find((item) => item.name === control);
   if (!definition) throw new Error(`Unknown plugin control: ${control}`);
-  return /* @__PURE__ */ jsx59(ControlRenderer, { control: definition, value: context.controls[control], body: context.body, variables: context.variables, onChange: (value) => context.setControl(control, value) });
+  return /* @__PURE__ */ jsx60(ControlRenderer, { control: definition, value: context.controls[control], body: context.body, variables: context.variables, onChange: (value) => context.setControl(control, value) });
 }
 export {
   BLOCK_TYPES,

package/dist/styles.css

@@ -1007,6 +1007,38 @@
 
 /* ---------- 画布 ---------- */
 
+.ree-stage-content,
+.ree-preview-buffer {
+  position: relative;
+  display: flex;
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  isolation: isolate;
+}
+
+.ree-stage-view.is-buffered,
+.ree-preview-stage.is-buffered {
+  position: absolute;
+  inset: 0;
+  visibility: hidden;
+  pointer-events: none;
+}
+
+.ree-preview-pending {
+  position: absolute;
+  top: 12px;
+  left: 50%;
+  transform: translateX(-50%);
+  padding: 6px 12px;
+  border: 1px solid var(--ree-border);
+  border-radius: 6px;
+  background: var(--ree-panel);
+  color: var(--ree-muted);
+  font-size: 12px;
+  pointer-events: none;
+}
+
 .ree-stage-view {
   display: flex;
   flex: 1;
@@ -1090,6 +1122,18 @@
   box-shadow: var(--ree-shadow-md);
 }
 
+.ree-preview-error {
+  position: absolute;
+  top: 12px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 1;
+  max-width: calc(100% - 24px);
+  border: 1px solid var(--ree-border);
+  border-radius: 6px;
+  background: var(--ree-panel);
+}
+
 /* ---------- 区块 ---------- */
 
 .ree-block {

package/docs/changelog.md

@@ -2,6 +2,22 @@
 
 English | [简体中文](./changelog.zh-CN.md)
 
+## 0.5.2 — 2026-10-29
+
+### Fixes and improvements
+
+- Fix canvas recreation and flicker when switching between editing and preview. Keep the editing canvas mounted and swap two iframe buffers after standby loading and height measurement, preserving separate editing and preview scroll positions. Exclude the hidden canvas from focus, keyboard and drag interactions while previewing.
+- Debounce document, configuration, variable and device-width changes for 400ms with a maximum wait of 2 seconds and idle scheduling support. Process Preview and Retry clicks immediately while continuing to debounce subsequent changes in preview mode. Reuse ready or loading buffers with identical HTML and width to avoid remounts.
+- Use `sandbox="allow-same-origin"` on preview iframes to block scripts and event handlers while retaining height measurement. Preserve exported HTML; this restriction is not complete HTML sanitization.
+- Handle generation, load and measurement errors, including a 15-second load/measurement timeout, with error messages and Retry. Retain existing previews on failure and force a new load on retry. Prevent callbacks from stale, replaced or failed buffers from overwriting current content, and clean up timers, observers, listeners and animation frames on unmount.
+- Update both template-engine guides. Bump the npm package from `0.5.1` to `0.5.2` as a patch, preserving the public API, email export and persisted document format. Preview no longer executes scripts in email HTML; custom engines and `renderEmail` should be pure and allow repeated background calls.
+
+### Validation
+
+- `npm run check` passes type checking, Oxlint, the build and all 144 Node tests, covering debounce, maximum wait, buffer reuse, stale callbacks, timeouts, exceptions, retry and cleanup.
+- Reuse the existing Chrome page to verify blocked scripts and event handlers, unchanged iframe nodes after subject-only edits, one load for five consecutive changes in preview mode, and a 15-second timeout that retains the old preview and recovers through Retry.
+- Verify desktop 600px and mobile 360px previews and five consecutive editing/preview round trips. Canvas, rich-text and iframe nodes remain mounted, with no visible blank or unmeasured frame in sampled states. Restore the test document and remove temporary probes. `git diff --check` passes.
+
 ## 0.5.1 — 2026-10-29
 
 ### Fixes and improvements

package/docs/changelog.zh-CN.md

@@ -2,6 +2,22 @@
 
 [English](./changelog.md) | 简体中文
 
+## 0.5.2 — 2026-10-29
+
+### 修复与改进
+
+- 修复编辑与预览切换时画布重建和闪动：编辑画布常驻，两个 iframe 在备用层完成加载与高度测量后交换显示，分别保留编辑区和预览区的滚动位置；预览时禁用隐藏画布的焦点、键盘和拖拽交互。
+- 文档、配置、变量和设备宽度变化使用 400ms 防抖与最长 2 秒等待，支持空闲调度；点击 Preview 或 Retry 立即处理，预览模式中的后续修改仍防抖。HTML 和宽度一致时复用已就绪或正在加载的缓冲，避免重复挂载。
+- 预览 iframe 使用 `sandbox="allow-same-origin"` 阻止脚本和事件属性执行，保持高度测量能力；导出 HTML 保持原有内容，此约束不等同于完整 HTML 消毒。
+- 补齐生成、加载和测量错误，以及 15 秒加载测量超时提示与 Retry。已有预览在失败时继续显示，重试强制新加载；过期、被替换或已失败缓冲的回调不能覆盖当前内容，卸载时清理计时器、观察器、监听器和动画帧。
+- 同步中英文模板引擎文档。本次按 patch 将 npm 包版本从 `0.5.1` 升至 `0.5.2`，公开 API、邮件导出与持久化文档格式不变；预览不再执行邮件 HTML 中的脚本，自定义引擎与 `renderEmail` 应允许后台重复调用并保持纯函数。
+
+### 验证
+
+- `npm run check` 通过类型检查、Oxlint、构建与全部 144 项 Node 测试，覆盖防抖、最长等待、缓冲复用、过期回调、超时、异常、重试与清理。
+- 复用现有 Chrome 页面验证脚本和事件属性被阻止、仅修改主题时 iframe 节点不变、预览内连续 5 次修改只加载 1 次，以及 15 秒超时保留旧预览并在 Retry 后恢复。
+- 验证桌面 600px 与移动 360px 预览及连续五轮编辑/预览切换，画布、富文本和 iframe 节点保持不变，采样未出现可见空白或未测量帧；测试文档已还原，临时探针已清理。`git diff --check` 通过。
+
 ## 0.5.1 — 2026-10-29
 
 ### 修复与改进

package/docs/template-engines.md

@@ -36,6 +36,14 @@ Field names support Unicode letters, digits and underscores, starting with a let
 
 Functions (including `eq/ne/and/or/not/len/index/printf/html`), pipelines, parentheses, local variables, template definitions/calls, comments and other full Go features require an external engine. Unsupported syntax or incomplete control structures preserve the **entire input for that render**, without partial evaluation. In the editor this preserves that block's HTML template.
 
+## Switching between editing and preview
+
+The editing canvas stays mounted, so switching modes preserves rich-text editors and HTML block iframes. Editing and preview retain their own scroll positions. While preview is requested, the canvas is excluded from focus, keyboard and drag interactions, and rich-text toolbars are hidden.
+
+Changes to the document, configuration, variables or device width schedule a complete email preview after a 400ms debounce, using an idle callback with a maximum wait of 2 seconds during continuous changes. Browsers without `requestIdleCallback` use a timer. Clicking Preview or Retry bypasses the wait and prepares the latest revision; subsequent changes in preview mode still use the same debounce. HTML generation still runs synchronously on the main thread; custom engines and `renderEmail` should be pure and allow repeated background calls.
+
+Two iframe buffers keep loading and measurement in the standby layer. A buffer becomes visible only after it has loaded and its height has been measured. Until the latest revision is ready, the current view remains visible with a preparation status. Stale revisions cannot replace newer content. Identical HTML and width reuse a ready or loading buffer to avoid unnecessary reloads. Generation, load or measurement failures, including a 15-second load/measurement timeout, show an error and Retry while retaining any existing preview. Retry forces a new load. Preview iframes use `sandbox="allow-same-origin"` to block scripts and event handlers while allowing the host to measure height; this is not complete HTML sanitization and does not rewrite exported HTML. This cache only serves the UI; explicit export APIs synchronously generate from the latest document at call time.
+
 ## Integration example
 
 Wrap your template library as TemplateEngine and pass the same adapter to editing and standalone preview. The caller provides templateEngine in this example:

package/docs/template-engines.zh-CN.md

@@ -36,6 +36,14 @@ interface TemplateEngineOptions {
 
 默认引擎不支持函数调用（含 `eq/ne/and/or/not/len/index/printf/html`）、管道、括号表达式、局部变量、模板定义/调用、注释和其他完整 Go 语法。输入包含不支持的语法或不完整的控制结构时，**保留该次渲染的完整输入，不执行部分替换**；编辑器中意味着保留对应区块的 HTML 模板。需要完整 Go 兼容性时接入外部引擎。
 
+## 编辑与预览切换
+
+编辑画布保持挂载，切换预览不会重建富文本编辑器或 HTML 区块 iframe。编辑区与预览区分别保留滚动位置；预览时编辑画布不参与焦点、键盘和拖拽交互，富文本工具栏也会隐藏。
+
+文档、配置、变量或设备宽度变化后，完整邮件预览在停止修改 400ms 后排入空闲任务，连续修改时最长等待 2 秒；不支持 `requestIdleCallback` 时使用定时器。点击 Preview 或 Retry 会跳过等待并准备最新版本；进入预览后的后续修改仍使用相同防抖规则。HTML 生成仍在主线程同步执行，自定义引擎和 `renderEmail` 应保持纯函数，允许后台重复调用。
+
+预览使用两个 iframe 缓冲：最新内容在备用层加载并测量高度，完成后才交换显示。首次预览或最新内容尚未就绪时保留当前画面并显示准备提示；过期版本不会覆盖新内容。HTML 和宽度相同时复用已就绪或正在加载的缓冲，避免无意义重载。生成、加载或测量失败，以及加载测量超过 15 秒时显示错误和 Retry；已有预览仍保留，Retry 强制创建新加载。预览 iframe 使用 `sandbox="allow-same-origin"`，阻止脚本及事件属性执行，同时允许宿主测量高度；这不等同于完整 HTML 消毒，也不改写导出的 HTML。预览缓存仅服务于界面，显式导出 API 仍按调用时的最新文档同步生成。
+
 ## 接入示例
 
 业务侧把实际模板库封装为 `TemplateEngine`，再把同一个适配器用于编辑器和独立预览。下面示例的 `templateEngine` 由调用方提供：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standhigher/react-email-editor",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "type": "module",
   "description": "React email template editor with drag-and-drop blocks, rich text, JSON storage, and HTML export.",
   "keywords": [