Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

30.1 KB
Raw Blame
/**
 * useBrowserComment —— web-browser tab 的「页面评论」状态机(host 侧)。
 *
 * 职责(对齐方案分层:guest 只管选择层与 marker,评论编辑与业务流程全在 host):
 *  - 模式开关:toggle 后向 guest 发 enter-mode / exit-mode(经 `webview.send`,
 *    guest 是 webview-security 强制注入的 browserCommentPreload)。
 *  - 订阅 webview `ipc-message`:element-selected(弹输入气泡;`immediate` 标记
 *    时跳过气泡直接空评论提交)、command-result(关键命令回执)与
 *    mode-exited(guest 内 Esc)。
 *  - 提交流程:prepare-screenshot → main capturePage 拿 PNG 字节 →
 *    cacheImageFromBuffer 进会话图片缓存 → 组 BrowserCommentDraftItem 追加进
 *    ComposerDraft.browserComments(browser-comment-chip:ChatInput 渲染为
 *    「N 条注释」胶囊,发送时才序列化文本块 + 截图并入 filesToSend)。
 *  - Phase 2 多评论:提交成功后**不退出模式**,发 commit-pending 让 pending
 *    marker 转常驻、编号推进,可连续标注;提交点之前失败则保留气泡供重试。
 *  - 导航 / 页面刷新时 guest 上下文销毁,host 侧同步退出评论模式。
 *
 * 状态机:off → starting(等待 guest 确认)→ selecting(点选中)→ pending(气泡打开)→
 *          submitting(截图 + 入草稿)→ selecting(连续标注)。
 *          pending → cancelling(等待 guest 撤销)→ selecting。
 *          若 enter 时页面已有文本选区:starting 暂存选择,ACK 后直接进 pending。
 *          immediate 路径:selecting → submitting → selecting(不经 pending)。
 *          任何态可被 exit 打断回 off。
 */

import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
import { useTranslation } from 'react-i18next';
import type { WebviewTag } from 'electron';

import type { BrowserCommentDraftItem } from '@/lib/browserComments';
import { appendBrowserCommentToDraft, getDraft } from '@/lib/composerDraftStore';
import type { AttachedFile } from '@/lib/fileTypes';
import { toast } from '@/lib/toast';

import {
  BROWSER_COMMENT_CANCEL_PENDING_CHANNEL,
  BROWSER_COMMENT_COMMAND_RESULT_CHANNEL,
  BROWSER_COMMENT_COMMIT_PENDING_CHANNEL,
  BROWSER_COMMENT_DESIGN_PREVIEW_CHANNEL,
  BROWSER_COMMENT_DESIGN_RESET_CHANNEL,
  BROWSER_COMMENT_ELEMENT_SELECTED_CHANNEL,
  BROWSER_COMMENT_ENTER_MODE_CHANNEL,
  BROWSER_COMMENT_EXIT_MODE_CHANNEL,
  BROWSER_COMMENT_MODE_EXITED_CHANNEL,
  BROWSER_COMMENT_PREPARE_SCREENSHOT_CHANNEL,
  type BrowserCommentCommandChannel,
  type BrowserCommentCommandEnvelope,
  type BrowserCommentCommandResult,
  type BrowserCommentDesignPreviewPayload,
  type BrowserCommentStyleChange,
  type BrowserCommentTargetInfo,
} from '../../../../../shared/browserComment';
import { composerDraftKeyForRightSidebarSession } from '@/features/cc-agent/newMakerDraftRightSidebar';
import {
  createEmptyBrowserCommentEditorDraft,
  hasBrowserCommentDesignDraft,
  hasBrowserCommentEditorDraft,
  type BrowserCommentEditorDraft,
} from './browserCommentEditorDraft';

/** 关键 guest 命令的完成回执等待上限;超时保持用户输入并允许重试。 */
const COMMAND_TIMEOUT_MS = 2_000;

