@plumeai/plugin-sdk 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wJiaaa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/plume-plugin.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * plume-plugin：新建、检查、构建、安装 Plume 插件。随 Plume 应用发，应用启动时生成 `~/.plume/bin/plume-plugin`，
+ * 用 Plume 自己的运行时跑这个文件，插件作者的机器上不用装 Node 和 npm。
+ *
+ *   plume-plugin init <目录> [--name 插件名] [--display 市场里的名字]
+ *   plume-plugin check [目录]              类型检查和插件规则（公开接口、样式、文案），缺省当前目录
+ *   plume-plugin build [目录]
+ *   plume-plugin install [目录] [--to 目录]  装进 ~/.plume/plugins，Plume 开着就当场加载
+ *   plume-plugin dev [目录] [--to 目录]      构建、装上，之后一改源码就重新来一遍
+ *   plume-plugin link [目录]               重新链到这份 SDK（Plume 挪了位置、npm 删了链接时）
+ */
+
+import { buildPlugin } from "../lib/build.mjs";
+import { checkPlugin } from "../lib/check.mjs";
+import { devPlugin } from "../lib/dev.mjs";
+import { initPlugin } from "../lib/init.mjs";
+import { installPlugin } from "../lib/install.mjs";
+import { linkSdk } from "../lib/link.mjs";
+
+const USAGE = `用法：
+  plume-plugin init <目录> [--name 插件名] [--display 市场里的名字]
+  plume-plugin check [目录]
+  plume-plugin build [目录]
+  plume-plugin install [目录] [--to 目录]
+  plume-plugin dev [目录] [--to 目录]
+  plume-plugin link [目录]`;
+
+const [command, ...rest] = process.argv.slice(2);
+const positional = [];
+const flags = {};
+for (let index = 0; index < rest.length; index++) {
+	const arg = rest[index];
+	if (arg.startsWith("--")) flags[arg.slice(2)] = rest[++index];
+	else positional.push(arg);
+}
+const dir = positional[0] ?? process.cwd();
+
+try {
+	if (command === "init") {
+		if (!positional[0]) throw new Error(USAGE);
+		const created = initPlugin(positional[0], { name: flags.name, displayName: flags.display });
+		console.log(`✓ ${created.name} → ${created.dir}`);
+		console.log(
+			created.workspace
+				? "  在仓库根目录跑 pnpm install，再 pnpm build:plugins"
+				: "  写法见 .claude/skills/plume-plugin/SKILL.md；写完 plume-plugin check、plume-plugin dev",
+		);
+	} else if (command === "check") {
+		if (!(await checkPlugin(dir))) process.exitCode = 1;
+		else console.log("✓ 检查通过");
+	} else if (command === "build") {
+		console.log(`✓ ${await buildPlugin(dir)}`);
+	} else if (command === "install") {
+		console.log(`✓ 装到 ${installPlugin(dir, flags.to)}；Plume 开着的话已经加载`);
+	} else if (command === "dev") {
+		devPlugin(dir, { root: flags.to });
+		console.log("盯着 src/、package.json、README.md，改了就重新构建、装上；Ctrl+C 结束");
+	} else if (command === "link") {
+		linkSdk(dir);
+		console.log("✓ 已链到这份 SDK");
+	} else {
+		console.log(USAGE);
+		if (command && command !== "help" && command !== "--help") process.exitCode = 1;
+	}
+} catch (error) {
+	// esbuild 的报错它自己已经打过了。
+	if (!error?.errors) console.error(`✗ ${error instanceof Error ? error.message : String(error)}`);
+	process.exitCode = 1;
+}

