@deepseek-harness-tui/dsh-tui 0.12.0 → 0.14.0

package/lib/types/components/sidePanel/companion/mood.js

@@ -0,0 +1,256 @@
+// ---------------------------------------------------------------------------
+// 量级常量（回归直接引用，勿在测试/组件里硬编码另一份）
+// ---------------------------------------------------------------------------
+/** 离开活跃族的防抖窗：目标稳定非工作这么久才切走（规则 3）。 */
+export const LEAVE_WORKING_SETTLE_MS = 1500;
+/** 任何非抢占切换后的最短停留（规则 4）。 */
+export const MIN_MOOD_DWELL_MS = 1000;
+/** 回合完成庆祝（happy）的停留窗；由 Panel 在 working→false 边沿armed。 */
+export const CELEBRATE_DWELL_MS = 2500;
+/** idle 族动画的轮换周期（规则 5）。 */
+export const IDLE_ROTATE_MS = 8000;
+/** 狂点判定窗口：窗口内 ≥TICKLE_MIN_CLICKS 次点击 → tickle。 */
+export const TICKLE_WINDOW_MS = 900;
+export const TICKLE_MIN_CLICKS = 3;
+/** 通知气泡的展示时长（约数，按动画 tick 粒度收回）。 */
+export const NOTIFICATION_BUBBLE_MS = 5000;
+/** 醒来（waking）反应的闪现时长。 */
+export const WAKING_FLASH_MS = 1800;
+/** 顶箱子（carrying，gitBranch 变更闪现）时长。 */
+export const CARRYING_FLASH_MS = 2500;
+/** Enter 戳一戳时完整活动行气泡的时长。 */
+export const POKE_MS = 3000;
+/** 工作态细分：activity 投影优先，缺省时 spinnerMode 兜底。 */
+function workingMood(inputs) {
+    const activity = inputs.activity;
+    if (activity !== undefined && activity.phase !== 'idle' && activity.phase !== 'done') {
+        if (activity.phase === 'waiting')
+            return 'waiting';
+        if (activity.phase === 'thinking')
+            return 'thinking';
+        return 'working';
+    }
+    switch (inputs.spinnerMode) {
+        case 'requesting':
+            return 'waiting';
+        case 'thinking':
+            return 'thinking';
+        case 'responding':
+            return 'responding';
+        case 'tool-use':
+        case 'tool-input':
+            return 'working';
+    }
+}
+/** 纯派生（规则 1 的第一层）：attention > error > working > celebrate >
+ *  sleeping > idle。 */
+export function deriveCompanionMood(inputs, now) {
+    let mood;
+    if (inputs.attention.approvalPending || inputs.attention.questionPending)
+        mood = 'attention';
+    else if (inputs.failures.failedJobsUnread > 0 || inputs.failures.failedSubagents > 0)
+        mood = 'error';
+    else if (inputs.working)
+        mood = workingMood(inputs);
+    else if (inputs.celebration !== undefined && now < inputs.celebration.until)
+        mood = 'celebrate';
+    else if (inputs.sleepAfterMs > 0 && now - inputs.lastInputAt >= inputs.sleepAfterMs)
+        mood = 'sleeping';
+    else
+        mood = 'idle';
+    const bubble = mood === 'sleeping' || mood === 'idle' ? undefined : bubbleOf(inputs);
+    return { mood, bubble };
+}
+function bubbleOf(inputs) {
+    const activity = inputs.activity;
+    if (activity === undefined)
+        return undefined;
+    if (activity.phrase !== undefined && activity.phrase !== '')
+        return activity.phrase;
+    const label = activity.label ?? '';
+    const detail = activity.detail ?? '';
+    const combined = (label + (label !== '' && detail !== '' ? ' ' : '') + detail).trim();
+    return combined === '' ? undefined : combined;
+}
+/** 子代理在跑数（starting/running）。 */
+export function countRunningSubagents(subagents) {
+    return subagents.filter(s => s.status === 'starting' || s.status === 'running').length;
+}
+/** 后台任务在跑数（running/stopping 都算活着）。 */
+export function countRunningJobs(jobs) {
+    return jobs.filter(j => j.status === 'running' || j.status === 'stopping').length;
+}
+/** 「会话」口径：主回合（working 计 1）+ 在跑子代理 + 在跑后台任务。 */
+export function countSessionsRunning(working, runningSubagents, runningJobs) {
+    return (working ? 1 : 0) + runningSubagents + runningJobs;
+}
+/** 素材包官方表：conducting=2+ 子代理；building=3+ 会话；music=1 子代理或
+ *  2 会话；compacting=上下文压缩进行中（ChannelUi.compaction 是现成信号）。
+ *  优先级：compacting > conducting > building > music（子代理专属动画最具体）。
+ *  carrying（新建工作树/分支）没有推送信号，走 gitBranch 变更闪现（Panel 接线）。 */
+export function deriveCompanionContext(inputs) {
+    if (inputs.compaction !== undefined && inputs.compaction !== null)
+        return 'compacting';
+    const runningSubagents = countRunningSubagents(inputs.subagents);
+    const sessions = countSessionsRunning(inputs.working, runningSubagents, countRunningJobs(inputs.backgroundJobs));
+    if (runningSubagents >= 2)
+        return 'conducting';
+    if (sessions >= 3)
+        return 'building';
+    if (runningSubagents >= 1 || sessions >= 2)
+        return 'music';
+    return undefined;
+}
+export const initialCompanionDisplayState = {
+    semantic: 'idle',
+    since: 0,
+    activeLeftAt: 0,
+};
+/** 活跃族 = working 细分 + 并行上下文（离开它们进 idle 族要防抖）。 */
+const ACTIVE_SEMANTICS = new Set([
+    'thinking', 'typing', 'music', 'conducting', 'building', 'compacting',
+]);
+/** working 细分（进入它不防抖——有信息量）。 */
+const WORKING_SEMANTICS = new Set(['thinking', 'typing']);
+/** idle 族（settle 闸只对它们生效）。 */
+const IDLE_FAMILY = new Set(['idle', 'sleeping']);
+/** 允许立刻打断的语义（规则 2）。 */
+const IMMEDIATE_SEMANTICS = new Set(['notification', 'error', 'happy']);
+/** 目标心情 + 上下文 → 目标显示语义（纯函数）。attention/error/happy 直通；
+ *  working 细分与 idle/sleeping 在有并行上下文时让位（music=官方表的
+ *  juggling：主回合 + 子代理同时在跑时宠物该演"分身"而不是敲代码）。 */
+export function resolveTargetSemantic(mood, context) {
+    if (mood === 'attention')
+        return 'notification';
+    if (mood === 'error')
+        return 'error';
+    if (mood === 'celebrate')
+        return 'happy';
+    if (mood === 'waiting' || mood === 'thinking')
+        return context ?? 'thinking';
+    if (mood === 'working' || mood === 'responding')
+        return context ?? 'typing';
+    return context ?? (mood === 'sleeping' ? 'sleeping' : 'idle');
+}
+/** 平滑器（规则 2/3/4，近纯步进）：输入目标语义流 + 时钟，输出显示语义流。
+ *
+ * - 目标 == 当前显示：什么都不动（since 保留 → 动画 elapsed 连续）。
+ * - 抢占（notification/error/happy）或进入 working 族：立刻切。
+ * - 其余切换：settle（离开活跃族进 idle 族需 LEAVE_WORKING_SETTLE_MS 稳定）
+ *   与 dwell（显示语义已停留 MIN_MOOD_DWELL_MS）双闸全开才切。
+ * - realign：visible=false→true 时跳过闸门对齐当前目标（隐藏期间没走 tick）。
+ */
+export function stepCompanionDisplay(prev, target, now, opts) {
+    const targetActive = ACTIVE_SEMANTICS.has(target);
+    const activeLeftAt = targetActive ? 0 : prev.activeLeftAt === 0 ? now : prev.activeLeftAt;
+    if (opts?.realign === true)
+        return { semantic: target, since: now, activeLeftAt };
+    if (target === prev.semantic) {
+        return { semantic: prev.semantic, since: prev.since, activeLeftAt };
+    }
+    const immediate = IMMEDIATE_SEMANTICS.has(target) ||
+        (WORKING_SEMANTICS.has(target) && !WORKING_SEMANTICS.has(prev.semantic));
+    if (immediate)
+        return { semantic: target, since: now, activeLeftAt };
+    const settleOk = !IDLE_FAMILY.has(target) || now - activeLeftAt >= LEAVE_WORKING_SETTLE_MS;
+    const dwellOk = now - prev.since >= MIN_MOOD_DWELL_MS;
+    if (settleOk && dwellOk)
+        return { semantic: target, since: now, activeLeftAt };
+    return { semantic: prev.semantic, since: prev.since, activeLeftAt };
+}
+// ---------------------------------------------------------------------------
+// 悬停驻留（hover dwell）：指针停够一会儿才换成悬停动画
+// ---------------------------------------------------------------------------
+/** 指针驻留多久才切到悬停动画（enter dwell）：400ms 内移开的划过不触发
+ *  切换。约为 poke 动画（~70ms/帧）半轮的时长。 */
+export const HOVER_ENTER_DWELL_MS = 400;
+/** 指针移开多久才切回非悬停档（leave settle）：短暂滑出面板（跨分区、
+ *  贴边抖动）不打断动画。比 LEAVE_WORKING_SETTLE_MS（1500）短，悬停只是
+ *  装饰，可以恢复得快一些。 */
+export const HOVER_LEAVE_SETTLE_MS = 800;
+export const initialCompanionHoverState = {
+    semantic: undefined,
+    since: 0,
+    desired: undefined,
+    desiredSince: 0,
+};
+/** 悬停驻留平滑器（近纯步进，与 stepCompanionDisplay 同模式）：输入期望
+ *  语义流（指针 zone 直读）+ 时钟，输出展示中的悬停语义流。
+ *
+ * - 期望 == 展示：什么都不动（since 保留 → 动画 elapsed 连续）。
+ * - 移入/换档（look↔notice）：驻留满 HOVER_ENTER_DWELL_MS 才切；快速划过
+ *  （enter 后未满窗就移开）全程不触发。
+ * - 移开：迟滞满 HOVER_LEAVE_SETTLE_MS 才切回；窗口内折返 = 期望回到当前
+ *  展示值 → 动画无缝续播（since 不重置）。
+ * - 互动覆盖层（poke/tickle/爱心）不经过本函数：点击反馈即时性不受影响。
+ */
+export function stepCompanionHover(prev, desired, now) {
+    const desiredSince = desired === prev.desired ? prev.desiredSince : now;
+    if (desired === prev.semantic) {
+        return { semantic: prev.semantic, since: prev.since, desired, desiredSince };
+    }
+    if (desired === undefined) {
+        // 移开：迟滞窗外保持展示（指针折返不打断）；满窗切回非悬停档。
+        if (now - desiredSince >= HOVER_LEAVE_SETTLE_MS) {
+            return { semantic: undefined, since: prev.since, desired, desiredSince };
+        }
+        return { ...prev, desired, desiredSince };
+    }
+    // 移入/换档：驻留满窗才真正切到悬停动画（快速划过不触发）。
+    if (now - desiredSince >= HOVER_ENTER_DWELL_MS) {
+        return { semantic: desired, since: now, desired, desiredSince };
+    }
+    return { ...prev, desired, desiredSince };
+}
+// ---------------------------------------------------------------------------
+// idle 族轮换（规则 5：按时间，不跟信号边沿）
+// ---------------------------------------------------------------------------
+/** idle 显示语义下的动画轮换槽序号：由进入 idle 的时刻与当前时钟决定，
+ *  与信号无关；同一 idle 期内确定，跨 idle 期自然错开。 */
+export function idleRotationIndex(idleSince, now, length) {
+    if (length <= 1 || idleSince <= 0)
+        return 0;
+    const slot = Math.max(0, Math.floor((now - idleSince) / IDLE_ROTATE_MS));
+    const offset = Math.abs(Math.floor(idleSince / 997)) % length;
+    return (slot + offset) % length;
+}
+/** NotificationItem.color → 反应档（error/warning/success/default）。
+ *  没有更多语义字段可判（如"已打断"），default 档用 idle-look——见交付说明。 */
+export function notificationReactionKind(color) {
+    if (color === 'error' || color === 'warning' || color === 'success')
+        return color;
+    return 'default';
+}
+export function createNotificationTracker() {
+    return { seen: new Set(), armed: false };
+}
+/** 渲染期步进：从尾部扫描未见过的条目（notify 追加在最后），返回最新一条
+ *  （旧的让位——气泡同时只留最新）；首次调用只记账不发射（不弹历史旧账）。
+ *  重建数组（slice/filter）但条目对象同引用时不会误报；条目被摘除时顺手
+ *  清理 seen，防泄漏。 */
+export function stepNotificationTracker(tracker, notifications, opts) {
+    let newest;
+    let scanned = 0;
+    for (let index = notifications.length - 1; index >= 0 && scanned < 16; index -= 1) {
+        const item = notifications[index];
+        if (item === undefined)
+            break;
+        scanned += 1;
+        if (tracker.seen.has(item))
+            break;
+        tracker.seen.add(item);
+        newest = newest ?? item;
+    }
+    if (tracker.seen.size > notifications.length + 8) {
+        const live = new Set(notifications);
+        for (const item of tracker.seen) {
+            if (!live.has(item))
+                tracker.seen.delete(item);
+        }
+    }
+    if (!tracker.armed || opts?.silent === true) {
+        tracker.armed = true;
+        return undefined;
+    }
+    return newest;
+}

