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

package/lib/types/components/onboardingModel.js

@@ -0,0 +1,128 @@
+/**
+ * Pure derivation for the first-run onboarding wizard, kept free of React and
+ * channel state so `scripts/verify-onboarding-wizard.tsx` can drive it
+ * headless (the `modelGroups.ts` precedent, for the same reason: the parts
+ * worth pinning are the ones with an opinion, not the JSX).
+ *
+ * @module dsh-tui/components/onboardingModel
+ */
+import { t } from '../i18n.js';
+/** 引导的四个配置域，按"先解决拦路的事、再解决好不好看、最后解决怎么用"排。 */
+export const ONBOARDING_STEPS = ['apikey', 'look', 'model', 'keys'];
+/**
+ * 步骤条需要的**最小**尺寸：四步的标题横排（`❯ API Key 与连通性 · ...`）
+ * 在 76 列下会被截成残句，在 8 行下会把内容挤没——那时整条不画，进度改由
+ * 头部那行"第 N / 4 步"承担（信息不丢，只是换了个地方）。
+ */
+export const STEP_BAR_MIN_COLUMNS = 76;
+export const STEP_BAR_MIN_ROWS = 10;
+/**
+ * 招式卡表：四张能**直接试用**的命令卡 + 两张只能读的键位卡。
+ * 顺序 = 使用频率，不按重要性；第一张是用户最先会需要的。
+ */
+export const TUTORIAL_CARDS = [
+    { id: 'cmd', titleKey: 'onboarding-card-cmd-title', descKey: 'onboarding-card-cmd-desc', literal: '/' },
+    { id: 'help', titleKey: 'onboarding-card-help-title', descKey: 'onboarding-card-help-desc', command: 'help', literal: '?' },
+    { id: 'model', titleKey: 'onboarding-card-model-title', descKey: 'onboarding-card-model-desc', command: 'model' },
+    { id: 'sessions', titleKey: 'onboarding-card-sessions-title', descKey: 'onboarding-card-sessions-desc', command: 'home' },
+    { id: 'rewind', titleKey: 'onboarding-card-rewind-title', descKey: 'onboarding-card-rewind-desc', command: 'rewind' },
+    { id: 'interrupt', titleKey: 'onboarding-card-interrupt-title', descKey: 'onboarding-card-interrupt-desc', action: 'cancel' },
+];
+/**
+ * 每一步的标题与说明 key，**写成字面量表而不是拼串**。
+ *
+ * 拼串（`` `onboarding-step-${step}-title` ``）能跑，但 `verify-i18n` 的死键
+ * 检查是**文本**检查：它按引号字面量找引用，拼出来的键在源码里不存在，只能
+ * 靠登记 `DYNAMIC_PREFIXES` 放行——那是一张"这里不检查"的白名单，放行一次就
+ * 少一处保护。这里总共只有八条，写成表既能被检查器看见，也让"哪一步用哪条
+ * 文案"一眼可读。
+ */
+const STEP_TEXT = {
+    apikey: { title: 'onboarding-step-apikey-title', desc: 'onboarding-step-apikey-desc' },
+    look: { title: 'onboarding-step-look-title', desc: 'onboarding-step-look-desc' },
+    model: { title: 'onboarding-step-model-title', desc: 'onboarding-step-model-desc' },
+    keys: { title: 'onboarding-step-keys-title', desc: 'onboarding-step-keys-desc' },
+};
+/**
+ * 某一步的标题 key。
+ * @param step - 步骤 id。
+ * @returns 该步标题的 i18n key。
+ */
+export function stepTitleKey(step) {
+    return STEP_TEXT[step].title;
+}
+/**
+ * 某一步的说明 key。
+ * @param step - 步骤 id。
+ * @returns 该步说明的 i18n key。
+ */
+export function stepDescKey(step) {
+    return STEP_TEXT[step].desc;
+}
+/** provider 分组（首现顺序，名字用注册表的，取不到就退回 route key）。 */
+export function modelGroupsOf(models, providers) {
+    const order = [];
+    const counts = new Map();
+    for (const model of models) {
+        if (!counts.has(model.provider)) {
+            order.push(model.provider);
+            counts.set(model.provider, 0);
+        }
+        counts.set(model.provider, counts.get(model.provider) + 1);
+    }
+    return order.map(provider => ({
+        provider,
+        label: providers.find(info => info.id === provider)?.name ?? provider,
+        count: counts.get(provider),
+    }));
+}
+/**
+ * 余额显示串：取第一条，币种码直接用接口给的（不猜符号）。
+ *
+ * @param result - `channel.balanceInfo()` 的返回值。
+ * @returns `"CNY 110.00"` 这类串；没有可用条目时 `null`。
+ */
+export function formatBalance(result) {
+    if (!result.ok)
+        return null;
+    const first = result.balances[0];
+    if (first === undefined)
+        return null;
+    return `${first.currency} ${first.total.toFixed(2)}`;
+}
+/**
+ * 连通性失败分类 → 可执行的下一步。
+ *
+ * 分类口径与 `BalanceResult.reason` 一一对应，因为"检查网络"这种话对
+ * `unauthorized` 的用户毫无用处——五种原因要指向五个不同的动作，这正是
+ * `BalanceResult` 分了五类的原因。
+ *
+ * @param reason - `BalanceResult.reason`。
+ * @param status - 非 2xx 时的状态码。
+ * @returns 给用户看的排查方向。
+ */
+export function connFailText(reason, status) {
+    switch (reason) {
+        case 'no-key': return t('onboarding-conn-fail-no-key');
+        case 'network': return t('onboarding-conn-fail-network');
+        case 'unauthorized': return t('onboarding-conn-fail-unauthorized');
+        case 'http': return t('onboarding-conn-fail-http', { status: status ?? 0 });
+        case 'invalid': return t('onboarding-conn-fail-invalid');
+        default: return t('onboarding-conn-fail-unknown');
+    }
+}
+/**
+ * 凭证来源的显示文案。`CredentialStatus.source` 是 adapter 自己的口径
+ * （`'env'` / `'config'` / 其他），这里只做展示映射，认不出的值一律走
+ * "未知"而不是把原始串丢到界面上——那个串属于 adapter 内部词汇。
+ *
+ * @param source - `CredentialStatus.source`。
+ * @returns 一句中文/英文来源说明。
+ */
+export function credentialSourceText(source) {
+    if (source === 'env')
+        return t('onboarding-key-source-env');
+    if (source === 'config')
+        return t('onboarding-key-source-config');
+    return t('onboarding-key-source-unknown');
+}

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

