@5even7/dlc-ui 0.2.17 → 0.2.18

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 > **发版规则**：默认每次发布只递增补丁号（0.x.y → 0.x.(y+1)，即 +0.01）；除非手动明确指定新版本号，否则不升次版本。
 
+## 0.2.18 - 2026-08-15
+- 新增第二个表情家族 `type="grok"`：纯 SVG Path Morph 动态角色（非 Lottie），内置 13 个语义状态（情绪 / Agent 状态 / 生命周期）、8 种身体形态、随机表情池与眨眼节奏、身体动作动画（bounce / tilt / scan / turn / pulse / glitch）、pointer 视线跟随交互。
+- `createEmo` / `DlcEmo` 新增 `type`、`shape`、`interactive` 选项与 `setShape()` / `setInteractive()` 方法；`partColors` 对 grok 支持 `body` / `eyes` 两部位。TypeScript 改为判别联合（`MiaoEmoOptions` / `GrokEmoOptions`）。
+- 架构重构：`emo.js` 收敛为公共 Facade，Miao（Lottie）与 Grok（SVG Morph）各自独立 Renderer；结构属性变更重建渲染器，行为属性变更实时转发；Grok 数据全部本地打包、离线可用。
+- 新增 `getEmoType()` API 与 `EMO_CATEGORIES` 新分组；新增 THIRD_PARTY_NOTICES.md（LaoA-GrokBot MIT 声明）并加入 npm 发布文件列表。
+- 修复（经外部 AI 代码审查验证）：
+  - 修复 Grok 表情节奏被 `speed` 重复缩放（速度平方）的问题，`speed` 现在只生效一次。
+  - 修复共享 rAF Scheduler 全部暂停后 Grok `play()` / 页面重新可见无法唤醒动画循环的问题。
+  - Grok 眼睛现在由与身体形态同步的 `clipPath` 裁剪（对齐原版实现），`setShape()` 会同步更新裁剪路径，clipPath id 按实例唯一。
+  - Grok `fit`（contain / cover / fill）现在真正生效：svg 按 fit 映射 `preserveAspectRatio`（meet / slice / none）。
+  - Grok 的 `renderer` 对外恒为 `'svg'`，miao→grok→miao 往返时 miao 的 renderer 偏好（canvas/svg）不再丢失。
+  - `setName()` 改为事务式：非法名称在销毁旧动画前即抛错，原动画保持挂载。
+  - 修正 THIRD_PARTY_NOTICES.md 中的来源仓库与版权信息；版本号同步为 0.2.18。
+- Grok 状态展示体系：新增 `GROK_STATE_META`（category / label / description / source 元数据）与派生列表 `GROK_NAMES` / `GROK_CATEGORIES`，以及 `getGrokStateMeta()` / `getGrokNamesFor()` 查询函数；13 个公开 name 全部保留，分类（情绪 / Agent 状态 / 生命周期）不影响公开 API。新增 `createEmoPreviewCard()` 轻量卡片预览控制器：默认静态，hover / focus 时临时播放约 2.8 秒，离开 / 移出视口 / 系统减少动态时立即暂停，避免多卡片同时长驻动画。Docs 的 Grok 区块改为不分类、平铺全部状态 + 动态预览卡片，并补充 Grok name = 动态状态模组 的说明。
+- Grok 状态精简：按「静态首帧同一张脸只保留一个代表」归并，移除 26 个重复/近重复状态，公开 name 从 39 精简为 13（保留 `idle / sleeping / loading / thinking / listening / searching / working / happy / surprised / angry / sad / confused / receiving`）。
+- 移除「推荐」体系：`recommended` 元数据字段与 `GROK_RECOMMENDED_NAMES` 删除，Docs 默认展示全部状态。
+- 13 个状态的名称与描述不再照搬上游，改为按 25 组表情几何逐帧核对后重写（如 `idle 待机→平静`、`loading 加载→缓冲中`、`listening 倾听→聆听`、`working 工作→专注`、`confused 困惑→疑惑`、`searching 搜索→寻找`、`sleeping 睡眠→睡觉`），描述贴合实际眼神与动效。
+- Capsule `pointerenter` / `pointerleave` 事件负载补齐 `event`，与文档 `{ event, preset }` 一致。
+- Vue wrapper 补齐 Capsule `setSeed()` / `setSpeed()` 与 Progress `setEdgeStyle()`，与 H5 控制器及文档方法表对齐。
+- 文档一致性：README `change.source` 更正为 `drag / keyboard / prop`；Grok 分类与 `GROK_CATEGORIES` 对齐；修正历史版本中“移除 Progress keyboard 控制”的过时说明（当前版本保留 `keyboard`，默认开启）；削除从未被消费的 `--dlc-emo-play-state` CSS 变量。
+
 ## 0.2.17 - 2026-08-15
 - Miao表情包优化展示，表情包拆分模块变更部分颜色属性
 

