@snack-kit/core 0.1.0 → 0.3.0

package/README.md

@@ -1,514 +1,424 @@
-# 3.0.0-beta.1
+# @snack-kit/core
 
-    支持 react 19
+Snack 动态模块加载与渲染 SDK，基于 React + RequireJS 构建。支持从服务端加载 UMD 格式的 Snack 模块，并将设计器页面 JSON 配置渲染为 React 组件树，同时提供完整的表单数据管理、校验、国际化与事件系统。
 
-# 2.3.7
+---
 
-    update 校验增加notEmptyObject，不为空对象判断
+## 安装
 
-# 2.3.6
-
-    update @paraview/lib to 3.x
+```bash
+npm install @snack-kit/core
+```
 
-# 2.3.5
+**Peer Dependencies**
 
-    修复 Snack 入参 data 为数组时，会导致页面渲染崩溃的问题
+```bash
+npm install react react-dom @snack-kit/lib
+```
 
-# 2.3.4
+---
 
-    修复表达式渲染配置丢失的问题
+## 快速开始
 
-# 2.3.3
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import { SnackSDK } from '@snack-kit/core';
+import * as SnackKitLib from '@snack-kit/lib';
+
+const sdk = new SnackSDK({
+  service: 'https://your-snack-service.com',
+  importMaps: {
+    'react': React,
+    'react-dom': ReactDOM,
+    '@snack-kit/lib': SnackKitLib
+  }
+});
+
+// 渲染设计器页面为 React 组件
+const Page = await sdk.createPageComponent({ id: 'page-id', type: 'portal' });
+
+createRoot(document.getElementById('app')!).render(<Page />);
+```
 
-    新增 setting 类设置参数对{{}}表达式的支持
+---
 
-# 2.3.1
+## SnackSDK 构造参数
 
-    （重要）修复调用渲染 api 时，为传onComplete 参数时，会自定义脚本未初始化的错误
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `service` | `string` | Snack 服务端地址 |
+| `importMaps` | `object` | 模块依赖注入，key 为模块名，value 为模块对象 |
+| `defaultFormAttr` | `SnackFormAttribute` | 表单组件 FormAttr 全局默认值 |
+| `runtime` | `boolean` | 是否为运行时模式，默认 `true`；设计器模式设为 `false` |
+| `runtimeMapping` | `object` | 运行时模块名映射 |
+| `modUrl` | `string` | 模块加载根路径，默认 `service + modPath` |
+| `modPath` | `string` | 模块请求路径，默认 `/package` |
+| `cdnUrl` | `string` | CDN 根路径，默认 `service + cdnPath` |
+| `cdnPath` | `string` | CDN 路径，默认 `/lib` |
+| `pageUrl` | `string` | 页面数据请求根路径 |
+| `pagePath` | `string` | 页面请求路径，默认 `/page` |
+| `staticUrl` | `string` | 模块静态资源 CDN 路径 |
+| `importModules` | `ImportModules` | 预置 Snack 模块 class，加载时优先从此查找 |
+| `basicsType` | `string` | 基础模块分类名，默认 `basics` |
+| `i18n` | `I18nData` | 国际化数据复写 |
+| `localeMapping` | `object` | 国际化语言映射关系，例如 `{ zh: 'zh_CN' }` |
+| `localeDefault` | `string` | 默认国际化语言，默认 `zh` |
+| `message` | `object` | 消息提示对象，供 evalJS 脚本使用 |
+| `argv` | `Record<string, ...>` | 全局环境变量，在表达式中通过 `$.argv` 访问 |
 
-# 2.3.1-a1
+---
 
-    移除旧版本表达式逻辑
+## 核心 API
 
-# 2.3.0
+### 页面渲染
 
-    新增全局变量支持；
-    SDK 参数新增 argv ，初始化可传入全局变量对象
-    移除 node-sass，新增 sass 库
+#### `sdk.createPageComponent(params, config?)`
 
-# 2.2.41
+将设计器页面渲染为 React 函数组件。
 
-    修复Message组件无法显示dom的问题
+```tsx
+const Page = await sdk.createPageComponent(
+  { id: 'my-page', type: 'portal' },
+  {
+    data: { username: 'admin' },  // 表单回填数据
+    onComplete: (event) => {
+      console.log('渲染完成', event.fields);
+    }
+  }
+);
 