package/dist/client/styles/src/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 共用的 Tailwind 类名组合：控件、卡片、代码、几种文字。产品界面、@plume/ui 的组件、插件的界面入口都从这里取，
+ * 改一处外观各处一起变。只用 theme.css 里的 token。
+ *
+ * 产品的 Tailwind 扫描这个包，这里写到的类一定会生成：第三方插件自己写的 Tailwind 类扫不到，用这里导出的组合可以。
+ * 只在一个页面用一次的布局（栅格、窗口顶行、页面边距）写在用的地方，不放进来。
+ */
+export declare const text: {
+    /** 次要说明：路径、状态、空状态。 */
+    faint: string;
+    error: string;
+    link: string;
+};
+/** 单行输入框和下拉框：无描边的一块 card 底，悬停、聚焦时深一档。高度只有 control 这一档。 */
+export declare const field = "h-control min-w-0 rounded-field bg-card px-4 text-label text-ink outline-none transition-colors placeholder:text-ink-faint hover:bg-card-hover focus:bg-card-hover";
+/** 包住输入框的 label：上面一行小字，下面是控件。 */
+export declare const fieldLabel = "flex flex-col gap-1.5 text-caption font-medium text-ink-muted";
+/** 多行输入框：没有框，放进自己画框的容器里（主输入框那种），外观由容器出。 */
+export declare const textarea = "min-w-0 resize-none bg-transparent text-body text-ink outline-none placeholder:text-ink-faint";
+type ButtonVariant = "primary" | "ghost" | "subtle" | "soft" | "danger";
+/**
+ * 按钮：五种外观、三档高度。焦点环是全局的（见渲染进程的 styles.css）；按下不缩放，底色深一档。
+ * 组件见 @plume/ui 的 Button，一般不直接拼这些。
+ */
+export declare const button: {
+    /** 禁用时不关掉指针事件：悬停提示要能解释它为什么不能按。 */
+    base: string;
+    /** md 32 是默认，对话框和表单底部的按钮；sm 26 给面板里的行；xs 20 给跟在一行小字后面的动作，圆角随之降到 6px。 */
+    size: {
+        md: string;
+        sm: string;
+        xs: string;
+    };
+    /** 只有图标时是正方形，图标居中；有字时字从左边起。 */
+    square: {
+        md: string;
+        sm: string;
+        xs: string;
+    };
+    pad: {
+        md: string;
+        sm: string;
+        xs: string;
+    };
+    variant: {
+        /** 一处只有一个，要按的那个：前景色压在底色上，不引入新的颜色也读得出是实心的。 */
+        primary: string;
+        /** 描边，平常的按钮，放在 primary 旁边。 */
+        ghost: string;
+        /** 没有描边，一排动作不想在面板上画出格子时用。 */
+        subtle: string;
+        /** 有底没描边：放在 primary 旁边、指针没过来之前就要读得出是按钮的一排选择。 */
+        soft: string;
+        /** 破坏性操作。只在悬停时上色：一排红按钮没人会读。 */
+        danger: string;
+    };
+    /** 一组选择里选中的那个：悬停态一直保持。只有 ghost 和 subtle 有。 */
+    pressed: Partial<Record<ButtonVariant, string>>;
+    /** 忙碌：和 disabled 分开，读起来是“在做”，不是“不能按”。宽度不变。 */
+    loading: string;
+};
+/** 图标按钮：平时是淡的字色，悬停才有底。按下底色深一档，不缩放。组件见 @plume/ui 的 IconButton。 */
+export declare const iconButton: {
+    /** 禁用时不关掉指针事件：`explainDisabled` 要靠悬停提示说明为什么不能按。 */
+    base: string;
+    /**
+     * xs 20 是标题行和一行小字的高度，圆角随之降到 6px。composer 跟着主输入框工具栏的控件边长走，
+     * 那个尺寸变了，这一排仍然是一行。
+     */
+    size: {
+        xs: string;
+        sm: string;
+        md: string;
+        composer: string;
+    };
+    tone: {
+        default: string;
+        danger: string;
+    };
+    /** 开着的开关，比如“区分大小写”。 */
+    active: string;
+    /** 一排里现在值得按的那个：满色的字，不是实心按钮。 */
+    emphasis: string;
+};
+export declare const card: {
+    frame: string;
+    head: string;
+    title: string;
+    subtitle: string;
+    status: string;
+    body: string;
+    /** 按语气换边框和标题行的底色。 */
+    tone: {
+        default: {
+            frame: string;
+            head: string;
+        };
+        error: {
+            frame: string;
+            head: string;
+        };
+        warning: {
+            frame: string;
+            head: string;
+        };
+    };
+};
+/** 卡片底部一行：左边是说明，右边是按钮。 */
+export declare const actions: {
+    row: string;
+    note: string;
+};
+export declare const code: {
+    block: string;
+    diff: string;
+    diffLine: string;
+    diffKind: {
+        same: string;
+        add: string;
+        remove: string;
+    };
+};
+export {};