package/lib/types/components/sidePanel/companion/pose.d.ts

@@ -0,0 +1,43 @@
+/**
+ * planPose（设计分文档 §2 + v2.1 修订）：皮肤无关的动画词汇。
+ *
+ * v2.1 的关键修订（评审 §八）：whaleIdle 是**多层同时发生**的规划器
+ * （tail + fin + blink + heart + sleep 各自独立），单一 gesture 字段会
+ * 丢信息、也无法做到帧级一致。因此：
+ * - gestures 是一个集合（wag + flutter 可以同时成立）；
+ * - nativeWhalePose 原样携带 WhaleLayerPose——鲸鱼皮肤 100% 复用现有
+ *   分层渲染（与开屏 splash 同一规划器、同一帧表，帧级 parity 免费），
+ *   其他皮肤只消费自己能理解的通用语义子集。
+ *
+ * 实现上就是 nextWhaleIdleStep 的薄包装：mood 映射到它的 working 输入
+ * （waiting/thinking/working/responding → working=true，与分文档一致；
+ * attention 也算 working——有需要用户处理的事时宠物应该醒着且活跃），
+ * 规划器本身一行不动。
+ */
+import type { WhaleLayerPose } from '../../whaleLayers.js';
+import { initialWhaleIdleState, type WhaleIdleState } from '../../whaleIdle.js';
+import type { CompanionMood } from './mood.js';
+export type CompanionGesture = 'wag' | 'flutter' | 'spout' | 'nod' | 'wave';
+export interface CompanionPose {
+    readonly mood: CompanionMood;
+    /** 0.. 单调递增，皮肤按自己的帧率取模（由 now/120 派生）。 */
+    readonly tick: number;
+    readonly gestures: ReadonlySet<CompanionGesture>;
+    readonly blink: boolean;
+    readonly heart: 0 | 1 | 2 | 3;
+    readonly sleepZ: 0 | 1 | 2 | 3 | 4 | 5;
+    readonly facing: 'left' | 'right';
+    /** 鲸鱼皮肤专用：与开屏 splash 完全一致的原始分层姿态。 */
+    readonly nativeWhalePose: WhaleLayerPose;
+}
+export interface CompanionPoseStep {
+    readonly state: WhaleIdleState;
+    readonly pose: CompanionPose;
+    readonly delayMs: number;
+}
+export declare const initialCompanionPoseState: typeof initialWhaleIdleState;
+export declare function nextCompanionPoseStep(prev: WhaleIdleState, input: {
+    readonly mood: CompanionMood;
+    readonly heart: boolean;
+}, now: number): CompanionPoseStep;
+//# sourceMappingURL=pose.d.ts.map