@@ -0,0 +1,17 @@
+/**
+ * InfoPanel — 侧栏「信息」面板：把当前会话的运行信息分组、紧凑地列出。
+ *
+ * 口径与状态栏完全一致：上下文占用（formatContextUsage + contextPressureStep
+ * 阈值配色）、缓存命中（formatCacheHitRate）、TPS（tpsStats / speedColor）、
+ * 花费（estimateSessionCostSnapshotCny 同一套门控）、模式名（modeDisplayName）、
+ * cwd 展示折叠（formatProject）。本组件不推导任何新口径，只重排布局。
+ *
+ * 布局：键值两列，标签列定宽截断、值列悬挂缩进并 truncate——长 cwd /
+ * 长标题在 28 列也不会把列挤爆。内容超高时 ScrollBox 滚动：滚轮由
+ * ScrollBox 自带（位置路由），↑/↓ 经 usePanelInput（v2.1 键盘契约）。
+ * visible=false 时不挂任何定时器 / 高频订阅（本面板本来就是纯读渲染）。
+ */
+import React from 'react';
+import type { PanelProps } from './types.js';
+export declare function InfoPanel({ width, height, focused, visible }: PanelProps): React.ReactNode;
+//# sourceMappingURL=InfoPanel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InfoPanel.d.ts","sourceRoot":"","sources":["../../../../src/components/sidePanel/InfoPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AAezB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAwB5C,wBAAgB,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,UAAU,GAAG,KAAK,CAAC,SAAS,CAsJ1F"}

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

