dsh-ds-balance 1.0.0

package/lib/types/client/model.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 视图模型：把后端契约机械映射成界面需要的形状。
+ * 这里不允许出现金额阈值判断 —— 颜色只由 `severity` 决定。
+ * @module dsh-ds-balance/client/model
+ */
+import type { BalanceInfo, BalanceResponse, Severity } from './api-types.ts';
+/** StateDot 的五个状态（原生原语取值）。 */
+export type DotState = 'done' | 'warning' | 'ongoing' | 'error' | 'idle';
+/** severity → StateDot 状态。见 .agents/notes 的映射决策。 */
+export declare function dotStateOf(severity: Severity): DotState;
+/** 圆环中心可以画的符号。目前只有「账户不可用」用得到。 */
+export type RingMarker = 'cross';
+/** 一个 severity 对应的环形态。 */
+export interface RingSpec {
+    /** 弧的状态；决定弧色。 */
+    state: DotState;
+    /** 中心符号；`null` 表示不画。 */
+    marker: RingMarker | null;
+}
+/**
+ * severity → 环形态。
+ *
+ * **颜色只有四个色相可用**：官方 token 里 `error-primary` 与 `error-secondary`
+ * 在深色主题下同值，没有第五种颜色。所以两档「红」靠**形状**区分：
+ *
+ * - 颜色编码「数值严重度」：绿 → 琥珀 → 红。
+ * - 形状编码「账户可用性」：`unavailable` 是账户维度的事实，与余额高低无关，
+ *   它拿红弧再加一个中心叉号。色盲与低分辨率下依然能分开。
+ *
+ * `critical` 与 `unavailable` 都是红弧，这是有意的：**别再往回改成从红系里挑两个**。
+ * @param severity - 后端给的严重度。
+ * @returns 弧状态与中心符号。
+ */
+export declare function ringSpecOf(severity: Severity): RingSpec;
+/**
+ * 圆环的弧长比例：选中币种的余额占它 warn 阈值的几分之几，封顶 1。
+ *
+ * **阈值在这里只当刻度，不当判据**：颜色仍然完全来自 `severity`，
+ * 这个函数只回答「弧画多长」。阈值是用户自己设的，它天然就是「多少算少」的坐标轴，
+ * 不必再引入一个「满」的基准。`critical` 不参与这里 —— 它已经在后端决定了 `severity`，
+ * 再进一次弧长等于把同一件事算两遍。
+ *
+ * 金额比较走放大 1e8 的整数，不经过浮点数：`v = w` 必须**恰好**是满环。
+ * @param total - 选中币种的余额（定点小数字符串）；`null` 表示没有可展示的币种。
+ * @param warnThreshold - 该币种的 warn 阈值；`undefined` 或非正数表示没配。
+ * @param severity - 后端给的严重度，仅在阈值不可用时用来定性。
+ * @returns 0~1 的弧长比例。
+ */
+export declare function ringRatioOf(total: string | null, warnThreshold: number | undefined, severity: Severity): number;
+/** 币种符号。未知币种回落到代码本身。 */
+export declare function currencySymbol(currency: string): string;
+/**
+ * 把后端的定点小数字符串裁成两位显示。
+ * 全程按字符串处理，不经过浮点数：金额相等比较与累加都在后端。
+ */
+export declare function formatAmount(value: string): string;
+/** 带币种符号的显示金额。 */
+export declare function formatMoney(amount: string, currency: string): string;
+/** 币种选择结果。 */
+export interface CurrencySelection {
+    /** 实际用于展示的那条余额；`null` 表示后端没有给出可展示的币种。 */
+    shown: BalanceInfo | null;
+    /** 后端选定的币种是否就是设置里选的那个。 */
+    matchesPreference: boolean;
+    /** 是否处于「自动」模式。 */
+    auto: boolean;
+    /** 是否连一条可展示的余额都没有。 */
+    empty: boolean;
+}
+/**
+ * 从后端给出的 `selected` 读出展示币种。
+ *
+ * **前端不再自己挑币种**：挑选规则（偏好币种、CNY 优先、余额为 0 时跳过）是
+ * 后端的职责，前端只把结果映射成界面。设置里的显示币种作为查询参数传给后端。
+ *
+ * 读的字段只有两个：`selected.currency`（决定展示哪条）与 `selected` 是否为
+ * `null`（决定空态）。金额直接取 `balances` 里同币种那条 —— `selected` 只带
+ * `total`，浮层还要 `granted` 与 `toppedUp`。
+ *
+ * `balances` 里找不到 `selected.currency` 时返回 `shown: null` 而不是硬凑一条：
+ * 契约保证它一定在，真出现就是形状违约，宁可显示「暂无余额」也不要编一个金额。
+ * @param response - 后端响应。
+ * @param preference - 设置里的显示币种；`auto` 表示跟随账户。
+ * @returns 展示币种与三个布尔标记。
+ */
+export declare function selectionOf(response: BalanceResponse, preference: string): CurrencySelection;
+/** 浮层相对时间的档位。 */
+export type AgeBucket = 'just-now' | 'seconds' | 'minutes' | 'hours' | 'days' | 'unknown';
+/** 把毫秒差归到一档，具体文案交给词典。 */
+export declare function ageBucket(ageMs: number): {
+    bucket: AgeBucket;
+    value: number;
+};

