@lemoncat7/dsh-theme-xiaohei 0.3.0-alpha.23 → 0.3.2

package/README.md

@@ -1,33 +1,45 @@
 # Xiaohei Night for DSH
 
-`Xiaohei Night` 是一个基于 DeepSeek Harness 官方主题注册接口开发的非官方粉丝主题插件。主题使用成对的二维动画背景建立人类城市与妖灵森林共存的场景，并以炭黑、雾灰、林地绿和青色妖灵力统一 DSH 的工作界面。
+`Xiaohei Night` 是一个基于 DeepSeek Harness 官方主题注册接口开发的非官方粉丝主题插件。主题以低饱和天空、日夜光线和坐在小平台上的人形小黑表达陪伴感，保留原生工作台布局。
+
+## 兼容性
+
+正式版 `0.3.2` 针对 DeepSeek Harness `0.1.2-rc.1` 构建，需要 Node.js `22.19+` 或 `24+`。Conversation、Renderer、Sidebar、Slots 与 Theme 接口均对应 `0.1.2-rc.1`。本版增加人物局部 2D 骨骼动画，优化侧栏切换性能和文字入场时序，发布为 npm `latest`。“跟随系统”读取当前设备／浏览器的配色偏好，不按服务器时间切换。
 
 ## 当前范围
 
 - 保留 DSH 原有布局、密度和交互层级。
 - 使用半透明墨黑表面，让背景可见但不压过对话内容。
 - 使用青绿色作为唯一交互强调色，错误、成功、警告保留独立语义色。