@@ -0,0 +1,124 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * InfoPanel — 侧栏「信息」面板：把当前会话的运行信息分组、紧凑地列出。
+ *
+ * 口径与状态栏完全一致：上下文占用（formatContextUsage + contextPressureStep
+ * 阈值配色）、缓存命中（formatCacheHitRate）、TPS（tpsStats / speedColor）、
+ * 花费（estimateSessionCostSnapshotCny 同一套门控）、模式名（modeDisplayName）、
+ * cwd 展示折叠（formatProject）。本组件不推导任何新口径，只重排布局。
+ *
+ * 布局：键值两列，标签列定宽截断、值列悬挂缩进并 truncate——长 cwd /
+ * 长标题在 28 列也不会把列挤爆。内容超高时 ScrollBox 滚动：滚轮由
+ * ScrollBox 自带（位置路由），↑/↓ 经 usePanelInput（v2.1 键盘契约）。
+ * visible=false 时不挂任何定时器 / 高频订阅（本面板本来就是纯读渲染）。
+ */
+import React from 'react';
+import { Box, Text, ScrollBox } from '../../ui.js';
+import { stringWidth } from '../../ink/stringWidth.js';
+import { t } from '../../i18n.js';
+import { formatTokens } from '../../terminal-utils/format.js';
+import { formatContextUsage } from '../../tuiDisplayPrefs.js';
+import { modeDisplayName } from '../../sessionModes.js';
+import { estimateSessionCostSnapshotCny, isDeepSeekOfficialProvider, isPeakHour } from '../../deepseekPricing.js';
+import { formatCacheHitRate } from '../../screens/StatusLine.js';
+import { contextPressureStep, speedColor } from '../../screens/StatusMetrics.js';
+import { formatProject } from '../../sessions/format.js';
+import { homeDir } from '../../utils/paths.js';
+import { Divider } from '../design-system/Divider.js';
+import { useSidePanelChannel } from './SidePanelRuntimeContext.js';
+import { usePanelInput } from './usePanelInput.js';
+/** 与状态栏同一口径的上下文已用量：最近一次请求的 input+cacheRead+cacheWrite。 */
+function contextUsedOf(channel) {
+    const usage = channel.lastUsage;
+    if (usage === undefined)
+        return undefined;
+    return usage.input + usage.cacheRead + usage.cacheWrite;
+}
+/** 权限行取值：durable preset 身份优先，否则 sandbox·approval 原子拼合。 */
+function approvalOf(mode) {
+    if (mode.permission !== undefined)
+        return mode.permission;
+    if (mode.sandbox === undefined && mode.approval === undefined)
+        return undefined;
+    return [mode.sandbox, mode.approval].filter(Boolean).join('·');
+}
+/** 非默认模式的显式标记（与状态栏 modeNeedsExplicitMarker 同判）。 */
+function modeNeedsExplicitMarker(mode) {
+    return mode.plan === true
+        || mode.sandbox === 'danger-full-access'
+        || mode.approval === 'never';
+}
+export function InfoPanel({ width, height, focused, visible }) {
+    const channel = useSidePanelChannel();
+    const scrollRef = React.useRef(null);
+    // 面板业务键：↑/↓ 滚动（内容超高才有意义）；Esc 等一律让出给宿主回退。
+    const panelKeyHandler = (input, key) => {
+        if (key.escape === true || (key.ctrl === true && input === 'c'))
+            return false;
+        if (key.upArrow === true) {
+            scrollRef.current?.scrollBy(-1);
+            return true;
+        }
+        if (key.downArrow === true) {
+            scrollRef.current?.scrollBy(1);
+            return true;
+        }
+        return false;
+    };
+    usePanelInput(panelKeyHandler, { active: focused && visible });
+    const usage = channel.lastUsage;
+    const used = contextUsedOf(channel);
+    const displayCwd = channel.displayCwd === channel.cwd
+        ? formatProject(channel.displayCwd, homeDir())
+        : channel.displayCwd;
+    // --- 值构造（全部复用状态栏口径） -------------------------------------
+    const none = t('info-value-none');
+    const modeName = modeDisplayName(channel.mode);
+    const approval = approvalOf(channel.mode);
+    const contextText = formatContextUsage(used, channel.contextWindow, true);
+    const contextPct = used !== undefined && channel.contextWindow !== undefined && channel.contextWindow > 0
+        ? (used / channel.contextWindow) * 100
+        : undefined;
+    const contextStep = contextPct !== undefined ? contextPressureStep(contextPct) : undefined;
+    const cacheText = formatCacheHitRate(usage) ?? none;
+    // 花费：与状态栏同门控——官方 DeepSeek 路由 + 有计价金额或未计价 token。
+    const estimate = isDeepSeekOfficialProvider(channel.provider)
+        ? estimateSessionCostSnapshotCny({
+            provider: channel.provider,
+            main: channel.mainCost ?? {},
+            subagents: channel.subagentCost ?? [],
+            fallbackTokens: channel.tokens,
+            fallbackModel: channel.model,
+        })
+        : undefined;
+    const costText = estimate !== undefined && (estimate.total > 0 || estimate.unpricedTokens > 0)
+        ? estimate.total > 0
+            ? '¥' + estimate.total.toFixed(2) + ' ' + t(isPeakHour() ? 'cost-now-peak' : 'cost-now-idle')
+            : t('cost-unpriced', { tokens: formatTokens(estimate.unpricedTokens) })
+        : none;
+    const tpsText = channel.tps !== undefined
+        ? speedColor(channel.tps, String(Math.round(channel.tps))) + ' tps'
+        : none;
+    const jobs = channel.backgroundJobs;
+    const jobsLive = (jobs ?? []).filter(job => job.status === 'running' || job.status === 'stopping').length;
+    const jobsText = jobs !== undefined ? jobsLive + '/' + jobs.length : none;
+    const subagents = channel.subagents;
+    const subagentsText = subagents !== undefined ? String(subagents.length) : none;
+    // 标签列取「本语言最长标签」与「内容宽一半」的较小者：28 列时标签
+    // 先让路（截断），值列保住至少一半——点名字段的前缀必须仍可读。
+    const contentWidth = Math.max(10, width - 2);
+    const labelWidth = Math.min(Math.max(...[
+        t('info-row-title'), t('info-row-session-id'), t('info-row-agent-id'), t('info-row-cwd'),
+        t('info-row-branch'), t('info-row-model'), t('info-row-effort'), t('info-row-mode'),
+        t('info-row-approval'), t('info-row-context'), t('info-row-window'), t('info-row-tokens'),
+        t('info-row-cache'), t('info-row-cost'), t('info-row-tps'), t('info-row-status'),
+        t('info-row-activity'), t('info-row-jobs'), t('info-row-subagents'),
+    ].map(s => stringWidth(s))), Math.max(6, Math.floor(contentWidth / 2)));
+    function Row({ label, value, valueColor }) {
+        return (_jsxs(Box, { flexDirection: "row", gap: 1, width: "100%", children: [_jsx(Box, { width: labelWidth, flexShrink: 0, children: _jsx(Text, { dimColor: true, wrap: "truncate-end", children: label }) }), _jsx(Box, { flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsx(Text, { color: valueColor, wrap: "truncate-end", children: value }) })] }));
+    }
+    function Section({ title, children }) {
+        return (_jsxs(Box, { flexDirection: "column", marginTop: 1, width: "100%", children: [_jsx(Divider, { title: title }), _jsx(Box, { flexDirection: "column", marginTop: 0, width: "100%", children: children })] }));
+    }
+    return (_jsx(Box, { flexDirection: "column", paddingLeft: 1, paddingRight: 1, width: width, flexShrink: 0, children: _jsxs(ScrollBox, { ref: scrollRef, flexDirection: "column", maxHeight: Math.max(3, height), flexGrow: 1, children: [_jsxs(Section, { title: t('info-section-session'), children: [_jsx(Row, { label: t('info-row-title'), value: channel.sessionTitle !== '' ? channel.sessionTitle : none }), _jsx(Row, { label: t('info-row-session-id'), value: channel.sessionId !== '' ? '#' + channel.sessionId.slice(0, 8) : none }), _jsx(Row, { label: t('info-row-agent-id'), value: channel.agentId !== '' ? '#' + channel.agentId.slice(0, 8) : none }), _jsx(Row, { label: t('info-row-cwd'), value: displayCwd !== '' ? displayCwd : none }), _jsx(Row, { label: t('info-row-branch'), value: channel.gitBranch !== undefined && channel.gitBranch !== '' ? channel.gitBranch : none })] }), _jsxs(Section, { title: t('info-section-model'), children: [_jsx(Row, { label: t('info-row-model'), value: channel.model !== '' ? channel.model : none }), _jsx(Row, { label: t('info-row-effort'), value: channel.reasoningEffort !== undefined && channel.reasoningEffort !== '' ? channel.reasoningEffort : none }), _jsx(Row, { label: t('info-row-mode'), value: modeName, valueColor: channel.mode.plan === true ? 'planMode' : modeNeedsExplicitMarker(channel.mode) ? 'warning' : undefined }), _jsx(Row, { label: t('info-row-approval'), value: approval !== undefined && approval !== '' ? approval : none, valueColor: modeNeedsExplicitMarker(channel.mode) ? 'warning' : undefined })] }), _jsxs(Section, { title: t('info-section-context'), children: [_jsx(Row, { label: t('info-row-context'), value: contextText ?? none, valueColor: contextStep }), _jsx(Row, { label: t('info-row-window'), value: channel.contextWindow !== undefined ? formatTokens(channel.contextWindow) : none }), _jsx(Row, { label: t('info-row-tokens'), value: formatTokens(channel.tokens.input) + '→' + formatTokens(channel.tokens.output) }), _jsx(Row, { label: t('info-row-cache'), value: cacheText }), _jsx(Row, { label: t('info-row-cost'), value: costText }), _jsx(Row, { label: t('info-row-tps'), value: tpsText })] }), _jsxs(Section, { title: t('info-section-runtime'), children: [_jsx(Row, { label: t('info-row-status'), value: String(channel.status) }), _jsx(Row, { label: t('info-row-activity'), value: channel.working ? channel.spinnerMode : none, valueColor: channel.working ? 'success' : undefined }), _jsx(Row, { label: t('info-row-jobs'), value: jobsText }), _jsx(Row, { label: t('info-row-subagents'), value: subagentsText })] })] }) }));
+}

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

