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

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

@@ -0,0 +1,582 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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 { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { Box, Text, Image, useTerminalImages, useTerminalImageProtocol, useTerminalImageCellSize } from '../../../ui.js';
+import { WhaleArt, renderSpriteRows } from '../../Whale.js';
+import { loadSharp } from '../../../dsh-adapter/sharp.js';
+import { DEEPY_CELLS, DEEPY_MOOD_ANIMATION, DEEPY_SEMANTIC_ANIMATION, frameAt, loadDeepyKit, loadWhaleGirlKit, renderedDeepyAnimation, } from './deepy.js';
+/** deepy 小鲸鱼（默认）：语义/心情 → 动画，elapsed → frameAt 确定性选帧。 */
+export const DeepySkin = {
+    id: 'deepy',
+    title: 'Deepy',
+    cells: DEEPY_CELLS,
+    graphics: 'none',
+    render(input) {
+        const { pose, moodSince, now, animationSemantic } = input;
+        const kit = loadDeepyKit();
+        if (kit === undefined)
+            return WhaleSkin.render({ pose, moodSince, now, width: DEEPY_CELLS.columns, animationSemantic });
+        // animationSemantic 已是 deepy 规范键；无效（皮肤词汇表外）才回 mood 层。
+        const animationKey = animationSemantic !== undefined && kit.byKey[animationSemantic] !== undefined
+            ? animationSemantic
+            : DEEPY_MOOD_ANIMATION[pose.mood] ?? 'idle';
+        const rendered = renderedDeepyAnimation(kit, animationKey);
+        const animation = kit.byKey[animationKey];
+        if (rendered === undefined || animation === undefined)
+            return null;
+        const frameIndex = frameAt(animation, now - moodSince);
+        const rows = rendered[frameIndex] ?? rendered[0] ?? [];
+        return (_jsx(Box, { flexDirection: "column", flexShrink: 0, width: DEEPY_CELLS.columns, children: rows.map((row, index) => (_jsx(Text, { wrap: "truncate-end", children: row }, index))) }));
+    },
+};
+/** 图像轨的盒宽契约（2026-10 拖动空气墙修复）：cells.columns = 8×16 像
+ * 件下图像的实际列宽（31）——面板 clamp/点击半区/§16.6 列宽预算全都吃这
+ * 个常量，盒贴边即图贴边。其他像元比下图宽漂移（宽 = 15 × cellRatio ×
+ * 帧比），钳在本常量内（contain 收行不裁剪），残隙 ≤2 格（常见像元比带
+ * 1.75–2.13 内精确或差 1–2 格；字母轨 42 宽帧串的本体 ~21–25 格也装得下，
+ * 两侧透明衬垫溢出盒外不可见）。字母轨的 8–11 格固有边距需另产裁边素材
+ * 才能治，本轮留档不做。 */
+const WHALE_GIRL_CELLS = Object.freeze({ columns: 31, rows: 15 });
+/** 图像轨单元格盒列数：15 行预算 × 像元比 × 帧宽高比，钳在 cells.columns
+ * （超出时调用方按 contain 收行）。导出供回归锁「cells 常量 == 常见像元比
+ * 下的实际图宽」（空气墙契约：盒宽=图宽）。 */
+export function whaleGirlImageBoxColumns(cell, frameRatio) {
+    const cellRatio = cell.height / cell.width;
+    return Math.max(1, Math.min(WHALE_GIRL_CELLS.columns, Math.round(cellRatio * WHALE_GIRL_CELLS.rows * frameRatio)));
+}
+/** 鲸娘心情表：deepy 表同名直通，只有 celebrate 换成鲸娘独有的
+ *  thumbs-up（happy/庆祝，success 通知反应同源）。 */
+const WHALE_GIRL_MOOD_ANIMATION = {
+    ...DEEPY_MOOD_ANIMATION,
+    celebrate: 'thumbs-up',
+};
+/** 鲸娘语义表：deepy 的语义/上下文/互动/通知反应表 key 同名直通，仅
+ *  notice（悬停本体）→ smile-hearts、happy（庆祝）→ thumbs-up 两处覆盖。
+ *  回归用它做全语义覆盖检查；运行时 CompanionPanel 把裁决出的
+ *  animationSemantic 交给每个皮肤的 render（WhaleGirlSkin.semanticMap
+ *  即本表），互动/通知反应因此同样能到非 deepy 皮肤。 */
+export const WHALE_GIRL_SEMANTIC_ANIMATION = {
+    ...DEEPY_SEMANTIC_ANIMATION,
+    notice: 'smile-hearts',
+    happy: 'thumbs-up',
+};
+/** pose → 鲸娘动画键（纯函数，回归直接测）：亲昵互动（爱心 pass，
+ *  CompanionPanel 在点击宠物 / Enter 戳一戳时 arm）优先于心情。 */
+export function whaleGirlAnimationKey(mood, heart) {
+    if (heart > 0)
+        return 'smile-hearts';
+    return WHALE_GIRL_MOOD_ANIMATION[mood] ?? 'idle';
+}
+/** 鲸娘（用户提供的表情包，assets/whaleGirl/frames.json）：渲染路径照
+ *  DeepySkin（kit → 动画 → frameAt 选帧 → 半块行）。动画键优先级：
+ *  animationSemantic（互动/通知反应层，经 semanticMap 落点）> 爱心 pass
+ *  > 心情层（whaleGirlAnimationKey 原契约不变）；缺 kit / 缺帧回退
+ *  DeepySkin.render（再缺则由它落到 WhaleSkin）。 */
+/** 鲸娘对 deepy 规范键的落点：只声明两处覆盖（悬停碰本体 deepy 会喷水，
+ *  鲸娘换成 smile-hearts；庆祝 happy → 独有 thumbs-up），其余 18 键与
+  deepy 同名直通（鲸娘 kit 键集同源）。semantic 空间的完整覆盖表见
+  WHALE_GIRL_SEMANTIC_ANIMATION（回归用）。 */
+const WHALE_GIRL_KEY_ANIMATION = {
+    'idle-spout': 'smile-hearts',
+    'happy': 'thumbs-up',
+};
+/** 鲸娘动画键裁决（字母格与图像两条路径共用）：semanticMap 映射 >
+ *  爱心 pass > 心情层，与 whaleGirlAnimationKey 的优先级一致。每个候选
+ *  都要过 hasKey（在素材包里、没解码失败过），不过就沿链往下：semantic
+ *  → heart → mood → idle；全部不可用返回 undefined，由调用方退字母格
+ *  或保持上一帧。导出供回归直接测这条链。 */
+export function resolveWhaleGirlAnimationKey(pose, animationSemantic, hasKey) {
+    if (animationSemantic !== undefined) {
+        const semanticKey = WHALE_GIRL_KEY_ANIMATION[animationSemantic] ?? animationSemantic;
+        if (hasKey(semanticKey))
+            return semanticKey;
+    }
+    if (pose.heart > 0 && hasKey('smile-hearts'))
+        return 'smile-hearts';
+    const moodKey = WHALE_GIRL_MOOD_ANIMATION[pose.mood] ?? 'idle';
+    if (hasKey(moodKey))
+        return moodKey;
+    const idleKey = WHALE_GIRL_MOOD_ANIMATION.idle;
+    if (hasKey(idleKey))
+        return idleKey;
+    return undefined;
+}
+/** 字母轨开窗（2026-10 空气墙修复配套）：42 格帧串的全部美术落在
+ * [5,35] 共 31 列（实测 267 帧，两侧是构建 contain 的透明衬垫 '.'）——
+ * 与图像轨 31 列盒同宽。开窗后字母轨也装进 cells.columns，盒贴边即
+ * （最宽姿势的）美术贴边；各姿势自身更窄的边距是美术固有，同 deepy。
+ * 回归锁「全部帧内容 ⊆ [5, 5+31)」防素材更新后悄悄越窗被截。 */
+const WHALE_GIRL_LETTER_WINDOW_START = 5;
+const whaleGirlWindowCache = new Map();
+function renderedWhaleGirlWindowRows(kit, key) {
+    const animation = kit.byKey[key];
+    if (animation === undefined)
+        return undefined;
+    const cacheKey = kit.id + ':window:' + key;
+    let rendered = whaleGirlWindowCache.get(cacheKey);
+    if (rendered === undefined) {
+        rendered = Object.freeze(animation.frames.map(frame => renderSpriteRows(frame.rows.map(row => row.slice(WHALE_GIRL_LETTER_WINDOW_START, WHALE_GIRL_LETTER_WINDOW_START + WHALE_GIRL_CELLS.columns)), kit.palette)));
+        whaleGirlWindowCache.set(cacheKey, rendered);
+    }
+    return rendered;
+}
+/** 鲸娘字母格渲染（31 列开窗半块路径，供两条渲染路径复用）：
+ *  缺 kit / 缺预渲染 → DeepySkin.render（再缺由它落到 WhaleSkin）。 */
+function renderWhaleGirlLetterGrid(input) {
+    const { pose, moodSince, now, animationSemantic } = input;
+    const kit = loadWhaleGirlKit();
+    if (kit === undefined)
+        return DeepySkin.render({ ...input, width: WHALE_GIRL_CELLS.columns });
+    // 字母轨只要求 kit 里有这个动画；一个都没有时退 DeepySkin，与缺帧
+    // 回退同一出口。
+    const animationKey = resolveWhaleGirlAnimationKey(pose, animationSemantic, key => kit.byKey[key] !== undefined);
+    if (animationKey === undefined)
+        return DeepySkin.render({ ...input, width: WHALE_GIRL_CELLS.columns });
+    const rendered = renderedWhaleGirlWindowRows(kit, animationKey);
+    const animation = kit.byKey[animationKey];
+    if (rendered === undefined || animation === undefined) {
+        return DeepySkin.render({ ...input, width: WHALE_GIRL_CELLS.columns });
+    }
+    const frameIndex = frameAt(animation, now - moodSince);
+    const rows = rendered[frameIndex] ?? rendered[0] ?? [];
+    return (_jsx(Box, { flexDirection: "column", flexShrink: 0, width: WHALE_GIRL_CELLS.columns, children: rows.map((row, index) => (_jsx(Text, { wrap: "truncate-end", children: row }, index))) }));
+}
+export const WhaleGirlSkin = {
+    id: 'whaleGirl',
+    title: '鲸娘',
+    cells: WHALE_GIRL_CELLS,
+    /** optional：有终端图像协议（kitty/sixel）时用原生像素帧，无协议退
+     *  字母格（renderWhaleGirlLetterGrid，老路径原样保留）。 */
+    graphics: 'optional',
+    semanticMap: WHALE_GIRL_KEY_ANIMATION,
+    render(input) {
+        // kit 缺失的回退必须发生在 render() 本体（同步），老回归契约如此。
+        if (loadWhaleGirlKit() === undefined)
+            return DeepySkin.render({ ...input, width: WHALE_GIRL_CELLS.columns });
+        // render 是普通函数，hooks 落在真正的组件里（无协议环境 mount 后
+        // 立即退回字母格，行为与旧版逐字节一致）。
+        return _jsx(WhaleGirlImageSkin, { ...input });
+    },
+};
+/** 与 deepy.ts 同一套层级教训：源码层 4 层 + 编译层（lib/types）5 层。 */
+const WHALE_GIRL_IMG_DIR_CANDIDATES = [
+    '../../../../assets/whaleGirl/img',
+    '../../../../../assets/whaleGirl/img',
+];
+let whaleGirlImageKitCache;
+/** 校验即拒绝（同 loadSpriteKit 契约）：timings.json 形状不对 → 整份
+ *  视为不可用，图像路径整体退字母格，不渲染半成品。 */
+function parseWhaleGirlImageKit(raw, dir) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const byKey = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!Array.isArray(value) || value.length === 0)
+            return undefined;
+        const frames = [];
+        for (const entry of value) {
+            if (typeof entry?.dur !== 'number' || !(entry.dur > 0))
+                return undefined;
+            if (typeof entry.file !== 'string' || !/^[0-9]{2}\.png$/.test(entry.file))
+                return undefined;
+            frames.push({ dur: entry.dur, file: entry.file });
+        }
+        byKey[key] = { key, frames, totalMs: frames.reduce((sum, frame) => sum + frame.dur, 0) };
+    }
+    return { dir, byKey };
+}
+/** 惰性加载 + 缓存图像 timings；缺失/校验失败返回 undefined（退字母格）。 */
+export function loadWhaleGirlImageKit() {
+    if (whaleGirlImageKitCache !== undefined)
+        return whaleGirlImageKitCache ?? undefined;
+    for (const candidate of WHALE_GIRL_IMG_DIR_CANDIDATES) {
+        try {
+            const dir = fileURLToPath(new URL(candidate, import.meta.url));
+            if (!existsSync(join(dir, 'timings.json')))
+                continue;
+            const kit = parseWhaleGirlImageKit(JSON.parse(readFileSync(join(dir, 'timings.json'), 'utf8')), dir);
+            if (kit !== undefined) {
+                whaleGirlImageKitCache = kit;
+                return kit;
+            }
+        }
+        catch {
+            // 下一个候选路径
+        }
+    }
+    whaleGirlImageKitCache = null;
+    return undefined;
+}
+/** elapsed 时刻应显示第几帧：dur 累加取模，与 deepy.frameAt 同语义
+ *  （确定性、可单测；回归里与 frameAt 逐 elapsed 比对）。 */
+export function whaleGirlImageFrameIndexAt(animation, elapsedMs) {
+    if (animation.frames.length === 0 || animation.totalMs <= 0)
+        return 0;
+    let remainder = Math.max(0, elapsedMs) % animation.totalMs;
+    for (let index = 0; index < animation.frames.length; index += 1) {
+        const frame = animation.frames[index];
+        if (remainder < frame.dur)
+            return index;
+        remainder -= frame.dur;
+    }
+    return animation.frames.length - 1;
+}
+/** 已解码动画的 LRU（Map 迭代序 = 最近使用序）；失败集合防止坏动画
+ *  每帧重试。字节上限防 267 帧全量常驻（全解约 92.6MB RGBA）。
+ *  提交后的使用经 touchDecodedAnimation 刷新迭代序；写入和驱逐会发布
+ *  revision，消费者订阅后能发现自己的键被挤出并重新解码。 */
+const decodedImageAnimations = new Map();
+const failedImageAnimations = new Set();
+let decodedImageBytes = 0;
+const DECODED_IMAGE_BYTES_CAP = 32 * 1024 * 1024;
+/** 缓存写入/驱逐的版本号。快照是原始 number，Object.is 比较稳定。
+ *  touch 只改迭代序、不发布：它在 commit 后运行，发布会让每次 commit
+ *  再触发一次渲染。 */
+let decodedImageCacheRevision = 0;
+const decodedImageCacheListeners = new Set();
+function publishDecodedImageCacheChange() {
+    decodedImageCacheRevision += 1;
+    for (const listener of [...decodedImageCacheListeners])
+        listener();
+}
+/** 订阅缓存写入/驱逐（uSES 的 subscribe 面；回归直接用它观测 revision）。 */
+export function subscribeDecodedImageCache(listener) {
+    decodedImageCacheListeners.add(listener);
+    return () => { decodedImageCacheListeners.delete(listener); };
+}
+/** 把命中的键移到最近使用位。只改迭代序，不动键集和字节数，所以不
+ *  发布 revision。只在 commit 后的 effect 里调用；键不在缓存时 no-op。 */
+function touchDecodedAnimation(key) {
+    const frames = decodedImageAnimations.get(key);
+    if (frames === undefined)
+        return;
+    decodedImageAnimations.delete(key);
+    decodedImageAnimations.set(key, frames);
+}
+/** 解码一个动画的全部帧（顺序、确定性）；任一帧失败 → 整个动画 undefined。 */
+async function decodeWhaleGirlAnimation(dir, animation) {
+    try {
+        const sharp = await loadSharp();
+        if (sharp === undefined)
+            return undefined;
+        const frames = [];
+        for (const frame of animation.frames) {
+            const decoded = await sharp(readFileSync(join(dir, animation.key, frame.file)), { failOn: 'error' })
+                .ensureAlpha()
+                .raw()
+                .toBuffer({ resolveWithObject: true });
+            if (decoded.info.channels !== 4
+                || decoded.data.byteLength !== decoded.info.width * decoded.info.height * 4)
+                return undefined;
+            frames.push({
+                data: new Uint8Array(decoded.data.buffer, decoded.data.byteOffset, decoded.data.byteLength),
+                width: decoded.info.width,
+                height: decoded.info.height,
+            });
+        }
+        return frames;
+    }
+    catch {
+        return undefined;
+    }
+}
+function rememberDecodedAnimation(key, frames) {
+    const previous = decodedImageAnimations.get(key);
+    if (previous !== undefined) {
+        decodedImageAnimations.delete(key);
+        decodedImageBytes -= previous.reduce((sum, frame) => sum + frame.data.byteLength, 0);
+    }
+    decodedImageAnimations.set(key, frames);
+    decodedImageBytes += frames.reduce((sum, frame) => sum + frame.data.byteLength, 0);
+    while (decodedImageBytes > DECODED_IMAGE_BYTES_CAP && decodedImageAnimations.size > 1) {
+        const oldest = decodedImageAnimations.keys().next().value;
+        if (oldest === undefined)
+            break;
+        const evicted = decodedImageAnimations.get(oldest);
+        decodedImageAnimations.delete(oldest);
+        decodedImageBytes -= evicted?.reduce((sum, frame) => sum + frame.data.byteLength, 0) ?? 0;
+    }
+    // 插入、替换、驱逐都改变了消费者可见的内容：发布 revision，让键被
+    // 挤出的消费者重跑解码 effect。
+    publishDecodedImageCacheChange();
+}
+/** 预热键集：面板可见且动画时钟在走时，把常用互动键（idle + poke
+ *  左/右 + smile-hearts）提前异步解码进 LRU，换键时少等一次解码。
+ *  导出供回归检查。 */
+export const WHALE_GIRL_PREHEAT_KEYS = [
+    WHALE_GIRL_MOOD_ANIMATION.idle,
+    'poke-left',
+    'poke-right',
+    'smile-hearts',
+];
+/** 在途解码登记（同键去重：活跃解码路径与预热共用一个 Promise）。 */
+const inflightImageDecodes = new Map();
+/** 解码发起次数，只在新建在途 Promise 时递增。回归用它检查失败键不
+ *  按 tick 重试、同键并发只解一次、驱逐后的恢复有界。 */
+let whaleGirlDecodeRequestCount = 0;
+/** 测试重置时递增：重置前发起、重置后才完成的解码不得写进新缓存。 */
+let decodeGeneration = 0;
+/** 解码一个动画并入库：成功进 LRU，失败进失败集（之后的裁决会跳过
+ *  这个键）；同键并发请求共用在途 Promise。永不 reject，也不直接触发
+ *  React 更新。 */
+function requestWhaleGirlAnimationFrames(kit, key) {
+    const inflight = inflightImageDecodes.get(key);
+    if (inflight !== undefined)
+        return inflight;
+    whaleGirlDecodeRequestCount += 1;
+    const generation = decodeGeneration;
+    const pending = decodeWhaleGirlAnimation(kit.dir, kit.byKey[key])
+        .then(frames => {
+        if (generation !== decodeGeneration)
+            return frames;
+        inflightImageDecodes.delete(key);
+        if (frames === undefined)
+            failedImageAnimations.add(key);
+        else
+            rememberDecodedAnimation(key, frames);
+        return frames;
+    })
+        .catch(() => {
+        if (generation !== decodeGeneration)
+            return undefined;
+        inflightImageDecodes.delete(key);
+        failedImageAnimations.add(key);
+        return undefined;
+    });
+    inflightImageDecodes.set(key, pending);
+    return pending;
+}
+/** 预热一个键（幂等：缺键/已缓存/已失败跳过）；失败静默——与按需解码
+ *  同语义地进失败集，不闪不响。 */
+function preheatWhaleGirlAnimation(kit, key) {
+    if (kit.byKey[key] === undefined)
+        return;
+    if (decodedImageAnimations.has(key) || failedImageAnimations.has(key))
+        return;
+    void requestWhaleGirlAnimationFrames(kit, key);
+}
+/** 测试观测点：当前进程已解码了哪些动画（惰性解码断言用）。 */
+export function whaleGirlDecodedAnimationKeys() {
+    return [...decodedImageAnimations.keys(), ...failedImageAnimations];
+}
+/** 测试接缝：LRU 迭代序（= 最近使用序）。 */
+export function decodedImageAnimationOrderForTests() {
+    return [...decodedImageAnimations.keys()];
+}
+/** 测试接缝：注入假帧，制造 32MiB 驱逐压力（不触发真实解码）。 */
+export function injectDecodedAnimationForTests(key, frames) {
+    rememberDecodedAnimation(key, frames);
+}
+/** 测试观测点：解码发起总次数。 */
+export function whaleGirlDecodeRequestCountForTests() {
+    return whaleGirlDecodeRequestCount;
+}
+/** 测试接缝：登记解码失败键（模拟坏 PNG，不动真实资产）。 */
+export function injectFailedAnimationForTests(key) {
+    failedImageAnimations.add(key);
+}
+/** 测试接缝：清图像层缓存（timings kit + 已解码动画 + 失败集合 + 字母开窗渲染）。 */
+export function resetWhaleGirlImageCacheForTests() {
+    whaleGirlImageKitCache = undefined;
+    decodedImageAnimations.clear();
+    failedImageAnimations.clear();
+    decodedImageBytes = 0;
+    inflightImageDecodes.clear();
+    decodeGeneration += 1;
+    whaleGirlWindowCache.clear();
+    whaleGirlDecodeRequestCount = 0;
+    publishDecodedImageCacheChange();
+}
+/** 面板可见性门（visible=false 零工作契约）：PanelHost 对非 active 的
+ *  enabled 面板包 display:none 的 Box——沿 DOM 祖先链查它。初始 false，
+ *  布局期更新（不触发额外渲染循环），解码 effect 只在证明可见后开跑。 */
+function useBoxDisplayed() {
+    const elementRef = React.useRef(null);
+    const displayedRef = React.useRef(false);
+    const [displayed, setDisplayed] = React.useState(false);
+    const setElement = React.useCallback((element) => { elementRef.current = element; }, []);
+    React.useLayoutEffect(() => {
+        let hidden = false;
+        let node = elementRef.current?.parentNode;
+        while (node !== undefined && !hidden) {
+            if (node.style?.display === 'none')
+                hidden = true;
+            node = node.parentNode;
+        }
+        // 只在值真的变化时 setState。这个无 deps 的 layout effect 每次
+        // commit 都跑；即使更新器返回原值，enqueue 本身也会计入
+        // react-reconciler 的 nestedUpdateCount，遇上连续提交（如 /context
+        // 滚动）会攒到 50 并抛 #185。用 ref 记住上次的值，稳态不入队。
+        const next = !hidden;
+        if (displayedRef.current !== next) {
+            displayedRef.current = next;
+            setDisplayed(next);
+        }
+    });
+    return [setElement, displayed];
+}
+/** 鲸娘图像路径的帧缓存 hook：activeKey 为 undefined（面板不可见/无
+ *  动画）时不做任何事；命中缓存同步返回，未命中异步解码完成后返回。
+ *  缓存 revision 是解码 effect 的依赖：键没变但被预热或别的实例挤出
+ *  缓存时，effect 重跑并重新解码。每次 commit 后刷新当前键的 LRU 位置。
+ *  导出供回归在真渲染器下测试。 */
+export function useDecodedWhaleGirlFrames(activeKey, kit) {
+    const [settled, setSettled] = React.useState(undefined);
+    // 只在缓存写入/驱逐时变化（解码完成或测试注入），稳态不触发渲染。
+    const cacheRevision = React.useSyncExternalStore(subscribeDecodedImageCache, () => decodedImageCacheRevision);
+    React.useEffect(() => {
+        if (activeKey === undefined || kit === undefined)
+            return;
+        if (!decodedImageAnimations.has(activeKey) && !failedImageAnimations.has(activeKey)) {
+            let live = true;
+            // 与预热共用在途解码；组件已换键或卸载时不 setSettled（预热先完成
+            // 的话，revision 通知触发的渲染会直接命中缓存）。
+            void requestWhaleGirlAnimationFrames(kit, activeKey).then(frames => {
+                if (live && frames !== undefined)
+                    setSettled({ key: activeKey, frames });
+            });
+            return () => { live = false; };
+        }
+        return;
+    }, [activeKey, kit, cacheRevision]);
+    // 每次 commit 刷新当前键的 LRU 位置；键不在缓存或为 undefined 时 no-op。
+    React.useLayoutEffect(() => {
+        if (activeKey !== undefined)
+            touchDecodedAnimation(activeKey);
+    });
+    const cached = activeKey !== undefined ? decodedImageAnimations.get(activeKey) : undefined;
+    if (cached !== undefined)
+        return cached;
+    return settled !== undefined && settled.key === activeKey ? settled.frames : undefined;
+}
+/** 协议裁决层：render() 只产出本组件，hooks 全部在这里落地。 */
+function WhaleGirlImageSkin(input) {
+    // 请求能力探测（无协议终端 probe 一次即回落，不再打扰）。
+    useTerminalImages(true);
+    const protocol = useTerminalImageProtocol();
+    if (protocol !== 'kitty' && protocol !== 'sixel')
+        return renderWhaleGirlLetterGrid(input);
+    return _jsx(WhaleGirlRasterSkin, { ...input });
+}
+/** 保持上一帧的 hook：render 把本次候选图像交进来，没有候选时返回上一
+ *  次已提交的图像。「上一帧」和「是否显示过」只在 commit 后的 layout
+ *  effect 里写，被放弃的 concurrent render 不会改动它们。保持期间返回
+ *  同一个元素引用，逐 tick 重渲染不会重画子树。返回 [要显示的节点,
+ *  是否显示过]；节点为 undefined 表示从未显示过（调用方画字母格）。
+ *  导出供回归在 ConcurrentRoot 下测试。 */
+export function useHeldCommittedImage(candidate) {
+    const everCommittedRef = React.useRef(false);
+    const heldCommittedRef = React.useRef(undefined);
+    React.useLayoutEffect(() => {
+        if (candidate === undefined)
+            return;
+        heldCommittedRef.current = candidate;
+        everCommittedRef.current = true;
+    });
+    if (candidate !== undefined)
+        return [candidate, everCommittedRef.current];
+    if (!everCommittedRef.current)
+        return [undefined, false];
+    return [heldCommittedRef.current, true];
+}
+/** 图像渲染层：timings 选帧 + 惰性解码 + 单元格盒（15 行预算、宽按
+ *  帧比例钳 31 列）。解码期间保持上一帧；字母格只在冷启动时出现；常用
+ *  互动键在可见后预热。保持和预热都只看已提交的 render。 */
+function WhaleGirlRasterSkin(input) {
+    const { pose, moodSince, now, animationSemantic } = input;
+    const cellSize = useTerminalImageCellSize();
+    const imageKit = loadWhaleGirlImageKit();
+    const [boxRef, displayed] = useBoxDisplayed();
+    // 解码失败过的键不再被选中（退到心情层的键），失败的互动不会让画面
+    // 一直停在上一帧。
+    const animationKey = imageKit !== undefined
+        ? resolveWhaleGirlAnimationKey(pose, animationSemantic, key => imageKit.byKey[key] !== undefined && !failedImageAnimations.has(key))
+        : undefined;
+    // visible=false 零工作：display:none 祖先链未排除前不解码、不订阅时钟。
+    const frames = useDecodedWhaleGirlFrames(displayed ? animationKey : undefined, imageKit);
+    const animation = animationKey !== undefined ? imageKit?.byKey[animationKey] : undefined;
+    // 预热：可见且动画时钟在走时，把常用互动键异步解码进 LRU（不挡首帧，
+    // 失败静默进失败集）。now 只在 commit 后的 effect 里与上次比较，被
+    // 放弃的 render 带来的 now 不算。时钟一直不动就是 active=false 的定格
+    // 态（SplashMascot 停在 idle 第 0 帧），不预热。
+    const lastNowRef = React.useRef(now);
+    React.useEffect(() => {
+        if (now === lastNowRef.current)
+            return;
+        lastNowRef.current = now;
+        if (!displayed || imageKit === undefined)
+            return;
+        for (const key of WHALE_GIRL_PREHEAT_KEYS)
+            preheatWhaleGirlAnimation(imageKit, key);
+    }, [now, displayed, imageKit]);
+    // 单元格盒：15 行预算 + 帧自身宽高比（source.width/height，与档位
+    // 无关）+ 真实像元；宽钳 31 列。8×16 像元下 288px 档
+    // （301×288）≈ 31 列，渲染层 fit 只降采样，显示恒 1:1 或更密。
+    // 外层盒恒定 31×15：ref 挂在它上面（可见性门要求任何分支都在树里），
+    // 字母格→图像切换时面板几何零跳动。
+    let image;
+    if (imageKit !== undefined && cellSize !== undefined && frames !== undefined && animation !== undefined) {
+        const frameIndex = whaleGirlImageFrameIndexAt(animation, now - moodSince);
+        const source = frames[frameIndex] ?? frames[0];
+        if (source !== undefined) {
+            const cellRatio = cellSize.height / cellSize.width;
+            const frameRatio = source.width / source.height;
+            // 盒宽=图宽（钳在 cells.columns 内；超宽像元比下 contain 收行不裁剪）。
+            const rawColumns = Math.max(1, Math.round(cellRatio * WHALE_GIRL_CELLS.rows * frameRatio));
+            const columns = whaleGirlImageBoxColumns(cellSize, frameRatio);
+            const rows = rawColumns > columns
+                ? Math.max(1, Math.round(columns / (cellRatio * frameRatio)))
+                : WHALE_GIRL_CELLS.rows;
+            image = (_jsx(Image, { transparent: true, source: source, width: columns, height: rows, alt: "", presentation: "transcript", children: _jsx(Text, { children: Array.from({ length: rows }, () => ' '.repeat(columns)).join('\n') }) }));
+        }
+    }
+    // 本次候选或上一帧；都没有（冷启动）时画字母格。切到还没解码的键时
+    // 保持上一帧，不闪回字母格。
+    const [visibleImage] = useHeldCommittedImage(image);
+    return (_jsx(Box, { ref: boxRef, flexDirection: "column", flexShrink: 0, alignItems: "center", justifyContent: "center", width: WHALE_GIRL_CELLS.columns, height: WHALE_GIRL_CELLS.rows, children: visibleImage !== undefined ? visibleImage : renderWhaleGirlLetterGrid(input) }));
+}
+const WHALE_CELLS = Object.freeze({ columns: 40, rows: 13 });
+/** 现有像素鲸鱼：直接消费 nativeWhalePose（与开屏 splash 同一规划器、
+ *  同一帧表、同一 LAYERED_CACHE）。 */
+export const WhaleSkin = {
+    id: 'whale',
+    title: 'Whale',
+    cells: WHALE_CELLS,
+    graphics: 'none',
+    render({ pose }) {
+        return _jsx(WhaleArt, { pose: pose.nativeWhalePose, width: WHALE_CELLS.columns });
+    },
+};
+const skins = new Map([
+    [DeepySkin.id, DeepySkin],
+    [WhaleGirlSkin.id, WhaleGirlSkin],
+    [WhaleSkin.id, WhaleSkin],
+]);
+/** 按 id 取皮肤；未知 id 回退默认（DeepySkin）。 */
+export function resolveCompanionSkin(id) {
+    if (id !== undefined) {
+        const skin = skins.get(id);
+        if (skin !== undefined)
+            return skin;
+    }
+    return DeepySkin;
+}
+/** 自定义皮肤注册接缝（用户自定义 / 插件皮肤的进入点；描述符校验
+ *  规则随 Phase 7 的插件皮肤一起落地）。 */
+export function registerCompanionSkin(skin) {
+    skins.set(skin.id, skin);
+}

