diff --git a/docs/guide/index.md b/docs/guide/index.md
index 14e68682..09d6a2ad 100644
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -1,6 +1,15 @@
# 快速开始
-tmagic-editor的编辑器我们已经封装成一个 npm 包，可以直接安装使用。编辑器是使用 vue3 开发的(仅支持vue3)，但使用编辑器的业务(runtime)可以不限框架，可以用 vue2、react 等开发业务组件。
+tmagic-editor 的编辑器已经封装成 npm 包，可以直接安装使用。编辑器使用 Vue 3 开发（**仅支持 Vue 3**），但承载真实业务的 runtime 不限框架，可以使用 Vue 2、Vue 3、React 等开发业务组件。
+
+整个项目结构由两部分组成：
+
+- **admin-client**（编辑器 / 管理端）：基于 `@tmagic/editor`，加载 runtime iframe、提供拖拽/属性配置/发布等能力。
+- **runtime**（运行时）：负责解析 DSL 并渲染页面，分为编辑器内嵌的 `playground` 和线上发布使用的 `page` 两个产物。
+
+> 仓库 [`playground/`](https://github.com/Tencent/tmagic-editor/tree/master/playground) 与 [`runtime/vue/`](https://github.com/Tencent/tmagic-editor/tree/master/runtime/vue) 就是一份完整可运行的最小实践，本节内容均与之对齐，可以对照阅读源码。
+
+## 使用脚手架创建（推荐）
::: code-group
@@ -11,220 +20,423 @@ $ npm create tmagic@latest
```bash [pnpm]
$ pnpm create tmagic
```
+
:::
-按照提示操作可以创建`6`种项目：
+按照交互式提示，可以创建以下 `6` 种项目：
-* runtime:运行时（DSL渲染）
-* admin-client:管理端（编辑器）
-* components:组件库(组件/插件/数据源)
-* component:组件
-* data-source:数据源
-* plugin:插件
+| 类型 | 说明 |
+| -------------- | ------------------------------ |
+| `runtime` | 运行时（DSL 渲染） |
+| `admin-client` | 管理端（编辑器） |
+| `components` | 组件库（组件 / 插件 / 数据源） |
+| `component` | 单个组件 |
+| `data-source` | 单个数据源 |
+| `plugin` | 单个插件 |
-至少需要一个runtime与admin-client后，就可以运行起一个最简单的项目了。
-
-后续还需要新增组件、插件、数据源等，可以继续添加后面几种类型的项目。
-
-新增好一个组件/插件/数据源后可以到runtime/tmagic.config.ts中配置到packages中
+最少需要一个 `runtime` 加一个 `admin-client`，就能跑起一个完整的可视化搭建流程。后续可以再陆续创建组件、插件、数据源；新建好后到 `runtime/tmagic.config.ts` 的 `packages` 中注册即可，参考[组件开发](./component.md) 与[页面发布 § @tmagic/cli](./publish.md#tmagic-cli)。
## 手动安装
-node.js >= 18
+::: tip 环境要求
-可以通过[Vite](https://cn.vitejs.dev/) 或 [Vue CLI](https://cli.vuejs.org/zh/)快速创建项目。
+- Node.js `^20.19.0 || >=22.12.0`
+- 推荐使用 [Vite](https://cn.vitejs.dev/)；如果使用 [Vue CLI](https://cli.vuejs.org/zh/) 需要在 `vue.config.js` 中加上 `transpileDependencies: [/@tmagic/]`
+ :::
-> 使用Vue CLI生成的项目需要在vue.config.js中加上配置：transpileDependencies: [/@tmagic/]
+### 1. 安装编辑器依赖
+
+`@tmagic/editor` 把内部使用到的 UI 组件抽象到了 `@tmagic/design`，通过 **adapter** 的形式接入具体的 UI 组件库。我们提供了：
+
+- [`@tmagic/element-plus-adapter`](https://github.com/Tencent/tmagic-editor/tree/master/packages/element-plus-adapter)：接入 [Element Plus](https://element-plus.org/)
+- [`@tmagic/tdesign-vue-next-adapter`](https://github.com/Tencent/tmagic-editor/tree/master/packages/tdesign-vue-next-adapter)：接入 [TDesign Vue Next](https://tdesign.tencent.com/vue-next/overview)
+
+任选其一即可，下面以 Element Plus 为例：
```bash
-$ npm install @tmagic/editor -S
+$ npm install @tmagic/editor @tmagic/core @tmagic/element-plus-adapter element-plus -S
```
-由于在实际应用中项目常常会用到例如[element-plus](https://element-plus.org/)、[tdesign-vue-next](https://tdesign.tencent.com/vue-next/overview)等UI组件库。为了能让使用者能够选择不同UI库，[@tmagic/editor](https://github.com/Tencent/tmagic-editor/tree/master/packages/editor)将其中使用到的UI组件封装到[@tmagic/design](https://github.com/Tencent/tmagic-editor/tree/master/packages/design)中，然后通过不同的adapter来指定使用具体的对应的UI库，我们提供了[@tmagic/element-plus-adapter](https://github.com/Tencent/tmagic-editor/tree/master/packages/element-plus-adapter)来支持[element-plus](https://element-plus.org/)，所以还需要安装相关的依赖。
-
-```bash
-$ npm install @tmagic/element-plus-adapter element-plus -S
-```
-
-editor 中还包含了[monaco-editor](https://microsoft.github.io/monaco-editor/)，所以还需安装monaco-editor，可以参考 monaco-editor 的[配置指引](https://github.com/microsoft/monaco-editor/blob/main/docs/integrate-esm.md)。
+`@tmagic/editor` 内部使用了 [monaco-editor](https://microsoft.github.io/monaco-editor/) 作为代码编辑器，需要额外安装并按照官方[配置指引](https://github.com/microsoft/monaco-editor/blob/main/docs/integrate-esm.md)注入 worker：
```bash
$ npm install monaco-editor -S
```
-## 快速上手
+### 2. 引入 @tmagic/editor
-## 引入 @tmagic/editor
+参考 [`playground/src/main.ts`](https://github.com/Tencent/tmagic-editor/blob/master/playground/src/main.ts)，在入口文件中按以下顺序完成 Monaco worker、UI 库样式、editor 样式与 adapter 的注入：
-在 main.js 中写入以下内容：
+```ts
+import { createApp } from "vue";
+import EditorWorker from "monaco-editor/esm/vs/editor/editor.worker?worker";
+import CssWorker from "monaco-editor/esm/vs/language/css/css.worker?worker";
+import HtmlWorker from "monaco-editor/esm/vs/language/html/html.worker?worker";
+import JsonWorker from "monaco-editor/esm/vs/language/json/json.worker?worker";
+import TsWorker from "monaco-editor/esm/vs/language/typescript/ts.worker?worker";
-```js
-import { createApp } from 'vue';
-import ElementPlus from 'element-plus';
-import zhCn from 'element-plus/es/locale/lang/zh-cn';
+import editorPlugin from "@tmagic/editor";
+import MagicElementPlusAdapter from "@tmagic/element-plus-adapter";
-import editorPlugin from '@tmagic/editor';
-import MagicElementPlusAdapter from '@tmagic/element-plus-adapter';
+import App from "./App.vue";
-import App from './App.vue';
+import "element-plus/dist/index.css";
+import "@tmagic/editor/dist/style.css";
-import 'element-plus/dist/index.css';
-import '@tmagic/editor/dist/style.css';
+// @ts-ignore
+globalThis.MonacoEnvironment = {
+ getWorker(_: any, label: string) {
+ if (label === "json") return new JsonWorker();
+ if (["css", "scss", "less"].includes(label)) return new CssWorker();
+ if (["html", "handlebars", "razor"].includes(label))
+ return new HtmlWorker();
+ if (["typescript", "javascript"].includes(label)) return new TsWorker();
+ return new EditorWorker();
+ },
+};
-const app = createApp(App);
-app.use(ElementPlus, {
- locale: zhCn,
-});
-app.use(editorPlugin, MagicElementPlusAdapter);
-app.mount('#app');
+createApp(App).use(editorPlugin, MagicElementPlusAdapter).mount("#app");
```
-以上代码便完成了 @tmagic/editor 的引入。需要注意的是，样式文件需要单独引入。
+::: tip 切换 UI 适配器
+playground 通过 `sessionStorage` 来切换 adapter，参考实现：
-可以参考我们提供的[Playground](https://github.com/Tencent/tmagic-editor/blob/master/playground/src/main.ts)示例实现代码
+```ts
+const adapter =
+ sessionStorage.getItem("tmagic-playground-ui-adapter") || "element-plus";
+const adapterModule =
+ adapter === "tdesign-vue-next"
+ ? import("@tmagic/tdesign-vue-next-adapter")
+ : import("@tmagic/element-plus-adapter");
+```
-## 使用 m-editor 组件
+:::
-在 App.vue 中写入以下内容：
+::: tip 常见报错
-```html
+1. `Preprocessor dependency "sass" not found.` —— 安装 sass：`npm i sass -D`
+2. `Uncaught ReferenceError: global is not defined` —— Vite 项目需要在 `vite.config.ts` 中加上：
+
+```ts
+// vite 8以下版本
+optimizeDeps: {
+ esbuildOptions: {
+ define: { global: 'globalThis' },
+ },
+}
+```
+
+```ts
+// vite 8及以上
+define: {
+ global: 'globalThis',
+},
+```
+
+:::
+
+### 3. 渲染 m-editor
+
+在 `App.vue` 中渲染 ``（即 `m-editor` 组件），最少需要传入 `v-model`、`runtime-url`、`component-group-list`、`props-configs`、`props-values` 五个核心属性：
+
+```vue
-
-
+
+
+
-
```
-关于 [@tmagic/editor](https://github.com/Tencent/tmagic-editor/tree/master/packages/editor) 组件，更多的属性配置详情请参考[编辑器 API](../api/editor/props.md)。
+完整的菜单/预览/键盘快捷键实现可以参考 [`playground/src/pages/Editor.vue`](https://github.com/Tencent/tmagic-editor/blob/master/playground/src/pages/Editor.vue)。
-其中，**有四个需要注意的属性配置项**：`runtimeUrl` `propsValues` `propsConfigs` `componentGroupList`。这是能让我们的编辑器正常运行的关键。
+更多 prop 详见[编辑器 API](../api/editor/props.md)，下文重点介绍最关键的 4 个：`runtimeUrl`、`componentGroupList`、`propsConfigs/propsValues`、初始 DSL（`v-model`）。
-:::tip
-如果出现```Preprocessor dependency "sass" not found. Did you install it?```，那么需要install sass
+## runtimeUrl
-```bash
-npm install sass -D
-```
-:::
+编辑器中央的模拟器画布是一个 `iframe`，`runtimeUrl` 就是这个 iframe 加载的地址，里面运行着一份 **playground runtime**，负责响应编辑器中组件的增删改查。
-:::tip
-如果是使用vite构建工具，如果出现 ```Uncaught ReferenceError: global is not defined```，那么需要再vite.config.js中添加如下配置：
+playground 中通过 Vite proxy 把 runtime 服务（默认端口 `8078`）代理到了同一个域：
-```js
-{
- optimizeDeps: {
- esbuildOptions: {
- define: {
- global: 'globalThis',
- },
+```ts
+server: {
+ port: 8098,
+ proxy: {
+ '^/tmagic-editor/playground/runtime': {
+ target: 'http://127.0.0.1:8078',
+ changeOrigin: true,
+ prependPath: false,
},
},
}
```
-:::
-## runtimeUrl
-
-该配置涉及到 [runtime 概念](runtime.md)，tmagic-editor编辑器中心的模拟器画布，是一个 iframe（这里的 `runtimeUrl` 配置的，就是你提供的 iframe 的 url），其中渲染了一个 runtime，用来响应编辑器中的组件增删改等操作。
-:::tip
-可以使用`npm create tmagic` 来快速创建一个runtime项目。
-:::
+实际项目中可以使用 `npm create tmagic` 快速生成一个 runtime 项目，详见[RUNTIME](./runtime.md)。
## componentGroupList
-`componentGroupList` 是指定左侧组件库内容的配置。此处定义了在编辑器组件库中有什么组件。在添加的时候通过组件 `type` 来确定 runtime 中要渲染什么组件。可以参考 [componentGroupList 配置](../api/editor/props.html#componentgrouplist)。
+`componentGroupList` 决定左侧组件库展示哪些组件分组。每个 item 通过 `type` 与 runtime 中注册的组件类型一一对应，添加到画布时编辑器会基于 `type` 通知 runtime 渲染对应组件。
-## propsConfigs/propsValues
+```ts
+import {
+ Files,
+ FolderOpened,
+ PictureFilled,
+ SwitchButton,
+ Tickets,
+} from "@element-plus/icons-vue";
+import type { ComponentGroup } from "@tmagic/editor";
-`propsConfigs` `propsValues` 和 `componentGroupList` 中声明的组件是一一对应的，通过 `type` 来识别属于哪个组件，该配置涉及的内容，就是组件的表单配置描述，在[组件开发中](./component.md)会通过 formConfig 配置来声明这份内容。
-
-`configs` 既可以通过 hardcode 方式写上每个组件的表单配置，也可以通过组件打包方式得到对应内容，然后通过异步加载来载入。比如：
-
-```javascript
-setup() {
- asyncLoadJs(`/runtime/vue/assets/config.js`).then(() => {
- propsConfigs.value = window.magicPresetConfigs;
- });
- asyncLoadJs(`/runtime/vue/assets/value.js`).then(() => {
- propsValues.value = window.magicPresetValues;
- });
-}
+export default [
+ {
+ title: "示例容器",
+ items: [
+ { icon: FolderOpened, text: "组", type: "container" },
+ { icon: FolderOpened, text: "蒙层", type: "overlay" },
+ { icon: Files, text: "迭代器容器", type: "iterator-container" },
+ ],
+ },
+ {
+ title: "示例组件",
+ items: [
+ { icon: Tickets, text: "文本", type: "text" },
+ { icon: SwitchButton, text: "按钮", type: "button" },
+ { icon: PictureFilled, text: "图片", type: "img" },
+ ],
+ },
+ // 也可以提供完整 schema 作为「组合」，添加时直接落入完整子树
+ {
+ title: "组合",
+ items: [
+ {
+ icon: Tickets,
+ text: "弹窗",
+ data: {
+ type: "overlay",
+ name: "弹窗",
+ style: {
+ position: "fixed",
+ width: "100%",
+ height: "100%",
+ top: 0,
+ left: 0,
+ },
+ items: [
+ /* ... */
+ ],
+ },
+ },
+ ],
+ },
+] as ComponentGroup[];
```
-::: tip 如何快速得到一个 configs/values
-上述的 runtime 产物中，dist 目录中即包含一个 entry 文件夹，在你的项目组件初始化之后，分别异步加载里面的config/index.umd.js、value/index.umd.js。并如上面代码中，赋值给 configs/values 即可。
+完整字段参考 [`componentGroupList`](../api/editor/props.md#componentgrouplist)。
+
+## propsConfigs / propsValues
+
+`propsConfigs` `propsValues` 与 `componentGroupList` 中声明的组件通过 `type` 一一对应：
+
+- `propsConfigs[type]`：组件**右侧表单**的配置描述（在组件中 `formConfig` 字段提供）。
+- `propsValues[type]`：组件被添加到画布时的**初始默认值**（在组件中 `initValue` 字段提供）。
+
+这些内容会通过 `@tmagic/cli` 在 runtime 构建时打包出对应的 UMD 文件，编辑器异步加载即可。playground 中的真实做法（[`use-editor-res.ts`](https://github.com/Tencent/tmagic-editor/blob/master/playground/src/pages/composables/use-editor-res.ts)）：
+
+```ts
+import { ref } from "vue";
+import { asyncLoadJs } from "@tmagic/editor";
+
+const { VITE_ENTRY_PATH } = import.meta.env;
+
+export const useEditorRes = () => {
+ const propsValues = ref>({});
+ const propsConfigs = ref>({});
+ const eventMethodList = ref>({});
+ const datasourceConfigs = ref>({});
+ const datasourceValues = ref>({});
+ const datasourceEventMethodList = ref>({
+ base: { events: [], methods: [] },
+ });
+
+ asyncLoadJs(`${VITE_ENTRY_PATH}/config/index.umd.cjs`).then(() => {
+ propsConfigs.value = (globalThis as any).magicPresetConfigs;
+ });
+ asyncLoadJs(`${VITE_ENTRY_PATH}/value/index.umd.cjs`).then(() => {
+ propsValues.value = (globalThis as any).magicPresetValues;
+ });
+ asyncLoadJs(`${VITE_ENTRY_PATH}/event/index.umd.cjs`).then(() => {
+ eventMethodList.value = (globalThis as any).magicPresetEvents;
+ });
+ asyncLoadJs(`${VITE_ENTRY_PATH}/ds-config/index.umd.cjs`).then(() => {
+ datasourceConfigs.value = (globalThis as any).magicPresetDsConfigs;
+ });
+ asyncLoadJs(`${VITE_ENTRY_PATH}/ds-value/index.umd.cjs`).then(() => {
+ datasourceValues.value = (globalThis as any).magicPresetDsValues;
+ });
+
+ return {
+ propsValues,
+ propsConfigs,
+ eventMethodList,
+ datasourceConfigs,
+ datasourceValues,
+ datasourceEventMethodList,
+ };
+};
+```
+
+::: tip 怎样得到这些 UMD 文件？
+在 runtime 项目中执行 `npm run build:libs`（参考 [`runtime/vue/package.json`](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue/package.json)），会在 `dist/entry/` 下生成 `config/value/event/ds-config/ds-value` 五个目录的 UMD 文件，全局变量分别为 `magicPresetConfigs` `magicPresetValues` `magicPresetEvents` `magicPresetDsConfigs` `magicPresetDsValues`。
:::
-## 更多
+如果是在调试期，也可以直接 hardcode 一份 `propsConfigs` / `propsValues`，比如：
-通过上述步骤，可以快速得到一个初始化的简单编辑器。
+```ts
+const propsConfigs = ref({
+ text: [{ name: "text", text: "文案" }],
+ button: [{ name: "text", text: "按钮文案" }],
+});
-除了上述内容外，文档的其他章节中，也会更深入的描述整个tmagic-editor的设计理念和实现细节。同时你也可以查看我们的[项目源码](https://github.com/Tencent/tmagic-editor)，从源码提供的 playground 和 runtime 示例来开发和理解tmagic-editor。
+const propsValues = ref({
+ text: { text: "一段文字" },
+ button: { text: "按钮" },
+});
+```
+
+## v-model：DSL 初始值
+
+`v-model` 绑定的是整个页面的 [DSL](./advanced/js-schema.md)，最简的初始 DSL 长这样：
+
+```ts
+import { type MApp, NodeType } from "@tmagic/core";
+
+const dsl: MApp = {
+ id: "1",
+ name: "demo",
+ type: NodeType.ROOT,
+ items: [
+ {
+ type: NodeType.PAGE,
+ id: "page_1",
+ name: "index",
+ layout: "absolute",
+ style: { position: "relative", width: "100%", height: "100%" },
+ items: [],
+ },
+ ],
+};
+```
+
+完整含数据源、代码块、事件联动的 DSL 示例见 [`playground/src/configs/dsl.ts`](https://github.com/Tencent/tmagic-editor/blob/master/playground/src/configs/dsl.ts)。
+
+::: tip 持久化与历史记录
+playground 用 `localStorage` + `serialize-javascript` 做了一个本地持久化方案，并在保存后调用 `editor.editorService.resetModifiedNodeId()` 重置修改状态，可以直接复用。
+:::
+
+## 进阶：编辑器服务与插件
+
+`@tmagic/editor` 提供了多组 **service**（`editorService` / `propsService` / `historyService` / `uiService` …）和 **插件机制**，可以非侵入式扩展行为。例如 playground 中：
+
+```ts
+import { editorService, propsService } from "@tmagic/editor";
+
+editorService.usePlugin({
+ beforeDoAdd: (config, parent) => {
+ if (config.type === "overlay") {
+ // 蒙层始终插入到当前 page 下，并钉到 (0, 0)
+ config.style = { ...config.style, left: 0, top: 0 };
+ return [config, editorService.get("page")];
+ }
+ return [config, parent];
+ },
+});
+
+propsService.usePlugin({
+ beforeFillConfig: (config) => [config, "100px"],
+});
+```
+
+更多扩展能力见[编辑器扩展](./editor-expand.md)与各 service 的 [API 文档](../api/editor/props.md)。
+
+## 下一步
+
+- [基础概念](./conception.md)：编辑器 / 模拟器 / runtime / DSL 的关系
+- [RUNTIME](./runtime.md)：实现并打包一个 runtime
+- [组件开发](./component.md)：自定义业务组件
+- [页面发布](./publish.md)：基于 `@tmagic/cli` 的产物结构与发布流程
+- [Playground 源码](https://github.com/Tencent/tmagic-editor/tree/master/playground)：与本节示例完全对应
+
+通过 `pnpm bootstrap && pnpm pg` 即可在仓库本地启动这份 playground，自由调试。
diff --git a/docs/guide/runtime.md b/docs/guide/runtime.md
index 2ce9fc7c..79e0f18c 100644
--- a/docs/guide/runtime.md
+++ b/docs/guide/runtime.md
@@ -1,29 +1,328 @@
# RUNTIME
-本章详细介绍如何深入理解tmagic-editor的打包，以及如何根据需求定制，修改tmagic-editor的页面打包发布方案。页面发布、打包相关的定制化开发，需要使用tmagic-editor的业务方，搭建好基于开源tmagic-editor的管理平台、存储服务等配套设施。
+
+本章详细介绍 tmagic-editor 中 runtime 的概念、目录结构与实现方式。所有内容均与开源仓库 [`runtime/vue/`](https://github.com/Tencent/tmagic-editor/tree/master/runtime/vue) 一一对应，可以对照阅读。
## runtime 是什么
-runtime是用来解析DSL的执行环境，用于渲染 DSL 呈现页面。
+**runtime 是用来解析 DSL 的执行环境**。编辑器只负责生成 DSL，最终把它**渲染成可见页面**的工作交给 runtime。
-编辑器生成出来的DSL需要通过 runtime 来渲染。
+在一份完整的 tmagic-editor 项目中，runtime 同时承担两个角色：
-## 实现一个 runtime
+| 角色 | 入口 | 用途 |
+| --- | --- | --- |
+| **page** | `runtime/vue/page/` | 线上发布产物，加载 `window.magicDSL` 渲染真实页面 |
+| **playground** | `runtime/vue/playground/` | 编辑器中央 iframe 加载的画布，响应增删改并渲染所见即所得 |
-:::tip
-可以使用`npm create tmagic` 来快速创建一个runtime项目。
+两者共用同一份组件、插件、数据源代码，只在入口（`main.ts` / `App.vue`）上有差异。
+
+::: tip
+DSL、playground 与 editor 之间的通信原理可以前往[教程](/guide/tutorial/)继续了解。
:::
-创建出来的项目会包含page、playground两个目录。
+## 创建 runtime 项目
+
+::: tip
+推荐用 `npm create tmagic@latest` / `pnpm create tmagic` 快速生成 runtime 模板，按提示选择 `runtime` 即可。
+:::
+
+生成的项目结构如下（与 [`runtime/vue/`](https://github.com/Tencent/tmagic-editor/tree/master/runtime/vue) 完全一致）：
+
```bash
-.
-├── page
-├── playground
+runtime/vue
+├── page/ # 线上 page 入口
+│ ├── App.vue
+│ ├── index.html
+│ ├── main.ts
+│ └── utils/
+├── playground/ # 编辑器内 iframe 入口
+│ ├── App.vue
+│ ├── index.html
+│ └── main.ts
+├── public/
+├── scripts/ # build 脚本（res / page / playground / all）
+├── tmagic.config.ts # @tmagic/cli 配置：声明组件、插件、数据源
+├── tmagic.config.local.ts# 本地覆盖配置（可选）
+└── vite.config.ts # 多入口构建：page + playground
```
-page用于生产环境
+## tmagic.config.ts：声明组件 / 插件 / 数据源
-playground用于编辑器中
+`tmagic.config.ts` 是 [@tmagic/cli](./publish.md#tmagic-cli) 的入口，它会扫描 `packages` 列表，生成 `.tmagic/comp-entry.ts` 等 5 个入口文件，runtime 只需要从这些入口里 `import` 即可：
-:::tip
-想要了解DSL的解析以及runtime与编辑器的通信，可以前往[教程](/guide/tutorial/)
+```ts
+import { defineConfig } from '@tmagic/cli';
+
+export default defineConfig({
+ componentFileAffix: '.vue',
+ // 是否使用 vite + 异步组件，详见 page/main.ts 中的 defineAsyncComponent
+ dynamicImport: true,
+ npmConfig: {
+ client: 'pnpm',
+ keepPackageJsonClean: true,
+ },
+ packages: [
+ {
+ // key 为组件 type，需要与编辑器中 componentGroupList 的 type 对应
+ button: '@tmagic/vue-button',
+ container: '@tmagic/vue-container',
+ img: '@tmagic/vue-img',
+ 'iterator-container': '@tmagic/vue-iterator-container',
+ overlay: '@tmagic/vue-overlay',
+ page: '@tmagic/vue-page',
+ 'page-fragment': '@tmagic/vue-page-fragment',
+ 'page-fragment-container': '@tmagic/vue-page-fragment-container',
+ qrcode: '@tmagic/vue-qrcode',
+ text: '@tmagic/vue-text',
+ },
+ ],
+});
+```
+
+`tmagic.config.local.ts` 用于本地覆盖（不会被提交），常见用法是把线上 npm 包临时替换为本地组件目录调试。
+
+执行 `npm run tmagic`（即 `tmagic entry`）后，runtime 根目录下会生成：
+
+```bash
+.tmagic/
+├── comp-entry.ts # page 同步组件入口
+├── async-comp-entry.ts # page 异步组件入口（dynamicImport 时使用）
+├── config-entry.ts # 编辑器右侧表单配置
+├── value-entry.ts # 组件初始值
+├── event-entry.ts # 组件事件 / 方法列表
+├── plugin-entry.ts # 插件入口
+├── datasource-entry.ts # 同步数据源入口
+└── async-datasource-entry.ts # 异步数据源入口
+```
+
+> 详细产物说明见[页面发布 § @tmagic/cli](./publish.md#tmagic-cli)。
+
+## playground runtime 实现
+
+playground 是编辑器中央 iframe 加载的画布，最关键的逻辑就是把编辑器派发的 DSL 变更同步到本地 Vue 状态并触发重新渲染。
+
+`@tmagic/vue-runtime-help` 提供的 `useEditorDsl` Hook 已经帮我们实现了与编辑器的通信（`onRuntimeReady` / `updateRootConfig` / `updatePageId` / `add` / `update` / `remove` 等）；只需要在入口里：
+
+1. 创建 `TMagicApp` 实例，注册组件、数据源、插件；
+2. 通过 `provide('app', app)` 把实例注入子组件；
+3. 在 `App.vue` 里使用 `useEditorDsl()` + `useComponent('page')` 渲染页面。
+
+完整的 [`runtime/vue/playground/main.ts`](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue/playground/main.ts)：
+
+```ts
+import { createApp } from 'vue';
+import TMagicApp, { DataSourceManager, DeepObservedData } from '@tmagic/core';
+
+import App from './App.vue';
+
+import '@tmagic/core/resetcss.css';
+
+DataSourceManager.registerObservedData(DeepObservedData);
+
+Promise.all([
+ import('../.tmagic/comp-entry'),
+ import('../.tmagic/plugin-entry'),
+ import('../.tmagic/datasource-entry'),
+]).then(([components, plugins, dataSources]) => {
+ const vueApp = createApp(App);
+
+ const app = new TMagicApp({
+ ua: window.navigator.userAgent,
+ platform: 'editor',
+ });
+
+ if (app.env.isWeb) {
+ app.setDesignWidth(window.document.documentElement.getBoundingClientRect().width);
+ }
+
+ Object.entries(components.default).forEach(([type, component]: [string, any]) => {
+ app.registerComponent(type, component);
+ });
+
+ Object.entries(dataSources.default).forEach(([type, ds]: [string, any]) => {
+ DataSourceManager.register(type, ds);
+ });
+
+ Object.values(plugins.default).forEach((plugin: any) => {
+ vueApp.use(plugin, { app });
+ });
+
+ window.appInstance = app;
+ vueApp.config.globalProperties.app = app;
+ vueApp.provide('app', app);
+
+ vueApp.mount('#app');
+});
+```
+
+[`playground/App.vue`](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue/playground/App.vue) 出乎意料地短：
+
+```vue
+
+
+
+
+
+```
+
+::: tip 关键点
+- `platform: 'editor'` 告知 `@tmagic/core` 进入编辑模式；
+- `useEditorDsl()` 内部已经调用 `window.magic?.onRuntimeReady({...})`，把 add/update/remove 等回调挂载到全局，编辑器通过 `iframe.contentWindow.magic` 触发；
+- 当 DSL 变化时，`pageConfig` 自动更新；当页面 DOM 渲染完成，`useEditorDsl` 会调用 `magic.onPageElUpdate(...)` 把页面元素同步给编辑器，让选中框能够吸附。
:::
+
+## page runtime 实现（线上发布）
+
+[`runtime/vue/page/main.ts`](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue/page/main.ts) 与 playground 的差别在于：
+
+1. 不需要响应编辑器消息，直接读取 `window.magicDSL`（或 `localPreview` 模式下从 `localStorage` 读取）；
+2. 使用 `defineAsyncComponent` + 异步入口，按需加载组件，**减小首屏体积**；
+3. 数据源走 `registerDataSourceOnDemand`，只注册当前 DSL 用到的；
+4. 注入 `request` 与 `userRender` 等业务侧 API 给组件复用。
+
+```ts
+import { createApp, defineAsyncComponent, resolveDirective, withDirectives } from 'vue';
+
+import TMagicApp, { DataSourceManager, DeepObservedData, getUrlParam, registerDataSourceOnDemand } from '@tmagic/core';
+
+import components from '../.tmagic/async-comp-entry';
+import asyncDataSources from '../.tmagic/async-datasource-entry';
+import plugins from '../.tmagic/plugin-entry';
+
+import request, { service } from './utils/request';
+import AppComponent from './App.vue';
+import { getLocalConfig } from './utils';
+
+import '@tmagic/core/resetcss.css';
+
+DataSourceManager.registerObservedData(DeepObservedData);
+
+const vueApp = createApp(AppComponent);
+vueApp.use(request);
+
+const dsl = ((getUrlParam('localPreview') ? getLocalConfig() : window.magicDSL) || [])[0] || {};
+
+const app = new TMagicApp({
+ ua: window.navigator.userAgent,
+ config: dsl,
+ request: service,
+ curPage: getUrlParam('page'),
+ useMock: Boolean(getUrlParam('useMock')),
+});
+
+app.setDesignWidth(app.env.isWeb ? window.document.documentElement.getBoundingClientRect().width : 375);
+
+Object.entries(components).forEach(([type, component]: [string, any]) => {
+ app.registerComponent(type, defineAsyncComponent(component));
+});
+
+Object.values(plugins).forEach((plugin: any) => {
+ vueApp.use(plugin, { app });
+});
+
+registerDataSourceOnDemand(dsl, asyncDataSources).then((dataSources) => {
+ Object.entries(dataSources).forEach(([type, ds]: [string, any]) => {
+ DataSourceManager.register(type, ds);
+ });
+
+ vueApp.config.globalProperties.app = app;
+ vueApp.provide('app', app);
+ vueApp.mount('#app');
+});
+```
+
+[`page/App.vue`](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue/page/App.vue) 用 `useDsl()`（注意不是 `useEditorDsl`）：
+
+```vue
+
+
+
+
+
+```
+
+## vite 多入口构建
+
+`runtime/vue` 通过单个 vite 工程构建出两份产物（[`vite.config.ts`](https://github.com/Tencent/tmagic-editor/blob/master/runtime/vue/vite.config.ts)）：
+
+```ts
+build: {
+ rolldownOptions: {
+ input: {
+ page: path.resolve(__dirname, './page/index.html'),
+ playground: path.resolve(__dirname, './playground/index.html'),
+ },
+ },
+}
+```
+
+加上 `package.json` 中提供的 build 脚本：
+
+```json
+{
+ "scripts": {
+ "tmagic": "tmagic entry",
+ "dev": "vite --force",
+ "build": "rimraf ./dist && node scripts/build.mjs --type=all",
+ "build:libs": "node scripts/build.mjs --type=res",
+ "build:page": "node scripts/build.mjs --type=page",
+ "build:playground": "node scripts/build.mjs --type=playground"
+ }
+}
+```
+
+最常用的两个：
+
+- `npm run build:libs`：构建 **编辑器侧**用到的 `config / value / event / ds-config / ds-value` 五份 UMD 资源（输出到 `dist/entry/`），编辑器通过 `asyncLoadJs` 异步加载（参考[快速开始 § propsConfigs / propsValues](./index.md#propsconfigs-propsvalues)）。
+- `npm run build`：同时产出 `playground/index.html`、`page/index.html` 与 `entry/`，可以一份产物覆盖编辑器、预览、线上三种场景。
+
+## @tmagic/vue-runtime-help 常用 Hook
+
+| Hook | 作用 |
+| --- | --- |
+| `useEditorDsl()` | playground 入口使用，建立与编辑器通信、维护当前页面 `pageConfig` |
+| `useDsl()` | page 入口使用，从 `window.magicDSL` 中读取并维护 `pageConfig` |
+| `useComponent(type)` | 通过组件 type 解析出已注册的 Vue 组件（找不到时会回退到 `magic-ui-${type}`） |
+| `useApp()` | 取出注入的 `TMagicApp` 实例 |
+| `useComponentStatus()` | 获取组件在编辑器中的展示/禁用状态 |
+
+::: tip
+React runtime 的实现思路完全一致，对应包是 [`@tmagic/react-runtime-help`](https://github.com/Tencent/tmagic-editor/tree/master/runtime/react-runtime-help)，可以参照本节自行迁移。
+:::
+
+## 跨域
+
+playground 是被编辑器以 iframe 形式加载的，开发期需要保证 runtime 服务允许跨域。仓库里的做法是用 Vite 的 proxy 把 runtime 反代到 playground 同域：
+
+```ts
+// playground/vite.config.ts
+server: {
+ port: 8098,
+ proxy: {
+ '^/tmagic-editor/playground/runtime': {
+ target: 'http://127.0.0.1:8078',
+ changeOrigin: true,
+ prependPath: false,
+ },
+ },
+}
+```
+
+如果编辑器和 runtime 跨域部署，需要在 runtime 服务侧返回 `Access-Control-Allow-Origin`，并保证 iframe 的 `postMessage` 同源策略允许双方通信。
+
+## 进一步阅读
+
+- [基础概念](./conception.md)：编辑器、模拟器、runtime 的关系
+- [组件开发](./component.md)：组件四件套（component / form-config / init-value / event）
+- [页面发布](./publish.md)：page.html 注入 DSL 的发布流程
+- [教程](./tutorial/index.md)：从零实现一份 runtime，理解 magic API 与 DSL 解析