@@ -0,0 +1,45 @@
+/**
+ * PanelBar: the 1-row tab strip on top of the side panel (design doc §6.1).
+ *
+ * Visual language:
+ * - the ACTIVE panel is a capsule: ‹ Title ›, accent + bold — one glance
+ *   tells you where you are;
+ * - inactive panels collapse to their single-cell icon (or first letter),
+ *   dim, with a status dot only when the panel has something to say
+ *   (● unread/active, ! warning, × error — theme colors, never emoji);
+ * - overflow is windowed, never a trail of dots: what does not fit
+ *   becomes a dim +N on the right edge.
+ *
+ * The bar's width demand is content-independent (capsule titles truncate
+ * to a fixed budget, icons are fixed cells) — a panel MUST never make the
+ * column want to resize (design doc §16.6).
+ */
+import React from 'react';
+export type PanelBadgeLevel = 'info' | 'warning' | 'error';
+export interface PanelBarTab {
+    readonly id: string;
+    readonly title: string;
+    /** Single-cell glyph; falls back to the title's first letter. */
+    readonly icon?: string;
+    readonly badge?: {
+        readonly level: PanelBadgeLevel;
+        readonly unread: number;
+    } | null;
+}
+export interface PanelBarProps {
+    readonly tabs: readonly PanelBarTab[];
+    readonly activeId: string | undefined;
+    readonly width: number;
+    /** Focus is in the right column: the bar brightens to match the divider. */
+    readonly focused: boolean;
+    /** The ACTIVE panel has a fullscreen form (capabilities.fullscreen): the
+     *  bar reserves the two trailing cells and draws the clickable ⤢. */
+    readonly canExpand?: boolean;
+    /** Click/Enter on ⤢: switch the active panel to its fullscreen surface. */
+    readonly onExpand?: () => void;
+    /** Click on a tab (icon or capsule): make that panel active. The host
+     *  funnels this into the same openPanel() path the keyboard uses. */
+    readonly onSelect?: (id: string) => void;
+}
+export declare function PanelBar({ tabs, activeId, width, focused, canExpand, onExpand, onSelect }: PanelBarProps): React.ReactNode;
+//# sourceMappingURL=PanelBar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PanelBar.d.ts","sourceRoot":"","sources":["../../../../src/components/sidePanel/PanelBar.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AAIzB,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;AAE1D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CACrF;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAA;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;yEACqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IAC9B;yEACqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CACzC;AA8BD,wBAAgB,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,aAAa,GAAG,KAAK,CAAC,SAAS,CAqH1H"}

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