package/lib/types/client/settings/BalanceSettingsCard.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 「DeepSeek 余额」在设置页里的配置卡片。
+ * 只做配置：连接、展示、阈值、刷新四组；不展示任何额度信息，也不按阈值给任何东西上色。
+ * 分组按使用频率排序：刷新三项有合理默认值，放最后。
+ * @module dsh-ds-balance/client/settings/BalanceSettingsCard
+ */
+import type { LocaleKey } from '../locales.ts';
+import type { SettingsScope } from './use-config-form.ts';
+export type { SettingsScope } from './use-config-form.ts';
+/** 卡片要求的属性。t 由框架按注册时声明的字典命名空间注入。 */
+export interface BalanceSettingsCardProps {
+    /** 词典读取器，键域来自本插件的命名空间。 */
+    t: (key: LocaleKey) => string;
+    /** 设置作用域；真实 ctx.settingsScope.bind() 的返回值结构上满足它。 */
+    scope: SettingsScope;
+}
+/**
+ * 渲染配置卡片。
+ * @param props - 词典读取器与设置作用域。
+ * @returns 卡片元素。
+ */
+export declare function BalanceSettingsCard({ t, scope }: BalanceSettingsCardProps): import("react").JSX.Element;

package/lib/types/client/settings/fields.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 手写字段控件：一行一个字段，控件只报告用户输入，写入统一由卡片的保存完成。
+ * 结构对齐官方 ui-settings-plugins/fields.tsx，取值全部走 --dsw-alias-* 语义令牌。
+ * @module dsh-ds-balance/client/settings/fields
+ */
+import type { ReactNode } from 'react';
+import type { TagTone } from '@deepseek-ai/dsh-client-ui-primitives';
+/** 一个配置分组的属性。展开状态由调用方持有：DisclosureRow 是完全受控组件。 */
+export interface FieldGroupProps {
+    /** 折叠头左侧的图标；展开后会被原语自己的 chevron 取代。 */
+    icon: ReactNode;
+    /** 折叠头标题，收起态也显示。 */
+    title: string;
+    /** 展开体开头的组级说明。 */
+    note?: ReactNode;
+    open: boolean;
+    onToggle: () => void;
+    /** 卡片里的最后一组：由它自己补上尾部 12px，卡片 body 不再单独贡献尾距。 */
+    last?: boolean;
+    children: ReactNode;
+}
+/**
+ * 一个可折叠的配置分组。
+ * 折叠头用原语 DisclosureRow（不自己画），展开体由原语在 open 时条件渲染、无动画。
+ * 各组独立展开，不做手风琴：官方 PluginCard 的注释写明多项同时展开是刻意的。
+ * @param props - 图标、标题、可选说明、受控展开状态与字段。
+ * @returns 分组元素。
+ */
+export declare function FieldGroup(props: FieldGroupProps): import("react").JSX.Element;
+/** 标签行右侧的状态胶囊：文案与色调都由调用方决定。 */
+export interface FieldStatus {
+    readonly label: string;
+    readonly tone: TagTone;
+}
+/** 标签行右侧的徽标区：状态胶囊、未保存标记与撤销入口。 */
+export interface FieldBadgesProps {
+    /** 常驻状态胶囊；为 null 或省略时不渲染。 */
+    status?: FieldStatus | null;
+    /** 存在未保存的草稿。 */
+    pending: boolean;
+    /** 存在可撤销的东西：草稿或已存的用户覆盖。 */
+    resettable: boolean;
+    /** 「未保存」文案。 */
+    pendingLabel: string;
+    /** 撤销入口文案。 */
+    resetLabel: string;
+    disabled: boolean;
+    /** 暂存一次清除。 */
+    onReset: () => void;
+}
+/**
+ * 渲染字段的徽标区。三者都不存在时不渲染任何东西。
+ * 状态胶囊排在最前，因为它描述的是当前生效值，而后面两个描述的是待保存的改动。
+ * @param props - 状态胶囊、两种改动状态与撤销回调。
+ * @returns 徽标区元素或 null。
+ */
+export declare function FieldBadges(props: FieldBadgesProps): import("react").JSX.Element | null;
+/** 字段容器：标签行、控件、提示行。 */
+export interface FieldFrameProps extends FieldBadgesProps {
+    /** 关联 label 与控件的稳定 id。 */
+    id: string;
+    /** 可见标签。 */
+    label: string;
+    /** 是否为非法草稿；为真时提示行换成 invalidNote。 */
+    invalid: boolean;
+    /** 常驻说明；省略或为空串时不渲染提示行。 */
+    hint?: ReactNode;
+    /** 非法时替换说明的文案；省略时沿用 hint。 */
+    invalidNote?: ReactNode;
+    /** 控件本体。 */
+    children: ReactNode;
+}
+/**
+ * 渲染一个字段行。
+ * @param props - 字段文案、状态与控件。
+ * @returns 字段行元素。
+ */
+export declare function FieldFrame(props: FieldFrameProps): import("react").JSX.Element;
+/** 文本 / 数字输入。numeric 只提示数字键盘，不改变接受范围。 */
+export interface TextControlProps {
+    id: string;
+    text: string;
+    /** 用 inputMode 的 numeric 值提示键盘；控件始终是 type 为 text。 */
+    numeric: boolean;
+    invalid: boolean;
+    disabled: boolean;
+    /** 失焦回调；阈值字段用它触发成对校验。 */
+    onBlur?: () => void;
+    onEdit: (text: string) => void;
+}
+/**
+ * 渲染单行文本框。
+ * @param props - 草稿文本与编辑回调。
+ * @returns 输入框元素。
+ */
+export declare function TextControl(props: TextControlProps): import("react").JSX.Element;
+/**
+ * 只读输入：字段照常渲染，但不可编辑，**框内不写任何文字**。
+ *
+ * 不从「隐藏字段」也不从「换一块只读文本」走：仍是 `disabled` 的真输入框，
+ * 与官方凭据字段同一形态。`readOnly` 与 `disabled` 同时给 ——
+ * 前者挡住程序化写入，后者给出官方的视觉与可访问语义。
+ *
+ * **为什么没有 placeholder**：灰字写在框里读起来像「这里该填但没填」。
+ * 只读的因由改由标签行右侧的状态徽章与它下方的说明行承担，那两处的措辞来自词典。
+ */
+export interface ReadOnlyControlProps {
+    id: string;
+}
+/**
+ * 渲染只读输入。
+ * @param props - 控件 id。
+ * @returns 输入框元素。
+ */
+export declare function ReadOnlyControl(props: ReadOnlyControlProps): import("react").JSX.Element;
+/** 二级折叠：卡片里的「自定义设置」。 */
+export interface DetailsGroupProps {
+    title: string;
+    /** 初始展开状态；省略即收起。 */
+    defaultOpen?: boolean;
+    children: ReactNode;
+}
+/**
+ * 渲染一个原生 details 折叠块。
+ *
+ * **受控但跟手**：`open` 由 state 持有，用户拨动时从 DOM 读回真实状态，
+ * 所以卡片每次重渲染（每敲一个字都会）不会把用户展开的块弹回去。
+ * @param props - 标题、初始状态与内容。
+ * @returns 折叠块元素。
+ */
+export declare function DetailsGroup(props: DetailsGroupProps): import("react").JSX.Element;
+/** 掩码输入：口令类型加一个显隐切换。 */
+export interface SecretControlProps {
+    id: string;
+    text: string;
+    invalid: boolean;
+    disabled: boolean;
+    /** 当前是否明文显示。 */
+    revealed: boolean;
+    /** 切换显隐按钮的可访问名；语义状态走在 aria-pressed 上。 */
+    revealLabel: string;
+    onToggleReveal: () => void;
+    onEdit: (text: string) => void;
+}
+/**
+ * 渲染掩码输入与它的显隐切换。
+ * @param props - 草稿文本、显隐状态与回调。
+ * @returns 输入行元素。
+ */
+export declare function SecretControl(props: SecretControlProps): import("react").JSX.Element;
+/** 选择器的一个选项。 */
+export interface SelectorOption {
+    readonly id: string;
+    readonly label: string;
+}
+/** 整行选择器：自绘 pill 触发按钮 + 原语 Menu 弹层。 */
+export interface SelectorControlProps {
+    /** 触发按钮的 id，供行容器或测试锚点定位。 */
+    id: string;
+    /** 触发按钮的可访问名，也是弹层的 aria-label。 */
+    label: string;
+    options: readonly SelectorOption[];
+    selectedId: string;
+    disabled: boolean;
+    onSelect: (id: string) => void;
+}
+/**
+ * 渲染原生形态的整行选择器。
+ * 官方设置页的「整行选择型」都是这一套：pill 按钮带 aria-haspopup，弹层由 Menu 自绘并 portal 出去。
+ * 弹层本身（圆角、高程、勾选、键盘、外部点击关闭）全由 Menu 负责，这里只管触发器的外观。
+ * @param props - 当前选中项、可选项与回调。
+ * @returns 选择器元素。
+ */
+export declare function SelectorControl(props: SelectorControlProps): import("react").JSX.Element;
+/** 动作行与它的结果行。 */
+export interface ActionRowProps {
+    label: string;
+    disabled: boolean;
+    /** 结果文案；无结果时为 null，此时不渲染结果行。 */
+    result: {
+        readonly ok: boolean;
+        readonly text: string;
+    } | null;
+    onClick: () => void;
+}
+/**
+ * 渲染一个动作按钮与它的状态结果行。
+ * @param props - 按钮文案、禁用态、结果与回调。
+ * @returns 动作行元素。
+ */
+export declare function ActionRow(props: ActionRowProps): import("react").JSX.Element;