-# 2.2.40
+<Page />
+```
 
-    修复sdk国际化问题 [object object] 问题
+#### `sdk.createPageForElement(el, params, config?)`
 
-# 2.2.39 【publish时存在版本未上传dist，故跳了版本】
+将页面直接渲染到指定 DOM 元素。
 
-    添加允许跳过校验的配置项，formAttr.skipVerify 设置为true则允许跳过校验规则
+```ts
+await sdk.createPageForElement(document.getElementById('container')!, { id: 'my-page' });
+```
 
-# 2.2.36
+#### `sdk.renderPage(params, config?)`
 
-    sdk 新增页面加载失败忽略，修复多页面加载时，一个失败页面导致后续渲染失败的问题；
-    add package-lock.json
+渲染页面并返回根容器 `DropOjb` 实例（低层 API）。支持传入数组一次渲染多个页面到同一表单容器。
 
-# 2.2.35
+---
 
-    snackCore表单组件label取值增加保底
+### 表单操作
 
-# 2.2.34
+渲染完成后，`onComplete` 回调参数 `event: SnackPageCompleteEvent` 提供以下方法：
 
-    snackCore修改i18nIntl国际化方法，增加托底，如果当前语言列表取不到对应的key,则取默认列表的value，如果没有则返回键值对
+```ts
+// 获取表单数据（全量）
+const formData = event.getData();
 
-# 2.2.33
+// 获取单个字段值
+const username = event.getData('username');
 
-    snackCore增加message提示对象参数，用于evalJs内置para-ui Message提示
+// 设置表单数据
+event.setData('username', 'new-value');
+event.setData({ username: 'a', password: 'b' });
 
-# 2.2.32
+// 表单校验（返回 Promise<boolean>）
+const passed = await event.verify();
+const fieldPassed = await event.verify('username');
 
-    snackCore GetParamsDetails修改参数定义
-    国际化方法replaceStrTemplateVars替换成更安全的方法
-    表单校验国际化getLocale不再读取sdk默认语言
+// 清空表单
+event.empty();
 
-# 2.2.31
+// 销毁页面（解绑事件、释放模块）
+event.destroy();
+```
 
-    snackCore GetParamsDetails和GetDefaultEvents增加英文国际化版本
+---
 
-# 2.2.30
+### 模块渲染
 
-    增加verifyJs中errtext在获取默认语言时的判断，兼容同一SDK维护两套国际化语言errtext空字符串的问题
+#### `sdk.createModuleComponent(args, data?)`
 
-# 2.2.29
+加载并渲染单个 Snack 模块为 React 函数组件。
 
-    修改错误文本校验verifyJs中getLocale没有传默认语言的问题
+```tsx
+const Editor = await sdk.createModuleComponent(
+  { name: 'codeeditor', type: 'code-editor' },
+  { readOnly: false }
+);
 
-# 2.2.28
+<Editor />
+```
 
-    内置国际化语言新增zh-CN、en-US
+#### `sdk.createClassModule(SnackClass, data?, main?)`
 
-# 2.2.27
+通过 Snack Class 直接创建模块实例。
 
-    修复Snack基础类获取国际化语言错的返回了默认值的问题；
+```ts
+const mod = sdk.createClassModule(MySnackClass, { value: 'hello' });
+```
 
-# 2.2.26
+#### `sdk.createClassModuleComponent(SnackClass, data?, main?)`
 
-    修复Snack基础类$lang属性获取国际化语言错误的问题；
-    Core新增localeDefault属性，用于设置默认语言；
+通过 Snack Class 创建模块并返回 React 函数组件。
 
-# 2.2.25
+---
 
-    修复Snack表单内部事件在多表单渲染时，反复被注册与执行的问题；
+### 模块加载
 
-# 2.2.24
+#### `sdk.module(config)`
 
-    修复校验规则的校验逻辑，必填规则需要全部通过，非必填规则至少需要一条通过，整个规则才能算全部通过；
-    修复在组件data对象替换{{var}}变量时造成的原型数据丢失的问题；
-    渲染组件的data数据对象，现在所有字段都支持{{data.var}}变量占位符，从data内获取数据，并且支持jsx；
-    例：
+按模块名称加载 UMD 模块，返回 Snack class 键值对。
 
-```tsx
-// 入参data
-data.jsx = <>
-	<div>123</div>
-	<div>123123</div>
-</>
-data.test = '123';
-// 组件页面渲染json
-moduleData.data.M.label.zh = '{{data.jsx}}xxx{{data.test}}';
+```ts
+const { mymodule } = await sdk.module({
+  module: [{ name: 'mymodule', type: 'custom' }]
+});
 ```
 
