@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/design/canvas/plugins/presence/presence-layer.tsx

@@ -0,0 +1,353 @@
+// 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/>.
+
+// 画布协同挂载层（P4a 任务 25 presence；P4b 任务 30 装配点）：本组件把
+// 画布协同四件在此收敛成完整协同态——
+//   ① canvas-presence 绑定（本端选中/视口上报 + 远端在场快照，T25）
+//   ② canvas-remote 绑定（Y → 引擎增量应用，T27）
+//   ③ canvas-local 绑定（引擎 → Y 转写 + 拖拽 awareness 影子，T28），其
+//      freezeTargets 接力 [remoteBinding, presenceBinding]（拖拽冻结纪律）
+//   ④ auto-save collab 参数由布局层注入本组件 collab prop（门控建连）并
+//      直通 useDesignAutoSave（保存让位，T29）
+// 装配时序（T27 交接锚点）：绑定创建在引擎就绪后；remote 绑定创建即
+// reconcileNow() 补种（room 已有 Y 树 → 引擎收敛到 Y 权威态）；local 绑定
+// 订阅在补种之后——初始 loadDoc 的 DB 态不再回写 Y。
+//
+// 编辑面双门控（审查 C1/I2）：① 装载窗口——loadPage 先 setActivePageId 再
+// 异步取页，窗口内引擎持旧页文档，远端桥/本地桥整体不装配（pageLoaded =
+// canvasLoadedRef 镜像，与 auto-save 同口径），零 Y 写防旧页内容污染新
+// room；② 预览——版本预览（readOnly）引擎持历史版本，reconcileNow/远端
+// 回放会覆写历史，编辑面整体跳过（presence 只读在场保留）。
+//
+// loadDoc 防覆盖守卫（任务 30 装配新增）：页装载完成时 DB 快照晚于 room
+// 协同态到达（sceneDoc prop 换新触发 engine.loadDoc(DB)）——若 room 内存在
+// 尚未 flush 的协同编辑（Y 新于 DB），本地桥将把陈旧快照回写 Y、覆盖他人
+// 在途编辑。守卫三件套：装配守卫预订阅（先于本地桥记录 lastEngineDoc）→
+// sceneDoc prop ≠ lastEngineDoc 时武装（等价 CanvasProvider initialDoc ≠
+// lastEmitted 的 loadDoc 判据；武装与 loadDoc 同 commit 相邻 effect，用户
+// 编辑无法插入）→ 被武装消费的装载通知从本地桥抑制（其内容从引擎丢弃，
+// queueMicrotask reconcileNow 以 Y 覆写——丢弃的正是陈旧 DB 快照，预期）。
+// Y 树为空时放行（写 Y 是合法首种）。守卫仅消费一次，普通编辑/远端应用
+// 不受影响。
+//
+// room 建连（getOrCreateProvider 单例 + createCollabTicketFn）→ 绑定层 →
+// overlay（远端选中框/名牌/拖拽影子）+ ViewerBadge（谁在看此页）+
+// CanvasCollabPanel（协作者面板，任务 30）。
+//
+// 挂载点：design-editor-layout 的 EditorShell（CanvasProvider 内，engine 与
+// activePageId 就绪处）——collab 不可用（desktop / 未配置 WS / collab=false）
+// 时 provider 为 noop（awareness null）→ binding 恒 null → 本组件渲染
+// null，零侵入。切页（pageId 变化）换 room：旧连接 destroy、新连接重建
+// （effect cleanup 先于新 effect 执行，lazy 双挂载场景安全——同
+// use-collab-doc 口径）。
+
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import { buildRoomName } from '@allbluecn/collab-core/rooms'
+import { yTreeToScene } from '@allbluecn/collab-core/canvas-tree'
+import { createCollabTicketFn } from '@/server/serverFns/collab'
+import type { SceneDocument } from '../../document/types'
+import {
+  createCanvasPresenceBinding,
+  type CanvasPresenceBinding,
+  type RemoteCanvasPresence,
+} from '@/lib/collab/bindings/canvas-presence'
+import { createCanvasLocalBinding } from '@/lib/collab/bindings/canvas-local'
+import { createCanvasRemoteBinding, type CanvasRemoteBinding } from '@/lib/collab/bindings/canvas-remote'
+import {
+  destroyProvider,
+  getOrCreateProvider,
+  type CollabProviderHandle,
+} from '@/lib/collab/provider'
+import { isCollabEnabled } from '@/lib/collab/env'
+import { useSelfProfileBroadcast } from '@/lib/collab/use-self-profile-broadcast'
+import { CanvasCollabPanel } from '@/components/collab/canvas-collab-panel'
+import { useCanvasEngineOptional } from '../../react/hooks'
+import { useCanvasSnapshotOptional } from '../../react/canvas-hooks'
+import { projectIntoContainer } from './layout'
+import { CanvasPresenceOverlay } from './presence-overlay'
+import { ViewerBadge } from './viewer-badge'
+
+/**
+ * 视口心跳（平移不触发 zoom 快照变化，15s 低频 setViewport 覆盖 pan 漂移
+ * 并续报 ts 新鲜度；对齐 use-presence-report 心跳节奏）。
+ */
+const CANVAS_VIEWPORT_HEARTBEAT_MS = 15_000
+
+const EMPTY_REMOTES: RemoteCanvasPresence[] = []
+
+/** 远端在场快照订阅（version 缓存快照，同 useCollabFields 口径） */
+function useCanvasRemotes(binding: CanvasPresenceBinding | null): RemoteCanvasPresence[] {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => binding?.subscribe(onStoreChange) ?? (() => {}),
+    [binding],
+  )
+  const cacheRef = useRef<{ version: number; remotes: RemoteCanvasPresence[] } | null>(null)
+  const getSnapshot = useCallback(() => {
+    if (!binding) return EMPTY_REMOTES
+    const version = binding.version()
+    if (cacheRef.current?.version !== version) {
+      cacheRef.current = { version, remotes: binding.readRemotes() }
+    }
+    return cacheRef.current.remotes
+  }, [binding])
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+export interface CanvasPresenceLayerProps {
+  /** 画布页 id（room 键；null = 未加载，不挂载） */
+  pageId: string | null
+  /**
+   * 协同入口参数（任务 30 装配：布局层按 isCollabEnabled() 注入并直通
+   * auto-save collab 参数）；false 或 env 不可用 → 全短路零挂载。
+   */
+  collab?: boolean
+  /**
+   * DB 取页产出的场景文档（EditorShell 的 sceneDoc prop）：loadDoc 防覆盖
+   * 守卫的武装判据（prop 换新 = 一次 engine.loadDoc(DB) 即将发生）。
+   */
+  loadedSceneDoc?: SceneDocument | null
+  /**
+   * 页面数据装载完成（布局层镜像 useDesignPageLoad 的 canvasLoadedRef，与
+   * auto-save 同口径，审查 C1）：loadPage 先 setActivePageId 再异步取页，
+   * 「activePageId 先行、sceneDoc 未到」窗口内引擎仍持旧页文档——此窗口
+   * 编辑面（远端桥回放 + 本地桥回写）整体不装配，任何引擎变更零 Y 写，
+   * 防旧页内容污染新 room。缺省 false（fail-closed：漏传即不启用编辑面）。
+   */
+  pageLoaded?: boolean
+}
+
+export function CanvasPresenceLayer({
+  pageId,
+  collab = false,
+  loadedSceneDoc = null,
+  pageLoaded = false,
+}: CanvasPresenceLayerProps) {
+  const engine = useCanvasEngineOptional()
+  const snapshot = useCanvasSnapshotOptional()
+  const layerRef = useRef<HTMLDivElement | null>(null)
+  // 预览态（版本预览 readOnly 引擎持历史版本）：编辑面跳过（审查 I2）——
+  // reconcileNow/远端回放会把 Y 现行态覆写历史预览；原始类型快照隔离
+  // （snapshot 对象每次 store emit 重建，不可作 effect deps）
+  const previewing = snapshot?.readOnly ?? false
+
+  // room 建连（collab 不可用/未加载页 → null，全链路降级）
+  const roomName =
+    pageId && snapshot?.ready && collab && isCollabEnabled()
+      ? buildRoomName({ kind: 'design-canvas', pageId })
+      : null
+  const [handle, setHandle] = useState<CollabProviderHandle | null>(null)
+  useEffect(() => {
+    if (!roomName) {
+      setHandle(null)
+      return
+    }
+    const created = getOrCreateProvider(roomName, {
+      getTicket: async (name) => {
+        const { ticket } = await createCollabTicketFn({ data: { roomName: name } })
+        return ticket
+      },
+    })
+    setHandle(created)
+    return () => {
+      setHandle(null)
+      destroyProvider(roomName)
+    }
+  }, [roomName])
+
+  // profile 头像摘要广播（本端 canvas.user 署名 profile 兜底 + 远端头像数据）
+  useSelfProfileBroadcast(handle)
+
+  // ===== 装配域（任务 30）：三绑定 + freezeTargets 接力 + loadDoc 守卫 =====
+
+  // loadDoc 守卫状态（ref 跨 effect 共享；guard 绑定与三绑定同生命周期）
+  const guardArmedRef = useRef(false)
+  const guardSuppressedRef = useRef<SceneDocument | null>(null)
+  const lastEngineDocRef = useRef<SceneDocument | null>(null)
+  const remoteBindingRef = useRef<CanvasRemoteBinding | null>(null)
+
+  const [binding, setBinding] = useState<CanvasPresenceBinding | null>(null)
+  useEffect(() => {
+    const awareness = handle?.awareness
+    if (!handle || !awareness || !engine) {
+      setBinding(null)
+      return
+    }
+
+    // 守卫预订阅（先于本地桥订阅：被武装通知先经此消费，本地桥的包装订阅
+    // 再按 guardSuppressedRef 跳过同一次通知）。
+    // 抑制语义（诚实口径，审查 I3）：被武装通知若是装载通知（loadDoc 的
+    // 陈旧 DB 快照），内容从引擎**丢弃**——reconcileNow 以 Y 覆写引擎，被
+    // 丢弃的正是「打开时刻的 DB 快照」，属预期；武装到 loadDoc 在同一次
+    // commit 内相邻 effect 完成（子组件 effect 先于父组件），用户编辑无法
+    // 插入该窗口。抑制仅在 Y 树非空时生效：room 未种子化（yTreeToScene
+    // null）时无远端态可回滚，DB 装载写 Y 反而是合法首种——放行不抑制。
+    lastEngineDocRef.current = null
+    guardArmedRef.current = false
+    guardSuppressedRef.current = null
+    const unsubscribeGuard = engine.onDocChange((doc) => {
+      lastEngineDocRef.current = doc
+      if (guardArmedRef.current) {
+        guardArmedRef.current = false
+        let seeded = false
+        try {
+          seeded = yTreeToScene(handle.doc) !== null
+        } catch {
+          seeded = false
+        }
+        if (!seeded) return
+        guardSuppressedRef.current = doc
+        // 以 Y 权威覆写引擎（丢弃被抑制的装载内容）：微任务避开 notify
+        // 派发中重入
+        queueMicrotask(() => {
+          remoteBindingRef.current?.reconcileNow()
+        })
+      }
+    })
+
+    // 本地桥专用引擎视图：包装 onDocChange，消费守卫抑制（被武装的装载
+    // 通知不进本地桥 → 陈旧快照永不回写 Y）；其余订阅/读面直通
+    const suppressed = guardSuppressedRef
+    const localEngine = {
+      getDoc: () => engine.getDoc(),
+      getSelection: () => engine.getSelection(),
+      onDocChange: (cb: (doc: SceneDocument) => void) =>
+        engine.onDocChange((doc) => {
+          if (suppressed.current === doc) {
+            suppressed.current = null
+            return
+          }
+          cb(doc)
+        }),
+      onDragChange: (cb: (dragging: boolean) => void) => engine.onDragChange(cb),
+    }
+
+    // 装配时序（T27 交接锚点）：remote 先行（Y observe）→ presence →
+    // 补种（引擎收敛 Y 权威态，本地桥订阅尚未建立——补种通知不回写 Y）→
+    // local（freezeTargets 接力 [remote, presence]，拖拽冻结纪律）。
+    //
+    // 编辑面（remote + local）仅在「页已装载且非预览」时装配（审查 C1/I2）：
+    //   - C1 装载窗口：activePageId 先行、sceneDoc 未到期间引擎持旧页文档，
+    //     远端回放与本地回写都会污染新 room 的 Y——整面延迟到 pageLoaded；
+    //   - I2 预览：readOnly 引擎持历史版本，reconcileNow/远端回放会把 Y
+    //     现行态覆写历史——编辑面整体跳过（预览本就不应回放远端变更）。
+    // presence（只读在场）恒建：预览/窗口期保留「谁在看此页」（T25 行为）。
+    const editPlaneReady = !previewing && pageLoaded
+    const remote = editPlaneReady
+      ? createCanvasRemoteBinding({ doc: handle.doc, engine })
+      : null
+    remoteBindingRef.current = remote
+    const presence = createCanvasPresenceBinding({
+      awareness,
+      onStatusChange: (listener) => handle.onStatusChange(listener),
+      selection: engine,
+    })
+    remote?.reconcileNow()
+    const local = editPlaneReady
+      ? createCanvasLocalBinding({
+          doc: handle.doc,
+          engine: localEngine,
+          awareness,
+          freezeTargets: [remote as CanvasRemoteBinding, presence],
+        })
+      : null
+    setBinding(presence)
+    return () => {
+      remoteBindingRef.current = null
+      // 销毁序：local 先（解订阅 + 拖拽中断线解冻接力）→ presence → remote
+      local?.destroy()
+      presence.destroy()
+      remote?.destroy()
+      unsubscribeGuard()
+      setBinding(null)
+    }
+  }, [handle, engine, previewing, pageLoaded])
+
+  // 守卫武装（loadDoc 判据）：sceneDoc prop ≠ 引擎最近通知文档 → 一次
+  // loadDoc(DB) 即将发生（同 CanvasProvider initialDoc ≠ lastEmitted 口径），
+  // 武装下个引擎通知为抑制对象。仅页已装载且非预览时武装（编辑面在场的
+  // 前提，与 binding 门控一致）；子组件 effect 先于父组件（CanvasProvider
+  // 的 initialDoc loadDoc effect）执行，武装先于通知。仅消费一次。
+  useEffect(() => {
+    guardArmedRef.current = false
+    if (!handle || !engine || !binding || !pageLoaded || previewing) return
+    if (loadedSceneDoc && loadedSceneDoc !== lastEngineDocRef.current) {
+      guardArmedRef.current = true
+    }
+  }, [loadedSceneDoc, handle, engine, binding, pageLoaded, previewing])
+
+  // 视口上报：绑定建立 + zoom 快照变化即时，15s 心跳覆盖 pan 漂移。
+  // ⚠ client 坐标口径：toCanvas 入参是浏览器视口坐标，必须带容器原点
+  // （cRect.left/top + 尺寸一半），不能用纯 clientWidth/2（容器原点 ≠ 视口
+  // 原点，左侧栏/顶部工具条偏移会系统性带偏 viewport 数据——C1 同源问题）
+  const reportViewport = useCallback(() => {
+    if (!binding || !engine) return
+    try {
+      const el = layerRef.current
+      const rect = el?.getBoundingClientRect()
+      const center = engine.toCanvas(
+        (rect?.left ?? 0) + (el?.clientWidth ?? 0) / 2,
+        (rect?.top ?? 0) + (el?.clientHeight ?? 0) / 2,
+      )
+      binding.setViewport({
+        x: center?.x ?? 0,
+        y: center?.y ?? 0,
+        zoom: engine.getZoom(),
+      })
+    } catch {
+      // 引擎 dispose 与 store 更新间的一帧竞态（getZoom/toCanvas 内部
+      // assertUsable 抛 LeaferEngine disposed）：静默跳过本次上报
+    }
+  }, [binding, engine])
+  useEffect(() => {
+    reportViewport()
+  }, [reportViewport, snapshot?.zoom])
+  useEffect(() => {
+    if (!binding) return
+    const timer = setInterval(reportViewport, CANVAS_VIEWPORT_HEARTBEAT_MS)
+    return () => clearInterval(timer)
+  }, [binding, reportViewport])
+
+  // board→容器坐标投影（C1 容器偏移校正）：engine.fromCanvas 产物是浏览器
+  // 视口坐标，而 overlay SVG 挂在本层容器（absolute inset-0）上——经
+  // projectIntoContainer 减去容器原点（annotation-overlay 的 -cRect.left
+  // 先例口径）。矩形每次现读（overlay 的 250ms tick 顺带覆盖容器 resize）；
+  // 抛错（引擎 dispose 竞态）由 overlay 的布局 try/catch 承接
+  const fromCanvasInLayer = useCallback(
+    (x: number, y: number): { x: number; y: number } | null => {
+      const el = layerRef.current
+      if (!el || !engine) return null
+      const rect = el.getBoundingClientRect()
+      return projectIntoContainer(
+        (px, py) => engine.fromCanvas(px, py),
+        { left: rect.left, top: rect.top },
+      )(x, y)
+    },
+    [engine],
+  )
+
+  const remotes = useCanvasRemotes(binding)
+  if (!binding) return null
+
+  return (
+    <div ref={layerRef} className="pointer-events-none absolute inset-0 z-10">
+      <CanvasPresenceOverlay remotes={remotes} fromCanvas={fromCanvasInLayer} doc={snapshot?.doc ?? null} />
+      <ViewerBadge remotes={remotes} />
+      {/* 协作者面板（任务 30）：头像组 + 元素级「X 正在编辑」提示 */}
+      <CanvasCollabPanel remotes={remotes} doc={snapshot?.doc ?? null} />
+    </div>
+  )
+}

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