package/lib/types/client/settings/use-config-form.d.ts

@@ -0,0 +1,212 @@
+/**
+ * 配置表单的暂存与保存状态机。
+ * 编辑只落在本地草稿，保存是草稿变成设置的唯一出口。
+ * 快照三元组语义与官方 card-form 一致：value 是生效值，user 是用户覆盖层，键存在即「已覆盖」。
+ * @module dsh-ds-balance/client/settings/use-config-form
+ */
+/** 作用域快照。真实 ctx.settingsScope 的快照还带 status/base/revision/mode，这里只取需要的三片。 */
+export interface SettingsScopeSnapshotLike {
+    /** 合并后的生效配置。 */
+    value: Record<string, unknown>;
+    /** 用户覆盖层；键是否存在就是「已覆盖」的判据。 */
+    user: Record<string, unknown>;
+    /** 宿主文档是否接受写入。 */
+    writable: boolean;
+}
+/**
+ * 配置卡片依赖的最小作用域面。
+ * 真实的 ctx.settingsScope.bind() 返回值结构上满足它，但 set/unset 返回 Promise，父代理的适配层可以原样透传。
+ */
+export interface SettingsScope {
+    /** 读当前快照。 */
+    getSnapshot(): SettingsScopeSnapshotLike;
+    /** 订阅快照变化。 */
+    subscribe(listener: () => void): () => void;
+    /** 写入一个字段。 */
+    set(field: string, value: unknown): void;
+    /** 清除一个字段的用户覆盖。 */
+    unset(field: string): void;
+}
+/** 一次字段写入。 */
+export type FieldWrite = {
+    readonly kind: 'set';
+    readonly value: unknown;
+} | {
+    readonly kind: 'clear';
+};
+/** 字段控件类型。 */
+export type FieldKind = 'text' | 'secret' | 'number' | 'select';
+/** 文本类字段规格。 */
+export interface TextFieldSpec {
+    readonly field: string;
+    readonly kind: 'text' | 'secret' | 'number';
+    /** 把生效值渲染成草稿文本。 */
+    format(value: unknown): string;
+    /** 把草稿文本解析成写入；返回 undefined 表示这份草稿非法并阻止保存。 */
+    parse(text: string): FieldWrite | undefined;
+}
+/** 值类字段规格（下拉这类不经过文本草稿的控件）。 */
+export interface ValueFieldSpec {
+    readonly field: string;
+    readonly kind: 'select';
+}
+/** 任一字段规格。 */
+export type AnyFieldSpec = TextFieldSpec | ValueFieldSpec;
+/**
+ * 判断规格是否文本类。
+ * @param spec - 字段规格。
+ * @returns 是否文本类。
+ */
+export declare function isTextSpec(spec: AnyFieldSpec): spec is TextFieldSpec;
+/** 自由文本：空串等于清除，与官方 textField 同规则。 */
+export declare function textField(field: string, kind?: 'text' | 'secret'): TextFieldSpec;
+/** 数字文本：空串等于清除，非有限数视为非法；上下界由宿主 schema 决定。 */
+export declare function numberField(field: string): TextFieldSpec;
+/** 下拉字段。 */
+export declare function selectField(field: string): ValueFieldSpec;
+/** 自动币种取值。 */
+export declare const AUTO_CURRENCY = "auto";
+/** 已知币种。阈值分组就是按这两个币种定义的，故它们是币种列表的最小闭集。 */
+export declare const KNOWN_CURRENCIES: readonly string[];
+/** 一对阈值：同一币种内的预警与告急。 */
+export interface ThresholdPair {
+    readonly currency: string;
+    readonly warn: string;
+    readonly critical: string;
+    /**
+     * 两个字段的宿主默认值。
+     *
+     * **必须在这里存一份**：草稿清空之后生效的是默认值而不是旧值，判「空值算不算合法」就得知道它。
+     * 两个半体不许值导入，所以抄一份是没办法的事 —— 与宿主 schema 的一致性由
+     * `test/threshold-pairs.test.ts` 对着 [src/config.ts](../../config.ts) 的 `Config` 兜底。
+     */
+    readonly defaultWarn: number;
+    readonly defaultCritical: number;
+}
+/** 阈值成对的清单；字段名沿用宿主 schema 的「币种代码小写 + Warn / Critical」。 */
+export declare const THRESHOLD_PAIRS: readonly ThresholdPair[];
+/**
+ * 一对阈值是否满足「告急 **严格低于** 预警」。
+ *
+ * 相等也拒绝：那时余额恰好压线会被同时判成 warn 与 critical，「预警」这一档等于不存在。
+ * 任一侧的草稿不是数字时返回 `true` —— 那种情况由各自的 `parse` 报错，不在这里重复报。
+ * @param pair - 币种与它的两个字段。
+ * @param warn - 预警字段的状态。
+ * @param critical - 告急字段的状态。
+ * @returns 是否通过。
+ */
+export declare function thresholdsOk(pair: ThresholdPair, warn: FieldState, critical: FieldState): boolean;
+/**
+ * 下拉可选的币种代码。
+ * 已知币种打底；传入的取值里若是未知代码也一并保留，避免把用户已存或编辑中的取值弄丢。
+ * @param currents - 任意个候选取值，通常同时给草稿值与生效值。
+ * @returns 非自动的币种代码列表。
+ */
+export declare function currencyCodes(...currents: readonly unknown[]): readonly string[];
+/** 卡片配置的全部字段，顺序即渲染顺序的参照。 */
+export declare const CONFIG_FIELDS: readonly AnyFieldSpec[];
+/** 字段名到规格的索引。 */
+export declare const SPEC_BY_FIELD: ReadonlyMap<string, AnyFieldSpec>;
+/** 一个字段渲染所需的状态。 */
+export interface FieldState {
+    /** 文本类字段的草稿文本。 */
+    readonly text: string;
+    /** 值类字段的草稿值；文本类字段为 undefined。 */
+    readonly value: unknown;
+    /** 快照里的生效值，与草稿无关。 */
+    readonly effective: unknown;
+    /** 用户层当前就存着这个字段（不看草稿）。状态徽标用它判「已覆盖」。 */
+    readonly stored: boolean;
+    /** 保存后该字段是否会留下用户层条目。 */
+    readonly overridden: boolean;
+    /** 这份草稿是否会产生一次写入。 */
+    readonly dirty: boolean;
+    /** 草稿是否不是该字段接受的值。 */
+    readonly invalid: boolean;
+}
+/** 表单整体状态。 */
+export interface ConfigFormState {
+    /** 宿主文档是否接受写入。 */
+    readonly writable: boolean;
+    /** 是否存在会产生写入的草稿。 */
+    readonly dirty: boolean;
+    /** 是否存在非法草稿；为真时禁止保存。 */
+    readonly invalid: boolean;
+    /** 是否正在跨线写入。 */
+    readonly saving: boolean;
+    /** 上一次保存是否没有落定；下一次编辑或保存会清掉它。 */
+    readonly failed: boolean;
+}
+/** 测试连接的状态。 */
+export interface TestState {
+    /** 是否正在测试。 */
+    readonly running: boolean;
+    /** 结果；未出结果时为 null。 */
+    readonly ok: boolean | null;
+    /** 失败原因；成功或未出结果时为空串。 */
+    readonly message: string;
+}
+/** 表单暴露给卡片的面。 */
+export interface ConfigFormApi {
+    /** 整体状态。 */
+    readonly state: ConfigFormState;
+    /** 读一个字段的渲染状态。 */
+    field(field: string): FieldState;
+    /** 暂存文本类字段的编辑。 */
+    edit(field: string, text: string): void;
+    /** 暂存值类字段的编辑。 */
+    setValue(field: string, value: unknown): void;
+    /** 暂存一次清除，让该字段回到组合层。 */
+    resetField(field: string): void;
+    /** 丢弃全部草稿。 */
+    discard(): void;
+    /** 写入全部草稿，并从快照读回落定结果。 */
+    save(): Promise<void>;
+    /** 一个币种的阈值草稿是否满足「告急 < 预警」；空草稿按默认值算。 */
+    thresholdPairOk(currency: string): boolean;
+    /** 该字段是否已经失焦过；用来决定要不要显示成对校验提示。 */
+    touched(field: string): boolean;
+    /** 记一次失焦。 */
+    touch(field: string): void;
+    /** 测试连接状态。 */
+    readonly test: TestState;
+    /** 跑一次本地模拟的连接测试。 */
+    runTest(): void;
+}
+/** 本地模拟的连接测试耗时。 */
+export declare const TEST_LATENCY_MS = 800;
+/**
+ * 判定一次模拟连接测试是否失败。
+ * 规则：Base URL 必须以 http:// 或 https:// 开头；API Key 与引用名不能同时为空。
+ * 返回的是宿主诊断风格的英文短句，与官方卡片直接展示宿主诊断的做法一致。
+ * @param baseUrl - 当前草稿或生效的 Base URL。
+ * @param apiKey - 当前草稿或生效的 API Key。
+ * @param apiKeyRef - 当前草稿或生效的引用名。
+ * @returns 失败原因；可通过时为 null。
+ */
+export declare function probeFailure(baseUrl: string, apiKey: string, apiKeyRef: string): string | null;
+/** 计划中的一次写入；write 为 undefined 表示草稿非法。 */
+interface PlannedWrite {
+    readonly field: string;
+    readonly write: FieldWrite | undefined;
+}
+/**
+ * 把写入计划里的成对字段排成「每一步合并后都合法」的顺序。
+ *
+ * 宿主的 `validate` 在**合并后的完整候选值**上跑，所以单字段写入会让中间态短暂非法：
+ * 把 (20, 15) 改成 (10, 5)，先写 warn 会得到 (10, 15)，宿主直接拒绝整次写入。
+ *
+ * 判据只看 warn：先写 warn 之后是 `(warn', critical)`，合法就保持原顺序；不合法就只能先写 critical ——
+ * 那时 `critical' < warn' ≤ critical < warn`，所以 `(warn, critical')` 必然合法。两者必有一个成立。
+ * @param writes - 待写入的编辑。
+ * @param current - 当前生效值，用来看「另一半现在是多少」。
+ * @returns 排好序的新数组。
+ */
+export declare function orderPairWrites(writes: readonly PlannedWrite[], current: Record<string, unknown>): PlannedWrite[];
+/**
+ * 绑定一个设置命名空间的配置表单。
+ * @param scope - 卡片拿到的设置作用域。
+ * @returns 表单状态与动作。
+ */
+export declare function useConfigForm(scope: SettingsScope): ConfigFormApi;
+export {};

