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。

11.2 KB
Raw Blame
/**
 * 隐藏期装饰动画闸门 —— 窗口对用户不可见时冻结常驻 infinite 装饰动画。
 *
 * 背景:主窗 `backgroundThrottling` 默认开着,但 bootstrap-electron 的
 * `setMainWindowBackgroundThrottlingForActiveTurn` 在有 running turn 时会主动
 * 关掉它(保证 agent 流式输出与 IPC 不被后台降频)。副作用是:挂着一批 agent 跑、
 * 人切去别的应用时,隐藏窗口里的无限循环装饰动画仍在全速推进并持续触发样式重算。
 *
 * 实测(2026-07-27,ABAB 四轮配对,低负载环境):10 个常驻动画令样式重算 29.8/s,
 * 暂停后降到 5.7/s(-81%),该 renderer 进程 CPU 12.4% → 6.0%。动画数随运行中的
 * 会话数线性增长(22 个动画时实测差值 40.2/s),会话越多代价越高。
 *
 * ## 为什么要两路信号
 *
 * 单靠 `document.visibilityState` 不行:Electron 规定 `backgroundThrottling` 关闭时
 * visibilityState 会一直停在 `'visible'`,即便窗口已最小化或 hide()。而本模块要救的
 * 正是「有 running turn(节流被关) + 人切走」这个场景,只认 visibilityState 等于永远
 * 不触发。已在 Electron 41.2.0 / macOS 实测复现:
 *
 *   backgroundThrottling=true   minimize()/hide() → visibilityState 转 'hidden'  ✅
 *   backgroundThrottling=false  minimize()/hide() → visibilityState 仍 'visible' ❌
 *
 * 所以再接一路 main 侧广播(`onWindowHiddenChange`,基于 BrowserWindow 的
 * hide/show/minimize/restore 事件),两路取「或」:
 *
 *   - main 广播:不受节流影响,覆盖最小化与 hide;
 *   - visibilityState:覆盖 macOS 的窗口遮挡(occlusion)——那个没有对应的 Electron
 *     事件,只能靠它。
 *
 * 已知局限:Windows 的窗口遮挡两路都盖不到(Electron 文档写明 occlusion 只在 macOS
 * 影响可见性)。此时表现为「不冻结」,即退回改动前的行为,不会误冻可见窗口。
 *
 * 只认可见性,不认 focus —— 副屏场景下窗口失焦但仍然可见,按失焦暂停会被用户直接
 * 看到。
 *
 * ## 两种暂停手段
 *
 * - **宿主文档**:翻 `documentElement` 上的 `data-app-hidden`,由 globals.css 的冻结
 *   清单接管。声明式覆盖,隐藏期间新挂载的元素自动纳入;清单只列 infinite 装饰动画,
 *   一次性动画刻意不进,免得被冻在中途帧。
 * - **Ghost 卡片 srcDoc iframe**:CSS 跨不进子文档,且卡内动画是意识现画的、没有可枚举
 *   清单,只能走 Web Animations API 逐个判 `iterations === Infinity`(见
 *   `syncFrameAnimations`)。用 JS 而非往 srcDoc 注一条通配 CSS,正是为了保住上面那条
 *   「不冻一次性动画」的性质。
 */
/**
 * 冻结标记的属性名。单一来源:CSS(globals.css 的冻结清单、GhostToolCard 注入进 srcDoc 的
 * 规则)与 JS(本模块、iframe 传播、卡片 onLoad 对齐)必须用同一个名字,分散写字面量迟早
 * 漏改。CSS 侧没法 import 常量,由 hiddenAnimationGate.test.ts 断言两边一致。
 */
export const HIDDEN_ANIMATION_ATTR = 'data-app-hidden';

const HIDDEN_ATTR = HIDDEN_ANIMATION_ATTR;

