@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/board/FilesPane.tsx

@@ -0,0 +1,262 @@
+// 工作区文件：面包屑 + 列表。目录点进去，文件点开预览；行尾可直接下载。
+// 列表随任务进展自动刷新（CliBoard 给 refreshKey），这次刷新里新出现 / 改过的文件标出来。
+import { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import type { BoardBackend } from "../core/client";
+import type { FileEntry } from "../core/types";
+import { Icon } from "../ui/icons";
+import { relTime } from "../ui/format";
+import { downloadFile } from "./fileOps";
+import { fmtSize } from "./fileKind";
+import { retainFileScope } from "./fileScope";
+import { downloadFolder, FAILED_LIST_NAME, type FolderProgress } from "./folderDownload";
+
+export interface FilesPaneProps {
+  backend: BoardBackend;
+  jobId: string;
+  dir: string;
+  onDir: (dir: string) => void;
+  onOpen: (entry: FileEntry) => void;
+  refreshKey: number;
+  /** 列表读到了（看板用来判断打开着的文件有没有更新）。 */
+  toolbarHost?: HTMLElement | null;
+  onListed?: (dir: string, entries: FileEntry[]) => void;
+}
+
+export function FilesPane({ backend, jobId, dir, onDir, onOpen, refreshKey, onListed, toolbarHost }: FilesPaneProps) {
+  const [entries, setEntries] = useState<FileEntry[] | null>(null);
+  const [truncated, setTruncated] = useState(false);
+  const [total, setTotal] = useState<number | undefined>(undefined);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [retry, setRetry] = useState(0);
+  const [nextCursor, setNextCursor] = useState<string | undefined>();
+  const [moreLoading, setMoreLoading] = useState(false);
+  const [scrollTop, setScrollTop] = useState(0);
+  const [viewport, setViewport] = useState(640);
+  const [inputDirectory, setInputDirectory] = useState<string | null>(null);
+  const inInputs = !!dir && (dir === inputDirectory || /\/(?:uploads|attachments)\/[^/]+\/?$/.test(dir));
+  useEffect(() => {
+    const controller = new AbortController(); setInputDirectory(null);
+    void backend.uploadDirectory?.(jobId, controller.signal).then(path => { if (!controller.signal.aborted) setInputDirectory(path); }, () => {});
+    return () => controller.abort();
+  }, [backend, jobId]);
+  const listRef = useRef<HTMLDivElement>(null);
+  const pageAbort = useRef<AbortController | null>(null);
+  const generation = useRef(0);
+  const entriesRef = useRef(entries); entriesRef.current = entries;
+  const rowHeight = 52;
+  const first = Math.min(Math.max(0, (entries?.length ?? 0) - 1), Math.max(0, Math.floor(scrollTop / rowHeight) - 4));
+  const end = Math.min(entries?.length ?? 0, first + Math.min(80, Math.ceil(viewport / rowHeight) + 8));
+  const visiblePaths = (entries ?? []).slice(first, end).filter(file => file.type === "file").map(file => file.path);
+  const scopeKey = JSON.stringify(visiblePaths);
+  useEffect(() => retainFileScope(backend, jobId, { dirs: [dir || "."], paths: JSON.parse(scopeKey) as string[], onDenied: message => { generation.current++; pageAbort.current?.abort(); setLoading(false); setMoreLoading(false); setEntries(null); setError(message || "工作区访问受限，请检查任务文件目录或访问权限"); } }), [backend, jobId, dir, scopeKey]);
+  useEffect(() => {
+    if (!listRef.current || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(([box]) => { if (box.contentRect.height) setViewport(box.contentRect.height); });
+    observer.observe(listRef.current); return () => observer.disconnect();
+  }, [!!entries]);
+  const page = (cursor: string | undefined, signal: AbortSignal) => backend.listFiles
+    ? backend.listFiles(jobId, dir || ".", { cursor, limit: 200, signal })
+    : backend.stat(jobId, dir || ".");
+  const loadMore = async () => {
+    if (!nextCursor || moreLoading || loading || !backend.listFiles) return;
+    const token = generation.current, ctl = new AbortController(); pageAbort.current = ctl;
+    setMoreLoading(true);
+    try {
+      const result = await page(nextCursor, ctl.signal);
+      if (ctl.signal.aborted || token !== generation.current || result.type !== "dir") return;
+      const previous = entriesRef.current ?? [], paths = new Set(previous.map(file => file.path));
+      const joined = [...previous, ...result.entries.filter(file => !paths.has(file.path))];
+      setEntries(joined); setNextCursor(result.nextCursor); setTruncated(result.truncated); setTotal(result.total);
+      onListedRef.current?.(dir, joined);
+    } catch (error) {
+      if (ctl.signal.aborted || token !== generation.current) return;
+      if ((error as { status?: number }).status === 409) { setRetry(value => value + 1); return; }
+      setError(error instanceof Error ? error.message : String(error));
+    } finally { if (token === generation.current) setMoreLoading(false); }
+  };
+  const crumbsRef = useRef<HTMLDivElement>(null);
+  // 这个目录上一次看到的 mtime：用来标「新」。第一次打开目录不标。
+  const seen = useRef<{ dir: string; mtimes: Map<string, number> | null }>({ dir, mtimes: null });
+  const [fresh, setFresh] = useState<Set<string>>(new Set());
+  const onListedRef = useRef(onListed);
+  onListedRef.current = onListed;
+  const onDirRef = useRef(onDir);
+  onDirRef.current = onDir;
+  // 打包下载文件夹：同一时间只打一个，可以取消。
+  const [zip, setZip] = useState<{ dir: string; progress: FolderProgress; abort: AbortController } | null>(null);
+  // 下载的结果 / 失败（和「同步失败」分开：下载出错不代表列表过期）。
+  const [notice, setNotice] = useState<{ text: string; err: boolean } | null>(null);
+  const zipAbort = useRef<AbortController | null>(null);
+  const downloadScope = useRef<object | null>({});
+  const zipDir = (target: string) => {
+    if (zipAbort.current) return;
+    const abort = new AbortController();
+    zipAbort.current = abort;
+    const current = () => zipAbort.current === abort && !abort.signal.aborted;
+    setNotice(null);
+    setZip({ dir: target, progress: { phase: "listing", files: 0, total: 0, bytes: 0 }, abort });
+    downloadFolder(backend, jobId, target, { signal: abort.signal, onProgress: (progress) => { if (current()) setZip((z) => (z && z.abort === abort ? { ...z, progress } : z)); } })
+      .then(({ files, failed, failedListName }) => {
+        if (current() && failed.length) setNotice({ err: true, text: `已打包 ${files} 个文件；${failed.length} 个没读到（${failed[0].reason}${failed.length > 1 ? " 等" : ""}），清单在压缩包里的 ${failedListName??FAILED_LIST_NAME}` });
+      })
+      .catch((err: unknown) => { if (current() && !(err instanceof DOMException && err.name === "AbortError")) setNotice({ err: true, text: `打包下载失败：${err instanceof Error ? err.message : String(err)}` }); })
+      .finally(() => { if (zipAbort.current === abort) { zipAbort.current = null; setZip(null); } });
+  };
+  const downloadOne = (path: string, size: number) => {
+    const scope = downloadScope.current;
+    setNotice(null);
+    void downloadFile(backend, jobId, path, size).catch((err: unknown) => { if (scope === downloadScope.current) setNotice({ err: true, text: `下载失败：${err instanceof Error ? err.message : String(err)}` }); });
+  };
+  useEffect(() => {
+    downloadScope.current = {};
+    setZip(null);
+    setNotice(null);
+    setEntries(null);
+    seen.current = { dir, mtimes: null };
+    setFresh(new Set());
+    return () => {
+      downloadScope.current = null;
+      zipAbort.current?.abort();
+      zipAbort.current = null;
+    };
+  }, [jobId, backend]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    let alive = true;
+    const ctl = new AbortController();
+    const token = ++generation.current; pageAbort.current?.abort(); pageAbort.current = ctl; setMoreLoading(false);
+    setLoading(true);
+    const sameDirectory = seen.current.dir === dir;
+    const wanted = sameDirectory ? Math.max(200, entriesRef.current?.length ?? 0) : 200;
+    if (!sameDirectory) { seen.current = { dir, mtimes: null }; setEntries(null); setFresh(new Set()); setScrollTop(0); if (listRef.current) listRef.current.scrollTop = 0; }
+    const reload = async () => {
+      let result = await page(undefined, ctl.signal);
+      if (result.type !== "dir") return result;
+      const combined = [...result.entries];
+      // Preserve only pages the user has already requested, never preload the directory.
+      while (backend.listFiles && result.nextCursor && combined.length < wanted && !ctl.signal.aborted) {
+        const next = await page(result.nextCursor, ctl.signal);
+        if (next.type !== "dir") break;
+        combined.push(...next.entries); result = next;
+      }
+      return { ...result, entries: combined };
+    };
+    reload().then((res) => {
+      if (!alive || ctl.signal.aborted || token !== generation.current) return;
+      setLoading(false);
+      if (res.type !== "dir") { setError("不是目录"); return; }
+      setError(null);
+      const prev = seen.current.mtimes;
+      if (prev) {
+        const changed = res.entries.filter((e) => e.type === "file" && prev.get(e.path) !== e.mtime).map((e) => e.path);
+        if (changed.length) setFresh((old) => new Set([...old, ...changed]));
+      }
+      seen.current.mtimes = new Map(res.entries.map((e) => [e.path, e.mtime]));
+      setEntries(res.entries);
+      setTruncated(res.truncated);
+      setTotal(res.total);
+      setNextCursor(res.nextCursor);
+      onListedRef.current?.(dir, res.entries);
+    }, (e: unknown) => {
+      if (!alive || ctl.signal.aborted || token !== generation.current) return;
+      setLoading(false);
+      if ((e as { status?: number }).status === 409) { setNextCursor(undefined); setEntries(null); entriesRef.current = null; setError("目录在加载时发生变化，请重新加载"); return; }
+      // 正在看的目录被删了（任务清理了输出）：回到上一级。
+      if (dir && (e as { status?: number }).status === 404) { onDirRef.current(inInputs ? "" : dir.split("/").slice(0, -1).join("/")); return; }
+      setError(e instanceof Error ? e.message : String(e));
+    });
+    return () => { alive = false; ctl.abort(); pageAbort.current?.abort(); };
+  }, [backend, jobId, dir, refreshKey, retry]);
+  useEffect(() => { if (crumbsRef.current) crumbsRef.current.scrollLeft = crumbsRef.current.scrollWidth; }, [dir, !!entries]);
+
+  const segs = inInputs ? ["输入文件"] : dir ? dir.split("/").filter(Boolean) : [];
+  const compact = toolbarHost !== undefined;
+  const toolbar = <>
+        {loading && entries && <span className="cli-files-sync" title="正在同步">同步中…</span>}
+        {entries && entries.length > 0 && !zip && (
+          <button className="cli-fv-icon" title={`把「${dir || "工作区"}」打包成 ZIP 下载`} aria-label={`打包下载 ${dir || "工作区"}`} onClick={() => zipDir(dir)}>{Icon.download()}</button>
+        )}
+  </>;
+  return (
+    <div className="cli-files">
+      {compact && toolbarHost && createPortal(toolbar, toolbarHost)}
+      {!compact && <div className="cli-crumbs">
+        <div className="cli-crumb-path" role="navigation" aria-label="工作区路径" ref={crumbsRef}>
+          <button className={`cli-crumb ${segs.length ? "" : "on"}`} title="工作区" aria-current={segs.length ? undefined : "location"} onClick={() => onDir("")}>{Icon.folder()}<span className="cli-crumb-name">工作区</span></button>
+          {segs.map((s, i) => (
+            <span key={i} className="cli-crumb-w">
+              <span className="cli-crumb-sep">/</span>
+              <button className={`cli-crumb ${i === segs.length - 1 ? "on" : ""}`} title={segs.slice(0, i + 1).join("/")} aria-current={i === segs.length - 1 ? "location" : undefined} onClick={() => onDir(inInputs ? dir : segs.slice(0, i + 1).join("/"))}><span className="cli-crumb-name">{s}</span></button>
+            </span>
+          ))}
+        </div>
+        {toolbar}
+
+      </div>}
+          {dir && (
+            <button className="cli-frow" title="返回上一级目录" onClick={() => onDir(inInputs ? "" : segs.slice(0, -1).join("/"))}>
+              <span className="cli-frow-ic">{Icon.folder()}</span><span className="cli-frow-name">{inInputs ? "返回工作区" : "返回上一级"}{compact && <small> · {inInputs ? "输入文件" : dir}</small>}</span>
+            </button>
+          )}
+      {!dir && inputDirectory && <button className="cli-frow" onClick={() => onDir(inputDirectory)} title="当前会话上传的文件">
+        <span className="cli-frow-ic">{Icon.folder()}</span><span className="cli-frow-name">输入文件</span><span className="cli-frow-meta">{Icon.chevRight()}</span>
+      </button>}
+      {zip && (
+        <div className="cli-fv-trunc cli-zip-bar">
+          {zip.progress.phase === "listing" ? `正在列出「${zip.dir || "工作区"}」里的文件…`
+            : zip.progress.phase === "reading" ? `正在读取 ${zip.progress.files} / ${zip.progress.total} 个文件（${fmtSize(zip.progress.bytes)}${zip.progress.totalBytes ? ` / ${fmtSize(zip.progress.totalBytes)}` : ""}）`
+              + (zip.progress.retrying ? ` · 网络不稳，正在重试 ${zip.progress.retrying.split("/").pop()}` : "")
+              + (zip.progress.failed ? ` · ${zip.progress.failed} 个没读到` : "") + "…"
+              : "正在打包…"}
+          {zip.progress.phase === "reading" && zip.progress.totalBytes ? (
+            <span className="cli-zip-meter"><span style={{ width: `${Math.min(100, (zip.progress.bytes / Math.max(1, zip.progress.totalBytes)) * 100)}%` }} /></span>
+          ) : null}
+          <button className="cli-fv-btn" onClick={() => zip.abort.abort()}>取消</button>
+        </div>
+      )}
+      {notice && (
+        <div className={`cli-fv-trunc ${notice.err ? "cli-files-err" : ""}`}>{notice.text}
+          <button className="cli-fv-btn" onClick={() => setNotice(null)}>知道了</button>
+        </div>
+      )}
+      {error && entries && <div className="cli-fv-trunc" role="alert">同步失败：{error}。已保留上次读到的列表。
+        <button className="cli-fv-btn" disabled={loading} onClick={() => setRetry(value => value + 1)}>{loading ? "重试中…" : "重新加载"}</button>
+      </div>}
+      {error && !entries ? (
+        <div className="cli-fv-note err" role="alert">{error}<br /><button className="cli-fv-btn" disabled={loading} onClick={() => setRetry(value => value + 1)}>{loading ? "重试中…" : "重新加载文件"}</button></div>
+      ) : !entries ? (
+        <div className="cli-fv-note">读取文件…</div>
+      ) : entries.length === 0 ? (
+        <div className="cli-fv-note">{inInputs ? "还没有上传文件。" : dir ? "这个目录是空的。" : inputDirectory ? "任务生成的文件会出现在这里。" : "工作区里还没有文件。任务生成的文件会出现在这里。"}</div>
+      ) : (
+        <div className="cli-files-list" role="list" ref={listRef} style={{ overflowAnchor: "none" }} onScroll={event => {
+          const el = event.currentTarget; setScrollTop(el.scrollTop);
+          if (el.scrollHeight - el.scrollTop - el.clientHeight < 300) void loadMore();
+        }}>
+          {first > 0 && <div aria-hidden="true" style={{ height: first * rowHeight }} />}
+          {entries.slice(first, end).map((e, index) => (
+            <div key={e.path} className={`cli-frow ${e.type} ${fresh.has(e.path) ? "fresh" : ""}`} role="listitem" aria-posinset={first + index + 1} aria-setsize={total ?? entries.length} style={{ height: rowHeight }}>
+              <button className="cli-frow-main" onClick={() => (e.type === "dir" ? onDir(e.path) : onOpen(e))} title={e.path}>
+                <span className="cli-frow-ic">{e.type === "dir" ? Icon.folder() : Icon.doc()}</span>
+                <span className="cli-frow-body">
+                  <span className="cli-frow-title"><span className="cli-frow-name">{e.name}</span>{fresh.has(e.path) && <span className="cli-frow-new">有更新</span>}</span>
+                  <span className="cli-frow-meta">{e.type === "file" ? `${fmtSize(e.size)} · ` : ""}{relTime(e.mtime)}</span>
+                </span>
+              </button>
+              {e.type === "file" ? (
+                <button className="cli-frow-dl" title="下载" aria-label={`下载 ${e.name}`} onClick={() => downloadOne(e.path, e.size)}>{Icon.download()}</button>
+              ) : (
+                <button className="cli-frow-dl" title="打包成 ZIP 下载" aria-label={`打包下载 ${e.name}`} disabled={!!zip} onClick={() => zipDir(e.path)}>{Icon.download()}</button>
+              )}
+            </div>
+          ))}
+          {end < entries.length && <div aria-hidden="true" style={{ height: (entries.length - end) * rowHeight }} />}
+          {nextCursor && <div className="cli-fv-trunc"><button className="cli-fv-btn" disabled={loading || moreLoading} onClick={() => void loadMore()}>{moreLoading ? "加载中…" : "加载更多"}</button><span>已加载 {entries.length.toLocaleString()}{total ? ` / ${total.toLocaleString()}` : ""} 项</span></div>}
+          {truncated && !nextCursor && <div className="cli-fv-trunc">文件太多{total ? `（共 ${total.toLocaleString()} 个）` : ""}，只列出前 {entries.length.toLocaleString()} 个。</div>}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/board/HtmlReadingPreview.tsx

@@ -0,0 +1,52 @@
+import { useEffect, useState, type RefObject } from "react";
+import { readHtmlSections, type HtmlReadingBlock, type HtmlReadingResult } from "./htmlReading";
+
+function ReadingBlock({ block }: { block: HtmlReadingBlock }) {
+  if (block.kind === "heading") return block.level === 1 ? <h1>{block.text}</h1> : block.level === 2 ? <h2>{block.text}</h2> : <h3>{block.text}</h3>;
+  if (block.kind === "code") return <pre className="cli-fv-pre"><code>{block.text}</code></pre>;
+  if (block.kind === "table-row") return <p className="cli-html-row">{block.text}</p>;
+  if (block.kind === "image") return <p className="cli-html-image">{block.text || "图片"}</p>;
+  return <p>{block.text}</p>;
+}
+
+/** A bounded reading page: original markup, CSS, scripts and image URLs never enter the DOM. */
+export function HtmlReadingPreview({ text, complete, version, onBusyChange, abortRef, scrollRef, onMore, onSource, onOriginal }: {
+  text: string; complete: boolean; version: string;
+  onBusyChange: (busy: boolean) => void;
+  abortRef: RefObject<AbortController | null>; scrollRef: RefObject<HTMLDivElement | null>;
+  onMore?: () => void; onSource: () => void; onOriginal: () => void;
+}) {
+  const [state, setState] = useState<{ text: string; version: string; page: number; result: HtmlReadingResult } | null>(null);
+  const [error, setError] = useState<string | null>(null), [page, setPage] = useState(0);
+  useEffect(() => {
+    const ctl = new AbortController(); abortRef.current = ctl;
+    setError(null); onBusyChange(true);
+    const cancel = () => onBusyChange(false); ctl.signal.addEventListener("abort", cancel, { once: true });
+    void readHtmlSections(text, { signal: ctl.signal, eof: complete, page }).then(result => {
+      if (!ctl.signal.aborted) setState({ text, version, page, result });
+    }, (error: unknown) => { if (!ctl.signal.aborted) setError(error instanceof Error ? error.message : String(error)); })
+      .finally(() => { if (!ctl.signal.aborted) onBusyChange(false); });
+    return () => { ctl.signal.removeEventListener("abort", cancel); ctl.abort(); onBusyChange(false); };
+  }, [text, complete, version, page, onBusyChange, abortRef]);
+  const result = state?.text === text && state.version === version && state.page === page ? state.result : null;
+  const current = result?.pageOffset ?? 0;
+  const move = (next: number) => { setPage(next); if (scrollRef.current) scrollRef.current.scrollTop = 0; };
+  if (error) return <div className="cli-fv-note" role="alert">此文档暂时无法整理为阅读内容。<button className="cli-fv-btn" onClick={onSource}>查看源文件</button></div>;
+  if (!result) return null;
+  return <>
+    <div className="cli-fv-trunc cli-html-reading-note">分段阅读 · 已简化原件布局、图片及交互，文件内容不变。</div>
+    <div className="cli-fv-md md cli-html-reading">
+      {result.pages[0]?.blocks.map((block, index) => <ReadingBlock key={index} block={block} />)}
+      {!result.pages.length && <div className="cli-fv-note">这一部分尚无可显示的正文，可能包含样式、图片或脚本。</div>}
+    </div>
+    {result.limited && <div className="cli-fv-trunc" role="status">{result.reason === "depth" ? "文档嵌套层级过多" : "此部分含超长标记或密集空结构"}，已显示可读取部分。<button className="cli-fv-btn" onClick={onSource}>查看源文件</button><button className="cli-fv-btn" onClick={onOriginal}>原样预览</button></div>}
+    <nav className="cli-fv-trunc cli-html-page-nav" aria-label="HTML阅读翻页">
+      <button className="cli-fv-btn" disabled={!current} onClick={() => move(current - 1)}>上一页</button>
+      <span>第 {current + 1} / {Math.max(1, result.pageCount)} 页{!complete ? "（已读取部分）" : ""}</span>
+      <button className="cli-fv-btn" disabled={current + 1 >= result.pageCount && (!onMore || result.limited)} onClick={() => {
+        if (current + 1 < result.pageCount) move(current + 1);
+        else { setPage(current + 1); onMore?.(); }
+      }}>{current + 1 < result.pageCount ? "下一页" : onMore && !result.limited ? "继续读取" : "已到结尾"}</button>
+    </nav>
+  </>;
+}

package/src/board/MarkdownPreview.tsx

@@ -0,0 +1,134 @@
+import { Component, memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode, type RefObject } from "react";
+import { Markdown } from "../ui/Markdown";
+import { splitMarkdownParts, type MarkdownPart } from "./fileKind";
+
+/** Character and structure budgets both matter: a short table may contain thousands of cells. */
+export const MARKDOWN_PREVIEW_CHARS = 16 * 1024;
+type Schedule = (work: () => void) => () => void;
+
+function useRenderQueue(): Schedule {
+  const pending = useRef(new Map<object, () => void>()), timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const schedule = useCallback<Schedule>(work => {
+    const key = {}; pending.current.set(key, work);
+    const next = () => {
+      timer.current = undefined;
+      const first = pending.current.entries().next().value;
+      if (first) { pending.current.delete(first[0]); first[1](); }
+      // One render tree per turn, leaving input and painting a chance between trees.
+      if (pending.current.size) timer.current = setTimeout(next, 16);
+    };
+    if (timer.current === undefined) timer.current = setTimeout(next, 16);
+    return () => { pending.current.delete(key); if (!pending.current.size) { clearTimeout(timer.current); timer.current = undefined; } };
+  }, []);
+  useEffect(() => () => { clearTimeout(timer.current); pending.current.clear(); }, []);
+  return schedule;
+}
+
+class SegmentBoundary extends Component<{ source: string; children: ReactNode }, { failed: boolean }> {
+  state = { failed: false };
+  static getDerivedStateFromError() { return { failed: true }; }
+  componentDidUpdate(previous: { source: string }) { if (previous.source !== this.props.source && this.state.failed) this.setState({ failed: false }); }
+  render() {
+    return this.state.failed ? <>
+      <div className="cli-fv-trunc" role="status">此段格式无法渲染，已显示原文；其他内容可继续阅读。</div>
+      <pre className="cli-fv-pre">{this.props.source}</pre>
+    </> : this.props.children;
+  }
+}
+
+const RenderPart = memo(function RenderPart({ part }: { part: MarkdownPart }) {
+  if (part.plain) return <>
+    {part.simplified && <div className="cli-fv-trunc" role="status">{part.simplified}</div>}
+    <pre className="cli-fv-pre">{part.text}</pre>
+  </>;
+  if (part.code) return <>
+    <div className="cli-fv-trunc">{part.code.language || "代码"} · 分段显示</div>
+    <pre className="cli-fv-pre"><code>{part.text.slice(part.code.start - part.start, part.code.end - part.start)}</code></pre>
+  </>;
+  return <>
+    {part.prefix && <div className="cli-fv-trunc">表格续页 · 表头已重复</div>}
+    <Markdown highlight={false}>{(part.prefix ?? "") + part.text + (part.definitions ? `\n\n${part.definitions}` : "")}</Markdown>
+  </>;
+});
+
+function PreviewWindow({ part, index, scrollRef, schedule }: { part: MarkdownPart; index: number; scrollRef: RefObject<HTMLDivElement | null>; schedule: Schedule }) {
+  const host = useRef<HTMLDivElement>(null), height = useRef(Math.max(80, Math.ceil(part.text.length / 100) * 22));
+  const [visible, setVisible] = useState(typeof IntersectionObserver === "undefined" || index === 0);
+  const token = useMemo(() => ({}), [part.text, part.plain, part.prefix, part.definitions, part.simplified, part.code?.start, part.code?.end, part.code?.language]);
+  const [ready, setReady] = useState<object | null>(null);
+  useEffect(() => {
+    const node = host.current;
+    if (!node || typeof IntersectionObserver === "undefined") return;
+    const observer = new IntersectionObserver(([entry]) => {
+      if (!entry.isIntersecting && node.firstElementChild) height.current = node.getBoundingClientRect().height || height.current;
+      setVisible(entry.isIntersecting);
+    }, { root: scrollRef.current, rootMargin: "600px 0px" });
+    observer.observe(node); return () => observer.disconnect();
+  }, [scrollRef]);
+  useEffect(() => {
+    if (!visible) { setReady(null); return; }
+    return schedule(() => setReady(token));
+  }, [visible, token, schedule]);
+  const shown = visible && ready === token;
+  useLayoutEffect(() => { if (shown && host.current) height.current = host.current.getBoundingClientRect().height || height.current; }, [shown, token]);
+  return <div ref={host} data-source-start={part.start} data-source-end={part.end} style={shown ? undefined : { height: height.current }} aria-hidden={!visible || undefined} aria-busy={visible && !shown || undefined}>
+    {shown ? <SegmentBoundary source={part.text}><RenderPart part={part} /></SegmentBoundary> : visible && <div className="cli-fv-note" role="status">正在排版…</div>}
+  </div>;
+}
+
+/** Distant groups need one placeholder, not an observer and React tree for every fragment. */
+function PreviewGroup({ parts, index, scrollRef, schedule }: { parts: MarkdownPart[]; index: number; scrollRef: RefObject<HTMLDivElement | null>; schedule: Schedule }) {
+  const host = useRef<HTMLDivElement>(null), [visible, setVisible] = useState(index === 0);
+  const height = useRef(parts.reduce((total, part) => total + Math.max(80, Math.ceil(part.text.length / 100) * 22), 0));
+  useEffect(() => {
+    const node = host.current; if (!node) return;
+    const observer = new IntersectionObserver(([entry]) => {
+      if (!entry.isIntersecting && node.firstElementChild) height.current = node.getBoundingClientRect().height || height.current;
+      setVisible(entry.isIntersecting);
+    }, { root: scrollRef.current, rootMargin: "1000px 0px" });
+    observer.observe(node); return () => observer.disconnect();
+  }, [scrollRef]);
+  return <div ref={host} data-preview-group={index} style={visible ? undefined : { height: height.current }} aria-hidden={!visible || undefined}>
+    {visible && parts.map((part, index) => <PreviewWindow key={part.start} part={part} index={index} scrollRef={scrollRef} schedule={schedule} />)}
+  </div>;
+}
+
+function PreviewParts({ parts, scrollRef }: { parts: MarkdownPart[]; scrollRef: RefObject<HTMLDivElement | null> }) {
+  const schedule = useRenderQueue(), [page, setPage] = useState(0);
+  const paged = typeof IntersectionObserver === "undefined", currentPage = Math.min(page, Math.max(0, Math.ceil(parts.length / 2) - 1));
+  const groups = useMemo(() => { const result: MarkdownPart[][] = []; for (let index = 0; index < parts.length; index += 32) result.push(parts.slice(index, index + 32)); return result; }, [parts]);
+  return <>
+    {paged ? parts.slice(currentPage * 2, currentPage * 2 + 2).map((part, index) => <PreviewWindow key={part.start} part={part} index={index} scrollRef={scrollRef} schedule={schedule} />)
+      : groups.map((group, index) => <PreviewGroup key={group[0].start} parts={group} index={index} scrollRef={scrollRef} schedule={schedule} />)}
+    {paged && parts.length > 2 && <div className="cli-fv-trunc">
+      <button disabled={!currentPage} className="cli-fv-btn" onClick={() => setPage(currentPage - 1)}>上一部分</button>
+      <button disabled={(currentPage + 1) * 2 >= parts.length} className="cli-fv-btn" onClick={() => setPage(currentPage + 1)}>下一部分</button>
+    </div>}
+  </>;
+}
+
+export function MarkdownPreview({ text, scrollRef }: { text: string; scrollRef: RefObject<HTMLDivElement | null> }) {
+  const parts = useMemo(() => splitMarkdownParts(text, MARKDOWN_PREVIEW_CHARS, { preview: true }), [text]);
+  const first = parts[0];
+  // Ordinary small documents do not need scheduling or viewport placeholders.
+  const immediate = parts.length === 1 && !first.plain && !first.simplified
+    && text.length + (first.prefix?.length ?? 0) + (first.definitions?.length ?? 0) <= 4096
+    && (text.match(/[|*_\[\]<>`~]/g)?.length ?? 0) <= 400;
+  if (immediate) return <SegmentBoundary source={text}><RenderPart part={first} /></SegmentBoundary>;
+  return <PreviewParts parts={parts} scrollRef={scrollRef} />;
+}
+
+/** Source views use the same cancellable render queue and viewport bounds, without Markdown parsing. */
+export function BoundedTextPreview({ text, scrollRef }: { text: string; scrollRef: RefObject<HTMLDivElement | null> }) {
+  const parts = useMemo(() => {
+    const result: MarkdownPart[] = [];
+    for (let start = 0; start < text.length;) {
+      let end = Math.min(text.length, start + MARKDOWN_PREVIEW_CHARS);
+      if (end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1])) end--;
+      result.push({ text: text.slice(start, end), start, end, plain: true }); start = end;
+    }
+    return result;
+  }, [text]);
+  if (text.length <= MARKDOWN_PREVIEW_CHARS) return <pre className="cli-fv-pre">{text}</pre>;
+  return <PreviewParts parts={parts} scrollRef={scrollRef} />;
+}

package/src/board/PanelControls.tsx

@@ -0,0 +1,40 @@
+import { useState, type Ref } from 'react';
+import { Icon } from '../ui/icons';
+import { Popover } from '../ui/Popover';
+/** The same board can place its tabs in the chat header without duplicating its content. */
+export interface InlineBoardLayout {
+  tabsHost: HTMLElement | null;
+  active: boolean;
+  onActivate: () => void;
+  onChat: () => void;
+}
+export function PanelTab({ id, label, title, active, onSelect, onClose }: {
+  id: string; label: string; title?: string; active: boolean; onSelect: () => void; onClose: () => void;
+}) {
+  return <span className={`rail-tab rail-ftab ${active ? 'on' : ''}`} title={title ?? label} onClick={onSelect}>
+    <button className="rail-ftab-l" role="tab" aria-selected={active} aria-label={label} data-panel-id={id} onClick={event => { event.stopPropagation(); onSelect(); }}><span className="rail-ftab-text">{label}</span></button>
+    <button className="rail-ftab-x" aria-label={id.startsWith("file:") ? `关闭 ${label}` : `关闭${label}面板`} title={id === 'browser' ? '隐藏浏览器面板，浏览器任务继续运行' : id.startsWith('file:') ? '关闭文件标签，可从工作区重新打开' : `关闭${label}面板，可从添加模块重新打开`}
+      onClick={event => { event.stopPropagation(); onClose(); }}>{Icon.x()}</button>
+  </span>;
+}
+export function PanelControls({ available, open, label, onShow, onClose, toolbarRef, upload }: {
+  toolbarRef?: Ref<HTMLSpanElement>;
+  upload?: { onChoose: () => void; disabled?: boolean; hint?: string };
+  available: readonly string[]; open: readonly string[]; label: (id: string) => string;
+  onShow: (id: string) => void; onClose: (id: string) => void;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  return <div className="cli-panel-controls">
+    {toolbarRef && <span className="cli-board-content-actions" ref={toolbarRef} />}
+    <button className="rail-collapse" aria-label="管理看板模块" title="添加或关闭看板模块" aria-expanded={expanded} onClick={() => setExpanded(value => !value)}>{Icon.plus()}</button>
+    {expanded && <Popover onClose={() => setExpanded(false)}>
+      {upload && <button className="pop-item" disabled={upload.disabled} title={upload.hint}
+        onClick={() => { setExpanded(false); upload.onChoose(); }}>{Icon.clip()}<span>上传文件</span></button>}
+      <div className="pop-sec">看板模块 · 可独立打开或关闭</div>
+      {available.map(id => <button key={id} className="pop-item" aria-label={`${open.includes(id) ? '关闭' : '打开'}${label(id)}面板`} aria-pressed={open.includes(id)}
+        onClick={() => { if (open.includes(id)) onClose(id); else onShow(id); setExpanded(false); }}>
+        <span>{label(id)}</span>{open.includes(id) ? Icon.check() : Icon.plus()}
+      </button>)}
+    </Popover>}
+  </div>;
+}

package/src/board/blocks.tsx

@@ -0,0 +1,97 @@
+// 看板的两个核心，各自是一块独立的积木，放到哪里都能用：
+//
+//   <CliFilePreview jobId path />   任务工作区里一个文件的预览 + 下载（Markdown / 代码 / CSV / 图片 / PDF / HTML / Word）
+//   <CliBrowserView jobId />        任务浏览器的实时画面 + 接管 / 交还 / 打开 / 关闭
+//
+// 和别的组件一样：外面有 <CliCenterProvider> 就共用它（同一个对话只连一条流）；没有就用自己的连接参数
+// （baseUrl / token / line / headers）建一个。不给 jobId 时跟 Provider 的选中走。
+// 它们只依赖中枢的看板接口（/api/jobs/:id/files、/browser…），不依赖 cli-chat / cli-board。
+import { useState, type CSSProperties } from "react";
+import { CliErrorBoundary } from "../ui/ErrorBoundary";
+import type { CliEvent, CliStore, CliStoreOptions } from "../core/store";
+import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider } from "../core/provider";
+import { FileViewer, type FileAction } from "./FileViewer";
+import { BrowserPane } from "./BrowserPane";
+
+interface BlockProps extends CliStoreOptions {
+  /** 哪个对话（center 的 job_id）。不给就跟 Provider 的选中走。 */
+  jobId?: string | null;
+  theme?: "light" | "dark";
+  className?: string;
+  style?: CSSProperties;
+  store?: CliStore;
+  onEvent?: (event: CliEvent) => void;
+}
+
+export interface CliFilePreviewProps extends BlockProps {
+  /** 工作区里的相对路径（如 "outputs/报告.md"），或节点上的绝对路径。 */
+  path: string;
+  /** 预览里点了别的本地文件（Markdown 里的链接）。不给就在本组件里切换过去。 */
+  onOpenPath?: (path: string) => void;
+  /** 给了就显示关闭按钮。 */
+  onClose?: () => void;
+  /** 头部的自定义按钮。 */
+  actions?: FileAction[];
+  /** 变了就重读（宿主知道文件更新时递增）。 */
+  version?: number;
+  /** 不要头部（宿主自己做标题和按钮）。 */
+  bare?: boolean;
+}
+
+export function CliFilePreview(props: CliFilePreviewProps) {
+  const ctx = useCliStoreContext();
+  return <CliErrorBoundary component="cli-file-preview" theme={props.theme}>{withOwnProvider(props, <FilePreviewInner {...props} inProvider={!!ctx} />, !!ctx)}</CliErrorBoundary>;
+}
+
+function FilePreviewInner({ jobId: jobIdProp, path, onOpenPath, onClose, actions, version, bare, theme = "light", className, style, onEvent, inProvider }: CliFilePreviewProps & { inProvider: boolean }) {
+  useComponentEvents(onEvent, {}, inProvider);
+  const store = useCliStore();
+  const selected = useCliState((s) => s.selected);
+  const jobId = jobIdProp !== undefined ? jobIdProp : selected;
+  const [shown, setShown] = useShownPath(path);
+  const backend = store.client.board;
+  return (
+    <div className={`cli-ui cli-file-preview ${className ?? ""}`} data-theme={theme} style={style}>
+      {!backend ? <div className="cli-fv-note">当前后端不支持文件预览（需要任务中心的 /api/jobs/:id/files 接口）。</div>
+        : !jobId ? <div className="cli-fv-note">没有指定对话。</div>
+          : !shown ? <div className="cli-fv-note">没有指定文件。</div>
+            : <FileViewer key={`${jobId}:${shown}`} backend={backend} jobId={jobId} path={shown} version={version} actions={actions} onClose={onClose} bare={bare}
+                onOpenPath={onOpenPath ?? setShown} />}
+    </div>
+  );
+}
+
+export interface CliBrowserViewProps extends BlockProps {
+  /** 只看：不能打开 / 关闭 / 接管。 */
+  readOnly?: boolean;
+}
+
+export function CliBrowserView(props: CliBrowserViewProps) {
+  const ctx = useCliStoreContext();
+  return <CliErrorBoundary component="cli-browser" theme={props.theme}>{withOwnProvider(props, <BrowserViewInner {...props} inProvider={!!ctx} />, !!ctx)}</CliErrorBoundary>;
+}
+
+function BrowserViewInner({ jobId: jobIdProp, readOnly, theme = "light", className, style, onEvent, inProvider }: CliBrowserViewProps & { inProvider: boolean }) {
+  useComponentEvents(onEvent, {}, inProvider);
+  const store = useCliStore();
+  const selected = useCliState((s) => s.selected);
+  const jobId = jobIdProp !== undefined ? jobIdProp : selected;
+  const backend = store.client.board;
+  return (
+    <div className={`cli-ui cli-browser-view ${className ?? ""}`} data-theme={theme} style={style}>
+      {!backend ? <div className="cli-fv-note">当前后端不支持任务浏览器（需要任务中心的 /api/jobs/:id/browser 接口）。</div>
+        : !jobId ? <div className="cli-fv-note">没有指定对话。</div>
+          : <BrowserPane key={jobId} backend={backend} jobId={jobId} readOnly={readOnly} />}
+    </div>
+  );
+}
+
+/** 显示的路径：跟着 prop 走；预览里点了别的文件时在组件内切换，prop 变了再以 prop 为准。 */
+function useShownPath(path: string): [string, (p: string) => void] {
+  const [state, setState] = useState({ prop: path, shown: path });
+  if (state.prop !== path) {
+    setState({ prop: path, shown: path });
+    return [path, (p) => setState({ prop: path, shown: p })];
+  }
+  return [state.shown, (p) => setState((s) => ({ ...s, shown: p }))];
+}