package/README.md

@@ -1,8 +1,8 @@
 # @5even7/dlc-ui
 
-框架无关的 **星云胶囊**、**流体进度胶囊**、**星云背景层（dlc-color）** 与 **Lottie 动态表情（dlc-emo）** 组件库。一套核心，H5 / Vue2 / Vue3 都能用。
+框架无关的 **星云胶囊**、**流体进度胶囊**、**星云背景层（dlc-color）** 与 **动态表情（dlc-emo）** 组件库。一套核心，H5 / Vue2 / Vue3 都能用。
 
-星云组件使用 WebGL2 实时渲染，不可用时自动降级 Canvas2D；Emo 使用按需加载的 `lottie-web` 轻量矢量播放器，可选 SVG / Canvas。现代浏览器加载原生 ESM，旧工具链可使用转译后的 legacy 构建。
+星云组件使用 WebGL2 实时渲染，不可用时自动降级 Canvas2D；Emo 内置 `type="miao"`（按需加载的 `lottie-web` 轻量矢量播放器，可选 SVG / Canvas）与 `type="grok"`（纯 SVG Path Morph 动态角色，无需任何播放器库）。现代浏览器加载原生 ESM，旧工具链可使用转译后的 legacy 构建。
 
 ## 发版规则
 
@@ -25,7 +25,10 @@ npm install @5even7/dlc-ui
 
 `dlc-color` 复用同一套星云渲染器，只做背景层，直接使用上表 capsule 的 6 个预置。
 
-`dlc-emo` 当前提供 `type="miao"` 与 23 个动作名：`angry / cry / sad / sigh / investigate / mute / ponder / question / static / asleep / yawn / badminton / confident / laugh / leisure / music / smile / yummy / mock / shy / snigger / panic / shocked`。`type` 为后续 `wang` 等素材家族保留扩展空间。
+`dlc-emo` 提供两个表情家族：
+
+- `type="miao"`：Lottie 动作表情，内置 23 个动作名：`angry / cry / sad / sigh / investigate / mute / ponder / question / static / asleep / yawn / badminton / confident / laugh / leisure / music / smile / yummy / mock / shy / snigger / panic / shocked`。
+- `type="grok"`：SVG Path Morph 动态角色，内置 13 个语义状态（分类与公开 API 一致，见 `GROK_CATEGORIES`）：情绪（`idle / happy / surprised / sad / angry / confused`）、Agent 状态（`loading / thinking / searching / working / listening / receiving`）、生命周期（`sleeping`）。支持 `shape`（`blob / pebble / squircle / capsule / triangle / hex / cloud / drop`）与 `interactive`（pointer 视线跟随），`partColors` 为 `body` / `eyes` 两部位。
 
 `preset` 只接受上表中的文学名称（如 `'沧溟'`），大小写不敏感、首尾空格忽略；不传时使用默认预置 `初光`（胶囊/背景层）或 `星火`（进度条）。`colors`、`seed`、`speed` 是独立属性，传了覆盖预置内置值，不传用预置默认值。
 
@@ -82,6 +85,25 @@ emo.setName('laugh').setSegment([0, 80]);
 // 宿主销毁时：emo.dispose();
 ```
 
+Grok 动态角色：
+
+```js
+const grok = createEmo(document.querySelector('#grok-host'), {
+  type: 'grok',
+  name: 'thinking',
+  width: 229,
+  height: 229,
+  shape: 'capsule',
+  interactive: true,
+  partColors: { body: '#2f86ed', eyes: '#fffdf7' }
+});
+
+grok.setName('celebrate').setShape('hex').setInteractive(false);
+// 宿主销毁时：grok.dispose();
+```
+
+> Grok 的 `name` 表示一个**动态状态模组**（表情池 + 节奏 + 眨眼 + 身体动作），而不是一张固定表情：不同状态在静态第一帧可能相似，但动态行为不同。13 个公开 name 全部有效，展示元数据见 `GROK_STATE_META`（`category` / `label` / `description` / `source`），分类表 `GROK_CATEGORIES`、查询函数 `getGrokStateMeta(name)` / `getGrokNamesFor(tab)` 均由该元数据派生。需要做 hover 预览卡片时可复用 `createEmoPreviewCard({ container, options, playFor, respectReducedMotion, trackViewport })`：默认静态，进入时播放短预览，离开 / 移出视口 / 系统减少动态时立即暂停。
+
 `partColors` 按部位替换颜色（`leftEye` / `rightEye` / `mouth` / `mouthFill` 等，每个部位在素材里有稳定的 `paint.*` 命名通道）。值为任意 CSS 颜色（`#fff` / `#rrggbb` / 命名色 / `rgb()` / `rgba()`，alpha 忽略）；未传或为 `null` 的部位保留素材默认色，当前动作不支持的部位会被忽略。外框背景单独用 `background` 控制。
 
 工厂调用用 `text` / `colorContent` 选项填插槽；Vue 组件直接用默认插槽和 `#color` 插槽（见下）。