package/lib/types/client/settings/use-credential-state.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 凭据状态：问后端要「配没配 / 可不可写」这三个事实。
+ *
+ * 官方的 provider 卡片用 `describeCredential()` 决定密钥字段是「可编辑」还是
+ * 「由启动环境提供（只读）」；浏览器半边拿不到凭据服务，所以走插件自己的
+ * `GET /api/v1/config`（**响应里没有密钥**，只有一个固定长度的掩码串）。
+ *
+ * 读不到就回 `null`，界面据此把字段当只读——宁可少给一个编辑入口，
+ * 也不要在不知道的情况下让用户以为能改。
+ * @module dsh-ds-balance/client/settings/use-credential-state
+ */
+import { type CredentialInfo } from '../data.ts';
+/** 只读凭据行要显示的状态。 */
+export type CredentialView = 'env' | 'configured' | 'notConfigured' | 'overridden';
+/**
+ * 决定只读凭据行显示哪一档。
+ *
+ * 它回答的是「**当前生效的值从哪来**」，不是「这个框能不能改」：
+ * - `overridden` 优先：折叠里存过 apiKey 或引用名时，生效的就是折叠里那一份。
+ * - 其次看宿主能不能写：写不了就是启动环境给的。
+ * - 再退到「配没配」。
+ * - 凭据信息读不到（`null`）一律当 `env`：这一行本来就是只读展示，编辑入口在下面的
+ *   「自定义设置」，所以「环境提供」在任何未知情况下都不会说错话，也不会因为字段缺失把卡片打挂。
+ *
+ * 优先级本身有测试兜底（`test/use-credential-state.test.ts`）—— 它是最容易被改错的一处。
+ * @param credential - 宿主的凭据描述；`null` 表示读不到。
+ * @param overridden - 用户层是否存着覆盖值（`apiKey` 或引用名）。
+ * @returns 四档之一。
+ */
+export declare function credentialViewOf(credential: CredentialInfo | null, overridden: boolean): CredentialView;
+/**
+ * 订阅凭据的只读描述。
+ * @param ref - 当前生效的凭据引用名；它一变就重读一次。
+ * @returns 三个事实，或 `null` 表示读不到。
+ */
+export declare function useCredentialState(ref: string): CredentialInfo | null;