@@ -0,0 +1,155 @@
+// 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/>.
+
+// 远端选中框 + 名牌 overlay（P4a，任务 25）。presentational 组件：投影函数
+// 与 doc 由 presence-layer 注入（生产为含容器偏移校正的 engine.fromCanvas
+// 包装；测试注入假实现——真 Leafer headless 限制下 DOM 层测试一律走假投影，
+// memrec 纪律）。
+//
+// 只读渲染纪律：不写本地文档、不碰序列化、不建 Y 树；布局经 layout.ts
+// 纯函数产出纯数值（无 ILeaf 进 React 层）。渲染形态对齐 annotation-overlay
+// 先例（绝对定位 SVG + pointer-events-none），漂移校正用 250ms 低频 tick
+// 而非连续 rAF（远端选中框 P4a 低精度，省持续帧预算；viewport 快照只覆盖
+// zoom 变化，pan 漂移由此 tick 兜底）。
+
+import { useEffect, useMemo, useState } from "react"
+import { m } from "@/paraglide/messages.js"
+import type { RemoteCanvasPresence } from "@/lib/collab/bindings/canvas-presence"
+import type { SceneDocument } from "../../document/types"
+import { computePresenceLayout, PRESENCE_TAG_HEIGHT_PX } from "./layout"
+
+/**
+ * board→容器坐标投影（生产 = projectIntoContainer 包装的 engine.fromCanvas，
+ * 已减去画布容器原点；测试注入纯函数假实现）
+ */
+export type PresenceFromCanvas = (x: number, y: number) => { x: number; y: number } | null
+
+/** 漂移校正 tick 间隔（ms） */
+const VIEWPORT_REFRESH_MS = 250
+
+/** 名牌文案宽度估算：CJK 全宽 ~10px、半角 ~6px @10px 字号 + 内边距 */
+function tagTextWidth(text: string): number {
+  let width = 12
+  for (const ch of text) width += ch.charCodeAt(0) > 0x2e80 ? 10 : 6
+  return width
+}
+
+export interface CanvasPresenceOverlayProps {
+  remotes: RemoteCanvasPresence[]
+  fromCanvas: PresenceFromCanvas | null
+  doc: SceneDocument | null
+}
+
+export function CanvasPresenceOverlay({ remotes, fromCanvas, doc }: CanvasPresenceOverlayProps) {
+  const [tick, setTick] = useState(0)
+
+  useEffect(() => {
+    if (remotes.length === 0) return
+    const timer = setInterval(() => setTick((t) => t + 1), VIEWPORT_REFRESH_MS)
+    return () => clearInterval(timer)
+  }, [remotes.length])
+
+  const layout = useMemo(() => {
+    if (!fromCanvas || !doc || remotes.length === 0) return []
+    try {
+      return computePresenceLayout({
+        doc,
+        remotes,
+        fromCanvas,
+      })
+    } catch {
+      // 引擎 dispose 与 store 更新间的一帧竞态（engine.fromCanvas 内部
+      // assertUsable 抛 LeaferEngine disposed）：跳过本帧重投影
+      return []
+    }
+    // tick 仅作重投影触发器（pan/缩放漂移校正），不参与计算
+  }, [fromCanvas, doc, remotes, tick])
+
+  if (layout.length === 0) return null
+
+  return (
+    <svg
+      data-testid="canvas-presence-overlay"
+      className="pointer-events-none absolute inset-0 h-full w-full"
+    >
+      {layout.map((user) => (
+        <g key={user.clientId} data-presence-user={user.userId}>
+          {/* 拖拽影子（任务 30）：半透明虚线轮廓——拖拽中的实时位置，不遮内容 */}
+          {user.shadows.map((box, index) => (
+            <rect
+              key={`shadow-${index}`}
+              data-presence-shadow={user.userId}
+              x={box.x}
+              y={box.y}
+              width={box.width}
+              height={box.height}
+              fill={user.color}
+              fillOpacity={0.14}
+              stroke={user.color}
+              strokeWidth={1.5}
+              strokeDasharray="5 4"
+              rx={2}
+              opacity={0.85}
+            />
+          ))}
+          {user.boxes.map((box, index) => (
+            <rect
+              key={index}
+              data-presence-box={user.userId}
+              x={box.x}
+              y={box.y}
+              width={box.width}
+              height={box.height}
+              fill="none"
+              stroke={user.color}
+              strokeWidth={1.5}
+              rx={2}
+              opacity={0.9}
+            />
+          ))}
+          {user.tag && (
+            <g data-presence-tag={user.userId}>
+              <rect
+                x={user.tag.x}
+                y={user.tag.y}
+                width={tagTextWidth(buildPresenceTagText(user.tag.name, user.tag.count))}
+                height={PRESENCE_TAG_HEIGHT_PX}
+                rx={3}
+                fill={user.color}
+              />
+              <text
+                x={user.tag.x + 6}
+                y={user.tag.y + 11.5}
+                fontSize={10}
+                fontWeight={600}
+                fill="#ffffff"
+              >
+                {buildPresenceTagText(user.tag.name, user.tag.count)}
+              </text>
+            </g>
+          )}
+        </g>
+      ))}
+    </svg>
+  )
+}
+
+/** 名牌文案（布局层数据 + 展示层兜底组装）：空名降级 i18n「未知用户」，多选附计数 */
+export function buildPresenceTagText(name: string, count: number): string {
+  const displayName = name.length > 0 ? name : m.collab_activityUnknownUser()
+  return count > 1 ? `${displayName} · ${count}` : displayName
+}

