@michaeltangseng/schemaai 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { default as schemaAIRenderer } from './renderer/Renderer';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// schemaAI npm-package public entry (初始迁移阶段)
+// 当前仅导出最小可用 Renderer，用于 schema → React 的运行态渲染测试。
+// `EditorStore` 仍在迁移中，暂不作为对外 API 参与构建。
+export { default as schemaAIRenderer } from './renderer/Renderer';

package/dist/renderer/Renderer.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+export interface DemoNodeSchema {
+    id: string;
+    type: string;
+    props?: Record<string, any>;
+    style?: React.CSSProperties;
+    children?: DemoNodeSchema[];
+}
+/**
+ * 最小可用版本：
+ * - 只负责把 schema 渲染成 React 组件树
+ * - 不包含拖拽、选中、高亮、事件编辑等「编辑器态」能力
+ * - 主要用于 npm 包在运行态（runtime）下的集成测试
+ */
+export interface SchemaAIRendererProps {
+    schema: DemoNodeSchema;
+    pageId?: string;
+}
+declare const SchemaAIRenderer: ({ schema }: SchemaAIRendererProps) => JSX.Element;
+export default SchemaAIRenderer;
+//# sourceMappingURL=Renderer.d.ts.map

package/dist/renderer/Renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../src/renderer/Renderer.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AAEH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsDD,QAAA,MAAM,gBAAgB,GAAI,YAAY,qBAAqB,KAAG,GAAG,CAAC,OAEjE,CAAC;AAEF,eAAe,gBAAgB,CAAC"}

package/dist/renderer/Renderer.js

@@ -0,0 +1,25 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+const renderNode = (node) => {
+    const children = (node.children || []).map(child => renderNode(child));
+    // 最小映射：只处理极少数内置类型，其余用 div 包裹
+    if (node.type === 'PluginText') {
+        return (_jsxs("p", { style: node.style, children: [node.props?.text ?? '', children] }, node.id));
+    }
+    if (node.type === 'Container') {
+        return (_jsxs("div", { style: node.style, children: [node.props?.title && (_jsx("h2", { style: { margin: 0, marginBottom: 8, fontSize: 16 }, children: node.props.title })), children] }, node.id));
+    }
+    // 其他类型：简单兜底渲染
+    return (_jsxs("div", { style: {
+            padding: 8,
+            border: '1px dashed #f97316',
+            fontSize: 12,
+            color: '#c2410c',
+            borderRadius: 4,
+            margin: 4,
+            ...(node.style || {}),
+        }, children: [_jsxs("div", { style: { marginBottom: 4 }, children: ["Unknown component type: ", _jsx("code", { children: node.type })] }), children] }, node.id));
+};
+const SchemaAIRenderer = ({ schema }) => {
+    return renderNode(schema);
+};
+export default SchemaAIRenderer;

package/docs/build-dist.md