package/dist/client/ui/src/avatar/AgentAvatar.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 一个智能体的脸：一块有颜色的形状，一双会眨的眼睛。
+ *
+ * 表情就是状态。面板里一排子智能体，谁在干活、谁在排队、谁做完了、谁出了事，从眼睛就读得
+ * 出来，不用每张脸旁边再挂一个字：
+ *
+ *   idle     睁着眼，时不时眨一下
+ *   working  上下轻轻颠着，眼睛左右扫——像在翻东西
+ *   waiting  眯着眼、褪了色，还没轮到它
+ *   done     眯成两道弯，满意了
+ *   failed   叉叉眼
+ *   stopped  闭着眼，被人叫停了
+ *
+ * 眨眼不用 CSS 的无限循环：那样哪怕一屏二十张脸都在屏幕外，动画时钟也一直在走。这里每张脸
+ * 自己排下一次眨眼的时间，看不见就跳过——两次眨眼之间什么都不跑。
+ */
+import { type Avatar } from "../lib/agent-avatar.ts";
+import type { DispatchState } from "../lib/dispatches.ts";
+export type AvatarMood = "idle" | DispatchState;
+export interface AgentAvatarProps {
+    avatar: Avatar;
+    /** 像素边长。 */
+    size?: number;
+    mood?: AvatarMood;
+    /** 右下角的小圆点：在跑是强调色、会一圈圈往外扩；出错是红的。 */
+    badge?: "running" | "failed" | null;
+    /**
+     * 悬停时眼睛跟着指针、身子弹一下。默认开。
+     *
+     * `host` 是往上找的那个容器：一整行的任何地方悬停都算，而不是非得对准这 20 像素。
+     */
+    interactive?: boolean;
+    host?: string;
+    /** 名字，决定眨眼的节奏——七张脸不该踩着同一个拍子。 */
+    seed?: string;
+    /** 默认是装饰：名字总在旁边写着。单独出现、没有字陪着的时候才给它一个名字。 */
+    label?: string;
+    /** 换一个值就蹦一下——刚保存好、刚换了脸，给它一个「是我」的回应。 */
+    cheer?: string | number | null;
+    className?: string;
+}
+export declare function AgentAvatar({ avatar, size, mood, badge, interactive, host, seed, label, cheer, className, }: AgentAvatarProps): import("react").JSX.Element;

