@standhigher/react-email-editor 0.4.1 → 0.4.3

package/README.md

@@ -1,14 +1,14 @@
 # @standhigher/react-email-editor
 
-English | [简体中文](./README.zh-CN.md)
+English | [简体中文](https://github.com/standhigher/react-email-editor/blob/main/README.zh-CN.md)
 
 Drag content onto a canvas, style your email, preview it, then save editable JSON or export email HTML.
 
 ## Modules and features
 
-![Project modules and features](./docs/assets/architecture.png)
+![Project modules and features](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.png)
 
-[Open full-size architecture diagram](./docs/assets/architecture.png) · [Editable SVG](./docs/assets/architecture.svg)
+[Open full-size architecture diagram](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.png) · [Editable SVG](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.svg)
 
 ## Install and integrate
 
@@ -32,21 +32,22 @@ With Next.js App Router, add `"use client"` to the integration component and imp
 
 ## Run locally
 
-Use a supported Node.js LTS release (at least 22.18 for the complete test suite) and pnpm:
+Use Node.js 24 LTS (`.nvmrc`; at least 22.18 for the complete test suite) and pnpm 10.16.1 (`packageManager`):
 
 ```bash
 pnpm install --frozen-lockfile
 pnpm dev
 ```
 
-Open [http://localhost:5173](http://localhost:5173); reuse an existing server when available. See [development and local linking](./docs/api.md#development-and-local-linking) for build and validation commands.
+Open [http://localhost:5173](http://localhost:5173); reuse an existing server when available. See [development and local linking](https://github.com/standhigher/react-email-editor/blob/main/docs/api.md#development-and-local-linking) for build and validation commands.
 
 ## Documentation
 
-- [API reference](./docs/api.md): every public export, parameter, default and type.
-- [Basic examples](./docs/basic-examples.md): initial content, saving/loading, body styles, variables and preview.
-- [Advanced examples](./docs/advanced-examples.md): validated saving, multiple instances, custom blocks, multiple editing regions, resource adapters and standalone export.
-- [Custom block guide](./docs/custom-blocks.md): detailed controls, plugins and rendering helpers.
-- [Changelog](./CHANGELOG.md).
+- [API reference](https://github.com/standhigher/react-email-editor/blob/main/docs/api.md): every public export, parameter, default and type.
+- [Basic examples](https://github.com/standhigher/react-email-editor/blob/main/docs/basic-examples.md): initial content, saving/loading, body styles, variables and preview.
+- [Advanced examples](https://github.com/standhigher/react-email-editor/blob/main/docs/advanced-examples.md): validated saving, multiple instances, custom blocks, multiple editing regions, resource adapters and standalone export.
+- [Custom block guide](https://github.com/standhigher/react-email-editor/blob/main/docs/custom-blocks.md): detailed controls, plugins and rendering helpers.
+- [Release guide](https://github.com/standhigher/react-email-editor/blob/main/docs/release.md): package checks and manual npm publishing.
+- [Changelog](https://github.com/standhigher/react-email-editor/blob/main/docs/changelog.md).
 
 The document format is under development. Only `version: 4` is supported, without automatic migration of older documents.

package/README.zh-CN.md

@@ -1,14 +1,14 @@
 # @standhigher/react-email-editor
 
-[English](./README.md) | 简体中文
+[English](https://github.com/standhigher/react-email-editor/blob/main/README.md) | 简体中文
 
 把内容拖进画布，调整邮件外观，预览后保存为可继续编辑的 JSON 或导出邮件 HTML。
 
 ## 模块架构图
 
-![项目模块架构图：8 个模块及对应功能](./docs/assets/architecture.zh-CN.png)
+![项目模块架构图：8 个模块及对应功能](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.zh-CN.png)
 
-[查看高清架构图](./docs/assets/architecture.zh-CN.png) · [可编辑 SVG](./docs/assets/architecture.zh-CN.svg)
+[查看高清架构图](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.zh-CN.png) · [可编辑 SVG](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.zh-CN.svg)
 
 ## 安装与最小接入
 
@@ -32,21 +32,22 @@ Next.js App Router 的接入组件需声明 `"use client"`；样式在应用允
 
 ## 本地启动
 
-使用依赖支持的 Node.js LTS（运行全部测试至少需要 22.18）和 pnpm：
+推荐 Node.js 24 LTS（`.nvmrc`；完整测试最低需要 22.18）和 pnpm 10.16.1（`packageManager`）：
 
 ```bash
 pnpm install --frozen-lockfile
 pnpm dev
 ```
 
-打开 [http://localhost:5173](http://localhost:5173)，已有服务时优先复用。构建与校验命令见 [API 文档的开发说明](./docs/api.zh-CN.md#开发与本地联调)。
+打开 [http://localhost:5173](http://localhost:5173)，已有服务时优先复用。构建与校验命令见 [API 文档的开发说明](https://github.com/standhigher/react-email-editor/blob/main/docs/api.zh-CN.md#开发与本地联调)。
 
 ## 文档
 
-- [API 参考](./docs/api.zh-CN.md)：所有公共导出、参数、默认值与类型。
-- [基础场景](./docs/basic-examples.zh-CN.md)：初始内容、保存恢复、主体样式、变量及预览。
-- [复杂场景](./docs/advanced-examples.zh-CN.md)：校验后保存、多实例、自定义区块、多区域编辑、资源适配与独立导出。
-- [自定义区块指南](./docs/custom-blocks.zh-CN.md)：控件、插件和渲染工具的完整说明。
-- [更新记录](./CHANGELOG.md)。
+- [API 参考](https://github.com/standhigher/react-email-editor/blob/main/docs/api.zh-CN.md)：所有公共导出、参数、默认值与类型。
+- [基础场景](https://github.com/standhigher/react-email-editor/blob/main/docs/basic-examples.zh-CN.md)：初始内容、保存恢复、主体样式、变量及预览。
+- [复杂场景](https://github.com/standhigher/react-email-editor/blob/main/docs/advanced-examples.zh-CN.md)：校验后保存、多实例、自定义区块、多区域编辑、资源适配与独立导出。
+- [自定义区块指南](https://github.com/standhigher/react-email-editor/blob/main/docs/custom-blocks.zh-CN.md)：控件、插件和渲染工具的完整说明。
+- [发布指南](https://github.com/standhigher/react-email-editor/blob/main/docs/release.zh-CN.md)：发布包校验与本地手动发布。
+- [更新记录](https://github.com/standhigher/react-email-editor/blob/main/docs/changelog.zh-CN.md)。
 
 文档格式仍处于开发阶段，当前只支持 `version: 4`，不自动迁移旧版文档。

package/dist/index.js

@@ -3840,7 +3840,7 @@ function buildRenderContext(node, mode, body = DEFAULT_EMAIL_BODY, definition =
 }
 
 // src/inspector/InspectorControls.tsx
-import { useId as useId10 } from "react";
+import { useId as useId11 } from "react";
 
 // src/constants/style-groups.ts
 var STYLE_GROUPS = [
@@ -3885,7 +3885,7 @@ function inheritedStyleValue(id, body) {
 }
 
 // src/inspector/components/BasicControl.tsx
-import { useRef as useRef9, useId as useId6 } from "react";
+import { useRef as useRef10, useId as useId7 } from "react";
 
 // src/inspector/HtmlCodeEditor.tsx
 import { useEffect as useEffect4, useLayoutEffect as useLayoutEffect6, useRef as useRef8 } from "react";
@@ -4079,41 +4079,147 @@ function HtmlCodeEditor({
   );
 }
 
-// src/inspector/VariablesDropdown.tsx
-import { useState as useState12 } from "react";
+// src/components/PersonalizationMenu.tsx
+import { useId as useId6, useRef as useRef9, useState as useState13 } from "react";
+import { createPortal as createPortal2 } from "react-dom";
+
+// src/components/usePersonalizationMenu.ts
+import { useLayoutEffect as useLayoutEffect7, useState as useState12 } from "react";
+function usePersonalizationMenu(open, rootRef, menuRef, focusOnOpen, setOpen) {
+  const [position, setPosition] = useState12({ left: 0, top: 0, maxHeight: 240 });
+  useLayoutEffect7(() => {
+    var _a;
+    const root = rootRef.current;
+    const menu = menuRef.current;
+    if (!open || !root || !menu) return;
+    const ownerDocument = root.ownerDocument;
+    const ownerWindow = ownerDocument.defaultView;
+    if (!ownerWindow) return;
+    const place = () => {
+      var _a2, _b;
+      const anchor = root.getBoundingClientRect();
+      const inputBounds = (_b = (_a2 = root.closest(".ree-input-with-variable")) == null ? void 0 : _a2.getBoundingClientRect()) != null ? _b : anchor;
+      const width = menu.offsetWidth;
+      const height = Math.min(menu.scrollHeight + 2, 240);
+      const below = Math.max(0, ownerWindow.innerHeight - inputBounds.bottom - 8);
+      const above = Math.max(0, inputBounds.top - 8);
+      const up = below < height && above > below;
+      const maxHeight = Math.min(240, up ? above : below);
+      const left = anchor.left + width > ownerWindow.innerWidth - 8 ? anchor.right - width : anchor.left;
+      setPosition({
+        left: Math.max(8, Math.min(left, ownerWindow.innerWidth - width - 8)),
+        top: up ? inputBounds.top - Math.min(height, maxHeight) : inputBounds.bottom,
+        maxHeight
+      });
+    };
+    const onPointerDown = (event) => {
+      if (!root.contains(event.target) && !menu.contains(event.target)) setOpen(false);
+    };
+    const onKeyDown = (event) => {
+      var _a2, _b;
+      const target = event.target;
+      if (!root.contains(target) && !menu.contains(target)) return;
+      if (event.key === "Tab" && menu.contains(target)) {
+        const buttons = menu.querySelectorAll("button");
+        if (target !== (event.shiftKey ? buttons[0] : buttons[buttons.length - 1])) return;
+        if (event.shiftKey) event.preventDefault();
+        setOpen(false);
+        (_a2 = root.querySelector("button")) == null ? void 0 : _a2.focus({ preventScroll: true });
+        return;
+      }
+      if (event.key !== "Escape") return;
+      event.preventDefault();
+      event.stopPropagation();
+      setOpen(false);
+      (_b = root.querySelector("button")) == null ? void 0 : _b.focus({ preventScroll: true });
+    };
+    menu.setAttribute("popover", "manual");
+    menu.showPopover();
+    place();
+    if (focusOnOpen.current) (_a = menu.querySelector("button")) == null ? void 0 : _a.focus({ preventScroll: true });
+    const observer = new ResizeObserver(place);
+    observer.observe(root);
+    observer.observe(menu);
+    ownerWindow.addEventListener("resize", place);
+    ownerDocument.addEventListener("scroll", place, true);
+    ownerDocument.addEventListener("pointerdown", onPointerDown, true);
+    ownerDocument.addEventListener("keydown", onKeyDown, true);
+    return () => {
+      menu.hidePopover();
+      observer.disconnect();
+      ownerWindow.removeEventListener("resize", place);
+      ownerDocument.removeEventListener("scroll", place, true);
+      ownerDocument.removeEventListener("pointerdown", onPointerDown, true);
+      ownerDocument.removeEventListener("keydown", onKeyDown, true);
+    };
+  }, [open, rootRef, menuRef, focusOnOpen, setOpen]);
+  return position;
+}
+
+// src/components/PersonalizationMenu.tsx
 import { jsx as jsx40, jsxs as jsxs29 } from "react/jsx-runtime";
-function VariablesDropdown({ variables, onInsert }) {
-  const [open, setOpen] = useState12(false);
+function PersonalizationMenu({
+  variables,
+  onInsert,
+  suffix = false
+}) {
+  const [open, setOpen] = useState13(false);
+  const [host, setHost] = useState13(null);
+  const id = useId6();
+  const rootRef = useRef9(null);
+  const menuRef = useRef9(null);
+  const focusOnOpen = useRef9(false);
+  const position = usePersonalizationMenu(open && variables.length > 0, rootRef, menuRef, focusOnOpen, setOpen);
   if (variables.length === 0) return null;
-  return /* @__PURE__ */ jsxs29("div", { className: "ree-var-wrap", children: [
-    /* @__PURE__ */ jsx40(
+  return /* @__PURE__ */ jsxs29("div", { className: suffix ? "ree-personalization ree-personalization-suffix" : "ree-personalization", ref: rootRef, children: [
+    /* @__PURE__ */ jsxs29(
       "button",
       {
         type: "button",
-        className: "ree-var-btn",
-        onClick: () => setOpen((current) => !current),
-        title: "Insert variable",
-        "aria-label": "Insert variable",
+        className: suffix ? "ree-personalization-suffix-btn" : "ree-personalization-btn",
+        "aria-label": suffix ? "Insert variable" : void 0,
+        title: suffix ? "Personalization" : void 0,
         "aria-expanded": open,
-        children: "{ }"
-      }
-    ),
-    open ? /* @__PURE__ */ jsx40("div", { className: "ree-var-menu", children: variables.map((variable) => /* @__PURE__ */ jsxs29(
-      "button",
-      {
-        type: "button",
-        className: "ree-var-item",
-        onClick: () => {
-          onInsert(variable.name);
-          setOpen(false);
+        "aria-controls": open ? id : void 0,
+        onClick: (event) => {
+          var _a;
+          focusOnOpen.current = event.detail === 0;
+          const root = rootRef.current;
+          if (root) setHost((_a = root.closest(".ree-root")) != null ? _a : root.ownerDocument.body);
+          setOpen((current) => !current);
+        },
+        onKeyDown: (event) => {
+          var _a, _b;
+          if (event.key === "Tab" && open && !event.shiftKey) {
+            event.preventDefault();
+            (_b = (_a = menuRef.current) == null ? void 0 : _a.querySelector("button")) == null ? void 0 : _b.focus();
+          }
         },
         children: [
-          /* @__PURE__ */ jsx40("span", { className: "ree-var-name", children: variable.name }),
-          variable.description ? /* @__PURE__ */ jsx40("span", { className: "ree-var-label", children: variable.description }) : null
+          suffix ? "{ }" : "Personalization",
+          suffix ? null : /* @__PURE__ */ jsx40("svg", { viewBox: "0 0 20 20", width: "16", height: "16", fill: "currentColor", "aria-hidden": "true", children: /* @__PURE__ */ jsx40("path", { d: "M5.2 7.5 10 12.3l4.8-4.8 1.2 1.2L10 14.7 4 8.7l1.2-1.2Z" }) })
         ]
-      },
-      variable.name
-    )) }) : null
+      }
+    ),
+    open && host ? createPortal2(
+      /* @__PURE__ */ jsx40("div", { id, ref: menuRef, className: "ree-var-menu ree-personalization-menu", style: position, children: variables.map((variable) => /* @__PURE__ */ jsxs29(
+        "button",
+        {
+          type: "button",
+          className: "ree-var-item",
+          onClick: () => {
+            onInsert(variable.name);
+            setOpen(false);
+          },
+          children: [
+            /* @__PURE__ */ jsx40("span", { className: "ree-var-name", children: variable.name }),
+            variable.description ? /* @__PURE__ */ jsx40("span", { className: "ree-var-label", children: variable.description }) : null
+          ]
+        },
+        variable.name
+      )) }),
+      host
+    ) : null
   ] });
 }
 
@@ -4121,8 +4227,8 @@ function VariablesDropdown({ variables, onInsert }) {
 import { jsx as jsx41, jsxs as jsxs30 } from "react/jsx-runtime";
 function BasicControl({ control, value, variables, onChange }) {
   var _a, _b, _c, _d, _e;
-  const ref = useRef9(null);
-  const id = useId6();
+  const ref = useRef10(null);
+  const id = useId7();
   const shown = value == null || typeof value === "number" && !Number.isFinite(value) ? "" : String(value);
   const insertVariable = (token) => {
     var _a2, _b2;
@@ -4130,6 +4236,11 @@ function BasicControl({ control, value, variables, onChange }) {
     const start = (_a2 = element == null ? void 0 : element.selectionStart) != null ? _a2 : shown.length;
     const end = (_b2 = element == null ? void 0 : element.selectionEnd) != null ? _b2 : shown.length;
     onChange(shown.slice(0, start) + token + shown.slice(end));
+    requestAnimationFrame(() => {
+      var _a3, _b3;
+      (_a3 = ref.current) == null ? void 0 : _a3.focus();
+      (_b3 = ref.current) == null ? void 0 : _b3.setSelectionRange(start + token.length, start + token.length);
+    });
   };
   if (control.kind === "boolean") return /* @__PURE__ */ jsx41(CheckboxControl, { label: control.label, checked: Boolean(value), onChange });
   if (control.kind === "color") return /* @__PURE__ */ jsx41(ColorControl, { label: control.label, value: shown, resetTo: String((_a = control.defaultValue) != null ? _a : ""), onChange });
@@ -4138,30 +4249,32 @@ function BasicControl({ control, value, variables, onChange }) {
     /* @__PURE__ */ jsx41(HtmlCodeEditor, { value: shown, placeholder: control.placeholder, rows: control.rows, onChange })
   ] });
   const textual = control.kind === "text" || control.kind === "textarea" || control.kind === "url";
+  const hasVariables = textual && variables.length > 0;
   const invalidUrl = control.kind === "url" && shown.trim() && !safeEmailUrl(shown);
+  const input = control.kind === "select" ? /* @__PURE__ */ jsx41(SelectControl, { id, label: control.label, value: shown, options: (_b = control.options) != null ? _b : [], emptyLabel: (_c = control.placeholder) != null ? _c : "None", onChange }) : control.kind === "textarea" ? /* @__PURE__ */ jsx41("textarea", { id, ref: (element) => {
+    ref.current = element;
+  }, className: "ree-input ree-textarea", value: shown, placeholder: control.placeholder, rows: (_d = control.rows) != null ? _d : 4, onChange: (event) => onChange(event.target.value) }) : /* @__PURE__ */ jsx41(TextInput, { id, ref: (element) => {
+    ref.current = element;
+  }, type: control.kind === "number" ? "number" : "text", value: shown, min: control.min, max: control.max, step: control.step, placeholder: control.placeholder, "aria-invalid": Boolean(invalidUrl) || Boolean((_e = control.validateValue) == null ? void 0 : _e.call(control, value)), onChange: (event) => onChange(control.kind === "number" && event.target.value !== "" ? Number(event.target.value) : event.target.value) });
   return /* @__PURE__ */ jsxs30("div", { className: "ree-field", children: [
-    /* @__PURE__ */ jsxs30("div", { className: "ree-field-label", children: [
-      /* @__PURE__ */ jsxs30("label", { htmlFor: id, children: [
-        control.label,
-        control.unit ? ` (${control.unit})` : ""
-      ] }),
-      textual ? /* @__PURE__ */ jsx41(VariablesDropdown, { variables, onInsert: insertVariable }) : null
-    ] }),
-    control.kind === "select" ? /* @__PURE__ */ jsx41(SelectControl, { id, label: control.label, value: shown, options: (_b = control.options) != null ? _b : [], emptyLabel: (_c = control.placeholder) != null ? _c : "None", onChange }) : control.kind === "textarea" ? /* @__PURE__ */ jsx41("textarea", { id, ref: (element) => {
-      ref.current = element;
-    }, className: "ree-input ree-textarea", value: shown, placeholder: control.placeholder, rows: (_d = control.rows) != null ? _d : 4, onChange: (event) => onChange(event.target.value) }) : /* @__PURE__ */ jsx41(TextInput, { id, ref: (element) => {
-      ref.current = element;
-    }, type: control.kind === "number" ? "number" : "text", value: shown, min: control.min, max: control.max, step: control.step, placeholder: control.placeholder, "aria-invalid": Boolean(invalidUrl) || Boolean((_e = control.validateValue) == null ? void 0 : _e.call(control, value)), onChange: (event) => onChange(control.kind === "number" && event.target.value !== "" ? Number(event.target.value) : event.target.value) })
+    /* @__PURE__ */ jsx41("div", { className: "ree-field-label", children: /* @__PURE__ */ jsxs30("label", { htmlFor: id, children: [
+      control.label,
+      control.unit ? ` (${control.unit})` : ""
+    ] }) }),
+    hasVariables ? /* @__PURE__ */ jsxs30("div", { className: "ree-input-with-variable", children: [
+      input,
+      /* @__PURE__ */ jsx41(PersonalizationMenu, { suffix: true, variables, onInsert: insertVariable })
+    ] }) : input
   ] });
 }
 
 // src/inspector/components/ListControl.tsx
-import { useId as useId7 } from "react";
+import { useId as useId8 } from "react";
 
 // src/inspector/components/useListRows.ts
-import { useLayoutEffect as useLayoutEffect7, useRef as useRef10, useState as useState13 } from "react";
+import { useLayoutEffect as useLayoutEffect8, useRef as useRef11, useState as useState14 } from "react";
 function useListRows(value, onChange) {
-  const [state, setState] = useState13({ source: void 0, rows: [], nextKey: 0 });
+  const [state, setState] = useState14({ source: void 0, rows: [], nextKey: 0 });
   if (state.source !== value) {
     const available = [...state.rows];
     let nextKey = state.nextKey;
@@ -4173,8 +4286,8 @@ function useListRows(value, onChange) {
     });
     setState({ source: value, rows, nextKey });
   }
-  const latest = useRef10(state);
-  useLayoutEffect7(() => {
+  const latest = useRef11(state);
+  useLayoutEffect8(() => {
     latest.current = state;
     return () => {
       latest.current = null;
@@ -4219,7 +4332,7 @@ import { jsx as jsx42, jsxs as jsxs31 } from "react/jsx-runtime";
 function ListControl(_a) {
   var _b = _a, { control, value, onChange } = _b, props = __objRest(_b, ["control", "value", "onChange"]);
   var _a2;
-  const id = useId7();
+  const id = useId8();
   const schema = (_a2 = control.itemControls) != null ? _a2 : {};
   const { rows, updateRow, moveRow, removeRow, addRow } = useListRows(value, onChange);
   return /* @__PURE__ */ jsxs31("fieldset", { className: "ree-plugin-list", children: [
@@ -4239,15 +4352,15 @@ function ListControl(_a) {
 }
 
 // src/inspector/components/ImageControl.tsx
-import { useContext as useContext4, useEffect as useEffect5, useId as useId8, useRef as useRef11, useState as useState14 } from "react";
+import { useContext as useContext4, useEffect as useEffect5, useId as useId9, useRef as useRef12, useState as useState15 } from "react";
 import { jsx as jsx43, jsxs as jsxs32 } from "react/jsx-runtime";
 function ImageControl({ control, value, onChange }) {
   var _a;
   const config = useContext4(EditorConfigContext);
-  const controller = useRef11(null);
-  const id = useId8();
-  const [loading, setLoading] = useState14(false);
-  const [error, setError] = useState14("");
+  const controller = useRef12(null);
+  const id = useId9();
+  const [loading, setLoading] = useState15(false);
+  const [error, setError] = useState15("");
   const shown = String(value != null ? value : "");
   const url = safeEmailUrl(shown, true);
   useEffect5(() => () => {
@@ -4284,12 +4397,12 @@ function ImageControl({ control, value, onChange }) {
 }
 
 // src/inspector/components/RichTextControl.tsx
-import { useContext as useContext5, useId as useId9 } from "react";
+import { useContext as useContext5, useId as useId10 } from "react";
 import { jsx as jsx44, jsxs as jsxs33 } from "react/jsx-runtime";
 function RichTextControl({ control, value, variables, body, onChange }) {
   var _a, _b;
   const parent = useContext5(PluginEditorContext);
-  const id = useId9();
+  const id = useId10();
   const context = {
     block: (_a = parent == null ? void 0 : parent.block) != null ? _a : { id, type: "control", controls: {} },
     controls: { [control.name]: value },
@@ -4347,7 +4460,7 @@ function InspectorControls({
   onCommitStyle
 }) {
   var _a, _b, _c, _d, _e;
-  const toolbarId = useId10();
+  const toolbarId = useId11();
   const contentControls = ((_a = definition.controls) != null ? _a : []).filter((control) => control.name !== definition.inlineControl);
   const CustomInspector = definition.inspector;
   const context = buildRenderContext(block, "canvas", body, definition);
@@ -4499,7 +4612,7 @@ function viewportWidth(device, body) {
 }
 
 // src/stage/canvas/CanvasBlock.tsx
-import { useId as useId12, useMemo as useMemo3, useState as useState15 } from "react";
+import { useId as useId13, useMemo as useMemo3, useState as useState16 } from "react";
 import { useSortable } from "@dnd-kit/sortable";
 import { CSS } from "@dnd-kit/utilities";
 
@@ -4753,7 +4866,7 @@ function blockToHtml(node, definitions = DEFAULT_BLOCKS, mode = "email", options
 }
 
 // src/stage/canvas/components/HtmlCanvas.tsx
-import { useCallback, useEffect as useEffect6, useRef as useRef12 } from "react";
+import { useCallback, useEffect as useEffect6, useRef as useRef13 } from "react";
 
 // src/render/head-styles.ts
 function extractHeadStyles(html) {
@@ -4774,9 +4887,9 @@ function frameHtml(html, baseCss) {
 }
 function HtmlCanvas({ html, baseCss = "", onSelect }) {
   const hasHtmlTag = /<\/?[a-z][\w:-]*(?:\s[^>]*)?>/i.test(html);
-  const containerRef = useRef12(null);
-  const frameRef = useRef12(null);
-  const cleanupRef = useRef12();
+  const containerRef = useRef13(null);
+  const frameRef = useRef13(null);
+  const cleanupRef = useRef13();
   const observeContent = useCallback(() => {
     var _a;
     (_a = cleanupRef.current) == null ? void 0 : _a.call(cleanupRef);
@@ -4897,7 +5010,7 @@ function PluginCanvasContent({ block, body, definition, variables, selected, too
 }
 
 // src/stage/canvas/components/BlockActions.tsx
-import { useId as useId11 } from "react";
+import { useId as useId12 } from "react";
 import { jsx as jsx50, jsxs as jsxs39 } from "react/jsx-runtime";
 function BlockActions({
   inlineEdit,
@@ -4907,7 +5020,7 @@ function BlockActions({
   onDuplicate,
   onRemove
 }) {
-  const tooltipId = useId11();
+  const tooltipId = useId12();
   const toggleLabel = toolbarCollapsed ? "Expand Toolbar" : "Collapse Toolbar";
   return /* @__PURE__ */ jsxs39(
     "div",
@@ -5003,8 +5116,8 @@ function CanvasBlock({
 }) {
   var _a, _b, _c;
   const block = useMemo3(() => __spreadProps(__spreadValues({}, sourceBlock), { style: resolveBlockStyle(sourceBlock.style, definition) }), [sourceBlock, definition]);
-  const toolbarId = useId12();
-  const [toolbarCollapsed, setToolbarCollapsed] = useState15(false);
+  const toolbarId = useId13();
+  const [toolbarCollapsed, setToolbarCollapsed] = useState16(false);
   const dragData = { kind: "canvas" };
   const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id: block.id, data: dragData });
   const select = (event) => {
@@ -5171,7 +5284,7 @@ function Canvas({
 }
 
 // src/stage/preview/Preview.tsx
-import { useCallback as useCallback2, useEffect as useEffect7, useMemo as useMemo4, useRef as useRef13 } from "react";
+import { useCallback as useCallback2, useEffect as useEffect7, useMemo as useMemo4, useRef as useRef14 } from "react";
 
 // src/render/document-html.ts
 function documentToHtml(document, definitions = DEFAULT_BLOCKS, options = {}) {
@@ -5225,8 +5338,8 @@ function documentToHtml(document, definitions = DEFAULT_BLOCKS, options = {}) {
 // src/stage/preview/Preview.tsx
 import { jsx as jsx53 } from "react/jsx-runtime";
 function Preview({ document, definitions, variables, device }) {
-  const frameRef = useRef13(null);
-  const cleanupRef = useRef13();
+  const frameRef = useRef14(null);
+  const cleanupRef = useRef14();
   const html = useMemo4(
     () => documentToHtml(document, definitions, {
       resolveHtmlTemplates: true,
@@ -5420,75 +5533,22 @@ function Stage({
 }
 
 // src/shell/SubjectBar.tsx
-import { useId as useId13, useRef as useRef15 } from "react";
+import { useId as useId14, useRef as useRef15 } from "react";
 
 // src/shell/constants.ts
 var EMPTY_VARIABLES = [];
 var PERSONALIZATION_HINT = "Personalization fields will appear blank if no data is available.";
 
-// src/shell/PersonalizationMenu.tsx
-import { useEffect as useEffect8, useRef as useRef14, useState as useState16 } from "react";
-import { jsx as jsx56, jsxs as jsxs43 } from "react/jsx-runtime";
-function PersonalizationMenu({
-  variables,
-  onInsert
-}) {
-  const [open, setOpen] = useState16(false);
-  const rootRef = useRef14(null);
-  useEffect8(() => {
-    const root = rootRef.current;
-    if (!open || !root) return;
-    const ownerDocument = root.ownerDocument;
-    const onPointerDown = (event) => {
-      if (!root.contains(event.target)) setOpen(false);
-    };
-    ownerDocument.addEventListener("pointerdown", onPointerDown, true);
-    return () => ownerDocument.removeEventListener("pointerdown", onPointerDown, true);
-  }, [open]);
-  if (variables.length === 0) return null;
-  return /* @__PURE__ */ jsxs43("div", { className: "ree-personalization", ref: rootRef, children: [
-    /* @__PURE__ */ jsxs43(
-      "button",
-      {
-        type: "button",
-        className: "ree-personalization-btn",
-        "aria-expanded": open,
-        onClick: () => setOpen((current) => !current),
-        children: [
-          "Personalization",
-          /* @__PURE__ */ jsx56("svg", { viewBox: "0 0 20 20", width: "16", height: "16", fill: "currentColor", "aria-hidden": "true", children: /* @__PURE__ */ jsx56("path", { d: "M5.2 7.5 10 12.3l4.8-4.8 1.2 1.2L10 14.7 4 8.7l1.2-1.2Z" }) })
-        ]
-      }
-    ),
-    open ? /* @__PURE__ */ jsx56("div", { className: "ree-var-menu ree-personalization-menu", children: variables.map((variable) => /* @__PURE__ */ jsxs43(
-      "button",
-      {
-        type: "button",
-        className: "ree-var-item",
-        onClick: () => {
-          onInsert(variable.name);
-          setOpen(false);
-        },
-        children: [
-          /* @__PURE__ */ jsx56("span", { className: "ree-var-name", children: variable.name }),
-          variable.description ? /* @__PURE__ */ jsx56("span", { className: "ree-var-label", children: variable.description }) : null
-        ]
-      },
-      variable.name
-    )) }) : null
-  ] });
-}
-
 // src/shell/SubjectBar.tsx
-import { Fragment as Fragment5, jsx as jsx57, jsxs as jsxs44 } from "react/jsx-runtime";
+import { Fragment as Fragment5, jsx as jsx56, jsxs as jsxs43 } from "react/jsx-runtime";
 function SubjectBar({
   subject,
   variables,
   onSubjectChange
 }) {
   const inputRef = useRef15(null);
-  const subjectId = useId13();
-  const countId = useId13();
+  const subjectId = useId14();
+  const countId = useId14();
   const insertVariable = (token) => {
     var _a, _b;
     const input = inputRef.current;
@@ -5506,10 +5566,10 @@ function SubjectBar({
       (_b2 = inputRef.current) == null ? void 0 : _b2.setSelectionRange(cursor, cursor);
     });
   };
-  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(
+  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(
         TextInput,
         {
           id: subjectId,
@@ -5521,15 +5581,15 @@ function SubjectBar({
           onChange: (event) => onSubjectChange(event.target.value)
         }
       ),
-      /* @__PURE__ */ jsxs44("span", { id: countId, className: "ree-subject-count", children: [
+      /* @__PURE__ */ jsxs43("span", { id: countId, className: "ree-subject-count", children: [
         subject.length,
         "/",
         SUBJECT_MAX_LENGTH
       ] })
     ] }),
-    variables.length > 0 ? /* @__PURE__ */ jsxs44(Fragment5, { children: [
-      /* @__PURE__ */ jsx57(PersonalizationMenu, { variables, onInsert: insertVariable }),
-      /* @__PURE__ */ jsx57("p", { className: "ree-subject-hint", children: PERSONALIZATION_HINT })
+    variables.length > 0 ? /* @__PURE__ */ jsxs43(Fragment5, { children: [
+      /* @__PURE__ */ jsx56(PersonalizationMenu, { variables, onInsert: insertVariable }),
+      /* @__PURE__ */ jsx56("p", { className: "ree-subject-hint", children: PERSONALIZATION_HINT })
     ] }) : null
   ] });
 }
@@ -5897,7 +5957,7 @@ function useEditorSession(editor) {
 }
 
 // src/shell/EmailEditorShell.tsx
-import { jsx as jsx58, jsxs as jsxs45 } from "react/jsx-runtime";
+import { jsx as jsx57, jsxs as jsxs44 } from "react/jsx-runtime";
 function EmailEditorShell({ editor, height = "100%" }) {
   var _a;
   const session = useEditorSession(editor);
@@ -5935,8 +5995,8 @@ function EmailEditorShell({ editor, height = "100%" }) {
     selectBlock(null);
   };
   const showCanvas = () => setViewMode("edit");
-  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(
+  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(
       SubjectBar,
       {
         subject: (_a = session.document.subject) != null ? _a : "",
@@ -5944,8 +6004,8 @@ function EmailEditorShell({ editor, height = "100%" }) {
         onSubjectChange: session.setSubject
       }
     ),
-    /* @__PURE__ */ jsxs45("div", { className: "ree-body", children: [
-      /* @__PURE__ */ jsxs45(
+    /* @__PURE__ */ jsxs44("div", { className: "ree-body", children: [
+      /* @__PURE__ */ jsxs44(
         EditorDnd,
         {
           blocks: session.document.blocks,
@@ -5957,7 +6017,7 @@ function EmailEditorShell({ editor, height = "100%" }) {
           onReorder: session.reorderBlocks,
           onLibraryDragStart: showCanvas,
           children: [
-            /* @__PURE__ */ jsx58(
+            /* @__PURE__ */ jsx57(
               BlockLibrary,
               {
                 definitions: session.config.library,
@@ -5967,7 +6027,7 @@ function EmailEditorShell({ editor, height = "100%" }) {
                 }
               }
             ),
-            /* @__PURE__ */ jsx58(
+            /* @__PURE__ */ jsx57(
               Stage,
               {
                 session,
@@ -5981,7 +6041,7 @@ function EmailEditorShell({ editor, height = "100%" }) {
           ]
         }
       ),
-      /* @__PURE__ */ jsx58(
+      /* @__PURE__ */ jsx57(
         Inspector,
         {
           panel: inspectorPanel,
@@ -6001,9 +6061,9 @@ function EmailEditorShell({ editor, height = "100%" }) {
 }
 
 // src/EmailEditor.tsx
-import { jsx as jsx59 } from "react/jsx-runtime";
+import { jsx as jsx58 } from "react/jsx-runtime";
 function EmailEditor(props) {
-  return /* @__PURE__ */ jsx59(EmailEditorShell, __spreadValues({}, props));
+  return /* @__PURE__ */ jsx58(EmailEditorShell, __spreadValues({}, props));
 }
 
 // src/plugins/useEmailEditorConfig.ts
@@ -6014,8 +6074,8 @@ function useEmailEditorConfig(options = {}) {
 }
 
 // src/shell/useEmailEditor.ts
-import { useEffect as useEffect9, useInsertionEffect, useLayoutEffect as useLayoutEffect8, useState as useState19 } from "react";
-var useOptionsEffect = typeof window === "undefined" ? useEffect9 : useLayoutEffect8;
+import { useEffect as useEffect8, useInsertionEffect, useLayoutEffect as useLayoutEffect9, useState as useState19 } from "react";
+var useOptionsEffect = typeof window === "undefined" ? useEffect8 : useLayoutEffect9;
 function useEmailEditor(options = {}) {
   const [store] = useState19(() => createEditorStore(options));
   useInsertionEffect(() => {
@@ -6033,12 +6093,12 @@ function useEmailEditorState(editor) {
 }
 
 // src/plugins/components/ControlEditor.tsx
-import { jsx as jsx60 } from "react/jsx-runtime";
+import { jsx as jsx59 } 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__ */ jsx60(ControlRenderer, { control: definition, value: context.controls[control], body: context.body, variables: context.variables, onChange: (value) => context.setControl(control, value) });
+  return /* @__PURE__ */ jsx59(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

@@ -693,11 +693,6 @@
   background: var(--ree-panel-secondary);
 }
 
-.ree-personalization-menu {
-  left: 0;
-  min-width: 240px;
-}
-
 .ree-subject-hint {
   flex: 0 1 auto;
   margin: 0;
@@ -1670,16 +1665,30 @@
 
 /* ---------- 变量 ---------- */
 
-.ree-var-wrap {
+.ree-input-with-variable {
   position: relative;
 }
 
-.ree-var-btn {
+.ree-input-with-variable > .ree-input {
+  --ree-control-padding-end: 48px;
+}
+
+.ree-input-with-variable > .ree-textarea {
+  display: block;
+}
+
+.ree-personalization-suffix {
+  position: absolute;
+  top: 6px;
+  right: 6px;
+}
+
+.ree-personalization-suffix-btn {
   appearance: none;
   border: none;
   background: transparent;
   min-width: 30px;
-  height: 24px;
+  height: 26px;
   padding: 0 6px;
   border-radius: var(--ree-radius-sm);
   cursor: pointer;
@@ -1687,10 +1696,16 @@
   font-size: 12px;
 }
 
-.ree-var-btn:hover {
+.ree-personalization-suffix-btn:hover {
   background: var(--ree-panel-secondary);
 }
 
+.ree-personalization-suffix-btn:focus-visible,
+.ree-personalization-btn:focus-visible {
+  outline: 2px solid var(--ree-text);
+  outline-offset: -2px;
+}
+
 .ree-var-menu {
   position: absolute;
   top: 100%;
@@ -1707,6 +1722,16 @@
   color: var(--ree-text, #202223);
 }
 
+.ree-var-menu.ree-personalization-menu {
+  position: fixed;
+  inset: auto;
+  margin: 0;
+  z-index: 1000;
+  width: 240px;
+  min-width: 0;
+  max-width: calc(100vw - 16px);
+}
+
 .ree-var-item {
   display: flex;
   flex-direction: column;
@@ -1730,6 +1755,13 @@
   color: var(--ree-primary);
 }
 
+.ree-var-name,
+.ree-var-label {
+  max-width: 100%;
+  overflow-wrap: anywhere;
+  white-space: pre-wrap;
+}
+
 .ree-var-label {
   font-size: 12px;
   color: var(--ree-muted);
@@ -1862,28 +1894,6 @@
   margin-bottom: 14px;
 }
 
-.ree-field-label:has(> .ree-var-wrap) {
-  position: relative;
-  justify-content: flex-start;
-}
-
-.ree-field-label > .ree-var-wrap {
-  position: static;
-}
-
-.ree-field-label .ree-var-menu {
-  left: 0;
-  width: min(280px, 100%);
-  min-width: 0;
-}
-
-.ree-field-label .ree-var-name,
-.ree-field-label .ree-var-label {
-  max-width: 100%;
-  overflow-wrap: anywhere;
-  white-space: pre-wrap;
-}
-
 /* ---------- 配置控件 ---------- */
 
 .ree-textarea {

package/docs/api.md

@@ -270,6 +270,8 @@ pnpm build
 node --test tests/*.test.mjs tests/*.test.ts
 ```
 
+Use `pnpm check` to run all four checks in order, or `pnpm test` after building to run only the Node tests. Node 24 LTS and pnpm 10.16.1 are the repository defaults. See the [release guide](./release.md) for package verification and publishing.
+
 Build before tests that depend on dist. Internal TypeScript tests require Node 22.18+. The package ships ESM, declarations and flattened CSS. React/React DOM are peer dependencies; TipTap, dnd-kit, CodeMirror and Lezer are dependencies, externalized during builds rather than bundled.
 
 Local consumers can use link:../react-email-editor. Run pnpm build first and pnpm build:watch to update dist. Both projects must share one React instance: Vite can use resolve.dedupe: ["react", "react-dom"]; Next.js can use transpilePackages: ["@standhigher/react-email-editor"], with Turbopack root covering the linked directory.

package/docs/api.zh-CN.md

@@ -270,6 +270,8 @@ pnpm build
 node --test tests/*.test.mjs tests/*.test.ts
 ```
 
+`pnpm check` 按上述顺序执行全部检查；只运行 Node 测试时，构建后执行 `pnpm test`。本仓库默认使用 Node 24 LTS 和 pnpm 10.16.1。打包检查与发布流程见[发布指南](./release.zh-CN.md)。
+
 先构建再运行依赖 dist 的测试；TypeScript 内部测试需要 Node 22.18+。包提供 ESM、类型与展开后的 CSS。React/React DOM 为 peer dependencies；TipTap、dnd-kit、CodeMirror、Lezer 等为 dependencies，构建时 external，不内联到发布包。
 
 消费方可使用 `link:../react-email-editor`；先 `pnpm build`，再 `pnpm build:watch` 保持 dist 更新。两项目需共用一个 React 实例：Vite 可设置 `resolve.dedupe: ["react", "react-dom"]`；Next.js 可设置 `transpilePackages: ["@standhigher/react-email-editor"]`，Turbopack 的 root 需覆盖链接目录。

package/docs/changelog.md

@@ -0,0 +1,125 @@
+# Changelog
+
+English | [简体中文](./changelog.zh-CN.md)
+
+## 0.4.3 — 2026-10-28
+
+### Fixes and improvements
+
+- Reuse the same Personalization menu in the subject header and configuration panel, with consistent variable colors, width, border radius, shadows and hover styles.
+- Move variable triggers for text, multiline text and link controls to an input suffix on the right, reserving space for content; restore input focus and cursor position after inserting a variable.
+- Open menus to the left or above according to available viewport space, using native popovers to avoid scroll clipping and positioning offsets in embedded containers with `transform`.
+- Complete focus handling when opening from the keyboard, Tab/Shift+Tab exit, Escape dismissal and outside-click dismissal; preserve the selected block on close and clean up observers and event listeners.
+- Keep the public API, email export and `version: 4` document format unchanged.
+
+### Validation
+
+- `pnpm check` passed, including type checking, Oxlint, build and all 103 Node tests; add regression coverage for menu positioning, focus, dismissal and lifecycle.
+- Reuse the existing development server for browser interaction checks, covering suffix clicks, cursor insertion, keyboard navigation and positioning inside containers with `transform`.
+
+## 0.4.2 — 2026-10-28
+
+### npm publishing and documentation
+
+- Add the MIT license, repository, homepage and issue tracker, pin the public npm registry and pnpm 10.16.1, and recommend Node 24 LTS through `.nvmrc`.
+- Add `pnpm test`, `pnpm check` and complete validation before publishing; preserve CSS through `sideEffects` and verify that consumers can remove unused JavaScript imports.
+- Fix broken npm README images by using fixed absolute CDN URLs for images and viewing links from the published 0.4.1 package; newer packages retain Markdown and SVG documentation without shipping PNG originals again.
+- Use absolute GitHub URLs for language switches, API references, examples, release guides, changelogs and section navigation in both READMEs, and verify target documents and anchors; remote documents must be pushed with the commit.
+- Add English and Chinese release guides, package-content checks and consumer CSS validation; keep the React 18 peer range, existing public API and document format unchanged.
+
+## 0.4.1 — 2026-10-28
+
+### Documentation and type hints
+
+- Simplify both READMEs, add module architecture diagrams, and move detailed integration instructions into separate API reference, basic example and advanced example documents.
+- Add examples for saving and restoring documents, body settings and variables, multiple-instance subscriptions, custom blocks, multiple rich-text regions, image resource pickers and individual block template previews; update navigation in the custom block guides.
+- Add English JSDoc for editor instances, document models, plugins and controls, email rendering helpers, rich text and basic UI components, shipped with TypeScript declarations for IDE hover details on parameters, defaults and behavior boundaries.
+- Update only documentation, type comments and the package version, without changing runtime behavior, the public API or the persisted document version; documents remain at `version: 4`.
+
+### Validation
+
+- Type checking, Oxlint, build and all 96 Node tests passed.
+- All 34 TypeScript/TSX example files from both READMEs, API references and scenario documents passed type checking; all local documentation link targets exist.
+
+## 0.4.0 — 2026-10-28
+
+### Features and improvements
+
+- Standardize React integration on `useEmailEditorConfig()`, `useEmailEditor()` and `<EmailEditor editor={editor}>`; add `useEmailEditorState(editor)` for on-demand subscriptions to cached, read-only document snapshots.
+- Keep editor instance references stable and isolated, allowing reading, validation and export without mounting the UI; add `setDocument()` and `reset()`, clearing selection, focus and control state from the previous document on replacement or reset.
+- Preserve the current document when configuration or variables change; merge external body input when its value changes, avoid initialization callbacks, and keep document reads and callback arguments as independent snapshots.
+- Add export, new-document, reset and subscription examples to the playground, and update English and Chinese integration documentation.
+
+### Fixes and validation
+
+- Synchronize configuration, variables, body settings and callbacks during commit so child layout effects can read new values; defer subscription notifications and body callbacks to the layout phase, keeping interrupted concurrent renders from changing existing instances.
+- Use instance-specific IDs for subject inputs so labels, inputs and character-count hints remain independently associated across multiple editors.
+- Add coverage for configuration update timing, concurrent interruption, subject associations across multiple instances, negative type contracts for removed APIs and checks for compatibility entry points in source.
+
+### Breaking changes
+
+- Remove public `createEmailEditorConfig`, `EmailEditorConfigOptions`, `EmailEditorHandle`, component refs and previous state Props, without aliases or compatibility layers. Pass configuration and state to `useEmailEditor()`; the component accepts only `editor` and `height`.
+- The fourth argument of `blockToHtml()` and `renderBlockContent()` accepts only a `BlockRenderOptions` object; remove boolean adaptation and explicitly reject booleans passed from JavaScript. Template previews use `{ resolveHtmlTemplate: true }`.
+- Persisted documents remain at `version: 4`, without migration of older versions; this package version change affects only the package API and behavior.
+
+## 0.3.0 — 2026-10-28
+
+### Features and improvements
+
+- Add `defineBlock()`, `EmailControls` and `createEmailEditorConfig()`, sharing plugin configuration between the editor and standalone email export; support filtering, sorting and explicit overrides in the built-in block library.
+- Support custom control components, React Canvas/Inspector components, multiple `EditableRichText` regions, `ControlEditor`, declarative nested lists, image resource pickers and shared email HTML helpers in block plugins.
+- Add `config.validate()` to collect issues with numeric ranges, options, URL/image protocols, list counts and business validation; support updating several related controls at once through `setControls()`.
+- Add English and Chinese custom block API documentation, coupon and product card examples, and component regression tests.
+
+### Fixes
+
+- Preserve explicit colors and underlines when changing link URLs or opening behavior, and restore BODY inheritance on reset.
+- Use the same base typography for the canvas body, preview and email export, fixing differences in calculations for `em` padding, borders and other dimensions.
+- Fix asynchronous list updates overwriting subsequent edits or sorting; merge the latest values by stable row identifiers, ignore stale results after deletion or unmount, and avoid reusing deleted row identifiers for new rows.
+- Give custom controls independent snapshots of values, body settings and variables to prevent parameter mutations from affecting the host; isolate variable synchronization for custom Canvas/Inspector components as well.
+- Show an empty option in optional selects and support clearing them; associate control labels correctly with selects.
+- Make inspector rich text inherit body settings and enabled block typography, paragraph, list and link styles, updating when body configuration changes.
+- Report missing plugins and email export failures explicitly; isolate canvas and inspector errors per block and preserve original node data.
+
+### Breaking changes
+
+- Switch custom blocks to `defineBlock` + `EmailControls` + `createEmailEditorConfig`, with the component receiving `config`; remove the old `blocks` Prop, public `BlockDefinition/FieldConfig/FieldType` and `resolveBlockStyleFields`, without an adaptation layer. Control factories use `EmailControls.text(...)`, and blocks and lists declare controls through `controls` (without `field` / `fields` aliases); runtime and persisted nodes use `controls`, style declarations use `styleControls`, and update methods use `setControl/setControls`, with corresponding renames for types, `ControlEditor` and `controlPath`. Content defaults come from control declarations, rendering uses `renderEmail`, and the document format advances to v4, without compatibility or automatic migration for old data.
+- Standardize email body settings on `body`: documents use `EmailDocument.body`, the component uses `body` / `onBodyChange`, and types and helpers use `EmailBodySettings`, `DEFAULT_EMAIL_BODY` and `resolveEmailBody`; block rendering contexts and `BlockRenderOptions` also use `body`. Remove the previous Global API without aliases or migration code.
+- Advance the document version to `4`, without support for older versions. BODY General provides text color, link color, font, font weight and a link underline toggle; Content provides a single body Background, content width, Padding and block spacing, with border color, width and style grouped under Advanced: Border, collapsed by default. Apply configuration consistently to canvas, preview and export while preserving explicit content formatting. Keep only `contentPadding`, removing `outerPadding`, body alignment, outer background and border radius; center the body and keep the outer area white.
+
+## 0.2.0 — 2026-10-27
+
+### Breaking changes
+
+- Advance the document format from `version: 1` to `version: 2`, rejecting older versions without automatic migration. Use `createEmailDocument()` to create current-version documents; upgrading existing data requires updating block fields and styles as well as the version number.
+- Store text formatting for Heading, Text and Button in `fields.html`; Button no longer reads `fields.label` or typography from `style.element`. `EmailElementStyle` no longer extends `EmailTypographyStyle`.
+- Make built-in blocks declare `styleFields` according to their capabilities and ignore disabled styles; remove `dimension.height` and block-level `typography` from built-in blocks. Custom blocks can still enable these fields explicitly, with `exactStyleFields` constraining defaults, canvas and email output.
+- Preserve paragraphs, lists, links and explicit styles inside HTML block source without injecting body typography; undeclared properties can still inherit global styles.
+
+### Features and improvements
+
+- Support inline rich-text editing for Button with a single paragraph, joining multiple pasted paragraphs with spaces; preserve basic inline formatting in email output and generate only one outer button link.
+- Add `BlockInspectorSection`, `inspectorSections`, `RichTextProfile` and `inlineEditProfile` for custom inspector groups and rich-text capabilities; standalone `RichText` supports `profile`.
+- Unify color panels, HEX input and color reset; use a centered dialog for link editing, with color, underline and opening behavior options.
+- Improve block action bars, drag feedback, the three-column layout, toolbar wrapping and preview height; let previews follow document content.
+- Change the default button fill to black and default button/image links to empty, with no navigation for blank links; default global content, block, button and image borders to transparent.
+- Simplify both READMEs, add npm keywords, and include the Chinese README and changelog in the published package.
+
+### Fixes and validation
+
+- Fix cursor, selection and formatting preservation after rich-text formatting operations, and preserve spacing and indentation when switching lists.
+- Fix button export handling of quotes, comparison operators, comments and spaces inside template expressions.
+- Add Oxlint and regression tests for block configuration, rich text, lists, buttons and color conversion.
+
+## 0.1.0 — 2026-10-27
+
+First official release (commit `48011d9`).
+
+- Provide a React 18 editor, draggable blocks, rich-text editing, an inspector and desktop/mobile previews.
+- Support JSON documents, global and block styles, HTML source editing, custom blocks and Go template previews.
+- Provide data access through component refs, standalone HTML rendering, ESM, TypeScript declarations and a separate CSS entry point.
+- Provide a Vite playground, build tooling and a local linking workflow.
+
+## 0.0.0-stage — 2026-10-27
+
+- Package distribution verification version before the first release.

package/{CHANGELOG.md → docs/changelog.zh-CN.md}

@@ -1,5 +1,32 @@
 # 更新日志
 
+[English](./changelog.md) | 简体中文
+
+## 0.4.3 — 2026-10-28
+
+### 修复与改进
+
+- 主题 header 与配置区复用同一个 Personalization 菜单，统一变量颜色、宽度、圆角、阴影和 hover 样式。
+- 将配置区文本、多行文本与链接字段的变量入口移至输入框右侧后缀，预留内容空间；插入变量后恢复输入焦点和光标位置。
+- 菜单按视口空间向左或向上展开，使用原生 popover 避免滚动裁切及带 `transform` 的嵌入容器引起的定位偏移。
+- 补齐键盘打开时的焦点、Tab/Shift+Tab 退出、Escape 关闭与外部点击关闭；关闭菜单时保留当前区块选择，并清理观察器及事件监听器。
+- 保持公开 API、邮件导出和 `version: 4` 文档格式不变。
+
+### 验证
+
+- `pnpm check` 通过，包含类型检查、Oxlint、构建及全部 103 项 Node 测试；新增菜单定位、焦点、关闭与生命周期回归测试。
+- 复用现有开发服务完成浏览器交互验收，覆盖后缀点击、光标插入、键盘导航及带 `transform` 容器中的定位。
+
+## 0.4.2 — 2026-10-28
+
+### npm 发布与文档
+
+- 补齐 MIT 许可证、仓库、主页和 Issue 地址，固定公开 npm registry 与 pnpm 10.16.1，并通过 `.nvmrc` 推荐 Node 24 LTS。
+- 新增 `pnpm test`、`pnpm check` 和发布前完整校验；通过 `sideEffects` 保留 CSS，并验证消费方可以移除未使用的 JavaScript 导入。
+- 修复 npm README 图片失效：中英文图片与查看链接改用已发布 0.4.1 资源的固定绝对 CDN 地址；新版包不重复携带 PNG 原图，保留 Markdown 和 SVG 文档。
+- 中英文 README 的语言切换、API、示例、发布指南、更新日志及章节导航统一使用 GitHub 绝对地址，并验证目标文档和锚点存在；远端文档需随提交一并推送。
+- 补充中英文发布指南、发布文件范围与 CSS 消费验证；保持 React 18 peer 范围及现有公开 API、文档格式不变。
+
 ## 0.4.1 — 2026-10-28
 
 ### 文档与类型提示

package/docs/release.md

@@ -0,0 +1,38 @@
+# npm release guide
+
+English | [简体中文](./release.zh-CN.md)
+
+## Toolchain and package configuration
+
+Development uses Node 24 LTS (`.nvmrc`) and pnpm 10.16.1 (`packageManager`). The complete test suite needs Node 22.18+. These development requirements are not consumer requirements, so the package does not declare `engines`. React / React DOM 18 remain the supported peers; React 19 requires a separate compatibility validation.
+
+The manifest declares MIT licensing, repository, homepage, issue tracker and the public npm registry. `sideEffects: ["**/*.css"]` preserves CSS imports while allowing unused JavaScript modules to be removed. Actual tree shaking depends on module contents and the consumer's bundler.
+
+The package includes built assets, Markdown documentation and SVGs under `docs/` (including [English](./changelog.md) and [Chinese](./changelog.zh-CN.md) changelogs), plus both READMEs. npm automatically includes `package.json` and `LICENSE`. Source, playground, tests, caches and PNG originals are excluded.
+
+## README images
+
+Both READMEs use absolute CDN URLs pinned to the publicly published `0.4.1` package, which contains the English and Chinese PNG and SVG assets. This avoids relative-path resolution on npm, GitHub branch synchronization and shipping PNG copies in every release.
+
+When updating a diagram, host the new image at a stable public URL before changing either README. Do not reference an unpublished version or a `latest` URL that may no longer contain PNGs. Verify an unauthenticated `200` response and the correct image Content-Type.
+
+README language switches, documentation, changelog and section links use absolute GitHub `blob/main` URLs. Push the corresponding commit before publishing so the linked READMEs, `docs/` and changelog exist on GitHub; local-only files still return 404. Relative links inside documentation pages are resolved by GitHub against their directories.
+
+## Local checks and publishing
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+npm pack --dry-run
+```
+
+`pnpm check` runs type checking, linting, build and Node tests in order. Tests cover package contents, README image URLs and consumer CSS preservation. `pnpm test` requires an existing build. `prepack` builds assets; `prepublishOnly` runs the complete check before local publishing.
+
+To publish locally, first update both changelogs and select an unpublished version:
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+npm publish
+```
+
+The npm account needs permission for the `@standhigher` scope and any required 2FA. Published versions cannot be overwritten. Committing or pushing code does not automatically publish a package.

package/docs/release.zh-CN.md

@@ -0,0 +1,38 @@
+# npm 发布指南
+
+[English](./release.md) | 简体中文
+
+## 工具链与包配置
+
+开发默认使用 Node 24 LTS（`.nvmrc`）和 pnpm 10.16.1（`packageManager`）。完整测试最低需要 Node 22.18；这不是消费方安装要求，因此包没有添加 `engines` 限制。当前仍只声明 React 18 / React DOM 18 支持，React 19 需完成独立兼容性验证后再扩大 peer 范围。
+
+`package.json` 声明 MIT 许可证、仓库、主页、Issue 地址及公开 npm registry。`sideEffects: ["**/*.css"]` 保留消费方的 CSS 导入，允许 bundler 丢弃未使用的 JavaScript 模块；实际裁剪效果取决于模块内容和消费方 bundler。
+
+`files` 只发布构建产物、`docs/` 下的 Markdown 文档和 SVG（含[英文](./changelog.md)与[中文](./changelog.zh-CN.md)更新日志），以及中英文 README；npm 自动包含 `package.json` 和 `LICENSE`。源码、playground、测试、本地缓存和 PNG 原图不进入包。
+
+## README 图片
+
+npm README 使用固定版本的绝对 CDN 地址，图片来自已公开发布的 `0.4.1` 包。中英文 PNG 和 SVG 源文件均由该版本提供，不依赖本地相对路径或 GitHub 分支同步，也不需要在每个新版包中重复分发 PNG。
+
+更新架构图时，先将新图片放到可公开读取的稳定地址，再更新两个 README 的图片与查看链接。不要把地址替换成尚未发布的版本，也不要使用会随 `latest` 变化且可能缺失 PNG 的路径。图片地址应无需登录，返回 `200` 和正确的图片 Content-Type。
+
+README 的语言切换、文档、更新日志和章节导航使用 GitHub `blob/main` 绝对地址。发布前须先推送相应提交，确保 GitHub 上的 README、`docs/` 与更新日志均已同步；仅在本地存在的文档仍会返回 404。文档页内部的相对链接继续由 GitHub 按目录解析。
+
+## 本地检查与发布
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+npm pack --dry-run
+```
+
+`pnpm check` 顺序执行类型检查、lint、构建和 Node 测试；测试包含发布文件范围、README 图片地址及消费方 CSS 保留验证。`pnpm test` 只执行测试，需先构建。`prepack` 负责构建；本地 `npm publish` 的 `prepublishOnly` 会执行完整校验。
+
+需要本地手动发布时，在确认版本未发布、中英文更新日志已同步后执行：
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+npm publish
+```
+
+发布需要 npm 账号对 `@standhigher` scope 的权限及账号要求的 2FA。已发布的相同版本不能覆盖。代码提交或推送不会自动发布 npm 包。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standhigher/react-email-editor",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "description": "React email template editor with drag-and-drop blocks, rich text, JSON storage, and HTML export.",
   "keywords": [
@@ -17,6 +17,16 @@
     "go-template"
   ],
   "author": "Nono",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/standhigher/react-email-editor.git"
+  },
+  "homepage": "https://github.com/standhigher/react-email-editor#readme",
+  "bugs": {
+    "url": "https://github.com/standhigher/react-email-editor/issues"
+  },
+  "packageManager": "pnpm@10.16.1",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -27,21 +37,26 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "sideEffects": ["**/*.css"],
   "files": [
     "dist",
-    "docs",
+    "docs/**/*.md",
+    "docs/**/*.svg",
     "README.md",
-    "README.zh-CN.md",
-    "CHANGELOG.md"
+    "README.zh-CN.md"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
     "dev": "vite --config playground/vite.config.ts",
     "build": "tsup",
     "build:watch": "tsup --watch src",
+    "test": "node --test tests/*.test.mjs tests/*.test.ts",
+    "check": "pnpm typecheck && pnpm lint && pnpm build && pnpm test",
     "prepack": "pnpm build",
+    "prepublishOnly": "pnpm check",
     "typecheck": "tsc --noEmit && tsc --noEmit -p playground",
     "lint": "oxlint . --deny-warnings --report-unused-disable-directives",
     "lint:fix": "pnpm lint --fix"