@@ -0,0 +1,83 @@
+## schemaAI 构建 dist 产物说明
+
+本文档记录如何在本地为 `schemaAI` npm 包构建 `dist` 目录，以及当前构建范围的约定。
+
+---
+
+## 1. 当前构建范围
+
+- **包路径**：`Others/utils-lib/npm-package`
+- **入口文件**：`src/index.ts`
+  - 目前对外仅导出：
+    - `schemaAIRenderer`（最小可用 Renderer，用于将简单 schema 渲染为 React 组件树）
+- **构建排除**：
+  - `src/core/EditorStore.tsx` 暂时被排除在构建之外（仅作为迁移中的镜像文件存在），对应配置见：
+    - `tsconfig.build.json` 中的：
+      ```json
+      "exclude": [
+        "src/core/EditorStore.tsx"
+      ]
+      ```
+
+---
+
+## 2. 构建配置概要
+
+- **`package.json` 关键字段**：
+  - `main`: `dist/index.cjs`
+  - `module`: `dist/index.esm.js`
+  - `types`: `dist/index.d.ts`
+  - `scripts`:
+    - `"build": "tsc -p tsconfig.build.json"`
+    - `"prepare": "npm run build"`（用于 `npm publish` 前自动构建）
+- **`tsconfig.build.json` 核心选项**：
+  - `compilerOptions.outDir`: `dist`
+  - `compilerOptions.rootDir`: `src`
+  - 生成类型声明：`declaration: true`, `declarationMap: true`
+  - 使用 JSX：`jsx: "react-jsx"`
+  - 其他：`esModuleInterop`, `skipLibCheck`, `strict` 等
+
+---
+
+## 3. 本地构建步骤
+
+在目录 `Others/utils-lib/npm-package` 下执行：
+
+```bash
+pnpm install   # 或 npm install
+pnpm run build # 或 npm run build
+```
+
+成功后应看到：
+
+- 生成 `dist/` 目录，包含：
+  - 编译后的 JS 文件（cjs/esm，具体取决于后续 bundler/输出策略）。
+  - `.d.ts` 类型声明文件。
+
+---
+
+## 4. 与测试项目的关系
+
+- 测试项目路径：`tests/schemaai-react-demo`
+- 当前推荐的本地开发/调试方式：
+  - **直接使用本地源码相对导入**：
+    - 在 `schemaai-react-demo/src/App.tsx` 中：
+      ```ts
+      import SchemaAIRenderer from '../../../src/renderer/Renderer';
+      ```
+    - 用于快速验证 Renderer 行为，无需依赖 `npm link` 或已发布包。
+  - 在需要模拟真实 npm 包使用方式时，可以：
+    - 等 `schemaAI` 发布到 npm 后，在独立项目中 `npm install @michaeltangseng/schemaai`；
+    - 或在更简洁的根级 demo 工程中使用 `npm link`。
+
+---
+
+## 5. 后续演进计划（与构建相关）
+
+- 当以下能力迁移完成后，将逐步纳入构建：
+  - 内聚到包内的 `types` / `constants` / `nodeUtils` 等基础依赖。
+  - 经过抽象的 `EditorStore` 能力（对应 `createEngineStore` 等 Public API）。
+- 届时需同步更新：
+  - `tsconfig.build.json` 的 `exclude` 配置（移除 `EditorStore`）。
+  - `src/index.ts` 的导出列表，与 `docs/public-api.md` 中的 Public API 设计保持一致。
+

package/docs/cursor-rule-low-code-engine.mdc

@@ -0,0 +1,66 @@
+---
+description: React Low-Code Engine npm-package 迁移与协作规则（供复制到 .cursor/rules 使用）
+alwaysApply: false
+---
+# React Low-Code Engine npm-package 规则（草案）
+
+> 用途：这是为本项目准备的 Cursor 规则草案，**建议你将本文件内容复制到本机的 `.cursor/rules/` 目录下**，以便 Cursor 在会话开始时优先读取这些约定。
+
+## 1. 作用范围
+
+- 主要作用于：`Others/utils-lib/npm-package/**` 目录下的所有文件。
+- 侧重内容：
+  - npm 包化的引擎核心能力（状态管理、renderer、schema、UIconfig 协议、插件机制）。
+  - 与 `react-low-code-engine` 主工程之间的边界与依赖。
+
+## 2. 总体原则
+
+- **先文档、后代码**：
+  - 任何结构性变更（目录调整、对外 API 变化）应先更新 `docs/migrate-plan.md` / `architecture.md`。
+  - 鼓励在实现前通过文档对齐思路，减少大范围重构。
+- **保持可回滚**：
+  - 迁移时优先采取「复制 + 重构」方式，而不是直接剪切原始文件。
+  - 保持主工程中的旧实现可用，方便 A/B 测试与回退。
+- **Public API 优先稳定**：
+  - 对外导出的 API（`src/index.ts`）一旦发布到 npm，非必要不做 breaking change。
+  - 如需重大变更，先在文档中标明「下一主版本变更计划」。
+
+## 3. 代码风格与模块边界
+
+- **模块划分建议**
+  - `src/core/`：仅包含与引擎生命周期、状态管理、命令系统强相关的逻辑。
+  - `src/renderer/`：仅负责「根据 schema 生成 React 节点树」，避免混入业务路由、鉴权等逻辑。
+  - `src/schema/`：定义 schema 类型、校验逻辑及默认值生成工具。
+  - `src/ui/`：承载与 UIconfig 协议相关的逻辑，将具体 UI 框架（如 antd、MUI）通过适配层隔离开。
+  - `src/plugins/`：统一插件注册与生命周期入口，避免在业务代码中直接操作内部插件表。
+- **依赖方向**
+  - 允许：`core` 依赖 `schema` 类型。
+  - 不鼓励：`renderer` 反向依赖具体业务组件；应通过抽象/配置注入。
+
+## 4. 与主工程的协作方式
+
+- 任何从主工程迁移到 `npm-package` 的模块，需要满足：
+  - 不直接依赖业务路由、鉴权、具体 API 地址等信息。
+  - 对外通过参数/配置注入可变部分（例如后端接口、鉴权 token 获取方式）。
+- 在迁移阶段，优先保证：
+  - 主工程仍可通过「旧路径」访问已有实现。
+  - 新实现通过 `npm link` / workspace 方式引入，逐步替换调用点。
+
+## 5. AI 使用约定（给 Cursor 模型看的）
+
+- 当你（AI）在 `Others/utils-lib/npm-package` 目录下工作时：
+  - **优先查看** `docs/migrate-plan.md` 与（如果存在的话）`docs/architecture.md`，再开始修改代码。
+  - 对于任何可能影响对外 API 的修改：
+    - 先在文档中增补「变更原因、影响范围、迁移方案」。
+  - 如果用户没有明确要求「立刻迁移代码」，优先：
+    - 更新迁移计划、补充 TODO 与接口设计草稿，
+    - 而不是擅自大规模搬运或重构。
+
+## 6. 如何在本机启用本规则
+
+- 建议在本机执行以下步骤（人工操作）：
+  1. 在你的用户目录（例如 `~/.cursor/rules/`）下新建一个文件，例如：`react-low-code-engine-npm-package.mdc`。
+  2. 将本文件的全部内容复制过去并保存。
+  3. 重新打开本项目或新建与该项目相关的会话。
+- 之后，Cursor 会在涉及该项目时优先参考这份规则文档。
+

