@mteditor/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MtEditor contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# @mteditor/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> MtEditor 的 React 适配层 —— **薄壳，不含任何编辑逻辑**。
+
+## 状态
+
+**M3-c 已落地**。组件、类型、单测与可跑通示例均在本包内；
+可跑通的最小示例见 [`../../examples/react/`](../../examples/react/)。
+
+## 用法
+
+```tsx
+import { useRef, useState } from 'react'
+import { MtEditor } from '@mteditor/react'
+import type { MtDocument, MtEditorReactHandle } from '@mteditor/react'
+
+export const App = () => {
+  const [doc, setDoc] = useState<MtDocument>()
+  const ref = useRef<MtEditorReactHandle>(null)
+
+  return (
+    <MtEditor
+      ref={ref}
+      value={doc}
+      onChange={(payload) => setDoc(payload.json)}
+      options={{ placeholder: '请输入…', theme: 'light' }}
+    />
+  )
+}
+```
+
+```ts
+// 样式是独立的包，且是纯 CSS（无 JS 入口），必须显式引入
+import '@mteditor/theme-default/index.css'
+```
+
+React 没有 `v-model`，因此「双向绑定」在这里就是**受控组件**惯例：
+`value` 进 / `onChange` 出，由宿主把两者接起来。
+
+## Props
+
+| Prop | 类型 | 说明 |
+|---|---|---|
+| `value` | `MtDocument \| undefined` | 文档（真相源） |
+| `options` | `MtAdapterOptions` | 其余内核选项 |
+| `className` | `string` | 宿主容器的类名（会与 `mt-editor-host` 合并） |
+| `style` | `CSSProperties` | 宿主容器的行内样式 |
+| `onChange` / `onReady` / `onFocus` / `onBlur` / `onSelectionChange` / `onError` / `onDestroy` | 见下表 | 全部可选 |
+
+`className` / `style` 需要显式声明，是因为 **React 不像 Vue 那样自动透传 attrs**
+到单根元素 —— Vue 侧这两个能力是白送的，React 侧必须写出来。
+
+`MtAdapterOptions = Omit<MtEditorOptions, 'element' | 'onChange' | 'onReady' | 'onError'>`。
+被摘掉的四个由组件自己接管；**`content` 保留**，语义收窄为「初始内容，挂载时读取一次」，
+`value` 一旦给出就优先于它。
+
+**这里没有 `html` prop**（与 Vue 适配层的一处刻意不对称）：`html` 是有损派生物，
+`onChange` 的载荷里已经带着它，再开一个输入通道只会多一个「谁覆盖谁」的问题。
+Vue 侧之所以有 `v-model:html`，是因为它的绑定语法需要一个 prop 名。
+
+**运行时可变**的选项只有三个：`theme` / `locale` / `readonly`
+（内核分别为它们提供了 `setTheme` / `setLocale` / `setReadonly`）。
+其余（`platform` / `ui` / `placeholder` / `plugins` / `historyDepth` /
+`changeDebounce` / `selectionThrottle`）**挂载时读取一次**，要换档请用 `key` 重挂载。
+
+## 事件
+
+内核事件名**原样**沿用（§7.5），只按 React 惯例加 `on` 前缀。
+
+| Prop | 载荷 |
+|---|---|
+| `onChange` | `MtChangePayload`（**150ms 防抖**） |
+| `onReady` | `{ instance }` |
+| `onFocus` / `onBlur` | `{ instance }` |
+| `onSelectionChange` | `MtSelectionInfo`（100ms 节流，leading + trailing） |
+| `onError` | `MtErrorPayload` |
+| `onDestroy` | `{ instance }` |
+
+`ready` 在内核的**构造函数里**就派发了，因此组件把它当**构造选项**（`onReady`）传入，
+而不是事后 `on('ready')` 订阅 —— 后者永远收不到。
+也正因如此，`onReady` 是**唯一**能直接拿到「刚建好的实例」的时机。
+
+## 暴露的句柄
+
+```tsx
+const ref = useRef<MtEditorReactHandle>(null)
+// 「卸载后」为 null
+ref.current?.editor?.command('focus')
+```
+
+适配层**不转发内核方法**：取到 `editor` 后用法与原生完全一致。
+组件卸载时 React 会把 `ref.current` **整体置空**，因此宿主不可能拿到已销毁的实例。
+
+## 边界（AGENTS.md §8.1）
+
+允许做：
+
+1. 挂载 / 卸载底层实例；
+2. `props` → `MtEditorOptions` 映射；
+3. `options` 变更时**增量更新**（不重建实例）；
+4. 内核事件 → 宿主回调透传；
+5. 受控值回灌（`value` → `setJSON()`）。
+
+**不允许做**：任何编辑逻辑、任何依赖 React 生态辅助包。
+
+三条具体的实现约束（ADR-0028 决策 4）：
+
+- **挂载 effect 的依赖数组必须是空的**。React 的内联回调每次渲染都是新引用，
+  放进依赖数组就等于「每敲一个字重建一次实例」，而内容是看不出问题的 ——
+  丢的是选区、撤销栈与 IME composition 状态。做法是把最新 props 存进 ref，
+  构造时传的闭包只从 ref 里读。
+- **不在这里做回声抑制**。「灌回来的是同一份内容就不该碰视图」这条判据写在**内核**
+  （`MtEngine.setDocument()` 的结构等价短路）。适配层再判一次等于两处判据，
+  且六个适配端会各判各的。
+- **不为了「同步内容」而重建实例**。
+
+## 严格模式双挂载（§8.2 必测项）
+
+开发模式下 React 会把 effect 执行两遍（挂载 → 清理 → 再挂载）来暴露副作用泄漏。
+本组件的清理函数会 `destroy()` 实例并退订全部监听，因此第二轮拿到的是一张干净的白纸。
+
+单测里用 `<StrictMode>` 实测守三条：页面上只剩**一个** `.mt-editor`、
+内容不重复、**一次编辑只派发一次 `onChange`**（监听不叠加）。
+
+## 依赖
+
+| 类型 | 内容 |
+|---|---|
+| `dependencies` | `@mteditor/core` |
+| `peerDependencies` | `react: ^18.0.0 \|\| ^19.0.0`（宽范围，不打包宿主运行时） |
+
+## 测试
+
+```bash
+pnpm --filter @mteditor/react test        # 单测（happy-dom + @testing-library/react）
+pnpm --filter @mteditor/react typecheck
+```
+
+14 条单测覆盖五组：挂载与卸载、受控值与事件（含「回灌不产生第二次派发」与
+「克隆后回灌」）、选项映射、`className` / `style` 透传、严格模式双挂载。
+
+端到端在 [`../../tests/e2e/adapters.spec.ts`](../../tests/e2e/adapters.spec.ts)：
+真实浏览器里（示例页也包着 `<StrictMode>`）挂载 → 输入 → 读回**宿主侧的受控值**。
+适配包不设覆盖率阈值（ADR-0019 只覆盖 `document` / `core` / `renderer-web`），
+但示例必须纳入 E2E（§8.3，ADR-0028 决策 6）。
+
+## 交付要求
+
+每个适配包必须在 `examples/react/` 下提供**可跑通的最小示例** + 完整 README
+（安装、引入、props 表、事件表、常见坑）。**没有示例视为未完成，不允许发版**（§8.3）。
+
+## 许可
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,89 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var react = require('react');
+var core = require('@mteditor/core');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/component.tsx
+var applyRuntimeOptions = (instance, options) => {
+  if (options.theme !== void 0) instance.setTheme(options.theme);
+  if (options.locale !== void 0) instance.setLocale(options.locale);
+  if (options.readonly !== void 0) instance.setReadonly(options.readonly);
+};
+var MtEditor = react.forwardRef((props, ref) => {
+  const hostRef = react.useRef(null);
+  const instanceRef = react.useRef(null);
+  const propsRef = react.useRef(props);
+  react.useEffect(() => {
+    propsRef.current = props;
+  });
+  react.useEffect(() => {
+    const element = hostRef.current;
+    if (element === null) return void 0;
+    const { content: initialContent, ...restOptions } = propsRef.current.options ?? {};
+    const editor = new core.MtEditor({
+      ...restOptions,
+      element,
+      content: propsRef.current.value ?? initialContent,
+      onChange: (payload) => propsRef.current.onChange?.(payload),
+      // `ready` 在构造期就已派发，因此它走构造选项；其余事件走总线订阅
+      onReady: (payload) => propsRef.current.onReady?.(payload),
+      onError: (payload) => propsRef.current.onError?.(payload)
+    });
+    const offs = [
+      editor.on("focus", (payload) => propsRef.current.onFocus?.(payload)),
+      editor.on("blur", (payload) => propsRef.current.onBlur?.(payload)),
+      editor.on(
+        "selectionChange",
+        (payload) => propsRef.current.onSelectionChange?.(payload)
+      ),
+      editor.on("destroy", (payload) => propsRef.current.onDestroy?.(payload))
+    ];
+    instanceRef.current = editor;
+    return () => {
+      instanceRef.current = null;
+      editor.destroy();
+      for (const off of offs) off();
+    };
+  }, []);
+  const { value, className, style } = props;
+  react.useEffect(() => {
+    const editor = instanceRef.current;
+    if (editor === null || value === void 0) return;
+    editor.setJSON(value);
+  }, [value]);
+  const theme = props.options?.theme;
+  const locale = props.options?.locale;
+  const readonly = props.options?.readonly;
+  react.useEffect(() => {
+    const editor = instanceRef.current;
+    if (editor !== null) applyRuntimeOptions(editor, { theme, locale, readonly });
+  }, [theme, locale, readonly]);
+  react.useImperativeHandle(
+    ref,
+    () => ({
+      get editor() {
+        return instanceRef.current;
+      }
+    }),
+    []
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      ref: hostRef,
+      className: className === void 0 ? "mt-editor-host" : `mt-editor-host ${className}`,
+      style,
+      "data-mt-adapter": "react"
+    }
+  );
+});
+MtEditor.displayName = "MtEditor";
+var component_default = MtEditor;
+
+exports.MtEditor = MtEditor;
+exports.default = component_default;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/component.tsx"],"names":["forwardRef","useRef","useEffect","MtCoreEditor","useImperativeHandle","jsx"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * React 适配组件（AGENTS.md §8.2）。\n *\n * 它是**薄壳**（§8.1）：只做挂载 / 卸载、props → 选项映射、增量更新、事件透传与受控值回灌。\n * 任何编辑逻辑都写在 `@mteditor/core`，写在这里视为违规。\n *\n * ## 三条关键设计（ADR-0028 决策 4）\n *\n * 1. **挂载 effect 只跑一次（`[]` 依赖）**。React 的内联箭头函数每次渲染都是新的引用，\n *    若把 `onChange` 之类的 props 放进依赖数组，用户每敲一个字就会「销毁 → 重建」实例，\n *    选区、撤销栈与 IME composition 状态全丢。做法是把最新 props 存进一个 ref，\n *    构造时传的闭包只从 ref 里读 —— 依赖数组因此可以是空的。\n * 2. **这里不做回声抑制**。宿主把编辑器刚给出的文档灌回来是受控组件的必然结果，\n *    而「灌回来的是同一份内容就不该碰视图」这条判据写在**内核**\n *    （`MtEngine.setDocument()` 的结构等价短路）。适配层再判一次等于两处判据，\n *    且 6 个适配端会各判各的。\n * 3. **结构性选项挂载时读取一次**。内核没有「运行时换档」的能力\n *    （`platform` / `ui` / `placeholder` / `historyDepth` 等都没有 setter），\n *    因此本组件不假装支持它。要换档请用 React 的重挂载机制（`key`）。\n *\n * ## 严格模式双挂载\n *\n * 开发模式下 React 会把 effect 执行两遍（挂载 → 清理 → 再挂载）来暴露副作用泄漏。\n * 本组件的清理函数会 `destroy()` 实例并退订全部监听，因此第二轮拿到的是一张干净的白纸；\n * 「页面上只剩一个 `.mt-editor`、内容不重复、监听不叠加」由单测与 E2E 守（§8.2 必测项）。\n */\n\nimport { forwardRef, useEffect, useImperativeHandle, useRef } from 'react'\n\nimport { MtEditor as MtCoreEditor } from '@mteditor/core'\nimport type {\n  MtAdapterOptions,\n  MtChangePayload,\n  MtErrorPayload,\n  MtSelectionInfo,\n} from '@mteditor/core'\n\nimport type { MtEditorReactHandle, MtEditorReactProps } from './types'\n\n/** 能就地同步的选项子集。类型取自 `MtAdapterOptions`，不另立一份定义 */\ntype MtRuntimeOptions = Pick<MtAdapterOptions, 'theme' | 'locale' | 'readonly'>\n\n/**\n * 把可在**运行时**就地同步的选项写进已存在的内核实例。\n *\n * 只覆盖 `theme` / `locale` / `readonly` 三项 —— 内核只为这三项提供了 setter\n * （`setTheme` / `setLocale` / `setReadonly`）。其余选项\n * （`platform` / `ui` / `placeholder` / `plugins` / `historyDepth` /\n * `changeDebounce` / `selectionThrottle`）**在挂载时读取一次**，\n * 要换档请用 React 的重挂载机制（`key`）。\n *\n * 白名单是刻意的：内核将来新增运行时 setter 时，需要**显式**加进这里才会生效 ——\n * 比「默认尝试同步」安全，因为后者会让 `ui` 之类的结构性选项被半途写入而非完整重建。\n *\n * @param instance 内核实例\n * @param options 只含「能就地改」的三项\n */\nconst applyRuntimeOptions = (instance: MtCoreEditor, options: MtRuntimeOptions): void => {\n  if (options.theme !== undefined) instance.setTheme(options.theme)\n  if (options.locale !== undefined) instance.setLocale(options.locale)\n  if (options.readonly !== undefined) instance.setReadonly(options.readonly)\n}\n\n/**\n * `<MtEditor>` —— React 的 MtEditor 组件。\n *\n * @example\n * ```tsx\n * import { useRef, useState } from 'react'\n * import { MtEditor } from '@mteditor/react'\n * import type { MtDocument, MtEditorReactHandle } from '@mteditor/react'\n * import '@mteditor/theme-default/index.css'\n *\n * export const App = () => {\n *   const [doc, setDoc] = useState<MtDocument>()\n *   const ref = useRef<MtEditorReactHandle>(null)\n *\n *   return (\n *     <MtEditor\n *       ref={ref}\n *       value={doc}\n *       onChange={(payload) => setDoc(payload.json)}\n *       options={{ placeholder: '请输入…', theme: 'light' }}\n *     />\n *   )\n * }\n * ```\n */\nexport const MtEditor = forwardRef<MtEditorReactHandle, MtEditorReactProps>((props, ref) => {\n  /** 挂载容器。由本组件创建，且**不给它任何子节点** —— React 因此不会碰内核建的 DOM */\n  const hostRef = useRef<HTMLDivElement | null>(null)\n  /** 内核实例。用 ref 而不是 state：实例变化不需要重绘（句柄走 getter 读实时值） */\n  const instanceRef = useRef<MtCoreEditor | null>(null)\n  /** 最新 props。让「只跑一次」的挂载 effect 也能读到当下的回调（见文件头设计 1） */\n  const propsRef = useRef(props)\n\n  // 不用依赖数组：每次提交后同步一次最新 props 即可\n  useEffect(() => {\n    propsRef.current = props\n  })\n\n  // 挂载 / 卸载。**依赖数组必须是空的** —— 见文件头设计 1\n  useEffect(() => {\n    const element = hostRef.current\n    if (element === null) return undefined\n\n    // `options.content` 语义是「初始内容」；受控值一旦给出就优先于它。\n    // 必须先摘出来再展开，否则 `...options` 会把 `content` 覆盖回旧值。\n    const { content: initialContent, ...restOptions } = propsRef.current.options ?? {}\n\n    const editor = new MtCoreEditor({\n      ...restOptions,\n      element,\n      content: propsRef.current.value ?? initialContent,\n      onChange: (payload: MtChangePayload) => propsRef.current.onChange?.(payload),\n      // `ready` 在构造期就已派发，因此它走构造选项；其余事件走总线订阅\n      onReady: (payload) => propsRef.current.onReady?.(payload),\n      onError: (payload: MtErrorPayload) => propsRef.current.onError?.(payload),\n    })\n\n    const offs = [\n      editor.on('focus', (payload) => propsRef.current.onFocus?.(payload)),\n      editor.on('blur', (payload) => propsRef.current.onBlur?.(payload)),\n      editor.on('selectionChange', (payload: MtSelectionInfo) =>\n        propsRef.current.onSelectionChange?.(payload),\n      ),\n      editor.on('destroy', (payload) => propsRef.current.onDestroy?.(payload)),\n    ]\n\n    instanceRef.current = editor\n\n    return () => {\n      instanceRef.current = null\n      // 先销毁再退订：`destroy` 事件本身要透给宿主\n      editor.destroy()\n      for (const off of offs) off()\n    }\n  }, [])\n\n  // 「编辑器 → 宿主」由 onChange 完成；这里只做「宿主 → 编辑器」。\n  // 内核的结构等价短路保证回灌同一个文档时不会重置光标（ADR-0028 决策 2）。\n  const { value, className, style } = props\n  useEffect(() => {\n    const editor = instanceRef.current\n    if (editor === null || value === undefined) return\n    editor.setJSON(value)\n  }, [value])\n\n  // 选项变化：只同步能在运行时就地改的那几个（结构性选项挂载时读取一次）\n  const theme = props.options?.theme\n  const locale = props.options?.locale\n  const readonly = props.options?.readonly\n  useEffect(() => {\n    const editor = instanceRef.current\n    if (editor !== null) applyRuntimeOptions(editor, { theme, locale, readonly })\n  }, [theme, locale, readonly])\n\n  // 句柄用 getter 读实时值：实例在挂载 effect 里才产生，渲染期取值只能取到 `null`\n  useImperativeHandle(\n    ref,\n    () => ({\n      get editor() {\n        return instanceRef.current\n      },\n    }),\n    [],\n  )\n\n  // 内核根容器在这个 div 内部，宿主若要整体样式钩子，用 `data-mt-adapter`。\n  // React 不会像 Vue 那样自动透传 class / style，故这两个 prop 需要显式声明。\n  return (\n    <div\n      ref={hostRef}\n      className={className === undefined ? 'mt-editor-host' : `mt-editor-host ${className}`}\n      style={style}\n      data-mt-adapter=\"react\"\n    />\n  )\n})\n\n/** 组件展示名。React DevTools 里显示为 `MtEditor` 而不是 `ForwardRef` */\nMtEditor.displayName = 'MtEditor'\n\nexport default MtEditor\n"]}

