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

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

@@ -0,0 +1,408 @@
+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 原契约不变）；落点在
+ *  「本路径的素材包」里不存在时退心情层，不报错。 */
+function resolveWhaleGirlAnimationKey(pose, animationSemantic, hasKey) {
+    const semanticKey = animationSemantic !== undefined
+        ? WHALE_GIRL_KEY_ANIMATION[animationSemantic] ?? animationSemantic
+        : undefined;
+    if (semanticKey !== undefined && hasKey(semanticKey))
+        return semanticKey;
+    return whaleGirlAnimationKey(pose.mood, pose.heart);
+}
+/** 字母轨开窗（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 });
+    const animationKey = resolveWhaleGirlAnimationKey(pose, animationSemantic, key => kit.byKey[key] !== undefined);
+    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 帧全量常驻（全解约 60MB RGBA）。 */
+const decodedImageAnimations = new Map();
+const failedImageAnimations = new Set();
+let decodedImageBytes = 0;
+const DECODED_IMAGE_BYTES_CAP = 32 * 1024 * 1024;
+/** 解码一个动画的全部帧（顺序、确定性）；任一帧失败 → 整个动画 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;
+    }
+}
+/** 测试观测点：当前进程已解码了哪些动画（惰性解码断言用）。 */
+export function whaleGirlDecodedAnimationKeys() {
+    return [...decodedImageAnimations.keys(), ...failedImageAnimations];
+}
+/** 测试接缝：清图像层缓存（timings kit + 已解码动画 + 失败集合 + 字母开窗渲染）。 */
+export function resetWhaleGirlImageCacheForTests() {
+    whaleGirlImageKitCache = undefined;
+    decodedImageAnimations.clear();
+    failedImageAnimations.clear();
+    decodedImageBytes = 0;
+    whaleGirlWindowCache.clear();
+}
+/** 面板可见性门（visible=false 零工作契约）：PanelHost 对非 active 的
+ *  enabled 面板包 display:none 的 Box——沿 DOM 祖先链查它。初始 false，
+ *  布局期更新（不触发额外渲染循环），解码 effect 只在证明可见后开跑。 */
+function useBoxDisplayed() {
+    const elementRef = React.useRef(null);
+    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;
+        }
+        setDisplayed(previous => (previous === !hidden ? previous : !hidden));
+    });
+    return [setElement, displayed];
+}
+/** 鲸娘图像路径的帧缓存 hook：activeKey 为 undefined（面板不可见/无
+ *  动画）时不做任何事；命中缓存同步返回，未命中异步解码完成后返回。 */
+function useDecodedWhaleGirlFrames(activeKey, kit) {
+    const [settled, setSettled] = React.useState(undefined);
+    React.useEffect(() => {
+        if (activeKey === undefined || kit === undefined)
+            return;
+        if (!decodedImageAnimations.has(activeKey) && !failedImageAnimations.has(activeKey)) {
+            let live = true;
+            const animation = kit.byKey[activeKey];
+            void decodeWhaleGirlAnimation(kit.dir, animation).then(frames => {
+                if (frames === undefined)
+                    failedImageAnimations.add(activeKey);
+                else {
+                    rememberDecodedAnimation(activeKey, frames);
+                    if (live)
+                        setSettled({ key: activeKey, frames });
+                }
+            });
+            return () => { live = false; };
+        }
+        return;
+    }, [activeKey, kit]);
+    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 });
+}
+/** 图像渲染层：timings 选帧 + 惰性解码 + 单元格盒（15 行预算、宽按
+ *  帧比例钳 42 列）。解码完成前渲染字母格（同一语义同一帧）兜底。 */
+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)
+        : undefined;
+    // visible=false 零工作：display:none 祖先链未排除前不解码、不订阅时钟。
+    const frames = useDecodedWhaleGirlFrames(displayed ? animationKey : undefined, imageKit);
+    const animation = animationKey !== undefined ? imageKit?.byKey[animationKey] : undefined;
+    // 单元格盒：15 行预算 + 帧自身宽高比（source.width/height，与档位
+    // 无关）+ 真实像元；宽钳 42 列（§16.6）。8×16 像元下 288px 档
+    // （301×288）≈ 31 列，渲染层 fit 只降采样，显示恒 1:1 或更密。
+    // 外层盒恒定 42×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') }) }));
+        }
+    }
+    return (_jsx(Box, { ref: boxRef, flexDirection: "column", flexShrink: 0, alignItems: "center", justifyContent: "center", width: WHALE_GIRL_CELLS.columns, height: WHALE_GIRL_CELLS.rows, children: image ?? 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"}

package/lib/types/components/sidePanel/dimensions.js

@@ -0,0 +1,75 @@
+/**
+ * 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 const CHAT_MIN_COLUMNS = 64;
+export const PANEL_MIN_COLUMNS = 28;
+export const DIVIDER_COLUMNS = 1;
+/** Chat fraction of the content width when the user has not resized. */
+export 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 const ZOOM_TARGET_RATIO = 0.20;
+/** Keyboard resize step (columns) for the panel-focused +/- bindings. */
+export const RESIZE_STEP_COLUMNS = 4;
+/** Smallest content width at which a split keeps both sides usable. */
+export function canSplit(columns) {
+    return columns >= CHAT_MIN_COLUMNS + PANEL_MIN_COLUMNS + DIVIDER_COLUMNS;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/** Feasible chat-fraction range for a content width (both ends inclusive). */
+export function ratioRange(columns) {
+    if (columns <= 0)
+        return { min: 0, max: 1 };
+    return {
+        min: Math.min(1, CHAT_MIN_COLUMNS / columns),
+        max: Math.max(0, (columns - PANEL_MIN_COLUMNS - DIVIDER_COLUMNS) / columns),
+    };
+}
+/** Clamp a stored ratio into the feasible range for this width. */
+export function clampRatio(columns, ratio) {
+    const range = ratioRange(columns);
+    return clamp(ratio, Math.min(range.min, range.max), range.max);
+}
+/** Split geometry for a content width and chat fraction. */
+export function resolveSplit(columns, ratio) {
+    const chat = clamp(Math.floor(columns * ratio), CHAT_MIN_COLUMNS, columns - PANEL_MIN_COLUMNS - DIVIDER_COLUMNS);
+    return { chat, panel: columns - chat - DIVIDER_COLUMNS };
+}
+/** Zoom geometry: the panel takes over; chat keeps at least CHAT_MIN_COLUMNS. */
+export function resolveZoom(columns) {
+    return resolveSplit(columns, ZOOM_TARGET_RATIO);
+}
+/**
+ * Resolve the effective layout. null means 'no split' (chat takes the
+ * full content width); callers render exactly as today in that case.
+ */
+export function resolveSidePanelGeometry(input) {
+    const { columns, open, zoom, ratio } = input;
+    if (!open || !canSplit(columns))
+        return null;
+    return zoom ? resolveZoom(columns) : resolveSplit(columns, ratio);
+}
+/** Keyboard resize: shift the chat fraction by deltaColumns worth of
+ *  width, clamped into the feasible range for this terminal. */
+export function nudgeRatio(columns, ratio, deltaColumns) {
+    if (columns <= 0)
+        return ratio;
+    return clampRatio(columns, ratio + deltaColumns / columns);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * jobsFocusStore：Chat → JobsPanelAdapter 的聚焦请求通道（任务卡片点击
+ * 打开面板时要聚焦到对应任务）。刻意做成 module-level 三行 store，而不是
+ * 塞进 PanelStore（那是 badge/注册表的家，不背业务状态）或
+ * SidePanelRuntimeContext（useSidePanel 不该知道 jobs 的业务）。
+ *
+ * 写：Chat 在 openPanel('jobs') 前调 request(id)；读：Adapter 经
+ * useSyncExternalStore 拿 { id, nonce }，nonce 保证同一 id 的重复请求
+ * （再次点击同一张卡）也能重新触发聚焦。
+ */
+export interface JobsFocusRequest {
+    readonly id: string | null;
+    readonly nonce: number;
+}
+export declare const jobsFocusStore: {
+    subscribe(listener: () => void): () => void;
+    get(): JobsFocusRequest;
+    /** 请求聚焦某个任务（id=null 只推进 nonce，不触发聚焦）。 */
+    request(id: string | null): void;
+};
+//# sourceMappingURL=jobsFocusStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jobsFocusStore.d.ts","sourceRoot":"","sources":["../../../../src/components/sidePanel/jobsFocusStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACzB;AASD,eAAO,MAAM,cAAc;wBACH,MAAM,IAAI,GAAG,MAAM,IAAI;WAIpC,gBAAgB;IAGvB,yCAAyC;gBAC7B,MAAM,GAAG,IAAI,GAAG,IAAI;CAInC,CAAA"}

package/lib/types/components/sidePanel/jobsFocusStore.js

@@ -0,0 +1,30 @@
+/**
+ * jobsFocusStore：Chat → JobsPanelAdapter 的聚焦请求通道（任务卡片点击
+ * 打开面板时要聚焦到对应任务）。刻意做成 module-level 三行 store，而不是
+ * 塞进 PanelStore（那是 badge/注册表的家，不背业务状态）或
+ * SidePanelRuntimeContext（useSidePanel 不该知道 jobs 的业务）。
+ *
+ * 写：Chat 在 openPanel('jobs') 前调 request(id)；读：Adapter 经
+ * useSyncExternalStore 拿 { id, nonce }，nonce 保证同一 id 的重复请求
+ * （再次点击同一张卡）也能重新触发聚焦。
+ */
+let snapshot = Object.freeze({ id: null, nonce: 0 });
+const listeners = new Set();
+function emit() {
+    for (const listener of [...listeners])
+        listener();
+}
+export const jobsFocusStore = {
+    subscribe(listener) {
+        listeners.add(listener);
+        return () => { listeners.delete(listener); };
+    },
+    get() {
+        return snapshot;
+    },
+    /** 请求聚焦某个任务（id=null 只推进 nonce，不触发聚焦）。 */
+    request(id) {
+        snapshot = Object.freeze({ id, nonce: snapshot.nonce + 1 });
+        emit();
+    },
+};

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

@@ -0,0 +1,44 @@
+/**
+ * panelBridge：ctx.tuiPanels 服务（dsh-adapter，Cordis 侧）与 useSidePanel
+ * （Chat 侧控制器）之间的小型 module-level 通道（设计文档 §18.2）。
+ *
+ * 照 jobsFocusStore 的形状刻意做成两个三行 store，而不是塞进 PanelStore
+ * （那是注册表/badge 的家）或 SidePanelRuntimeContext（useSidePanel 不该
+ * 知道插件业务）：
+ * - state：Chat 每次渲染后回写 { open, activePanelId, focus }，服务侧
+ *   close()/focus() 据此判断；
+ * - requests：服务侧 open/focus/close 的请求队列（nonce 保证同 id 重复
+ *   请求也能重新触发），useSidePanel 订阅并在自己的启用集合里裁决。
+ *
+ * hasConsumer：没有任何 Chat 挂载（无头夹具 / 侧栏永不渲染）时 open()
+ * 必须返回 false 而不是假装成功——attach/detach 由 useSidePanel 的
+ * mount effect 维护。
+ */
+export type PanelBridgeFocus = 'chat' | 'panel';
+export interface PanelBridgeUiState {
+    readonly open: boolean;
+    readonly activePanelId: string | undefined;
+    readonly focus: PanelBridgeFocus;
+}
+export type PanelBridgeRequestKind = 'open' | 'focus' | 'close';
+export interface PanelBridgeRequest {
+    readonly kind: PanelBridgeRequestKind;
+    readonly id: string;
+    readonly nonce: number;
+}
+export declare const panelBridgeRequests: {
+    subscribe(listener: (request: PanelBridgeRequest) => void): () => void;
+    /** 服务侧入口：无 Chat 消费者时返回 false（调用方据此向插件返回 false）。 */
+    request(kind: PanelBridgeRequestKind, id: string): boolean;
+    /** useSidePanel mount/unmount 维护；带消费者才允许请求入队。 */
+    attach(): void;
+    detach(): void;
+    hasConsumer(): boolean;
+};
+export declare const panelBridgeState: {
+    subscribe(listener: () => void): () => void;
+    get(): PanelBridgeUiState;
+    /** 只由 useSidePanel 回写。 */
+    set(next: PanelBridgeUiState): void;
+};
+//# sourceMappingURL=panelBridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"panelBridge.d.ts","sourceRoot":"","sources":["../../../../src/components/sidePanel/panelBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,CAAA;AAE/C,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1C,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;CACnC;AAED,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAE/D,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACzB;AAMD,eAAO,MAAM,mBAAmB;wBACR,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI;IAItE,mDAAmD;kBACrC,sBAAsB,MAAM,MAAM,GAAG,OAAO;IAM1D,iDAAiD;cACvC,IAAI;cACJ,IAAI;mBACC,OAAO;CACzB,CAAA;AAKD,eAAO,MAAM,gBAAgB;wBACL,MAAM,IAAI,GAAG,MAAM,IAAI;WAIpC,kBAAkB;IAGzB,0BAA0B;cAChB,kBAAkB,GAAG,IAAI;CAItC,CAAA"}