/** 存放 disposer 的槽位:本模块自有的私有约定,不在 lib.dom 的 Window 声明里。 */
interface GateWindow {
  __xdtHiddenAnimationGateDisposer?: () => void;
  /**
   * 最近一次 main 广播的窗口隐藏态。必须跨重装存活:preload 的 createIpcFanOut 不会向
   * 新订阅者回放最后一次 payload,而 HMR 重装时页面没有重新加载、也就不会触发 main 侧
   * did-finish-load 的补发。不缓存的话,「窗口已隐藏 + 节流关闭(visibilityState 恒为
   * visible)」时重装,闸门会一直等不到下一次 hide/minimize 而静默失效。
   */
  __xdtHiddenAnimationGateLastHidden?: boolean;
  /**
   * 本闸门暂停过的子文档动画。挂在 window 上而非闭包里,因为隐藏期间新挂载的卡片要在
   * 自己的 onLoad 里登记进来(见 alignFrameWithGate)——不登记的话恢复路径不会 play 它们,
   * 卡片动画会永久停住。同时跨重装存活,理由同 LastHidden。
   */
  __xdtHiddenAnimationGatePausedAnims?: Set<GateAnimation>;
  /** main 侧窗口可见性广播;非 Electron 宿主(单测 / 纯浏览器)下缺省。 */
  electronAPI?: {
    onWindowHiddenChange?: (callback: (hidden: boolean) => void) => () => void;
  };
}

/** 注入面,让单测能用假 document/visibilityState/IPC 驱动。 */
export interface HiddenAnimationGateTarget {
  document: Pick<Document, 'addEventListener' | 'removeEventListener'> & {
    readonly visibilityState: DocumentVisibilityState;
    readonly documentElement: Pick<Element, 'setAttribute' | 'removeAttribute'>;
    /** 用于把冻结标记传播进同源子文档(Ghost 卡片的 srcDoc iframe)。 */
    querySelectorAll?: (selectors: string) => ArrayLike<HiddenAnimationGateFrame>;
  };
  window: GateWindow;
}

/** 子文档里一个动画的最小面(Web Animations API 的子集)。 */
export interface GateAnimation {
  readonly playState?: string;
  effect?: { getTiming?: () => { iterations?: number } } | null;
  pause?: () => void;
  play?: () => void;
}

/** iframe 的最小面:同源子文档 + 其动画清单。 */
export interface HiddenAnimationGateFrame {
  readonly contentDocument?: {
    getAnimations?: () => ArrayLike<GateAnimation>;
  } | null;
}

/** 判断一个动画是不是无限循环。 */
export function isLoopingAnimation(anim: GateAnimation): boolean {
  return anim.effect?.getTiming?.()?.iterations === Infinity;
}

/** 子文档的最小面:只需要能列出自己的动画。 */
export interface GateFrameDocument {
  getAnimations?: () => ArrayLike<GateAnimation>;
}

/**
 * 让一个刚加载完的子文档跟上当前闸门状态 —— 供 Ghost 卡片在 iframe onLoad 时调用。
 *
 * 窗口可能在这张卡挂载之前就已隐藏,那时闸门的遍历还看不到这个 iframe。**关键是必须把
 * 暂停的动画登记进闸门的共享集合**:恢复路径只 play 集合里的,漏登记 = 这张卡的动画永久
 * 停住(窗口切回来也不动)。所以这里不自己维护记账,直接复用 window 上那份。
 *
 * 只停无限循环的;有限动画照播 —— 冻在中途帧、恢复时才接着播才是突兀的那种。
 */
export function alignFrameWithGate(
  frameDoc: GateFrameDocument,
  hostDocument: Pick<Document, 'documentElement'> = document,
  hostWindow: GateWindow = window as Window & GateWindow,
): void {
  if (!hostDocument.documentElement.hasAttribute(HIDDEN_ATTR)) return;
  const paused = (hostWindow.__xdtHiddenAnimationGatePausedAnims ??= new Set<GateAnimation>());
  for (const anim of Array.from(frameDoc.getAnimations?.() ?? [])) {
    if (anim.playState !== 'running' || !isLoopingAnimation(anim)) continue;
    anim.pause?.();
    paused.add(anim);
  }
}

/**
 * 把冻结同步进同源子文档(Ghost 卡片的 srcDoc iframe)。
 *
 * Ghost 卡片是 `sandbox="allow-same-origin"` 的 srcDoc iframe,CSS 选择器跨不进去,而
 * cardSanitizer 明确保留意识作者写的动画,所以隐藏期间这些卡片会继续吃渲染。
 *
 * 这里走 Web Animations API 而不是像宿主侧那样注一条 CSS 规则:CSS 选不出「只暂停无限
 * 循环动画」——`animation-play-state` 加在通配选择器上会把有限动画一并冻住,而
 * cardSanitizer 是允许 `animation:f 1s` 这类有限声明的。被冻在中途的有限动画会在窗口
 * 恢复可见时突然从暂停帧接着播,正是宿主侧 allowlist 刻意规避的那种突兀感。
 * `getAnimations()` 能逐个读 timing,精确只停 `iterations === Infinity` 的。
 *
 * 恢复时只 play 本闸门暂停过的那些,不动意识自己 pause 的动画 —— 调用方传入 paused 集合
 * 承担这份记账。跨源 iframe 读 contentDocument 会抛,逐个吞掉即可。
 */