-- 背景与角色是独立位图图层，角色不使用 CSS 符号或几何块拼接。
-- 角色没有常驻漂浮、缩放或抖动；待机时使用对齐精灵帧完成自然眨眼和稀疏微反应。
-- 鼠标或嘿咻进入局部注视范围后，小黑会先注视再按方向轻动一次耳朵；纯待机 12–24 秒自然摆尾一次，回答完成后快速摆尾一次。
-- 使用 DSH 官方会话快照呈现七种状态：待机、聚能思考、流式回答、工具执行、等待用户、完成庆祝与错误提示。
-- 状态只跟随当前打开的会话；后台运行中的其他会话不会抢占角色，切换会话也不会误触发完成庆祝。
-- 所有角色位图随插件内联并预载，运行时只切换状态与完整帧精灵表，不发起图片请求；非待机状态始终优先于待机微反应。
-- 聚能、回答、工具、等待、完成和错误分别使用轻量局部光效，离开对应状态后动画立即停止。
-- 深浅模式使用同一林城交界构图的昼夜背景：远处城市、古树会馆、小型空间门和沿树根流动的妖灵力共用一套位置，不在小黑脚下叠加底圈或常驻漩涡动效。
-- 左侧栏直接共享全局水墨灵域，仅使用向主场景渐隐的半透明同色材质组织品牌区、主操作、工作区与底部工具，并以潦草竖写的生图“罗小黑”签名占据纵向留白，不新增无功能入口。
-- 工作区、工具区和会话输入区不使用额外铭牌，分别以猫尾灵珠、空间裂环、蓝嘴黑猫牌作为轻量识别点；工作区右侧额外内收，收起后所有工具回到同一条 35px 视觉轴。
+- 背景与人物分层：保留日间／夜间的柔和天空；人物使用独立高清、无损 WebP，不随整张壁纸放大。坐姿、托腮和打盹统一为 720×1019，探头素材宽 360；最大显示尺寸仍有约 3 倍像素密度。姿势按需解码后再显示，保留轮廓与五官细节。
+- 根据真实剩余空间决定姿势：右侧宽裕时坐在小平台上，中等窗口扶着侧栏探头；细侧栏空位使用更窄的半脸偷看。没有安全空间时暂时隐藏，不覆盖消息、头像或侧栏按钮，不修改业务布局。
+- 坐姿下，用户空闲 30 秒后托腮、3 分钟后闭眼打盹；鼠标、键盘、触摸点击或滚轮操作后恢复。页面隐藏或不再使用坐姿时暂停计时，返回后重新开始。最多一个空闲计时器，睡着后不继续轮询，不绑定 AI 状态，不读取输入内容。姿势以 220ms 淡化过渡，不是连续骨骼动画。
+- 耳朵以独立耳根转动，坐姿和托腮的尾巴通过 7 个关节点与网格蒙皮连续变形，鼠标靠近可触发联动。WebP 仅用于静态图层，不播放帧条；眨眼仍为眼睑贴图合成，身体与四肢没有完整骨骼绑定，并非完整 Live2D。动作最高 30 帧，静止、后台和减少动态模式不持续绘制。
+- 装饰背景使用稳定的大视口高度；姿势切换不横穿会话，不读取会话内容或执行状态；流式文本高度变化不触发布局重测。软键盘兼容性仍需 iOS / Android 真机验收。
+- bloub 嘿咻保留 alpha.171 略宽于高的小黑团轮廓和圆润奶白眼圈。单击依次眨眼回应、轻跳、歪头、感叹号惊讶；双击或键盘 Shift+Enter 轮换散开重聚、蛋形、环绕、六边形、单眼眨眼、睁大眼、感叹号、警觉、休眠、思考、通知。每隔随机 20–40 秒自动选择一种待机动作（含眨眼、休眠，不含思考、通知、感叹号），不连续重复；打字、飞行或其他动作尚未结束时顺延。后台/离屏/减少动态时取消调度，恢复后重新等待，不补播。
+- 嘿咻通过可选的官方 `sessions.list` / `binding().session` 只读订阅当前会话：运行中显示三点思考（代表本轮处理中，不细分推理/输出/工具），观察到本轮结束时提醒一次，新执行错误显示感叹号。提醒表示本轮结束，不承诺任务成功，手动停止也可能触发。初次加载历史、切换会话、重新加载历史不会补发完成提醒。通知徽点采用暖金色和真正透明的缺口；不申请浏览器通知权限、不发送消息、不操作会话、不关联壁纸。
+- 新会话将同一只嘿咻停在输入框上方、Logo 左边；输入区落到底部时，用可打断的约 950 ms 飞行动画转移到输入框左侧。手机给 Logo 左侧留出空间并缩小角色；普通窗口缩放不触发跨区域飞行。仅使用现有 Hero 品牌元素和输入框位置，不读取或改变会话业务数据。
+- 慢浮动周期 14 秒，宽屏横向 ±7 px、纵向 ±10 px；窄屏自动减小幅度。视线跟随窗口内鼠标，身体只在近处轻微靠近（宽屏最多 5 / 3.5 px），约 480 ms 柔和回位。CSS transform 合成浮动和跟随，不增加持续 JS 帧计算或逐帧布局测量；除短暂换位飞行外，点击区域保持固定。减少动态模式关闭浮动、跟随、飞行和自动动作；不改发送键。
+- 嘿咻初始只有 10 个 SVG 节点；首次触发特殊动作才一次性建立粒子/轨道池及通知缺口，之后固定复用（总计 102 节点），帧循环不新增节点、不测量布局，结束后隐藏特效。小尺寸变形中的眼圈适当收窄，避免相互粘连。空闲间歇唤醒，离屏、隐藏和减少动态时暂停，卸载释放监听、观察器、帧请求和定时器。宽屏使用框外空位，窄屏使用框内左侧预留位，不改发送键。原项目 MIT 许可与固定源码版本见 `THIRD_PARTY_NOTICES.md`；观察及改动记录见 `docs/heixiu-motion-reference.md`。
+- 对话双方保留静态身份头像；消息气泡使用更舒适的横向留白。
+- 左侧栏只有一层独立磨砂材质，目录与会话不再各自模糊。展开目录、Hover、选中会话使用逐级增强的中性底色；移除拼接空间框和底部卡片，原生滚动、拖拽和菜单保持不变。
+- 侧栏展开时，内容等待列宽到位后统一淡入，避免文字先出现再被展开裁切。切换期间暂停装饰角色布局和绘制；侧栏品牌金属画面缓存复用，不再反复创建 WebGL 和编译着色器。
+- 新会话使用统一圆角控件；发送键嘿咻继续保留完整帧眨眼。左栏行宽、缩进、滚动条预留和收起布局交给 DSH 管理，避免主题强行计算宽度。
 - 支持减少动态、增强对比度、强制颜色和打印模式降级。
-- 插件加载后自动启用 `xiaohei-night`，卸载后由 DSH 主题服务恢复系统主题。
-
-状态优先级为：错误 → 等待用户 → 工具执行 → 流式回答 → 聚能思考 → 完成 → 待机。完成态仅在同一个当前会话结束后显示约 1.6 秒。
+- 主题通过 DSH Theme Runtime 覆盖 Light / Dark / System 的语义 token，不替换用户的主题偏好；卸载后由 DSH 恢复原始 token。
 
 ## 安装
 