package/lib/types/components/sidePanel/companion/pose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pose.d.ts","sourceRoot":"","sources":["../../../../../src/components/sidePanel/companion/pose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EACL,qBAAqB,EAErB,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAE9C,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAA;AAE3E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAA;IAChD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC,qCAAqC;IACrC,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAA;CACzC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,eAAO,MAAM,yBAAyB,8BAAwB,CAAA;AAU9D,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAChE,GAAG,EAAE,MAAM,GACV,iBAAiB,CAyBnB"}

package/lib/types/components/sidePanel/companion/pose.js

@@ -0,0 +1,34 @@
+import { initialWhaleIdleState, nextWhaleIdleStep, } from '../../whaleIdle.js';
+export const initialCompanionPoseState = initialWhaleIdleState;
+const AWAKE_ACTIVE_MOODS = new Set([
+    'waiting',
+    'thinking',
+    'working',
+    'responding',
+    'attention',
+]);
+export function nextCompanionPoseStep(prev, input, now) {
+    const step = nextWhaleIdleStep(prev, { working: AWAKE_ACTIVE_MOODS.has(input.mood), heart: input.heart }, now);
+    const layers = step.pose;
+    const gestures = new Set();
+    if (layers.tail > 0)
+        gestures.add('wag');
+    if (layers.fin > 0)
+        gestures.add('flutter');
+    if (layers.spout > 0)
+        gestures.add('spout');
+    return {
+        state: step.state,
+        pose: {
+            mood: input.mood,
+            tick: Math.max(0, Math.floor(now / 120)),
+            gestures,
+            blink: layers.blink,
+            heart: Math.min(3, Math.max(0, layers.heart)),
+            sleepZ: Math.min(5, Math.max(0, layers.sleep)),
+            facing: 'left',
+            nativeWhalePose: layers,
+        },
+        delayMs: step.delayMs,
+    };
+}