export function syncFrameAnimations(
  doc: HiddenAnimationGateTarget['document'],
  hidden: boolean,
  pausedByGate: Set<GateAnimation>,
): void {
  const frames = doc.querySelectorAll?.('iframe');
  if (!frames) return;
  for (let i = 0; i < frames.length; i++) {
    try {
      const anims = frames[i]?.contentDocument?.getAnimations?.();
      if (!anims) continue;
      for (let j = 0; j < anims.length; j++) {
        const anim = anims[j];
        if (!anim) continue;
        if (hidden) {
          if (anim.playState !== 'running' || !isLoopingAnimation(anim)) continue;
          anim.pause?.();
          pausedByGate.add(anim);
        } else if (pausedByGate.has(anim)) {
          anim.play?.();
          pausedByGate.delete(anim);
        }
      }
    } catch {
      // 跨源 / 已卸载的 frame:跳过
    }
  }
  // 解冻时清账:已卸载的卡片对应的动画对象不会再出现在任何 frame 里。
  if (!hidden) pausedByGate.clear();
}

function defaultTarget(): HiddenAnimationGateTarget {
  return { document, window: window as Window & GateWindow };
}

export function installHiddenAnimationGate(
  target: HiddenAnimationGateTarget = defaultTarget(),
): () => void {
  // 重复安装时先拆旧的,避免同一 document 上挂多份监听。
  target.window.__xdtHiddenAnimationGateDisposer?.();

  // main 广播的窗口态。优先复用上一轮缓存(HMR 重装时窗口可能已经是隐藏的,
  // 见 GateWindow 上该字段的注释);首次安装则按「未隐藏」起步 —— 窗口刚建出来就是
  // 可见的,真隐藏了 main 侧 did-finish-load 的补发会立刻纠正。
  let windowHidden = target.window.__xdtHiddenAnimationGateLastHidden ?? false;
  // 本闸门暂停过的子文档动画,解冻时只 play 这些,不动意识自己 pause 的。挂在 window 上
  // 共享:隐藏期间新挂载的卡片走 alignFrameWithGate 往同一份集合里登记。
  const pausedFrameAnimations = (target.window.__xdtHiddenAnimationGatePausedAnims ??=
    new Set<GateAnimation>());

  const apply = (): void => {
    const hidden = windowHidden || target.document.visibilityState === 'hidden';
    if (hidden) {
      target.document.documentElement.setAttribute(HIDDEN_ATTR, 'true');
    } else {
      target.document.documentElement.removeAttribute(HIDDEN_ATTR);
    }
    // 已挂载的同源子文档跟着翻。隐藏期间新建的 iframe 由挂载方(GhostToolCard 的
    // onLoad)自己对齐一次,那条路径不经过这里。
    syncFrameAnimations(target.document, hidden, pausedFrameAnimations);
  };

  // 安装时先对齐一次:窗口可能已经处于隐藏态(例如启动后立刻切走)。
  apply();
  target.document.addEventListener('visibilitychange', apply);

  const unsubscribeWindowHidden = target.window.electronAPI?.onWindowHiddenChange?.((hidden) => {
    windowHidden = hidden;
    target.window.__xdtHiddenAnimationGateLastHidden = hidden;
    apply();
  });

  const dispose = (): void => {
    target.document.removeEventListener('visibilitychange', apply);
    unsubscribeWindowHidden?.();
    // 拆闸门时一律恢复动画,不把页面(及子文档)留在冻结态。
    target.document.documentElement.removeAttribute(HIDDEN_ATTR);
    syncFrameAnimations(target.document, false, pausedFrameAnimations);
    if (target.window.__xdtHiddenAnimationGateDisposer === dispose) {
      delete target.window.__xdtHiddenAnimationGateDisposer;
    }
  };

  target.window.__xdtHiddenAnimationGateDisposer = dispose;
  return dispose;
}