@@ -268,10 +290,10 @@ createProgressCapsule(el, {
 | capsule | `pointerenter` / `pointerleave` | `{ event, preset }` |
 | capsule | `error` | `{ message }`（WebGL2 不可用降级时触发） |
 | progress | `ready` / `presetchange` | `{ preset }` |
-| progress | `change` | `{ value, source }`，source ∈ `drag/prop` |
+| progress | `change` | `{ value, source }`，source ∈ `drag / keyboard / prop` |
 | progress | `dragstart` / `dragend` | `{ value }` |
 | progress | `error` | `{ message }` |
-| emo | `ready` | `{ preset, duration, frames }` |
+| emo | `ready` | `{ preset, duration, frames }`（grok 无逐帧概念：duration 为 null、不含 frames） |
 | emo | `complete` / `loopComplete` / `segmentStart` | 播放生命周期 |
 | emo | `namechange` / `typechange` | `{ preset }` |
 | emo | `error` | `{ message }` |

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,40 @@
+# Third Party Notices
+
+本组件库使用了以下第三方作品。所有内容均按各自许可条款使用。
+
+## LaoA-GrokBot（Grok 表情数据与实现参考）
+
+- 来源：https://github.com/zhulin025/LaoA-GrokBot（仅作为数据与算法参考，未分发其完整仓库）
+- 许可证：MIT License
+- 用途：DLC-EMO `type="grok"` 的 13 个语义状态、25 组表情几何数据（`GROK_EXPRESSIONS`）、眨眼/表情节奏参数、8 种身体形态与 SVG Path Morph 算法的参考实现。
+- 本仓库中生成的 `src/dlc-emo/assets/grok/data.js` 源自该项目 `original-data.js` 的转换数据。
+
+MIT License 全文：
+
+> MIT License
+>
+> Copyright (c) 2026 老A玩AI
+>
+> 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.
+
+## lottie-web
+
+- 来源：https://github.com/airbnb/lottie-web
+- 许可证：MIT License
+- 用途：DLC-EMO `type="miao"` 的 Lottie 动画播放器。

package/dist/capsule.cjs

@@ -1366,13 +1366,15 @@ function createCapsule(container) {
   var isMotionPaused = function isMotionPaused() {
     return manuallyPaused || reducedPaused || staticMode || contextLost;
   };
-  root.addEventListener('pointerenter', function () {
+  root.addEventListener('pointerenter', function (event) {
     return emitter.emit('pointerenter', {
+      event: event,
       preset: _objectSpread2({}, preset)
     });
   });
-  root.addEventListener('pointerleave', function () {
+  root.addEventListener('pointerleave', function (event) {
     return emitter.emit('pointerleave', {
+      event: event,
       preset: _objectSpread2({}, preset)
     });
   });

package/dist/capsule.mjs

@@ -1159,8 +1159,8 @@ function createCapsule(container, options = {}) {
   reducedPaused = motionPreference.matches();
   const isMotionPaused = () => manuallyPaused || reducedPaused || staticMode || contextLost;
 
-  root.addEventListener('pointerenter', () => emitter.emit('pointerenter', { preset: { ...preset } }));
-  root.addEventListener('pointerleave', () => emitter.emit('pointerleave', { preset: { ...preset } }));
+  root.addEventListener('pointerenter', (event) => emitter.emit('pointerenter', { event, preset: { ...preset } }));
+  root.addEventListener('pointerleave', (event) => emitter.emit('pointerleave', { event, preset: { ...preset } }));
   root.addEventListener('click', (event) => {
     emitter.emit('click', { event, preset: { ...preset } });
   });