-从 [GitHub Releases](https://github.com/lemoncat7/dsh-theme-xiaohei/releases) 下载 `0.3.0-alpha.15` 的完整构建包后安装：
+通过 npm 安装正式版：
 
 ```bash
-dsh plugin --profile web add ./lemoncat7-dsh-theme-xiaohei-0.3.0-alpha.15.tgz
+dsh plugin --profile web add @lemoncat7/dsh-theme-xiaohei@0.3.2
+```
+
+也可从 [GitHub Releases](https://github.com/lemoncat7/dsh-theme-xiaohei/releases/tag/v0.3.2) 下载完整包后安装：
+
+```bash
+dsh plugin --profile web add ./lemoncat7-dsh-theme-xiaohei-0.3.2.tgz
 ```
 
 卸载：
@@ -52,6 +64,16 @@ npm run pack:check
 npm run pack:docker
 ```
 
+### 代码边界
+
+- `src/index.ts` 只负责 Host 首帧加载装饰，保持自包含并在客户端插件启动前运行。
+- `src/plugin.ts` 通过 DSH 生命周期装配主题 token、Chrome、场景与交互行为。
+- `src/chrome/` 管理控件和公共插件表面；`src/scene/` 分离场景样式与运行时 DOM。
+- `src/host-contract.ts` 集中维护宿主插槽选择器；`src/host-dom.ts` 为运行期模块共享一个批处理 DOM 观察器。左栏只在尺寸或节点变化时测量布局，流式文本更新不重复强制布局。
+- `src/scene/character-layout.ts` 只计算安全位置，`character-idle.ts` 只管理空闲期限，`character-poses.ts` 统一素材目录；`wallpaper-character.ts` 负责生命周期、按需解码和呈现，卸载时释放监听与计时器。
+- `src/vendor/bloub/` 保留上游动画计算，`src/bloub-heixiu/` 分离 SVG 呈现、布局、样式和生命周期。`signals.ts` 可选地只读订阅当前会话执行状态，不读取会话内容，不操作会话。
+- 旧树洞／落叶挂载器已移除，历史图片保留供版本回溯；背景、材质和业务状态各自独立。
+
 ## 扩展工具接入主题
 
 SSH、伙伴、Git 等后续工具不需要复制主题 CSS。插件根节点使用公开的框架属性即可继承小黑主题：
@@ -77,7 +99,7 @@ SSH、伙伴、Git 等后续工具不需要复制主题 CSS。插件根节点使
 
 ## 视觉资产
 
-主题主视觉使用 `gpt-image-2` 通过标准 Images API 生成，并压缩为 WebP 后以内联资源打入浏览器插件。深浅两张背景共享连续的水墨山林构图：左侧和中央保持低对比度以承载导航与对话，青色灵流贯穿墨域，右下角以较亮雾池和冷色背光托起独立角色图层；背景本身不含人物、动物、文字或水印。待机耳朵和尾巴动作从正式待机帧通过平滑局部形变离线生成，每一格都是完整角色画面，运行时不切割耳朵或尾巴。
+背景使用内置的日夜天空 WebP、CSS 渐变及按需加载的人物透明素材，不加载 Three.js、外部 CDN 或角色模型。品牌头像、消息静态头像、加载动画与发送键嘿咻作为内联资源随插件交付；嘿咻交互使用 SVG。
 
 ## License
 

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,41 @@
+# bloub
+
+Source: https://github.com/jeremy-prt/bloub
+Revision: b4bb3c1b5f93c7b87a2e8d620f667c4093d97749
+
+`src/vendor/bloub/` contains the framework-free animation engine from bloub.
+Authored body profiles, state choreography, gaze projection and interruption
+blending are retained. Local changes: NodeNext `.js` import extensions; lazy
+custom-shape fitting table (unknown profiles bypass the catalogue); repeat the
+blink calendar for long-running sessions; expose eye bounds, uncompressed tangent
+and lid openness for a separate hollow-eye renderer; interpolate notification
+badge/notch radii during entry, exit and interrupted morphs. The theme supplies a custom
+Heixiu radial profile and face through the upstream customisation API. Its gesture
+tracks, DOM lifecycle, placement and scheduler are separate from the upstream core.
+No Vue application, editor, video exporter or media dependencies are included.
+
+The original project recreates an x.ai avatar; its MIT license covers code, not
+ownership of the character designs. This theme is an unofficial fan work and is
+not endorsed by the owners of Luo Xiaohei or x.ai.
+
+## MIT License
+
+Copyright (c) 2026 Jérémy Perret
+
+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/lib/appearance.js

@@ -4,22 +4,38 @@ export const XIAOHEI_APPEARANCE_ATTRIBUTE = 'data-xiaohei-appearance';
 export function bindXiaoheiAppearance(ctx, doc = typeof document === 'undefined' ? undefined : document) {
     if (doc === undefined)
         return () => { };
+    const win = doc.defaultView;
+    let handoff;
+    let disposed = false;
+    const cancelHandoff = () => {
+        if (handoff !== undefined)
+            win?.clearTimeout(handoff);
+        handoff = undefined;
+    };
     const sync = (snapshot) => {
-        const bootAppearance = doc.documentElement.getAttribute(XIAOHEI_BOOT_APPEARANCE_ATTRIBUTE);
-        if (bootAppearance === 'light' || bootAppearance === 'dark') {
-            doc.documentElement.setAttribute(XIAOHEI_APPEARANCE_ATTRIBUTE, bootAppearance);
-            if (snapshot.active.colorScheme !== bootAppearance)
-                return;
-        }
-        else {
-            doc.documentElement.setAttribute(XIAOHEI_APPEARANCE_ATTRIBUTE, snapshot.active.colorScheme);
-        }
+        if (disposed)
+            return;
+        cancelHandoff();
+        doc.documentElement.setAttribute(XIAOHEI_APPEARANCE_ATTRIBUTE, snapshot.active.colorScheme);
         releaseXiaoheiBootAppearance(doc);
     };
     const off = ctx.on('theme/change', sync);
-    sync(ctx.theme.getTheme());
+    const initial = ctx.theme.getTheme();
+    const boot = doc.documentElement.getAttribute(XIAOHEI_BOOT_APPEARANCE_ATTRIBUTE);
+    if ((boot === 'light' || boot === 'dark') && boot !== initial.active.colorScheme) {
+        // Preserve the Host's first frame during settings hydration, but never
+        // let a stale boot marker veto later theme events or lock a palette.
+        doc.documentElement.setAttribute(XIAOHEI_APPEARANCE_ATTRIBUTE, boot);
+        if (win)
+            handoff = win.setTimeout(() => sync(ctx.theme.getTheme()), 1000);
+    }
+    else
+        sync(initial);
     return () => {
+        disposed = true;
+        cancelHandoff();
         off();
+        releaseXiaoheiBootAppearance(doc);
         doc.documentElement.removeAttribute(XIAOHEI_APPEARANCE_ATTRIBUTE);
     };
 }

package/lib/blink.js

@@ -1,5 +1,6 @@
 import { XIAOHEI_BLINK_CSS } from './chrome/blink.js';
 import { XIAOHEI_HEIXIU_GREETING_EVENT } from './heixiu-interactions.js';
+import { subscribeXiaoheiHostDom } from './host-dom.js';
 export const XIAOHEI_BLINK_STYLE_ID = 'dsh-theme-xiaohei/blink-style';
 const INITIAL_BLINK_DELAY_MS = 4780;
 const IDLE_BLINK_INTERVAL_MS = 5065;
@@ -84,8 +85,7 @@ export function installXiaoheiBlink(doc = typeof document === 'undefined' ? unde
         });
     };
     const onEnvironmentChange = () => restartIdleBlink();
-    const mountObserver = new win.MutationObserver(attach);
-    mountObserver.observe(doc.body, { childList: true, subtree: true });
+    const unsubscribeHostDom = subscribeXiaoheiHostDom(doc, attach);
     const stateObserver = new win.MutationObserver(onEnvironmentChange);
     stateObserver.observe(doc.documentElement, {
         attributes: true,
@@ -98,7 +98,7 @@ export function installXiaoheiBlink(doc = typeof document === 'undefined' ? unde
     return () => {
         disposed = true;
         clearTimers();
-        mountObserver.disconnect();
+        unsubscribeHostDom();
         stateObserver.disconnect();
         doc.removeEventListener('visibilitychange', onEnvironmentChange);
         doc.removeEventListener(XIAOHEI_HEIXIU_GREETING_EVENT, onHeixiuGreeting);

package/lib/bloub-heixiu/ambient.d.ts

@@ -0,0 +1,3 @@
+export declare function heixiuAmbientDelay(random?: () => number): number;
+export declare function heixiuAmbientIndex(count: number, previous: number, random?: () => number): number;
+//# sourceMappingURL=ambient.d.ts.map

package/lib/bloub-heixiu/ambient.js

@@ -0,0 +1,12 @@
+const unit = (n) => Number.isFinite(n) ? Math.max(0, Math.min(.999999, n)) : .5;
+export function heixiuAmbientDelay(random = Math.random) {
+    return 20_000 + Math.floor(unit(random()) * 20_000);
+}
+export function heixiuAmbientIndex(count, previous, random = Math.random) {
+    if (count <= 1)
+        return 0;
+    const exclude = previous >= 0 && previous < count;
+    const index = Math.floor(unit(random()) * (exclude ? count - 1 : count));
+    return exclude && index >= previous ? index + 1 : index;
+}
+//# sourceMappingURL=ambient.js.map

package/lib/bloub-heixiu/character.d.ts

@@ -0,0 +1,33 @@
+import type { BotExpression } from '../vendor/bloub/expressions.js';
+export declare const HEIXIU_PROFILE: number[];
+export declare const HEIXIU_FACE: BotExpression;
+export declare const HEIXIU_FOOT: number;
+export interface HeixiuReaction {
+    x: number;
+    y: number;
+    sx: number;
+    sy: number;
+    roll: number;
+    lid: number;
+    cheer: number;
+}
+export declare const HEIXIU_REST: HeixiuReaction;
+export declare const HEIXIU_REACTIONS: readonly ["greet", "hop", "wiggle"];
+export type HeixiuReactionId = typeof HEIXIU_REACTIONS[number];
+/** One bounded, interruptible gesture track; never queues clicks or runs timers. */
+export declare class HeixiuReactions {
+    private start;
+    private keys;
+    private hover;
+    private hoverAt;
+    private hoverFrom;
+    private hoverTo;
+    get end(): number;
+    reset(): void;
+    settle(time: number): void;
+    aim(direction: number, time: number): void;
+    private track;
+    play(kind: HeixiuReactionId, time: number, side?: number): void;
+    sample(time: number): HeixiuReaction;
+}
+//# sourceMappingURL=character.d.ts.map

package/lib/bloub-heixiu/character.js

@@ -0,0 +1,124 @@
+import { superellipseProfile } from '../vendor/bloub/shape.js';
+// Slightly wider than tall: a soft black body, not an upright head or a flat
+// pill. Side tips sit near the equator. Keep bloub's 64 radial samples.
+export const HEIXIU_PROFILE = superellipseProfile(2.2, 1, .89).map((r, i, radii) => {
+    const angle = i / radii.length * Math.PI * 2;
+    const bump = (center, width, amount) => {
+        const d = Math.atan2(Math.sin(angle - center), Math.cos(angle - center));
+        return amount * Math.exp(-.5 * (d / width) ** 2);
+    };
+    return r * (1 + .016 * Math.sin(angle))
+        + bump(6.12, .12, .065) + bump(3.30, .12, .065)
+        + bump(4.04, .10, .025);
+});
+export const HEIXIU_FACE = {
+    id: 'neutre', gaze: { yaw: 0, pitch: -7, roll: -2 }, split: 26,
+    eyes: [{ w: .355, h: .48, open: 1 }, { w: .34, h: .465, open: 1 }],
+};
+// Derive the squash pivot from the body itself so a proportion adjustment
+// cannot leave the character rotating/compressing around an invisible foot.
+export const HEIXIU_FOOT = Math.max(...HEIXIU_PROFILE.map((r, i) => r * Math.sin(i / HEIXIU_PROFILE.length * Math.PI * 2))) * 100;
+export const HEIXIU_REST = { x: 0, y: 0, sx: 1, sy: 1, roll: 0, lid: 1, cheer: 0 };
+export const HEIXIU_REACTIONS = ['greet', 'hop', 'wiggle'];
+const smooth = (x) => { const k = Math.max(0, Math.min(1, x)); return k * k * (3 - 2 * k); };
+const pose = (over) => ({ ...HEIXIU_REST, ...over });
+const CHANNELS = Object.keys(HEIXIU_REST);
+// Shape-preserving Hermite tangents: a rising/falling arc passes through its
+// intermediate samples without stopping at every key. Extrema still settle,
+// and lids/scales never overshoot their authored bounds.
+function tangent(keys, index, channel) {
+    if (index === 0 || index === keys.length - 1)
+        return 0;
+    const a = keys[index - 1], b = keys[index], c = keys[index + 1];
+    const h0 = b.at - a.at, h1 = c.at - b.at;
+    const d0 = (b.pose[channel] - a.pose[channel]) / h0, d1 = (c.pose[channel] - b.pose[channel]) / h1;
+    if (d0 * d1 <= 0)
+        return 0;
+    const w0 = 2 * h1 + h0, w1 = h1 + 2 * h0;
+    return (w0 + w1) / (w0 / d0 + w1 / d1);
+}
+/** One bounded, interruptible gesture track; never queues clicks or runs timers. */
+export class HeixiuReactions {
+    start = 0;
+    keys = [];
+    hover = 0;
+    hoverAt = 0;
+    hoverFrom = 0;
+    hoverTo = 0;
+    get end() { return this.start + (this.keys.at(-1)?.at ?? 0); }
+    reset() { this.keys = []; this.hover = this.hoverFrom = this.hoverTo = 0; }
+    settle(time) {
+        const origin = this.track(time);
+        this.start = time;
+        this.keys = [{ at: 0, pose: origin }, { at: .22, pose: { ...HEIXIU_REST } }];
+        this.aim(0, time);
+    }
+    aim(direction, time) {
+        this.hover = this.hoverFrom + (this.hoverTo - this.hoverFrom) * smooth((time - this.hoverAt) / .28);
+        this.hoverFrom = this.hover;
+        this.hoverTo = Math.max(-1, Math.min(1, direction));
+        this.hoverAt = time;
+    }
+    track(time) {
+        if (!this.keys.length || time >= this.end)
+            return { ...HEIXIU_REST };
+        const t = Math.max(0, time - this.start);
+        let left = this.keys[0];
+        for (let i = 1; i < this.keys.length; i++) {
+            const right = this.keys[i];
+            if (t <= right.at) {
+                const span = right.at - left.at, k = (t - left.at) / span;
+                const k2 = k * k, k3 = k2 * k;
+                const out = { ...left.pose };
+                for (const key of CHANNELS) {
+                    out[key] = (2 * k3 - 3 * k2 + 1) * left.pose[key] + (-2 * k3 + 3 * k2) * right.pose[key]
+                        + (k3 - 2 * k2 + k) * span * tangent(this.keys, i - 1, key)
+                        + (k3 - k2) * span * tangent(this.keys, i, key);
+                }
+                return out;
+            }
+            left = right;
+        }
+        return { ...HEIXIU_REST };
+    }
+    play(kind, time, side = 1) {
+        const origin = this.track(time), sign = side < 0 ? -1 : 1;
+        const keys = [{ at: 0, pose: origin }];
+        const add = (at, over) => keys.push({ at, pose: pose(over) });
+        if (kind === 'greet') {
+            add(.09, { lid: .25, sy: .99, cheer: .35 });
+            add(.16, { lid: 0, sy: .985, cheer: .35, roll: -2 * sign });
+            add(.26, { y: -2, sy: 1.005, roll: 1 * sign });
+            add(.43, { y: -7, sx: .99, sy: 1.015, roll: 3 * sign });
+            add(.67, { sx: 1.018, sy: .982, roll: -1 * sign });
+            add(.95, {});
+        }
+        else if (kind === 'hop') {
+            add(.12, { sx: 1.065, sy: .94, lid: .85, roll: -2 * sign });
+            add(.23, { sx: .97, sy: 1.045, y: -14, roll: 2 * sign });
+            add(.40, { sx: .99, sy: 1.02, y: -28, roll: 3 * sign });
+            add(.57, { sy: 1.015, y: -14, roll: 1 * sign });
+            add(.69, { sx: 1.06, sy: .94, lid: .55, cheer: .3 });
+            add(.80, { sx: .985, sy: 1.02 });
+            add(1.02, {});
+        }
+        else {
+            add(.18, { x: -2 * sign, roll: -7 * sign });
+            add(.38, { x: 2 * sign, roll: 7 * sign });
+            add(.55, { x: -1 * sign, roll: -3 * sign, lid: .3, cheer: .2 });
+            add(.64, { roll: -1 * sign, lid: 0, cheer: .2 });
+            add(.78, {});
+            add(.96, {});
+        }
+        this.start = time;
+        this.keys = keys;
+    }
+    sample(time) {
+        const out = this.track(time);
+        this.hover = this.hoverFrom + (this.hoverTo - this.hoverFrom) * smooth((time - this.hoverAt) / .28);
+        out.roll += this.hover * 5;
+        out.x += this.hover * 4;
+        return out;
+    }
+}
+//# sourceMappingURL=character.js.map

package/lib/bloub-heixiu/effects.d.ts

@@ -0,0 +1,4 @@
+import type { BotFrame } from '../vendor/bloub/engine.js';
+/** Allocated once on first explicit special action, never from the frame loop. */
+export declare function createHeixiuEffects(doc: Document, id: string, defs: SVGDefsElement, behind: SVGGElement, front: SVGGElement, body: SVGGElement): (frame: BotFrame) => void;
+//# sourceMappingURL=effects.d.ts.map

package/lib/bloub-heixiu/effects.js

@@ -0,0 +1,91 @@
+const NS = 'http://www.w3.org/2000/svg';
+/** Allocated once on first explicit special action, never from the frame loop. */
+export function createHeixiuEffects(doc, id, defs, behind, front, body) {
+    const el = (name) => doc.createElementNS(NS, name);
+    const attrs = (node, values) => {
+        for (const [key, value] of Object.entries(values)) {
+            const text = String(value);
+            if (node.getAttribute(key) !== text)
+                node.setAttribute(key, text);
+        }
+    };
+    const dotsBack = el('g'), dotsFront = el('g');
+    behind.append(dotsBack);
+    front.append(dotsFront);
+    // Real transparent notch, never a wallpaper-coloured disc over the body.
+    const mask = el('mask'), surface = el('rect'), notch = el('circle'), badge = el('circle');
+    attrs(mask, { id: `${id}-notification`, maskUnits: 'userSpaceOnUse', x: -200, y: -200, width: 400, height: 400, 'mask-type': 'luminance' });
+    attrs(surface, { x: -200, y: -200, width: 400, height: 400, fill: 'white' });
+    attrs(notch, { fill: 'black', r: 0, 'data-heixiu-notch': '' });
+    attrs(badge, { fill: '#dca964', display: 'none', 'data-heixiu-notification': '' });
+    mask.append(surface, notch);
+    defs.append(mask);
+    front.append(badge);
+    const dots = Array.from({ length: 12 }, () => {
+        const node = el('path');
+        attrs(node, { display: 'none', 'data-heixiu-particle': '' });
+        dotsFront.append(node);
+        return node;
+    });
+    const arcs = Array.from({ length: 12 }, (_, i) => {
+        const gradient = el('linearGradient'), back = el('path'), fore = el('path');
+        attrs(gradient, { id: `${id}-arc-${i}`, gradientUnits: 'userSpaceOnUse' });
+        const stops = Array.from({ length: 3 }, () => el('stop'));
+        gradient.append(...stops);
+        defs.append(gradient);
+        for (const node of [back, fore])
+            attrs(node, {
+                fill: 'none', 'stroke-linecap': 'round', stroke: `url(#${id}-arc-${i})`, display: 'none', 'data-heixiu-orbit': '',
+            });
+        behind.append(back);
+        front.append(fore);
+        return { gradient, back, fore, stops };
+    });
+    return (frame) => {
+        if (frame.notif && frame.notch) {
+            attrs(body, { mask: `url(#${id}-notification)` });
+            attrs(notch, { cx: frame.notch.x, cy: frame.notch.y, r: frame.notch.r });
+            attrs(badge, { display: 'inline', cx: frame.notif.x, cy: frame.notif.y, r: frame.notif.r });
+        }
+        else {
+            if (body.getAttribute('mask'))
+                body.removeAttribute('mask');
+            attrs(notch, { r: 0 });
+            attrs(badge, { display: 'none' });
+        }
+        for (const [i, node] of dots.entries()) {
+            const dot = frame.dots[i];
+            if (!dot) {
+                attrs(node, { display: 'none' });
+                continue;
+            }
+            const parent = frame.dotsBehind ? dotsBack : dotsFront;
+            if (node.parentNode !== parent)
+                parent.append(node);
+            const r = dot.r;
+            attrs(node, { display: 'inline',
+                d: dot.d ?? `M${-r} 0a${r} ${r} 0 1 0 ${r * 2} 0a${r} ${r} 0 1 0 ${-r * 2} 0`,
+                transform: `translate(${dot.x} ${dot.y}) rotate(${dot.rot ?? 0}) scale(${dot.d ? 100 : 1})`,
+                fill: dot.color ?? 'var(--heixiu-ink)', opacity: dot.opacity * (dot.depth ?? 1),
+            });
+        }
+        for (const [i, nodes] of arcs.entries()) {
+            const arc = frame.arcs[i];
+            if (!arc) {
+                attrs(nodes.back, { display: 'none' });
+                attrs(nodes.fore, { display: 'none' });
+                continue;
+            }
+            attrs(nodes.gradient, { x1: arc.grad.x1, y1: arc.grad.y1, x2: arc.grad.x2, y2: arc.grad.y2 });
+            for (const [j, stop] of nodes.stops.entries())
+                attrs(stop, {
+                    offset: j / 2, 'stop-color': arc.grad.stops[Math.min(j, arc.grad.stops.length - 1)] ?? '#ddd',
+                });
+            for (const [node, d] of [[nodes.back, arc.back], [nodes.fore, arc.front]])
+                attrs(node, {
+                    display: 'inline', d, 'stroke-width': arc.width, opacity: arc.opacity,
+                });
+        }
+    };
+}
+//# sourceMappingURL=effects.js.map