package/docs/migrate-plan.md

@@ -0,0 +1,145 @@
+## React Low-Code Engine → npm 包迁移规划
+
+本计划用于指导将现有的 **React Low-Code Engine（schemaAI）相关功能**，逐步迁移到 `Others/utils-lib/npm-package` 目录下，打包成可发布到 npm 的独立库。当前阶段 **不迁移任何功能代码，只搭建骨架与约定**。
+
+---
+
+## 1. 目标与约束
+
+- **目标**
+  - **提取通用的低代码引擎能力**（状态管理、schema 渲染器、组件协议等），发布为一个可复用的 npm 包。
+  - 支持在其他项目中通过 `import { ... } from '@your-scope/schemaAI'` 的方式消费。
+  - 保留现有项目中「应用层逻辑 / 具体业务配置」，避免与引擎核心强耦合。
+- **约束**
+  - 迁移过程遵循 **小步快跑** 原则：先骨架、后接口、再内部实现。
+  - 保持现有 `react-low-code-engine` 运行不受影响（严禁一次性大改）。
+  - 优先保证 **向后兼容**：迁移过程中，新旧两套引用方式可并行存在一段时间。
+
+---
+
+## 2. npm-package 目录目标结构
+
+目标目录：`Others/utils-lib/npm-package`（当前阶段只创建目录和文档）
+
+- `src/`
+  - `core/`：核心状态管理、撤销重做、命令系统。
+  - `renderer/`：schema 渲染器（React 组件树构建）。
+  - `schema/`：Schema 类型定义、校验与默认值。
+  - `ui/`：与 `UIconfig` 相关的 UI 原子样式 & 适配层。
+  - `plugins/`：插件机制入口、类型与注册系统。
+  - `index.ts`：对外导出统一入口（最终 npm 包主入口）。
+- `config/`
+  - 构建工具配置（如 `tsconfig.json`、`rollup.config.mts` / `vite.config.ts` 等）。
+- `scripts/`
+  - 发布脚本、构建脚本（例如 `build.mts`、`release.mts` 或简单的 Node 脚本）。
+- `examples/`
+  - 使用示例：最小化 React 项目 / 代码片段，演示如何消费该 npm 包。
+- `tests/`
+  - 针对核心模块的单元测试（可使用 Vitest / Jest）。
+- `docs/`
+  - `migrate-plan.md`（本文件）
+  - `architecture.md`（后续补充：抽象后的 npm 包内部架构）
+  - `usage.md`（后续补充：npm 包使用说明）
+
+> 说明：目录已通过命令预先创建（如存在），后续内容会逐步填充。
+
+---
+
+## 3. 分阶段迁移策略
+
+### Phase 0：骨架与规则（当前阶段）
+
+- [x] 在 `npm-package` 下创建基础目录结构（`src/`, `dist/`, `config/`, `scripts/`, `examples/`, `tests/`, `docs/`）。
+- [ ] 起草 npm 包的 `package.json`（仅文档设计，不立即写入文件）。
+- [x] 编写 `migrate-plan.md`，明确迁移边界、阶段与优先级。
+- [x] 起草项目规则（Cursor `.cursor` 规则文档草案），统一 AI 辅助时的风格与约束。
+
+### Phase 1：抽象边界与公共接口设计
+
+- [x] 梳理当前 `react-low-code-engine` 中属于「引擎层」的模块（**示例清单，后续可补充/调整**）：
+  - **核心状态管理与 command/undo 栈**
+    - `store/EditorStore.tsx`
+      - 负责：多页面管理（`Page`）、当前 `tree`、选中/hover 状态、撤销重做历史（`history.past/future`）、变量与 `runtimeValues`、modal/overlay 管理等。
+      - 逻辑上对应未来 npm 包中的 `createEngineStore` 能力。
+  - **Renderer（基于 schema 的 React 渲染）**
+    - `components/renderer/Renderer.tsx`
+      - 内部 `RenderNode` 等负责：依据 `NodeSchema` + `COMPONENT_REGISTRY` 渲染组件树，处理拖拽布局（`useDragDrop`）、选中/hover 高亮、容器布局（grid/flex 等）、事件绑定与执行（`executeUserCode`），以及基于 `nodeUtils` 的节点查找。
+      - 将来可抽象为 npm 包中的 `schemaAIRenderer` / 运行时渲染核心。
+  - **应用壳与多页面 orchestration（部分属于引擎层、部分是应用层）**
+    - `App.tsx`
+      - 引入 `EditorProvider`（基于 `EditorStore`）、`Canvas`、左/右侧面板、Dashboard 等。
+      - 负责：编辑器与 Dashboard 之间的路由切换、预览窗口打开、导入导出 schema（`ExportModal`）、撤销重做按钮等。
+      - 目前作为「应用壳」存在，其与引擎强相关的逻辑可在后续视情况提炼为可复用的 `schemaAI` 编辑器容器。
+  - **Schema 规范与 UIconfig 协议（待进一步梳理）**
+    - 预计涉及：
+      - 类型定义文件：`types.ts`（例如 `NodeSchema`, `Page`, `EventHandler`, `ThemeConfig`, `RBLayoutPercent` 等）。
+      - 与 UI 原子样式和布局配置相关的常量/工具：`constants` 中与 `COMPONENT_REGISTRY`、默认主题、布局比例等相关的部分。
+      - 文档层面的 UI 协议：`docs/UIconfig.md`。
+  - **插件机制及其生命周期（如图表、地图等）（待列出具体实现文件）**
+    - 已知入口（暂不迁移，仅在此标记）：
+      - `plugins/runtimeRegistry.ts`：运行时组件注册与解析。
+      - `plugins` 目录下的具体插件实现（如 Recharts、MapLibre 等）。
+    - 目标：统一抽象为 npm 包 Public API 中的 `registerPlugin` / `createPlugin` 等。
+- [x] 在文档中定义 **对外暴露的 Public API**（函数、组件、类型），形成初稿：
+  - `createEngineStore(...)`
+  - `<schemaAIRenderer schema={...} />`
+  - `registerPlugin(...)` 等。
+// Public API 已在 `docs/public-api.md` 中维护，后续变更需同步更新该文档。
+- [x] 明确哪些内容只作为 **内部实现**，不对外暴露（第一版约定）：
+  - **内部实现优先**：
+    - `Canvas`、各类编辑器侧边栏面板、Dashboard、Orchestrator 等纯编辑器 UI。
+    - 与具体业务/后端接口强绑定的逻辑（如某些存储实现、业务路由）。
+    - 仅用于内部编辑器交互的 hook（如快捷键、面板展开状态等）。
+  - **公共 API 候选**：
+    - `EditorStore` 的精简版能力（对应 `createEngineStore`）。
+    - 运行态渲染入口（对应 `schemaAIRenderer`），以及未来的编辑态 Renderer 包装层。
+    - 通用 Schema 类型、UIconfig 协议、插件协议。
+
+### Phase 2：代码迁移（只在计划确认后执行）
+
+> 本阶段暂不实施，只在此做预演规划，后续单独执行。
+
+- [ ] 从现有项目中 **复制**（非剪切）核心模块到 `src/` 对应目录，保持原始路径下仍可运行。
+- [ ] 调整导出结构，使 `src/index.ts` 能对外导出稳定 API。
+- [ ] 引入必要的构建配置（TS 编译、打包为 CJS/ESM），仍然只在 `npm-package` 内生效。
+
+### Phase 3：本地验证与渐进集成
+
+- [ ] 在 `examples/` 中新增一个小型 React 示例，使用 `npm-package` 提供的引擎能力。
+- [ ] 在主工程中，选择一小块功能（例如单页面 renderer），改为从 `npm-package` 引入：
+  - 新路径：`import { Renderer } from '@your-scope/schemaAI'`
+  - 保留旧路径，便于 A/B 对比与回滚。
+- [ ] 通过本地 `npm link` 或 `pnpm/yarn workspaces` 连接主工程与 `npm-package`。
+
+### Phase 4：发布准备与 npm 发布
+
+- [ ] 编写 `usage.md` 与对外 `README.md`（放在 `npm-package` 内）。
+- [ ] 根据 `Others/utils-lib/examples` 下 `nzp-cli` 的 `PUBLISH.md` 和 `2FA_SETUP.md`，复用/裁剪一套 **发布 checklist**。
+- [ ] 完成 `package.json` 中的：
+  - `name`, `version`, `main`, `module`, `types`, `files`, `scripts`, `repository`, `license` 等字段。
+- [ ] 本地构建、自动化测试通过后，执行 `npm publish`（具体命令与 2FA 细节参照 `nzp-cli` 经验）。
+
+---
+
+## 4. 与现有工程的关系
+
+- 迁移过程中，`react-low-code-engine` 仍然是主工程，`npm-package` 是一个「提炼出来的引擎子模块」。
+- 优先把以下部分抽象为 npm 包能力：
+  - **通用引擎**：schema 驱动渲染、状态管理、命令系统。
+  - **插件协议**：统一插件注册/生命周期/配置格式。
+  - **UIconfig 协议**：与样式系统解耦，但暴露统一配置方式。
+- 保持以下部分留在主工程中：
+  - 业务级 Dashboard、应用管理逻辑。
+  - 与具体业务绑定的 schema 模板。
+
+---
+
+## 5. 后续文档与协作约定
+
+- 所有迁移决策（例如「某模块是否进入 npm 包」）应在本文件或 `docs/architecture.md` 中有简短记录。
+- 每个 Phase 开始前，优先更新本计划，列出本阶段的「待确认问题」与「完成标准」。
+- 如需调整目录结构或导出 API，优先更新：
+  - 本文件（迁移节奏与范围）
+  - `architecture.md`（结构 & 依赖关系）
+  - `usage.md`（对外使用方式）
+