/**
 * 下一个 marker 编号 = 草稿里已有 marker 编号的最大值 + 1。
 * 不能用 `browserComments.length + 1`:用户删掉某条 chip 后,数组长度会与最大
 * 编号脱节(如删了 ②,剩 ①③ 时 length=2 → 会复用 ③),导致重复的 marker 与
 * `## Comment N` 块。取 max 保证编号单调、永不重号。
 */
function computeNextMarkerNumber(items: readonly { markerNumber: number }[] | undefined): number {
  if (!items || items.length === 0) return 1;
  return items.reduce((max, item) => Math.max(max, item.markerNumber), 0) + 1;
}

/**
 * Electron 当前类型把 WebviewTag.send 标成 Promise<void>,但不同 Electron
 * 版本 / 测试替身可能仍返回 void。状态机只能观察真实 thenable 的异步失败,
 * 不能因对 undefined 调用 .catch 而把已经投递的命令误判成发送失败。
 */
function observeSendRejection(result: unknown, onRejected: (reason: unknown) => void): void {
  if (
    result === null ||
    (typeof result !== 'object' && typeof result !== 'function') ||
    typeof (result as PromiseLike<unknown>).then !== 'function'
  ) {
    return;
  }
  void Promise.resolve(result).catch(onRejected);
}

export type BrowserCommentMode =
  'off' | 'starting' | 'selecting' | 'pending' | 'cancelling' | 'submitting';

interface PendingBrowserCommentCommand {
  webview: WebviewTag;
  command: BrowserCommentCommandChannel;
  timer: ReturnType<typeof setTimeout>;
  resolve: () => void;
  reject: (reason: Error) => void;
}

interface BufferedStartupSelection {
  webview: WebviewTag;
  epoch: number;
  target: BrowserCommentTargetInfo;
}

export interface UseBrowserCommentResult {
  /** 当前状态;BrowserChrome 按钮 active 态 = mode !== 'off'。 */
  mode: BrowserCommentMode;
  /** 已点选的目标信息(pending / submitting 态非空),气泡定位与提交都用它。 */
  pendingTarget: BrowserCommentTargetInfo | null;
  /** Host 侧未提交编辑草稿;WebView 自动换代时保留,显式取消 / 成功后清空。 */
  editorDraft: BrowserCommentEditorDraft;
  updateEditorDraft: (draft: BrowserCommentEditorDraft) => void;
  /** 工具栏按钮:off → 进入点选;其它态 → 整体退出。 */
  toggle: () => void;
  /** 气泡取消:回到点选态(marker 清除、样式预览还原,评论模式保持)。 */
  cancelPending: () => void;
  /** 气泡提交:走截图 + 入草稿流程。styleChanges 为样式编辑器的改动(可空)。 */
  submit: (commentText: string, styleChanges?: BrowserCommentStyleChange[]) => void;
  /** 样式编辑器实时预览:全量当前编辑状态透传给 guest 应用到 pending 元素。 */
  previewDesign: (payload: BrowserCommentDesignPreviewPayload) => void;
  /** 样式编辑器「重置」:guest 还原 pending 元素上的全部预览。 */
  resetDesign: () => void;
}