-# 2.2.22
-
-    新增formAttr属性：
-        verifyOnEvents: 设置所要在组件事件触发时，执行以下校验规则；
-        verifyASTime：校验规则触发防抖时间，防止某些事件触发校验规则过于频繁所设置的间隔时间；
-
-# 2.2.21
-
-    新增事件onCreateBefore，组件初始化之前执行；
-    新增事件列表方法，GetDefaultEvents();
-    调整导出方法CodeHintConfig -> GetParamsDetails;
-    修复自定义脚本$display对非表单组件的支持；
-
-# 2.2.20
-
-    修复form组件触发校验的限流器作用范围错误，导致不同组件触发限流器时会被相互干扰终止；
+#### `sdk.moduleURL(config)`
 
-# 2.2.19
+按模块 URL 加载模块。
 
-    新增组件属性值占位符变量机制，占位符{{data.xxxx}}, 当前可用变量data为渲染页面所传入的data对象；
-
-# 2.2.18
+```ts
+const mods = await sdk.moduleURL({
+  urls: 'https://cdn.example.com/package/custom/mymodule/index.js',
+  cdnUrl: 'https://cdn.example.com/lib'
+});
+```
 
-    【重要】修复多个表单渲染，只会渲染第一个错误；
+---
 
-# 2.2.17
+### 事件系统
 
-    修复模块onCreate事件触发时机错误，导致部分模块无法执行脚本事件的问题;
-    修复表单$setData方法当key为数字开始的变量时，将会出现语法错误的问题；
+```ts
+// 注册事件
+sdk.addEvent('onComplete', (root, params) => {
+  console.log('页面加载完成', root);
+});
 
-# 2.2.16
+// 页面内组件事件（onChange、onBlur 等）由 SDK 自动分发
+// 手动发送事件
+sdk.sendEvent('custom-event', [arg1, arg2]);
 
-    修复当渲染单个页面失败时，未给出任何错误渲染提示的问题；
+// 卸载指定回调
+sdk.removeEvent('onComplete', myCallback);
 
-# 2.2.15
+// 卸载所有同名事件
+sdk.removeEvent('onComplete');
+```
 
-    修复当多个页面同时渲染时，静默忽略加载失败的页面
+**内置事件**
 
-# 2.2.14
+| 事件名 | 触发时机 |
+|--------|----------|
+| `onComplete` | 整个页面加载渲染完成 |
+| `onRemove` | 模块被移除 |
+| `snack-event` | 组件内部事件（onChange、onBlur 等）分发 |
 
-    调整onCreate时间现在仅在runtime环境触发；
+---
 
-# 2.2.13
+### 国际化
 
-    修复SnackSetting基础类$setData方法无法正确渲染值为空的内容；
+```ts
+// SDK 级别
+sdk.intl('required');               // 返回 string | ReactNode
+sdk.setI18n({ zh: { required: '此字段必填' } });
+sdk.language('en-US');              // 切换所有已加载模块的语言
+
+// 模块内（Snack 基础类）
+this.$intl({ id: 'required' });
+this.$intl('required', { label: '用户名' });
+this.$lang;                         // 获取当前语言
+this.$lang = 'en-US';              // 设置语言
+```
 
-# 2.2.12
+---
 
-    Snack基础类新增$getI18n方法，用于获取国际化数据
+## 基础类
 
-# 2.2.11
+### `Snack<T>`
 
-    修复加载模块，加载带有setting模块时，模块的静态资源路径计算错误的问题；
+所有 Snack 模块的基础类，继承此类实现自定义模块。
 
