@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/board/FileViewer.tsx

@@ -0,0 +1,721 @@
+// 文件预览：Markdown / 代码 / 文本 / CSV / 图片 / PDF / HTML（沙箱）/ Word，其余给下载。
+// 看板和对话里的弹窗共用。文件经 center 转发读取（浏览器不直连执行节点）。
+//
+// 远端、实时、超大文件：
+//   · HTML 使用经授权的不可变修订与持久块缓存重组；图片 / PDF / 显式下载保留直接文件地址。
+//   · Markdown 按需增加已加载范围并窗口渲染；其他文本可切到末尾。GBK 导出按 GB18030 解。
+//   · 文件在变（任务还在写）：看板递增 version 时重读；读的时候保留滚动位置，原本在最底下的继续贴着底（像 tail -f）。
+import { Fragment, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode, type RefObject } from "react";
+import { createPortal } from "react-dom";
+import { fileUrlFromBase, type BoardBackend } from "../core/client";
+import { Icon } from "../ui/icons";
+import { Popover } from "../ui/Popover";
+import { Markdown } from "../ui/Markdown";
+import { MarkdownPreview, BoundedTextPreview } from "./MarkdownPreview";
+import { HtmlReadingPreview } from "./HtmlReadingPreview";
+import { FileLinkContext, FileOpenContext } from "../ui/fileLinks";
+import { codeLang, fmtSize, parseCsv, previewKind, resolveRelative, type PreviewKind } from "./fileKind";
+import { loadText, refreshText, type LoadedText } from "./textLoad";
+import { decodeText } from "../core/textDecode";
+import { relTime } from "../ui/format";
+import { downloadFile, mimeOf, readBoundedBuffer, FileReadLimitError } from "./fileOps";
+import { bridgeDoc, frameToken, type FrameSelMessage } from "./frameQuote";
+import { syncFile } from "./fileSync";
+import { retainFileScope } from "./fileScope";
+import { isTaskUploadPath } from "../core/documentUpload";
+
+export { downloadFile };
+
+/** 看板 / 预览里给文件加的自定义操作（例如「在对话里引用」「发到工作协同」）。 */
+export interface FileAction {
+  label: string;
+  title?: string;
+  /** 只对某些文件显示。 */
+  when?: (file: { path: string; name: string }) => boolean;
+  onClick: (file: { path: string; name: string; url: string; downloadUrl: string }, jobId: string) => void;
+}
+
+// 原样预览保留完整排版；分段阅读按需加载，限制单次创建的 DOM。
+/** 文本（代码、日志、Markdown、CSV、HTML 源文件）一次最多读这么多；更大的看开头 / 末尾。 */
+export const TEXT_MAX = 32 * 1024 * 1024;
+/** HTML 预览（能选中引用）最多读这么多进来；更大的直接按地址打开（能看，不能选中引用）。 */
+export const HTML_QUOTE_MAX = 100 * 1024 * 1024;
+/** 代码高亮到这么大（约 1 MB/秒）；更大的按纯文本显示（照样能选中引用）。 */
+const HIGHLIGHT_MAX = 512 * 1024;
+const MARKDOWN_STEP = 512 * 1024;
+const nextTextLimit = (limit: number) => Math.min(HTML_QUOTE_MAX, limit + Math.min(limit, 8 * 1024 * 1024));
+/** 只能先 fetch 成 blob 时（中枢太旧）：超过这么大的图片 / PDF 不预览、不在浏览器里拼下载。 */
+const BLOB_PREVIEW_MAX = 100 * 1024 * 1024;
+/** Word 在浏览器里转换，太大的只给下载。 */
+const DOCX_PREVIEW_MAX = 50 * 1024 * 1024;
+
+/**
+ * 浏览器能直接打开的文件地址。directLinks（同源代理）时马上有；否则等中枢发的短期链接（pending = 还在换）；
+ * 中枢发不了（太旧）时 url 为 null、blob = true，调用方退回先 fetch 再显示。
+ */
+function useFileLinks(backend: BoardBackend, jobId: string, path: string, version: number, attempt: number, reloadKey: number | string | undefined, useBlocks = false): { url: ((path: string, download?: boolean) => string) | null; pending: boolean; blob: boolean } {
+  const [linkBase, setLinkBase] = useState<string | null | undefined>(undefined);
+  useEffect(() => {
+    if (useBlocks || backend.directLinks || !backend.fileLinkBase) return;
+    let alive = true, pending = false;
+    const check = () => {
+      if (!alive || pending) return;
+      pending = true;
+      void Promise.resolve().then(() => alive ? backend.fileLinkBase!(jobId) : null).then(
+        base => { if (alive) setLinkBase(old => base ?? old ?? null); },
+        () => { if (alive) setLinkBase(old => old ?? null); },
+      ).finally(() => { pending = false; });
+    };
+    const wake = () => { if (document.visibilityState === "visible") check(); };
+    void check();
+    document.addEventListener("visibilitychange", wake); window.addEventListener("online", wake);
+    return () => { alive = false; document.removeEventListener("visibilitychange", wake); window.removeEventListener("online", wake); };
+  }, [backend, jobId, path, version, attempt, reloadKey, useBlocks]);
+  return useMemo(() => {
+    if (useBlocks) return { url: null, pending: false, blob: true };
+    if (backend.directLinks) return { url: (path: string, download?: boolean) => backend.fileUrl(jobId, path, { download }), pending: false, blob: false };
+    if (!backend.fileLinkBase || linkBase === null) return { url: null, pending: false, blob: true };
+    if (linkBase === undefined) return { url: null, pending: true, blob: false };
+    return { url: (path: string, download?: boolean) => fileUrlFromBase(linkBase, path, download), pending: false, blob: false };
+  }, [backend, jobId, linkBase, useBlocks]);
+}
+
+const withVersion = (url: string, version: number, attempt = 0) => {
+  const q = [version ? `v=${version}` : "", attempt ? `r=${attempt}` : ""].filter(Boolean).join("&");
+  return q ? `${url}${url.includes("?") ? "&" : "?"}${q}` : url;
+};
+/** 读了这么久还没好：提示「网络较慢」，不让人以为卡死了。 */
+const SLOW_HINT_MS = 8_000;
+function useSlow(loading: boolean) {
+  const [slow, setSlow] = useState(false);
+  useEffect(() => {
+    setSlow(false);
+    if (!loading) return;
+    const t = setTimeout(() => setSlow(true), SLOW_HINT_MS);
+    return () => clearTimeout(t);
+  }, [loading]);
+  return slow;
+}
+
+/** 图片 / PDF / HTML 的地址：能直接用就用；只能 fetch 时先读成 blob（离开时释放），太大的不读。 */
+function useFileSrc(backend: BoardBackend, jobId: string, path: string, enabled: boolean, version: number, size: number | undefined, links: ReturnType<typeof useFileLinks>, attempt = 0) {
+  const [state, setState] = useState<{ url: string | null; error: string | null }>({ url: null, error: null });
+  const direct = enabled && links.url ? withVersion(links.url(path), version, attempt) : null;
+  useEffect(() => {
+    if (!enabled || !links.blob) return;
+    setState({ url: null, error: null });
+    if (size !== undefined && size > BLOB_PREVIEW_MAX) { setState({ url: null, error: `文件较大（${fmtSize(size)}），请下载后查看` }); return; }
+    let alive = true;
+    const ctl = new AbortController();
+    let objectUrl: string | null = null;
+    readBoundedBuffer(backend, jobId, path, BLOB_PREVIEW_MAX, {signal:ctl.signal}).then((buffer) => {
+      if (!alive) return;
+      objectUrl = URL.createObjectURL(new Blob([buffer], { type: mimeOf(path) }));
+      setState({ url: objectUrl, error: null });
+    }, (error: unknown) => { if (alive) setState({ url: null, error: error instanceof Error ? error.message : String(error) }); });
+    return () => { alive = false; ctl.abort(); if (objectUrl) URL.revokeObjectURL(objectUrl); };
+  }, [backend, jobId, path, enabled, version, links.blob, size, attempt]);
+  return direct ? { url: direct, error: null } : state;
+}
+
+type Loaded =
+  | ({ kind: "text" } & LoadedText)
+  | { kind: "docx"; html: string }
+  | { kind: "none" };
+
+export interface FileViewerProps {
+  backend: BoardBackend;
+  jobId: string;
+  path: string;
+  /** 服务端保留的上传原名；实际访问仍使用 path。 */
+  displayName?: string;
+  /** 文件信息（列表里已有的话省一次请求）。 */
+  size?: number;
+  mtime?: number;
+  /** 变了就重新读（看板在文件更新时递增）。 */
+  version?: number;
+  /** 明确的文件变更事件使内容重新读取，不能只按末尾重叠判断为追加。 */
+  reloadKey?: number | string;
+  /** 预览里点了别的本地文件（Markdown 里的链接）。 */
+  onOpenPath?: (path: string) => void;
+  onClose?: () => void;
+  /** 头部左侧额外内容（看板放「返回」按钮）。 */
+  lead?: ReactNode;
+  onBack?: () => void;
+  actions?: FileAction[];
+  /** 隐藏头部（宿主自己做）。 */
+  bare?: boolean;
+  /** 看板页签栏提供操作容器，避免重复标题行。 */
+  toolbarHost?: HTMLElement | null;
+  /** 给了就支持「选中文字 → 引用到对话」：在预览里选中一段文字时浮出按钮（Markdown / 代码 / 文本 / 表格 / HTML / Word，及各自的源文件）。 */
+  onQuoteText?: (text: string, context?: { revision: string }) => void;
+}
+
+/** 选中的文字超过这么多只带开头（引用是给智能体指位置的，不是搬运全文）。 */
+const QUOTE_SELECTION_MAX = 3_000;
+
+const viewerBackendIds=new WeakMap<BoardBackend,number>();let nextViewerBackendId=1;
+export function FileViewer(props:FileViewerProps) {
+  let id=viewerBackendIds.get(props.backend);if(id===undefined){id=nextViewerBackendId++;viewerBackendIds.set(props.backend,id);}
+  return <FileViewerInner key={JSON.stringify([id,props.jobId,props.path])} {...props}/>;
+}
+function FileViewerInner({ backend, jobId, path, displayName, size, mtime, version = 0, reloadKey, onOpenPath, onClose, lead, onBack, actions = [], bare, toolbarHost, onQuoteText }: FileViewerProps) {
+  const name = displayName || path.split("/").pop() || path;
+  const kind: PreviewKind = previewKind(path);
+  const [loaded, setLoaded] = useState<Loaded | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [downloadError, setDownloadError] = useState<string | null>(null);
+  const [copied, setCopied] = useState(false);
+  const [copying, setCopying] = useState(false);
+  const [copyError, setCopyError] = useState<string | null>(null);
+  const copiedTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [actionsOpen, setActionsOpen] = useState(false);
+  const moreRef = useRef<HTMLButtonElement>(null);
+  const [busy, setBusy] = useState(false);
+  const [mode, setMode] = useState<"preview" | "source">("preview");
+  const [htmlPresentation, setHtmlPresentation] = useState<"reading" | "original">("original");
+  const htmlReading = kind === "html" && mode === "preview" && htmlPresentation === "reading";
+  // 超大文本：看开头还是看末尾（日志看末尾）。
+  const [tail, setTail] = useState(false);
+  const progressiveText = !!backend.fileSync && (kind === "text" || kind === "code");
+  const [textLimit, setTextLimit] = useState(kind === "html" || backend.fileSync && (kind === "markdown" || progressiveText) ? MARKDOWN_STEP : TEXT_MAX);
+  const [syncing, setSyncing] = useState(false);
+  const [parsing, setParsing] = useState(false);
+  const [cancelled, setCancelled] = useState(false);
+  const sourceBusy = useCallback((value: boolean) => { setSyncing(value); if (value) setCancelled(false); }, []);
+  const readingBusy = useCallback((value: boolean) => { setParsing(value); if (value) setCancelled(false); }, []);
+  const revisionRef = useRef<string | undefined>(undefined);
+  const fileReadAbort = useRef<AbortController | null>(null);
+  const readingAbort = useRef<AbortController | null>(null);
+  const cancelRead = () => { fileReadAbort.current?.abort(); readingAbort.current?.abort(); setSyncing(false); setParsing(false); setCancelled(true); };
+  useEffect(() => retainFileScope(backend, jobId, { paths: [path], dirs: [], onDenied: message => {
+    fileReadAbort.current?.abort(); readingAbort.current?.abort(); revisionRef.current = undefined;
+    setLoaded(null); setHtmlDoc(null); setSyncing(false); setParsing(false); setError(message || "文件访问受限，请检查任务文件目录或访问权限");
+  } }), [backend, jobId, path]);
+  // 放大：盖住页面看（看板窄的时候看报告、表格、图片）。Esc 还原。
+  const [big, setBig] = useState(false);
+  const previousBig = useRef(big);
+  useLayoutEffect(() => {
+    if (previousBig.current !== big && toolbarHost !== undefined) moreRef.current?.focus({ preventScroll: true });
+    previousBig.current = big;
+  }, [big, toolbarHost]);
+  // 点「重试」：重新读（图片 / PDF 换一个地址参数，绕开浏览器缓存的失败）。
+  const [attempt, setAttempt] = useState(0);
+  useEffect(() => () => { if (copiedTimer.current !== null) clearTimeout(copiedTimer.current); }, []);
+  const retry = () => { setError(null); setLoaded(null); setAttempt((n) => n + 1); };
+  useEffect(() => {
+    if (!big) return;
+    const onKey = (e: KeyboardEvent) => { if (e.key === "Escape" && !e.defaultPrevented && !actionsOpen) setBig(false); };
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    window.addEventListener("keydown", onKey);
+    return () => { window.removeEventListener("keydown", onKey); document.body.style.overflow = prev; };
+  }, [big, actionsOpen]);
+  const needsSrc = kind === "image" || kind === "pdf" || kind === "html" && !htmlReading;
+  // 这个预览的口令：iframe 里的选区桥报上来的消息只认它（见 frameQuote.ts）。
+  const token = useMemo(frameToken, []);
+  const links = useFileLinks(backend, jobId, path, version, attempt, reloadKey, !!backend.fileSync && isTaskUploadPath(path));
+  const knownSize = size ?? (loaded?.kind === "text" ? loaded.size : undefined);
+  // 读大文件时的进度（已收到的字节数）。
+  const [progress, setProgress] = useState(0);
+  // HTML 默认原样预览，完整重组后插选区桥；加载或排版较慢时可切分段阅读。
+  // 新同步协议失败时保留旧完整修订并提示重试；只有自定义旧后端保留原来的地址预览。
+  // 文件地址在读到的那一刻定下来：短期链接定时换新时不重载页面。
+  const linksRef = useRef(links);
+  linksRef.current = links;
+  const htmlTooBig = size !== undefined && size > HTML_QUOTE_MAX;
+  const htmlBridge = (!!backend.fileSync || !!onQuoteText) && kind === "html" && mode === "preview" && !htmlReading && !links.pending && !htmlTooBig;
+  const [htmlDoc, setHtmlDoc] = useState<{ srcDoc: string; token: string; revision?: string } | "fallback" | "toobig" | null>(null);
+  useEffect(() => { if (htmlReading || mode === "source") setHtmlDoc(null); }, [htmlReading, mode]);
+  const [frameState, setFrameState] = useState<"rendering" | "slow" | "ready">("rendering");
+  // 走 srcdoc 时不用再按地址取（中枢太旧时那是又整个读一遍）。
+  const bridged = htmlBridge && htmlDoc !== "fallback" && htmlDoc !== "toobig";
+  const src = useFileSrc(backend, jobId, path, needsSrc && !bridged && !(kind === "html" && mode === "source"), version, knownSize, links, attempt);
+  useEffect(() => {
+    if (!htmlBridge) return;
+    const ctl = new AbortController();
+    fileReadAbort.current = ctl;
+    setError(null); setCancelled(false); setSyncing(true); setProgress(0);
+    const loading = backend.fileSync
+      ? (async () => {
+        const transport = backend.fileSync!, options = { signal: ctl.signal, preview: true, fresh: attempt > 0, onProgress: (progress: { loadedBytes: number }) => setProgress(progress.loadedBytes) };
+        const result = await syncFile(transport, jobId, path, options);
+        return { text: result.text ?? decodeText(result.bytes).text, revision: result.revision, size: result.size };
+      })()
+      : readBoundedBuffer(backend, jobId, path, HTML_QUOTE_MAX, { signal: ctl.signal, onBytes: setProgress }).then(buffer => ({ text: decodeText(new Uint8Array(buffer)).text, revision: undefined }));
+    loading.then(result => {
+      if (ctl.signal.aborted) return;
+      const url = linksRef.current.url?.(path);
+      const base = url ? new URL(url, window.location.href).href : undefined;
+      revisionRef.current = result.revision;
+      setHtmlDoc(previous => {
+        if (result.revision && previous && typeof previous === "object" && previous.revision === result.revision) return previous;
+        const bridgeToken = frameToken();
+        return { srcDoc: bridgeDoc(result.text, { token: bridgeToken, base }), token: bridgeToken, revision: result.revision };
+      });
+    }, (error: unknown) => {
+      if (ctl.signal.aborted) return;
+      if (backend.fileSync) {
+        if ([401, 403, 404].includes((error as { status?: number }).status ?? 0)) { setHtmlDoc(null); revisionRef.current = undefined; }
+        setError(error instanceof Error ? error.message : String(error));
+      } else if (error instanceof FileReadLimitError) setHtmlDoc("toobig");
+      else setHtmlDoc("fallback");
+    }).finally(() => { if (!ctl.signal.aborted) setSyncing(false); });
+    return () => ctl.abort();
+  }, [htmlBridge, backend, jobId, path, version, reloadKey, attempt, htmlPresentation]);
+  const activeToken = htmlDoc && typeof htmlDoc === "object" ? htmlDoc.token : token;
+  useEffect(() => {
+    if (!bridged || !htmlDoc || typeof htmlDoc !== "object") return;
+    setFrameState("rendering");
+    const timer = setTimeout(() => setFrameState(state => state === "ready" ? state : "slow"), 12_000);
+    return () => clearTimeout(timer);
+  }, [bridged, htmlDoc]);
+
+
+  // 重读时保留滚动位置；原本贴着底（或在看末尾）的继续贴着底——任务在往文件里写时像 tail -f。
+  const bodyRef = useRef<HTMLDivElement | null>(null);
+  const loadedRef = useRef(loaded);
+  loadedRef.current = loaded;
+  const textKey = useRef("");
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const selectionButtonRef = useRef<HTMLButtonElement | null>(null);
+  const stick = useRef(false);
+  // 选中文字 → 浮出「引用到对话」。按钮放在选区上方；滚动、点别处、选区清空时收起。
+  // frame = 选区在 HTML / Word 预览的 iframe 里（由插进去的小脚本报上来，见 frameQuote.ts）。
+  const [sel, setSel] = useState<{ text: string; x: number; y: number; frame?: boolean; revision?: string } | null>(null);
+  const frameRef = useRef<HTMLIFrameElement | null>(null);
+  const frameScroll = useRef({ top: 0, left: 0 });
+  useEffect(() => { setSel(null); }, [htmlDoc, loaded, mode]);
+  const sourceRevision = useCallback((revision: string | undefined) => { revisionRef.current = revision; setSel(null); }, []);
+  useEffect(() => {
+    const onMessage = (e: MessageEvent) => {
+      const frame = frameRef.current;
+      const root = rootRef.current;
+      const data = e.data as FrameSelMessage | null;
+      if (!frame || !root || e.source !== frame.contentWindow || !data || data.cliUiSel !== activeToken) return;
+      if (data.ready) { setFrameState("ready"); return; }
+      if (data.scroll) frameScroll.current = { top: Math.max(0, data.top ?? 0), left: Math.max(0, data.left ?? 0) };
+      if (!onQuoteText) return;
+      const text = data.scroll ? "" : (data.text ?? "").trim();
+      if (!text) { setSel((cur) => (cur?.frame ? null : cur)); return; }
+      const box = root.getBoundingClientRect();
+      const fr = frame.getBoundingClientRect();
+      const r = data.rect ?? { left: fr.width / 2, top: 48, width: 0 };
+      setSel({ text, frame: true, revision: revisionRef.current, x: Math.min(Math.max(8, fr.left - box.left + r.left + r.width / 2), box.width - 8), y: Math.max(40, fr.top - box.top + r.top) });
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [onQuoteText, activeToken]);
+  useEffect(() => {
+    if (!onQuoteText) return;
+    const read = () => {
+      const s = window.getSelection();
+      const body = bodyRef.current;
+      const root = rootRef.current;
+      // 宿主页面上没有选区：iframe 里的选区（另一个文档）不在这里，交给上面的消息处理，不清掉。
+      if (!s || s.isCollapsed || !s.rangeCount) { setSel((cur) => (cur?.frame ? cur : null)); return; }
+      if (!body || !root || !body.contains(s.anchorNode) || !body.contains(s.focusNode)) { setSel(null); return; }
+      const text = s.toString().trim();
+      if (!text) { setSel(null); return; }
+      const box = root.getBoundingClientRect();
+      // 取不到选区位置的环境（老浏览器、测试环境）：按钮放在预览顶部中间。
+      const range = s.getRangeAt(0);
+      const r = typeof range.getBoundingClientRect === "function" ? range.getBoundingClientRect() : { left: box.left + box.width / 2, width: 0, top: box.top + 48 };
+      setSel({ text, revision: revisionRef.current, x: Math.min(Math.max(8, r.left - box.left + r.width / 2), box.width - 8), y: Math.max(40, r.top - box.top) });
+    };
+    let selectionTimer: ReturnType<typeof setTimeout> | undefined;
+    const onUp = () => {
+      if (selectionTimer !== undefined) clearTimeout(selectionTimer);
+      selectionTimer = setTimeout(() => { selectionTimer = undefined; read(); }, 0);
+    };
+    // Native touch selection/handle changes need not generate mouseup or keyup.
+    const onChange = onUp;
+    const body = bodyRef.current;
+    document.addEventListener("mouseup", onUp);
+    document.addEventListener("keyup", onUp);
+    document.addEventListener("selectionchange", onChange);
+    const onScroll = () => setSel(null);
+    // 选区在 iframe 里时，点宿主页面别处（不是这个按钮）就收起。
+    const onDown = (e: MouseEvent) => { if (!(e.target instanceof Element && e.target.closest(".cli-fv-selq"))) setSel((cur) => (cur?.frame ? null : cur)); };
+    body?.addEventListener("scroll", onScroll, { passive: true });
+    document.addEventListener("mousedown", onDown);
+    return () => {
+      if (selectionTimer !== undefined) clearTimeout(selectionTimer);
+      document.removeEventListener("mousedown", onDown);
+      document.removeEventListener("mouseup", onUp);
+      document.removeEventListener("keyup", onUp);
+      document.removeEventListener("selectionchange", onChange);
+      body?.removeEventListener("scroll", onScroll);
+    };
+  }, [onQuoteText, loaded]);
+  useLayoutEffect(() => {
+    const root = rootRef.current, button = selectionButtonRef.current;
+    if (!sel || !root || !button) return;
+    const place = () => {
+      const bounds = root.getBoundingClientRect(), size = button.getBoundingClientRect();
+      if (bounds.width <= 0) return;
+      const half = size.width / 2;
+      const headerHeight = root.querySelector(".cli-fv-h")?.getBoundingClientRect().height ?? 0;
+      const minimumTop = Math.max(8, headerHeight) + size.height + 6;
+      button.style.left = `${Math.max(half + 8, Math.min(sel.x, bounds.width - half - 8))}px`;
+      button.style.top = `${Math.max(minimumTop, Math.min(sel.y, bounds.height - 8))}px`;
+    };
+    place();
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(place);
+    observer?.observe(root); observer?.observe(button);
+    return () => observer?.disconnect();
+  }, [sel]);
+  const quoteSelection = () => {
+    if (!sel || !onQuoteText) return;
+    const text = sel.text.length > QUOTE_SELECTION_MAX ? `${sel.text.slice(0, QUOTE_SELECTION_MAX)}…` : sel.text;
+    if (sel.revision) onQuoteText(text, { revision: sel.revision }); else onQuoteText(text);
+    if (sel.frame) frameRef.current?.contentWindow?.postMessage({ cliUiClear: activeToken }, "*");
+    else window.getSelection()?.removeAllRanges();
+    setSel(null);
+  };
+  useEffect(() => {
+    let alive = true;
+    const ctl=new AbortController();
+    setError(null); setCancelled(false);
+    if (needsSrc || kind === "binary") { setLoaded({ kind: "none" }); return; }
+    fileReadAbort.current = ctl;
+    if (kind === "docx") {
+      if (size !== undefined && size > DOCX_PREVIEW_MAX) { setError(`文件较大（${fmtSize(size)}），请下载后查看`); return; }
+      setProgress(0);
+      readBoundedBuffer(backend, jobId, path, DOCX_PREVIEW_MAX, { signal:ctl.signal,onBytes: (n) => { if (alive) setProgress(n); } }).then(async (buffer) => {
+        if(!alive)return;
+        const mammoth = await import("mammoth");
+        const convert = (mammoth as unknown as { convertToHtml: typeof import("mammoth").convertToHtml }).convertToHtml
+          ?? (mammoth as unknown as { default: typeof import("mammoth") }).default.convertToHtml;
+        if(!alive)return;
+        const input: Record<string, unknown> = { arrayBuffer: buffer };
+        const B = (globalThis as { Buffer?: { from(b: ArrayBuffer): unknown } }).Buffer;
+        if (B) input.buffer = B.from(buffer);
+        const out = await convert(input as unknown as Parameters<typeof convert>[0]);
+        if (alive) setLoaded({ kind: "docx", html: out.value });
+      }).catch((e: unknown) => { if (alive) setError(e instanceof Error ? e.message : String(e)); });
+    } else {
+      // A refresh verifies the immutable revision and reuses matching blocks.
+      const key = `${path}|${tail}|${attempt}|${reloadKey??""}`;
+      const prev = loadedRef.current?.kind === "text" && textKey.current === key ? loadedRef.current : null;
+      textKey.current = key;
+      if (!prev) setProgress(0);
+      setSyncing(true);
+      const max = htmlReading || backend.fileSync && (kind === "markdown" || progressiveText) ? textLimit : TEXT_MAX;
+      const full = () => loadText(backend, jobId, path, { max, tail, preview: true, fresh: attempt > 0, signal: ctl.signal, onBytes: (n) => { if (alive && !prev) setProgress(n); } });
+      (prev ? refreshText(backend, jobId, path, prev, max, { signal: ctl.signal, preview: true, fresh: attempt > 0 }).then((r) => r ?? full()) : full()).then(
+        (r) => {
+          if (!alive || ctl.signal.aborted) return;
+          const box = bodyRef.current;
+          stick.current = tail || (!!box && box.scrollHeight > box.clientHeight && box.scrollHeight - box.scrollTop - box.clientHeight < 40);
+          revisionRef.current = r.revision;
+          setLoaded({ kind: "text", ...r });
+        },
+        (e: unknown) => { if (alive && !ctl.signal.aborted) {
+          if ([401, 403, 404].includes((e as { status?: number }).status ?? 0)) { setLoaded(null); revisionRef.current = undefined; }
+          setError(e instanceof Error ? e.message : String(e));
+        } },
+      ).finally(() => { if (alive) setSyncing(false); });
+    }
+    return () => { alive = false; ctl.abort(); };
+  }, [backend, jobId, path, kind, needsSrc, version, reloadKey, tail, attempt, textLimit, htmlReading]); // eslint-disable-line react-hooks/exhaustive-deps
+  useLayoutEffect(() => {
+    const box = bodyRef.current;
+    if (box && stick.current && loaded?.kind === "text") box.scrollTop = box.scrollHeight;
+  }, [loaded]);
+
+  const fileInfo = useCallback(() => ({
+    path, name, url: links.url?.(path) ?? backend.fileUrl(jobId, path), downloadUrl: links.url?.(path, true) ?? backend.fileUrl(jobId, path, { download: true }),
+  }), [backend, jobId, path, name, links]);
+
+  const download = async () => {
+    if (busy) return;
+    setBusy(true); setDownloadError(null);
+    try { await downloadFile(backend, jobId, path, knownSize); } catch (e) { setDownloadError(e instanceof Error ? e.message : String(e)); } finally { setBusy(false); }
+  };
+  const openUrl = links.url ? links.url(path) : src.url;
+  const canOpenExternal = !!openUrl && !(backend.fileSync && isTaskUploadPath(path));
+  const openNew = () => { if (canOpenExternal && openUrl) window.open(openUrl, "_blank", "noopener"); };
+  const copyPath = async () => {
+    if (copying) return;
+    setCopying(true); setCopyError(null); setCopied(false);
+    try {
+      if (!navigator.clipboard?.writeText) throw new Error("当前浏览器不支持自动复制，可从文件操作菜单选择路径手动复制");
+      await navigator.clipboard.writeText(path);
+      setCopied(true);
+      if (copiedTimer.current !== null) clearTimeout(copiedTimer.current);
+      copiedTimer.current = setTimeout(() => setCopied(false), 1200);
+    } catch (error) { setCopyError(`复制路径失败：${error instanceof Error ? error.message : "请重试"}`); }
+    finally { setCopying(false); }
+  };
+  const performAction = (action: () => void) => {
+    setActionsOpen(false);
+    moreRef.current?.focus({ preventScroll: true });
+    action();
+  };
+
+  // Markdown 里的相对链接 / 图片：相对这个文件所在目录。
+  const mdResolve = useMemo(() => (href: string) => links.url?.(resolveRelative(path, href)) ?? null, [links, path]);
+  const mdOpen = useMemo(() => (onOpenPath ? (href: string) => { onOpenPath(resolveRelative(path, href)); return true; } : null), [onOpenPath, path]);
+
+  const canSource = kind === "markdown" || kind === "html" || kind === "csv";
+  const visibleActions = actions.filter(action => !action.when || action.when({ path, name }));
+  const shownSize = knownSize;
+  const text = loaded?.kind === "text" ? loaded : null;
+  const loading = !error && !src.error && (needsSrc ? (bridged ? htmlDoc === null : !src.url) : !loaded);
+  const slow = useSlow(loading);
+  // 大文件显示读到哪了；很久没读完提示网络慢。
+  const progressText = progress > 0 ? `已读取 ${fmtSize(progress)}${shownSize ? ` / ${fmtSize(shownSize)}` : ""}` : "";
+  const slowNote = progressText || slow
+    ? <div className="cli-fv-slow">{slow ? `网络较慢或执行节点忙，仍在读取${progressText ? `（${progressText}）` : shownSize ? `（${fmtSize(shownSize)}）` : ""}…` : progressText}</div>
+    : null;
+
+  const embedded = toolbarHost !== undefined && !big;
+  const toolbar = <>
+          {(copying || copied || busy) && <span className="cli-fv-status" role="status">{copying ? "正在复制路径…" : copied ? "路径已复制" : "正在下载…"}</span>}
+          <div className="cli-fv-actions">
+            {embedded && <button className="cli-fv-icon" title={syncing || parsing ? "正在同步当前文件" : "刷新当前文件"} aria-label="刷新当前文件" aria-busy={syncing || parsing} disabled={syncing || parsing} onClick={() => setAttempt(value => value + 1)}>↻</button>}
+            <button ref={moreRef} className="cli-fv-icon cli-fv-more" title="更多文件操作" aria-label="更多文件操作" aria-haspopup="dialog" aria-expanded={actionsOpen} onClick={() => setActionsOpen(open => !open)}>{Icon.dots()}</button>
+            {actionsOpen && <Popover className="cli-fv-menu" ariaLabel="文件操作" returnFocusRef={moreRef} onClose={() => setActionsOpen(false)}>
+              <div className="cli-fv-menu-head"><strong>文件操作</strong><span title={path}>{path}</span></div>
+              <button className="pop-item" disabled={syncing || parsing} onClick={() => performAction(() => setAttempt(value => value + 1))}>刷新内容</button>
+              {onBack && <button className="pop-item" title="返回文件列表" onClick={() => performAction(onBack)}>返回文件列表</button>}
+              {visibleActions.length > 0 && <div className="cli-fv-menu-custom">{visibleActions.map(action => (
+                <button key={action.label} className="pop-item" title={action.title} onClick={() => performAction(() => action.onClick(fileInfo(), jobId))}>{action.label}</button>
+              ))}</div>}
+              {canSource && <button className="pop-item" onClick={() => performAction(() => setMode(mode === "preview" ? "source" : "preview"))} title={mode === "preview" ? "查看源文件" : "查看预览"}>{Icon.doc()} {mode === "preview" ? "源文件" : "预览"}</button>}
+              {kind === "html" && <button className="pop-item" onClick={() => performAction(() => { setMode("preview"); setHtmlPresentation(htmlReading ? "original" : "reading"); })}>{htmlReading ? "原样预览" : "分段阅读"}</button>}
+              <button className="pop-item" disabled={copying} onClick={() => performAction(() => void copyPath())} title={copied ? "已复制" : "复制路径"}>{copied ? Icon.check() : Icon.copy()} {copying ? "复制中…" : copied ? "路径已复制" : "复制路径"}</button>
+              <button className="pop-item" onClick={() => performAction(() => setBig((b) => !b))} title={big ? "还原（Esc）" : "放大查看"} aria-pressed={big}>{big ? "⤡" : "⤢"} {big ? "还原大小" : "放大查看"}</button>
+              <button className="pop-item" onClick={() => performAction(openNew)} title={openUrl && !canOpenExternal ? "此附件可在看板预览或下载" : "在新窗口打开"} disabled={!canOpenExternal}>{Icon.external()} 在新窗口打开</button>
+              <button className="pop-item" onClick={() => performAction(() => void download())} title="下载" disabled={busy}>{Icon.download()} {busy ? "下载中…" : "下载"}</button>
+            </Popover>}
+          </div>
+  </>;
+
+  return (
+    <>
+    {big && <div className="cli-ui cli-fv-backdrop" onClick={() => setBig(false)} />}
+    <div className={`cli-fv ${big ? "cli-fv-big" : ""}`} ref={rootRef} role={big ? "dialog" : undefined} aria-modal={big || undefined} aria-label={big ? name : undefined}>
+      {sel && (
+        <button ref={selectionButtonRef} className="cli-fv-selq" style={{ left: sel.x, top: sel.y }} onPointerDown={event => event.preventDefault()} onMouseDown={(e) => e.preventDefault()} onClick={quoteSelection} title={`把选中的${sel.text.length > QUOTE_SELECTION_MAX ? `前 ${QUOTE_SELECTION_MAX}` : sel.text.length}字带进下一条消息`}>
+          {Icon.board()} 引用到对话
+        </button>
+      )}
+      {!bare && embedded && toolbarHost && createPortal(toolbar, toolbarHost)}
+      {!bare && !embedded && (
+        <div className="cli-fv-h">
+          {lead}
+          <span className="cli-fv-ic">{Icon.doc()}</span>
+          <span className="cli-fv-name" title={path}>{name}</span>
+          <span className="cli-fv-meta">
+            {shownSize !== undefined && fmtSize(shownSize)}
+            {mtime && mtime > 0 ? ` · ${relTime(mtime)}更新` : ""}
+            {text?.encoding && text.encoding !== "utf-8" ? ` · ${text.encoding.toUpperCase()}` : ""}
+          </span>
+          <span className="cli-fv-sp" />
+          {toolbar}
+          {onClose && <button className="cli-fv-icon" onClick={onClose} title="关闭">{Icon.x()}</button>}
+        </div>
+      )}
+      {copyError && <div className="cli-fv-trunc" role="alert">{copyError}
+        <button className="cli-fv-btn" disabled={copying} onClick={() => void copyPath()}>重试复制</button>
+        <button className="cli-fv-btn" onClick={() => setCopyError(null)} aria-label="关闭复制错误">关闭</button>
+      </div>}
+      {downloadError && <div className="cli-fv-trunc" role="alert">下载失败：{downloadError}
+        <button className="cli-fv-btn" disabled={busy} onClick={() => void download()}>重试下载</button>
+        <button className="cli-fv-btn" onClick={() => setDownloadError(null)} aria-label="关闭下载错误">关闭</button>
+      </div>}
+      {error && (loaded?.kind === "text" || (htmlDoc && typeof htmlDoc === "object")) && <div className="cli-fv-trunc" role="alert">同步失败：{error}。保留上次完整内容。<button className="cli-fv-btn" onClick={() => setAttempt(value => value + 1)}>重试</button></div>}
+      {(syncing || parsing) && <div className="cli-fv-sync" role="status">{!syncing && parsing ? "正在整理正文…" : loaded?.kind === "text" || (htmlDoc && typeof htmlDoc === "object") ? "正在核对更新…" : "正在读取文件…"}<button className="cli-fv-btn" onClick={cancelRead}>暂停加载</button>{kind === "html" && mode === "preview" && !htmlReading && <button className="cli-fv-btn" onClick={() => setHtmlPresentation("reading")}>分段阅读</button>}</div>}
+      {cancelled && <div className="cli-fv-trunc" role="status">已暂停加载，已读取的内容仍然保留。<button className="cli-fv-btn" onClick={() => setAttempt(value => value + 1)}>继续加载</button></div>}
+      {bridged && htmlDoc && typeof htmlDoc === "object" && frameState !== "ready" && <div className="cli-fv-trunc cli-fv-render" role="status">{frameState === "slow" ? "原样预览排版较慢，可切换分段阅读。" : "正在显示页面…"}<button className="cli-fv-btn" onClick={() => setHtmlPresentation("reading")}>分段阅读</button></div>}
+      <div className={`cli-fv-b k-${kind}${kind === "html" && (htmlReading || mode === "source") ? " cli-fv-flow" : ""}`} ref={bodyRef} onScroll={event => {
+        const el = event.currentTarget;
+        if (kind === "markdown" && backend.fileSync && loaded?.kind === "text" && loaded.truncated && !syncing && !error && el.scrollHeight - el.scrollTop - el.clientHeight < 500) setTextLimit(limit => nextTextLimit(limit));
+      }}>
+        {(error && loaded?.kind !== "text" && !(htmlDoc && typeof htmlDoc === "object")) || src.error ? (
+          <div className="cli-fv-note err">读取失败：{error ?? src.error}
+            <button className="btn btn-line btn-sm" style={{ marginLeft: 8 }} onClick={retry}>重试</button>
+            <button className="btn btn-line btn-sm" style={{ marginLeft: 8 }} onClick={() => void download()} disabled={busy}>{Icon.download()} 下载</button>
+          </div>
+        ) : kind === "binary" ? (
+          <div className="cli-fv-note">这种文件不能在这里预览。
+            <button className="btn btn-accent btn-sm" style={{ marginLeft: 8 }} onClick={() => void download()} disabled={busy}>{Icon.download()} 下载</button>
+          </div>
+        ) : needsSrc ? (
+          kind === "html" && mode === "source" ? <SourceView backend={backend} jobId={jobId} path={path} version={`${version}:${reloadKey ?? ""}:${attempt}`} fresh={attempt > 0} onBusyChange={sourceBusy} onRevision={sourceRevision} abortRef={fileReadAbort} scrollRef={bodyRef} />
+          : bridged && htmlDoc === null ? (cancelled ? null : <div className="cli-fv-note">加载中…{slowNote}</div>)
+          // 可以选中引用：srcdoc + 选区桥。沙箱同样不给同源，页面自己的脚本被插入的 CSP 挡住，只有桥脚本能跑。
+          : bridged && htmlDoc ? <iframe ref={frameRef} className="cli-fv-frame" srcDoc={htmlDoc.srcDoc} title={name} onLoad={() => frameRef.current?.contentWindow?.postMessage({ cliUiRestore: htmlDoc.token, ...frameScroll.current }, "*")} sandbox="allow-scripts allow-popups allow-forms allow-modals" />
+          : !src.url ? <div className="cli-fv-note">加载中…{slowNote}</div>
+            : kind === "image" ? <ImageView key={src.url} src={src.url} name={name} onRetry={retry} />
+              : kind === "pdf" ? <iframe className="cli-fv-frame" src={src.url} title={name} />
+                : mode === "source" ? <SourceView backend={backend} jobId={jobId} path={path} version={`${version}:${reloadKey ?? ""}:${attempt}`} fresh={attempt > 0} onBusyChange={sourceBusy} onRevision={sourceRevision} abortRef={fileReadAbort} scrollRef={bodyRef} />
+                  // HTML：节点按沙箱 CSP 返回；这里再加 iframe 沙箱（不给同源），页面脚本碰不到宿主。
+                  : <>
+                        {onQuoteText && (htmlTooBig || htmlDoc === "toobig") && <div className="cli-fv-trunc">文件超过 {fmtSize(HTML_QUOTE_MAX)}，直接打开显示，不能选中文字引用（可以用「引用到对话」引用整个文件）。</div>}
+                        <iframe className="cli-fv-frame" src={src.url} title={name} sandbox="allow-scripts allow-popups allow-forms allow-modals" />
+                      </>
+        ) : !loaded ? (
+          cancelled ? null : <div className="cli-fv-note">加载中…{slowNote}</div>
+        ) : loaded.kind === "docx" ? (
+          // Word：转出来的 HTML 放进沙箱。能选中引用时插上选区桥（只放行桥脚本，文档里不会有别的脚本能跑）。
+          onQuoteText
+            ? <iframe ref={frameRef} className="cli-fv-frame doc" title={name} sandbox="allow-scripts" srcDoc={bridgeDoc(docxPage(loaded.html), { token })} />
+            : <iframe className="cli-fv-frame doc" title={name} sandbox="" srcDoc={docxPage(loaded.html)} />
+        ) : text ? (
+          <>
+            {(text.truncated || tail) && !htmlReading && !(kind === "markdown" && backend.fileSync) && (
+              <div className="cli-fv-trunc">
+                {tail && !text.tail ? "执行节点不支持只读末尾，下面仍是开头；" : ""}
+                文件较大（{fmtSize(text.size)}），只显示{text.tail ? "最后" : "前"} {fmtSize(progressiveText ? text.end - text.start : TEXT_MAX)}；完整内容请下载。
+                {progressiveText && text.truncated && textLimit < TEXT_MAX && <button className="cli-fv-btn" disabled={syncing || !!error} onClick={() => setTextLimit(limit => Math.min(TEXT_MAX, nextTextLimit(limit)))}>{syncing ? "读取中…" : "继续读取"}</button>}
+                <button className="cli-fv-btn" onClick={() => { if (progressiveText) setTextLimit(MARKDOWN_STEP); setTail(!tail); }}>{tail ? "看开头" : "看末尾"}</button>
+              </div>
+            )}
+            {htmlReading ? <HtmlReadingPreview text={text.text} complete={!text.truncated} version={`${version}:${reloadKey ?? ""}:${attempt}:${text.revision ?? ""}`} onBusyChange={readingBusy} abortRef={readingAbort} scrollRef={bodyRef}
+              onSource={() => setMode("source")} onOriginal={() => setHtmlPresentation("original")} onMore={!syncing && !cancelled && text.truncated && textLimit < HTML_QUOTE_MAX ? () => setTextLimit(limit => nextTextLimit(limit)) : undefined} /> : kind === "markdown" && mode === "preview" ? (
+              <FileLinkContext.Provider value={mdResolve}>
+                <FileOpenContext.Provider value={mdOpen}>
+                  <div className="cli-fv-md"><MarkdownPreview text={text.text} scrollRef={bodyRef} /></div>
+                  {text.truncated && backend.fileSync && <div className="cli-fv-trunc"><button className="cli-fv-btn" disabled={syncing} onClick={() => setTextLimit(limit => nextTextLimit(limit))}>{syncing ? "读取中…" : "继续读取"}</button>已读取 {fmtSize(text.end)} / {fmtSize(text.size)}</div>}
+                </FileOpenContext.Provider>
+              </FileLinkContext.Provider>
+            ) : kind === "csv" && mode === "preview" ? (
+              <CsvTable text={text.text} />
+            ) : kind === "code" && text.text.length <= HIGHLIGHT_MAX ? (
+              <div className="cli-fv-code"><Markdown>{fenced(text.text, codeLang(path))}</Markdown></div>
+            ) : (
+              // 追加的内容各是一个文字节点：文件往后长的时候前面的不用重新排版。
+              <pre className="cli-fv-pre">{text.parts.map((p, i) => <Fragment key={i}>{p}</Fragment>)}</pre>
+            )}
+          </>
+        ) : null}
+      </div>
+    </div>
+    </>
+  );
+}
+
+/** 图片：缺省适应宽度；可以放大缩小、看原始大小，Ctrl / ⌘ + 滚轮也能缩放。 */
+function ImageView({ src, name, onRetry }: { src: string; name: string; onRetry?: () => void }) {
+  const [scale, setScale] = useState<number | null>(null); // null = 适应
+  const [natural, setNatural] = useState<{ w: number; h: number } | null>(null);
+  // 加载失败（网络断了、链接过期、文件坏了 / 不是浏览器认识的图片）：说清楚，给重试。
+  const [failed, setFailed] = useState(false);
+  const loadingImg = !natural && !failed;
+  const slow = useSlow(loadingImg);
+  const boxRef = useRef<HTMLDivElement | null>(null);
+  const fitScale = () => {
+    const box = boxRef.current;
+    if (!box || !natural) return 1;
+    return Math.min(1, (box.clientWidth - 32) / natural.w);
+  };
+  const zoom = (factor: number) => setScale((s) => Math.min(8, Math.max(0.1, (s ?? fitScale()) * factor)));
+  useEffect(() => {
+    const box = boxRef.current;
+    if (!box) return;
+    const onWheel = (e: WheelEvent) => {
+      if (!e.ctrlKey && !e.metaKey) return;
+      e.preventDefault();
+      zoom(e.deltaY < 0 ? 1.1 : 1 / 1.1);
+    };
+    box.addEventListener("wheel", onWheel, { passive: false });
+    return () => box.removeEventListener("wheel", onWheel);
+  }); // eslint-disable-line react-hooks/exhaustive-deps
+  const style = scale === null || !natural ? undefined : { width: Math.round(natural.w * scale), maxWidth: "none" };
+  return (
+    <div className="cli-fv-imgwrap">
+      <div className="cli-fv-imgbar">
+        <button className="cli-fv-btn" onClick={() => zoom(1 / 1.25)} title="缩小">−</button>
+        <span className="cli-fv-imgpct">{scale === null ? "适应" : `${Math.round(scale * 100)}%`}</span>
+        <button className="cli-fv-btn" onClick={() => zoom(1.25)} title="放大">＋</button>
+        <button className="cli-fv-btn" onClick={() => setScale(null)} disabled={scale === null}>适应</button>
+        <button className="cli-fv-btn" onClick={() => setScale(1)} disabled={scale === 1}>原始大小</button>
+        {natural && <span className="cli-fv-imgpct">{natural.w} × {natural.h}</span>}
+      </div>
+      <div className={`cli-fv-img ${scale === null ? "" : "zoomed"}`} ref={boxRef}>
+        {failed ? (
+          <div className="cli-fv-img-err">图片没有加载出来（网络中断、链接过期，或文件损坏 / 格式不支持）。
+            {onRetry && <button className="btn btn-line btn-sm" onClick={onRetry}>重试</button>}
+          </div>
+        ) : (
+          <>
+            <img src={src} alt={name} style={style} onLoad={(e) => setNatural({ w: e.currentTarget.naturalWidth, h: e.currentTarget.naturalHeight })} onError={() => setFailed(true)} />
+            {slow && <div className="cli-fv-slow">图片较大或网络较慢，仍在加载…</div>}
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function SourceView({ backend, jobId, path, version, fresh, onBusyChange, onRevision, abortRef, scrollRef }: { backend: BoardBackend; jobId: string; path: string; version: string; fresh?: boolean; onBusyChange: (busy: boolean) => void; onRevision: (revision: string | undefined) => void; abortRef: RefObject<AbortController | null>; scrollRef: RefObject<HTMLDivElement | null> }) {
+  const [state, setState] = useState<LoadedText | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [limit, setLimit] = useState(backend.fileSync ? MARKDOWN_STEP : TEXT_MAX);
+  const [busy, setBusy] = useState(false);
+  useEffect(() => {
+    const ctl = new AbortController(); abortRef.current = ctl;
+    const cancelled = () => { setBusy(false); onBusyChange(false); };
+    ctl.signal.addEventListener("abort", cancelled, { once: true });
+    setBusy(true); onBusyChange(true); setError(null);
+    loadText(backend, jobId, path, { max: limit, signal: ctl.signal, preview: true, fresh }).then(result => {
+      if (ctl.signal.aborted) return;
+      setState(result); onRevision(result.revision);
+    }, (error: unknown) => {
+      if (ctl.signal.aborted) return;
+      if ([401, 403, 404].includes((error as { status?: number }).status ?? 0)) { setState(null); onRevision(undefined); }
+      setError(error instanceof Error ? error.message : String(error));
+    }).finally(() => { if (!ctl.signal.aborted) { setBusy(false); onBusyChange(false); } });
+    return () => { ctl.signal.removeEventListener("abort", cancelled); ctl.abort(); onBusyChange(false); };
+  }, [backend, jobId, path, version, limit, fresh, onBusyChange, onRevision, abortRef]);
+  return <>
+    {error && <div className="cli-fv-trunc" role="alert">读取失败：{error}</div>}
+    {!state && !error && busy && <div className="cli-fv-note">加载中…</div>}
+    {state?.truncated && <div className="cli-fv-trunc">已读取 {fmtSize(limit)} / {fmtSize(state.size ?? 0)}
+      {backend.fileSync && limit < HTML_QUOTE_MAX && <button className="cli-fv-btn" disabled={busy} onClick={() => setLimit(value => nextTextLimit(value))}>{busy ? '读取中…' : '继续读取'}</button>}
+    </div>}
+    {state && <BoundedTextPreview text={state.text} scrollRef={scrollRef} />}
+  </>;
+}
+
+/** 表格先显示这么多行，「再显示」每次多这么多（几十万行一次画出来页面会卡住）。 */
+const CSV_PAGE = 2_000;
+
+function CsvTable({ text }: { text: string }) {
+  const [limit, setLimit] = useState(CSV_PAGE);
+  const { rows, more } = useMemo(() => parseCsv(text, limit + 1), [text, limit]);
+  if (!rows.length) return <div className="cli-fv-note">空文件。</div>;
+  const [head, ...body] = rows;
+  return (
+    <div className="cli-fv-csv">
+      <table>
+        <thead><tr>{head.map((c, i) => <th key={i}>{c}</th>)}</tr></thead>
+        <tbody>{body.map((r, i) => <tr key={i}>{r.map((c, j) => <td key={j}>{c}</td>)}</tr>)}</tbody>
+      </table>
+      {more && (
+        <div className="cli-fv-trunc">已显示前 {body.length.toLocaleString()} 行。
+          <button className="cli-fv-btn" onClick={() => setLimit((n) => n + CSV_PAGE * 5)}>再显示 {(CSV_PAGE * 5).toLocaleString()} 行</button>
+          （也可以切到「源文件」看全部文字）
+        </div>
+      )}
+    </div>
+  );
+}
+
+function fenced(text: string, lang: string) {
+  const runs = text.match(/`{3,}/g) ?? [];
+  const fence = "`".repeat(Math.max(3, ...runs.map((r) => r.length + 1)));
+  return `${fence}${lang}\n${text}\n${fence}`;
+}
+
+// Word 转出来的 HTML 放进无脚本的沙箱 iframe，配一份阅读样式。
+function docxPage(body: string) {
+  return `<!doctype html><meta charset="utf-8"><style>
+body{font:14px/1.7 -apple-system,"PingFang SC","Microsoft YaHei",sans-serif;color:#1f2328;max-width:820px;margin:0 auto;padding:24px 28px;}
+h1,h2,h3{line-height:1.35}table{border-collapse:collapse}td,th{border:1px solid #d0d7de;padding:4px 8px}img{max-width:100%}
+</style>${body}`;
+}
+