package/dist/client/ui/src/avatar/AvatarPile.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 一摞脸：派出去不止一个时，叠在一起说「有好几个」。
+ *
+ * 和 `AvatarStack` 是两件事。那一排并排摆开，每张脸都看得清表情，适合「这一批都是谁」的场合；
+ * 这一摞叠着放，占地方小，说的是「这里有好几个，点开看」——放在一行字旁边、一个切换器上这类挤的地方。
+ * 表情仍然在：在跑的还在颠，只是被邻居盖住半张脸。
+ *
+ * 叠放有先后：后一张压在前一张上面，像一张一张往右放下去的牌，最后放下的那张完整露出来，「+N」
+ * 是最后一张。反过来（前一张压后一张）时，「+2」的加号被它左边那张盖住，读出来像「-2」，一摞
+ * 牌也像是从右往左倒着放的。
+ *
+ * 每张脸垫一枚圆底，叠起来才分得清谁是谁：形状各不相同的脸直接叠，三角压着云朵，读起来是一团
+ * 色块。被压住的那枚在上一枚的位置被挖掉，不是被涂盖，所以无论底下是什么，都透不出下面那张脸
+ * （`@plume/styles` 的 `ui/motion.css`）。指针进来的时候这一摞往右松开一点，像一叠牌被拨开。
+ */
+import type { Avatar } from "../lib/agent-avatar.ts";
+import { type AvatarMood } from "./AgentAvatar.tsx";
+export interface PileFace {
+    key: string;
+    avatar: Avatar;
+    mood?: AvatarMood;
+    seed: string;
+}
+export declare function AvatarPile({ faces, size, max, focus, className, }: {
+    faces: PileFace[];
+    size?: number;
+    max?: number;
+    /**
+     * 要完整露出来的那一张（面板顶上：正在看的那个）。
+     *
+     * 它排在露出来的那几张的最后——也就是最上面，紧挨着旁边写它名字的标题。放不下的时候先让出别人的
+     * 位置，它自己一定在。
+     */
+    focus?: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/client/ui/src/avatar/AvatarStack.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 一排小脸：这一批派出去的是谁、各自在干什么。
+ *
+ * 并排而不是叠着：叠起来的头像组说的是「有这么些人」，而这里每张脸自己有话说——谁在颠着干活、
+ * 谁眯着眼在排队、谁已经交差——被邻居盖住半张脸，表情就读不出来了。
+ *
+ * 放不下的收成一个「+N」，数字本身就是提示：想看全的点开面板。
+ */
+import type { Avatar } from "../lib/agent-avatar.ts";
+import { type AvatarMood } from "./AgentAvatar.tsx";
+export interface StackFace {
+    key: string;
+    avatar: Avatar;
+    mood?: AvatarMood;
+    /** 名字，决定眨眼的节奏。 */
+    seed: string;
+    /** 悬停时的那句话，同时是读屏念的名字。 */
+    tip: string;
+    onClick?: () => void;
+}
+export declare function AvatarStack({ faces, size, max, className }: {
+    faces: StackFace[];
+    size?: number;
+    max?: number;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/client/ui/src/avatar/art.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 每种形状的轮廓、脸在哪，和每种颜色的色值。
+ *
+ * 都画在 100×100 的格子里，身体大致占 10–90：留出边是给悬停时那一下「果冻」——压扁时会横着
+ * 胀出去一截，贴边画的话那一截会被裁掉。
+ *
+ * `face` 是两只眼睛的中点。不是每个形状都在正中：三角形的肚子在下半截，云的上沿全是鼓包，
+ * 眼睛放在几何中心会挤到边上去。整体都往右上偏一点，这张脸就是在「看着」右边的名字。
+ */
+import type { AvatarColor, AvatarShape } from "../lib/agent-avatar.ts";
+export interface ShapeArt {
+    d: string;
+    /** 只有水滴用：它是歪着的，歪在路径外面比把每个坐标都转一遍好改。 */
+    transform?: string;
+    face: {
+        x: number;
+        y: number;
+        gap: number;
+        scale: number;
+    };
+}
+export declare const SHAPE_ART: Record<AvatarShape, ShapeArt>;
+/**
+ * 眼睛的颜色，亮暗主题都是它：眼睛长在身体上，不长在窗口上，窗口底色换了它也不该跟着换。
+ * 和身体的颜色一样是这幅画自己的颜料，不是界面的 token，所以写在这里而不是样式表里。
+ */
+export declare const EYE_ART = "#141417";
+/**
+ * 色值是亮暗两种主题共用的一套中等明度：眼睛是深色的，身体太暗眼睛就看不见，太浅在白底上
+ * 就化开了。所以没有黑、没有灰、也没有嫩黄。
+ */
+export declare const COLOR_ART: Record<AvatarColor, string>;

package/dist/client/ui/src/fileIcon.d.ts

@@ -0,0 +1,33 @@
+import { type LucideIcon } from "./icons/index.ts";
+/**
+ * 一个文件在列表里长什么样。
+ *
+ * 颜色是重点。四十行一样灰的树得一行一行读；同一棵树有了 TypeScript 的蓝、JSON 的琥珀、Markdown 的
+ * 石板灰，一眼就读完了，因为眼睛先找到一组，再读名字。
+ *
+ * 色相跟着人们在编辑器里已经习惯的约定走——TS 蓝、JS 黄、Rust 锈色——而不是这里另起一套。没人认得
+ * 的配色只是装饰。
+ *
+ * 每种颜色都给两套主题各一个值：在白底上读得清的中间调，放到近黑的底上是浑的，反过来也一样。
+ */
+export interface FileLook {
+    Icon: LucideIcon;
+    /** 不走 Tailwind：行内设上，因为这些颜色不在主题推导的色阶里。 */
+    light: string;
+    dark: string;
+}
+export declare function lookFor(name: string, isDirectory: boolean, expanded?: boolean): FileLook;
+/** 取在当前主题下读得清的那个色值。深浅色跟随系统，和 theme.css 的 `prefers-color-scheme` 一致。 */
+export declare function iconColour(look: FileLook): string;
+/**
+ * 附件标记前面那枚图标该是什么：和文件树、回复里的文件链接同一张表。
+ *
+ * 只按门类画的话（`.plume-attachment-token[data-kind]` 那十几枚），`starship.toml`、`a.ts`、`x.json`
+ * 都落在「文本」那一档，是同一张灰纸，文件夹也只是另一种灰。表里认不出的（Word、表格、压缩包……）
+ * 返回 `null`，由门类图标接着画——那些本来就按常见配色挑过，比通用的灰纸强。
+ */
+export declare function tokenLook(name: string | undefined, kind?: string): FileLook | null;
+/** 画出来的那一枚。大小和位置由 `.plume-token-glyph` 定，和门类图标住同一个位置。 */
+export declare function TokenGlyph({ look }: {
+    look: FileLook;
+}): import("react").JSX.Element;

package/dist/client/ui/src/hooks/useCopied.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 复制键按下之后那个对钩：亮一会儿，自己变回去。
+ *
+ * 没有这一下，复制和没复制在屏幕上长得一模一样——剪贴板是个看不见的地方，人会忍不住再按一次。
+ * 各处各写一份的话，停留时长各不相同，有的卸载时不清定时器、有的压根不变回去。
+ *
+ * 只管对钩，不管怎么写剪贴板：渲染进程里有的走 `navigator.clipboard`，有的走主进程，而 `ui/`
+ * 不调 service。写成功了再 `mark`，写失败就别亮。
+ *
+ * `T` 是「亮的是哪一个」：同一页上有两枚复制键（链接和口令）时，亮的只该是按下的那枚。
+ */
+export declare function useCopied<T = true>(): {
+    copied: T | null;
+    mark: (which: T) => void;
+    reset: () => void;
+};

package/dist/client/ui/src/hooks/useLiveRefresh.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 让某样东西跟着正在干活的 agent 走，而不是等它这一轮结束。
+ *
+ * 每个汇报工作区状态的界面原本都是同一个形状——`running` 变回 false 时重读一次——也都有同一个毛病：
+ * 一轮花四分钟改文件，git 面板和改动计数显示的是四分钟前的样子。说明「积了多少没看过」的那个数，
+ * 反倒是窗口里最后一个知道的。
+ *
+ * 轮询，而不是从工具结果驱动，这是有意的。写文件的不只是工具：跑格式化的 `bash`、agent 写完又执行的
+ * 脚本、窗口旁边开着的编辑器。问一次 git 很便宜，而且对所有这些都对；一张「会写文件的工具」清单是
+ * 猜测，下次加一个工具它就过时了。
+ *
+ * 挂载时刷新一次，一轮结束时再刷新一次，所以最终状态不会落后一个轮询间隔；`touchWorkingTree` 时也刷新，
+ * 管两轮之间改动工作区的事。窗口回到前台时也刷新：在旁边终端里切分支、改文件时没有东西在轮询，而回来
+ * 正是人要看的时候。
+ */
+/**
+ * 工作区刚被不是一轮对话的东西改过——比如撤销把文件放了回去。
+ *
+ * 空闲时没有东西轮询，没有这个的话，改动计数会一直停在文件放回去之前的数，直到下一轮结束。
+ */
+export declare function touchWorkingTree(): void;
+export declare function useLiveRefresh(refresh: () => void | Promise<void>, running: boolean, ms?: number): void;

package/dist/client/ui/src/hooks/useNarrow.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 一个元素是不是窄到放不下两栏，按元素自己量。
+ *
+ * 面板里的内容没法问窗口自己有多宽——同一个组件既跑在 368px 的面板里，也跑在整列宽的正文里。
+ * 这里看的是它实际拿到的那个盒子。
+ *
+ * 第一次测量在节点一到就做，而不是留给 observer 的首次回调。那次回调在绘制之后才到，一个从 `false`
+ * 起步的组件会先画一帧错的布局——更糟的是，挂在这次翻转上的东西（比如列表/详情的重置）会在用户已经
+ * 动手之后晚一拍才触发，把刚做的操作撤掉。
+ *
+ * 用回调 ref，不用 ref 对象。这不是风格问题：`useRef` + `useLayoutEffect` 只在 effect 第一次运行时
+ * 挂 observer，一个先渲染了*别的*东西的组件——比如项目加载时的空状态——要么根本没挂上，要么挂到一个
+ * 随后被换掉的节点上。两种情况下 observer 都在看一个不存在的东西，标记停在碰巧的那个值上，一个开到
+ * 全屏的面板在一千像素宽时还在画堆叠布局。React 每次节点变化都会调用回调 ref，而节点变化正是要紧的那件事。
+ */
+export declare function useNarrow(threshold: number): [boolean, (node: HTMLDivElement | null) => void];

package/dist/client/ui/src/i18n/context.d.ts

@@ -0,0 +1,17 @@
+import { type UiLocale } from "./locales.ts";
+import type { MessageKey, ResolvedUiLocale } from "./messages/index.ts";
+import { type MessageVariables } from "./translate.ts";
+interface I18nValue {
+    locale: UiLocale;
+    resolvedLocale: ResolvedUiLocale;
+    t: (key: MessageKey, variables?: MessageVariables) => string;
+    formatNumber: (value: number, options?: Intl.NumberFormatOptions) => string;
+    formatDate: (value: Date | number, options?: Intl.DateTimeFormatOptions) => string;
+}
+export declare function I18nProvider({ locale, children }: {
+    locale: UiLocale;
+    children: React.ReactNode;
+}): import("react").JSX.Element;
+/** 当前界面语言和产品的文案目录。插件只用 `resolvedLocale` 选自己 `messages.ts` 里的那一份；`t()` 查的是产品的目录，插件的文字不在里面。 */
+export declare function useI18n(): I18nValue;
+export {};

package/dist/client/ui/src/i18n/index.d.ts

@@ -0,0 +1,2 @@
+export { useI18n } from "./context.tsx";
+export type { ResolvedUiLocale } from "./messages/index.ts";

package/dist/client/ui/src/i18n/list.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A list of things, punctuated the way the interface language punctuates one.
+ *
+ * Lists used to be joined with a hardcoded 「、」, so the English interface summed up a run of tool
+ * calls as "Read files merge.ts、Created files merge.test.ts". The separator belongs to the language,
+ * not to the sentence it sits in, which is why it is looked up here instead of written at each call.
+ *
+ * It comes from `Intl.ListFormat`, but not from `format()`: a conjunction style closes a list with
+ * "and" — "and" in English at `long` — and a summary line is a tally, not a sentence. `type: "unit"`
+ * has no conjunction, but CLDR joins Chinese units with nothing at all (the pattern behind
+ * 「3小时20分钟」), which would run the parts together. What is left is the literal between two middle
+ * items: the language's own list comma, which never carries a conjunction — 「、」 in Chinese,
+ * ", " in English.
+ *
+ * For items of one kind. Fields or clauses — a name and its description — take `common.comma`
+ * instead, because Chinese separates those with 「，」 rather than 「、」.
+ */
+import type { ResolvedUiLocale } from "./messages/index.ts";
+/** `items`, joined for the language the window is set to — or for `locale`, when a caller has one. */
+export declare function formatList(items: readonly string[], locale?: ResolvedUiLocale): string;

package/dist/client/ui/src/i18n/locales.d.ts

@@ -0,0 +1,10 @@
+import type { MessageKey, ResolvedUiLocale } from "./messages/index.ts";
+/** 界面语言的设置值：跟随系统，或者指定一种。 */
+export type UiLocale = "system" | ResolvedUiLocale;
+export interface LocaleOption {
+    value: UiLocale;
+    mark: string;
+    label: MessageKey;
+}
+export declare const LOCALE_OPTIONS: readonly LocaleOption[];
+export declare function resolveUiLocale(locale: UiLocale, languages: readonly string[]): ResolvedUiLocale;