package/docs/public-api.md

@@ -0,0 +1,297 @@
+## React Low-Code Engine npm 包 Public API 设计（初稿）
+
+> 本文档仅定义 **目标 API 形态**，当前阶段不迁移代码，只用于在实现前对齐「对外怎么用」。
+
+---
+
+## 1. 包信息（预期）
+
+- **包名（待定示例）**：`@your-scope/schemaAI`  
+- **入口文件**：
+  - `main`：`dist/index.cjs`
+  - `module`：`dist/index.esm.js`
+  - `types`：`dist/index.d.ts`
+- **目标消费者**：
+  - React 应用（最低支持 React 18+）
+  - TypeScript 工程（完整类型导出）
+
+---
+
+## 2. 顶层导出概览
+
+假设用户在外部项目中的典型使用方式：
+
+```ts
+import {
+  createEngineStore,
+  schemaAIProvider,
+  schemaAIRenderer,
+  registerPlugin,
+  defineComponentSchema,
+  useEngineState,
+} from '@your-scope/schemaAI';
+```
+
+计划中的顶层导出主要分为几类：
+
+- **引擎核心与状态管理**
+  - `createEngineStore`
+  - `schemaAIProvider`
+  - `useEngineState`
+- **渲染与视图集成**
+  - `schemaAIRenderer`
+  - `schemaAICanvas`（可选，设计态/编辑器用）
+- **插件与扩展机制**
+  - `registerPlugin`
+  - `createPlugin`
+- **Schema 与 UI 协议**
+  - `defineComponentSchema`
+  - `createSchemaValidator`
+  - 类型导出：`EngineSchema`, `PageSchema`, `ComponentSchema`, `PluginDefinition`, `UIConfig` 等。
+
+> 说明：下面每一节只定义接口形态和职责，不约束具体内部实现细节。
+
+---
+
+## 3. 引擎核心与状态管理 API
+
+### 3.1 `createEngineStore(options)`
+
+**用途**：创建并配置一个引擎实例的核心状态容器，用于管理 schema、页面、变量、撤销/重做栈等。
+
+```ts
+import { createEngineStore } from '@your-scope/schemaAI';
+
+const engine = createEngineStore({
+  initialSchema,
+  plugins,
+  historyLimit: 100,
+});
+```
+
+- **入参（初稿）**：
+  - `initialSchema: EngineSchema`：初始应用 schema（包含页面、组件树等）。
+  - `plugins?: PluginDefinition[]`：预注册的插件列表。
+  - `historyLimit?: number`：撤销/重做历史长度上限。
+- **返回（初稿）**：
+  - `store` 对象，封装以下能力：
+    - `getState(): EngineState`
+    - `subscribe(listener: (state: EngineState) => void): () => void`
+    - `dispatch(command: EngineCommand): void`
+    - `undo(): void`
+    - `redo(): void`
+
+> 后续可在实现阶段，根据现有状态管理方案（如 Zustand/Redux/自研）做适配，但对外保持上述抽象不变。
+
+### 3.2 `schemaAIProvider`
+
+**用途**：在 React 组件树中注入引擎上下文，方便子组件消费状态和命令。
+
+```tsx
+import { schemaAIProvider, createEngineStore } from '@your-scope/schemaAI';
+
+const engine = createEngineStore({ initialSchema });
+
+export function App() {
+  return (
+    <schemaAIProvider engine={engine}>
+      {/* 运行时或编辑器 UI */}
+    </schemaAIProvider>
+  );
+}
+```
+
+- **Props（初稿）**：
+  - `engine: EngineStore`：由 `createEngineStore` 创建的引擎实例。
+  - 可选 `children: ReactNode`。
+
+### 3.3 `useEngineState(selector?)`
+
+**用途**：在 React 组件中访问引擎状态，并支持选择器优化。
+
+```tsx
+import { useEngineState } from '@your-scope/schemaAI';
+
+function CurrentPageTitle() {
+  const title = useEngineState((state) => state.currentPage.title);
+  return <h1>{title}</h1>;
+}
+```
+
+- **签名（初稿）**：
+  - `useEngineState<TSelected>(selector?: (state: EngineState) => TSelected): TSelected`
+
+---
+
+## 4. 渲染与视图集成 API
+
+### 4.1 `schemaAIRenderer`
+
+**用途**：根据传入的 schema 和上下文，将低代码描述渲染为真实的 React 组件树。可用于「运行态预览」或集成到业务页面中。
+
+```tsx
+import { schemaAIRenderer } from '@your-scope/schemaAI';
+
+function RuntimeView() {
+  return (
+    <schemaAIRenderer
+      schema={runtimeSchema}
+      pageId="home"
+      mode="runtime"
+    />
+  );
+}
+```
+
+- **Props（初稿）**：
+  - `schema: EngineSchema`：必填，当前要渲染的应用/页面 schema。
+  - `pageId?: string`：当前页面 ID；不填时可用 schema 内默认页。
+  - `mode?: 'runtime' | 'design'`：渲染模式（运行态/编辑态）。
+  - `onEvent?: (event: EngineEvent) => void`：运行时事件回调（如按钮点击、路由跳转等）。
+  - `componentsOverride?: Record<string, React.ComponentType<any>>`：允许外部替换部分组件实现。
+
+### 4.2 `schemaAICanvas`（可选）
+
+**用途**：专用于设计器场景的画布组件，支持选中、高亮、拖拽等 UI 反馈。  
+当前仅作为规划占位，具体 Props 和行为待后续基于现有编辑器实现进一步抽象。
+
+---
+
+## 5. 插件与扩展机制 API
+
+### 5.1 `registerPlugin(plugin)`
+
+**用途**：注册一个插件，使引擎能够识别新的组件类型、数据源或行为。
+
+```ts
+import { registerPlugin } from '@your-scope/schemaAI';
+
+registerPlugin({
+  name: 'recharts-basic',
+  components: [/* ... */],
+  dataSources: [/* ... */],
+});
+```
+
+- **入参（初稿）**：
+  - `plugin: PluginDefinition`
+    - `name: string`
+    - `components?: ComponentDefinition[]`
+    - `dataSources?: DataSourceDefinition[]`
+    - 其他扩展点：指令、动作、事件处理器等。
+
+> 具体内部注册方式（全局/按引擎实例）在实现阶段细化，但对外保持 `registerPlugin` 这种使用方式。
+
+### 5.2 `createPlugin(options)`
+
+**用途**：帮助用户使用类型安全的方式创建插件定义。  
+
+```ts
+import { createPlugin } from '@your-scope/schemaAI';
+
+const RechartsPlugin = createPlugin({
+  name: 'recharts-basic',
+  components: [/* ... */],
+});
+```
+
+- **入参/返回**：包装 `PluginDefinition`，提供更好的类型提示和默认值。
+
+---
+
+## 6. Schema 与 UI 协议 API
+
+### 6.1 `defineComponentSchema(definition)`
+
+**用途**：声明一个组件在引擎中的 schema 形态（props、事件、插槽、样式配置等），同时为编辑器和运行时提供统一的元数据。
+
+```ts
+import { defineComponentSchema } from '@your-scope/schemaAI';
+
+export const ButtonSchema = defineComponentSchema({
+  type: 'button',
+  displayName: 'Button',
+  props: {
+    text: { type: 'string', default: 'Button' },
+    variant: { type: 'enum', options: ['primary', 'secondary'], default: 'primary' },
+  },
+  events: {
+    onClick: { description: 'Click event' },
+  },
+  uiConfig: {
+    /* 与 UIconfig 绑定的原子样式配置 */
+  },
+});
+```
+
+- **入参（初稿）**：
+  - `definition: ComponentSchemaDefinition`：
+    - `type: string`
+    - `displayName?: string`
+    - `props?: Record<string, PropDefinition>`
+    - `events?: Record<string, EventDefinition>`
+    - `slots?: Record<string, SlotDefinition>`
+    - `uiConfig?: UIConfig`
+- **返回**：
+  - 标准化后的 `ComponentSchema`，可用于插件注册与渲染。
+
+### 6.2 `createSchemaValidator(options)`
+
+**用途**：创建一个针对 EngineSchema 的校验器，用于在保存、导入或 AI 修改 schema 时进行检查。
+
+```ts
+import { createSchemaValidator } from '@your-scope/schemaAI';
+
+const validate = createSchemaValidator({ plugins: [RechartsPlugin] });
+
+const result = validate(schema);
+if (!result.valid) {
+  console.error(result.errors);
+}
+```
+
+- **返回结果（初稿）**：
+  - `{ valid: boolean; errors: SchemaValidationError[] }`
+
+### 6.3 类型导出
+
+为方便 TS 项目使用，计划导出常用类型：
+
+```ts
+import type {
+  EngineSchema,
+  PageSchema,
+  ComponentSchema,
+  EngineState,
+  EngineCommand,
+  PluginDefinition,
+  UIConfig,
+} from '@your-scope/schemaAI';
+```
+
+---
+
+## 7. 未来可能扩展的 API（占位）
+
+- **AI 相关接口**（待基于现有实现抽象）：
+  - `applyAiSuggestion(schema, suggestion)`：对 schema 应用 AI 生成的变更。
+  - `diffSchemas(a, b)`：用于展示差异或生成变更说明。
+- **跨页面路由与数据绑定**：
+  - `navigate(pageId, params)`：在运行时中触发页面跳转。
+  - 相关 hook，如 `useCurrentRoute`, `useBoundData(sourceRef)`。
+
+> 这些暂时只作为「方向占位」，在实际实现前需要结合当前代码进一步细化。
+
+---
+
+## 8. 使用建议与版本策略（草案）
+
+- **版本号策略**：
+  - 初始版本建议为 `0.x`，用于快速迭代设计。
+  - 当 Public API 相对稳定且已有外部项目依赖后，发布 `1.0.0`。
+- **变更流程建议**：
+  - 任意可能影响上述 Public API 的变更：
+    - 先在本文件中更新接口说明；
+    - 在 `migrate-plan.md` 标注对应 Phase/里程碑；
+    - 再进行代码层实现与发布。
+