@xgspz/cli-ui 0.0.0-stage → 0.6.15

package/src/board/BrowserPane.tsx

@@ -0,0 +1,969 @@
+// 任务浏览器：移植自 Operator 的 BrowserPane（状态、实时画面、接管 / 交还、打开 / 关闭）。
+// 全部经 center 转发：一条实时连接（GET /browser/live）里有状态、画面、弹窗和复制出的文字，鼠标键盘走 POST。
+// 旧版中枢没有这条连接时退回两条（/browser/events 状态 + /browser/frames 画面）。页面切到后台就断开，切回来再连
+// （同一域名的连接数有限，后台页面不该占着）。
+// 输入只在用户接管（control = human）时发送，节点那边也只在接管时接受。
+// 让远端操作和本机一样：
+//   · 打字是真正的按键事件（网页的 keydown / 快捷键 / 输入即搜索都能收到）；输入法、粘贴走文字插入；
+//   · 编辑快捷键（全选 / 复制 / 剪切 / 撤销）按节点的系统换成那边的按键，复制出来的文字写进你自己的剪贴板；
+//   · 按住拖动带着按键（选中文字、拖滑块）；滚轮合并发送；
+//   · 网页的 alert / confirm / prompt 画面里看不到，这里单独弹出来处理。
+// Operator 的「在节点屏幕上显示」「弹出窗口」「登录状态」是节点本机的功能，这里不提供。
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState, type MutableRefObject, type ReactNode } from "react";
+import { CenterError, isMissingRoute, type BoardBackend } from "../core/client";
+import { jitter } from "../core/store";
+import type { BrowserFramesState, BrowserMessage, BrowserStatus } from "../core/types";
+import { Icon } from "../ui/icons";
+
+interface FrameMeta { deviceWidth: number; deviceHeight: number }
+type Dialog = Extract<BrowserMessage, { type: "dialog" }>;
+type Tabs = Extract<BrowserMessage, { type: "tabs" }>;
+type Target = { targetId: string; targetEpoch: number };
+function messageTarget(message: BrowserMessage): Target | null {
+  return typeof message.targetId === "string" && message.targetId.length > 0 && Number.isSafeInteger(message.targetEpoch) && message.targetEpoch! >= 0
+    ? { targetId: message.targetId, targetEpoch: message.targetEpoch! } : null;
+}
+const sameTarget = (a: Target | null, b: Target | null) => !!a && !!b && a.targetId === b.targetId && a.targetEpoch === b.targetEpoch;
+
+const CAPABILITY_LABEL: Record<string, string> = { config: "任务配置", manual: "手动打开过", ai: "AI 自行启用" };
+const SPECIAL_KEYS: Record<string, number> = {
+  Enter: 13, Backspace: 8, Tab: 9, Escape: 27, Delete: 46, ArrowLeft: 37, ArrowUp: 38, ArrowRight: 39, ArrowDown: 40,
+  Home: 36, End: 35, PageUp: 33, PageDown: 34,
+};
+const MOUSE_BUTTONS = ["left", "middle", "right"] as const;
+const RETRY_MS = [1_000, 3_000, 8_000, 15_000];
+const retryDelay = (attempt: number) => jitter(RETRY_MS[Math.min(attempt, RETRY_MS.length - 1)]);
+/** 看的人满了（中枢回 429）：别人退出才有位置，隔久一点再试。 */
+const FULL_RETRY_MS = 20_000;
+/** 连接失败后多久再试：还没派发不超过 3 秒；登录过期 30 秒；人满 20 秒；其余按退避（都带随机浮动，免得大家同一秒一起重连）。 */
+const nextTry = (err: { status?: number } | null | undefined, attempt: number) =>
+  err?.status === 409 ? Math.round(3_000 * (0.7 + Math.random() * 0.3)) : err && (err.status === 401 || err.status === 403) ? jitter(30_000) : err?.status === 429 ? jitter(FULL_RETRY_MS) : retryDelay(attempt);
+
+/**
+ * 连续失败这么多次就停下，不再定时重试（约 1.5 分钟；人满约 2.5 分钟）：显示「重试」，
+ * 网络恢复、页面回到前台、窗口重新获得焦点时自动再连。
+ */
+const MAX_TRIES = 8;
+const GAVE_UP = "连接多次失败，已停止自动重试；网络恢复、回到页面或点「重试」时再连";
+
+/** 接管时发了操作、这么久画面一点没变：提示「画面没有响应」，给重连。 */
+const UNRESPONSIVE_MS = 8_000;
+/** 输入队列最多攒这么多（请求卡住时不无限堆积；先丢鼠标移动）。 */
+const QUEUE_MAX = 200;
+
+/** 地址栏：没写协议的补 https://（example.com、localhost:3000）；看起来不像地址的原样交给节点。 */
+export function normalizeUrl(input: string): string {
+  const v = input.trim();
+  if (!v) return "";
+  if (/^[a-z][a-z0-9+.-]*:/i.test(v) && !/^[^/]+:\d+(\/|$)/.test(v)) return v;
+  if (/^(localhost|\d{1,3}(\.\d{1,3}){3})(:\d+)?(\/|$)/i.test(v)) return `http://${v}`;
+  if (!/\s/.test(v) && /\.[a-z]{2,}(:\d+)?(\/|$|\?|#)/i.test(v)) return `https://${v}`;
+  return v;
+}
+
+function modifiers(e: { altKey: boolean; ctrlKey: boolean; metaKey: boolean; shiftKey: boolean }): number {
+  return (e.altKey ? 1 : 0) | (e.ctrlKey ? 2 : 0) | (e.metaKey ? 4 : 0) | (e.shiftKey ? 8 : 0);
+}
+
+function usePageVisible(): boolean {
+  const [visible, setVisible] = useState(() => typeof document === "undefined" || document.visibilityState === "visible");
+  useEffect(() => {
+    const on = () => setVisible(document.visibilityState === "visible");
+    document.addEventListener("visibilitychange", on);
+    return () => document.removeEventListener("visibilitychange", on);
+  }, []);
+  return visible;
+}
+
+/** 写进本机剪贴板：优先 Clipboard API，不行（没有授权、不是安全来源）退回 execCommand。 */
+async function writeClipboard(text: string): Promise<boolean> {
+  try {
+    if (navigator.clipboard?.writeText) { await navigator.clipboard.writeText(text); return true; }
+  } catch { /* 退回下面 */ }
+  try {
+    const area = document.createElement("textarea");
+    area.value = text;
+    area.style.cssText = "position:fixed;left:0;top:0;opacity:0;";
+    document.body.appendChild(area);
+    area.select();
+    const ok = document.execCommand("copy");
+    area.remove();
+    return ok;
+  } catch {
+    return false;
+  }
+}
+
+interface BrowserFeed {
+  status: BrowserStatus | null;
+  setStatus: (s: BrowserStatus) => void;
+  /** 连接出了问题（正在重连）。 */
+  streamError: string | null;
+  /** 不会自动重连了（节点拒绝、没有权限）：显示原因和「重试」。 */
+  ended: string | null;
+  /** 发输入用的 viewer id；ready = 输入能送到节点。 */
+  viewer: string | null;
+  ready: boolean;
+  generation: number;
+  frames: BrowserFramesState;
+  paused: boolean;
+  reconnect: () => void;
+  /**
+   * 最近的页面、弹窗、画面：中枢在连上时就推过来，那时画面区（要等状态是「已打开」才挂上）可能还没挂好，
+   * 挂上时从这里补上——否则地址栏一直是空的，要等下一次换页。
+   */
+  latest: MutableRefObject<{ generation: number; protocol: boolean; tabs?: Tabs; page?: BrowserMessage; dialog?: BrowserMessage | null; frame?: BrowserMessage }>;
+}
+
+/**
+ * 浏览器的数据：状态、画面连接、viewer。新版中枢一条连接（browserLive），旧版两条。
+ * 画面和其他消息交给 sink（画面直接画到 canvas，不经 React 状态）。
+ */
+function useBrowserFeed(backend: BoardBackend, jobId: string, sink: MutableRefObject<((m: BrowserMessage) => void) | null>): BrowserFeed {
+  const visible = usePageVisible();
+  const [mode, setMode] = useState<"live" | "legacy">(backend.browserLive ? "live" : "legacy");
+  const [status, setStatus] = useState<BrowserStatus | null>(null);
+  const [streamError, setStreamError] = useState<string | null>(null);
+  const [ended, setEnded] = useState<string | null>(null);
+  const [viewer, setViewer] = useState<string | null>(null);
+  const [ready, setReady] = useState(false);
+  const [generation, setGeneration] = useState(0);
+  const [frames, setFrames] = useState<BrowserFramesState>({ state: "idle" });
+  const [retry, setRetry] = useState(0);
+  // 重试用完后停下：等网络恢复 / 回到页面 / 获得焦点再连（不定时重试）。
+  const gaveUp = useRef(false);
+  const reconnect = useCallback(() => { gaveUp.current = false; setEnded(null); setRetry((n) => n + 1); }, []);
+  const giveUp = useCallback(() => { gaveUp.current = true; setEnded(GAVE_UP); }, []);
+  useEffect(() => {
+    const wake = () => { if (gaveUp.current && document.visibilityState !== "hidden") reconnect(); };
+    window.addEventListener("online", wake);
+    window.addEventListener("focus", wake);
+    document.addEventListener("visibilitychange", wake);
+    return () => { window.removeEventListener("online", wake); window.removeEventListener("focus", wake); document.removeEventListener("visibilitychange", wake); };
+  }, [reconnect]);
+  const latest = useRef<BrowserFeed["latest"]["current"]>({ generation: 0, protocol: false });
+  const beginViewer = useCallback(() => {
+    const previous = latest.current;
+    // Epochs belong to one stream. A recovered viewer may start at epoch 1 again.
+    // Legacy servers retain their dialog while reconnecting, as before.
+    const next = previous.generation + 1;
+    latest.current = previous.protocol ? { generation: next, protocol: true } : { ...previous, generation: next };
+    setGeneration(next);
+  }, []);
+  const deliver = useCallback((m: BrowserMessage) => {
+    const cache = latest.current;
+    const target = messageTarget(m);
+    const current = cache.page ? messageTarget(cache.page) : null;
+    if (target) cache.protocol = true;
+    if (m.type === "tabs") {
+      cache.protocol = true; cache.tabs = m;
+      if (m.activeId === null) { delete cache.page; delete cache.frame; cache.dialog = null; }
+    }
+    if (m.type === "page") {
+      if (cache.protocol && !target) return;
+      if (target) {
+        cache.protocol = true;
+        if (current && (target.targetEpoch < current.targetEpoch || (target.targetEpoch === current.targetEpoch && target.targetId !== current.targetId))) return;
+        if (!sameTarget(current, target)) { delete cache.frame; cache.dialog = null; }
+      }
+      cache.page = m;
+    }
+    // A frame can arrive late or precede its page announcement. Neither is safe
+    // to display or use for coordinate input in the current page.
+    else if (cache.protocol && m.type !== "tabs" && m.type !== "error" && (!target || !sameTarget(current, target))) return;
+    else if (target && current && !sameTarget(current, target)) return;
+    if (m.type === "dialog") cache.dialog = m;
+    else if (m.type === "dialog_closed") cache.dialog = null;
+    else if (m.type === "frame") cache.frame = m;
+    sink.current?.(m);
+  }, [sink]);
+
+  // ── 新版：一条连接 ──
+  useEffect(() => {
+    if (mode !== "live") return;
+    if (!visible) { setViewer(null); setReady(false); setFrames({ state: "idle" }); return; }
+    let alive = true;
+    let stop: (() => void) | null = null;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let attempt = 0;
+    const connect = () => {
+      if (!alive) return;
+      let finished = false;
+      let seenViewer = false;
+      let stopThis: (() => void) | null = null;
+      const retire = () => {
+        if (!alive || finished) return false;
+        finished = true;
+        stopThis?.();
+        setViewer(null); setReady(false);
+        return true;
+      };
+      stopThis = backend.browserLive!(jobId, {
+        onViewer: (id, isReady) => { if (!alive || finished) return; if (!seenViewer) { seenViewer = true; beginViewer(); } attempt = 0; setViewer(id); setReady(isReady); },
+        onStatus: (s) => { if (!alive || finished) return; attempt = 0; setStreamError(null); setStatus(s); },
+        onMessage: (message) => { if (alive && !finished) deliver(message); },
+        onFrames: (state) => { if (alive && !finished) setFrames(state); },
+        onEnd: (end) => {
+          if (end.reason !== "refused" && end.reason !== "client_closed") return;
+          if (!retire()) return;
+          setFrames({ state: "idle" });
+          if (end.reason === "refused") setEnded(end.detail || "执行节点拒绝了浏览器连接");
+        },
+        onClose: (err) => {
+          if (!retire()) return;
+          if (isMissingRoute(err)) { setMode("legacy"); return; }
+          // 对话不存在：重连也没用。
+          if (err && [400,404,405,410,501].includes(err.status)) { setEnded(err.message); return; }
+          if (err) setStreamError(err.message);
+          // 409 还没派发：隔几秒再问；401 / 403 多半是宿主会话过期，30 秒后再试（续上会话就自己恢复）；
+          // 其余（断线、中枢重启、人太多）按退避重连。
+          if (attempt >= MAX_TRIES) { giveUp(); return; }
+          timer = setTimeout(connect, nextTry(err, attempt++));
+        },
+      });
+      stop = stopThis;
+      if (finished) stopThis();
+    };
+    connect();
+    return () => { alive = false; stop?.(); if (timer) clearTimeout(timer); };
+  }, [backend, jobId, mode, visible, retry, deliver, beginViewer, giveUp]);
+
+  // ── 旧版：状态一条（页面在后台时也断开，切回来再连：人多时少占中枢和节点的连接） ──
+  useEffect(() => {
+    if (mode !== "legacy" || !visible) return;
+    let alive = true;
+    let stop: (() => void) | null = null;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let attempt = 0;
+    const connect = () => {
+      if (!alive) return;
+      let finished = false;
+      let stopThis: (() => void) | null = null;
+      stopThis = backend.browserEvents(jobId, {
+        onStatus: (s) => { if (!alive || finished) return; attempt = 0; setStreamError(null); setStatus(s); },
+        onError: (error) => { if (alive && !finished) setStreamError(error.message); },
+        onClose: (err) => {
+          if (!alive || finished) return;
+          finished = true;
+          stopThis?.();
+          if (err && [400,404,405,410,501].includes(err.status)) { setEnded(err.message); return; }
+          if (err) setStreamError(err.message);
+          if (attempt >= MAX_TRIES) { giveUp(); return; }
+          timer = setTimeout(connect, nextTry(err, attempt++));
+        },
+      });
+      stop = stopThis;
+      if (finished) stopThis();
+    };
+    connect();
+    return () => { alive = false; stop?.(); if (timer) clearTimeout(timer); };
+  }, [backend, jobId, mode, visible, retry, giveUp]);
+
+  // ── 旧版：画面一条（浏览器开着、页面可见时） ──
+  const legacyRunning = mode === "legacy" && visible && status?.state === "running";
+  useEffect(() => {
+    if (!legacyRunning) { if (mode === "legacy") { setViewer(null); setReady(false); setFrames({ state: "idle" }); } return; }
+    let alive = true;
+    let stop: (() => void) | null = null;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let attempt = 0;
+    const connect = () => {
+      if (!alive) return;
+      let finished = false;
+      let seenViewer = false;
+      let stopThis: (() => void) | null = null;
+      const again = (detail?: string) => {
+        // A stream can emit an end event and then close; retire it only once.
+        if (!alive || finished) return;
+        finished = true;
+        stopThis?.();
+        setViewer(null);
+        setReady(false);
+        if (attempt >= MAX_TRIES) { setFrames({ state: "idle" }); giveUp(); return; }
+        setFrames({ state: "retrying", ...(detail ? { detail } : {}) });
+        timer = setTimeout(connect, retryDelay(attempt++));
+      };
+      setFrames({ state: attempt ? "retrying" : "connecting" });
+      stopThis = backend.browserFrames(jobId, {
+        onViewer: (id) => { if (!alive || finished) return; if (!seenViewer) { seenViewer = true; beginViewer(); } attempt = 0; setViewer(id); setReady(true); setFrames({ state: "live" }); },
+        onMessage: (message) => { if (alive && !finished) deliver(message); },
+        onEnd: (end) => {
+          if (end.reason !== "client_closed") { again(end.reason === "refused" ? end.detail : undefined); return; }
+          if (!alive || finished) return;
+          finished = true;
+          stopThis?.();
+          setViewer(null); setReady(false); setFrames({ state: "idle" });
+        },
+        // Clean EOF also invalidates the old viewer and needs a reconnect.
+        onClose: (err) => again(err?.message),
+      });
+      stop = stopThis;
+      // Custom transports may close synchronously before returning cleanup.
+      if (finished) stopThis();
+    };
+    connect();
+    return () => { alive = false; stop?.(); if (timer) clearTimeout(timer); };
+  }, [backend, jobId, legacyRunning, retry, deliver, beginViewer, giveUp]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // 浏览器关了：上一个页面的地址、弹窗、画面都作废，重新打开时不先闪一下旧画面。
+  const running = status?.state === "running";
+  useEffect(() => { if (status && !running) latest.current = { generation: latest.current.generation, protocol: false }; }, [running, status]);
+
+  return { status, setStatus, streamError, ended, viewer, ready, generation, frames, paused: !visible, reconnect, latest };
+}
+
+interface ScreenHandle { draw(base64: string, meta: FrameMeta | null): void; clear(): void }
+
+/** base64 → 字节。 */
+function decodeBase64(data: string): Uint8Array {
+  const bin = atob(data);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/**
+ * 实时画面：画在 canvas 上。
+ *   · 帧在内存里解码（createImageBitmap），不走 data: / blob: 地址，宿主页面的 CSP 没放行 img-src data: 也能显示；
+ *     解码是异步的，按序号丢掉过期帧，画面不会倒退。没有 createImageBitmap 的环境退回 <img>。
+ *   · 输入用指针事件：鼠标照原样；触屏点一下 = 点击，拖动 = 滚动；接管时滚轮 / 触摸只作用于画面，不滚动宿主页面。
+ *   · 画面按比例缩放，适应容器宽高（窄的侧栏、弹窗、整页都可以）。
+ */
+const Screen = forwardRef<ScreenHandle, { human: boolean; inputEpoch: number; hidden: boolean; label: string; send: (msg: Record<string, unknown>) => void; onFocusKeys: () => void }>(
+  function Screen({ human, inputEpoch, hidden, label, send, onFocusKeys }, ref) {
+    const canvasRef = useRef<HTMLCanvasElement | null>(null);
+    const imgRef = useRef<HTMLImageElement | null>(null);
+    const meta = useRef<FrameMeta | null>(null);
+    const seq = useRef({ next: 0, drawn: 0 });
+    const imageGeneration = useRef(0);
+    const [fallback] = useState(() => typeof createImageBitmap !== "function");
+    const [fallbackFrame, setFallbackFrame] = useState<{src:string;meta:FrameMeta|null} | null>(null);
+
+    useImperativeHandle(ref, () => ({
+      clear() {
+        imageGeneration.current++;
+        seq.current = { next: 0, drawn: 0 };
+        meta.current = null;
+        setFallbackFrame(null);
+        const canvas = canvasRef.current;
+        // Resetting dimensions also clears its pixels without requiring a 2d context.
+        if (canvas) canvas.width = canvas.width;
+      },
+      draw(data, frameMeta) {
+        const type = data.startsWith("iVBOR") ? "image/png" : "image/jpeg";
+        if (fallback) { setFallbackFrame({src:`data:${type};base64,${data}`,meta:frameMeta}); return; }
+        const n = ++seq.current.next;
+        const generation = imageGeneration.current;
+        let bytes: Uint8Array;
+        try { bytes = decodeBase64(data); } catch { return; }
+        createImageBitmap(new Blob([bytes as BlobPart], { type })).then((bitmap) => {
+          const canvas = canvasRef.current;
+          if (!canvas || generation !== imageGeneration.current || n < seq.current.drawn) { bitmap.close(); return; }
+          seq.current.drawn = n;
+          meta.current = frameMeta;
+          if (canvas.width !== bitmap.width || canvas.height !== bitmap.height) { canvas.width = bitmap.width; canvas.height = bitmap.height; }
+          canvas.getContext("2d")?.drawImage(bitmap, 0, 0);
+          bitmap.close();
+        }, () => undefined);
+      },
+    }), [fallback]);
+
+    // Identical image bytes may accompany updated CSS viewport metadata and
+    // need not trigger another load event in the fallback image element.
+    useEffect(()=>{const img=imgRef.current;if(fallbackFrame&&img?.complete&&img.naturalWidth>0)meta.current=fallbackFrame.meta;},[fallbackFrame]);
+
+    const el = () => (fallback ? imgRef.current : canvasRef.current);
+    /** 屏幕坐标 → 页面 CSS 像素（按帧自带的页面尺寸换算）。 */
+    const point = useCallback((clientX: number, clientY: number) => {
+      const node = el();
+      if (!node) return null;
+      // Network arrival is not an interactive image: never map a click onto
+      // the blank initial canvas or an image that has not decoded yet.
+      if (fallback ? !(node instanceof HTMLImageElement && node.complete && node.naturalWidth > 0) : seq.current.drawn === 0) return null;
+      const r = node.getBoundingClientRect();
+      if (!r.width || !r.height) return null;
+      const natural = node instanceof HTMLCanvasElement ? { w: node.width, h: node.height } : { w: node.naturalWidth, h: node.naturalHeight };
+      const w = meta.current?.deviceWidth ?? natural.w;
+      const h = meta.current?.deviceHeight ?? natural.h;
+      return { x: Math.round(((clientX - r.left) / r.width) * w), y: Math.round(((clientY - r.top) / r.height) * h) };
+    }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+    const humanRef = useRef(human);
+    humanRef.current = human;
+    const touch = useRef<{ id: number; x: number; y: number; lastY: number; lastX: number; moved: boolean } | null>(null);
+    const lastMove = useRef(0);
+    // 按住的鼠标键：按住拖动时移动事件要带上它，网页里选中文字、拖滑块、拖拽才生效（CDP 按 button 判断是不是在拖）。
+    const pressed = useRef<(typeof MOUSE_BUTTONS)[number] | null>(null);
+    const lastPoint = useRef<{ clientX: number; clientY: number } | null>(null);
+
+    const mouse = (event: string, e: { clientX: number; clientY: number; altKey: boolean; ctrlKey: boolean; metaKey: boolean; shiftKey: boolean }, extra: Record<string, unknown> = {}) => {
+      lastPoint.current = { clientX: e.clientX, clientY: e.clientY };
+      const p = point(e.clientX, e.clientY);
+      if (p) send({ type: "mouse", event, ...p, modifiers: modifiers(e), ...extra });
+    };
+
+    const onPointerDown = (e: React.PointerEvent) => {
+      if (!human || !point(e.clientX,e.clientY)) return;
+      e.preventDefault();
+      if (e.pointerType === "touch") {
+        touch.current = { id: e.pointerId, x: e.clientX, y: e.clientY, lastX: e.clientX, lastY: e.clientY, moved: false };
+        return;
+      }
+      onFocusKeys();
+      (e.currentTarget as Element).setPointerCapture?.(e.pointerId);
+      pressed.current = MOUSE_BUTTONS[e.button] ?? "left";
+      mouse("mousePressed", e, { button: pressed.current, clickCount: e.detail || 1 });
+    };
+    const onPointerMove = (e: React.PointerEvent) => {
+      if (!human) return;
+      const t = touch.current;
+      if (e.pointerType === "touch" && t && t.id === e.pointerId) {
+        // 触屏拖动 → 滚动页面（在按下的位置发滚轮）。
+        const dx = t.lastX - e.clientX;
+        const dy = t.lastY - e.clientY;
+        if (Math.abs(e.clientX - t.x) + Math.abs(e.clientY - t.y) > 8) t.moved = true;
+        if (t.moved && (Math.abs(dx) >= 4 || Math.abs(dy) >= 4)) {
+          const p = point(t.x, t.y);
+          if (p) send({ type: "mouse", event: "mouseWheel", ...p, deltaX: dx * 2, deltaY: dy * 2, modifiers: 0 });
+          t.lastX = e.clientX;
+          t.lastY = e.clientY;
+        }
+        return;
+      }
+      if (Date.now() - lastMove.current < 50) return;
+      lastMove.current = Date.now();
+      mouse("mouseMoved", e, pressed.current ? { button: pressed.current } : {});
+    };
+    const onPointerUp = (e: React.PointerEvent) => {
+      if (!human) return;
+      const t = touch.current;
+      if (e.pointerType === "touch" && t && t.id === e.pointerId) {
+        touch.current = null;
+        if (!t.moved && point(e.clientX, e.clientY)) {
+          // Send before focusing: the mobile keyboard can resize/reposition the frame.
+          // 触屏点一下 = 鼠标点击
+          mouse("mousePressed", e, { button: "left", clickCount: 1 });
+          mouse("mouseReleased", e, { button: "left", clickCount: 1 });
+          onFocusKeys();
+        }
+        return;
+      }
+      if (e.pointerType === "touch" || !pressed.current) return;
+      pressed.current = null;
+      mouse("mouseReleased", e, { button: MOUSE_BUTTONS[e.button] ?? "left", clickCount: e.detail || 1 });
+    };
+
+    // A new control/viewer epoch cannot inherit a drag from the previous one.
+    useEffect(()=>{touch.current=null;pressed.current=null;lastPoint.current=null;},[human,inputEpoch]);
+    const release = useCallback(() => {
+        touch.current=null;
+        if (!pressed.current || !lastPoint.current) return;
+        const p = point(lastPoint.current.clientX, lastPoint.current.clientY);
+        if (p && humanRef.current) send({ type: "mouse", event: "mouseReleased", ...p, button: pressed.current, clickCount: 1, modifiers: 0 });
+        pressed.current = null;
+    },[point,send]);
+    // Cancellation/window blur must release the remote pointer as well.
+    useEffect(() => {
+      window.addEventListener("blur", release);
+      document.addEventListener("visibilitychange", release);
+      return () => { window.removeEventListener("blur", release); document.removeEventListener("visibilitychange", release); };
+    }, [release]);
+
+    // 滚轮：React 的 onWheel 是被动监听，拦不住宿主页面滚动，所以用原生监听（passive: false）。
+    useEffect(() => {
+      const node: HTMLElement | null = el();
+      if (!node) return;
+      const onWheel = (e: WheelEvent) => {
+        if (!humanRef.current) return;
+        e.preventDefault();
+        // deltaMode 1 / 2（按行 / 按页滚动的鼠标）换成像素。
+        const k = e.deltaMode === 1 ? 16 : e.deltaMode === 2 ? 800 : 1;
+        mouse("mouseWheel", e, { deltaX: e.deltaX * k, deltaY: e.deltaY * k });
+      };
+      node.addEventListener("wheel", onWheel, { passive: false });
+      return () => node.removeEventListener("wheel", onWheel);
+    }); // 每次渲染重绑：fallback 时节点会变
+
+    const common = {
+      className: `bp-frame ${human ? "live" : ""}`,
+      style: { display: hidden ? "none" : undefined, touchAction: human ? "none" : "auto" } as React.CSSProperties,
+      onPointerDown, onPointerMove, onPointerUp,
+      onPointerCancel: release,
+      onContextMenu: (e: React.MouseEvent) => { if (human) e.preventDefault(); },
+      role: "img" as const,
+      "aria-label": label,
+    };
+    return fallback
+      ? (fallbackFrame ? <img ref={imgRef} src={fallbackFrame.src} onLoad={()=>{meta.current=fallbackFrame.meta;}} alt={label} draggable={false} {...common} /> : null)
+      : <canvas ref={canvasRef} {...common} />;
+  },
+);
+
+function Viewer({ backend, jobId, human, feed, sink, onPage, onQuoteText }: {
+  backend: BoardBackend; jobId: string; human: boolean; feed: BrowserFeed; sink: MutableRefObject<((m: BrowserMessage) => void) | null>;
+  onPage?: (page: { url: string; title: string } | null) => void;
+  onQuoteText?: (text: string, page: { url: string; title: string }) => void;
+}) {
+  const screenRef = useRef<ScreenHandle | null>(null);
+  const keysRef = useRef<HTMLTextAreaElement | null>(null);
+  const [hasFrame, setHasFrame] = useState(false);
+  const [tabs, setTabs] = useState<Tabs | null>(null);
+  const [switching, setSwitching] = useState<string | null>(null);
+  const targetRef = useRef<Target | null>(null);
+  const frameReady = useRef(false);
+  const pendingTarget = useRef<string | null>(null);
+  const pageGeneration = useRef(feed.latest.current.generation);
+  const [page, setPage] = useState<{ url: string; title: string }>({ url: "", title: "" });
+  const [addr, setAddr] = useState("");
+  const [editing, setEditing] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
+  const [dialog, setDialog] = useState<Dialog | null>(null);
+  const [promptText, setPromptText] = useState("");
+  const [dialogSending, setDialogSending] = useState(false);
+  const pendingDialog = useRef<Record<string, unknown> | null>(null);
+  // 在网页里复制出来的文字：除了写进剪贴板，还可以「引用到对话」。
+  const [copied, setCopied] = useState<{text:string;page:{url:string;title:string}} | null>(null);
+  const clipboardSequence=useRef(0);
+  // 画面没有响应：接管时发了操作，之后 UNRESPONSIVE_MS 一帧都没来。
+  const [stuck, setStuck] = useState(false);
+  const lastInputAt = useRef(0);
+  const lastFrameAt = useRef(0);
+  const noticeTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const flash = useCallback((text: string, ms = 3000) => {
+    setNotice(text);
+    if (noticeTimer.current) clearTimeout(noticeTimer.current);
+    noticeTimer.current = setTimeout(() => setNotice(null), ms);
+  }, []);
+  useEffect(() => () => { if (noticeTimer.current) clearTimeout(noticeTimer.current); }, []);
+
+  useEffect(() => { if (!editing) setAddr(page.url); }, [page.url, editing]);
+  const onPageRef = useRef(onPage);
+  onPageRef.current = onPage;
+  useEffect(() => { onPageRef.current?.(page.url ? page : null); }, [page]);
+  useEffect(() => () => onPageRef.current?.(null), []);
+  // 接管中发了操作却一直没有新画面：多半是画面连接卡住或网络很慢，说出来并给「重连」。
+  useEffect(() => {
+    if (!human) { setStuck(false); return; }
+    const t = setInterval(() => {
+      const waiting = lastInputAt.current > lastFrameAt.current && Date.now() - lastInputAt.current > UNRESPONSIVE_MS;
+      setStuck(waiting);
+    }, 1_000);
+    return () => clearInterval(t);
+  }, [human]);
+
+  // 输入按顺序发：一个请求在路上时攒着，回来后一次发完（鼠标移动只留最后一个，连续的滚轮合并）。
+  const viewerRef = useRef<string | null>(null);
+  const queue = useRef<Array<Record<string, unknown>>>([]);
+  const controlRef = useRef(human); controlRef.current=human;
+  const mountedRef = useRef(true);
+  useEffect(()=>{mountedRef.current=true;return()=>{mountedRef.current=false;queue.current=[];};},[]);
+  useEffect(() => { if (!feed.ready || !human) { pendingDialog.current = null; setDialogSending(false); } }, [feed.ready, feed.viewer, human]);
+  const inflight = useRef<{ viewer:string; epoch:number } | null>(null);
+  const inputEpoch = useRef(0);
+  const previousControl = useRef(human);
+  const nextViewer=feed.ready?feed.viewer:null;
+  if(viewerRef.current!==nextViewer||previousControl.current!==human){
+    inputEpoch.current++;queue.current=[];inflight.current=null;
+  }
+  previousControl.current=human;
+  viewerRef.current=nextViewer;
+  const reconnect = feed.reconnect;
+  const flush = useCallback(() => {
+    const viewer = viewerRef.current;
+    if (!mountedRef.current || !controlRef.current || inflight.current || !viewer || !queue.current.length) return;
+    const batch = queue.current.splice(0, 50);
+    const token={viewer,epoch:inputEpoch.current};
+    inflight.current = token;
+    backend.browserInput(jobId, viewer, batch).catch((error: unknown) => {
+      if(!mountedRef.current||inflight.current!==token||viewerRef.current!==viewer||!controlRef.current)return;
+      if (pendingDialog.current && batch.includes(pendingDialog.current)) { pendingDialog.current = null; setDialogSending(false); }
+      if (batch.some((message) => message.type === "select_tab")) {
+        flash("页面切换未确认，正在重新连接…", 5000);
+        reconnect();
+        return;
+      }
+      // 画面连接已失效（中枢重启、连接断开）：丢掉这批输入并重连，避免用户以为点了没反应。
+      if (error instanceof CenterError && (error.status === 404 || error.status === 409)) {
+        queue.current = [];
+        flash("画面连接已断开，正在重连…（刚才的操作没有送达，请重新操作）", 4000);
+        reconnect();
+        return;
+      }
+      // 其余（网络抖动、超时、中枢忙）：不自动重发——点击、回车重复送达比没送达更糟。说清楚，让用户看画面决定要不要再操作。
+      const important = batch.some((m) => m.type !== "mouse" || m.event === "mousePressed");
+      if (important) {
+        const why = error instanceof CenterError && error.status === 429 ? "操作太快，任务中心暂时没接收" : "网络不稳";
+        flash(`${why}：刚才的操作可能没有送达，请看画面确认后再操作`, 5000);
+      }
+    }).finally(() => { if(inflight.current!==token)return;inflight.current = null; flush(); });
+  }, [backend, jobId, reconnect, flash]);
+  const send = useCallback((msg: Record<string, unknown>) => {
+    if(!mountedRef.current||!controlRef.current)return false;
+    // 画面连接还没就绪（刚接管、正在重连）：不攒着等连上再补发——过几秒才落下的点击比没点更糟。
+    if (!viewerRef.current) {
+      if (msg.type !== "mouse" || msg.event === "mousePressed") flash("画面连接还没就绪，刚才的操作没有送达，请稍后再操作");
+      return false;
+    }
+    if (feed.latest.current.protocol) {
+      if (!targetRef.current || (!frameReady.current && msg.type !== "dialog") || pendingTarget.current || pageGeneration.current !== feed.latest.current.generation) return false;
+      // Preserve command identity (dialog acknowledgement tracks the queued object).
+      Object.assign(msg, targetRef.current);
+    }
+    lastInputAt.current = Date.now();
+    const q = queue.current;
+    // 请求卡住时别无限攒：超了先丢鼠标移动，还超就丢最早的。
+    if (q.length >= QUEUE_MAX) {
+      const kept = q.filter((m) => !(m.type === "mouse" && m.event === "mouseMoved"));
+      q.splice(0, q.length, ...kept.slice(-(QUEUE_MAX - 1)));
+    }
+    const last = q[q.length - 1];
+    if (msg.type === "mouse" && last?.type === "mouse" && msg.event === last.event && (msg.event === "mouseMoved" || (msg.event === "mouseWheel" && msg.x === last.x && msg.y === last.y))) {
+      q[q.length - 1] = msg.event === "mouseWheel"
+        ? { ...msg, deltaX: Number(last.deltaX) + Number(msg.deltaX), deltaY: Number(last.deltaY) + Number(msg.deltaY) }
+        : msg;
+    } else q.push(msg);
+    flush();
+    return true;
+  }, [flush, flash, feed.latest]);
+
+  const clearPage = useCallback(() => {
+    inputEpoch.current++;
+    queue.current = [];
+    inflight.current = null;
+    frameReady.current = false;
+    screenRef.current?.clear();
+    setHasFrame(false);
+    setPage({ url: "", title: "" });
+    setAddr(""); setEditing(false);
+    if (keysRef.current) keysRef.current.value = "";
+    pendingDialog.current = null; setDialogSending(false); setDialog(null); setPromptText("");
+    clipboardSequence.current++; setCopied(null); setNotice(null);
+    lastInputAt.current = 0; lastFrameAt.current = 0; setStuck(false);
+  }, []);
+  const selectTab = (id: string) => {
+    const current = targetRef.current;
+    if (!human || !feed.ready || !viewerRef.current || tabs?.canSelect !== true || !current || pendingTarget.current || id === current.targetId || pageGeneration.current !== feed.latest.current.generation) return;
+    if (!tabs.tabs.some((tab) => tab.id === id)) return;
+    clearPage();
+    pendingTarget.current = id; setSwitching(id);
+    queue.current.push({ type: "select_tab", targetId: id, expectedTargetId: current.targetId, expectedTargetEpoch: current.targetEpoch });
+    lastInputAt.current = Date.now();
+    flush();
+  };
+
+  useEffect(() => {
+    if (pageGeneration.current === feed.generation || !feed.latest.current.protocol) return;
+    pageGeneration.current = feed.generation;
+    targetRef.current = null; pendingTarget.current = null; setSwitching(null); setTabs(null);
+    clearPage();
+  }, [feed.generation, feed.latest, clearPage]);
+  useEffect(() => {
+    if (!switching) return;
+    const timer = setTimeout(() => {
+      if (!pendingTarget.current) return;
+      flash("切换页面尚未确认，正在重新连接…", 5000);
+      reconnect();
+    }, UNRESPONSIVE_MS);
+    return () => clearTimeout(timer);
+  }, [switching, flash, reconnect]);
+
+  // 连接上来的消息：画面直接画，其余更新界面。挂上时先补上挂上之前到的页面 / 弹窗 / 最后一帧。
+  const latest = feed.latest;
+  useEffect(() => {
+    const handle = (m: BrowserMessage) => {
+      if (pageGeneration.current !== latest.current.generation) {
+        pageGeneration.current = latest.current.generation;
+        if (latest.current.protocol) {
+          targetRef.current = null; pendingTarget.current = null; setSwitching(null); setTabs(null);
+          clearPage();
+        }
+      }
+      const target = messageTarget(m);
+      // Until the page announcement confirms a switch, events from the previous
+      // page may still be in transit (notably clipboard results and JS dialogs).
+      if (pendingTarget.current && m.type !== "page" && m.type !== "tabs" && m.type !== "error") return;
+      if (m.type === "tabs") {
+        setTabs(m);
+        if (m.activeId === null) { clearPage(); targetRef.current = null; pendingTarget.current = null; setSwitching(null); }
+      } else if (m.type === "page") {
+        // The old page may still announce its title while a switch is in flight.
+        if (pendingTarget.current && sameTarget(targetRef.current, target)) return;
+        if (target && !sameTarget(targetRef.current, target)) {
+          clearPage(); targetRef.current = target;
+          pendingTarget.current = null; setSwitching(null);
+        }
+        setPage({ url: m.url ?? "", title: m.title ?? "" });
+      }
+      if (m.type === "frame" && m.data) {
+        if (latest.current.protocol && (pendingTarget.current || !sameTarget(targetRef.current, target))) return;
+        screenRef.current?.draw(m.data, m.metadata ?? null);
+        frameReady.current = true;
+        lastFrameAt.current = Date.now();
+        setStuck(false);
+        setHasFrame(true);
+      } else if (m.type === "error" && m.message) { if(pendingDialog.current){pendingDialog.current=null;setDialogSending(false);} if (pendingTarget.current) reconnect(); flash(m.message); }
+      else if (m.type === "dialog") { pendingDialog.current = null; setDialogSending(false); setDialog(m); setPromptText(m.defaultPrompt ?? ""); }
+      else if (m.type === "dialog_closed") { pendingDialog.current = null; setDialogSending(false); setDialog(null); }
+      else if (m.type === "clipboard") {
+        const source=latest.current.page;
+        const sequence=++clipboardSequence.current;
+        setCopied({text:m.text,page:{url:source?.type==='page'?source.url??'':'',title:source?.type==='page'?source.title??'':''}});
+        void writeClipboard(m.text).then((ok) => {if(sequence===clipboardSequence.current)flash(ok ? "已复制到你的剪贴板" : "没能写入剪贴板（浏览器不允许），可以在网页里选中后再试", 6000);});
+      }
+    };
+    const { tabs: lastTabs, page: lastPage, dialog: lastDialog, frame: lastFrame } = latest.current;
+    if (lastTabs) handle(lastTabs);
+    if (lastPage) handle(lastPage);
+    if (lastDialog) handle(lastDialog);
+    if (lastFrame) handle(lastFrame);
+    sink.current = handle;
+    return () => { sink.current = null; clipboardSequence.current++; };
+  }, [sink, flash, latest, clearPage, reconnect]);
+
+  // 键盘：
+  //   · 普通字符（不带 Ctrl / ⌘）作为真正的按键发出（带 text）——网页的 keydown、快捷键、输入即搜索都能收到；
+  //   · 功能键（回车、退格、方向……）照发；
+  //   · Ctrl / ⌘ 组合键照发（节点按自己的系统换成那边的快捷键；复制 / 剪切出来的文字写进你的剪贴板）；
+  //     ⌘V / Ctrl+V 例外：让本机的粘贴进到接收框，再作为文字插入；
+  //   · 输入法的组字结果、粘贴走文字插入（compositionend / input）。
+  const onKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.nativeEvent.isComposing || e.keyCode === 229) return;
+    const mods = modifiers(e);
+    const shortcut = (mods & 6) !== 0;
+    if (shortcut && e.key.toLowerCase() === "v") return;
+    const special = SPECIAL_KEYS[e.key];
+    const printable = e.key.length === 1;
+    if (special === undefined && !printable && !shortcut) return;
+    e.preventDefault();
+    const keyCode = special ?? (e.keyCode || (printable ? e.key.toUpperCase().charCodeAt(0) : 0));
+    const base = { key: e.key, code: e.code, keyCode, modifiers: mods };
+    const text = e.key === "Enter" ? "\r" : printable && !shortcut ? e.key : undefined;
+    send({ type: "key", event: "keyDown", ...base, ...(text ? { text } : {}) });
+    send({ type: "key", event: "keyUp", ...base });
+  };
+  const flushText = (el: HTMLTextAreaElement) => {
+    if (el.value) send({ type: "text", text: el.value });
+    el.value = "";
+  };
+  const nav = (msg: Record<string, unknown>) => { if (human) send(msg); };
+  const answer = (accept: boolean) => {
+    if (!dialog || !human || !feed.ready || pendingDialog.current) return;
+    const command = { type: "dialog", accept, ...(dialog.dialogType === "prompt" && accept ? { promptText } : {}) };
+    if (send(command)) { pendingDialog.current = command; setDialogSending(true); }
+    // Keep the dialog until the remote browser confirms dialog_closed. Failed
+    // or disconnected input must remain visible and available to retry.
+  };
+
+  const { frames, paused } = feed;
+  const retrying = frames.state === "retrying";
+  const interactive = human && (!latest.current.protocol || (feed.ready && !!targetRef.current && hasFrame && !switching && pageGeneration.current === latest.current.generation));
+  const activeTab = switching ?? targetRef.current?.targetId ?? tabs?.activeId;
+  const listedTabs = tabs?.tabs.filter((tab, index, all) => typeof tab.id === "string" && !!tab.id && all.findIndex((candidate) => candidate.id === tab.id) === index) ?? [];
+  return (
+    <div className="bp-viewer">
+      {listedTabs.length > 0 && <nav className="bp-tabs" aria-label="任务浏览器页面">
+        {listedTabs.map((tab) => <button key={tab.id} className={`bp-tab${activeTab === tab.id ? " active" : ""}`} aria-pressed={activeTab === tab.id}
+          title={`${tab.title || "未命名页面"}${tab.url ? `\n${tab.url}` : ""}${!human ? "\n接管浏览器后可切换" : ""}`}
+          disabled={!human || !feed.ready || tabs?.canSelect !== true || !!switching || !targetRef.current}
+          onClick={() => selectTab(tab.id)}>
+          <span>{tab.title || tab.url || "未命名页面"}</span>{switching === tab.id && <span className="bp-tab-wait" aria-label="正在切换">…</span>}
+        </button>)}
+      </nav>}
+      <div className="prev-chrome bp-chrome">
+        <button className="bp-nav" disabled={!interactive} onClick={() => nav({ type: "back" })} title="后退">‹</button>
+        <button className="bp-nav" disabled={!interactive} onClick={() => nav({ type: "forward" })} title="前进">›</button>
+        <button className="bp-nav" disabled={!interactive} onClick={() => nav({ type: "reload" })} title="刷新">↻</button>
+        <form className="bp-addr-form" onSubmit={(e) => { e.preventDefault(); const url = normalizeUrl(addr); if (url) nav({ type: "navigate", url }); setEditing(false); (e.currentTarget.querySelector("input") as HTMLInputElement | null)?.blur(); }}>
+          <input className="prev-addr bp-addr" value={addr} readOnly={!interactive} title={page.title || page.url}
+            onFocus={() => setEditing(true)} onBlur={() => setEditing(false)} onChange={(e) => setAddr(e.target.value)} />
+        </form>
+      </div>
+      <div className={`bp-screen ${interactive ? "live" : ""}`}>
+        {/* 画面一直挂着（收到第一帧前隐藏），解码在内存里做，不受宿主页面 CSP 的 img-src 限制。 */}
+        <Screen ref={screenRef} human={interactive} inputEpoch={inputEpoch.current} hidden={!hasFrame} label={page.title || "浏览器画面"} send={send} onFocusKeys={() => keysRef.current?.focus({ preventScroll: true })} />
+        {!hasFrame && (
+          <div className="bp-empty">
+            {switching ? "正在切换页面…" : paused ? "页面不可见，已暂停画面" : retrying ? `画面连接中断，正在重连…${frames.detail ? `（${frames.detail}）` : ""}` : "正在连接画面…"}
+            {retrying && <><br /><button className="btn btn-line btn-sm" style={{ marginTop: 8 }} onClick={reconnect}>立即重试</button></>}
+          </div>
+        )}
+        {dialog && (
+          <div className="bp-dialog" role="dialog" aria-label="网页弹窗">
+            <div className="bp-dialog-box">
+              <div className="bp-dialog-t">网页{dialog.dialogType === "confirm" ? "请求确认" : dialog.dialogType === "prompt" ? "请求输入" : dialog.dialogType === "beforeunload" ? "询问是否离开" : "提示"}</div>
+              <div className="bp-dialog-m">{dialog.message || "（没有内容）"}</div>
+              {dialog.dialogType === "prompt" && <input className="bp-dialog-in" value={promptText} disabled={!human || !feed.ready || dialogSending} onChange={(e) => setPromptText(e.target.value)} onKeyDown={(e) => { if (e.key === "Enter") answer(true); }} />}
+              {!human && <div className="bp-dialog-hint">接管浏览器后才能处理这个弹窗。</div>}
+              {human && !feed.ready && <div className="bp-dialog-hint">画面连接恢复后可继续处理这个弹窗。</div>}
+              {dialogSending && <div className="bp-dialog-hint" role="status">正在等待网页确认…</div>}
+              <div className="bp-dialog-a">
+                {dialog.dialogType !== "alert" && <button className="btn btn-line btn-sm" disabled={!human || !feed.ready || dialogSending} onClick={() => answer(false)}>取消</button>}
+                <button className="btn btn-accent btn-sm" disabled={!human || !feed.ready || dialogSending} onClick={() => answer(true)}>确定</button>
+              </div>
+            </div>
+          </div>
+        )}
+        {notice && (
+          <div className="bp-toast">{notice}
+            {copied?.text && onQuoteText && /剪贴板/.test(notice) && (
+              <button className="bp-toast-btn" onClick={() => { onQuoteText(copied.text, copied.page); setCopied(null); setNotice(null); }}>引用到对话</button>
+            )}
+          </div>
+        )}
+        {stuck && !notice && (
+          <div className="bp-toast">画面 {Math.round(UNRESPONSIVE_MS / 1000)} 秒没有变化：网络较慢，或画面连接卡住了
+            <button className="bp-toast-btn" onClick={() => { setStuck(false); lastInputAt.current = 0; reconnect(); }}>重连画面</button>
+          </div>
+        )}
+        {hasFrame && !notice && (paused ? <div className="bp-toast">页面不可见，已暂停画面</div> : retrying ? <div className="bp-toast">画面连接中断，正在重连…</div> : null)}
+      </div>
+      <textarea
+        ref={keysRef}
+        className="bp-keys"
+        aria-label="向浏览器输入"
+        disabled={!interactive}
+        onKeyDown={onKeyDown}
+        onInput={(e) => { if (!(e.nativeEvent as InputEvent).isComposing) flushText(e.currentTarget); }}
+        onCompositionEnd={(e) => flushText(e.currentTarget)}
+      />
+    </div>
+  );
+}
+
+type BrowserPaneProps = {
+  backend: BoardBackend; jobId: string; readOnly?: boolean;
+  extension?: (status: BrowserStatus, update: (status:BrowserStatus)=>void) => ReactNode;
+  footer?: ReactNode;
+  className?: string;
+  /** 给了就显示「引用到对话」：把浏览器当前页面（标题 + 地址）带进下一条消息。 */
+  onQuote?: (page: { url: string; title: string }) => void;
+  /** 给了就能把在网页里复制（⌘C / Ctrl+C）出来的文字引用到对话。 */
+  onQuoteText?: (text: string, page: { url: string; title: string }) => void;
+  /** 当前页面变了（null = 浏览器没开 / 不在看）。 */
+  onPage?: (page: { url: string; title: string } | null) => void;
+};
+const browserBackendIds = new WeakMap<BoardBackend,number>();
+let nextBrowserBackendId=1;
+/** The low-level public component is safe to reuse across task/backend identity changes too. */
+export function BrowserPane(props:BrowserPaneProps) {
+  let identity=browserBackendIds.get(props.backend);
+  if(identity===undefined){identity=nextBrowserBackendId++;browserBackendIds.set(props.backend,identity);}
+  return <BrowserPaneInner key={`${identity}:${props.jobId}`} {...props}/>;
+}
+function BrowserPaneInner({ backend, jobId, readOnly, onQuote, onQuoteText, onPage, extension, footer, className }:BrowserPaneProps) {
+  const sink = useRef<((m: BrowserMessage) => void) | null>(null);
+  const feed = useBrowserFeed(backend, jobId, sink);
+  const { status, setStatus, streamError, ended } = feed;
+  const [busy, setBusy] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  // 放大：看板 / 弹窗里画面太小，接管后登录、填验证码看不清。接管时自动放大，交还、关闭时还原；也可以随时手动放大。
+  const [big, setBig] = useState(false);
+  useEffect(() => {
+    if (!big) return;
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => { document.body.style.overflow = prev; };
+  }, [big]);
+  const act = async (action: "open" | "close" | "takeover" | "handback") => {
+    setBusy(action);
+    setError(null);
+    if (action === "handback" || action === "close") setBig(false);
+    try {
+      setStatus(await backend.browserAction(jobId, action));
+      if (action === "takeover") setBig(true);
+    }
+    catch (e) { setError(e instanceof Error ? e.message : String(e)); }
+    finally { setBusy(null); }
+  };
+
+  if (!status) {
+    return (
+      <div className="rail-pad">
+        <div className="prev-note">
+          {ended ? `看不到浏览器：${ended}` : streamError ? `读取浏览器状态失败：${streamError}（正在重试）` : "读取浏览器状态…"}
+          {ended && <><br /><button className="btn btn-line btn-sm" style={{ marginTop: 8 }} onClick={feed.reconnect}>重试</button></>}
+        </div>
+      </div>
+    );
+  }
+  const running = status.state === "running";
+  const human = running && status.control === "human";
+  const kept = human && status.handoff?.by === "kept";
+  // 状态连接断了（还在重连）时，界面上的状态可能已经过时：写出来，免得用户对着旧状态操作。
+  const shownError = error ?? (status.state === "none" ? status.error : null)
+    ?? (ended ? `浏览器连接已停止：${ended}` : streamError ? `浏览器状态连接中断，正在重连…（${streamError}）` : null);
+
+  const zoomable = running;
+  return (
+    <>
+    {big && zoomable && <div className="cli-ui bp-backdrop" onClick={() => setBig(false)} />}
+    <div className={`rail-pad bp ${big && zoomable ? "bp-big" : ""} ${className??""}`}>
+      <div className="bp-head">
+        <span className="rail-eyebrow">浏览器 · ego lite</span>
+        <span className={`bp-badge ${running ? (human ? "human" : "ai") : ""}`}>
+          {status.state === "opening" ? "正在打开" : status.state === "closing" ? "正在关闭" : !running ? "未打开" : kept ? "结果页保留中" : human ? "你在操作" : "AI 控制中"}
+        </span>
+        {running && status.viewers > 0 && <span className="bp-meta">{status.viewers} 人在看</span>}
+        <span style={{ flex: 1 }} />
+        {zoomable && <button className="btn btn-ghost btn-sm bp-zoom" onClick={() => setBig((b) => !b)} title={big ? "还原到看板里" : "放大画面（登录、填验证码时更清楚）"}>{big ? "还原" : "⤢ 放大"}</button>}
+      </div>
+
+      {kept && <div className="bp-kept">AI 已完成，把结果页留在这里供你查看。看完点「关闭浏览器」；任务之后再用浏览器时会自动收回，没人看 10 分钟后也会自动关闭。</div>}
+      {human && !kept && status.handoff && (
+        <div className="bp-handoff">
+          {status.handoff.by === "ai"
+            ? <>🖐 AI 请求你操作：<b>{status.handoff.instruction || "完成浏览器里的这一步"}</b></>
+            : status.handoff.by === "browser"
+              ? <>🖐 浏览器需要你处理（AI 交出了控制权，或页面弹出了权限请求）</>
+              : <>你已接管浏览器，AI 的浏览器命令会暂停</>}
+          <div className="bp-handoff-sub">完成后点「交还给 AI」。密码只会发到网页，不会进入对话记录。</div>
+        </div>
+      )}
+
+      {running ? (
+        <>
+          <Viewer backend={backend} jobId={jobId} human={human && !readOnly} feed={feed} sink={sink} onPage={onPage} onQuoteText={onQuoteText?(text,page)=>{setBig(false);onQuoteText(text,page);}:undefined} />
+          {!readOnly && (
+            <div className="prev-actions bp-actions">
+              {human
+                ? <button className="btn btn-accent" disabled={!!busy} onClick={() => act("handback")}>{Icon.check()} 交还给 AI</button>
+                : <button className="btn btn-line" disabled={!!busy} onClick={() => act("takeover")}>{Icon.edit()} 接管</button>}
+              <span style={{ flex: 1 }} />
+              {onQuote && (
+                <button className="btn btn-ghost btn-sm" title="把当前页面的标题和地址带进下一条消息（在网页里复制文字后，也可以把复制的文字引用过去）"
+                  disabled={!feed.latest.current.page}
+                  onClick={() => { const p = feed.latest.current.page; if (p?.type === "page" && p.url) { setBig(false); onQuote({ url: p.url, title: p.title ?? "" }); } }}>
+                  {Icon.board()} 引用到对话
+                </button>
+              )}
+              <button className="btn btn-ghost btn-sm" disabled={!!busy} onClick={() => act("close")}>{Icon.x()} 关闭浏览器</button>
+            </div>
+          )}
+        </>
+      ) : (
+        <div className="bp-idle">
+          <p>
+            {status.capability
+              ? `这个任务已开启浏览器能力（${CAPABILITY_LABEL[status.capability] ?? status.capability}）：AI 第一次用到时会自动打开，轮次结束自动关闭。`
+              : "这个任务还没有开启浏览器能力。手动打开一次就会开启，之后 AI 也能使用这个浏览器（例如你先在这里登录好网站）。"}
+          </p>
+          {!readOnly && (
+            <button className="btn btn-accent" disabled={status.state !== "none" || !!busy} onClick={() => act("open")}>
+              {Icon.external()} {status.state === "opening" || busy === "open" ? "正在打开…" : "打开浏览器"}
+            </button>
+          )}
+          <div className="prev-note">
+            节点浏览器：{status.instance.running ? `运行中（${status.instance.spaces} 个任务在用）` : "未运行（首次打开需要几秒启动）"}
+            <br />登录状态保存在执行节点的 ego lite 里，所有任务共享：登录一次即可。
+          </div>
+        </div>
+      )}
+      {extension?.(status,setStatus)}
+      {footer}
+      {shownError && <div className="bp-error">{shownError}</div>}
+      {shownError && ended && <button className="btn btn-line btn-sm" onClick={feed.reconnect}>重试</button>}
+    </div>
+    </>
+  );
+}