export function useBrowserComment(
  tabId: string,
  sessionId: string | undefined,
  /** useBrowserWebview 暴露的当前 WebView 代际句柄。 */
  webview: WebviewTag | null,
  /** 提交时刻的页面 URL 取值器(immediate 路径由 hook 自己触发提交,拿不到
   *  调用方参数,统一走 getter;需引用稳定或由调用方 useCallback 包裹)。 */
  getPageUrl: () => string,
  /** Retained background hosts keep their guest, but must release selection overlays. */
  visible = true,
): UseBrowserCommentResult {
  const { t } = useTranslation();
  // 草稿写入目标键:项目草稿页的 RSB bucket 是合成 sessionId,可见 composer
  // 实际用 NEW_MAKER_DRAFT_KEY 存草稿 —— 评论(含截图缓存目录)必须落到
  // composer 真正读取的键上,否则 toast 成功但胶囊永远不出现(Codex review P2)。
  const composerDraftKey =
    sessionId === undefined ? undefined : composerDraftKeyForRightSidebarSession(sessionId);
  const [mode, setMode] = useState<BrowserCommentMode>('off');
  const [pendingTarget, setPendingTarget] = useState<BrowserCommentTargetInfo | null>(null);
  const [editorDraft, setEditorDraft] = useState(createEmptyBrowserCommentEditorDraft);
  const editorDraftRef = useRef(editorDraft);
  editorDraftRef.current = editorDraft;
  const modeRef = useRef(mode);
  modeRef.current = mode;
  const pendingTargetRef = useRef(pendingTarget);
  pendingTargetRef.current = pendingTarget;
  const tRef = useRef(t);
  tRef.current = t;
  const getPageUrlRef = useRef(getPageUrl);
  getPageUrlRef.current = getPageUrl;
  const webviewRef = useRef<WebviewTag | null>(webview);
  const requestSequenceRef = useRef(0);
  const pendingCommandsRef = useRef(new Map<string, PendingBrowserCommentCommand>());
  /**
   * Guest 在 enter-mode 内会同步识别页面已有文本选区,而统一 command ACK
   * 要等 handler 返回后才发送。starting 期间收到的 selection 先按 WebView
   * 代际与提交纪元暂存,ACK 后再原子地推进到 pending / submitting,避免
   * guest 已被 blocker 锁成 pending、host 却把事件丢掉。
   */
  const bufferedStartupSelectionRef = useRef<BufferedStartupSelection | null>(null);
  /**
   * 提交纪元:每次退出模式 / 导航 / guest 内 Esc 都自增,使正在挂起的异步提交
   * (prepare → capture → cache)在恢复后察觉自己已被作废并静默中止,避免把一个
   * 已取消 / 已失效的选择追加进草稿(或把已退出的模式又拨回 selecting)。
   */
  const submitEpochRef = useRef(0);
  /**
   * appendBrowserCommentToDraft 是用户数据的提交点。其后的 guest ACK 只负责
   * 收尾 overlay;若此时 WebView 导航 / 崩溃 / 换代,仍必须按成功上报,不能
   * 用 lifecycle failure 诱导用户重试并重复写入同一条评论。
   */
  const committedSubmissionEpochRef = useRef<number | null>(null);
  const clearEditorDraft = useCallback(() => {
    setEditorDraft(createEmptyBrowserCommentEditorDraft());
  }, []);
  const updateEditorDraft = useCallback((draft: BrowserCommentEditorDraft) => {
    setEditorDraft(draft);
  }, []);

  const rejectCommandsForWebview = useCallback((target: WebviewTag) => {
    for (const [requestId, pending] of pendingCommandsRef.current) {
      if (pending.webview !== target) continue;
      clearTimeout(pending.timer);
      pendingCommandsRef.current.delete(requestId);
      pending.reject(new Error('browser comment WebView changed'));
    }
  }, []);

  const settleCommittedSubmission = useCallback(
    (epoch: number, nextMode: Extract<BrowserCommentMode, 'off' | 'selecting'>): boolean => {
      if (committedSubmissionEpochRef.current !== epoch) return false;
      committedSubmissionEpochRef.current = null;
      setPendingTarget(null);
      clearEditorDraft();
      setMode(nextMode);
      toast.success(tRef.current('rightSidebar.browser.commentAdded'));
      return true;
    },
    [clearEditorDraft],
  );

  /**
   * 向当前 WebView 发送一条必须确认完成的命令。requestId resolver 与具体
   * WebView 对象绑定,旧代际回执不可能推进新代际的状态机。
   */
  const sendCommand = useCallback(
    <T>(command: BrowserCommentCommandChannel, payload?: T): Promise<void> => {
      const target = webviewRef.current;
      if (!target) return Promise.reject(new Error('browser comment WebView unavailable'));
      const requestId = `${tabId}:${++requestSequenceRef.current}`;
      const envelope: BrowserCommentCommandEnvelope<T> = { requestId, payload };

      return new Promise<void>((resolve, reject) => {
        const timer = setTimeout(() => {
          const pending = pendingCommandsRef.current.get(requestId);
          if (!pending) return;
          pendingCommandsRef.current.delete(requestId);
          reject(new Error(`browser comment command timed out: ${command}`));
        }, COMMAND_TIMEOUT_MS);
        pendingCommandsRef.current.set(requestId, {
          webview: target,
          command,
          timer,
          resolve,
          reject,
        });

        const rejectDelivery = (reason: unknown) => {
          const pending = pendingCommandsRef.current.get(requestId);
          if (!pending) return;
          clearTimeout(pending.timer);
          pendingCommandsRef.current.delete(requestId);
          reject(reason instanceof Error ? reason : new Error('browser comment send failed'));
        };

        try {
          observeSendRejection(target.send(command, envelope), rejectDelivery);
        } catch (reason) {
          rejectDelivery(reason);
        }
      });
    },
    [tabId],
  );

  /** 无需等待状态推进的通知;仍使用信封,guest 可统一执行同一套命令 handler。 */
  const sendBestEffortCommand = useCallback(
    <T>(command: BrowserCommentCommandChannel, payload?: T) => {
      const target = webviewRef.current;
      if (!target) return;
      const envelope: BrowserCommentCommandEnvelope<T> = {
        requestId: `${tabId}:${++requestSequenceRef.current}`,
        payload,
      };
      try {
        observeSendRejection(target.send(command, envelope), () => undefined);
      } catch {
        // WebView 正在 detach / destroy;host 仍可安全完成本地退出。
      }
    },
    [tabId],
  );

  const sendNotification = useCallback((channel: string, payload?: unknown) => {
    const target = webviewRef.current;
    if (!target) return;
    try {
      observeSendRejection(target.send(channel, payload), () => undefined);
    } catch {
      // 实时预览是非关键通知;关键状态转换全部走 sendCommand。
    }
  }, []);

  /**
   * 统一退出 Guest 评论状态。用户主动关闭 / 取消时 discardEditorDraft=true;
   * WebView 导航、enter 失败等非用户故障只拆 overlay、保留可恢复的 Host 草稿。
   */
  const leaveMode = useCallback(
    (discardEditorDraft: boolean) => {
      const committedEpoch = committedSubmissionEpochRef.current;
      submitEpochRef.current += 1; // 作废任何挂起中的提交
      bufferedStartupSelectionRef.current = null;
      if (discardEditorDraft) clearEditorDraft();
      sendBestEffortCommand(BROWSER_COMMENT_EXIT_MODE_CHANNEL);
      if (committedEpoch !== null && settleCommittedSubmission(committedEpoch, 'off')) return;
      setMode('off');
      setPendingTarget(null);
    },
    [clearEditorDraft, sendBestEffortCommand, settleCommittedSubmission],
  );
  const exitMode = useCallback(() => {
    leaveMode(true);
  }, [leaveMode]);
  const abortModePreservingDraft = useCallback(() => {
    leaveMode(false);
  }, [leaveMode]);
  const exitModeRef = useRef(exitMode);
  exitModeRef.current = exitMode;
  const abortModePreservingDraftRef = useRef(abortModePreservingDraft);
  abortModePreservingDraftRef.current = abortModePreservingDraft;

  /**
   * 撤销 Guest 已建立的 pending target。显式取消会丢弃 Host 草稿;自动拒绝
   * 一个无法承载恢复中 design edits 的 target 时只撤 marker,保留草稿继续
   * 点选。两条路径共用 ACK 状态机,避免 Host 提前回 selecting 而 Guest 仍
   * 卡在 pending。
   */
  const cancelGuestPending = useCallback(
    (discardEditorDraft: boolean) => {
      const epoch = submitEpochRef.current;
      setMode('cancelling');
      void sendCommand(BROWSER_COMMENT_CANCEL_PENDING_CHANNEL).then(
        () => {
          if (submitEpochRef.current !== epoch) return;
          setPendingTarget(null);
          if (discardEditorDraft) clearEditorDraft();
          setMode('selecting');
        },
        () => {
          if (submitEpochRef.current !== epoch) return;
          // 无法确认 guest 已撤掉 pending 时整体退出;下次 enter 会先幂等拆旧 overlay。
          if (discardEditorDraft) {
            exitMode();
          } else {
            abortModePreservingDraft();
          }
          toast.error(tRef.current('rightSidebar.browser.commentFailed'));
        },
      );
    },
    [abortModePreservingDraft, clearEditorDraft, exitMode, sendCommand],
  );

  const cancelPending = useCallback(() => {
    if (modeRef.current !== 'pending') return;
    // 立即离开 pending,序列化 cancel 与 submit:ACK 前 submit() 不再能够
    // 启动 prepare-screenshot,避免 guest 已撤销 target 后 host 又进提交态。
    cancelGuestPending(true);
  }, [cancelGuestPending]);

  /**
   * 提交主流程(气泡提交与 immediate 共用)。commentText 允许为空(immediate:
   * 只留标注 + 截图,用户回 composer 再补话)。调用前提:target 已在 guest 侧
   * pending(marker 已画好)。
   */
  const doSubmit = useCallback(
    (
      target: BrowserCommentTargetInfo,
      commentText: string,
      styleChanges?: BrowserCommentStyleChange[],
    ) => {
      if (!composerDraftKey) return;
      if (modeRef.current === 'submitting' || modeRef.current === 'off') return;
      // 注意不在这里 setPendingTarget:气泡路径早已设置(submitting 期间气泡
      // 保持可见的禁用态);immediate 路径刻意保持 null,不闪现气泡。
      setMode('submitting');
      // 认领本次提交纪元:后续每个 await 之后都比对,一旦被退出 / 导航自增,
      // 说明这次选择已作废,静默中止(既不入草稿也不把模式拨回 selecting)。
      const epoch = submitEpochRef.current;
      const isStale = () => submitEpochRef.current !== epoch;

      void (async () => {
        let draftCommitted = false;
        try {
          // 1) guest 隐藏交互层只留标注,并明确确认两帧渲染已经完成。
          // 随命令下发草稿现存 marker 编号白名单:chip 单删 / 清空 / 发送
          // 清草稿都是 silent 写入无法事件通知,截图前对账是唯一可靠时机 ——
          // guest 据此剪除已无对应 `## Comment N` 块的常驻 marker。
          await sendCommand(BROWSER_COMMENT_PREPARE_SCREENSHOT_CHANNEL, {
            validMarkerNumbers: (getDraft(composerDraftKey)?.browserComments ?? []).map(
              (c) => c.markerNumber,
            ),
          });
          if (isStale()) return; // 已退出 / 导航,放弃本次提交

          // 2) main capturePage → PNG 字节(标注是页内 DOM,天然在图里)。
          const { data } = await window.electronAPI.rsbBrowserBridge.captureScreenshotData({
            tabId,
          });
          if (isStale()) return;

          // 3) PNG → 会话图片缓存 → AttachedFile。
          const n = target.markerNumber;
          const suggestedName = `browser-comment-${n}.png`;
          const cached = await window.electronAPI.cacheImageFromBuffer({
            sessionId: composerDraftKey,
            buffer: data,
            mimeType: 'image/png',
            suggestedName,
          });
          if (isStale()) return;
          const attached: AttachedFile = {
            id: crypto.randomUUID(),
            name: suggestedName,
            // 与剪贴板粘贴的 `clipboard://paste-*` 同型:图片附件以 url 为准,
            // path 只是占位标识来源。
            path: `clipboard://browser-comment-${Date.now()}`,
            ext: '.png',
            size: data.byteLength,
            category: 'image',
            mimeType: 'image/png',
            url: cached.url,
            originalName: suggestedName,
          };

          // 4) 结构化评论条目入草稿(browser-comment-chip):不进草稿文本、
          //    不进附件托盘 —— ChatInput 渲染为「N 条注释」胶囊,发送时才
          //    序列化 + 截图并入 filesToSend。非 silent 写入,挂载中的
          //    ChatInput 经 subscribeDraft 立即刷新胶囊。
          const item: BrowserCommentDraftItem = {
            id: crypto.randomUUID(),
            markerNumber: n,
            pageUrl: getPageUrlRef.current(),
            target,
            comment: commentText.trim(),
            screenshot: attached,
            ...(styleChanges && styleChanges.length > 0 ? { styleChanges } : {}),
          };
          appendBrowserCommentToDraft(composerDraftKey, item);
          draftCommitted = true;
          committedSubmissionEpochRef.current = epoch;

          // 5) Phase 2 连续标注:pending marker 转常驻,编号按草稿最大编号推进,
          //    回点选态继续标注(不退出模式,与 Codex 一致)。
          await sendCommand(BROWSER_COMMENT_COMMIT_PENDING_CHANNEL, {
            nextMarkerNumber: computeNextMarkerNumber(getDraft(composerDraftKey)?.browserComments),
          });
          if (isStale()) {
            settleCommittedSubmission(epoch, 'off');
            return;
          }
          settleCommittedSubmission(epoch, 'selecting');
        } catch {
          if (draftCommitted) {
            // Composer 已经是用户数据的提交点。guest 收尾失败时不能把同一条评论
            // 留在气泡里让用户重试并重复 append。即使 lifecycle 已作废本纪元,
            // 也先结算成功;若 lifecycle 已抢先结算,epoch guard 会避免重复 toast。
            if (!isStale()) sendBestEffortCommand(BROWSER_COMMENT_EXIT_MODE_CHANNEL);
            settleCommittedSubmission(epoch, 'off');
            return;
          }
          // 已退出 / 导航:模式与 marker 已由打断方复位,静默(不报错、不拨回)。
          if (isStale()) return;
          if (target.immediate) {
            // immediate 没有 Popover / 用户输入可保留。失败时撤掉本次 pending
            // marker 并回点选态,用户可以直接重新 Cmd/Ctrl+点击;不能把 host
            // 留在一个没有 pendingTarget、也没有取消入口的 pending 状态。
            try {
              await sendCommand(BROWSER_COMMENT_CANCEL_PENDING_CHANNEL);
              if (isStale()) return;
              setPendingTarget(null);
              setMode('selecting');
            } catch {
              if (isStale()) return;
              // 无法确认 pending marker 已撤除时,整体退出比继续展示失配状态安全。
              abortModePreservingDraft();
            }
            toast.error(t('rightSidebar.browser.commentFailed'));
            return;
          }
          // 普通气泡提交失败:pendingTarget 与 Popover 实例都保留,用户输入不会
          // 卸载丢失,可直接修订后重试或主动取消。guest 在截图准备期间始终保有
          // 透明 blocker,因此底层网页也不会抢走点击。
          setMode('pending');
          toast.error(t('rightSidebar.browser.commentFailed'));
        }
      })();
    },
    [
      composerDraftKey,
      abortModePreservingDraft,
      exitMode,
      sendBestEffortCommand,
      sendCommand,
      settleCommittedSubmission,
      t,
      tabId,
    ],
  );
  const doSubmitRef = useRef(doSubmit);
  doSubmitRef.current = doSubmit;

  const acceptSelectedTarget = useCallback(
    (info: BrowserCommentTargetInfo) => {
      const editorDraft = editorDraftRef.current;
      if (!info.designBaseline && hasBrowserCommentDesignDraft(editorDraft)) {
        // 恢复中的 CSS / text edit 不能绑定到 region、文本选区或 baseline
        // 采集失败的元素。Guest 此时已经建立 pending marker,先经 ACK 撤销,
        // Host 草稿保持不变,让用户继续选择一个兼容元素。
        cancelGuestPending(false);
        return;
      }
      if (info.immediate && !hasBrowserCommentEditorDraft(editorDraft)) {
        // Cmd/Ctrl+点击「立即添加」:跳过气泡,空评论文本直接提交。
        doSubmitRef.current(info, '');
        return;
      }
      // 生命周期恢复后若仍有 Host 草稿,即使用户 Cmd/Ctrl+点击也必须重新打开
      // Popover,让恢复的正文 / 样式明确绑定当前 target;不能提交空评论后清空。
      // 同时归一化为普通 pending,后续截图失败应保留 Popover,而不是走 immediate
      // 的无编辑器取消路径。
      setPendingTarget(info.immediate ? { ...info, immediate: false } : info);
      setMode('pending');
    },
    [cancelGuestPending],
  );

  const toggle = useCallback(() => {
    if (modeRef.current !== 'off') {
      exitMode();
      return;
    }
    if (!composerDraftKey) return;
    // 编号 = 草稿里已有 marker 编号的最大值 + 1(删 chip 后长度与最大编号会脱节)。
    const epoch = submitEpochRef.current;
    bufferedStartupSelectionRef.current = null;
    setMode('starting');
    void sendCommand(BROWSER_COMMENT_ENTER_MODE_CHANNEL, {
      markerNumber: computeNextMarkerNumber(getDraft(composerDraftKey)?.browserComments),
    }).then(
      () => {
        if (submitEpochRef.current !== epoch) return;
        const buffered = bufferedStartupSelectionRef.current;
        bufferedStartupSelectionRef.current = null;
        if (buffered && buffered.epoch === epoch && buffered.webview === webviewRef.current) {
          acceptSelectedTarget(buffered.target);
          return;
        }
        setMode('selecting');
      },
      () => {
        if (submitEpochRef.current !== epoch) return;
        bufferedStartupSelectionRef.current = null;
        // send 已到 guest 但 ACK 丢失时,guest 可能已经挂上 overlay。失败路径
        // 必须与用户主动退出走同一套清理,不能只关闭 host 按钮状态。
        abortModePreservingDraft();
        toast.error(tRef.current('rightSidebar.browser.commentFailed'));
      },
    );
  }, [abortModePreservingDraft, acceptSelectedTarget, composerDraftKey, exitMode, sendCommand]);

  const submit = useCallback(
    (commentText: string, styleChanges?: BrowserCommentStyleChange[]) => {
      const target = pendingTarget;
      if (!target || modeRef.current !== 'pending') return;
      // 有样式改动时允许空评论(标注本身就是诉求);两者皆空不提交。
      if (!commentText.trim() && !(styleChanges && styleChanges.length > 0)) return;
      doSubmit(target, commentText, styleChanges);
    },
    [doSubmit, pendingTarget],
  );

  const previewDesign = useCallback(
    (payload: BrowserCommentDesignPreviewPayload) => {
      if (modeRef.current !== 'pending') return;
      sendNotification(BROWSER_COMMENT_DESIGN_PREVIEW_CHANNEL, payload);
    },
    [sendNotification],
  );
  const resetDesign = useCallback(() => {
    sendNotification(BROWSER_COMMENT_DESIGN_RESET_CHANNEL);
  }, [sendNotification]);

  /**
   * 当前 WebView 代际的唯一事件绑定点。useBrowserWebview 在延迟创建、LRU
   * 淘汰和崩溃重建时都会发布新对象,因此 layout effect 会在浏览器可交互
   * 之前精确拆旧挂新并更新 send target,消除普通 effect 前 ref 仍指向旧
   * generation 的点击窗口。
   */
  useLayoutEffect(() => {
    const previousWebview = webviewRef.current;
    webviewRef.current = webview;
    if (previousWebview && previousWebview !== webview) {
      const committedEpoch = committedSubmissionEpochRef.current;
      submitEpochRef.current += 1;
      bufferedStartupSelectionRef.current = null;
      if (committedEpoch !== null) {
        settleCommittedSubmission(committedEpoch, 'off');
      } else if (
        modeRef.current === 'pending' ||
        modeRef.current === 'submitting' ||
        pendingTargetRef.current
      ) {
        toast.error(tRef.current('rightSidebar.browser.commentFailed'));
      }
      setMode('off');
      setPendingTarget(null);
    }
    if (!webview) return;

    const onIpcMessage = (e: Electron.IpcMessageEvent) => {
      switch (e.channel) {
        case BROWSER_COMMENT_COMMAND_RESULT_CHANNEL: {
          const result = e.args[0] as BrowserCommentCommandResult | undefined;
          if (
            !result ||
            typeof result.requestId !== 'string' ||
            typeof result.command !== 'string' ||
            typeof result.ok !== 'boolean'
          ) {
            return;
          }
          const pending = pendingCommandsRef.current.get(result.requestId);
          if (!pending || pending.webview !== webview || pending.command !== result.command) {
            return;
          }
          clearTimeout(pending.timer);
          pendingCommandsRef.current.delete(result.requestId);
          if (result.ok) {
            pending.resolve();
          } else {
            pending.reject(new Error(`browser comment guest rejected: ${result.command}`));
          }
          return;
        }
        case BROWSER_COMMENT_ELEMENT_SELECTED_CHANNEL: {
          const currentMode = modeRef.current;
          if (currentMode !== 'starting' && currentMode !== 'selecting') return;
          const info = e.args[0] as BrowserCommentTargetInfo | undefined;
          if (!info || typeof info !== 'object') return;
          if (currentMode === 'starting') {
            // enterMode 会在统一 ACK 前同步上报页面已有文本选区。只保留当前
            // generation / epoch 的第一条选择;guest 一旦 pending 不会再发第二条。
            bufferedStartupSelectionRef.current ??= {
              webview,
              epoch: submitEpochRef.current,
              target: info,
            };
            return;
          }
          acceptSelectedTarget(info);
          return;
        }
        case BROWSER_COMMENT_MODE_EXITED_CHANNEL: {
          // guest 内按了 Esc,overlay 已自拆 —— host 只同步状态。
          const committedEpoch = committedSubmissionEpochRef.current;
          submitEpochRef.current += 1; // 作废任何挂起中的提交
          bufferedStartupSelectionRef.current = null;
          clearEditorDraft();
          if (committedEpoch !== null && settleCommittedSubmission(committedEpoch, 'off')) return;
          setMode('off');
          setPendingTarget(null);
          return;
        }
        default:
      }
    };
    const onNavigate = () => {
      if (modeRef.current === 'off') return;
      abortModePreservingDraftRef.current();
    };
    webview.addEventListener('ipc-message', onIpcMessage);
    webview.addEventListener('did-navigate', onNavigate);
    webview.addEventListener('did-navigate-in-page', onNavigate);
    return () => {
      webview.removeEventListener('ipc-message', onIpcMessage);
      webview.removeEventListener('did-navigate', onNavigate);
      webview.removeEventListener('did-navigate-in-page', onNavigate);
      rejectCommandsForWebview(webview);
    };
  }, [
    acceptSelectedTarget,
    clearEditorDraft,
    rejectCommandsForWebview,
    settleCommittedSubmission,
    webview,
  ]);

  // A retained host no longer unmounts on task switches or sidebar collapse.
  // Use the existing abort path to invalidate pending work and remove the guest
  // blocker, while keeping unfinished host text/design edits recoverable.
  useLayoutEffect(() => {
    if (!visible && modeRef.current !== 'off') {
      // Abort increments the epoch before rejecting pending IPC promises, so
      // their continuations cannot restore selection or report a stale error.
      abortModePreservingDraft();
      if (webview) rejectCommandsForWebview(webview);
    }
  }, [visible, abortModePreservingDraft, rejectCommandsForWebview, webview]);

  // tab 卸载时若模式仍开着,通知 guest 拆 overlay(webview 被 pool 保活,
  // 不通知的话 overlay 会一直趴在页面上)。
  useEffect(() => {
    return () => {
      if (modeRef.current !== 'off') exitModeRef.current();
    };
  }, [tabId]);

  return {
    mode,
    pendingTarget,
    editorDraft,
    updateEditorDraft,
    toggle,
    cancelPending,
    submit,
    previewDesign,
    resetDesign,
  };
}