package/lib/types/components/sidePanel/dimensions.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Side-panel geometry: the single source of truth for 'can we split, and
+ * if so how wide is each column'. Pure functions only — the verify scripts
+ * assert these tables directly at boundary widths.
+ *
+ * Anchors (side-panel design doc §4.2):
+ * - CHAT_MIN_COLUMNS keeps the 2-col transcript gutter
+ *   (RAIL_MIN_TERMINAL_WIDTH = 60 in ink/timeline-rail.ts) plus tool-card
+ *   indentation readable;
+ * - PANEL_MIN_COLUMNS is the narrowest width at which the Jobs panel
+ *   variant stays legible;
+ * - everything is derived from those minimums — never a hard-coded
+ *   'columns < 100' style threshold.
+ *
+ * Widths are ALWAYS numeric (Math.floor): ink resolves % against the
+ * padding-inclusive parent box, so a percentage column would lie (see
+ * PageMargin.tsx's content-box comment).
+ */
+export declare const CHAT_MIN_COLUMNS = 64;
+export declare const PANEL_MIN_COLUMNS = 28;
+export declare const DIVIDER_COLUMNS = 1;
+/** Chat fraction of the content width when the user has not resized. */
+export declare const DEFAULT_RATIO = 0.68;
+/** What zoom ASKS for (chat fraction); the chat column never goes below
+ *  CHAT_MIN_COLUMNS, so the achieved ratio is usually larger. */
+export declare const ZOOM_TARGET_RATIO = 0.2;
+/** Keyboard resize step (columns) for the panel-focused +/- bindings. */
+export declare const RESIZE_STEP_COLUMNS = 4;
+/** Smallest content width at which a split keeps both sides usable. */
+export declare function canSplit(columns: number): boolean;
+/** Feasible chat-fraction range for a content width (both ends inclusive). */
+export declare function ratioRange(columns: number): {
+    readonly min: number;
+    readonly max: number;
+};
+/** Clamp a stored ratio into the feasible range for this width. */
+export declare function clampRatio(columns: number, ratio: number): number;
+export interface SidePanelSplit {
+    readonly chat: number;
+    readonly panel: number;
+}
+/** Split geometry for a content width and chat fraction. */
+export declare function resolveSplit(columns: number, ratio: number): SidePanelSplit;
+/** Zoom geometry: the panel takes over; chat keeps at least CHAT_MIN_COLUMNS. */
+export declare function resolveZoom(columns: number): SidePanelSplit;
+export interface SidePanelGeometryInput {
+    readonly columns: number;
+    readonly open: boolean;
+    readonly zoom: boolean;
+    readonly ratio: number;
+}
+/**
+ * Resolve the effective layout. null means 'no split' (chat takes the
+ * full content width); callers render exactly as today in that case.
+ */
+export declare function resolveSidePanelGeometry(input: SidePanelGeometryInput): SidePanelSplit | null;
+/** Keyboard resize: shift the chat fraction by deltaColumns worth of
+ *  width, clamped into the feasible range for this terminal. */
+export declare function nudgeRatio(columns: number, ratio: number, deltaColumns: number): number;
+//# sourceMappingURL=dimensions.d.ts.map

package/lib/types/components/sidePanel/dimensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dimensions.d.ts","sourceRoot":"","sources":["../../../../src/components/sidePanel/dimensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAClC,eAAO,MAAM,iBAAiB,KAAK,CAAA;AACnC,eAAO,MAAM,eAAe,IAAI,CAAA;AAEhC,wEAAwE;AACxE,eAAO,MAAM,aAAa,OAAO,CAAA;AAEjC;iEACiE;AACjE,eAAO,MAAM,iBAAiB,MAAO,CAAA;AAErC,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEjD;AAMD,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAM1F;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjE;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAO3E;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAE3D;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,sBAAsB,GAC5B,cAAc,GAAG,IAAI,CAIvB;AAED;gEACgE;AAChE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAGvF"}