package/src/components/design/canvas/plugins/presence/viewer-badge.tsx

@@ -0,0 +1,80 @@
+// 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/>.
+
+// 「谁在看此页」徽标（P4a，任务 25）：画布视口左上角的在场 pill——色点
+// （getUserColor 哈希色）+ 人数，hover 列出每人姓名与选中数（名牌 tooltip
+// 的 i18n 承载面）。presentational：remotes 由 presence-layer 注入。
+//
+// 精度口径（P4a）：只表「在此 room」不表视口朝向——viewport 字段已入
+// awareness schema 供 P4b 远端视口指示器升级。
+
+import { m } from '@/paraglide/messages.js'
+import type { RemoteCanvasPresence } from '@/lib/collab/bindings/canvas-presence'
+import { getUserColor } from '@/lib/collab/user-color'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+
+export interface ViewerBadgeProps {
+  remotes: RemoteCanvasPresence[]
+}
+
+export function ViewerBadge({ remotes }: ViewerBadgeProps) {
+  if (remotes.length === 0) return null
+  return (
+    <div className="pointer-events-auto absolute left-2 top-2 z-20" data-testid="canvas-presence-badge">
+      <Tooltip>
+        <TooltipTrigger
+          className="flex h-6 items-center gap-1.5 rounded-full border border-border bg-background/90 px-2 shadow-sm"
+          aria-label={m.collab_canvasViewersCount({ count: remotes.length })}
+        >
+          <span className="flex -space-x-1">
+            {remotes.map((remote) => (
+              <span
+                key={remote.clientId}
+                className="inline-block size-2.5 rounded-full border border-background"
+                style={{ backgroundColor: getUserColor(remote.userId) }}
+              />
+            ))}
+          </span>
+          {/* text-[10px]：对齐画布角标既有字号口径（CanvasToolbarBar 自动保存角标同款） */}
+          <span className="text-[10px] leading-none tabular-nums text-muted-foreground">
+            {m.collab_canvasViewersCount({ count: remotes.length })}
+          </span>
+        </TooltipTrigger>
+        <TooltipContent side="bottom" align="start">
+          <div className="flex flex-col gap-0.5">
+            {remotes.map((remote) => (
+              <span key={remote.clientId} className="flex items-center gap-1.5">
+                <span
+                  className="inline-block size-2 shrink-0 rounded-full"
+                  style={{ backgroundColor: getUserColor(remote.userId) }}
+                />
+                {remote.selection.length > 0
+                  ? m.collab_canvasViewerRow({
+                      name: remote.name || m.collab_activityUnknownUser(),
+                      count: remote.selection.length,
+                    })
+                  : m.collab_canvasViewerIdle({
+                      name: remote.name || m.collab_activityUnknownUser(),
+                    })}
+              </span>
+            ))}
+          </div>
+        </TooltipContent>
+      </Tooltip>
+    </div>
+  )
+}

