@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/collab/__tests__/use-presence-list-refresh.test.tsx

@@ -0,0 +1,309 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// usePresenceListRefresh 单元测试（任务 24，§7.1 列表行「列表查询缓存 observe
+// 失效刷新」的控制者裁决落地——列表页不建连实体 room，presence 变化为弱信号）：
+//   ① 挂载即有在场成员 → 不刷新（首屏数据刚加载，presence 快照不作信号）
+//   ② 成员进入实体详情（detail section）→ 防抖后刷新 1 次
+//   ③ 心跳续报（ts 刷新、id+route 不变）→ 不刷新
+//   ④ 列表页 presence（section list）→ 不刷新
+//   ⑤ 其他模块的实体详情 → 不刷新
+//   ⑥ 成员离开实体（快照少人）→ 刷新
+//   ⑦ 卸载后 presence 变化 → 不再刷新
+//   ⑧ 轮询到期 → 刷新（refetchInterval 惯例）
+//   ⑨ 窗口回前台 → 刷新（refetchOnWindowFocus 惯例）
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act, cleanup } from "@testing-library/react";
+
+import {
+  __resetPresenceStoreForTests,
+  presenceActions,
+} from "@/lib/collab/presence-store";
+import { usePresenceListRefresh } from "../use-presence-list-refresh";
+
+function teammate(
+  id: string,
+  username: string,
+  module: string,
+  extra: Record<string, unknown> = {},
+) {
+  return {
+    user: { id, username, bgShape: "circle", bgColor: "#fff" },
+    module,
+    route: "/stories",
+    ts: Date.now(),
+    ...extra,
+  };
+}
+
+beforeEach(() => {
+  __resetPresenceStoreForTests();
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+describe("usePresenceListRefresh", () => {
+  it("挂载即有在场成员 → 不刷新（presence 快照不作信号）", () => {
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail" }),
+    );
+    const refresh = vi.fn();
+    renderHook(() => usePresenceListRefresh({ module: "stories", refresh }));
+
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+    expect(refresh).not.toHaveBeenCalled();
+  });
+
+  it("成员进入实体详情 → 防抖窗口后刷新 1 次（连续变化合并）", async () => {
+    const refresh = vi.fn();
+    renderHook(() =>
+      usePresenceListRefresh({ module: "stories", refresh, debounceMs: 50 }),
+    );
+
+    act(() => {
+      presenceActions.applyRemote(
+        teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail" }),
+      );
+    });
+    act(() => {
+      presenceActions.applyRemote(
+        teammate("u2", "bob", "stories", { route: "/stories/2", section: "detail" }),
+      );
+    });
+
+    // 防抖窗口内不调用
+    act(() => {
+      vi.advanceTimersByTime(20);
+    });
+    expect(refresh).not.toHaveBeenCalled();
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(100);
+    });
+    expect(refresh).toHaveBeenCalledTimes(1);
+  });
+
+  it("心跳续报（ts 刷新、id+route 不变）→ 不刷新", async () => {
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail" }),
+    );
+    const refresh = vi.fn();
+    renderHook(() =>
+      usePresenceListRefresh({ module: "stories", refresh, debounceMs: 20 }),
+    );
+
+    act(() => {
+      presenceActions.applyRemote(
+        teammate("u1", "alice", "stories", {
+          route: "/stories/1",
+          section: "detail",
+          ts: Date.now() + 1000,
+        }),
+      );
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+    expect(refresh).not.toHaveBeenCalled();
+  });
+
+  it("成员停留在模块列表页（section list）→ 不刷新", async () => {
+    const refresh = vi.fn();
+    renderHook(() =>
+      usePresenceListRefresh({ module: "stories", refresh, debounceMs: 20 }),
+    );
+
+    act(() => {
+      presenceActions.applyRemote(
+        teammate("u1", "alice", "stories", { route: "/stories", section: "list" }),
+      );
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+    expect(refresh).not.toHaveBeenCalled();
+  });
+
+  it("其他模块的实体详情变化 → 不刷新", async () => {
+    const refresh = vi.fn();
+    renderHook(() =>
+      usePresenceListRefresh({ module: "stories", refresh, debounceMs: 20 }),
+    );
+
+    act(() => {
+      presenceActions.applyRemote(
+        teammate("u1", "alice", "bugs", { route: "/bugs/1", section: "detail" }),
+      );
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+    expect(refresh).not.toHaveBeenCalled();
+  });
+
+  it("成员离开实体（全量快照少人）→ 刷新", async () => {
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail" }),
+    );
+    const refresh = vi.fn();
+    renderHook(() =>
+      usePresenceListRefresh({ module: "stories", refresh, debounceMs: 20 }),
+    );
+
+    act(() => {
+      presenceActions.remove("u1");
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+    expect(refresh).toHaveBeenCalledTimes(1);
+  });
+
+  it("section 缺省的实体路由（旧端兼容）→ 仍视为实体在看并刷新", async () => {
+    const refresh = vi.fn();
+    renderHook(() =>
+      usePresenceListRefresh({ module: "stories", refresh, debounceMs: 20 }),
+    );
+
+    act(() => {
+      presenceActions.applyRemote(
+        teammate("u1", "alice", "stories", { route: "/stories/1" }),
+      );
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+    expect(refresh).toHaveBeenCalledTimes(1);
+  });
+
+  it("卸载后 presence 变化 → 不再刷新", async () => {
+    const refresh = vi.fn();
+    const { unmount } = renderHook(() =>
+      usePresenceListRefresh({ module: "stories", refresh, debounceMs: 20 }),
+    );
+    unmount();
+
+    act(() => {
+      presenceActions.applyRemote(
+        teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail" }),
+      );
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+    expect(refresh).not.toHaveBeenCalled();
+  });
+
+  it("轮询到期 → 刷新（refetchInterval 惯例；pollIntervalMs=0 关闭）", async () => {
+    const refresh = vi.fn();
+    renderHook(() =>
+      usePresenceListRefresh({
+        module: "stories",
+        refresh,
+        debounceMs: 10,
+        pollIntervalMs: 100,
+      }),
+    );
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(350);
+    });
+    expect(refresh.mock.calls.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("窗口回前台 → 刷新（refetchOnWindowFocus 惯例）", async () => {
+    const refresh = vi.fn();
+    renderHook(() =>
+      usePresenceListRefresh({ module: "stories", refresh, debounceMs: 20 }),
+    );
+
+    act(() => {
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+    expect(refresh).toHaveBeenCalledTimes(1);
+  });
+
+  it("refresh 回调用最新闭包（签名变化后重拉取当次筛选）", async () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = renderHook(
+      ({ refresh }) => usePresenceListRefresh({ module: "stories", refresh, debounceMs: 20 }),
+      { initialProps: { refresh: first as () => void } },
+    );
+    rerender({ refresh: second as () => void });
+
+    act(() => {
+      presenceActions.applyRemote(
+        teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail" }),
+      );
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it("心跳式 state 重建（签名未变）→ 列表视图组件零重渲染、不刷新（审查重要①）", async () => {
+    presenceActions.applyRemote(
+      teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail", ts: 100 }),
+    );
+    const refresh = vi.fn();
+    let renders = 0;
+    renderHook(() => {
+      renders += 1;
+      usePresenceListRefresh({ module: "stories", refresh, debounceMs: 20 });
+    });
+    const afterMount = renders;
+
+    act(() => {
+      // u1 心跳续报（ts 前进、id+route 不变，syncRemote 全量重建口径的新对象）
+      presenceActions.applyRemote(
+        teammate("u1", "alice", "stories", { route: "/stories/1", section: "detail", ts: 200 }),
+      );
+      // 其他模块成员心跳（同样触发 store 更新，但不影响本模块签名）
+      presenceActions.applyRemote(
+        teammate("u2", "bob", "bugs", { route: "/bugs/1", section: "detail", ts: 200 }),
+      );
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+    expect(renders).toBe(afterMount);
+    expect(refresh).not.toHaveBeenCalled();
+
+    // 对照：签名真变（成员离开实体）→ 恢复重渲染 + 刷新
+    act(() => {
+      presenceActions.remove("u1");
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(200);
+    });
+    expect(renders).toBeGreaterThan(afterMount);
+    expect(refresh).toHaveBeenCalledTimes(1);
+  });
+});

package/src/lib/collab/__tests__/use-presence-report.test.ts

@@ -0,0 +1,356 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// usePresenceReport hook 层测试（renderHook + 假计时器，审查重要③）：
+//   ① 路由变化 2s 节流上报——leading 首报即时、窗口内导航被节流、
+//      尾随只保留最后一次（若未删未节流直调，本组用例即红，审查②回归）
+//   ② 心跳续报——15s 无导航也刷新 ts，30s+ 挂机不出摘除窗口
+//      （审查关键①回归：仅路由变化续报会让在线用户被 pruneStale 误摘）
+//   ③ 远端摘除时序——stop 心跳的远端（ts 过期）被 pruneStale 摘除、
+//      活跃远端保留
+//   ④ 卸载清理——setLocalState(null) 离场 + destroyProvider + 心跳停止
+//
+// 依赖 mock：serverFns（引导/ticket）、provider（FakeAwareness 内存实现，
+// 不引真 y-protocols——pnpm 严格隔离下 apps/web 不可直依赖）、env、
+// @tanstack/react-router 的 useLocation（可控 pathname）。pacer 节流走
+// 真实现（假计时器驱动 setTimeout 与 Date.now）。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import {
+  __resetPresenceStoreForTests,
+  presenceActions,
+  presenceStore,
+} from '../presence-store'
+import { HEARTBEAT_INTERVAL_MS } from '../use-presence-report'
+
+const currentPathname = vi.hoisted(() => ({ value: '/stories' }))
+
+vi.mock('@tanstack/react-router', () => ({
+  useLocation: () => ({ pathname: currentPathname.value }),
+}))
+
+const mocks = vi.hoisted(() => ({
+  getPresenceRoomFn: vi.fn(),
+  createPresenceTicketFn: vi.fn(),
+  getOrCreateProvider: vi.fn(),
+  destroyProvider: vi.fn(),
+  isCollabEnabled: vi.fn((): boolean => true),
+}))
+
+vi.mock('@/server/serverFns/collab-presence', () => ({
+  getPresenceRoomFn: mocks.getPresenceRoomFn,
+  createPresenceTicketFn: mocks.createPresenceTicketFn,
+}))
+
+vi.mock('../provider', () => ({
+  getOrCreateProvider: mocks.getOrCreateProvider,
+  destroyProvider: mocks.destroyProvider,
+}))
+
+vi.mock('../env', () => ({ isCollabEnabled: mocks.isCollabEnabled }))
+
+import { usePresenceReport } from '../use-presence-report'
+
+// ---------------------------------------------------------------------------
+// FakeAwareness / FakeProvider（内存实现，接口面与 hook 消费一致）
+// ---------------------------------------------------------------------------
+
+type UpdateHandler = (update: unknown) => void
+
+class FakeAwareness {
+  clientID = 1
+  localState: Record<string, unknown> | null = null
+  /** 远端 client 的 state（不含本地；getStates 时合并） */
+  remotes = new Map<number, Record<string, unknown>>()
+  private listeners = new Set<UpdateHandler>()
+  /** setLocalState 全部写入记录（含卸载的 null 离场写） */
+  writes: Array<Record<string, unknown> | null> = []
+
+  setLocalState(state: Record<string, unknown> | null): void {
+    this.localState = state
+    this.writes.push(state)
+    this.emit()
+  }
+
+  getStates(): Map<number, Record<string, unknown>> {
+    const all = new Map(this.remotes)
+    if (this.localState) all.set(this.clientID, this.localState)
+    return all
+  }
+
+  on(_event: string, handler: UpdateHandler): void {
+    this.listeners.add(handler)
+  }
+
+  off(_event: string, handler: UpdateHandler): void {
+    this.listeners.delete(handler)
+  }
+
+  emit(): void {
+    for (const handler of [...this.listeners]) {
+      handler({ added: [], updated: [], removed: [] })
+    }
+  }
+
+  addRemote(clientId: number, state: Record<string, unknown>): void {
+    this.remotes.set(clientId, state)
+    this.emit()
+  }
+}
+
+interface FakeHandle {
+  roomName: string
+  awareness: FakeAwareness
+  statusListener: ((status: string) => void) | null
+  onStatusChange(listener: (status: string) => void): () => void
+}
+
+function makeFakeHandle(awareness: FakeAwareness): FakeHandle {
+  const handle: FakeHandle = {
+    roomName: 'presence:team:t1',
+    awareness,
+    statusListener: null,
+    onStatusChange(listener) {
+      handle.statusListener = listener
+      listener('connecting') // 对齐 provider 语义：立即回放当前状态
+      return () => {
+        handle.statusListener = null
+      }
+    },
+  }
+  return handle
+}
+
+/** 引导 mock 就位并挂载 hook，返回 awareness 便于断言 */
+async function mountHook() {
+  const awareness = new FakeAwareness()
+  const handle = makeFakeHandle(awareness)
+  mocks.getPresenceRoomFn.mockResolvedValue({
+    ownerId: 'me',
+    roomName: handle.roomName,
+    user: { id: 'u-self', username: 'self', bgShape: 'square', bgColor: '#fff' },
+  })
+  mocks.getOrCreateProvider.mockImplementation(() => handle)
+  const rendered = renderHook(() => usePresenceReport())
+  // flush 引导 promise（getPresenceRoomFn → provider 接线全部微任务）
+  await act(async () => {
+    await Promise.resolve()
+    await Promise.resolve()
+  })
+  return { ...rendered, awareness, handle }
+}
+
+function remoteState(userId: string, module: string, ts: number) {
+  return {
+    user: { id: userId, username: userId, bgShape: 'square', bgColor: '#fff' },
+    module,
+    route: `/${module}`,
+    ts,
+  }
+}
+
+beforeEach(() => {
+    vi.useFakeTimers()
+  currentPathname.value = '/stories'
+  __resetPresenceStoreForTests()
+  mocks.getPresenceRoomFn.mockReset()
+  mocks.createPresenceTicketFn.mockReset()
+  mocks.getOrCreateProvider.mockReset()
+  mocks.destroyProvider.mockReset()
+  mocks.isCollabEnabled.mockReturnValue(true)
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+})
+
+// ---------------------------------------------------------------------------
+// ① 路由变化 2s 节流上报
+// ---------------------------------------------------------------------------
+
+describe('usePresenceReport 路由上报节流', () => {
+  it('挂载引导完成即首报（leading 即时，不等路由变化）', async () => {
+    const { awareness } = await mountHook()
+    expect(awareness.writes).toHaveLength(1)
+    expect(awareness.writes[0]).toMatchObject({
+      module: 'stories',
+      route: '/stories',
+      user: { id: 'u-self' },
+    })
+  })
+
+  it('2s 窗口内的路由变化被节流，尾随只报最后一次', async () => {
+    const { awareness, rerender } = await mountHook()
+    expect(awareness.writes).toHaveLength(1) // leading：/stories
+
+    // +0.5s 导航 /bugs：窗口内 → 即时不写
+    vi.advanceTimersByTime(500)
+    currentPathname.value = '/bugs'
+    rerender()
+    await act(async () => {})
+    expect(awareness.writes).toHaveLength(1)
+
+    // +0.6s 再导航 /design：仍在窗口内 → 被合并
+    vi.advanceTimersByTime(600)
+    currentPathname.value = '/design'
+    rerender()
+    await act(async () => {})
+
+    // 满 2s：尾随一次，直接落最后路径
+    vi.advanceTimersByTime(900)
+    expect(awareness.writes).toHaveLength(2)
+    expect(awareness.writes[1]).toMatchObject({ module: 'design', route: '/design' })
+  })
+
+  it('leading 触发后窗口重新计时，窗口内导航被合并不旁路（审查②回归）', async () => {
+    const { awareness, rerender } = await mountHook()
+    expect(awareness.writes).toHaveLength(1) // 首报来自引导直调
+
+    // +2.1s 导航 /bugs：窗口已过 → leading 即时广播（合法）
+    vi.advanceTimersByTime(2100)
+    currentPathname.value = '/bugs'
+    rerender()
+    await act(async () => {})
+    expect(awareness.writes).toHaveLength(2)
+    expect(awareness.writes[1]).toMatchObject({ route: '/bugs' })
+
+    // +0.5s 再导航 /design：新窗口内 → 不得旁路直调立即广播
+    vi.advanceTimersByTime(500)
+    currentPathname.value = '/design'
+    rerender()
+    await act(async () => {})
+    expect(awareness.writes).toHaveLength(2)
+
+    // 尾随补一次，落最后路径
+    vi.advanceTimersByTime(1500)
+    expect(awareness.writes).toHaveLength(3)
+    expect(awareness.writes[2]).toMatchObject({ route: '/design' })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ② 心跳续报（审查关键①回归）
+// ---------------------------------------------------------------------------
+
+describe('usePresenceReport 心跳续报', () => {
+  it('15s 无导航也刷新 ts（心跳间隔对齐 awareness keepalive）', async () => {
+    const { awareness } = await mountHook()
+    const first = awareness.writes[0]!
+    expect(first.ts).toBe(Date.now())
+
+    vi.advanceTimersByTime(HEARTBEAT_INTERVAL_MS)
+    const heartbeatWrites = awareness.writes.slice(1)
+    expect(heartbeatWrites.length).toBeGreaterThanOrEqual(1)
+    const latest = heartbeatWrites[heartbeatWrites.length - 1]!
+    expect(latest.route).toBe('/stories') // 路径未变
+    expect(latest.ts as number).toBeGreaterThan(first.ts as number) // ts 已刷新
+  })
+
+  it('挂机 30s+ 持续心跳：ts 始终新鲜，不落摘除窗口', async () => {
+    const { awareness } = await mountHook()
+    vi.advanceTimersByTime(75_000) // 5 个摘除窗口
+    const recent = awareness.writes[awareness.writes.length - 1]!
+    // 最新一次续报距当前假时钟不超过一个心跳间隔 → pruneStale 永不命中
+    expect(Date.now() - (recent.ts as number)).toBeLessThan(
+      HEARTBEAT_INTERVAL_MS * 2,
+    )
+    expect(awareness.writes.length).toBeGreaterThanOrEqual(5)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ③ 远端摘除时序
+// ---------------------------------------------------------------------------
+
+describe('usePresenceReport 远端摘除', () => {
+  it('ts 过期（停心跳）的远端被摘除，活跃远端保留', async () => {
+    const { awareness } = await mountHook()
+    awareness.addRemote(2, remoteState('u-stale', 'bugs', Date.now() - 31_000))
+    awareness.addRemote(3, remoteState('u-live', 'stories', Date.now()))
+    // addRemote 内 emit → hook onAwarenessUpdate：syncRemote + pruneStale
+    const teammates = presenceStore.get().teammates
+    expect([...teammates.keys()]).toEqual(['u-live'])
+  })
+
+  it('远端再次心跳（ts 刷新）后重新可见', async () => {
+    const { awareness } = await mountHook()
+    awareness.addRemote(2, remoteState('u2', 'bugs', Date.now()))
+    expect(presenceStore.get().teammates.has('u2')).toBe(true)
+
+    awareness.remotes.delete(2)
+    awareness.emit() // removed → 快照重建摘除
+    expect(presenceStore.get().teammates.has('u2')).toBe(false)
+
+    awareness.addRemote(2, remoteState('u2', 'bugs', Date.now() + 1))
+    expect(presenceStore.get().teammates.has('u2')).toBe(true)
+  })
+
+  it('自身 state 不进 store（awareness 快照含本地也被过滤）', async () => {
+    const { awareness } = await mountHook()
+    awareness.emit() // getStates 含本地 state（user.id=u-self）
+    expect(presenceStore.get().teammates.size).toBe(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ④ 生命周期与降级
+// ---------------------------------------------------------------------------
+
+describe('usePresenceReport 生命周期', () => {
+  it('卸载：null 离场写 + destroyProvider + 心跳停止', async () => {
+    const { awareness, unmount } = await mountHook()
+    const writesAtUnmount = awareness.writes.length
+    unmount()
+    expect(awareness.writes[awareness.writes.length - 1]).toBeNull()
+    expect(mocks.destroyProvider).toHaveBeenCalledWith('presence:team:t1')
+
+    awareness.writes.length = 0
+    vi.advanceTimersByTime(HEARTBEAT_INTERVAL_MS * 2)
+    expect(awareness.writes).toHaveLength(0) // 心跳已停
+    expect(writesAtUnmount).toBeGreaterThan(0)
+  })
+
+  it('provider offline：store 清空（降级不显示）', async () => {
+    const { handle } = await mountHook()
+    presenceActions.applyRemote(
+      remoteState('u2', 'bugs', Date.now()),
+    )
+    expect(presenceStore.get().teammates.size).toBe(1)
+    act(() => handle.statusListener?.('offline'))
+    expect(presenceStore.get().status).toBe('offline')
+    expect(presenceStore.get().teammates.size).toBe(0)
+  })
+
+  it('引导失败（未登录/网络错误）：静默降级不建连', async () => {
+    mocks.getPresenceRoomFn.mockRejectedValue(new Error('401'))
+    renderHook(() => usePresenceReport())
+    await act(async () => {
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+    expect(mocks.getOrCreateProvider).not.toHaveBeenCalled()
+  })
+
+  it('协同不可用（desktop/无 WS URL）：全链路 no-op', async () => {
+    mocks.isCollabEnabled.mockReturnValue(false)
+    await mountHook()
+    expect(mocks.getPresenceRoomFn).not.toHaveBeenCalled()
+    expect(mocks.getOrCreateProvider).not.toHaveBeenCalled()
+  })
+})