@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/design/canvas/plugins/presence/__tests__/layout.test.ts

@@ -0,0 +1,292 @@
+// 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.
+
+// presence 渲染插件坐标层测试（P4a，任务 25）：
+// 纯函数 computePresenceLayout 用假投影（fromCanvas 注入）+ 假节点表
+// （SceneDocument 数据）验证 board→容器投影、已删节点跳过、非有限防御、
+// 截断与名牌锚点；projectIntoContainer 单测钉住 C1 容器偏移校正
+// （-cRect.left/-cRect.top）——真 Leafer headless 限制下 DOM/坐标层一律
+// 走假投影（memrec 纪律）。
+
+import { describe, expect, it } from 'vitest'
+import { getUserColor } from '@/lib/collab/user-color'
+import type { RemoteCanvasPresence } from '@/lib/collab/bindings/canvas-presence'
+import { BOARD_NODE_ID, createEmptyDoc, type SceneDocument } from '../../../document/types'
+import {
+  PRESENCE_MAX_BOXES_PER_USER,
+  PRESENCE_TAG_HEIGHT_PX,
+  computePresenceLayout,
+  projectIntoContainer,
+} from '../layout'
+
+/** 假投影：board ×2 → client（模拟 zoom=2 的线性引擎投影） */
+const fromCanvasX2 = (x: number, y: number): { x: number; y: number } | null => ({
+  x: x * 2,
+  y: y * 2,
+})
+
+function makeDoc(): SceneDocument {
+  const doc = createEmptyDoc()
+  doc.nodes.push(
+    {
+      id: 'frame-1',
+      kind: 'group',
+      type: 'frame',
+      parentId: BOARD_NODE_ID,
+      x: 100,
+      y: 100,
+      width: 200,
+      height: 200,
+    },
+    {
+      id: 'child-rect',
+      kind: 'shape',
+      type: 'rect',
+      parentId: 'frame-1',
+      x: 10,
+      y: 10,
+      width: 50,
+      height: 50,
+    },
+  )
+  return doc
+}
+
+function makeRemote(overrides: Partial<RemoteCanvasPresence>): RemoteCanvasPresence {
+  return {
+    clientId: 1,
+    userId: 'u-1',
+    name: '阿蓝',
+    selection: [],
+    viewport: { x: 0, y: 0, zoom: 1 },
+    ts: 1,
+    ...overrides,
+  }
+}
+
+describe('computePresenceLayout', () => {
+  it('board→client 投影（嵌套节点累计父偏移，nodeAbsoluteRect 口径）', () => {
+    const layout = computePresenceLayout({
+      doc: makeDoc(),
+      remotes: [makeRemote({ selection: ['child-rect'] })],
+      fromCanvas: fromCanvasX2,
+      colorOf: () => '#ff0000',
+    })
+    expect(layout).toHaveLength(1)
+    const entry = layout[0]!
+    // child(10,10) in frame(100,100) → board(110,110,50,50) → ×2 → (220,220,100,100)
+    expect(entry.boxes).toEqual([{ x: 220, y: 220, width: 100, height: 100 }])
+    // 名牌锚在首个框上方（间距 6px）
+    expect(entry.tag).toEqual({
+      x: 220,
+      y: 220 - PRESENCE_TAG_HEIGHT_PX - 6,
+      name: '阿蓝',
+      count: 1,
+    })
+    expect(entry.color).toBe('#ff0000')
+    expect(entry.selectionCount).toBe(1)
+  })
+
+  it('已删除节点跳过（不定位不渲染框），计数保留真实选中数', () => {
+    const layout = computePresenceLayout({
+      doc: makeDoc(),
+      remotes: [makeRemote({ selection: ['gone', 'child-rect'] })],
+      fromCanvas: fromCanvasX2,
+      colorOf: () => '#ff0000',
+    })
+    expect(layout[0]!.boxes).toHaveLength(1)
+    expect(layout[0]!.selectionCount).toBe(2)
+    expect(layout[0]!.tag?.count).toBe(2)
+  })
+
+  it('全部选中已删除 → 无框无名牌（用户仍在查看列表）', () => {
+    const layout = computePresenceLayout({
+      doc: makeDoc(),
+      remotes: [makeRemote({ selection: ['gone'] })],
+      fromCanvas: fromCanvasX2,
+      colorOf: () => '#ff0000',
+    })
+    expect(layout[0]!.boxes).toEqual([])
+    expect(layout[0]!.tag).toBeNull()
+  })
+
+  it('投影返回 null（引擎未就绪/离屏）时跳过该框', () => {
+    const layout = computePresenceLayout({
+      doc: makeDoc(),
+      remotes: [makeRemote({ selection: ['child-rect'] })],
+      fromCanvas: () => null,
+      colorOf: () => '#ff0000',
+    })
+    expect(layout[0]!.boxes).toEqual([])
+    expect(layout[0]!.tag).toBeNull()
+  })
+
+  it('单用户渲染框截断到上限（防 select-all 万节点 DOM 爆炸），计数不截断', () => {
+    const ids = Array.from({ length: PRESENCE_MAX_BOXES_PER_USER + 10 }, (_, i) => `n${i}`)
+    const doc = makeDoc()
+    for (const id of ids) {
+      doc.nodes.push({
+        id,
+        kind: 'shape',
+        type: 'rect',
+        parentId: BOARD_NODE_ID,
+        x: 0,
+        y: 0,
+        width: 10,
+        height: 10,
+      })
+    }
+    const layout = computePresenceLayout({
+      doc,
+      remotes: [makeRemote({ selection: ids })],
+      fromCanvas: fromCanvasX2,
+      colorOf: () => '#ff0000',
+    })
+    expect(layout[0]!.boxes).toHaveLength(PRESENCE_MAX_BOXES_PER_USER)
+    expect(layout[0]!.selectionCount).toBe(ids.length)
+    expect(layout[0]!.tag?.count).toBe(ids.length)
+  })
+
+  it('空选择用户保留在列表（查看徽标数据面），无渲染元素', () => {
+    const layout = computePresenceLayout({
+      doc: makeDoc(),
+      remotes: [
+        makeRemote({ clientId: 2, userId: 'u-2', selection: [] }),
+        makeRemote({ clientId: 1, userId: 'u-1', selection: ['child-rect'] }),
+      ],
+      fromCanvas: fromCanvasX2,
+    })
+    expect(layout).toHaveLength(2)
+    // 输入顺序保持（readRemotes 已按 clientID 稳定排序，此处不重排）
+    expect(layout[0]!.userId).toBe('u-2')
+    expect(layout[0]!.boxes).toEqual([])
+    expect(layout[1]!.userId).toBe('u-1')
+    // colorOf 缺省走 getUserColor（8 色板确定性映射）
+    expect(layout[0]!.color).toBe(getUserColor('u-2'))
+    expect(layout[1]!.color).toBe(getUserColor('u-1'))
+  })
+
+  it('投影非有限值（NaN）拒绝下发该框（对齐引擎 toCanvas 防御口径）', () => {
+    const layout = computePresenceLayout({
+      doc: makeDoc(),
+      remotes: [makeRemote({ selection: ['child-rect'] })],
+      fromCanvas: () => ({ x: Number.NaN, y: 0 }),
+      colorOf: () => '#ff0000',
+    })
+    expect(layout[0]!.boxes).toEqual([])
+    expect(layout[0]!.tag).toBeNull()
+  })
+})
+
+describe('projectIntoContainer（C1 容器偏移校正）', () => {
+  it('视口坐标减容器原点（-cRect.left/-cRect.top）', () => {
+    // 模拟容器位于视口 (240,120)：底层投影带视口原点，包装层换算为容器相对
+    const raw = (x: number, y: number): { x: number; y: number } | null => ({
+      x: x * 2 + 240,
+      y: y * 2 + 120,
+    })
+    const projected = projectIntoContainer(raw, { left: 240, top: 120 })
+    // board(50,60) ×2 → 视口(340,240) → 容器(100,120)
+    expect(projected(50, 60)).toEqual({ x: 100, y: 120 })
+  })
+
+  it('容器原点为零时等同原投影', () => {
+    const projected = projectIntoContainer(fromCanvasX2, { left: 0, top: 0 })
+    expect(projected(50, 60)).toEqual({ x: 100, y: 120 })
+  })
+
+  it('底层返回 null / 非有限值均拒收为 null', () => {
+    const none = projectIntoContainer(() => null, { left: 5, top: 5 })
+    expect(none(1, 1)).toBeNull()
+    const nan = projectIntoContainer(() => ({ x: Number.NaN, y: 3 }), { left: 5, top: 5 })
+    expect(nan(1, 1)).toBeNull()
+    const inf = projectIntoContainer(() => ({ x: 1, y: Number.POSITIVE_INFINITY }), { left: 0, top: 0 })
+    expect(inf(1, 1)).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 拖拽影子布局（任务 30）：awareness canvas.drag 子字段 → 容器相对影子框。
+// 影子位置是 board 坐标（本地桥写入 node.x/y 父相对值）→ 需按本地 doc 的
+// 父链补齐绝对偏移再投影；宽高取本地 doc 同 id 节点（已删跳过）。
+// ---------------------------------------------------------------------------
+
+describe('computePresenceLayout 拖拽影子（任务 30）', () => {
+  it('drag 子字段渲染为影子框（父链绝对偏移 + 本地 doc 宽高 + 投影）', () => {
+    const layout = computePresenceLayout({
+      doc: makeDoc(),
+      remotes: [
+        makeRemote({
+          drag: { items: [{ id: 'child-rect', x: 20, y: 30 }], ts: 1 },
+        }),
+      ],
+      fromCanvas: fromCanvasX2,
+      colorOf: () => '#ff0000',
+    })
+    expect(layout).toHaveLength(1)
+    // child-rect 拖拽中位置 (20,30) + 父链 frame-1 偏移 (100,100) → board (120,130)
+    // 宽高取本地 doc（50×50）→ ×2 投影 → (240,260,100,100)
+    expect(layout[0]?.shadows).toEqual([{ x: 240, y: 260, width: 100, height: 100 }])
+  })
+
+  it('已删/画板节点跳过；空 drag 不产生影子', () => {
+    const layout = computePresenceLayout({
+      doc: makeDoc(),
+      remotes: [
+        makeRemote({
+          drag: {
+            items: [
+              { id: 'deleted-node', x: 0, y: 0 },
+              { id: BOARD_NODE_ID, x: 0, y: 0 },
+              { id: 'child-rect', x: 1, y: 1 },
+            ],
+            ts: 1,
+          },
+        }),
+      ],
+      fromCanvas: fromCanvasX2,
+      colorOf: () => '#ff0000',
+    })
+    expect(layout[0]?.shadows).toHaveLength(1)
+    expect(layout[0]?.shadows[0]?.x).toBe(2 * (1 + 100))
+
+    const idle = computePresenceLayout({
+      doc: makeDoc(),
+      remotes: [makeRemote({})],
+      fromCanvas: fromCanvasX2,
+      colorOf: () => '#ff0000',
+    })
+    expect(idle[0]?.shadows).toEqual([])
+  })
+
+  it('影子框数量受 PRESENCE_MAX_BOXES_PER_USER 截断（select-all 拖拽防 DOM 爆炸）', () => {
+    const items = Array.from({ length: PRESENCE_MAX_BOXES_PER_USER + 10 }, (_, i) => ({
+      id: `frame-1`,
+      x: i,
+      y: i,
+    }))
+    const layout = computePresenceLayout({
+      doc: makeDoc(),
+      remotes: [makeRemote({ drag: { items, ts: 1 } })],
+      fromCanvas: fromCanvasX2,
+      colorOf: () => '#ff0000',
+    })
+    expect(layout[0]?.shadows).toHaveLength(PRESENCE_MAX_BOXES_PER_USER)
+  })
+
+  it('投影非有限（NaN）时影子框拒收不下发', () => {
+    const layout = computePresenceLayout({
+      doc: makeDoc(),
+      remotes: [makeRemote({ drag: { items: [{ id: 'child-rect', x: 20, y: 30 }], ts: 1 } })],
+      fromCanvas: () => ({ x: Number.NaN, y: 0 }),
+      colorOf: () => '#ff0000',
+    })
+    expect(layout[0]?.shadows).toEqual([])
+  })
+})

package/src/components/design/canvas/plugins/presence/__tests__/presence-overlay.test.tsx

@@ -0,0 +1,139 @@
+// 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.
+
+// presence overlay DOM 层测试（P4a，任务 25）：假投影（board ×2，容器相对
+// 坐标）+ 假节点表直渲 presentational 组件（不经 CanvasProvider——jsdom
+// 无法装配真 Leafer），断言 SVG 框/名牌的容器坐标与文案。
+
+import { describe, expect, it } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import { BOARD_NODE_ID, createEmptyDoc, type SceneDocument } from '../../../document/types'
+import type { RemoteCanvasPresence } from '@/lib/collab/bindings/canvas-presence'
+import {
+  CanvasPresenceOverlay,
+  buildPresenceTagText,
+} from '../presence-overlay'
+
+function makeDoc(): SceneDocument {
+  const doc = createEmptyDoc()
+  doc.nodes.push({
+    id: 'rect-1',
+    kind: 'shape',
+    type: 'rect',
+    parentId: BOARD_NODE_ID,
+    x: 50,
+    y: 60,
+    width: 30,
+    height: 40,
+  })
+  return doc
+}
+
+/** 假投影：board ×2 → 容器坐标（模拟 zoom=2、容器原点已在注入层校正） */
+const fakeFromCanvas = (x: number, y: number): { x: number; y: number } | null => ({
+  x: x * 2,
+  y: y * 2,
+})
+
+function makeRemote(selection: string[]): RemoteCanvasPresence {
+  return {
+    clientId: 7,
+    userId: 'u-1',
+    name: '阿蓝',
+    selection,
+    viewport: { x: 0, y: 0, zoom: 2 },
+    ts: 1,
+  }
+}
+
+afterEach(cleanup)
+
+describe('CanvasPresenceOverlay（DOM 层，假投影）', () => {
+  it('远端选中渲染为 SVG 框（容器坐标）+ 名牌（姓名 · 选中数）', () => {
+    const { container } = render(
+      <CanvasPresenceOverlay
+        remotes={[makeRemote(['rect-1'])]}
+        fromCanvas={fakeFromCanvas}
+        doc={makeDoc()}
+      />,
+    )
+    const svg = container.querySelector('[data-testid="canvas-presence-overlay"]')
+    expect(svg).not.toBeNull()
+    const box = container.querySelector('[data-presence-box="u-1"]')
+    expect(box).not.toBeNull()
+    // board(50,60,30,40) ×2 → 容器(100,120,60,80)
+    expect(box?.getAttribute('x')).toBe('100')
+    expect(box?.getAttribute('y')).toBe('120')
+    expect(box?.getAttribute('width')).toBe('60')
+    expect(box?.getAttribute('height')).toBe('80')
+    const tag = container.querySelector('[data-presence-tag="u-1"]')
+    expect(tag).not.toBeNull()
+    expect(tag?.textContent).toContain('阿蓝')
+  })
+
+  it('无远端在场渲染 null（零空转）', () => {
+    const { container } = render(
+      <CanvasPresenceOverlay remotes={[]} fromCanvas={fakeFromCanvas} doc={makeDoc()} />,
+    )
+    expect(container.querySelector('[data-testid="canvas-presence-overlay"]')).toBeNull()
+  })
+
+  it('投影缺失（引擎未就绪）渲染 null 不抛错', () => {
+    const { container } = render(
+      <CanvasPresenceOverlay remotes={[makeRemote(['rect-1'])]} fromCanvas={null} doc={makeDoc()} />,
+    )
+    expect(container.querySelector('[data-testid="canvas-presence-overlay"]')).toBeNull()
+  })
+})
+
+describe('buildPresenceTagText', () => {
+  it('单选只显名，多选附计数，空名降级「未知用户」', () => {
+    expect(buildPresenceTagText('阿蓝', 1)).toBe('阿蓝')
+    expect(buildPresenceTagText('阿蓝', 3)).toBe('阿蓝 · 3')
+    expect(buildPresenceTagText('', 1)).not.toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 拖拽影子渲染（任务 30）：远端 drag → 半透明虚线轮廓 SVG（React SVG 模式
+// 同选中框；影子与选中框互斥场景由数据面决定——拖拽中 selection 仍在，
+// 两者并存渲染）
+// ---------------------------------------------------------------------------
+
+describe('CanvasPresenceOverlay 拖拽影子（任务 30）', () => {
+  it('drag 到达渲染半透明影子框（容器坐标投影）', () => {
+    const remote = {
+      ...makeRemote(['rect-1']),
+      drag: { items: [{ id: 'rect-1', x: 100, y: 100 }], ts: 1 },
+    }
+    const { container } = render(
+      <CanvasPresenceOverlay remotes={[remote]} fromCanvas={fakeFromCanvas} doc={makeDoc()} />,
+    )
+    const shadow = container.querySelector('[data-presence-shadow="u-1"]')
+    expect(shadow).not.toBeNull()
+    // rect-1 本地宽高 30×40，影子位置 (100,100) → ×2 投影 → (200,200,60,80)
+    expect(shadow?.getAttribute('x')).toBe('200')
+    expect(shadow?.getAttribute('y')).toBe('200')
+    expect(shadow?.getAttribute('width')).toBe('60')
+    expect(shadow?.getAttribute('height')).toBe('80')
+    // 半透明可辨：fillOpacity < 1（影子不遮内容）
+    expect(Number(shadow?.getAttribute('fill-opacity'))).toBeLessThan(1)
+  })
+
+  it('无 drag 不渲染影子元素', () => {
+    const { container } = render(
+      <CanvasPresenceOverlay
+        remotes={[makeRemote(['rect-1'])]}
+        fromCanvas={fakeFromCanvas}
+        doc={makeDoc()}
+      />,
+    )
+    expect(container.querySelector('[data-presence-shadow]')).toBeNull()
+  })
+})

package/src/components/design/canvas/plugins/presence/layout.ts

@@ -0,0 +1,222 @@
+// 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/>.
+
+// presence 渲染插件坐标层（P4a，任务 25，规格 §7.2）：远端 awareness 快照
+// → **容器相对像素**布局（纯函数，可无头测试）。两段式同 measure-overlay/
+// annotation-overlay 先例：
+//   ① 本文件：nodeAbsoluteRect（board 绝对矩形，父链累计平移）+ 投影函数
+//      （engine.fromCanvas 为浏览器视口坐标，经 projectIntoContainer 减去
+//      容器原点；测试注入假实现）→ 每用户选中框矩形数组 + 名牌锚点（首个
+//      框上方）。
+//   ② presence-overlay.tsx：把布局渲染为容器内 SVG（pointer-events-none
+//      装饰，不动本地数据、不碰序列化、不建 Y 树——P4a 只读）。
+//
+// 纪律：本文件零 Leafer 依赖——输入/输出均为 id 字符串与纯数值（Leafer
+// 元素/树禁止进 React 层，AGENTS.md）；旋转父链下的 AABB 精度损失 P4a
+// 可接受（nodeAbsoluteRect 同口径，注释见 geometry.ts）。
+
+import { getUserColor } from '@/lib/collab/user-color'
+import { nodeAbsoluteRect } from '../../document/geometry'
+import { BOARD_NODE_ID, type SceneDocument, type SceneNode } from '../../document/types'
+import type { RemoteCanvasPresence } from '@/lib/collab/bindings/canvas-presence'
+
+/** 容器相对像素矩形（画布内 SVG 渲染坐标；原点 = canvas-viewport 容器左上角） */
+export interface PresenceClientBox {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/** 名牌（锚在首个选中框上方；count 为真实选中数，不受框截断影响） */
+export interface PresenceTag {
+  x: number
+  y: number
+  name: string
+  count: number
+}
+
+/** 单个远端协作者的渲染布局 */
+export interface RemotePresenceLayout {
+  clientId: number
+  userId: string
+  name: string
+  /** getUserColor 哈希色板色（确定性，选中框/名牌同色） */
+  color: string
+  boxes: PresenceClientBox[]
+  tag: PresenceTag | null
+  /** 真实选中元素数（boxes 可能被截断） */
+  selectionCount: number
+  /**
+   * 拖拽影子框（任务 30，P4b）：远端 awareness canvas.drag 子字段 → 半透明
+   * 虚线轮廓（与选中框并存渲染——拖拽中 selection 仍在，影子展示实时位置）。
+   * 空数组 = 未在拖拽。
+   */
+  shadows: PresenceClientBox[]
+}
+
+/**
+ * 单用户渲染框上限：select-all 在万节点文档下会产生同量级 SVG 元素
+ * （DOM 爆炸），截断到 32 个可视框（约一屏内可辨），计数用 selectionCount。
+ */
+export const PRESENCE_MAX_BOXES_PER_USER = 32
+
+/** 名牌高度（渲染侧 rect 高度与锚点计算共用） */
+export const PRESENCE_TAG_HEIGHT_PX = 16
+
+/** 名牌与选中框的垂直间距 */
+export const PRESENCE_TAG_GAP_PX = 6
+
+/** 名牌最低 y（贴视口顶边时不越界） */
+const TAG_MIN_Y = 2
+
+/**
+ * 容器相对投影：engine.fromCanvas 产物是**浏览器视口坐标系**
+ * （底层 Leafer getClientPointByWorld = clientBounds + world，clientBounds
+ * 为 view 的 getBoundingClientRect），而画布内 SVG 挂在 canvas-viewport
+ * 容器（absolute inset-0）上、原点 ≠ 视口原点——必须减去容器偏移才能直用
+ * （annotation-overlay 先例口径：`start.x - cRect.left`）。非有限值
+ * （NaN/Infinity，Leafer 坐标 API 异常形态）一律拒收返回 null。
+ */
+export function projectIntoContainer(
+  fromCanvas: (x: number, y: number) => { x: number; y: number } | null,
+  containerRect: { left: number; top: number },
+): (x: number, y: number) => { x: number; y: number } | null {
+  return (x, y) => {
+    const point = fromCanvas(x, y)
+    if (!point) return null
+    if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) return null
+    return { x: point.x - containerRect.left, y: point.y - containerRect.top }
+  }
+}
+
+/** 投影产物有限性防御（NaN/Infinity 拒绝下发，对齐引擎 toCanvas 防御口径） */
+function isFinitePoint(p: { x: number; y: number }): boolean {
+  return Number.isFinite(p.x) && Number.isFinite(p.y)
+}
+
+/**
+ * 节点父链绝对偏移（board 坐标系）：影子子字段携带的是节点父相对 x/y
+ * （本地桥写 engine doc 的 node.x/y），远端渲染需按本地 doc 父链补齐绝对
+ * 偏移后再投影——与 nodeAbsoluteRect 同一遍历口径（含 visible 剪枝与
+ * MAX_DEPTH 防环），不含节点自身 x/y。
+ */
+function parentAbsoluteOffset(
+  byId: Map<string, SceneNode>,
+  id: string,
+): { x: number; y: number } | null {
+  const node = byId.get(id)
+  if (!node || node.id === BOARD_NODE_ID || node.visible === false) return null
+  let x = 0
+  let y = 0
+  let parent: SceneNode | undefined = node.parentId ? byId.get(node.parentId) : undefined
+  let depth = 0
+  while (parent && depth < MAX_PARENT_DEPTH) {
+    if (parent.visible === false) return null
+    x += parent.x
+    y += parent.y
+    parent = parent.parentId ? byId.get(parent.parentId) : undefined
+    depth += 1
+  }
+  return { x, y }
+}
+
+/** 父链遍历深度上限（geometry.ts MAX_DEPTH 同口径，防数据环） */
+const MAX_PARENT_DEPTH = 64
+
+/** 单用户影子框截断（与选中框同上限：select-all 拖拽防 DOM 爆炸） */
+function computeDragShadows(
+  doc: SceneDocument,
+  drag: NonNullable<RemoteCanvasPresence['drag']>,
+  fromCanvas: (x: number, y: number) => { x: number; y: number } | null,
+): PresenceClientBox[] {
+  const byId = new Map(doc.nodes.map((node) => [node.id, node]))
+  const shadows: PresenceClientBox[] = []
+  for (const item of drag.items) {
+    if (shadows.length >= PRESENCE_MAX_BOXES_PER_USER) break
+    const node = byId.get(item.id)
+    // 已删/画板/隐藏节点跳过（本地 doc 是投影权威；无宽高不画框）
+    if (!node || node.id === BOARD_NODE_ID || node.visible === false) continue
+    const offset = parentAbsoluteOffset(byId, item.id)
+    if (!offset) continue
+    const ax = item.x + offset.x
+    const ay = item.y + offset.y
+    const tl = fromCanvas(ax, ay)
+    const br = fromCanvas(ax + node.width, ay + node.height)
+    if (!tl || !br || !isFinitePoint(tl) || !isFinitePoint(br)) continue
+    shadows.push({
+      x: Math.min(tl.x, br.x),
+      y: Math.min(tl.y, br.y),
+      width: Math.abs(br.x - tl.x),
+      height: Math.abs(br.y - tl.y),
+    })
+  }
+  return shadows
+}
+
+export function computePresenceLayout(input: {
+  doc: SceneDocument
+  remotes: RemoteCanvasPresence[]
+  /** board→容器坐标投影（生产注入 projectIntoContainer 包装的 engine.fromCanvas；测试注入假实现） */
+  fromCanvas: (x: number, y: number) => { x: number; y: number } | null
+  /** userId → 色（缺省 getUserColor 哈希色板；测试注入确定性色） */
+  colorOf?: (userId: string) => string
+}): RemotePresenceLayout[] {
+  const { doc, remotes, fromCanvas } = input
+  const colorOf = input.colorOf ?? getUserColor
+
+  return remotes.map((remote) => {
+    const boxes: PresenceClientBox[] = []
+    for (const nodeId of remote.selection) {
+      if (boxes.length >= PRESENCE_MAX_BOXES_PER_USER) break
+      // 已删/隐藏/不可定位（含 board 自身）→ null 跳过（简报口径）
+      const rect = nodeAbsoluteRect(doc, nodeId)
+      if (!rect) continue
+      // AABB 两对角投影（等比缩放下线性，旋转父链误差与 nodeAbsoluteRect 同口径）
+      const tl = fromCanvas(rect.x, rect.y)
+      const br = fromCanvas(rect.x + rect.width, rect.y + rect.height)
+      if (!tl || !br || !isFinitePoint(tl) || !isFinitePoint(br)) continue
+      boxes.push({
+        x: Math.min(tl.x, br.x),
+        y: Math.min(tl.y, br.y),
+        width: Math.abs(br.x - tl.x),
+        height: Math.abs(br.y - tl.y),
+      })
+    }
+
+    const first = boxes[0]
+    const tag: PresenceTag | null = first
+      ? {
+          x: first.x,
+          y: Math.max(TAG_MIN_Y, first.y - PRESENCE_TAG_HEIGHT_PX - PRESENCE_TAG_GAP_PX),
+          name: remote.name,
+          count: remote.selection.length,
+        }
+      : null
+
+    return {
+      clientId: remote.clientId,
+      userId: remote.userId,
+      name: remote.name,
+      color: colorOf(remote.userId),
+      boxes,
+      tag,
+      selectionCount: remote.selection.length,
+      shadows: remote.drag ? computeDragShadows(doc, remote.drag, fromCanvas) : [],
+    }
+  })
+}