@spzxg/cli-ui 0.3.1 → 0.6.0

package/src/core/types.ts

@@ -224,7 +224,8 @@ export type NodeEvent =
 /** center 实时流 chunk.events 里的一项。 */
 export type StreamItem =
   /** remote_task_id：一次性任务的流里才有（大任务里可能同时有几个节点对话）。 */
-  | { type: "transcript"; remote_task_id?: string; messages: Message[] | null; pending: PendingMessage[] | null; running: boolean | null }
+  /** older：快照只有最新一段时，更早还有几条（往上翻时经 history 分页取）。旧版中枢没有 = 全量。 */
+  | { type: "transcript"; remote_task_id?: string; messages: Message[] | null; pending: PendingMessage[] | null; running: boolean | null; older?: number }
   | { type: "node"; remote_task_id?: string; event: NodeEvent }
   | { type: "turn"; turn: CenterTurn }
   | { type: "job"; job: { id: string; status: JobStatus; closed_reason?: string | null; node_id: string | null } }
@@ -258,6 +259,13 @@ export interface BatchStreamTask {
   last_error: string | null;
   prompt?: string;
   opener_prompt?: string;
+  /**
+   * 对话式子任务（续派时 mode=conversation）：指定 ?task= 看它时，它和续派接着它聊的子任务算一个对话——
+   * 这条是其中最新的；conversation_remote_task_id 是它们共用的节点对话，queued 是还没派发的消息。旧版中枢没有。
+   */
+  conversation?: boolean;
+  conversation_remote_task_id?: string | null;
+  queued?: Array<{ id: string; prompt: string; created_at?: string }>;
 }
 
 /** 一次性任务（含续派，mode 不是 conversation）的实时流首个事件：没有轮次，只有子任务。 */