package/dist/index.d.cts

@@ -0,0 +1,113 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+import { MtChangePayload, MtEditor as MtEditor$1, MtSelectionInfo, MtErrorPayload, MtDocument, MtAdapterOptions } from '@mteditor/core';
+export { MtAdapterOptions, MtChangePayload, MtDocument, MtEditor as MtEditorInstance, MtErrorPayload, MtSelectionInfo, MtThemeName } from '@mteditor/core';
+
+/**
+ * `@mteditor/react` 的公开类型面。
+ *
+ * 这些类型是**给宿主写 JSX 与处理函数用的**，不是内部实现类型。
+ * 它们只是 `@mteditor/core` 的再导出与组合 —— 适配层不得自己另立一套文档模型类型，
+ * 否则「适配层的类型」与「内核的类型」会漂移成两份（ADR-0028 决策 3）。
+ */
+
+/**
+ * `<MtEditor>` 的处理函数 props。
+ *
+ * 名字**原样**沿用内核的 §7.5 事件命名（`change` / `ready` / `focus` / `blur` /
+ * `selectionChange` / `error` / `destroy`），只按 React 惯例加上 `on` 前缀 ——
+ * 改名会让「内核文档里的事件名」与「框架里的用法」变成两套说法（ADR-0028 决策 4）。
+ *
+ * 全部可选：不传就是「不关心该事件」，不会因为漏传而在控制台报错。
+ */
+interface MtEditorReactHandlers {
+    /** 内容变化（**150ms 防抖**）。载荷含 `json` / `html` / `text` 三份产物 */
+    onChange?: (payload: MtChangePayload) => void;
+    /** 实例就绪。**在构造期同步派发**，因此它是唯一能拿到「刚建好的实例」的时机 */
+    onReady?: (payload: {
+        instance: MtEditor$1;
+    }) => void;
+    /** 编辑器获得焦点 */
+    onFocus?: (payload: {
+        instance: MtEditor$1;
+    }) => void;
+    /** 编辑器失去焦点 */
+    onBlur?: (payload: {
+        instance: MtEditor$1;
+    }) => void;
+    /** 选区变化（**100ms 节流**，leading + trailing） */
+    onSelectionChange?: (payload: MtSelectionInfo) => void;
+    /** 内核错误。**所有「闸口拒绝」都走这里**，不允许只 `console.warn` */
+    onError?: (payload: MtErrorPayload) => void;
+    /** 实例销毁（组件卸载时也会走到） */
+    onDestroy?: (payload: {
+        instance: MtEditor$1;
+    }) => void;
+}
+/**
+ * `<MtEditor>` 的 props。
+ *
+ * React 没有 `v-model`，因此「双向绑定」在 React 侧表现为 **`value` 进 / `onChange` 出**，
+ * 由宿主自己把两者接起来（受控组件惯例）。
+ *
+ * 与 Vue 适配层的一点不对称：**这里没有 `html` prop**。
+ * `html` 是有损派生物，`v-model:html` 在 Vue 里之所以存在，是因为 Vue 的绑定语法
+ * 需要一个 prop 名；React 的 `onChange` 载荷里已经带着 `html`，
+ * 再开一个输入通道只会多一个「谁覆盖谁」的问题（ADR-0028 决策 4）。
+ */
+interface MtEditorReactProps extends MtEditorReactHandlers {
+    /** 文档（真相源）。与 `onChange` 配合即为受控用法 */
+    value?: MtDocument;
+    /** 其余内核选项。见 `MtAdapterOptions` */
+    options?: MtAdapterOptions;
+    /** 宿主容器的类名。Vue 侧由 attrs 透传自动完成，React 需要显式声明 */
+    className?: string;
+    /** 宿主容器的行内样式。同上 */
+    style?: CSSProperties;
+}
+/**
+ * 通过 `ref` 取到的命令式句柄。
+ *
+ * 只暴露 `editor`：适配层是薄壳，不该把内核的方法再转发一遍 ——
+ * 那样每加一个内核方法就要改 6 个适配端，且「适配层的方法」会与内核文档分叉。
+ *
+ * @example
+ * ```tsx
+ * const editorRef = useRef<MtEditorReactHandle>(null)
+ * // …
+ * editorRef.current?.editor?.command('focus')
+ * ```
+ */
+interface MtEditorReactHandle {
+    /** 底层内核实例；未挂载（或已卸载、或正处于严格模式的重挂载空档）时为 `null` */
+    readonly editor: MtEditor$1 | null;
+}
+
+/**
+ * `<MtEditor>` —— React 的 MtEditor 组件。
+ *
+ * @example
+ * ```tsx
+ * import { useRef, useState } from 'react'
+ * import { MtEditor } from '@mteditor/react'
+ * import type { MtDocument, MtEditorReactHandle } from '@mteditor/react'
+ * import '@mteditor/theme-default/index.css'
+ *
+ * export const App = () => {
+ *   const [doc, setDoc] = useState<MtDocument>()
+ *   const ref = useRef<MtEditorReactHandle>(null)
+ *
+ *   return (
+ *     <MtEditor
+ *       ref={ref}
+ *       value={doc}
+ *       onChange={(payload) => setDoc(payload.json)}
+ *       options={{ placeholder: '请输入…', theme: 'light' }}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+declare const MtEditor: react.ForwardRefExoticComponent<MtEditorReactProps & react.RefAttributes<MtEditorReactHandle>>;
+
+export { MtEditor, type MtEditorReactHandle, type MtEditorReactHandlers, type MtEditorReactProps, MtEditor as default };

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+import { MtChangePayload, MtEditor as MtEditor$1, MtSelectionInfo, MtErrorPayload, MtDocument, MtAdapterOptions } from '@mteditor/core';
+export { MtAdapterOptions, MtChangePayload, MtDocument, MtEditor as MtEditorInstance, MtErrorPayload, MtSelectionInfo, MtThemeName } from '@mteditor/core';
+
+/**
+ * `@mteditor/react` 的公开类型面。
+ *
+ * 这些类型是**给宿主写 JSX 与处理函数用的**，不是内部实现类型。
+ * 它们只是 `@mteditor/core` 的再导出与组合 —— 适配层不得自己另立一套文档模型类型，
+ * 否则「适配层的类型」与「内核的类型」会漂移成两份（ADR-0028 决策 3）。
+ */
+
+/**
+ * `<MtEditor>` 的处理函数 props。
+ *
+ * 名字**原样**沿用内核的 §7.5 事件命名（`change` / `ready` / `focus` / `blur` /
+ * `selectionChange` / `error` / `destroy`），只按 React 惯例加上 `on` 前缀 ——
+ * 改名会让「内核文档里的事件名」与「框架里的用法」变成两套说法（ADR-0028 决策 4）。
+ *
+ * 全部可选：不传就是「不关心该事件」，不会因为漏传而在控制台报错。
+ */
+interface MtEditorReactHandlers {
+    /** 内容变化（**150ms 防抖**）。载荷含 `json` / `html` / `text` 三份产物 */
+    onChange?: (payload: MtChangePayload) => void;
+    /** 实例就绪。**在构造期同步派发**，因此它是唯一能拿到「刚建好的实例」的时机 */
+    onReady?: (payload: {
+        instance: MtEditor$1;
+    }) => void;
+    /** 编辑器获得焦点 */
+    onFocus?: (payload: {
+        instance: MtEditor$1;
+    }) => void;
+    /** 编辑器失去焦点 */
+    onBlur?: (payload: {
+        instance: MtEditor$1;
+    }) => void;
+    /** 选区变化（**100ms 节流**，leading + trailing） */
+    onSelectionChange?: (payload: MtSelectionInfo) => void;
+    /** 内核错误。**所有「闸口拒绝」都走这里**，不允许只 `console.warn` */
+    onError?: (payload: MtErrorPayload) => void;
+    /** 实例销毁（组件卸载时也会走到） */
+    onDestroy?: (payload: {
+        instance: MtEditor$1;
+    }) => void;
+}
+/**
+ * `<MtEditor>` 的 props。
+ *
+ * React 没有 `v-model`，因此「双向绑定」在 React 侧表现为 **`value` 进 / `onChange` 出**，
+ * 由宿主自己把两者接起来（受控组件惯例）。
+ *
+ * 与 Vue 适配层的一点不对称：**这里没有 `html` prop**。
+ * `html` 是有损派生物，`v-model:html` 在 Vue 里之所以存在，是因为 Vue 的绑定语法
+ * 需要一个 prop 名；React 的 `onChange` 载荷里已经带着 `html`，
+ * 再开一个输入通道只会多一个「谁覆盖谁」的问题（ADR-0028 决策 4）。
+ */
+interface MtEditorReactProps extends MtEditorReactHandlers {
+    /** 文档（真相源）。与 `onChange` 配合即为受控用法 */
+    value?: MtDocument;
+    /** 其余内核选项。见 `MtAdapterOptions` */
+    options?: MtAdapterOptions;
+    /** 宿主容器的类名。Vue 侧由 attrs 透传自动完成，React 需要显式声明 */
+    className?: string;
+    /** 宿主容器的行内样式。同上 */
+    style?: CSSProperties;
+}
+/**
+ * 通过 `ref` 取到的命令式句柄。
+ *
+ * 只暴露 `editor`：适配层是薄壳，不该把内核的方法再转发一遍 ——
+ * 那样每加一个内核方法就要改 6 个适配端，且「适配层的方法」会与内核文档分叉。
+ *
+ * @example
+ * ```tsx
+ * const editorRef = useRef<MtEditorReactHandle>(null)
+ * // …
+ * editorRef.current?.editor?.command('focus')
+ * ```
+ */
+interface MtEditorReactHandle {
+    /** 底层内核实例；未挂载（或已卸载、或正处于严格模式的重挂载空档）时为 `null` */
+    readonly editor: MtEditor$1 | null;
+}
+
+/**
+ * `<MtEditor>` —— React 的 MtEditor 组件。
+ *
+ * @example
+ * ```tsx
+ * import { useRef, useState } from 'react'
+ * import { MtEditor } from '@mteditor/react'
+ * import type { MtDocument, MtEditorReactHandle } from '@mteditor/react'
+ * import '@mteditor/theme-default/index.css'
+ *
+ * export const App = () => {
+ *   const [doc, setDoc] = useState<MtDocument>()
+ *   const ref = useRef<MtEditorReactHandle>(null)
+ *
+ *   return (
+ *     <MtEditor
+ *       ref={ref}
+ *       value={doc}
+ *       onChange={(payload) => setDoc(payload.json)}
+ *       options={{ placeholder: '请输入…', theme: 'light' }}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+declare const MtEditor: react.ForwardRefExoticComponent<MtEditorReactProps & react.RefAttributes<MtEditorReactHandle>>;
+
+export { MtEditor, type MtEditorReactHandle, type MtEditorReactHandlers, type MtEditorReactProps, MtEditor as default };

package/dist/index.js

@@ -0,0 +1,84 @@
+import { forwardRef, useRef, useEffect, useImperativeHandle } from 'react';
+import { MtEditor as MtEditor$1 } from '@mteditor/core';
+import { jsx } from 'react/jsx-runtime';
+
+// src/component.tsx
+var applyRuntimeOptions = (instance, options) => {
+  if (options.theme !== void 0) instance.setTheme(options.theme);
+  if (options.locale !== void 0) instance.setLocale(options.locale);
+  if (options.readonly !== void 0) instance.setReadonly(options.readonly);
+};
+var MtEditor = forwardRef((props, ref) => {
+  const hostRef = useRef(null);
+  const instanceRef = useRef(null);
+  const propsRef = useRef(props);
+  useEffect(() => {
+    propsRef.current = props;
+  });
+  useEffect(() => {
+    const element = hostRef.current;
+    if (element === null) return void 0;
+    const { content: initialContent, ...restOptions } = propsRef.current.options ?? {};
+    const editor = new MtEditor$1({
+      ...restOptions,
+      element,
+      content: propsRef.current.value ?? initialContent,
+      onChange: (payload) => propsRef.current.onChange?.(payload),
+      // `ready` 在构造期就已派发，因此它走构造选项；其余事件走总线订阅
+      onReady: (payload) => propsRef.current.onReady?.(payload),
+      onError: (payload) => propsRef.current.onError?.(payload)
+    });
+    const offs = [
+      editor.on("focus", (payload) => propsRef.current.onFocus?.(payload)),
+      editor.on("blur", (payload) => propsRef.current.onBlur?.(payload)),
+      editor.on(
+        "selectionChange",
+        (payload) => propsRef.current.onSelectionChange?.(payload)
+      ),
+      editor.on("destroy", (payload) => propsRef.current.onDestroy?.(payload))
+    ];
+    instanceRef.current = editor;
+    return () => {
+      instanceRef.current = null;
+      editor.destroy();
+      for (const off of offs) off();
+    };
+  }, []);
+  const { value, className, style } = props;
+  useEffect(() => {
+    const editor = instanceRef.current;
+    if (editor === null || value === void 0) return;
+    editor.setJSON(value);
+  }, [value]);
+  const theme = props.options?.theme;
+  const locale = props.options?.locale;
+  const readonly = props.options?.readonly;
+  useEffect(() => {
+    const editor = instanceRef.current;
+    if (editor !== null) applyRuntimeOptions(editor, { theme, locale, readonly });
+  }, [theme, locale, readonly]);
+  useImperativeHandle(
+    ref,
+    () => ({
+      get editor() {
+        return instanceRef.current;
+      }
+    }),
+    []
+  );
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: hostRef,
+      className: className === void 0 ? "mt-editor-host" : `mt-editor-host ${className}`,
+      style,
+      "data-mt-adapter": "react"
+    }
+  );
+});
+MtEditor.displayName = "MtEditor";
+var component_default = MtEditor;
+
+export { MtEditor, component_default as default };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/component.tsx"],"names":["MtCoreEditor"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * React 适配组件（AGENTS.md §8.2）。\n *\n * 它是**薄壳**（§8.1）：只做挂载 / 卸载、props → 选项映射、增量更新、事件透传与受控值回灌。\n * 任何编辑逻辑都写在 `@mteditor/core`，写在这里视为违规。\n *\n * ## 三条关键设计（ADR-0028 决策 4）\n *\n * 1. **挂载 effect 只跑一次（`[]` 依赖）**。React 的内联箭头函数每次渲染都是新的引用，\n *    若把 `onChange` 之类的 props 放进依赖数组，用户每敲一个字就会「销毁 → 重建」实例，\n *    选区、撤销栈与 IME composition 状态全丢。做法是把最新 props 存进一个 ref，\n *    构造时传的闭包只从 ref 里读 —— 依赖数组因此可以是空的。\n * 2. **这里不做回声抑制**。宿主把编辑器刚给出的文档灌回来是受控组件的必然结果，\n *    而「灌回来的是同一份内容就不该碰视图」这条判据写在**内核**\n *    （`MtEngine.setDocument()` 的结构等价短路）。适配层再判一次等于两处判据，\n *    且 6 个适配端会各判各的。\n * 3. **结构性选项挂载时读取一次**。内核没有「运行时换档」的能力\n *    （`platform` / `ui` / `placeholder` / `historyDepth` 等都没有 setter），\n *    因此本组件不假装支持它。要换档请用 React 的重挂载机制（`key`）。\n *\n * ## 严格模式双挂载\n *\n * 开发模式下 React 会把 effect 执行两遍（挂载 → 清理 → 再挂载）来暴露副作用泄漏。\n * 本组件的清理函数会 `destroy()` 实例并退订全部监听，因此第二轮拿到的是一张干净的白纸；\n * 「页面上只剩一个 `.mt-editor`、内容不重复、监听不叠加」由单测与 E2E 守（§8.2 必测项）。\n */\n\nimport { forwardRef, useEffect, useImperativeHandle, useRef } from 'react'\n\nimport { MtEditor as MtCoreEditor } from '@mteditor/core'\nimport type {\n  MtAdapterOptions,\n  MtChangePayload,\n  MtErrorPayload,\n  MtSelectionInfo,\n} from '@mteditor/core'\n\nimport type { MtEditorReactHandle, MtEditorReactProps } from './types'\n\n/** 能就地同步的选项子集。类型取自 `MtAdapterOptions`，不另立一份定义 */\ntype MtRuntimeOptions = Pick<MtAdapterOptions, 'theme' | 'locale' | 'readonly'>\n\n/**\n * 把可在**运行时**就地同步的选项写进已存在的内核实例。\n *\n * 只覆盖 `theme` / `locale` / `readonly` 三项 —— 内核只为这三项提供了 setter\n * （`setTheme` / `setLocale` / `setReadonly`）。其余选项\n * （`platform` / `ui` / `placeholder` / `plugins` / `historyDepth` /\n * `changeDebounce` / `selectionThrottle`）**在挂载时读取一次**，\n * 要换档请用 React 的重挂载机制（`key`）。\n *\n * 白名单是刻意的：内核将来新增运行时 setter 时，需要**显式**加进这里才会生效 ——\n * 比「默认尝试同步」安全，因为后者会让 `ui` 之类的结构性选项被半途写入而非完整重建。\n *\n * @param instance 内核实例\n * @param options 只含「能就地改」的三项\n */\nconst applyRuntimeOptions = (instance: MtCoreEditor, options: MtRuntimeOptions): void => {\n  if (options.theme !== undefined) instance.setTheme(options.theme)\n  if (options.locale !== undefined) instance.setLocale(options.locale)\n  if (options.readonly !== undefined) instance.setReadonly(options.readonly)\n}\n\n/**\n * `<MtEditor>` —— React 的 MtEditor 组件。\n *\n * @example\n * ```tsx\n * import { useRef, useState } from 'react'\n * import { MtEditor } from '@mteditor/react'\n * import type { MtDocument, MtEditorReactHandle } from '@mteditor/react'\n * import '@mteditor/theme-default/index.css'\n *\n * export const App = () => {\n *   const [doc, setDoc] = useState<MtDocument>()\n *   const ref = useRef<MtEditorReactHandle>(null)\n *\n *   return (\n *     <MtEditor\n *       ref={ref}\n *       value={doc}\n *       onChange={(payload) => setDoc(payload.json)}\n *       options={{ placeholder: '请输入…', theme: 'light' }}\n *     />\n *   )\n * }\n * ```\n */\nexport const MtEditor = forwardRef<MtEditorReactHandle, MtEditorReactProps>((props, ref) => {\n  /** 挂载容器。由本组件创建，且**不给它任何子节点** —— React 因此不会碰内核建的 DOM */\n  const hostRef = useRef<HTMLDivElement | null>(null)\n  /** 内核实例。用 ref 而不是 state：实例变化不需要重绘（句柄走 getter 读实时值） */\n  const instanceRef = useRef<MtCoreEditor | null>(null)\n  /** 最新 props。让「只跑一次」的挂载 effect 也能读到当下的回调（见文件头设计 1） */\n  const propsRef = useRef(props)\n\n  // 不用依赖数组：每次提交后同步一次最新 props 即可\n  useEffect(() => {\n    propsRef.current = props\n  })\n\n  // 挂载 / 卸载。**依赖数组必须是空的** —— 见文件头设计 1\n  useEffect(() => {\n    const element = hostRef.current\n    if (element === null) return undefined\n\n    // `options.content` 语义是「初始内容」；受控值一旦给出就优先于它。\n    // 必须先摘出来再展开，否则 `...options` 会把 `content` 覆盖回旧值。\n    const { content: initialContent, ...restOptions } = propsRef.current.options ?? {}\n\n    const editor = new MtCoreEditor({\n      ...restOptions,\n      element,\n      content: propsRef.current.value ?? initialContent,\n      onChange: (payload: MtChangePayload) => propsRef.current.onChange?.(payload),\n      // `ready` 在构造期就已派发，因此它走构造选项；其余事件走总线订阅\n      onReady: (payload) => propsRef.current.onReady?.(payload),\n      onError: (payload: MtErrorPayload) => propsRef.current.onError?.(payload),\n    })\n\n    const offs = [\n      editor.on('focus', (payload) => propsRef.current.onFocus?.(payload)),\n      editor.on('blur', (payload) => propsRef.current.onBlur?.(payload)),\n      editor.on('selectionChange', (payload: MtSelectionInfo) =>\n        propsRef.current.onSelectionChange?.(payload),\n      ),\n      editor.on('destroy', (payload) => propsRef.current.onDestroy?.(payload)),\n    ]\n\n    instanceRef.current = editor\n\n    return () => {\n      instanceRef.current = null\n      // 先销毁再退订：`destroy` 事件本身要透给宿主\n      editor.destroy()\n      for (const off of offs) off()\n    }\n  }, [])\n\n  // 「编辑器 → 宿主」由 onChange 完成；这里只做「宿主 → 编辑器」。\n  // 内核的结构等价短路保证回灌同一个文档时不会重置光标（ADR-0028 决策 2）。\n  const { value, className, style } = props\n  useEffect(() => {\n    const editor = instanceRef.current\n    if (editor === null || value === undefined) return\n    editor.setJSON(value)\n  }, [value])\n\n  // 选项变化：只同步能在运行时就地改的那几个（结构性选项挂载时读取一次）\n  const theme = props.options?.theme\n  const locale = props.options?.locale\n  const readonly = props.options?.readonly\n  useEffect(() => {\n    const editor = instanceRef.current\n    if (editor !== null) applyRuntimeOptions(editor, { theme, locale, readonly })\n  }, [theme, locale, readonly])\n\n  // 句柄用 getter 读实时值：实例在挂载 effect 里才产生，渲染期取值只能取到 `null`\n  useImperativeHandle(\n    ref,\n    () => ({\n      get editor() {\n        return instanceRef.current\n      },\n    }),\n    [],\n  )\n\n  // 内核根容器在这个 div 内部，宿主若要整体样式钩子，用 `data-mt-adapter`。\n  // React 不会像 Vue 那样自动透传 class / style，故这两个 prop 需要显式声明。\n  return (\n    <div\n      ref={hostRef}\n      className={className === undefined ? 'mt-editor-host' : `mt-editor-host ${className}`}\n      style={style}\n      data-mt-adapter=\"react\"\n    />\n  )\n})\n\n/** 组件展示名。React DevTools 里显示为 `MtEditor` 而不是 `ForwardRef` */\nMtEditor.displayName = 'MtEditor'\n\nexport default MtEditor\n"]}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@mteditor/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "MtEditor 的 React 适配层：forwardRef 薄壳，严格模式双挂载幂等",
+  "keywords": [
+    "mteditor",
+    "react",
+    "editor",
+    "rich-text"
+  ],
+  "license": "MIT",
+  "homepage": "https://gitee.com/meilitao/editor",
+  "bugs": {
+    "url": "https://gitee.com/meilitao/editor/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/meilitao/editor.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mteditor/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^18.3.18",
+    "happy-dom": "^15.11.7",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "clean": "rimraf dist .turbo"
+  }
 }