package/lib/types/client/sidebar/BalancePopover.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 余额浮层：点击条目后在条目的上方展开。
+ *
+ * 皮肤照抄官方「用量 / 用时」浮层（ui-chat 的 stat-dialog.module.css）；
+ * 定位由父组件用 useAnchoredPosition 算好后经 style 传入，本组件只渲染表面。
+ * 面板由父组件 createPortal 挂到 document.body，所以 panelRef 指向面板自身。
+ * @module dsh-ds-balance/client/sidebar/BalancePopover
+ */
+import type { CSSProperties, RefObject } from 'react';
+import { type LocaleKey } from '../locales.ts';
+import { type CurrencySelection } from '../model.ts';
+/** 没有可显示金额时的占位符；条目与浮层共用同一个字面量。 */
+export declare const BALANCE_PLACEHOLDER = "--";
+/** 浮层属性。 */
+export interface BalancePopoverProps {
+    /** 词典函数。 */
+    t: (key: LocaleKey) => string;
+    /** 币种选择结果。 */
+    selection: CurrencySelection;
+    /** 用户在设置里选的币种，用于不匹配文案。 */
+    displayCurrency: string;
+    /** 生效的抓取时刻（毫秒）；模拟刷新会替换它。 */
+    fetchedAt: number;
+    /** 当前时刻（毫秒），由父组件按秒推进。 */
+    now: number;
+    /** 是否正在刷新。 */
+    refreshing: boolean;
+    /** 冷却剩余秒数；0 表示可以刷新。 */
+    cooldownSeconds: number;
+    /** 面板自身的引用：useAnchoredPosition 用它量尺寸，外部点击判定用它算「内部」。 */
+    panelRef: RefObject<HTMLElement>;
+    /** 由 useAnchoredPosition 给出的 fixed 坐标；首帧是 MEASURE_STYLE（隐藏待测）。 */
+    style: CSSProperties;
+    /** 刷新回调。 */
+    onRefresh: () => void;
+    /** 「改用 X」回调。 */
+    onUseShown: () => void;
+    /** 「去设置」回调；本阶段只做占位。 */
+    onOpenSettings: () => void;
+}
+/**
+ * 渲染余额浮层。
+ * @param props - 选择结果、时间、刷新状态、面板 ref/style 与三个动作回调。
+ * @returns 浮层元素。
+ */
+export declare function BalancePopover(props: BalancePopoverProps): JSX.Element;