-# 2.2.10
+```ts
+import { Snack, SnackData } from '@snack-kit/core';
 
-    国际化模块变量现在支持，jsx；
+interface MyData extends SnackData {
+  value: string;
+  label: { zh: string; en: string };
+}
 
-```tsx
-// 变量替换逻辑
-/**
- * 替换字符串模版变量
- * @param str
- * @param params
- */
-export function replaceStrTemplateVars(str: string, vars?: any) {
-	if (!vars) return str;
-	let jsx: boolean = false; // 当替换的vars变量内存在jsx对象，则返回也是jsx数据，否则返回字符串
-	str = str.replace(/\"/g, '\\"');
-	const strTemplate = str.replace(/\{(.*?)\}/ig, (s, v) => {
-		if (typeof vars[v] === 'object') jsx = true;
-		return `",vars.${v},"`;
-	});
-	if (jsx)
-		return new Function('vars', `return ["${strTemplate}"];`)(vars)
-			.map((item: any) => <React.Fragment key={Math.random()}>{item}</React.Fragment>);
-	else
-		return new Function('vars', `return ["${strTemplate}"].join('');`)(vars);
+export class MyModule extends Snack<MyData> {
+  public $component(data?: MyData) {
+    return <div>{data?.value}</div>;
+  }
 }
 ```
 
-# 2.2.9
-
-    Snack基础类data新增参数$i18n国际化数据，可在new Snack组件时通过构造函数传入，该国际化数据不会覆盖代码内原始的默认国际化数据，
-    当通过this.$intl方法获取国际化数据时，优先获取外部传入的国际化数据，当获取失败时则尝试获取默认数据；
-
-# 2.2.8
-
-    调整国际化方法的调用参数，intl({id:'key'}, params);,国际化变量占位符为 xxx{var}xxx；
-
-# 2.2.7
-
-    SnackVueSetting设置属性方法$setData支持.操作符的属性赋值；
-
-# 2.2.6
-
-    修复Snack组件无法从FC组件标签上传属性的错误，Snack= e=> snack.FC(e); <Snack {...data}/>
-
-# 2.2.5
-
-    SnackSetting基础类方法$setData现在支持设置带有.操作符的字段赋值
-
-# 2.2.3
-
-    SDK Form组件事件onChange、onBlur触发的表单校验，增加了500ms的限流；
-
-# 2.2.2
+**常用属性与方法**
+
+| 成员 | 说明 |
+|------|------|
+| `data` | 模块数据对象 |
+| `sdk` | 所属 SDK 实例 |
+| `$id` | 模块唯一实例 ID |
+| `$name` | 模块名称 |
+| `$parent` | 父级 Snack 实例（通常为 Drag 容器） |
+| `$page` | 所属页面事件对象 |
+| `$forceUpdate(reload?)` | 强制重绘 |
+| `$style(key?, value?)` | 读写样式并触发重绘 |
+| `$display(visible)` | 显示 / 隐藏当前组件 |
+| `$intl(ops, params?)` | 获取国际化文本 |
+| `$language(lang)` | 切换语言 |
+| `$destroy()` | 销毁模块，从 SDK moduleMaps 中移除 |
+| `FC(data)` | React 渲染入口，由 SDK 调用 |
+| `$component(data?)` | 子类重写此方法实现 UI |
+
+### `SnackSetting`
+
+设置面板模块的基础类，通过 `$setData` 同步修改关联主模块（`main`）的数据。
 
-    SDK构造函数性增localeMapping配置，可设置国际化语言的转换关系；
-    SDK优化必填校验获取组件label的逻辑；
-
-# 2.2.1
-
-    SDK新增国际化模块，构造函数新增参数i18n可复写内部默认国际化文本；
-    复写国际化方式1:
-    const sdk = window.sdk = new SnackSDK({
-        service: Context.get('snackbar'),
-        importMaps: {
-            'react': React,
-            'react-dom': ReactDOM
-        },
-        defaultFormAttr: {
-            passwordFlag: false
-        },
-        i18n: {
-            zh: {
-                require: '{label}xxxxxxseee{label}',
-                noErrorMsg: ''
-            }
-        }
-    });
-    方式2:
-    sdk.setI18n({
-            zh: {
-                require: '{label}xxxxxxseee{label}',
-                noErrorMsg: ''
-            }
-        });
-    Snack基础类提供的国际化现在也支持字符串模版，{id:'key'},{label:'text'} i18nStrTemplate：key: 'xxx${label}xxx';
-
-# 2.2.0
-
-    externals: {
-        '@paraview/lib': '@paraview/lib',
-        '@paraview/lib/http': '@paraview/lib',
-        '@paraview/lib/esso': '@paraview/lib',
-        '@paraview/lib/ui': '@paraview/lib',
-        '@paraview/lib/utils': '@paraview/lib'
-    },
+```ts
+import { SnackSetting } from '@snack-kit/core';
+
+export class MyModuleSetting extends SnackSetting {
+  public $component() {
+    return (
+      <input
+        value={String(this.main.data?.value ?? '')}
+        onChange={(e) => this.$setData('value', e.target.value)}
+      />
+    );
+  }
+}
+```
 
-# 2.1.1
+---
 
-    调整webapck.externals过滤@paraview/lib依赖
+## 表达式系统
 
-# 2.1.0
+页面 JSON 配置中支持 `{{$.xxx}}` 占位符，在运行时由 SDK 自动替换：
 
-    SKD新增importModules属性，可在初始化时输入Snack模块class类，加载模块时将优先匹配该对象；
-    export interface ImportModules {
-        [type: string]: {
-            [name: string]: Snack | SnackVue | SnackSetting | SnackVueSetting
-        }
+```json
+{
+  "data": {
+    "M": {
+      "label": "{{$.argv.username}}"
     }
-    SDK新增方法createClassModule、createClassModuleComponent方法用于通过Snack Class类渲染组件；
-
-# 2.0.1
-
-    修复vue sanck模块在切换调试页面路由时会报错的问题；
-
-# 2.0.0
-
-    移除para-lib，更换为@paraview/lib
-
-# 1.7.2
-
-    新增SnackFormAttribute.hideNoSubmit,当组件被隐藏时不提交与校验该组件所绑定的字段；
-
-# 1.7.1
-
-    修复sdk方法createPageComponent、createModuleComponent返回值类型定义；
-    SnackSetting基础类新增public $normal: boolean = false;定义
-
-# 1.7.0
-
-    SDK新增createModuleForElement、createPageForElement方法，可以直接渲染snack模块与页面至dom元素内；
-
-# 1.6.17
-
-    sdk新增参数defaultFormAttr，sanck组件FormAttr全局默认值配置，当组件内部缺少参数时，采用该定义数值；
-    Snack表单组件SnackFormAttribute新增passwordFlag描述字段(默认启用)，密码字段标记，
-    为true时则将会在当前表单getData数据组装时候增加 @password: [f...] 字段对当前字段进行描述
-
-# 1.6.16
-
-    新增内部事件onCreate初始化事件
-
-# 1.6.15
-
-    新增页面销毁方法:
-        通过sdk方式: sdk.destroy(event: SnackPageCompleteEvent | null, root: DropOjb | null);
-        通过页面事件对象： (event as SnackPageCompleteEvent).destroy();
-
-# 1.6.14
-
-    修复data入参数据会被基础类构造函数意外过滤的问题，解决国际化数据丢失的问题；
-
-# 1.6.13
-
-    修复渲染表单组时，表单存在空内容时，将不会触发完成事件的问题；
-
-# 1.6.12
-
-    修复自定义校验脚本，返参错误的问题；
-
-# 1.6.11
-
-    修复sdk自定义入参脚本，可能造成对象丢失的错误；
-
-# 1.6.10
-
-    调整Loading，Error组件样式；
-
-# 1.6.9
-
-    自定义脚本新增可用变量:
-        $key    当前组件的唯一key值
-        $field  当前表单绑定的字段名
-        $verify 校验方法 (key?: string) => Promise<boolean>
-    调整$val方法，当设置值时现在会自动触发校验；
-
-# 1.6.8
-
-    SnackForm getData方法新增密码字段清单逻辑，表单内密码输入框的字段最终getData返回时将会额外增加一个@password: ['密文组件字段',...]
-
-# 1.6.7
-
-    SnackSDK接口SnackFormAttribute新增trimValue参数，当为false时不针对表单字段value为string的值进行trim，默认进行trim；
-
-# 1.6.6
-
-    修复SnackForm校验规则在value为空也会进行校验的错误；
-
-# 1.6.5
-
-    修复SnackForm不提交字段未正确过滤的错误；
-
-# 1.6.4
-
-    新增SnackForm表单字段校验将会在onChange与onBlur时触发；
-
-# 1.6.3
-
-    修复SnackFrom入参为空对象时会出错的问题；
-    调整Snack 构造函数入参data默认值；
-
-# 1.6.1
-
-    修复SnackForm数据回填时带有 . 对象访问符的字段无法正确回填的错误；
-
-# 1.6.0
-
-    Snack基础类构造函数，第二位参数现在为data默认值；
-
-# 1.5.3
-
-    新增SnackEvent接口；
-    Snack基础类新增变量$parent定义；
-    Snack基础类移除，parent第二位参数与相关逻辑；
-    新增snack-event内置组件事件监听；
-
-# 1.5.1
-
-    调整基础类目录结构；
-    Snack表单绑定字段支持 . 作为对象结构表达式，getData将解析为对象结构；
-
-# 1.5.0
-
-    打包增加IE支持
-
-# 1.4.11
-
-    表单自定义脚本$val、$display方法当前会优先从表单绑定字段获取，其次从data.key进行匹配；
-    表单自定义脚本新增变量$children当前页面所有子元素键值对；
-    修复表单setData方法失效的问题；
-
-# 1.4.10
-
-    修复资源路径在运行时无法加载的问题；
-    修复页面基础样式无法正确渲染的错误；
-    新增自定义脚本变量定义导出；
-
-# 1.4.8
+  }
+}
+```
 
-    form自定义脚本新增$getData方法，根据字段获取组件M对象的data；
+**可用变量**
 
-# 1.4.7
+| 变量 | 说明 |
+|------|------|
+| `$.argv` | SDK 构造时传入的 `argv` 全局变量 |
+| `$.data` | 当前组件的 data 对象 |
+| `$.sdk` | SDK 实例 |
 
-    新增表单渲染rules规则参数
+---
 
-# 1.4.6
+## 模块打包（UMD 格式）
 
-    修复form入出参转换脚本的已知问题；
+Snack 模块需打包为 UMD 格式并通过 `snackdefine` 注册（由 `scripts/config/webpack.snack.config.js` 提供）：
 
-# 1.4.3
+```js
+// webpack.snack.config.js 关键配置
+output: {
+  filename: 'index.js',
+  library: { type: 'umd' }
+},
+externals: {
+  'react': 'react',
+  '@snack-kit/lib': '@snack-kit/lib'
+}
+```
 
-    新增事件
+打包产物头部会自动注入：
 
-```ts
-// 模块倍移除
-sdk.sendEvent('onRemove', [id]);
+```js
+if (typeof window !== 'undefined' && window.snackdefine) {
+  var define = window.snackdefine;
+}
 ```
 
-    新增form表单清空方法，修复入参脚本未执行的错误；
+---
 
-# 1.4.2
+## 开发
 
-    新增统一错误组件
-    新增统一Loading组件
+```bash
+# 本地开发调试（webpack-dev-server）
+npm run dev
 
-# 1.4.1
+# 构建库（ESM + CJS + Types）
+npm run build
 
-    修复接口定义导致的错误
+# 运行单元测试
+npm test
 
-# 1.4.0
+# 类型检查
+npm run lint
 
-    sdk新增事件，注册事件addEvent，卸载事件removeEvent，发送事件sendEvent；
-
-```js
-// 注册onClick事件
-sdk.addEvent('onClick', (arg1, arg2) => {});
-// 卸载所有onClick事件
-sdk.removeEvent('onClick');
-// 指定卸载onClick事件
-sdk.removeEvent('onClick', (arg1, arg2) => {});
-// 发送事件 [事件的参数]
-sdk.sendEvent('onClick', [arg1, arg2]);
+# 生成 API 文档
+npm run docs
 ```
 
-    新增SDK系统事件，onComplete在整个页面加载完成后触发；
-    优化基础类与SDK部分接口的定义；
-
-# 1.3.8
-
-    修复snack基础类被意外回滚的代码
-
-# 1.3.7
+---
 
-    新增模块与页面渲染错误处理
+## Changelog
 
-# 1.3.6
+### 0.2.0
 
-    修复Core加载模块未捕获错误的问题；
-    修复Snack构造函数第一个参数类型在ts类型在会报错的问题；
+**新增**
 
-# 1.3.5
+- 新增 `src/utils/reactAdapter.ts`：`createReactRoot` / `SnackReactRoot` 运行时兼容层，支持 React 17 / 18 / 19 三版本并存
+  - React 18+：使用 `createRoot`（react-dom/client）
+  - React 17：回退至旧版 `ReactDOM.render` / `unmountComponentAtNode`
+  - 通过变量形式 require，绕过 webpack 静态分析，避免 React 17 宿主环境因 `react-dom/client` 不存在报 "Module not found"
+- 导出 `createReactRoot` 与 `SnackReactRoot` 供外部使用
 
-    调整createModule入参与逻辑
+**依赖调整**
 
-# 1.3.3
+- `react` / `react-dom` 由 `dependencies` 移至 `peerDependencies`，支持版本范围 `>=17.0.0`，宿主项目可自行管理 React 版本
 
-    修复createModuleComponent方法无法创建设置模块的问题
+---
 
-# 1.3.2
+### 0.1.0
 
-    SnackSDK新增方法：
-    createModule 创建snack模块
-    createPageComponent 创建Snack页面的React组件
-    createModuleComponent 创建Snack模块的React组件
+**破坏性变更**
 
-# 1.3.1
+- 移除 Vue 2.0 支持（删除 `SnackVue`、`SnackVueSetting` 及相关导出）
+- 依赖由 `@paraview/lib` 迁移至 `@snack-kit/lib`（`@paraview/lib` 作为 importMaps 别名保持向后兼容）
+- 构建工具由 webpack 迁移至 tsup，产物格式调整为 ESM + CJS + Types
 
-    修复$forceUpdate方法会结束组件生命周期的问题
+**安全修复**
 
-# 1.3.0
+- 移除所有 `new Function` 动态字段访问，改用 `safeGet` / `safeSet` 路径工具（消除代码注入风险）
+- `window.define` 全局污染修复：改用 `window.snackdefine`，不再覆盖标准 AMD `define`
 
-    新增staticUrl参数，指定snack模块静态资源cdn地址，默认根据index.js相对路径获取
+**Bug 修复**
 
-# 1.1.10
+- 修复 `$defaultDisplay(false)` 逻辑反转问题，调用后组件现可正确隐藏
+- 修复模块渲染失败时 `childCount` 未递减，导致 `onComplete` 永不触发的问题
+- 修复渲染错误日志缺少模块 key 信息，现输出 `key` / `field` 辅助定位
 
-    新增SnackSDK继承于Core额外负责设计器页面的渲染与请求
-    Core新增runtime模式相关参数
+**新增**
 
-# 1.1.3
+- 新增 `src/utils/pathAccess.ts`：`safeGet` / `safeSet` 支持 `.` 与 `[]` 混合路径语法
+- 并发加载去重：同一 URL 的模块并发请求只发出一次网络请求
+- `destroy()` 方法现会清理所有待处理的 `verifyTimeout` 防抖计时器，防止内存泄漏
+- 新增 vitest 单元测试（`tests/utils/pathAccess.test.ts`）
+- 新增 typedoc 支持，`npm run docs` 生成 API 文档
 
-    core 新增 basicsType 属性，定义基础模块的分类类型名，拖拽模块使用中将会读取该参数去请求drag与drop模块；
-    调整SnackVue继承于Snack类，移除重复代码
+**类型系统**
 
-# 1.0.11
+- 全局类型安全审查，大幅减少 `any` 使用
+- 新增导出类型：`SnackRequireFunction`、`SnackDefineFunction`、`SnackSettingModelItem`、`ExprArgv`
+- 支持 React 19
 
-    Snack基础类新增isContainer、isBasic、isForm标记变量
-    新增接口SnackFormAttribute
+---
 
-# 1.0.10
+## License
 
-    Core 新增onDrop事件定义
+ISC