package/lib/bloub-heixiu/flight.d.ts

@@ -0,0 +1,15 @@
+export interface HeixiuBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** FLIP between native docks; the existing SVG and reaction clock stay alive. */
+export declare function createHeixiuFlight(button: HTMLElement): {
+    readonly active: boolean;
+    capture: (fallback?: HeixiuBox) => HeixiuBox | undefined;
+    target(measured: HeixiuBox): HeixiuBox;
+    move(from: HeixiuBox | undefined, to: HeixiuBox, reduced: boolean): void;
+    cancel: () => void;
+};
+//# sourceMappingURL=flight.d.ts.map

package/lib/bloub-heixiu/flight.js

@@ -0,0 +1,66 @@
+const copyBox = (box) => ({ left: box.left, top: box.top, width: box.width, height: box.height });
+/** FLIP between native docks; the existing SVG and reaction clock stay alive. */
+export function createHeixiuFlight(button) {
+    let animation;
+    let route;
+    const active = () => animation?.playState === 'running';
+    const progress = () => Math.max(0, Math.min(1, animation?.effect?.getComputedTiming().progress ?? 0));
+    // Native borders can settle by half a CSS pixel; this is not a new flight.
+    const same = (a, b) => ['left', 'top', 'width', 'height'].every(k => Math.abs(a[k] - b[k]) < 1);
+    function position(fallback) {
+        if (!active() || !route)
+            return fallback;
+        const p = progress();
+        const lerp = (key) => route.from[key] + (route.to[key] - route.from[key]) * p;
+        return { left: lerp('left'), top: lerp('top'), width: lerp('width'), height: lerp('height') };
+    }
+    function cancel() {
+        if (animation) {
+            animation.onfinish = null;
+            animation.cancel();
+            animation = undefined;
+        }
+        route = undefined;
+        button.dataset.flying = 'false';
+    }
+    return {
+        get active() { return active(); },
+        // Read the previous viewport trajectory, not a box already displaced by
+        // the moving composer. Capturing must not cancel/restart an equal target.
+        capture: position,
+        target(measured) {
+            if (!active() || !route)
+                return measured;
+            const p = progress(), { from, to } = route;
+            const scale = (from.width / to.width) * (1 - p) + p;
+            const width = measured.width / scale, height = measured.height / scale;
+            const dx = (from.left + from.width / 2 - to.left - to.width / 2) * (1 - p);
+            const dy = (from.top + from.height / 2 - to.top - to.height / 2) * (1 - p);
+            return { left: measured.left - dx + (measured.width - width) / 2,
+                top: measured.top - dy + (measured.height - height) / 2, width, height };
+        },
+        move(from, to, reduced) {
+            if (!reduced && active() && route && same(route.to, to))
+                return;
+            const duration = active() && route ? Math.max(80, route.duration - Number(animation.currentTime ?? 0)) : 950;
+            cancel();
+            if (!from || reduced || typeof button.animate !== 'function' || !from.width || !to.width)
+                return;
+            const dx = from.left + from.width / 2 - to.left - to.width / 2;
+            const dy = from.top + from.height / 2 - to.top - to.height / 2;
+            if (Math.hypot(dx, dy) < 4 && Math.abs(from.width - to.width) < 1)
+                return;
+            route = { from: copyBox(from), to: copyBox(to), duration };
+            animation = button.animate([
+                { transform: `translate(${dx}px, ${dy}px) scale(${from.width / to.width})` },
+                { transform: 'translate(0px, 0px) scale(1)' },
+            ], { duration, easing: 'cubic-bezier(.22,.75,.2,1)' });
+            button.dataset.flying = 'true';
+            const current = animation;
+            current.onfinish = () => { if (animation === current)
+                cancel(); };
+        },
+        cancel,
+    };
+}
+//# sourceMappingURL=flight.js.map