package/lib/types/client/sidebar/PercentRing.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 状态圆环：条目在展开态与折叠态共用的唯一图标。
+ *
+ * 几何逐条照抄官方 ContextMeter：viewBox 14×14、r=5.5、stroke-width 2、
+ * 用 strokeDasharray 而不是 stroke-dashoffset，起点靠 rotate(-90 7 7) 挪到 12 点。
+ *
+ * 两件事分开编码：
+ * - **弧长**表达比例：余额占该币种 warn 阈值的几分之几，由 `model.ts` 的 `ringRatioOf` 算好传进来。
+ *   阈值是用户自己设的刻度，所以不必再定义「满」是多少；本组件不做任何金额判断。
+ * - **颜色**按 state 机械映射，取值与原生 StateDot 的 data-state 一一对应，来源只有 `severity`。
+ * 账户不可用（unavailable）在这条弧上再加一个中心叉号：颜色只有四个色相可用，
+ * 形状负责把「账户维度不可用」与「余额维度告急」分开。
+ * @module dsh-ds-balance/client/sidebar/PercentRing
+ */
+import type { RingMarker } from '../model.ts';
+/** 圆环能表达的状态；取值域与原生 StateDot 对齐，本插件用不到 ongoing。 */
+export type RingState = 'done' | 'warning' | 'error' | 'idle';
+/** 圆环属性。 */
+export interface PercentRingProps {
+    /** 状态，决定环的颜色；语义与原生 StateDot 的同一套枚举一致。 */
+    state: RingState;
+    /** 中心符号；`null` 或省略时不画。 */
+    marker?: RingMarker | null;
+    /** 弧长比例 0~1；省略即满环。越界与非数都夹回 [0, 1]。 */
+    ratio?: number;
+    /** 渲染边长（px），默认 18。 */
+    size?: number;
+    /** 可选的原生悬停提示，由 SVG 的 <title> 子元素承载。 */
+    title?: string;
+}
+/**
+ * 渲染状态圆环。
+ * @param props - 状态、边长与可选提示。
+ * @returns 圆环 svg；自身 aria-hidden，语义名由调用方的 aria-label 提供。
+ */
+export declare function PercentRing({ state, marker, ratio, size, title }: PercentRingProps): JSX.Element;