package/src/components/design/canvas/react/__tests__/hooks.test.tsx

@@ -321,8 +321,8 @@ describe("canvas hooks", () => {
   it("undo/redo 快捷键语法通过 @tanstack/hotkeys 校验", () => {
     for (const hotkey of [UNDO_HOTKEY, REDO_HOTKEY, GROUP_HOTKEY, UNGROUP_HOTKEY] as Hotkey[]) {
       const result = validateHotkey(hotkey)
-      expect(result.errors, hotkey).toEqual([])
-      expect(result.warnings, hotkey).toEqual([])
+      expect(result.errors, String(hotkey)).toEqual([])
+      expect(result.warnings, String(hotkey)).toEqual([])
     }
   })
 
@@ -337,8 +337,8 @@ describe("canvas hooks", () => {
       HIDE_HOTKEY,
     ] as Hotkey[]) {
       const result = validateHotkey(hotkey)
-      expect(result.errors, hotkey).toEqual([])
-      expect(result.warnings, hotkey).toEqual([])
+      expect(result.errors, String(hotkey)).toEqual([])
+      expect(result.warnings, String(hotkey)).toEqual([])
     }
   })
 

package/src/components/design/editor/collaboration/__tests__/design-agent-panel-regenerate.test.tsx

@@ -278,7 +278,9 @@ describe("DesignAgentPanel 组件级重生成（FS-8.4）", () => {
 
     await waitFor(() => expect(fetchMock).toHaveBeenCalled())
     const body = lastBody(fetchMock)
-    const biz = (body.forwardedProps ?? body.data) as Record<string, unknown>
+    // connect 第 4 参 run context：wire threadId = 当前会话 id（1.0 threadId 必填语义）
+    expect(body.threadId).toBe("conv_1")
+    const biz = body.forwardedProps as Record<string, unknown>
     expect(biz.prompt).toBe("把主按钮改为描边样式")
     expect(biz.mode).toBe("regenerate")
     expect(biz.selectedFrameId).toBe("a_1")

package/src/components/design/editor/collaboration/__tests__/design-agent-panel-stream.test.tsx

@@ -428,7 +428,9 @@ describe("DesignAgentPanel 流式生成消费（FS-8.3）", () => {
 
     await waitFor(() => expect(fetchMock).toHaveBeenCalled())
     const body = lastBody(fetchMock)
-    const biz = (body.forwardedProps ?? body.data) as Record<string, unknown>
+    // connect 第 4 参 run context：wire threadId = 当前会话 id（1.0 threadId 必填语义）
+    expect(body.threadId).toBe("conv_1")
+    const biz = body.forwardedProps as Record<string, unknown>
     expect(biz.prompt).toBe("在选中画板里加一个卡片")
     expect(biz.mode).toBe("generate")
     expect(biz.selectedFrameId).toBe("a_1")

package/src/components/design/editor/collaboration/design-agent-panel.tsx

@@ -372,6 +372,8 @@ export function DesignAgentPanel({ designId, onSceneGenerated, selectedModel, on
 
     try {
       const connection = fetchServerSentEvents(STREAM_URL)
+      // 第 4 参 run context：threadId 用本会话 id（convId 由调用方确保非空），
+      // runId 每次 connect 一个（一次 connect = 一次 run，与客户端自 mint 语义一致）
       const stream = connection.connect(
         [] as never[],
         {
@@ -384,6 +386,7 @@ export function DesignAgentPanel({ designId, onSceneGenerated, selectedModel, on
             : {}),
         },
         controller.signal,
+        { threadId: convId, runId: crypto.randomUUID() },
       )
       for await (const chunk of stream) {
         // 首事件已到解除首事件超时；每个事件重挂空闲超时——空闲窗口自最近