package/lib/bloub-heixiu/follow.d.ts

@@ -0,0 +1,13 @@
+/** Attraction measured from the stationary hit area, not the moving artwork. */
+export declare function resolveHeixiuGaze(dx: number, dy: number): {
+    yaw: number;
+    pitch: number;
+    mix: number;
+    spin: number;
+    wander: number;
+};
+export declare function resolveHeixiuFollow(dx: number, dy: number, compact: boolean): {
+    x: number;
+    y: number;
+};
+//# sourceMappingURL=follow.d.ts.map

package/lib/bloub-heixiu/follow.js

@@ -0,0 +1,23 @@
+/** Attraction measured from the stationary hit area, not the moving artwork. */
+export function resolveHeixiuGaze(dx, dy) {
+    if (!Number.isFinite(dx) || !Number.isFinite(dy))
+        return { yaw: 0, pitch: -7, mix: 1, spin: 0, wander: .35 };
+    return { yaw: Math.max(-14, Math.min(14, dx / 16)),
+        // The old upper limit was -7 + 9 = 2 degrees: barely above straight ahead.
+        pitch: -7 - Math.max(-31, Math.min(9, dy / 16)), mix: 1, spin: 0, wander: 0 };
+}
+export function resolveHeixiuFollow(dx, dy, compact) {
+    if (!Number.isFinite(dx) || !Number.isFinite(dy))
+        return { x: 0, y: 0 };
+    const distance = Math.hypot(dx, dy), radius = compact ? 90 : 140;
+    if (distance >= radius)
+        return { x: 0, y: 0 };
+    const k = Math.max(0, Math.min(1, (distance - radius * .5) / (radius * .5)));
+    const fade = 1 - k * k * (3 - 2 * k);
+    const divisor = Math.max(compact ? 32 : 50, distance);
+    return {
+        x: dx / divisor * (compact ? 2 : 5) * fade,
+        y: dy / divisor * (compact ? 1.5 : 3.5) * fade,
+    };
+}
+//# sourceMappingURL=follow.js.map