@@ -0,0 +1,104 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * PanelBar: the 1-row tab strip on top of the side panel (design doc §6.1).
+ *
+ * Visual language:
+ * - the ACTIVE panel is a capsule: ‹ Title ›, accent + bold — one glance
+ *   tells you where you are;
+ * - inactive panels collapse to their single-cell icon (or first letter),
+ *   dim, with a status dot only when the panel has something to say
+ *   (● unread/active, ! warning, × error — theme colors, never emoji);
+ * - overflow is windowed, never a trail of dots: what does not fit
+ *   becomes a dim +N on the right edge.
+ *
+ * The bar's width demand is content-independent (capsule titles truncate
+ * to a fixed budget, icons are fixed cells) — a panel MUST never make the
+ * column want to resize (design doc §16.6).
+ */
+import React from 'react';
+import { Box, Text } from '../../ui.js';
+import { stringWidth } from '../../ink/stringWidth.js';
+/** Capsule title budget keeps one long plugin title from eating the bar. */
+const ACTIVE_TITLE_MAX = 12;
+function badgeGlyph(level) {
+    if (level === 'warning')
+        return '!';
+    if (level === 'error')
+        return '×';
+    return '●';
+}
+function badgeColor(level) {
+    if (level === 'warning')
+        return 'warning';
+    if (level === 'error')
+        return 'error';
+    return 'accent';
+}
+function truncateCells(text, maxCells) {
+    if (stringWidth(text) <= maxCells)
+        return text;
+    let out = '';
+    let cells = 0;
+    for (const char of text) {
+        const w = stringWidth(char);
+        if (cells + w > Math.max(1, maxCells - 1))
+            break;
+        out += char;
+        cells += w;
+    }
+    return out + '…';
+}
+export function PanelBar({ tabs, activeId, width, focused, canExpand, onExpand, onSelect }) {
+    const [expandHovered, setExpandHovered] = React.useState(false);
+    // Mouse feedback is per-tab: the bar is the only place where a click
+    // switches WHAT the whole right column shows, so it must read as clickable
+    // (hover brightens the glyph; the click path mirrors the ←/→ host keys).
+    const [hoveredTab, setHoveredTab] = React.useState(null);
+    // The ⤢ affordance lives in the bar's own row (design: the panel column's
+    // chrome is fixed-height — a panel must never make the column want to
+    // resize). Reserve its two cells (one gap + one glyph) up front so tab
+    // windowing and the +N marker stay honest at every width.
+    const barWidth = Math.max(0, width - (canExpand === true ? 2 : 0));
+    // Windowing: the active tab is always rendered; inactive tabs fit in
+    // order around it and whatever remains folds into +N on the right.
+    const active = tabs.find(tab => tab.id === activeId) ?? tabs[0];
+    const segments = [];
+    let hidden = 0;
+    let used = 0;
+    const moreCells = (n) => stringWidth('+' + String(n)) + 1;
+    for (const tab of tabs) {
+        const isActive = active !== undefined && tab.id === active.id;
+        // Budget per segment includes the 1-col gap rendered between them
+        // (marginRight), otherwise the +N badge gets clipped at full bars.
+        const cells = (isActive ? Math.min(stringWidth(tab.title), ACTIVE_TITLE_MAX) + 4 : 2) + (segments.length > 0 ? 1 : 0);
+        // Reserve room for the eventual +N badge while tabs remain after this one.
+        const remaining = tabs.length - segments.length - hidden - 1;
+        const reserve = remaining > 0 ? moreCells(remaining) : 0;
+        if (!isActive && used + cells + reserve > barWidth) {
+            hidden += 1;
+            continue;
+        }
+        used += cells;
+        const hovered = hoveredTab === tab.id;
+        segments.push({
+            key: tab.id,
+            node: isActive ? (_jsxs(Text, { bold: true, underline: hovered, color: hovered || focused ? 'accent' : 'inactive', wrap: "truncate-end", children: ['‹ ', truncateCells(tab.title, ACTIVE_TITLE_MAX), ' ›'] })) : (_jsxs(Text, { bold: hovered, dimColor: !hovered && tab.badge == null, color: tab.badge != null ? badgeColor(tab.badge.level) : hovered ? 'accent' : undefined, children: [(tab.icon ?? tab.title.slice(0, 1)).slice(0, 1), tab.badge != null ? badgeGlyph(tab.badge.level) : ''] })),
+            // Every tab is clickable: on an inactive one it switches the column,
+            // on the active one it just takes the focus (same three-state as the
+            // Ctrl+B smart toggle, minus the closing step).
+            clickable: onSelect !== undefined,
+            onHover: (next) => setHoveredTab(previous => (next ? tab.id : previous === tab.id ? null : previous)),
+        });
+    }
+    return (_jsxs(Box, { height: 1, flexShrink: 0, paddingX: 1, overflow: "hidden", children: [_jsx(Box, { flexGrow: 1, flexShrink: 1, overflow: "hidden", children: segments.map((segment, index) => (_jsx(Box, { flexShrink: 0, marginRight: index < segments.length - 1 ? 1 : 0, onMouseEnter: () => { segment.onHover(true); }, onMouseLeave: () => { segment.onHover(false); }, onClick: segment.clickable
+                        ? (event) => {
+                            // Mouse contract: without this the page-level "click the
+                            // column to focus it" fallback also fires on the same event.
+                            event.stopImmediatePropagation();
+                            onSelect?.(segment.key);
+                        }
+                        : undefined, children: segment.node }, segment.key))) }), hidden > 0 && (_jsxs(Text, { dimColor: true, children: ['+', hidden] })), canExpand === true && (_jsx(Box, { flexShrink: 0, marginLeft: 1, onMouseEnter: () => { setExpandHovered(true); }, onMouseLeave: () => { setExpandHovered(false); }, onClick: (event) => {
+                    event.stopImmediatePropagation();
+                    onExpand?.();
+                }, children: _jsx(Text, { bold: expandHovered, color: expandHovered ? 'accent' : 'inactive', children: '⤢' }) }))] }));
+}

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

