@armadra/agent 0.3.0 → 0.4.0

package/dist/tui/components/key-value.js

@@ -4,8 +4,9 @@
  * - 键列宽 = 最长键的可见宽度，但不超过总宽的 `maxKeyRatio`（缺省 0.4，至少 4 列），超出的键截断；
  * - 值在剩余宽度内截断（不换行，保留 ANSI 样式）；值里的换行折成 ` ⏎ `；
  * - 宽度连键列都放不下时退化为只显示截断后的键；空行（`key` 为空串）原样输出空行，可作分组间隔。
+ * - `wrap: true`：值按剩余宽度折行（值里的换行也换行），续行对齐值列。
  */
-import { padToWidth, truncateToWidth, visibleWidth } from "../ansi.js";
+import { padToWidth, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../ansi.js";
 /** 键列至少保留的宽度（键更短时取键宽）；再窄就只显示键。 */
 const MIN_KEY_WIDTH = 4;
 export class KeyValue {
@@ -29,15 +30,24 @@ export class KeyValue {
         const keyWidth = Math.min(longest, Math.max(share, MIN_KEY_WIDTH));
         const valueWidth = width - keyWidth - gap;
         const { theme, keyColor = "dim" } = this.options;
-        const lines = this.rows.map(({ key, value }) => {
+        const wrap = this.options.wrap === true;
+        const lines = this.rows.flatMap(({ key, value }) => {
             if (key === "" && value === "")
-                return "";
+                return [""];
             const shownKey = truncateToWidth(key, Math.max(keyWidth, 1));
             const styledKey = theme ? theme.fg(keyColor, shownKey) : shownKey;
             if (valueWidth < 1)
-                return truncateToWidth(styledKey, width);
-            const flat = value.replace(/\r?\n/g, " ⏎ ");
-            return padToWidth(styledKey, keyWidth) + " ".repeat(gap) + truncateToWidth(flat, valueWidth);
+                return [truncateToWidth(styledKey, width)];
+            const head = padToWidth(styledKey, keyWidth) + " ".repeat(gap);
+            if (!wrap) {
+                const flat = value.replace(/\r?\n/g, " ⏎ ");
+                return [head + truncateToWidth(flat, valueWidth)];
+            }
+            const pieces = value
+                .split(/\r?\n/)
+                .flatMap((line) => (line === "" ? [""] : wrapTextWithAnsi(line, valueWidth)));
+            const indent = " ".repeat(keyWidth + gap);
+            return pieces.map((piece, i) => (i === 0 ? head : indent) + piece);
         });
         this.cache = { width, lines };
         return lines;

package/dist/tui/components/loader.d.ts

@@ -1,35 +1,65 @@
 /**
- * 旋转指示器（设计 §12.1、§12.6：运行中显示 Loader 与已用时）。[B4]
+ * 运行指示（设计 §12.1、§12.6；终端界面视觉设计 v1 §3.7）。[B4]
  *
- * 帧由定时器推进并调用 `requestRender`；`stop()` 后不再触发渲染。时钟可注入便于测试。
+ * 一行 `⠋ 动词 · 已用时 · 附加项…`：spinner `accent`、动词正文色、其余 `dim`，以 ` · ` 连接。
+ * - `setVerb(verb, extras, { elapsed })` 换动词（思考中 / 回复中 / 运行 bash / 等待确认……）；
+ *   `setMessage(text)` 是只换动词的旧接口。
+ * - 帧取 `theme.glyphs.spinner`（Unicode 10 帧 80 ms、ASCII 4 帧 250 ms）；`frame` 暴露当前帧字形，
+ *   `onFrame` 让别的组件（运行中的工具摘要行）与 Loader 同帧换字，保证一帧只多改一行。
+ * - `animation: false`：spinner 固定为 `glyphs.spinnerStatic`，定时器每秒一次，已用时变了才请求重绘。
+ * - `stop()` 后不再触发渲染。时钟可注入便于测试。
  */
 import type { Component, Theme } from "../component.js";
-export declare const LOADER_FRAMES: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** Unicode 帧表（兼容旧导出；实际帧取 `theme.glyphs.spinner`）。 */
+export declare const LOADER_FRAMES: readonly string[];
 export interface LoaderOptions {
+    /** 初始动词（旧名 message）。 */
     message?: string;
     theme?: Theme;
-    /** 帧间隔（ms），缺省 80。 */
+    /** 帧间隔（ms），缺省 Unicode 80、ASCII 250；`animation: false` 时为 1000。 */
     intervalMs?: number;
     /** 显示已用时（`12s`、`1m05s`），缺省 true。 */
     showElapsed?: boolean;
+    /** false：spinner 静止，缺省 true。 */
+    animation?: boolean;
     now?: () => number;
 }
+export interface LoaderVerbOptions {
+    /** 本动词是否显示已用时（缺省跟随 `showElapsed`）。 */
+    elapsed?: boolean;
+}
 export declare function formatElapsed(ms: number): string;
 export declare class Loader implements Component {
     private readonly requestRender;
     private readonly options;
-    private frame;
+    private frameIndex;
     private timer;
     private startedAt;
-    private message;
+    private verb;
+    private extras;
+    private verbElapsed;
+    private lastElapsed;
+    private readonly listeners;
     private readonly now;
     constructor(requestRender: () => void, options?: LoaderOptions);
     get running(): boolean;
+    private get frames();
+    private get animated();
+    /** 当前帧字形（静止时为 `spinnerStatic`）。 */
+    get frame(): string;
+    /** 订阅换帧（返回取消函数）。 */
+    onFrame(listener: (frame: string) => void): () => void;
+    /** 换动词与附加项（附加项 dim，排在已用时之后）。 */
+    setVerb(verb: string, extras?: readonly string[], options?: LoaderVerbOptions): void;
+    /** 旧接口：只换动词。 */
     setMessage(message: string): void;
+    /** 已用时从现在重新算（换到另一段工作时）。 */
+    resetElapsed(): void;
     start(): void;
     stop(): void;
-    /** 推进一帧（定时器调用；测试可直接调用）。 */
+    /** 推进一帧（定时器调用；测试可直接调用）。静止时只在已用时变化时重绘。 */
     tick(): void;
+    private elapsedText;
     render(width: number): string[];
     invalidate(): void;
 }

package/dist/tui/components/loader.js

@@ -1,10 +1,18 @@
 /**
- * 旋转指示器（设计 §12.1、§12.6：运行中显示 Loader 与已用时）。[B4]
+ * 运行指示（设计 §12.1、§12.6；终端界面视觉设计 v1 §3.7）。[B4]
  *
- * 帧由定时器推进并调用 `requestRender`；`stop()` 后不再触发渲染。时钟可注入便于测试。
+ * 一行 `⠋ 动词 · 已用时 · 附加项…`：spinner `accent`、动词正文色、其余 `dim`，以 ` · ` 连接。
+ * - `setVerb(verb, extras, { elapsed })` 换动词（思考中 / 回复中 / 运行 bash / 等待确认……）；
+ *   `setMessage(text)` 是只换动词的旧接口。
+ * - 帧取 `theme.glyphs.spinner`（Unicode 10 帧 80 ms、ASCII 4 帧 250 ms）；`frame` 暴露当前帧字形，
+ *   `onFrame` 让别的组件（运行中的工具摘要行）与 Loader 同帧换字，保证一帧只多改一行。
+ * - `animation: false`：spinner 固定为 `glyphs.spinnerStatic`，定时器每秒一次，已用时变了才请求重绘。
+ * - `stop()` 后不再触发渲染。时钟可注入便于测试。
  */
 import { truncateToWidth } from "../ansi.js";
-export const LOADER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+import { UNICODE_GLYPHS } from "../glyphs.js";
+/** Unicode 帧表（兼容旧导出；实际帧取 `theme.glyphs.spinner`）。 */
+export const LOADER_FRAMES = UNICODE_GLYPHS.spinner;
 export function formatElapsed(ms) {
     const total = Math.max(0, Math.floor(ms / 1000));
     if (total < 60)
@@ -16,31 +24,74 @@ export function formatElapsed(ms) {
 export class Loader {
     requestRender;
     options;
-    frame = 0;
+    frameIndex = 0;
     timer = null;
     startedAt;
-    message;
+    verb;
+    extras = [];
+    verbElapsed;
+    lastElapsed = "";
+    listeners = new Set();
     now;
     constructor(requestRender, options = {}) {
         this.requestRender = requestRender;
         this.options = options;
         this.now = options.now ?? Date.now;
-        this.message = options.message ?? "";
+        this.verb = options.message ?? "";
         this.startedAt = this.now();
     }
     get running() {
         return this.timer !== null;
     }
-    setMessage(message) {
-        this.message = message;
+    get frames() {
+        return (this.options.theme?.glyphs ?? UNICODE_GLYPHS).spinner;
+    }
+    get animated() {
+        return this.options.animation !== false;
+    }
+    /** 当前帧字形（静止时为 `spinnerStatic`）。 */
+    get frame() {
+        const glyphs = this.options.theme?.glyphs ?? UNICODE_GLYPHS;
+        return this.animated
+            ? this.frames[this.frameIndex % this.frames.length]
+            : glyphs.spinnerStatic;
+    }
+    /** 订阅换帧（返回取消函数）。 */
+    onFrame(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** 换动词与附加项（附加项 dim，排在已用时之后）。 */
+    setVerb(verb, extras = [], options = {}) {
+        const same = verb === this.verb &&
+            options.elapsed === this.verbElapsed &&
+            extras.length === this.extras.length &&
+            extras.every((e, i) => e === this.extras[i]);
+        if (same)
+            return;
+        this.verb = verb;
+        this.extras = [...extras];
+        this.verbElapsed = options.elapsed;
         this.requestRender();
     }
+    /** 旧接口：只换动词。 */
+    setMessage(message) {
+        this.setVerb(message);
+    }
+    /** 已用时从现在重新算（换到另一段工作时）。 */
+    resetElapsed() {
+        this.startedAt = this.now();
+    }
     start() {
         if (this.timer !== null)
             return;
         this.startedAt = this.now();
-        this.frame = 0;
-        this.timer = setInterval(() => this.tick(), this.options.intervalMs ?? 80);
+        this.frameIndex = 0;
+        const glyphs = this.options.theme?.glyphs ?? UNICODE_GLYPHS;
+        const interval = this.animated
+            ? (this.options.intervalMs ?? (glyphs.ascii ? 250 : 80))
+            : Math.max(this.options.intervalMs ?? 1000, 1000);
+        this.timer = setInterval(() => this.tick(), interval);
         this.timer.unref?.();
         this.requestRender();
     }
@@ -50,22 +101,34 @@ export class Loader {
         clearInterval(this.timer);
         this.timer = null;
     }
-    /** 推进一帧（定时器调用；测试可直接调用）。 */
+    /** 推进一帧（定时器调用；测试可直接调用）。静止时只在已用时变化时重绘。 */
     tick() {
-        this.frame = (this.frame + 1) % LOADER_FRAMES.length;
+        if (this.animated)
+            this.frameIndex = (this.frameIndex + 1) % this.frames.length;
+        else if (this.elapsedText() === this.lastElapsed)
+            return;
+        const frame = this.frame;
+        for (const listener of this.listeners)
+            listener(frame);
         this.requestRender();
     }
+    elapsedText() {
+        return formatElapsed(this.now() - this.startedAt);
+    }
     render(width) {
         const theme = this.options.theme;
-        const spinner = LOADER_FRAMES[this.frame];
-        const parts = [theme ? theme.fg("accent", spinner) : spinner];
-        if (this.message !== "")
-            parts.push(this.message);
-        if (this.options.showElapsed !== false) {
-            const elapsed = `(${formatElapsed(this.now() - this.startedAt)})`;
-            parts.push(theme ? theme.fg("dim", elapsed) : elapsed);
-        }
-        return [truncateToWidth(parts.join(" "), width)];
+        const dim = (s) => (theme ? theme.fg("dim", s) : s);
+        const parts = [];
+        if (this.verb !== "")
+            parts.push(this.verb);
+        const elapsed = this.elapsedText();
+        this.lastElapsed = elapsed;
+        if (this.verbElapsed ?? this.options.showElapsed !== false)
+            parts.push(dim(elapsed));
+        for (const extra of this.extras)
+            parts.push(dim(extra));
+        const spinner = theme ? theme.fg("accent", this.frame) : this.frame;
+        return [truncateToWidth(`${spinner} ${parts.join(dim(" · "))}`, width)];
     }
     invalidate() { }
 }

package/dist/tui/components/markdown.d.ts

@@ -4,7 +4,11 @@
  * 支持：ATX 标题、段落（软换行合并为空格，行尾两个空格或 `\` 为硬换行）、无序 / 有序列表（缩进嵌套）、
  * 围栏代码块（边框 + 语言标签；流式时未闭合的围栏按代码块渲染）、引用、分隔线、
  * 行内 `code` / **粗体** / *斜体* / ~~删除线~~ / [链接](url) / <自动链接> / 反斜杠转义。
- * 表格降级为等宽对齐文本（不换行、超宽截断）；不做语法高亮（§12.9）。
+ * 表格降级为等宽对齐文本（列间两个空格、首行粗体其下一条规则线、不换行、超宽截断）；不做语法高亮（§12.9）。
+ *
+ * 配色（终端界面视觉设计 v1 §3.3）：h1 / h2 `accent` 粗体，h3+ 粗体；行内代码 `code`；链接文字 `link`
+ * 加下划线、URL 以 ` (url)` `dim` 追加；列表符号 `muted`；代码块全宽、边框 `border`、语言标签 `dim`、
+ * 正文 `text`；引用 `▎` + `muted` 斜体。字形（圆点、框线、竖条）取 `theme.glyphs`。
  *
  * 缓存：按块缓存渲染结果（键 = 宽度 + 块源文本），流式追加时只有末块重新渲染；解析也是增量的
  * （`Markdown.append` 只从尾部可能变化的块重新解析）。

package/dist/tui/components/markdown.js

@@ -4,7 +4,11 @@
  * 支持：ATX 标题、段落（软换行合并为空格，行尾两个空格或 `\` 为硬换行）、无序 / 有序列表（缩进嵌套）、
  * 围栏代码块（边框 + 语言标签；流式时未闭合的围栏按代码块渲染）、引用、分隔线、
  * 行内 `code` / **粗体** / *斜体* / ~~删除线~~ / [链接](url) / <自动链接> / 反斜杠转义。
- * 表格降级为等宽对齐文本（不换行、超宽截断）；不做语法高亮（§12.9）。
+ * 表格降级为等宽对齐文本（列间两个空格、首行粗体其下一条规则线、不换行、超宽截断）；不做语法高亮（§12.9）。
+ *
+ * 配色（终端界面视觉设计 v1 §3.3）：h1 / h2 `accent` 粗体，h3+ 粗体；行内代码 `code`；链接文字 `link`
+ * 加下划线、URL 以 ` (url)` `dim` 追加；列表符号 `muted`；代码块全宽、边框 `border`、语言标签 `dim`、
+ * 正文 `text`；引用 `▎` + `muted` 斜体。字形（圆点、框线、竖条）取 `theme.glyphs`。
  *
  * 缓存：按块缓存渲染结果（键 = 宽度 + 块源文本），流式追加时只有末块重新渲染；解析也是增量的
  * （`Markdown.append` 只从尾部可能变化的块重新解析）。
@@ -208,8 +212,8 @@ export function renderInline(text, theme) {
                 const url = link[2];
                 out +=
                     link[1] === url || url === ""
-                        ? theme.underline(label || url)
-                        : theme.underline(label) + theme.fg("dim", ` (${url})`);
+                        ? theme.fg("link", theme.underline(label || url))
+                        : theme.fg("link", theme.underline(label)) + theme.fg("dim", ` (${url})`);
                 i += link[0].length;
                 continue;
             }
@@ -217,7 +221,7 @@ export function renderInline(text, theme) {
         if (ch === "<") {
             const auto = /^<((?:https?|mailto):[^>\s]+)>/.exec(text.slice(i));
             if (auto) {
-                out += theme.underline(auto[1]);
+                out += theme.fg("link", theme.underline(auto[1]));
                 i += auto[0].length;
                 continue;
             }
@@ -263,17 +267,19 @@ export function renderBlock(block, width, theme) {
     switch (block.kind) {
         case "heading": {
             const text = renderInline(block.text, theme);
-            const styled = block.level <= 2 ? theme.fg("accent", theme.bold(text)) : theme.bold(text);
+            const styled = block.level <= 2
+                ? theme.fg("accent", theme.bold(text))
+                : theme.fg("text", theme.bold(text));
             return wrapTextWithAnsi(styled, width);
         }
         case "paragraph":
             return wrapTextWithAnsi(renderInline(block.text, theme), width);
         case "hr":
-            return [theme.fg("border", "─".repeat(Math.max(1, width)))];
+            return [theme.fg("border", theme.glyphs.rule.repeat(Math.max(1, width)))];
         case "quote": {
-            const bar = theme.fg("border", "│ ");
-            const inner = wrapTextWithAnsi(theme.italic(renderInline(block.text, theme)), width - 2);
-            return inner.map((line) => bar + line);
+            const bar = theme.fg("border", theme.glyphs.card) + " ";
+            const body = theme.fg("muted", theme.italic(renderInline(block.text, theme)));
+            return wrapTextWithAnsi(body, Math.max(1, width - 2)).map((line) => bar + line);
         }
         case "list":
             return renderList(block.items, width, theme);
@@ -283,15 +289,24 @@ export function renderBlock(block, width, theme) {
             return renderTable(block.rows, width, theme);
     }
 }
-const BULLETS = ["•", "◦", "▪"];
 function renderList(items, width, theme) {
     const lines = [];
+    const bullets = theme.glyphs.bullets;
+    /** 各层的正文起始列与无序层数（嵌套项对齐父项正文，圆点按无序层数换）。 */
+    const columns = [];
+    const unordered = [];
     for (const item of items) {
-        const indent = "  ".repeat(item.depth);
+        const depth = Math.min(item.depth, columns.length);
+        const indent = depth === 0 ? 0 : columns[depth - 1];
         const ordered = /\d/.test(item.marker);
-        const bullet = ordered ? item.marker : BULLETS[item.depth % BULLETS.length];
-        const head = indent + theme.fg("accent", bullet) + " ";
+        const level = (depth === 0 ? 0 : unordered[depth - 1]) + (ordered ? 0 : 1);
+        const bullet = ordered ? item.marker : bullets[(level - 1) % bullets.length];
+        const head = " ".repeat(indent) + theme.fg("muted", bullet) + " ";
         const headWidth = visibleWidth(head);
+        columns.length = depth;
+        unordered.length = depth;
+        columns.push(headWidth);
+        unordered.push(level);
         const body = wrapTextWithAnsi(renderInline(item.text, theme), Math.max(1, width - headWidth));
         body.forEach((line, index) => {
             lines.push((index === 0 ? head : " ".repeat(headWidth)) + line);
@@ -304,18 +319,21 @@ function renderCode(lang, body, width, theme) {
     if (width < 8)
         return code.map((line) => truncateToWidth(line, width));
     const inner = width - 4;
+    const g = theme.glyphs.box;
     const border = (s) => theme.fg("border", s);
     const label = lang === "" ? "" : truncateToWidth(` ${lang} `, inner - 1);
-    const top = border("╭─") +
+    const top = border(g.topLeft + g.horizontal) +
         theme.fg("dim", label) +
-        border("─".repeat(width - 3 - visibleWidth(label)) + "╮");
+        border(g.horizontal.repeat(width - 3 - visibleWidth(label)) + g.topRight);
     const lines = [top];
     for (const line of code) {
         for (const piece of wrapCode(line, inner)) {
-            lines.push(border("│ ") + padToWidth(theme.fg("code", piece), inner) + border(" │"));
+            lines.push(border(g.vertical + " ") +
+                padToWidth(theme.fg("text", piece), inner) +
+                border(" " + g.vertical));
         }
     }
-    lines.push(border("╰" + "─".repeat(width - 2) + "╯"));
+    lines.push(border(g.bottomLeft + g.horizontal.repeat(width - 2) + g.bottomRight));
     return lines;
 }
 /** 代码按列硬断行（不按词），空行保留。 */
@@ -345,12 +363,18 @@ function renderTable(rows, width, theme) {
     for (const row of rendered) {
         row.forEach((cell, c) => (widths[c] = Math.max(widths[c], visibleWidth(cell))));
     }
-    const sep = theme.fg("border", " │ ");
-    return rendered.map((row, r) => {
+    const lines = [];
+    rendered.forEach((row, r) => {
         const cells = widths.map((w, c) => padToWidth(row[c] ?? "", w));
-        const line = cells.join(sep).replace(/\s+$/, "");
-        return truncateToWidth(r === 0 && rows.length > 1 ? theme.bold(line) : line, width);
+        const line = cells.join("  ").replace(/\s+$/, "");
+        const header = r === 0 && rows.length > 1;
+        lines.push(truncateToWidth(header ? theme.bold(line) : line, width));
+        if (header) {
+            const total = widths.reduce((sum, w) => sum + w, 0) + 2 * Math.max(0, cols - 1);
+            lines.push(theme.fg("border", theme.glyphs.rule.repeat(Math.max(1, Math.min(total, width)))));
+        }
     });
+    return lines;
 }
 export class Markdown {
     text;

package/dist/tui/components/meter.d.ts

@@ -4,7 +4,7 @@
  * - `value` 是 0–1 的比例（越界夹紧）；undefined 显示 `—`，格子全空；
  * - 阈值着色（需要 theme）：≥ `dangerAt`（缺省 0.9）error，≥ `warnAt`（缺省 0.7）warning，否则 success；
  *   空格子 dim；
- * - 宽度不够时先去掉格子，只剩「标签 百分比」，再不够就截断。
+ * - 宽度不够时先去掉格子，只剩「标签 百分比」，再不够就截断；格子字形取 `theme.glyphs`（ASCII `# .`）。
  */
 import type { Component, SemanticColor, Theme } from "../component.js";
 export interface MeterOptions {
@@ -15,8 +15,8 @@ export interface MeterOptions {
     dangerAt?: number;
     theme?: Theme;
 }
-export declare const METER_FULL = "\u25AE";
-export declare const METER_EMPTY = "\u25AF";
+export declare const METER_FULL: string;
+export declare const METER_EMPTY: string;
 export declare class Meter implements Component {
     private value;
     private readonly options;

package/dist/tui/components/meter.js

@@ -4,11 +4,13 @@
  * - `value` 是 0–1 的比例（越界夹紧）；undefined 显示 `—`，格子全空；
  * - 阈值着色（需要 theme）：≥ `dangerAt`（缺省 0.9）error，≥ `warnAt`（缺省 0.7）warning，否则 success；
  *   空格子 dim；
- * - 宽度不够时先去掉格子，只剩「标签 百分比」，再不够就截断。
+ * - 宽度不够时先去掉格子，只剩「标签 百分比」，再不够就截断；格子字形取 `theme.glyphs`（ASCII `# .`）。
  */
 import { truncateToWidth, visibleWidth } from "../ansi.js";
-export const METER_FULL = "▮";
-export const METER_EMPTY = "▯";
+import { levelColor } from "../theme.js";
+import { UNICODE_GLYPHS } from "../glyphs.js";
+export const METER_FULL = UNICODE_GLYPHS.meterFull;
+export const METER_EMPTY = UNICODE_GLYPHS.meterEmpty;
 export class Meter {
     value;
     options;
@@ -21,12 +23,11 @@ export class Meter {
     }
     /** 当前阈值档位对应的语义色。 */
     level() {
-        const v = this.value ?? 0;
-        if (v >= (this.options.dangerAt ?? 0.9))
-            return "error";
-        if (v >= (this.options.warnAt ?? 0.7))
-            return "warning";
-        return "success";
+        const { warnAt, dangerAt } = this.options;
+        return levelColor(this.value ?? 0, {
+            ...(warnAt !== undefined ? { warnAt } : {}),
+            ...(dangerAt !== undefined ? { dangerAt } : {}),
+        });
     }
     render(width) {
         const { theme, label, cells = 10 } = this.options;
@@ -35,8 +36,9 @@ export class Meter {
         const color = (c, text) => (theme ? theme.fg(c, text) : text);
         const head = label === undefined || label === "" ? "" : `${label} `;
         const filled = ratio === undefined ? 0 : Math.round(ratio * cells);
-        const bar = color(this.level(), METER_FULL.repeat(filled)) +
-            color("dim", METER_EMPTY.repeat(cells - filled));
+        const glyphs = theme?.glyphs ?? UNICODE_GLYPHS;
+        const bar = color(this.level(), glyphs.meterFull.repeat(filled)) +
+            color("dim", glyphs.meterEmpty.repeat(cells - filled));
         const tail = color(ratio === undefined ? "dim" : this.level(), percent);
         const full = `${head}${bar} ${tail}`;
         if (visibleWidth(full) <= width)

package/dist/tui/components/select-list.d.ts

@@ -4,8 +4,15 @@
  * 键位走 `tui.select.*`：上下移动（循环）、翻页、确认（Enter / Tab）、取消（Esc / Ctrl+C）。
  * `filterable` 时可打印字符追加到过滤词、退格删除；过滤为大小写不敏感的分词子串匹配
  * （每个词都要出现在 label / value / group / description 之一中）。
+ *
+ * `badge` 靠右显示（如 `Default`、`Recommended`）；`numberKeys` 时右侧标 1–9，按数字直接选中并确认；
+ * `stacked` 时说明换到标签下一行（缩进、暗色），适合「名字 + 一行说明」的短列表。
+ *
+ * 终端界面视觉设计 v1：选中行 `›` + `selection` 底色（< 256 色退化为 accent 粗体，stacked 时两行都上）；
+ * `currentValue` 的项标 `✓`；`footer` 是列表下的一行按键提示（dim），`showCount` 时前面带 `(i/n)`
+ * （缺省只在超出一屏时带）；过滤框提示符 `›`。字形取 `theme.glyphs`。
  */
-import type { Component, Focusable, Theme } from "../component.js";
+import type { Component, Focusable, SemanticColor, Theme } from "../component.js";
 import { type Keybindings } from "../keybindings.js";
 export interface SelectItem {
     value: string;
@@ -13,6 +20,10 @@ export interface SelectItem {
     description?: string;
     /** 相邻项 group 不同时插入分组标题行。 */
     group?: string;
+    /** 靠右的徽标文字。 */
+    badge?: string;
+    /** 徽标颜色，缺省 accent。 */
+    badgeColor?: SemanticColor;
 }
 export interface SelectListOptions {
     /** 一屏最多显示的条目数，缺省 10。 */
@@ -21,6 +32,16 @@ export interface SelectListOptions {
     keybindings?: Keybindings;
     filterable?: boolean;
     emptyText?: string;
+    /** 右侧标序号，按 1–9 直接选中并确认（不与 filterable 同用）。 */
+    numberKeys?: boolean;
+    /** 说明放在标签下一行。 */
+    stacked?: boolean;
+    /** 列表下的按键提示行（dim）。 */
+    footer?: string;
+    /** 提示行前带 `(i/n)`；缺省只在超出一屏时带。 */
+    showCount?: boolean;
+    /** 当前值：该项标签前标 `✓`（其余项留同宽空白）。 */
+    currentValue?: string;
     onSelect?(item: SelectItem): void;
     onCancel?(): void;
     onSelectionChange?(item: SelectItem | undefined): void;
@@ -48,6 +69,7 @@ export declare class SelectList implements Component, Focusable {
     selectValue(value: string): boolean;
     moveSelection(delta: number, wrap?: boolean): void;
     handleInput(data: string): void;
+    private get glyphs();
     render(width: number): string[];
     invalidate(): void;
     private renderItem;