package/lib/types/components/sidePanel/companion/skins.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Companion 皮肤接口与注册表（设计分文档 §3 + v2.1）：皮肤拿到的是
+ * CompanionPose（多层语义 + nativeWhalePose）与渲染上下文；皮肤只实现
+ * 自己理解的语义子集，未支持的姿态退化而不是报错。
+ *
+ * 用户的 deepy 是默认皮肤（DEEPY_MOOD_ANIMATION 逐心情整段动画）；
+ * WhaleGirlSkin 用用户提供的鲸娘素材包（assets/whaleGirl，映射表与 deepy
+ * 同源，仅 smile-hearts / thumbs-up 两键独有）；WhaleSkin 复用开屏分层
+ * 规划器的 nativeWhalePose（与 splash 帧级一致）。
+ * 插件皮肤（纯数据帧表，分文档 §6）留到 Phase 7，注册表先把接缝定好：
+ * 皮肤 = id + cells + render(pose, ctx)，自定义皮肤走同一接口进入。
+ */
+import React from 'react';
+import type { I18nKey } from '../../../i18n.js';
+import type { TerminalImageSource } from '../../../ink/terminal-image.js';
+import type { CompanionMood } from './mood.js';
+import type { CompanionPose } from './pose.js';
+export interface CompanionSkinRenderInput {
+    readonly pose: CompanionPose;
+    /** 当前心情进入的时刻（动画从 0 计 elapsed 的起点）。 */
+    readonly moodSince: number;
+    readonly now: number;
+    /** 可用宽度（皮肤永不超宽：宽度不足由 Panel 决定用不用 small）。 */
+    readonly width: number;
+    /** 当前应播的动画键——CompanionPanel 的平滑层+互动层裁决结果，取
+     *  deepy 规范键词汇表（即素材包 20 键：'typing' / 'poke-left' /
+     *  'tickle' / 'idle-look' / 'notification' …），任何皮肤都能对互动
+     *  做反应；互动覆盖期间 moodSince = 覆盖开始时刻（elapsed 从头播）。
+     *  旧调用方（缺省）皮肤退回 pose.mood 分层，属皮肤接口「未支持即
+     *  退化」契约。 */
+    readonly animationSemantic?: string;
+}
+export interface CompanionSkin {
+    readonly id: string;
+    readonly titleKey?: I18nKey;
+    readonly title?: string;
+    /** 固定占位（列×行），永不随帧变化（§16.6 列宽不变硬约束）。 */
+    readonly cells: {
+        readonly columns: number;
+        readonly rows: number;
+    };
+    readonly graphics: 'none' | 'optional' | 'required';
+    /** 本皮肤对 animationSemantic（deepy 规范键）的声明式落点表：规范键
+     *  → 自家动画键；未列出的键同名直通（自家 kit 键集相同即可）。皮肤
+     *  解析不出落点（semanticMap 缺 + 自家 kit 也没有同名键）→ 退回 mood
+     *  层（pose.mood/pose.heart），不报错。像素鲸这类无帧表皮肤不声明，
+     *  维持原样忽略。 */
+    readonly semanticMap?: Readonly<Record<string, string>>;
+    render(input: CompanionSkinRenderInput): React.ReactNode;
+}
+/** deepy 小鲸鱼（默认）：语义/心情 → 动画，elapsed → frameAt 确定性选帧。 */
+export declare const DeepySkin: CompanionSkin;
+/** 图像轨单元格盒列数：15 行预算 × 像元比 × 帧宽高比，钳在 cells.columns
+ * （超出时调用方按 contain 收行）。导出供回归锁「cells 常量 == 常见像元比
+ * 下的实际图宽」（空气墙契约：盒宽=图宽）。 */
+export declare function whaleGirlImageBoxColumns(cell: {
+    readonly width: number;
+    readonly height: number;
+}, frameRatio: number): number;
+/** 鲸娘语义表：deepy 的语义/上下文/互动/通知反应表 key 同名直通，仅
+ *  notice（悬停本体）→ smile-hearts、happy（庆祝）→ thumbs-up 两处覆盖。
+ *  回归用它做全语义覆盖检查；运行时 CompanionPanel 把裁决出的
+ *  animationSemantic 交给每个皮肤的 render（WhaleGirlSkin.semanticMap
+ *  即本表），互动/通知反应因此同样能到非 deepy 皮肤。 */
+export declare const WHALE_GIRL_SEMANTIC_ANIMATION: Readonly<Record<string, string>>;
+/** pose → 鲸娘动画键（纯函数，回归直接测）：亲昵互动（爱心 pass，
+ *  CompanionPanel 在点击宠物 / Enter 戳一戳时 arm）优先于心情。 */
+export declare function whaleGirlAnimationKey(mood: CompanionMood, heart: number): string;
+/** 鲸娘动画键裁决（字母格与图像两条路径共用）：semanticMap 映射 >
+ *  爱心 pass > 心情层，与 whaleGirlAnimationKey 的优先级一致。每个候选
+ *  都要过 hasKey（在素材包里、没解码失败过），不过就沿链往下：semantic
+ *  → heart → mood → idle；全部不可用返回 undefined，由调用方退字母格
+ *  或保持上一帧。导出供回归直接测这条链。 */
+export declare function resolveWhaleGirlAnimationKey(pose: CompanionPose, animationSemantic: string | undefined, hasKey: (key: string) => boolean): string | undefined;
+export declare const WhaleGirlSkin: CompanionSkin;
+interface WhaleGirlImageTiming {
+    readonly dur: number;
+    readonly file: string;
+}
+interface WhaleGirlImageAnimation {
+    readonly key: string;
+    readonly frames: readonly WhaleGirlImageTiming[];
+    /** 全部帧 dur 总和（循环周期）。 */
+    readonly totalMs: number;
+}
+interface WhaleGirlImageKit {
+    /** img/ 目录的绝对路径（帧 PNG 解码用）。 */
+    readonly dir: string;
+    readonly byKey: Readonly<Record<string, WhaleGirlImageAnimation>>;
+}
+/** 惰性加载 + 缓存图像 timings；缺失/校验失败返回 undefined（退字母格）。 */
+export declare function loadWhaleGirlImageKit(): WhaleGirlImageKit | undefined;
+/** elapsed 时刻应显示第几帧：dur 累加取模，与 deepy.frameAt 同语义
+ *  （确定性、可单测；回归里与 frameAt 逐 elapsed 比对）。 */
+export declare function whaleGirlImageFrameIndexAt(animation: WhaleGirlImageAnimation, elapsedMs: number): number;
+/** 订阅缓存写入/驱逐（uSES 的 subscribe 面；回归直接用它观测 revision）。 */
+export declare function subscribeDecodedImageCache(listener: () => void): () => void;
+/** 预热键集：面板可见且动画时钟在走时，把常用互动键（idle + poke
+ *  左/右 + smile-hearts）提前异步解码进 LRU，换键时少等一次解码。
+ *  导出供回归检查。 */
+export declare const WHALE_GIRL_PREHEAT_KEYS: readonly string[];
+/** 测试观测点：当前进程已解码了哪些动画（惰性解码断言用）。 */
+export declare function whaleGirlDecodedAnimationKeys(): readonly string[];
+/** 测试接缝：LRU 迭代序（= 最近使用序）。 */
+export declare function decodedImageAnimationOrderForTests(): readonly string[];
+/** 测试接缝：注入假帧，制造 32MiB 驱逐压力（不触发真实解码）。 */
+export declare function injectDecodedAnimationForTests(key: string, frames: readonly TerminalImageSource[]): void;
+/** 测试观测点：解码发起总次数。 */
+export declare function whaleGirlDecodeRequestCountForTests(): number;
+/** 测试接缝：登记解码失败键（模拟坏 PNG，不动真实资产）。 */
+export declare function injectFailedAnimationForTests(key: string): void;
+/** 测试接缝：清图像层缓存（timings kit + 已解码动画 + 失败集合 + 字母开窗渲染）。 */
+export declare function resetWhaleGirlImageCacheForTests(): void;
+/** 鲸娘图像路径的帧缓存 hook：activeKey 为 undefined（面板不可见/无
+ *  动画）时不做任何事；命中缓存同步返回，未命中异步解码完成后返回。
+ *  缓存 revision 是解码 effect 的依赖：键没变但被预热或别的实例挤出
+ *  缓存时，effect 重跑并重新解码。每次 commit 后刷新当前键的 LRU 位置。
+ *  导出供回归在真渲染器下测试。 */
+export declare function useDecodedWhaleGirlFrames(activeKey: string | undefined, kit: WhaleGirlImageKit | undefined): readonly TerminalImageSource[] | undefined;
+/** 保持上一帧的 hook：render 把本次候选图像交进来，没有候选时返回上一
+ *  次已提交的图像。「上一帧」和「是否显示过」只在 commit 后的 layout
+ *  effect 里写，被放弃的 concurrent render 不会改动它们。保持期间返回
+ *  同一个元素引用，逐 tick 重渲染不会重画子树。返回 [要显示的节点,
+ *  是否显示过]；节点为 undefined 表示从未显示过（调用方画字母格）。
+ *  导出供回归在 ConcurrentRoot 下测试。 */
+export declare function useHeldCommittedImage(candidate: React.ReactNode): readonly [committed: React.ReactNode, everCommitted: boolean];
+/** 现有像素鲸鱼：直接消费 nativeWhalePose（与开屏 splash 同一规划器、
+ *  同一帧表、同一 LAYERED_CACHE）。 */
+export declare const WhaleSkin: CompanionSkin;
+/** 按 id 取皮肤；未知 id 回退默认（DeepySkin）。 */
+export declare function resolveCompanionSkin(id: string | undefined): CompanionSkin;
+/** 自定义皮肤注册接缝（用户自定义 / 插件皮肤的进入点；描述符校验
+ *  规则随 Phase 7 的插件皮肤一起落地）。 */
+export declare function registerCompanionSkin(skin: CompanionSkin): void;
+export {};
+//# sourceMappingURL=skins.d.ts.map

package/lib/types/components/sidePanel/companion/skins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skins.d.ts","sourceRoot":"","sources":["../../../../../src/components/sidePanel/companion/skins.tsx"],"names":[],"mappings":"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"}