@@ -0,0 +1,21 @@
+/**
+ * PanelErrorBoundary（照 PluginStatusViewBoundary 的约定）：出错只隐藏
+ * 该 Panel、记 reportError，同 key 重注册用 registrationId 重挂。插件
+ * Panel 崩溃时，Chat 的输入、流式、工具卡必须完全不受影响——硬要求。
+ */
+import React from 'react';
+interface BoundaryProps {
+    readonly panelId: string;
+    readonly children: React.ReactNode;
+}
+interface BoundaryState {
+    readonly error: Error | null;
+}
+export declare class PanelErrorBoundary extends React.Component<BoundaryProps, BoundaryState> {
+    state: BoundaryState;
+    static getDerivedStateFromError(error: Error): BoundaryState;
+    componentDidCatch(error: Error): void;
+    render(): React.ReactNode;
+}
+export {};
+//# sourceMappingURL=PanelErrorBoundary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PanelErrorBoundary.d.ts","sourceRoot":"","sources":["../../../../src/components/sidePanel/PanelErrorBoundary.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AAMzB,UAAU,aAAa;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CACnC;AAED,UAAU,aAAa;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CAC7B;AAED,qBAAa,kBAAmB,SAAQ,KAAK,CAAC,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;IAC1E,KAAK,EAAE,aAAa,CAAkB;IAE/C,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa;IAInD,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAOrC,MAAM,IAAI,KAAK,CAAC,SAAS;CAenC"}

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

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * PanelErrorBoundary（照 PluginStatusViewBoundary 的约定）：出错只隐藏
+ * 该 Panel、记 reportError，同 key 重注册用 registrationId 重挂。插件
+ * Panel 崩溃时，Chat 的输入、流式、工具卡必须完全不受影响——硬要求。
+ */
+import React from 'react';
+import { Box, Text } from '../../ui.js';
+import { t } from '../../i18n.js';
+import { logError } from '../../utils/log.js';
+import { panelStore } from './PanelStore.js';
+export class PanelErrorBoundary extends React.Component {
+    state = { error: null };
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    componentDidCatch(error) {
+        // 卡片上只显示截断的 message，卸载即失忆——落盘一份带边界的完整
+        // 错误（含堆栈），否则"面板渲染出错"永远无法事后归因。
+        logError(new Error(`side panel "${this.props.panelId}" render error: ${error.message}`, { cause: error }));
+        panelStore.reportError(this.props.panelId, error);
+    }
+    render() {
+        const { error } = this.state;
+        if (error !== null) {
+            return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, alignItems: "center", justifyContent: "center", paddingX: 1, children: [_jsx(Text, { color: "error", children: t('panel-error-title') }), _jsx(Box, { height: 1 }), _jsx(Text, { dimColor: true, wrap: "truncate-end", children: error.message }), _jsx(Box, { height: 1 }), _jsx(Text, { dimColor: true, children: t('panel-error-hint') })] }));
+        }
+        return this.props.children;
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * PanelHost（设计文档 §6.3 + v2.1 修订）：
+ * - 计算 bounds 并以 PanelProps 传入；为 Panel 子树再嵌套一层
+ *   TerminalSizeContext（columns = panel width），现有组件直接放进来
+ *   就能拿到正确宽度。
+ * - 每个 Panel 独立 PanelErrorBoundary（registrationId 重挂）。
+ * - mountPolicy（v2.1）：active=只挂 active（插件默认）；enabled=启用
+ *   即挂载，非 active 时 display:none + focused/visible=false——状态
+ *   保留但不动画、不收键（内置 todo/jobs/agents/companion）。
+ * - 不自动包 ScrollBox（v2.1）：滚动由 Panel 自己决定（右栏内的
+ *   ScrollBox 按命中节点接收滚轮）。
+ * - 打开某 Panel 时清它的 badge（soft follow：后台更新只亮点不切换）。
+ * - 键盘：焦点在右栏时，useSidePanel 先经 SidePanelRuntime.dispatchKey
+ *   问活动 Panel（usePanelInput 注册），Panel 没吃才轮到宿主回退键。
+ * - 不知道 Chat 消息、输入、Thinking、工具。
+ */
+import React from 'react';
+import type { ChannelUi } from '../../adapter/channel/ui-policy.js';
+import type { SidePanelController } from './useSidePanel.js';
+export interface PanelHostProps {
+    readonly controller: SidePanelController;
+    readonly channel: ChannelUi;
+    readonly width: number;
+    readonly height: number;
+    readonly activity?: import('../../dsh-adapter/activity-store.js').ActivityView;
+    readonly attention?: {
+        readonly approvals: number;
+        readonly questions: number;
+    };
+    /** 会话轨迹投影（Chat 折好的那一份；轨迹 Panel 直接渲染）。 */
+    readonly trajectory?: import('../../dsh-adapter/trajectory/index.js').TrajBuild;
+    /** 宿主「全屏」出口（PanelBar 的 ⤢ 经 SidePanelColumn 传进来）。 */
+    readonly openFullscreen?: (panelId: string) => void;
+}
+export declare function PanelHost({ controller, channel, width, height, activity, attention, trajectory, openFullscreen }: PanelHostProps): React.ReactNode;
+//# sourceMappingURL=PanelHost.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PanelHost.d.ts","sourceRoot":"","sources":["../../../../src/components/sidePanel/PanelHost.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AAKzB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAA;AAKnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAE5D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,qCAAqC,EAAE,YAAY,CAAA;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/E,yCAAyC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,uCAAuC,EAAE,SAAS,CAAA;IAC/E,oDAAoD;IACpD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACpD;AA4BD,wBAAgB,SAAS,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,EAAE,cAAc,GAAG,KAAK,CAAC,SAAS,CAiFlJ"}

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

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * PanelHost（设计文档 §6.3 + v2.1 修订）：
+ * - 计算 bounds 并以 PanelProps 传入；为 Panel 子树再嵌套一层
+ *   TerminalSizeContext（columns = panel width），现有组件直接放进来
+ *   就能拿到正确宽度。
+ * - 每个 Panel 独立 PanelErrorBoundary（registrationId 重挂）。
+ * - mountPolicy（v2.1）：active=只挂 active（插件默认）；enabled=启用
+ *   即挂载，非 active 时 display:none + focused/visible=false——状态
+ *   保留但不动画、不收键（内置 todo/jobs/agents/companion）。
+ * - 不自动包 ScrollBox（v2.1）：滚动由 Panel 自己决定（右栏内的
+ *   ScrollBox 按命中节点接收滚轮）。
+ * - 打开某 Panel 时清它的 badge（soft follow：后台更新只亮点不切换）。
+ * - 键盘：焦点在右栏时，useSidePanel 先经 SidePanelRuntime.dispatchKey
+ *   问活动 Panel（usePanelInput 注册），Panel 没吃才轮到宿主回退键。
+ * - 不知道 Chat 消息、输入、Thinking、工具。
+ */
+import React from 'react';
+import { Box, Text } from '../../ui.js';
+import { t } from '../../i18n.js';
+import { TerminalSizeContext } from '../../ink/components/TerminalSizeContext.js';
+import { useTerminalSize } from '../../ink/hooks/use-terminal-size.js';
+import { panelStore } from './PanelStore.js';
+import { PanelContext, SidePanelRuntimeContext } from './SidePanelRuntimeContext.js';
+import { PanelErrorBoundary } from './PanelErrorBoundary.js';
+function TooNarrow({ minColumns }) {
+    return (_jsx(Box, { flexDirection: "column", flexGrow: 1, alignItems: "center", justifyContent: "center", paddingX: 1, children: _jsx(Text, { dimColor: true, wrap: "truncate-end", children: t('panel-too-narrow', { min: minColumns }) }) }));
+}
+/** 插件 Panel 连续崩溃后的会话内禁用卡（§18.4）：不再挂载插件组件，只
+ * 提示原因；toast 一次（每 Panel 每会话）。 */
+const disabledToasted = new Set();
+function PluginDisabled({ panelId, channel }) {
+    React.useEffect(() => {
+        if (disabledToasted.has(panelId))
+            return;
+        disabledToasted.add(panelId);
+        channel.notify(t('panel-plugin-disabled-toast'));
+    }, [panelId, channel]);
+    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, alignItems: "center", justifyContent: "center", paddingX: 1, children: [_jsx(Text, { color: "warning", children: t('panel-plugin-disabled') }), _jsx(Box, { height: 1 }), _jsx(Text, { dimColor: true, wrap: "truncate-end", children: t('panel-plugin-disabled-hint') })] }));
+}
+export function PanelHost({ controller, channel, width, height, activity, attention, trajectory, openFullscreen }) {
+    const entries = React.useSyncExternalStore(panelStore.subscribe, () => panelStore.list());
+    // Forward the real screen rows so panel animations (useAnimationFrame →
+    // useTerminalViewport) measure visibility against the screen, not the
+    // host's narrowed rows.
+    const parentSize = useTerminalSize();
+    const screenRows = parentSize.screenRows ?? parentSize.rows;
+    const enabledIds = controller.enabledPanelIds;
+    // 只画「已启用 ∩ 已注册」的 Panel，顺序 = 设置里的启用顺序。
+    const visibleEntries = React.useMemo(() => enabledIds
+        .map(id => entries.find(entry => entry.definition.id === id))
+        .filter((entry) => entry !== undefined), [enabledIds, entries]);
+    const activeEntry = visibleEntries.find(entry => entry.definition.id === controller.activePanelId)
+        ?? visibleEntries[0];
+    // Soft follow：后台更新只亮 PanelBar 状态点；用户打开该 Panel 时清零。
+    const activeId = activeEntry?.definition.id;
+    React.useEffect(() => {
+        if (activeId !== undefined)
+            panelStore.clearBadge(activeId);
+    }, [activeId]);
+    const mode = controller.zoom ? 'zoom' : 'split';
+    const runtimeContext = React.useMemo(() => ({ runtime: controller.runtime, channel, activity, attention, trajectory, openFullscreen }), [controller.runtime, channel, activity, attention, trajectory, openFullscreen]);
+    return (_jsx(SidePanelRuntimeContext.Provider, { value: runtimeContext, children: visibleEntries.map(entry => {
+            const def = entry.definition;
+            const isActive = activeEntry !== undefined && def.id === activeEntry.definition.id;
+            if (!isActive && def.mountPolicy !== 'enabled')
+                return null;
+            if (entry.disabled === true) {
+                return (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", display: isActive ? 'flex' : 'none', children: _jsx(PluginDisabled, { panelId: def.id, channel: channel }) }, def.id));
+            }
+            const tooNarrow = def.minColumns !== undefined && width < def.minColumns;
+            const body = tooNarrow ? (_jsx(TooNarrow, { minColumns: def.minColumns })) : (_jsx(PanelErrorBoundary, { panelId: def.id, children: _jsx(PanelContext.Provider, { value: { panelId: def.id }, children: _jsx(TerminalSizeContext.Provider, { value: { columns: width, rows: height, screenRows }, children: React.createElement(def.component, {
+                            width,
+                            height,
+                            focused: controller.focus === 'panel' && isActive,
+                            visible: isActive,
+                            mode,
+                        }) }) }) }, entry.registrationId));
+            return (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", display: isActive ? 'flex' : 'none', children: body }, def.id));
+        }) }));
+}

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

@@ -0,0 +1,24 @@
+/**
+ * /panel 无参的面板选择器：Pane + Select 行列出「已启用 ∩ 已注册」的
+ * 面板（内置与插件同席——图标、标题、badge 状态点都来自 PanelStore），
+ * 当前活动面板带 current 标记。Enter 打开并聚焦，Esc 取消。
+ */
+import React from 'react';
+import type { SidePanelController } from './useSidePanel.js';
+export interface PanelPickerRow {
+    readonly id: string;
+    readonly title: string;
+    readonly icon?: string;
+    readonly badge?: {
+        readonly level: 'info' | 'warning' | 'error';
+        readonly unread: number;
+    } | null;
+}
+export declare function usePanelPickerRows(controller: SidePanelController): readonly PanelPickerRow[];
+export declare function PanelPicker({ rows, focusIndex, activeId, onPick, }: {
+    readonly rows: readonly PanelPickerRow[];
+    readonly focusIndex: number;
+    readonly activeId: string | undefined;
+    readonly onPick?: (index: number) => void;
+}): React.ReactNode;
+//# sourceMappingURL=PanelPicker.d.ts.map