@@ -361,8 +369,8 @@ export interface BoardInfo {
   remote_task_id?: string;
   node?: { id: string; health: string };
   files: boolean;
-  /** 节点开了浏览器功能。 */
-  browser: boolean;
+  /** 节点开了浏览器功能。null = 这次没探测出来（节点慢 / 暂时连不上），照常显示浏览器页签。 */
+  browser: boolean | null;
 }
 
 export interface FileEntry {
@@ -374,10 +382,14 @@ export interface FileEntry {
   mtime: number;
 }
 
-export interface DirListing { type: "dir"; path: string; entries: FileEntry[]; truncated: boolean }
+export interface DirListing { type: "dir"; path: string; entries: FileEntry[]; truncated: boolean; /** 目录里的条目总数（新版节点给）。 */ total?: number }
 export interface FileInfo { type: "file"; path: string; name: string; size: number; mtime: number; contentType: string; inline: boolean }
 
-export interface DiffFile { path: string; status: string; additions: number; deletions: number; binary: boolean; patch: string; truncated?: boolean }
+export interface DiffFile {
+  path: string; status: string; additions: number; deletions: number; binary: boolean; patch: string; truncated?: boolean;
+  /** 改动太多，这个文件的 diff 没有带上（节点对整个 diff 有总量上限）；文件本身照常可以打开。 */
+  omitted?: boolean;
+}
 /** Operator 的 /api/tasks/:id/diff（经 center 原样转发）。 */
 export interface DiffResult {
   isolated?: boolean;
@@ -388,6 +400,8 @@ export interface DiffResult {
   isDirty?: boolean;
   ahead?: number;
   alreadyMerged?: boolean;
+  /** 因为总量上限没带 diff 的文件数。 */
+  patchesOmitted?: number;
   error?: string;
   /** 有的节点只给一整段 unified diff。 */
   diff?: string;
@@ -413,4 +427,12 @@ export interface BrowserStatus {
 export type BrowserMessage =
   | { type: "frame"; data: string; metadata?: { deviceWidth: number; deviceHeight: number } }
   | { type: "page"; url?: string; title?: string }
-  | { type: "error"; message?: string };
+  | { type: "error"; message?: string }
+  /** 按了复制 / 剪切：选中的文字（只发给按键的人），写进本机剪贴板。 */
+  | { type: "clipboard"; text: string }
+  /** 网页弹出了 alert / confirm / prompt（画面里看不到，单独显示）。 */
+  | { type: "dialog"; dialogType: "alert" | "confirm" | "prompt" | "beforeunload"; message: string; defaultPrompt?: string }
+  | { type: "dialog_closed" };
+
+/** 浏览器实时连接（GET /browser/live）的画面连接状况。 */
+export type BrowserFramesState = { state: "idle" | "connecting" | "live" | "retrying"; detail?: string };

package/src/elements.tsx

@@ -10,8 +10,12 @@
  *   <cli-board group="a"></cli-board>      （右侧看板：文件 / 改动 / 浏览器；对话里点文件会在这里打开）
  *   <cli-file-preview job-id="job_x" path="outputs/报告.md"></cli-file-preview>   （单独的文件预览 + 下载）
  *   <cli-browser job-id="job_x"></cli-browser>                                  （单独的浏览器实时画面）
+ *   <cli-split storage-key="a"> <cli-msglist …/> <cli-chat …/> <cli-board …/> </cli-split>
+ *                                    （可拖动分栏：子元素每个是一栏，栏之间左右拖动改宽度；panes='[{"size":300},{},{"size":"42%"}]'）
  *
- * 同一个 group 的元素共享一个仓库：列表点哪个，对话就显示哪个；不写 group 各自独立。
+ * 同一个 group 的元素共享一个仓库，切换时一起变：列表点哪个，对话和看板就显示哪个；不写 group 各自独立。
+ * 要一起切换，group 里的元素就不要写 job-id（写了的只看自己那个）；从外面打开某个对话，给任意一个元素写
+ * selected-id="job_x" 或 "job_x#task_y"（改它就一起切过去），选中变化在 cli-event 的 select 事件里。
  * 属性：base-url、token、line、namespace、group、job-id、task-id（对话任务里的哪个对话，"new" = 新开一个；对话 / 看板）、
  *       title、color、theme、context、read-only、
  *       tabs（看板页签，逗号分隔：files,changes,browser）、default-tab、file-open（对话：auto / board / modal / link）、
@@ -29,9 +33,15 @@ import { CliChat } from "./chat/CliChat.js";
 import { CliBoard, type BoardTab } from "./board/CliBoard.js";
 import { CliBrowserView, CliFilePreview } from "./board/blocks.js";
 import { createCliStore, type CliStore } from "./core/store.js";
+import { convKey } from "./core/conversation.js";
+import type { CliWorkspace } from "./board/workspace.js";
+import { attachSplit, type SplitHandle } from "./layout/split.js";
 
 const groups = new Map<string, CliStore>();
 
+// 服务端渲染（Next.js 等）时没有 HTMLElement：模块照样能导入，defineCliElements() 在服务端什么都不做。
+const Base = (typeof HTMLElement === "undefined" ? class {} : HTMLElement) as typeof HTMLElement;
+
 function storeFor(el: HTMLElement): CliStore | undefined {
   const group = el.getAttribute("group");
   if (!group) return undefined;
@@ -45,7 +55,7 @@ function storeFor(el: HTMLElement): CliStore | undefined {
   return store;
 }
 
-const ATTRS = ["base-url", "token", "line", "namespace", "group", "job-id", "task-id", "title", "color", "theme", "context", "read-only", "config", "new-conversation", "tabs", "default-tab", "file-open", "path"];
+const ATTRS = ["base-url", "token", "line", "namespace", "group", "selected-id", "job-id", "task-id", "title", "color", "theme", "context", "read-only", "config", "new-conversation", "tabs", "default-tab", "file-open", "path", "no-quote", "hidden"];
 
 function jsonAttr(el: HTMLElement, name: string): object | undefined {
   const raw = el.getAttribute(name);
@@ -63,7 +73,7 @@ function storeOptions(el: HTMLElement) {
   };
 }
 
-abstract class CliElement extends HTMLElement {
+abstract class CliElement extends Base {
   static observedAttributes = ATTRS;
   private root: Root | null = null;
   private ownStore: CliStore | undefined;
@@ -78,9 +88,40 @@ abstract class CliElement extends HTMLElement {
     if (this.root) this.render();
   }
 
+  /** 这个元素用的仓库（同一个 group 的元素共用一个）。高级用法：store.on(...)、store.select(...)。 */
+  get store(): CliStore {
+    return storeFor(this) ?? (this.ownStore ??= createCliStore(storeOptions(this)));
+  }
+  /** 元素自己写的对话（job-id + task-id）；没写时 null（跟着这一组的选中走）。 */
+  private ownKey(): string | null {
+    const job = this.getAttribute("job-id");
+    if (!job) return null;
+    const task = this.getAttribute("task-id");
+    return task ? convKey(job, task) : job;
+  }
+  /**
+   * 工作区文件接口：列文件、读文件、下载、打包、当前打开的文件。不传 jobId = 这个元素看的对话（没写 job-id 时是这一组选中的）。
+   * 看板可以隐藏（<cli-board hidden>）或者干脆不放，接口照样能用。
+   */
+  workspace(jobId?: string): CliWorkspace {
+    return this.store.workspace(jobId ?? this.ownKey() ?? undefined);
+  }
+  /**
+   * 追加项目背景：下一条消息发出时一起带给智能体。opts.jobId 不传 = 这个元素看的对话（还没有对话时，随新对话的第一条消息带上）。
+   * 返回这条背景的 id（同一个 id 再追加会替换）。
+   */
+  appendContext(text: string, opts: { title?: string; id?: string; jobId?: string } = {}): string {
+    const key = opts.jobId ?? this.ownKey() ?? this.store.getState().selected;
+    return this.store.appendContext(key, text, { title: opts.title, id: opts.id });
+  }
+  /** 去掉还没发出的补充背景（不传 id = 全部）。 */
+  removeContext(id?: string, jobId?: string) {
+    this.store.removeContext(jobId ?? this.ownKey() ?? this.store.getState().selected, id);
+  }
+
   connectedCallback() {
-    // 缺省撑满父容器；组件自己内部滚动（宿主给定高度即可）。
-    this.style.display ||= "block";
+    // 缺省撑满父容器；组件自己内部滚动（宿主给定高度即可）。hidden：不显示、不连接（接口照样能用）。
+    this.syncHidden();
     this.style.height ||= "100%";
     this.style.minHeight ||= "0";
     this.root ??= createRoot(this);
@@ -90,10 +131,23 @@ abstract class CliElement extends HTMLElement {
     // 移动节点时会先断开再连上：推到下一轮再卸载。
     queueMicrotask(() => { if (!this.isConnected) { this.root?.unmount(); this.root = null; } });
   }
-  attributeChangedCallback() { if (this.root) this.render(); }
+  attributeChangedCallback() { this.syncHidden(); if (this.root) this.render(); }
+  private syncHidden() {
+    if (this.hasAttribute("hidden")) this.style.display = "none";
+    else if (!this.style.display || this.style.display === "none") this.style.display = "block";
+  }
 
+  private appliedSelection: string | null = null;
+  /** selected-id：这一组一起看哪个对话。属性变了才切（列表点击换了选中，不会被属性拉回去）。隐藏的元素也生效。 */
+  private applySelection() {
+    const selection = this.getAttribute("selected-id");
+    if (selection !== null && selection !== this.appliedSelection) {
+      this.appliedSelection = selection;
+      this.store.select(selection || null);
+    }
+  }
   protected common() {
-    const store = storeFor(this) ?? (this.ownStore ??= createCliStore(storeOptions(this)));
+    const store = this.store;
     return {
       store,
       title: this.getAttribute("title") ?? undefined,
@@ -108,7 +162,11 @@ abstract class CliElement extends HTMLElement {
     };
   }
   protected abstract element(): React.ReactNode;
-  private render() { this.root?.render(this.element()); }
+  // 隐藏的元素什么都不渲染：不轮询、不占连接；workspace() / appendContext() 照样能用。
+  private render() {
+    this.applySelection();
+    this.root?.render(this.hasAttribute("hidden") ? null : this.element());
+  }
 }
 
 class CliMsgListElement extends CliElement {
@@ -137,7 +195,9 @@ class CliBoardElement extends CliElement {
     // 结果事件只由 <cli-chat> 发（同上）；看板只发 cli-event。
     const { onTurnEnd: _a, onConversationEnd: _b, onCallback: _c, title: _t, color: _k, config: _g, ...common } = this.common();
     const taskId = this.getAttribute("task-id");
-    return <CliBoard {...common} {...(jobId !== null ? { jobId: jobId || null } : {})} {...(taskId ? { taskId } : {})} tabs={tabs?.length ? tabs : undefined} defaultTab={defaultTab} readOnly={this.hasAttribute("read-only")} />;
+    return <CliBoard {...common} {...(jobId !== null ? { jobId: jobId || null } : {})} {...(taskId ? { taskId } : {})} tabs={tabs?.length ? tabs : undefined} defaultTab={defaultTab} readOnly={this.hasAttribute("read-only")}
+      // 同一个 group 里有对话：看板里「引用到对话」带进那个对话的下一条消息；no-quote 关掉。
+      quoteToChat={this.hasAttribute("group") && !this.hasAttribute("no-quote")} />;
   }
 }
 
@@ -157,10 +217,54 @@ class CliBrowserElement extends CliElement {
   }
 }
 
+/** <cli-split>：可拖动分栏（规则见 layout/split.ts）。属性 panes（JSON，每栏 size / min / max）、storage-key（记住宽度）。 */
+class CliSplitElement extends Base {
+  static observedAttributes = ["panes", "storage-key"];
+  private handle: SplitHandle | null = null;
+  private options() {
+    let panes: unknown;
+    try { panes = JSON.parse(this.getAttribute("panes") ?? "null"); } catch { panes = null; }
+    return {
+      ...(Array.isArray(panes) ? { panes } : {}),
+      storageKey: this.getAttribute("storage-key") ?? undefined,
+      onResize: (sizes: (number | null)[]) => this.dispatchEvent(new CustomEvent("cli-resize", { detail: { sizes } })),
+    };
+  }
+  connectedCallback() {
+    this.style.height ||= "100%";
+    this.handle ??= attachSplit(this, this.options());
+  }
+  disconnectedCallback() {
+    queueMicrotask(() => { if (!this.isConnected) { this.handle?.destroy(); this.handle = null; } });
+  }
+  attributeChangedCallback() { this.handle?.update(this.options()); }
+}
+
 export function defineCliElements() {
+  if (typeof customElements === "undefined") return;
   if (!customElements.get("cli-msglist")) customElements.define("cli-msglist", CliMsgListElement);
   if (!customElements.get("cli-chat")) customElements.define("cli-chat", CliChatElement);
   if (!customElements.get("cli-board")) customElements.define("cli-board", CliBoardElement);
   if (!customElements.get("cli-file-preview")) customElements.define("cli-file-preview", CliFilePreviewElement);
   if (!customElements.get("cli-browser")) customElements.define("cli-browser", CliBrowserElement);
+  if (!customElements.get("cli-split")) customElements.define("cli-split", CliSplitElement);
+}
+
+/** 元素上给业务方用的方法（<cli-msglist> / <cli-chat> / <cli-board> / <cli-file-preview> / <cli-browser> 都有）。 */
+export interface CliElementApi extends HTMLElement {
+  readonly store: CliStore;
+  config: object | undefined;
+  workspace(jobId?: string): CliWorkspace;
+  appendContext(text: string, opts?: { title?: string; id?: string; jobId?: string }): string;
+  removeContext(id?: string, jobId?: string): void;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "cli-msglist": CliElementApi;
+    "cli-chat": CliElementApi;
+    "cli-board": CliElementApi;
+    "cli-file-preview": CliElementApi;
+    "cli-browser": CliElementApi;
+  }
 }

package/src/index.ts

@@ -5,6 +5,7 @@
  *   cli-chat     对话（CliChat）
  *   cli-board    右侧看板：工作区文件（预览 / 下载）、改动、任务浏览器（CliBoard）
  *                 其中两个核心也能单独用：CliFilePreview（文件预览 + 下载）、CliBrowserView（浏览器实时画面）
+ *   CliSplit     可拖动分栏：把上面几个横着排，栏之间左右拖动改宽度（Web Component：<cli-split>）
  *
  * 单独用：
  *   <CliChat baseUrl="/api/center" jobId="job_xxx" />
@@ -20,17 +21,21 @@
  */
 export { CliMsgList, type CliMsgListProps } from "./msglist/CliMsgList.js";
 export { CliChat, type CliChatProps } from "./chat/CliChat.js";
-export { CliBoard, type CliBoardProps, type BoardTab } from "./board/CliBoard.js";
+export { CliBoard, type CliBoardProps, type BoardTab, type BoardExtraTab } from "./board/CliBoard.js";
+export { downloadFolder, zipFolder, listFolder, FOLDER_MAX_FILES, FOLDER_MAX_BYTES, type FolderResult, type FolderZip, type FolderProgress } from "./board/folderDownload.js";
+export { createWorkspace, WORKSPACE_TEXT_MAX, WORKSPACE_LIST_MAX, WORKSPACE_FILE_MAX, type CliWorkspace, type BoardView } from "./board/workspace.js";
 export { CliFilePreview, CliBrowserView, type CliFilePreviewProps, type CliBrowserViewProps } from "./board/blocks.js";
 export { FileViewer, downloadFile, type FileViewerProps, type FileAction } from "./board/FileViewer.js";
 export { BrowserPane } from "./board/BrowserPane.js";
+export { CliSplit, type CliSplitProps } from "./layout/CliSplit.js";
+export { attachSplit, type SplitPane, type SplitOptions, type SplitHandle } from "./layout/split.js";
 export { CliCenterProvider, useCliStore, useCliState, type CliCenterProviderProps, type ResultHandlers } from "./core/provider.js";
 
 export {
   resolveChatConfig, resolveMsgListConfig, DEFAULT_CHAT_CONFIG, DEFAULT_MSGLIST_CONFIG,
   type CliChatConfig, type CliMsgListConfig, type ResolvedChatConfig, type ResolvedMsgListConfig,
 } from "./core/config.js";
-export { createCliStore, type CliStore, type CliStoreOptions, type CliState, type CliEvent, type JobEntry, type OpenTarget } from "./core/store.js";
+export { createCliStore, CONTEXT_ITEM_MAX, type CliStore, type CliStoreOptions, type CliState, type CliEvent, type JobEntry, type OpenTarget, type BoardRef, type ContextItem } from "./core/store.js";
 export { createCenterClient, CenterError, boardFileUrl, type CenterClient, type CenterClientOptions, type StreamHandlers, type BoardBackend, type ConversationBackend } from "./core/client.js";
 export { viewMessages, isRunning, runningTurn, convKey, parseConvKey, NEW_TASK, type ConvState } from "./core/conversation.js";
 export {

package/src/layout/CliSplit.tsx

@@ -0,0 +1,53 @@
+/**
+ * 可拖动分栏（React 版）。每个子元素是一栏，栏之间可以左右拖动改宽度（规则见 split.ts）。
+ *
+ *   <CliCenterProvider baseUrl="/api/center" namespace="strategy">
+ *     <CliSplit storageKey="strategy" panes={[{ size: 300, min: 220, max: 480 }, { min: 360 }, { size: "42%", min: 320 }]}>
+ *       <CliMsgList />
+ *       <CliChat />
+ *       <CliBoard />
+ *     </CliSplit>
+ *   </CliCenterProvider>
+ *
+ * 三个组件在同一个 Provider 里照常联动（列表选中 → 对话和看板跟着切；对话里点文件 → 看板打开），分栏只管宽度。
+ */
+import { Children, useEffect, useRef, type CSSProperties, type ReactNode } from "react";
+import { attachSplit, type SplitHandle, type SplitPane } from "./split.js";
+
+export type CliSplitProps = {
+  children: ReactNode;
+  /** 每栏的初始宽度 / 最小 / 最大。写了 size 的是定宽栏，没写的占剩余宽度。缺省：第一栏 300px、最后一栏 42%、中间占剩余。 */
+  panes?: SplitPane[];
+  /** 记住拖好的宽度（localStorage）。 */
+  storageKey?: string;
+  onResize?: (sizes: (number | null)[]) => void;
+  className?: string;
+  style?: CSSProperties;
+};
+
+const defaultPanes = (n: number): SplitPane[] =>
+  n <= 1 ? [{}] : n === 2 ? [{ size: 300, min: 220, max: 520 }, { min: 360 }]
+    : Array.from({ length: n }, (_, i) => (i === 0 ? { size: 300, min: 220, max: 520 } : i === n - 1 ? { size: "42%", min: 320 } : { min: 360 }));
+
+export function CliSplit({ children, panes, storageKey, onResize, className, style }: CliSplitProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const handle = useRef<SplitHandle | null>(null);
+  const items = Children.toArray(children).filter(Boolean);
+  const onResizeRef = useRef(onResize);
+  onResizeRef.current = onResize;
+  const options = { panes: panes ?? defaultPanes(items.length), storageKey, onResize: (s: (number | null)[]) => onResizeRef.current?.(s) };
+  const sig = JSON.stringify([options.panes, storageKey, items.length]);
+
+  useEffect(() => {
+    if (!ref.current) return;
+    handle.current = attachSplit(ref.current, options);
+    return () => { handle.current?.destroy(); handle.current = null; };
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => { handle.current?.update(options); }, [sig]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return (
+    <div ref={ref} className={`cli-split ${className ?? ""}`} style={style}>
+      {items.map((child, i) => <div key={(child as { key?: string | null }).key ?? i} className="cli-split-pane">{child}</div>)}
+    </div>
+  );
+}

package/src/layout/split.ts

@@ -0,0 +1,214 @@
+/**
+ * 可拖动分栏：把一个容器里横向排的几栏（列表 / 对话 / 看板，或宿主自己的栏）之间加上拖动条，左右拖改宽度。
+ * 不依赖 React：React 版 CliSplit 和 Web Component 版 <cli-split> 都用它。
+ *
+ *   attachSplit(container, { panes: [{ size: 300, min: 220, max: 480 }, { min: 360 }, { size: "42%", min: 320 }], storageKey: "strategy" })
+ *
+ * 规则：
+ *   · 写了 size 的栏是定宽（px 或百分比，百分比按容器宽度换算成 px）；没写 size 的栏占剩下的宽度（只能有一个，没有就是最后一栏）。
+ *   · 拖动条改它旁边定宽的那一栏；任何一栏都不会小于自己的 min，占剩余宽度的那栏也一样。
+ *   · 双击拖动条：那一栏回到初始宽度。键盘：拖动条能聚焦，←/→ 每次 16px（按住 Shift 64px）。
+ *   · 子元素根节点带 collapsed 类（cli-board 收起时）：那一栏变成 40px 窄条（--cli-split-collapsed），旁边的拖动条隐藏；展开后回到原来的宽度。
+ *   · 写了 storageKey：拖好的宽度记在 localStorage（cli-ui:split:<storageKey>），下次打开还是这个宽度。
+ *   · 窗口变窄时定宽栏按比例让出宽度，保证占剩余宽度的那栏不小于它的 min。
+ */
+export type SplitPane = { size?: number | `${number}%`; min?: number; max?: number };
+export type SplitOptions = {
+  panes?: SplitPane[];
+  storageKey?: string;
+  /** 拖完（松手 / 键盘 / 双击）后的各栏宽度，占剩余宽度的那栏是 null。 */
+  onResize?: (sizes: (number | null)[]) => void;
+};
+export type SplitHandle = { update: (options: SplitOptions) => void; reset: () => void; destroy: () => void };
+
+const DEFAULT_MIN = 160;
+const STEP = 16;
+
+export function attachSplit(container: HTMLElement, initial: SplitOptions = {}): SplitHandle {
+  let options = initial;
+  let sizes: (number | null)[] = [];
+  let gutters: HTMLElement[] = [];
+  let panes: HTMLElement[] = [];
+  let dragging = false;
+
+  container.classList.add("cli-split");
+
+  const key = () => (options.storageKey ? `cli-ui:split:${options.storageKey}` : null);
+  const load = (): (number | null)[] | null => {
+    const k = key();
+    if (!k) return null;
+    try { const v = JSON.parse(localStorage.getItem(k) ?? "null"); return Array.isArray(v) ? v : null; } catch { return null; }
+  };
+  const save = () => {
+    const k = key();
+    if (k) try { localStorage.setItem(k, JSON.stringify(sizes)); } catch { /* 存不下就不记 */ }
+  };
+
+  const spec = (i: number): SplitPane => options.panes?.[i] ?? {};
+  const flexIndex = () => {
+    const i = panes.findIndex((_, n) => spec(n).size === undefined);
+    return i >= 0 ? i : panes.length - 1;
+  };
+  const minOf = (i: number) => spec(i).min ?? DEFAULT_MIN;
+  const initialSize = (i: number): number | null => {
+    if (i === flexIndex()) return null;
+    const s = spec(i).size;
+    if (typeof s === "string") return Math.round((parseFloat(s) / 100) * (container.clientWidth || 1200));
+    return s ?? 320;
+  };
+  const isCollapsed = (pane: HTMLElement) => !!pane.firstElementChild?.classList.contains("collapsed");
+  const clamp = (i: number, w: number) => Math.round(Math.min(spec(i).max ?? Infinity, Math.max(minOf(i), w)));
+
+  /** 定宽栏放进容器：总宽超了就按比例收，给占剩余宽度的那栏留出它的 min。 */
+  function fitted(): (number | null)[] {
+    const total = container.clientWidth;
+    const flex = flexIndex();
+    const fixed = sizes.map((s, i) => (i === flex || isCollapsed(panes[i]) ? 0 : s ?? 0));
+    const collapsedW = panes.reduce((sum, p, i) => sum + (i !== flex && isCollapsed(p) ? p.getBoundingClientRect().width : 0), 0);
+    const room = total - minOf(flex) - collapsedW;
+    const sum = fixed.reduce((a, b) => a + b, 0);
+    if (!total || sum <= room) return sizes;
+    const ratio = Math.max(0, room) / sum;
+    return sizes.map((s, i) => (i === flex || s === null ? null : Math.max(minOf(i), Math.floor(s * ratio))));
+  }
+
+  function apply() {
+    const flex = flexIndex();
+    const shown = fitted();
+    panes.forEach((pane, i) => {
+      pane.classList.add("cli-split-pane");
+      if (i === flex) { pane.style.flex = "1 1 0"; pane.style.width = ""; pane.style.minWidth = `${minOf(i)}px`; return; }
+      // 收起的栏（cli-board 的窄条宽度是 100%，没有自身宽度）：固定窄条宽，宿主可用 --cli-split-collapsed 改。
+      if (isCollapsed(pane)) { pane.style.flex = "0 0 var(--cli-split-collapsed, 40px)"; pane.style.width = ""; pane.style.minWidth = ""; return; }
+      pane.style.flex = `0 0 ${shown[i]}px`;
+      pane.style.width = `${shown[i]}px`;
+      pane.style.minWidth = "0";
+    });
+    gutters.forEach((g, i) => {
+      const hidden = isCollapsed(panes[i]) || isCollapsed(panes[i + 1]);
+      g.hidden = hidden;
+      g.setAttribute("aria-valuenow", String(Math.round(panes[sideOf(i)]?.getBoundingClientRect().width ?? 0)));
+    });
+  }
+
+  /** 拖动条 i（在第 i 栏和第 i+1 栏之间）改的是哪一栏：左边定宽改左边，否则改右边。 */
+  const sideOf = (gutter: number) => (gutter === flexIndex() ? gutter + 1 : gutter);
+
+  function resize(gutter: number, dx: number) {
+    const target = sideOf(gutter);
+    const sign = target === gutter ? 1 : -1;
+    const flex = flexIndex();
+    const current = panes[target].getBoundingClientRect().width;
+    // 占剩余宽度的那栏不能被挤到 min 以下。
+    const flexW = panes[flex].getBoundingClientRect().width;
+    const grow = Math.min(sign * dx, flexW - minOf(flex));
+    sizes[target] = clamp(target, current + grow);
+    apply();
+  }
+
+  function finish() { save(); options.onResize?.([...sizes]); }
+
+  function makeGutter(index: number) {
+    const g = document.createElement("div");
+    g.className = "cli-split-gutter";
+    g.tabIndex = 0;
+    g.setAttribute("role", "separator");
+    g.setAttribute("aria-orientation", "vertical");
+    g.setAttribute("aria-label", "拖动调整宽度");
+    g.title = "拖动调整宽度，双击恢复";
+    g.addEventListener("pointerdown", (e) => {
+      if (e.button !== 0) return;
+      e.preventDefault();
+      g.setPointerCapture(e.pointerId);
+      dragging = true;
+      container.classList.add("cli-split-dragging");
+      let last = e.clientX;
+      const move = (ev: PointerEvent) => { const dx = ev.clientX - last; if (!dx) return; last = ev.clientX; resize(index, dx); };
+      const up = () => {
+        dragging = false;
+        container.classList.remove("cli-split-dragging");
+        g.removeEventListener("pointermove", move);
+        g.removeEventListener("pointerup", up);
+        g.removeEventListener("pointercancel", up);
+        finish();
+      };
+      g.addEventListener("pointermove", move);
+      g.addEventListener("pointerup", up);
+      g.addEventListener("pointercancel", up);
+    });
+    g.addEventListener("dblclick", () => {
+      const target = sideOf(index);
+      sizes[target] = initialSize(target);
+      apply();
+      finish();
+    });
+    g.addEventListener("keydown", (e) => {
+      if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
+      e.preventDefault();
+      resize(index, (e.key === "ArrowLeft" ? -1 : 1) * (e.shiftKey ? STEP * 4 : STEP));
+      finish();
+    });
+    return g;
+  }
+
+  /** 子元素变了（宿主增删栏）：重新找栏、重新插拖动条。 */
+  function rebuild() {
+    for (const g of gutters) g.remove();
+    panes = [...container.children].filter((c): c is HTMLElement => c instanceof HTMLElement && !c.classList.contains("cli-split-gutter"));
+    const saved = load();
+    const flex = flexIndex();
+    sizes = panes.map((_, i) => {
+      if (i === flex) return null;
+      const keep = sizes[i];
+      if (typeof keep === "number") return keep;
+      const s = saved && saved.length === panes.length ? saved[i] : null;
+      return typeof s === "number" ? clamp(i, s) : initialSize(i);
+    });
+    gutters = panes.slice(0, -1).map((_, i) => makeGutter(i));
+    gutters.forEach((g, i) => panes[i].after(g));
+    apply();
+  }
+
+  // 只看栏的增删、栏的根节点换了、根节点的 class 变了（收起 / 展开）；栏里面的内容（流式输出）不看，不然每个字都要重排。
+  const observer = new MutationObserver((records) => {
+    if (dragging) return;
+    const structural = records.some((r) => r.type === "childList" && r.target === container
+      && [...r.addedNodes, ...r.removedNodes].some((n) => !(n instanceof HTMLElement && n.classList.contains("cli-split-gutter"))));
+    observer.disconnect();
+    if (structural) rebuild(); else apply();
+    observe();
+  });
+  const observe = () => {
+    observer.observe(container, { childList: true });
+    for (const p of panes) {
+      observer.observe(p, { childList: true });
+      if (p.firstElementChild) observer.observe(p.firstElementChild, { attributes: true, attributeFilter: ["class"] });
+    }
+  };
+  const ro = typeof ResizeObserver !== "undefined" ? new ResizeObserver(() => { if (!dragging) apply(); }) : null;
+
+  rebuild();
+  observe();
+  ro?.observe(container);
+
+  return {
+    update(next) {
+      const keyChanged = next.storageKey !== options.storageKey;
+      options = next;
+      if (keyChanged) sizes = [];
+      observer.disconnect(); rebuild(); observe();
+    },
+    reset() {
+      sizes = panes.map((_, i) => initialSize(i));
+      apply();
+      finish();
+    },
+    destroy() {
+      observer.disconnect();
+      ro?.disconnect();
+      for (const g of gutters) g.remove();
+      for (const p of panes) { p.style.flex = ""; p.style.width = ""; p.style.minWidth = ""; p.classList.remove("cli-split-pane"); }
+      container.classList.remove("cli-split", "cli-split-dragging");
+    },
+  };
+}