package/lib/bloub-heixiu/layout.d.ts

@@ -0,0 +1,18 @@
+export declare function resolveHeixiuDock(composerLeft: number, sidebarRight: number, viewportWidth: number): {
+    readonly mode: "outside" | "compact";
+    readonly size: 96 | 52;
+};
+export declare function resolveHeixiuWelcome(hero: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, composer: {
+    left: number;
+    top: number;
+}, sidebarRight: number, viewportWidth: number): {
+    size: number;
+    left: number;
+    top: number;
+} | undefined;
+//# sourceMappingURL=layout.d.ts.map

package/lib/bloub-heixiu/layout.js

@@ -0,0 +1,12 @@
+export function resolveHeixiuDock(composerLeft, sidebarRight, viewportWidth) {
+    const outside = viewportWidth > 760 && composerLeft - sidebarRight >= 114;
+    return { mode: outside ? 'outside' : 'compact', size: outside ? 96 : 52 };
+}
+export function resolveHeixiuWelcome(hero, composer, sidebarRight, viewportWidth) {
+    if (hero.width <= 0 || hero.height <= 0 || hero.top + hero.height > composer.top)
+        return undefined;
+    const size = viewportWidth <= 760 ? 52 : 96;
+    const left = Math.max(sidebarRight + 6, hero.left - size - (size === 52 ? 10 : 24));
+    return { size, left: left - composer.left, top: hero.top + hero.height / 2 - size / 2 - composer.top };
+}
+//# sourceMappingURL=layout.js.map