@nelsonlongxiang/dsh-open-a2a-net 0.5.14 → 0.6.24

package/nexus-stage/src/planning-view.ts

@@ -0,0 +1,1313 @@
+/**
+ * The 2D planning-mode view: one section#dsh-plan holding a screen-fixed
+ * dot-grid layer, the transformed world container (SVG star edges + team
+ * frames + node cards), a marquee, and the HUD (toolbar / tabs host /
+ * status / legend). This is the ONLY new DOM module; everything spatial
+ * lives in the pure modules (viewport/world/edges/layout-doc).
+ *
+ * Reconcile discipline:
+ * - the WorldModel persists across polls and is maintained incrementally
+ *   (upsert refreshes rendered attributes, never positions - a poll must
+ *   not snap a dragged card back to its last-saved spot);
+ * - card/frame elements are keyed-diffed so focus, the pickup transition,
+ *   and an in-flight pointer capture survive a poll; SVG edges carry no
+ *   state and are rebuilt wholesale;
+ * - the federation overlay (peer cards + activity/federal edges) renders
+ *   on every render, OUTSIDE the revision gate, so inFlight ages tick per
+ *   poll and the badge cards track the local content bounds;
+ * - XSS: session labels/teams are attacker-shaped data and land only via
+ *   createElement + textContent.
+ *
+ * Gestures (Figma-style ruling): left-blank drag = marquee; pan = Space+drag
+ * or middle-drag or Shift+wheel; wheel (with or without Ctrl) =
+ * pointer-anchored zoom (owner ruling 2026-09-01).
+ * Tests drive the same handlers production binds through `seam`.
+ * @module nexus-stage/planning-view
+ */
+
+import type { LampState } from './layout-wire'
+import { buildLayoutDoc, clampDoc, type LayoutDoc, type LayoutRect } from './layout-doc'
+import { FRAME_HEAD_LIFT, starEdges } from './edges'
+import { displayName } from './stage-name'
+import {
+  activityEdges, federalEdges, flyBounds, groupRemoteTeams, peerNodeId, peerHostOf, placePeers,
+  type FrameAnchor, type InFlightRow, type PeerPlacement, type PeerRow,
+  type RemoteTeamRow,
+} from './federation'
+import { clampViewport, fitView, panBy, screenToWorld, worldTransformCss, zoomAt, type LayoutViewport } from './viewport'
+import { WorldModel, nodeRect, deriveInitialFrame, homeTeams, planSeatClear, planTeamClusters } from './world'
+import { applyAction, actionTeam, innermostFrameAt, reorderOps, yOrderedMembers, type CanvasAction } from './canvas-ops'
+import { FRAME_HUES } from './tokens'
+import { createPlanningMenus } from './planning-menus'
+import { createNodeList } from './planning-nodelist'
+import { viewportBucket, type PlanningDeps, type PlanningInput, type PlanningSession, type PlanningTeam, type PlanningView, type SeamKey, type SeamPointer, type ViewportBucket } from './planning-types'
+import './planning.css'
+
+export { viewportBucket } from './planning-types'
+export type { PlanningDeps, PlanningInput, PlanningSession, PlanningTeam, PlanningView, SeamKey, SeamPointer, ViewportBucket } from './planning-types'
+
+/** Team-name hue, same 31-polynomial family as the 3D scene's getHue. */
+function frameHue(name: string): { line: string; bg: string } {
+  let h = 0
+  for (let i = 0; i < name.length; i++) h = ((h * 31 + name.charCodeAt(i)) & 0xfffffff) >>> 0
+  const rgb = FRAME_HUES[h % FRAME_HUES.length]!
+  const line = '#' + rgb.toString(16).padStart(6, '0')
+  // 5% alpha fill over the dark base, per the design system.
+  const r = (rgb >> 16) & 0xff
+  const g = (rgb >> 8) & 0xff
+  const b = rgb & 0xff
+  return { line, bg: `rgba(${r},${g},${b},0.05)` }
+}
+
+
+type Gesture =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'node'; ids: readonly string[]; clicked: string; last: { x: number; y: number }; moved: boolean; el: Element | null }
+  | { readonly kind: 'frame'; name: string; snap: NonNullable<ReturnType<WorldModel['beginFrameDrag']>>; origin: { x: number; y: number }; moved: boolean }
+  | { readonly kind: 'frame-resize'; name: string; dir: string; startRect: { x: number; y: number; w: number; h: number }; origin: { x: number; y: number }; moved: boolean }
+  | { readonly kind: 'pan'; last: { x: number; y: number }; moved: boolean }
+  | { readonly kind: 'marquee'; origin: { x: number; y: number }; last: { x: number; y: number }; additive: boolean }
+
+export function createPlanningView(deps: PlanningDeps): PlanningView {
+  const model = new WorldModel()
+  let layoutDoc: LayoutDoc | undefined
+  let vp: LayoutViewport = { ...model.viewport }
+  let gesture: Gesture = { kind: 'none' }
+  let spaceDown = false
+  let renderedRevision = -1
+  /** Until the first reconcile with nodes (or an adopted viewport), frame the content once. */
+  let firstFitPending = true
+  let viewportAdopted = false
+  const bucket = (): ViewportBucket => viewportBucket(globalThis.innerWidth || viewW)
+  const markDirty = (): void => {
+    deps.viewportStore?.set(bucket(), vp)
+    deps.onDirty()
+  }
+  const clock = deps.now ?? Date.now
+  const ac = new AbortController()
+  const noticeTimers: Array<ReturnType<typeof setTimeout>> = []
+  /** Active right-button press: hold-drag pans; a clean release opens the
+   *  context menu (the contextmenu event itself is always suppressed). */
+  let rightPress: { x: number; y: number; target: Element | null; moved: boolean } | null = null
+  let suppressNextMenu = false
+  const signal = { signal: ac.signal } as AddEventListenerOptions
+
+  // ── DOM shell (built once) ──
+  const root = document.createElement('section')
+  root.id = 'dsh-plan'
+  root.setAttribute('role', 'tabpanel')
+  root.setAttribute('aria-label', 'A2A 规划画布')
+  root.tabIndex = 0
+  root.style.display = 'none'
+
+  const grid = document.createElement('div')
+  grid.className = 'p-grid'
+
+  const world = document.createElement('div')
+  world.className = 'p-world'
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
+  svg.setAttribute('class', 'p-edges')
+  // NOTE: the svg is intentionally NOT aria-hidden — its .edge-label texts
+  // carry the route ages that reduced-motion users rely on.
+  // Stable layers: frames must ALWAYS paint (and lose hit-testing) below
+  // cards, regardless of which keyed diff created its element first — a
+  // frame created after the cards used to sit on top of them and swallow
+  // every real-pointer drag inside the team (synthetic tests bypassed it
+  // by targeting cards directly).
+  const frameLayer = document.createElement('div')
+  frameLayer.className = 'p-layer p-frames'
+  /** The selected frame keeps its resize handles visible without hover. */
+  let selectedFrame: string | undefined
+  const markSelectedFrame = (name: string | undefined): void => {
+    if (selectedFrame !== undefined) {
+      frameEls.get(selectedFrame)?.classList.remove('selected')
+    }
+    selectedFrame = name
+    if (name !== undefined) {
+      frameEls.get(name)?.classList.add('selected')
+    }
+  }
+  const nodeLayer = document.createElement('div')
+  nodeLayer.className = 'p-layer p-nodes'
+  nodeLayer.setAttribute('role', 'listbox')
+  nodeLayer.setAttribute('aria-multiselectable', 'true')
+  nodeLayer.setAttribute('aria-label', '会话节点')
+  world.append(svg, frameLayer, nodeLayer)
+
+  const marquee = document.createElement('div')
+  marquee.className = 'p-marquee'
+
+  const toolbar = document.createElement('div')
+  toolbar.className = 'p-toolbar'
+  const zoomLabel = document.createElement('span')
+  zoomLabel.className = 'p-zoom mono'
+  zoomLabel.textContent = '100%'
+  const mkButton = (text: string, title: string, onClick: () => void): HTMLButtonElement => {
+    const b = document.createElement('button')
+    b.type = 'button'
+    b.textContent = text
+    b.title = title
+    b.addEventListener('click', onClick, signal)
+    return b
+  }
+  toolbar.append(
+    mkButton('适配', '适配视图（快捷键 0）', () => fitToContent()),
+    mkButton('－', '缩小', () => zoomCenter(1 / 1.2)),
+    zoomLabel,
+    mkButton('＋', '放大', () => zoomCenter(1.2)),
+    mkButton('建队', '组成团队（G）：先框选至少 2 个节点', () => menus.startCreateFromSelection()),
+  )
+  // Unjoined sessions ride a toolbar chip + dropdown: the panel-slim
+  // migration made the planning view the join surface — without this, an
+  // unjoined session had no GUI path into the mesh at all.
+  const netBtn = mkButton('未入网', '未入网会话（点击选择入网）', () => menus.toggleNetMenu())
+  netBtn.className = 'p-netbtn'
+  netBtn.setAttribute('aria-haspopup', 'menu')
+  toolbar.appendChild(netBtn)
+  // Node list (network-membership-display): the canvas shows teamed nodes
+  // only; every other session — teamless joined, unjoined, and each peer's
+  // published nodes — is managed from this list, switched by host.
+  const nodesBtn = mkButton('节点', '节点清单：本机与对等节点（未组队/未入网在此管理）', () => nodes.toggle())
+  nodesBtn.className = 'p-nodebtn'
+  nodesBtn.setAttribute('aria-haspopup', 'dialog')
+  toolbar.appendChild(nodesBtn)
+  const lamp = document.createElement('span')
+  lamp.setAttribute('aria-live', 'polite')
+  lamp.className = 'p-lamp'
+  const lampDot = document.createElement('i')
+  const lampText = document.createElement('span')
+  lampText.textContent = '布局'
+  lamp.append(lampDot, lampText)
+  lamp.addEventListener('click', () => { if (lamp.classList.contains('error')) deps.onLampClick() }, signal)
+  lamp.addEventListener('keydown', (ev) => {
+    const e = ev as KeyboardEvent
+    if ((e.key === 'Enter' || e.key === ' ') && lamp.classList.contains('error')) {
+      e.preventDefault()
+      deps.onLampClick()
+    }
+  }, signal)
+  toolbar.appendChild(lamp)
+
+  const status = document.createElement('div')
+  status.className = 'p-status'
+  const statusLive = document.createElement('span')
+  const statusCold = document.createElement('span')
+  const statusAct = document.createElement('span')
+  statusAct.className = 'mut'
+  const statusMut = document.createElement('span')
+  statusMut.className = 'mut'
+  status.append(statusLive, statusCold, statusAct, statusMut)
+  // Fly control (PR D): the whole statusbar fits the frames ∪ peers region,
+  // keyboard-parity via Enter/Space with a focus ring (a11y parity with 0).
+  status.tabIndex = 0
+  status.setAttribute('role', 'button')
+  status.setAttribute('aria-label', '定位在途路由与联邦对端')
+  status.title = '定位在途与联邦（回车）'
+  status.addEventListener('click', () => flyToFederation(), signal)
+  status.addEventListener('keydown', (ev) => {
+    const e = ev as KeyboardEvent
+    if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); flyToFederation() }
+  }, signal)
+
+  const legend = document.createElement('div')
+  legend.className = 'p-legend'
+  const legendRow = (dashed: boolean, text: string, color?: string): void => {
+    const row = document.createElement('span')
+    const bar = document.createElement('i')
+    if (dashed) bar.className = 'dashed'
+    if (color !== undefined) bar.style.borderTopColor = color
+    row.append(bar, document.createTextNode(text))
+    legend.appendChild(row)
+  }
+  legendRow(false, '成员边（星形，框→成员）')
+  legendRow(true, '跨队多属（虚线）')
+  legendRow(false, '活动边（inFlight 路由，瞬时）', 'var(--accent)')
+  legendRow(true, '联邦线（→peer）', 'var(--federal)')
+
+  const noticeStack = document.createElement('div')
+  noticeStack.className = 'p-notice-stack'
+  noticeStack.setAttribute('role', 'log')
+  noticeStack.setAttribute('aria-live', 'polite')
+
+  root.append(grid, world, marquee, toolbar, status, legend, noticeStack)
+
+  // ── viewport application ──
+  let viewW = 0
+  let viewH = 0
+  const measure = (): { w: number; h: number } =>
+    deps.viewSize ? deps.viewSize() : { w: root.clientWidth, h: root.clientHeight }
+  const syncViewSize = (): void => {
+    const size = measure()
+    viewW = size.w
+    viewH = size.h
+  }
+
+  function applyViewport(): void {
+    world.style.transform = worldTransformCss(vp)
+    const step = 24 * vp.scale
+    grid.style.backgroundSize = `${step}px ${step}px`
+    grid.style.backgroundPosition = `${-vp.x * vp.scale}px ${-vp.y * vp.scale}px`
+    zoomLabel.textContent = `${Math.round(vp.scale * 100)}%`
+  }
+
+  function render(): void {
+    applyViewport()
+    if (model.revision !== renderedRevision) {
+      renderedRevision = model.revision
+      renderFrames()
+      renderNodes()
+      renderEdges()
+    }
+    renderFederation()
+  }
+
+  // ── keyed diff: frames ──
+  // Element maps instead of selector lookups: keyed identity for focus and
+  // transitions, no CSS.escape dependency, O(1) per row.
+  const frameEls = new Map<string, HTMLElement>()
+  const nodeEls = new Map<string, HTMLElement>()
+
+  function renderFrames(): void {
+    const seen = new Set<string>()
+    for (const [name, rect] of model.allFrames()) {
+      seen.add(name)
+      let el = frameEls.get(name)
+      if (el === undefined) {
+        el = document.createElement('div')
+        el.className = 'p-frame'
+        el.dataset.name = name
+        const head = document.createElement('div')
+        head.className = 'p-frame-head'
+        head.dataset.frame = name
+        head.tabIndex = 0 // keyboard: Shift+F10 menu, Delete 散队
+        head.setAttribute('role', 'button')
+        head.setAttribute('aria-haspopup', 'menu')
+        head.setAttribute('aria-label', `团队框 ${name}（拖动整组，回车菜单）`)
+        const title = document.createElement('span')
+        title.className = 'ttl'
+        const cnt = document.createElement('span')
+        cnt.className = 'cnt mono'
+        const route = document.createElement('span')
+        route.className = 'route mono'
+        head.append(title, cnt, route)
+        el.appendChild(head)
+        // Resize handles (owner ruling: the frame canvas is stretchable and
+        // adjustable): eight directions, pointer seam routes them to the
+        // frame-resize gesture. Purely visual affordance + hit targets.
+        for (const dir of ['n', 's', 'e', 'w', 'ne', 'nw', 'se', 'sw']) {
+          const handle = document.createElement('div')
+          handle.className = `p-frame-handle p-h-${dir}`
+          handle.dataset.frame = name
+          handle.dataset.dir = dir
+          el.appendChild(handle)
+        }
+        frameLayer.appendChild(el)
+        frameEls.set(name, el)
+      }
+      const hue = frameHue(name)
+      el.style.setProperty('--frame-line', hue.line)
+      el.style.setProperty('--frame-bg', hue.bg)
+      el.style.left = `${rect.x}px`
+      el.style.top = `${rect.y}px`
+      el.style.width = `${rect.w}px`
+      el.style.height = `${rect.h}px`
+      const title = el.querySelector<HTMLElement>('.ttl')!
+      const cnt = el.querySelector<HTMLElement>('.cnt')!
+      const route = el.querySelector<HTMLElement>('.route')!
+      if (title.textContent !== name) title.textContent = name
+      let members = 0
+      let cross = 0
+      for (const m of model.allNodes()) {
+        const mem = m.memberships.find(x => x.team === name)
+        if (mem === undefined) continue
+        members += 1
+        if (m.memberships.length > 1) cross += 1
+      }
+      const cntText = `${members} 成员` + (cross > 0 ? ` +${cross} 跨队` : '')
+      if (cnt.textContent !== cntText) cnt.textContent = cntText
+      const routeText0 = routeText(name)
+      if (route.textContent !== routeText0) route.textContent = routeText0
+    }
+    for (const [name, el] of [...frameEls]) {
+      if (!seen.has(name)) { el.remove(); frameEls.delete(name) }
+    }
+  }
+
+  /** Remote card sub line: score + remote team count/names behind this peer. */
+  function remoteSubText(host: string): string {
+    const rows = lastRemoteTeams.get(host) ?? []
+    const names = rows.map(r => r.name !== undefined && r.name !== '' ? r.name : r.team)
+    const head = names.slice(0, 2).join('、')
+    const more = names.length > 2 ? ` +${names.length - 2}` : ''
+    const score = peerScoreByText.get(host)
+    return (score !== undefined ? `score ${score} · ` : '') + `${rows.length} 远端团队` + (head !== '' ? `：${head}${more}` : '')
+  }
+
+  /** The mono route line `<host>/canvas/<name>` when the payload carries it. */
+  function routeText(name: string): string {
+    const t = lastTeams.find(x => x.name === name)
+    return t?.team ?? name
+  }
+
+  // ── keyed diff: nodes ──
+  function renderNodes(): void {
+    const seen = new Set<string>()
+    for (const n of model.allNodes()) {
+      seen.add(n.id)
+      let el = nodeEls.get(n.id)
+      if (el === undefined) {
+        el = document.createElement('div')
+        el.className = 'p-node'
+        el.dataset.id = n.id
+        el.tabIndex = 0
+        const nm = document.createElement('div')
+        nm.className = 'nm'
+        const dot = document.createElement('span')
+        dot.className = 'dot'
+        const name = document.createElement('span')
+        name.className = 'nm-text'
+        nm.append(dot, name)
+        const sub = document.createElement('div')
+        sub.className = 'sub mono'
+        const prio = document.createElement('span')
+        prio.className = 'prio mono'
+        el.append(nm, sub, prio)
+        nodeLayer.appendChild(el)
+        nodeEls.set(n.id, el)
+      }
+      const r = nodeRect(n)
+      el.style.left = `${r.x}px`
+      el.style.top = `${r.y}px`
+      el.classList.toggle('cold', !n.live)
+      el.classList.toggle('remote', n.remote === true)
+      el.classList.toggle('selected', model.isSelected(n.id))
+      el.setAttribute('aria-selected', String(model.isSelected(n.id)))
+      const host = n.id.slice('peer-'.length)
+      const nmText = n.remote === true ? host : displayName(n)
+      const nmEl = el.querySelector<HTMLElement>('.nm-text')!
+      if (nmEl.textContent !== nmText) nmEl.textContent = nmText
+      const subEl = el.querySelector<HTMLElement>('.sub')!
+      const subBase = n.team + (n.name !== undefined && n.name !== '' ? ' · ' + n.name : '')
+      // When the title fell back to the team label the sub line would repeat
+      // it verbatim; collapse to the cross-team suffix alone in that case.
+      const subText = n.remote === true
+        ? remoteSubText(host)
+        : (subBase === nmText ? '' : subBase)
+          + (n.memberships.length > 1 ? ` · 跨队×${n.memberships.length}` : '')
+          + (n.teams !== undefined && n.teams.length > 0 ? ` · 网络队×${n.teams.length}` : '')
+      if (subEl.textContent !== subText) subEl.textContent = subText
+      const prioEl = el.querySelector<HTMLElement>('.prio')!
+      const prioText = n.remote === true ? 'peer' : (n.memberships[0] !== undefined ? `P${n.memberships[0]!.index}` : '')
+      if (prioEl.textContent !== prioText) prioEl.textContent = prioText
+    }
+    for (const [id, el] of [...nodeEls]) {
+      if (!seen.has(id)) { el.remove(); nodeEls.delete(id) }
+    }
+  }
+
+  // ── edges: stateless, rebuilt wholesale ──
+  // Derived from the MODEL (not lastTeams): optimistic membership changes
+  // must repaint their edges immediately, before the host confirms.
+  function renderEdges(): void {
+    while (svg.firstChild !== null) svg.firstChild.remove()
+    const teams = model.allFrames().map(([name]) => ({ name, members: model.teamMemberIds(name).map(id => ({ id })) }))
+    for (const e of starEdges(teams, new Map(model.allFrames()), model.positions())) {
+      const line = document.createElementNS('http://www.w3.org/2000/svg', 'line')
+      line.setAttribute('class', 'e-member' + (e.dashed ? ' dashed' : ''))
+      line.setAttribute('x1', String(e.x1))
+      line.setAttribute('y1', String(e.y1))
+      line.setAttribute('x2', String(e.x2))
+      line.setAttribute('y2', String(e.y2))
+      svg.appendChild(line)
+    }
+  }
+
+  // ── federation overlay (PR D): peer chips + activity/federal edges ──
+  // Runs on EVERY render, outside the model-revision gate: the poll's
+  // inFlight ages must tick even when the model is unchanged, and the
+  // badge column tracks the content bounds each reconcile. Its SVG
+  // children are tracked separately because renderEdges clears the svg
+  // wholesale - this appends after it (render() orders the two).
+  let fedSvg: SVGElement[] = []
+  let lastPlacements: PeerPlacement[] = []
+  let lastPeers: ReadonlyArray<PeerRow> = []
+  let lastRemoteTeams: ReadonlyMap<string, RemoteTeamRow[]> = new Map()
+  const peerScoreByText = new Map<string, number | undefined>()
+  let lastInFlight: ReadonlyArray<InFlightRow> = []
+
+  function renderFederation(): void {
+    for (const el of fedSvg) el.remove()
+    fedSvg = []
+    // Peer placements come from the MODEL's remote nodes (v1 ruling: peers
+    // are cards in the same pipeline, dragged/saved like sessions) — the
+    // old chip column is gone.
+    const placements: PeerPlacement[] = model.allNodes()
+      .filter(n => n.remote === true)
+      .map(n => ({ url: n.peerUrl ?? n.id.slice(5), score: n.score, x: n.x, y: n.y }))
+    lastPlacements = placements
+    const bounds = model.contentBounds()
+    if (bounds !== null) {
+      // Edges: titlebar anchors (fx + fw/2, fy + 11, edges.ts lockstep).
+      const anchors = new Map<string, FrameAnchor>()
+      for (const [name, rect] of model.allFrames()) {
+        anchors.set(name, { name, x: rect.x + rect.w / 2, y: rect.y + FRAME_HEAD_LIFT })
+      }
+      for (const e of activityEdges(lastInFlight, anchors, placements, clock())) {
+        fedSvg.push(...fedEdge(e, 'e-activity', e.label))
+      }
+      for (const e of federalEdges(placements, bounds)) {
+        fedSvg.push(...fedEdge(e, 'e-federal', e.label))
+      }
+    }
+  }
+
+  /** One overlay line + its optional midpoint label (offset +14/+18). */
+  function fedEdge(
+    e: { x1: number; y1: number; x2: number; y2: number },
+    cls: string,
+    label: string,
+  ): SVGElement[] {
+    const line = document.createElementNS('http://www.w3.org/2000/svg', 'line')
+    line.setAttribute('class', cls)
+    line.setAttribute('x1', String(e.x1))
+    line.setAttribute('y1', String(e.y1))
+    line.setAttribute('x2', String(e.x2))
+    line.setAttribute('y2', String(e.y2))
+    svg.appendChild(line)
+    const out: SVGElement[] = [line]
+    if (label !== '') {
+      const t = document.createElementNS('http://www.w3.org/2000/svg', 'text')
+      t.setAttribute('class', 'edge-label mono')
+      t.setAttribute('x', String((e.x1 + e.x2) / 2 + 14))
+      t.setAttribute('y', String((e.y1 + e.y2) / 2 + 18))
+      t.textContent = label
+      svg.appendChild(t)
+      out.push(t)
+    }
+    return out
+  }
+
+  /** Statusbar fly: fit the frames ∪ peers region (flyBounds pads it). */
+  function flyToFederation(): void {
+    vp = fitView(flyBounds(model.contentBounds(), lastPlacements), root.clientWidth || viewW, root.clientHeight || viewH)
+    applyViewport()
+    markDirty()
+  }
+
+  // ── status counts ──
+  function renderStatus(input: PlanningInput): void {
+    const live = input.sessions.filter(s => s.live !== false).length
+    const cold = input.sessions.length - live
+    statusLive.textContent = ''
+    const bLive = document.createElement('b')
+    bLive.className = 'ok'
+    bLive.textContent = `● ${live} live`
+    statusLive.appendChild(bLive)
+    statusCold.textContent = ''
+    const bCold = document.createElement('b')
+    bCold.className = 'warn'
+    bCold.textContent = `● ${cold} cold`
+    statusCold.appendChild(bCold)
+    statusAct.textContent = `${input.inFlight?.length ?? 0} inFlight`
+    statusMut.className = 'mut'
+    statusMut.textContent = `${input.teams.length} 队 · ${input.peerCount} peer`
+  }
+
+  // ── canvas write actions: optimistic apply + team-scoped undo ──
+  // Per-team REFERENCE COUNT: two queued actions on one team keep the guard
+  // up until BOTH settle (a Set deleted per action let a mid-queue poll wipe
+  // the second action's optimistic membership).
+  const pendingTeams = new Map<string, number>()
+  const pendingAdd = (team: string): void => { pendingTeams.set(team, (pendingTeams.get(team) ?? 0) + 1) }
+  const pendingRelease = (team: string): void => {
+    const n = (pendingTeams.get(team) ?? 0) - 1
+    if (n <= 0) pendingTeams.delete(team)
+    else pendingTeams.set(team, n)
+  }
+
+  function emitAction(a: CanvasAction): void {
+    // Optimistic seats: a write may reference a session the teamed gate
+    // keeps OFF the model (no canvas card yet). The write actions read and
+    // write memberships through the node table, so materialize those ids
+    // from the last poll's inventory first — the next reconcile refreshes
+    // label/live/teams and keeps the saved-or-seat position.
+    if (a.type === 'add-member' || a.type === 'remove-member' || a.type === 'reorder' || a.type === 'create-team') {
+      const ids = a.type === 'reorder' ? a.ops.map(op => op.id) : [...a.ids]
+      for (const id of ids) {
+        if (id === '' || id.startsWith('peer-')) continue
+        if (model.getNode(id) !== undefined) continue
+        const s = lastSessions.find(row => row.id === id)
+        if (s === undefined) continue
+        const saved = layoutDoc?.nodes[id]
+        const seat = saved !== undefined ? { x: saved.x, y: saved.y } : seatFor2(id)
+        model.upsertNode({
+          id, x: seat.x, y: seat.y, label: s.label, team: s.team, name: s.name,
+          live: s.live !== false, memberships: [],
+          ...(s.teams !== undefined && s.teams.length > 0 ? { teams: s.teams } : {}),
+        })
+      }
+    }
+    const undo = applyAction(model, a)
+    const team = actionTeam(a)
+    pendingAdd(team)
+    render()
+    void deps.onCanvasAction(a).then(
+      ok => {
+        pendingRelease(team)
+        if (!ok) undo() // host refused: roll this action's optimistic delta back
+        render()
+      },
+      () => {
+        // Contract-robustness: a rejecting action channel must not pin the
+        // team's guard (and its optimistic state) forever — and per §3.4
+        // 不吞错, the rollback surfaces to the user.
+        pendingRelease(team)
+        undo()
+        notice('error', '操作通道异常，已回滚')
+        render()
+      },
+    )
+  }
+
+  // ── notices (host errors verbatim; design.md §3.4 不吞错) ──
+  function notice(kind: 'error' | 'info', text: string): void {
+    while (noticeStack.childElementCount >= 3) noticeStack.firstElementChild?.remove()
+    const item = document.createElement('div')
+    item.className = 'p-notice' + (kind === 'error' ? ' error' : '')
+    item.setAttribute('role', kind === 'error' ? 'alert' : 'status')
+    item.textContent = text
+    noticeStack.appendChild(item)
+    noticeTimers.push(setTimeout(() => item.remove(), 4000))
+  }
+
+  // ── popovers: 建队 dialog, context menu, 未入网 dropdown (planning-menus) ──
+  const menus = createPlanningMenus({
+    root, netBtn, signal, model,
+    teams: () => lastTeams,
+    anchorFor: (t) => (t.kind === 'node' ? nodeEls.get(t.id) : frameEls.get(t.name)) ?? null,
+    emit: emitAction,
+    notice,
+  })
+
+  // ── 节点列表 drawer (planning-nodelist) ──
+  let lastSessions: ReadonlyArray<PlanningSession> = []
+  let lastCanvasMemberIds: ReadonlySet<string> = new Set()
+  const nodes = createNodeList({
+    root, trigger: nodesBtn, signal, model,
+    facts: () => ({ sessions: lastSessions, canvasMemberIds: lastCanvasMemberIds, remoteTeams: lastRemoteTeams, teams: lastTeams }),
+    menuItem: menus.menuItem,
+    emit: emitAction,
+    openNameDialog: menus.openNameDialog,
+    locate: locateNode,
+  })
+
+  /** Center the viewport on one canvas node (the 已组队 row's 定位). */
+  function locateNode(id: string): void {
+    const n = model.getNode(id)
+    if (n === undefined) return
+    nodes.close()
+    const size = deps.viewSize?.() ?? { w: root.clientWidth > 0 ? root.clientWidth : 800, h: root.clientHeight > 0 ? root.clientHeight : 600 }
+    vp = clampViewport({ scale: vp.scale, x: n.x - size.w / (2 * vp.scale), y: n.y - size.h / (2 * vp.scale) })
+    applyViewport()
+    renderedRevision = -1
+    render()
+  }
+
+  // ── gestures ──
+  function localXY(ev: { clientX: number; clientY: number }): { x: number; y: number } {
+    const rect = root.getBoundingClientRect()
+    return { x: ev.clientX - rect.left, y: ev.clientY - rect.top }
+  }
+
+  /** Drop dispatch for a moved node drag: 入队 / 队内 y 排序. Leaving a team
+   * is an explicit menu action only — dragging out to blank is a position
+   * move (owner removal 2026-09-02: the drag-out-to-blank 离队 path is
+   * removed; accidental blank drops wrote whole-group removals). */
+  function dropDispatch(gesture: Extract<Gesture, { kind: 'node' }>, ev: SeamPointer): void {
+    const p = localXY(ev)
+    const w = screenToWorld(vp, p.x, p.y)
+    const f = innermostFrameAt(new Map(model.allFrames()), w)
+    // 契约不变量 1：成员必须 joined session——对等卡永远不进名单写面。
+    const localIds = gesture.ids.filter(id => model.getNode(id)?.remote !== true)
+    if (f !== undefined) {
+      const fresh = localIds.filter(id => !(model.getNode(id)?.memberships.some(m => m.team === f)))
+      if (fresh.length > 0) {
+        emitAction({ type: 'add-member', team: f, ids: fresh }) // 入队：不自动离原队（多对多）
+        return
+      }
+      // Reorder only for LOCAL single-card drops: dropping a peer card is a
+      // position move, never a roster write (P2 from the incremental seat).
+      if (gesture.ids.length === 1 && model.getNode(gesture.clicked)?.remote !== true) {
+        // Already a member: an in-frame drop sorts that frame's members by y.
+        const current = model.teamMemberIds(f)
+        const desired = yOrderedMembers(model, f)
+        if (desired.join('\u0000') !== current.join('\u0000')) {
+          emitAction({ type: 'reorder', team: f, ops: reorderOps(current, desired) })
+        }
+      }
+    }
+    // Blank drop: a position move only. No roster writes — the explicit
+    // context-menu 离队 (and the node drawer) remain the removal paths.
+  }
+
+  function pointerDown(ev: SeamPointer): void {
+    if (viewW === 0) syncViewSize()
+    if (menus.isDialogOpen()) { ev.preventDefault(); return } // modal: no gestures behind the dialog
+    const target = ev.target as Element | null
+    // Context-menu dismissal: the first pointerdown outside an open menu
+    // closes it and is swallowed; a press on the menu's own chrome is
+    // swallowed too — only its items act.
+    if (menus.isMenuOpen()) {
+      if (target !== null && target.closest('.p-menu') !== null) return
+      menus.closeMenu()
+      ev.preventDefault()
+      return
+    }
+    const p = localXY(ev)
+    // 右键按下：按住拖动 = 平移（Figma 惯例），原地抬起 = 上下文菜单。
+    // Pan actually starts on the first move beyond RIGHT_DRAG_THRESHOLD px;
+    // a clean press falls through to the context menu at pointerup.
+    if (ev.button === 2) {
+      rightPress = { x: p.x, y: p.y, target: ev.target, moved: false }
+      ev.preventDefault()
+      try { root.setPointerCapture(ev.pointerId ?? 0) } catch { /* jsdom */ }
+      return
+    }
+    if (target !== null && (target.closest('button') !== null || target.closest('.p-lamp') !== null || target.closest('.p-status') !== null)) return
+    const nodeEl = target !== null ? target.closest<HTMLElement>('.p-node') : null
+    const headEl = target !== null ? target.closest<HTMLElement>('.p-frame-head') : null
+    if ((nodeEl !== null || headEl !== null) && ev.button === 1) {
+      // Middle-button anywhere — including on cards and frame heads — pans
+      // (baf51a1 claimed this; the guards used to swallow it before the pan
+      // branch was reachable, and skipped preventDefault, re-enabling
+      // native autoscroll).
+      gesture = { kind: 'pan', last: p, moved: false }
+      ev.preventDefault()
+      try { root.setPointerCapture(ev.pointerId ?? 0) } catch { /* jsdom */ }
+      return
+    }
+    const handleEl = target !== null ? target.closest<HTMLElement>('.p-frame-handle') : null
+    // Selection clearing: any press NOT on the selected frame's own chrome
+    // (head/handle/body) drops the frame selection.
+    if (selectedFrame !== undefined) {
+      const selFrameEl = frameEls.get(selectedFrame)
+      const onSelectedChrome = target !== null && selFrameEl !== undefined &&
+        (selFrameEl.contains(target) || selFrameEl === target)
+      const onSelectedHead = headEl !== null && headEl.dataset.frame === selectedFrame
+      if (!onSelectedChrome && !onSelectedHead) markSelectedFrame(undefined)
+    }
+    if (handleEl !== null && ev.button === 0) {
+      // Frame resize (owner ruling): record the frame's current rect and
+      // the world-space origin; the move branch re-solves the rect per
+      // direction with a minimum size clamp.
+      const name = handleEl.dataset.frame ?? ''
+      markSelectedFrame(name)
+      const rect = model.getFrame(name)
+      if (rect === undefined) return
+      gesture = { kind: 'frame-resize', name, dir: handleEl.dataset.dir ?? 'se', startRect: { ...rect }, origin: screenToWorld(vp, p.x, p.y), moved: false }
+      ev.preventDefault()
+      try { root.setPointerCapture(ev.pointerId ?? 0) } catch { /* jsdom: no capture */ }
+      return
+    }
+    if (nodeEl !== null) {
+      if (ev.button !== 0) return // right on a card: contextmenu only, never a card drag (F3)
+      const id = nodeEl.dataset.id ?? ''
+      const already = model.isSelected(id)
+      if (!already && !ev.shiftKey) model.setSelection([id])
+      const ids = ev.shiftKey || already ? (model.isSelected(id) ? model.selectedIds() : [...model.selectedIds(), id]) : [id]
+      gesture = { kind: 'node', clicked: id, ids, last: screenToWorld(vp, p.x, p.y), moved: false, el: nodeEl }
+      nodeEl.classList.add('dragging')
+    } else if (headEl !== null) {
+      if (ev.button !== 0) return
+      const name = headEl.dataset.frame ?? ''
+      // Selecting a frame keeps its resize handles visible (hover-only
+      // handles vanished the moment the pointer left).
+      markSelectedFrame(name)
+      const snap = model.beginFrameDrag(name)
+      if (snap === undefined) return
+      gesture = { kind: 'frame', name, snap, origin: screenToWorld(vp, p.x, p.y), moved: false }
+    } else {
+      if (ev.button === 1 || (ev.button === 0 && spaceDown)) {
+        gesture = { kind: 'pan', last: p, moved: false }
+      } else if (ev.button === 0) {
+        gesture = { kind: 'marquee', origin: p, last: p, additive: ev.shiftKey }
+        marquee.style.display = 'block'
+        marquee.style.left = `${p.x}px`
+        marquee.style.top = `${p.y}px`
+        marquee.style.width = '0px'
+        marquee.style.height = '0px'
+      } else return
+    }
+    ev.preventDefault()
+    try { root.setPointerCapture(ev.pointerId ?? 0) } catch { /* jsdom: no capture */ }
+  }
+
+  function pointerMove(ev: SeamPointer): void {
+    const p = localXY(ev)
+    if (rightPress !== null) {
+      // Right-hold pan: incremental viewport follow once past the threshold.
+      // User ruling (2026-08-30): the drag moves the CONTENT, not the window —
+      // drag right and the canvas follows the cursor (Figma convention), so
+      // the viewport origin moves OPPOSITE the pointer delta. The wheel and
+      // middle/space pans keep their own established directions.
+      const dx = p.x - rightPress.x
+      const dy = p.y - rightPress.y
+      if (Math.hypot(dx, dy) > 4) {
+        rightPress.moved = true
+        vp = clampViewport(panBy(vp, -dx, -dy))
+        rightPress.x = p.x
+        rightPress.y = p.y
+        applyViewport()
+      }
+      return
+    }
+    if (gesture.kind === 'node') {
+      const w = screenToWorld(vp, p.x, p.y)
+      const dx = w.x - gesture.last.x
+      const dy = w.y - gesture.last.y
+      if (dx === 0 && dy === 0) return
+      gesture.moved = true
+      gesture.last = w
+      model.dragNodes(gesture.ids, dx, dy)
+      // Drop-target highlight: the innermost frame under the pointer, but
+      // only when the drop would change something (some id not yet member).
+      const f = innermostFrameAt(new Map(model.allFrames()), w)
+      const joinables = gesture.ids.filter(id => model.getNode(id)?.remote !== true)
+      const relevant = f !== undefined && joinables.length > 0
+      for (const [name, el] of frameEls) el.classList.toggle('drop-target', relevant && name === f)
+      render()
+    } else if (gesture.kind === 'frame') {
+      const w = screenToWorld(vp, p.x, p.y)
+      const dx = w.x - gesture.origin.x
+      const dy = w.y - gesture.origin.y
+      if (!gesture.moved && dx === 0 && dy === 0) return
+      gesture.moved = true
+      model.applyFrameDrag(gesture.snap, dx, dy)
+      render()
+    } else if (gesture.kind === 'frame-resize') {
+      // Re-solve the rect from the start rect plus the world delta, per
+      // direction. Minimum 220x120 keeps the titlebar and成员 badges
+      // readable; the frame rect is independent of member positions, so
+      // no node moves — star edges follow on the next render.
+      const w = screenToWorld(vp, p.x, p.y)
+      const dx = w.x - gesture.origin.x
+      const dy = w.y - gesture.origin.y
+      if (!gesture.moved && dx === 0 && dy === 0) return
+      gesture.moved = true
+      const MIN_W = 220
+      const MIN_H = 120
+      const r = { ...gesture.startRect }
+      let { x, y, w: width, h: height } = r
+      if (gesture.dir.includes('e')) width = Math.max(MIN_W, r.w + dx)
+      if (gesture.dir.includes('s')) height = Math.max(MIN_H, r.h + dy)
+      if (gesture.dir.includes('w')) {
+        width = Math.max(MIN_W, r.w - dx)
+        x = r.x + (r.w - width)
+      }
+      if (gesture.dir.includes('n')) {
+        height = Math.max(MIN_H, r.h - dy)
+        y = r.y + (r.h - height)
+      }
+      model.setFrame(gesture.name, { x: Math.round(x), y: Math.round(y), w: Math.round(width), h: Math.round(height) })
+      render()
+    } else if (gesture.kind === 'pan') {
+      vp = panBy(vp, p.x - gesture.last.x, p.y - gesture.last.y)
+      gesture.last = p
+      gesture.moved = true
+      applyViewport()
+    } else if (gesture.kind === 'marquee') {
+      const x = Math.min(gesture.origin.x, p.x)
+      const y = Math.min(gesture.origin.y, p.y)
+      marquee.style.left = `${x}px`
+      marquee.style.top = `${y}px`
+      marquee.style.width = `${Math.abs(p.x - gesture.origin.x)}px`
+      marquee.style.height = `${Math.abs(p.y - gesture.origin.y)}px`
+      gesture.last = p
+    }
+  }
+
+  function pointerUp(ev: SeamPointer): void {
+    if (rightPress !== null) {
+      const wasPan = rightPress.moved
+      const pressTarget = rightPress.target
+      const x = rightPress.x
+      const y = rightPress.y
+      rightPress = null
+      if (wasPan) {
+        suppressNextMenu = true
+        markDirty() // the viewport persists with the layout
+      } else if (pressTarget !== null) {
+        menus.contextMenuAt(x, y, pressTarget) // clean right-click: context menu
+      }
+      return
+    }
+    if (gesture.kind === 'node') {
+      const id = gesture.clicked
+      if (!gesture.moved) {
+        // A click (no drag) is pure selection — NEVER a drop. The F1 fix:
+        // an unmoved multi-select click used to fall through to dropDispatch
+        // and write an entire group's 离队 to the host.
+        if (ev.shiftKey) {
+          const current = model.selectedIds()
+          model.setSelection(current.includes(id) ? current.filter(x => x !== id) : [...current, id])
+        } else {
+          model.setSelection([id])
+          // 0.6.13: a clean single click is also a node pick — the host opens
+          // the chat drawer. Shift-click (multi-select) stays a pure selection.
+          deps.onNodePick?.(id)
+        }
+      } else {
+        dropDispatch(gesture, ev)
+        markDirty()
+      }
+      for (const el of frameEls.values()) el.classList.remove('drop-target')
+      gesture.el?.classList.remove('dragging')
+      render()
+    } else if (gesture.kind === 'frame') {
+      if (gesture.moved) markDirty()
+    } else if (gesture.kind === 'frame-resize') {
+      if (gesture.moved) markDirty() // the resized rect persists with the layout
+    } else if (gesture.kind === 'pan') {
+      if (gesture.moved) markDirty() // the viewport persists with the layout
+    } else if (gesture.kind === 'marquee') {
+      const p = gesture.last
+      const a = screenToWorld(vp, Math.min(gesture.origin.x, p.x), Math.min(gesture.origin.y, p.y))
+      const b = screenToWorld(vp, Math.max(gesture.origin.x, p.x), Math.max(gesture.origin.y, p.y))
+      model.marqueeSelect({ x: a.x, y: a.y, w: b.x - a.x, h: b.y - a.y }, gesture.additive)
+      marquee.style.display = 'none'
+      render()
+    }
+    gesture = { kind: 'none' }
+    try { root.releasePointerCapture(ev.pointerId ?? 0) } catch { /* not captured */ }
+  }
+
+  function wheel(ev: SeamPointer): void {
+    if (menus.isMenuOpen()) menus.closeMenu()
+    const p = localXY(ev)
+    // Wheel = pointer-anchored zoom (owner ruling 2026-09-01: 鼠标滚动 =
+    // 放大缩小), with or without Ctrl — both muscle memories land on the
+    // same action. Shift+wheel keeps the natural-scroll pan as the escape
+    // hatch. Line-mode wheels (Firefox, deltaMode=1) report ~3 per notch.
+    if (ev.shiftKey && !ev.ctrlKey) {
+      const line = ev.deltaMode === 1 ? 16 : 1
+      vp = clampViewport(panBy(vp, (ev.deltaX ?? 0) * line, (ev.deltaY ?? 0) * line))
+    } else {
+      const line = ev.deltaMode === 1 ? 16 : 1
+      const factor = Math.exp(-((ev.deltaY ?? 0) * line) * 0.0015)
+      vp = zoomAt(vp, factor, p.x, p.y)
+    }
+    ev.preventDefault()
+    applyViewport()
+    markDirty()
+  }
+
+  function zoomCenter(factor: number): void {
+    syncViewSize()
+    vp = zoomAt(vp, factor, viewW / 2, viewH / 2)
+    applyViewport()
+    markDirty()
+  }
+
+  function fitToContent(): void {
+    syncViewSize()
+    vp = fitView(model.contentBounds(), viewW, viewH)
+    applyViewport()
+    markDirty()
+  }
+
+  function key(ev: SeamKey): void {
+    if (menus.isDialogOpen()) return // modal: the dialog input handles Enter/Esc itself
+    if (ev.ctrlKey || ev.metaKey) return // browser/OS chords stay browser/OS
+    if (menus.isMenuOpen()) {
+      // The menu owns most keys (its own handler navigates); Escape still
+      // closes from here so a seam/keyboard Esc never gets lost.
+      if (ev.key === 'Escape') { menus.closeMenu(); ev.preventDefault() }
+      return
+    }
+    if (ev.key === ' ' && ev.target === root) { spaceDown = true; ev.preventDefault(); return }
+    // 键盘全等路径（WCAG 2.2 Dragging Movements）：
+    const headTarget = (ev.target as Element | null)?.closest?.('.p-frame-head') ?? null
+    if ((ev.key === 'Enter' || ev.key === ' ') && headTarget !== null) {
+      ev.preventDefault()
+      const r = headTarget.getBoundingClientRect()
+      menus.contextMenuAt(r.left + r.width / 2, r.top + r.height / 2, headTarget)
+      return
+    }
+    if (ev.key === ' ' && (ev.target as Element | null)?.classList?.contains('p-node')) {
+      const el = ev.target as HTMLElement
+      const id = el.dataset.id ?? ''
+      const current = model.selectedIds()
+      model.setSelection(current.includes(id) ? current.filter(x => x !== id) : [...current, id])
+      render()
+      ev.preventDefault()
+      return
+    }
+    if ((ev.key === 'F10' && ev.shiftKey) || ev.key === 'ContextMenu') {
+      ev.preventDefault()
+      const fe = (document.activeElement as Element | null) ?? null
+      const r = fe?.getBoundingClientRect?.() ?? { left: 0, top: 0, width: 0, height: 0 }
+      menus.contextMenuAt(r.left + r.width / 2, r.top + r.height / 2, fe)
+      return
+    }
+    if (ev.key === 'Delete' || ev.key === 'Backspace') { ev.preventDefault(); deleteFocused(); return }
+    if (ev.altKey && (ev.key === 'ArrowUp' || ev.key === 'ArrowDown')) { ev.preventDefault(); altMove(ev.key === 'ArrowUp'); return }
+    if (ev.key === 'g' || ev.key === 'G') { menus.startCreateFromSelection(); return }
+    if (ev.key === '0') { fitToContent(); return }
+    if (ev.key === '=' || ev.key === '+') { zoomCenter(1.2); return }
+    if (ev.key === '-') { zoomCenter(1 / 1.2); return }
+    if (ev.key === 'Escape') {
+      if (menus.isMenuOpen()) { menus.closeMenu(); render(); return } // menu > clear selection
+      model.setSelection([])
+      render()
+      return
+    }
+    const step = ev.shiftKey ? 40 : 8
+    const dxdy: Record<string, [number, number]> = {
+      ArrowLeft: [-step, 0], ArrowRight: [step, 0], ArrowUp: [0, -step], ArrowDown: [0, step],
+    }
+    const d = dxdy[ev.key]
+    if (d !== undefined) {
+      ev.preventDefault()
+      const ids = model.selectedIds()
+      if (ids.length > 0) {
+        model.nudge(ids, d[0]!, d[1]!)
+        render()
+        markDirty()
+      }
+    }
+  }
+
+  /** Delete 按焦点对象：单队卡=离队、多队卡=下钻离队菜单、无队=info、框头=散队。 */
+  function deleteFocused(): void {
+    const fe = document.activeElement as HTMLElement | null
+    const headEl = fe?.closest?.<HTMLElement>('.p-frame-head') ?? null
+    const nodeEl = fe?.closest?.<HTMLElement>('.p-node') ?? null
+    if (headEl !== null) {
+      emitAction({ type: 'remove-team', name: headEl.dataset.frame ?? '' })
+      return
+    }
+    if (nodeEl !== null) {
+      const id = nodeEl.dataset.id ?? ''
+      const teams = model.getNode(id)?.memberships.map(m => m.team) ?? []
+      if (teams.length === 0) { notice('info', '该节点未加入任何团队'); return }
+      if (teams.length === 1) {
+        emitAction({ type: 'remove-member', team: teams[0]!, ids: [id] })
+        return
+      }
+      menus.openMenu(window.innerWidth / 2, window.innerHeight / 2, { kind: 'node', id }, 'leave', nodeEl)
+      return
+    }
+    notice('info', '焦点不在节点或团队框上')
+  }
+
+  /** Alt+↑/↓: move the focused card within its single team's priority. */
+  function altMove(up: boolean): void {
+    const fe = document.activeElement as HTMLElement | null
+    const nodeEl = fe?.closest?.<HTMLElement>('.p-node') ?? null
+    if (nodeEl === null) return
+    const id = nodeEl.dataset.id ?? ''
+    const mem = model.getNode(id)?.memberships ?? []
+    if (mem.length !== 1) return
+    const team = mem[0]!.team
+    const current = model.teamMemberIds(team)
+    const idx = current.indexOf(id)
+    const to = up ? Math.max(0, idx - 1) : Math.min(current.length - 1, idx + 1)
+    if (to === idx) return
+    const desired = [...current]
+    desired.splice(idx, 1)
+    desired.splice(to, 0, id)
+    emitAction({ type: 'reorder', team, ops: reorderOps(current, desired) })
+  }
+
+  function keyUp(ev: SeamKey): void {
+    if (ev.key === ' ') spaceDown = false
+  }
+
+  root.addEventListener('pointerdown', (ev) => pointerDown(ev as unknown as SeamPointer), signal)
+  root.addEventListener('pointermove', (ev) => pointerMove(ev as unknown as SeamPointer), signal)
+  root.addEventListener('pointerup', (ev) => pointerUp(ev as unknown as SeamPointer), signal)
+  root.addEventListener('wheel', (ev) => wheel(ev as unknown as SeamPointer), { ...signal, passive: false })
+  root.addEventListener('keydown', (ev) => key(ev as unknown as SeamKey), signal)
+  root.addEventListener('keyup', (ev) => keyUp(ev as unknown as SeamKey), signal)
+  root.addEventListener('contextmenu', (ev) => {
+    const e = ev as unknown as SeamPointer
+    e.preventDefault()
+    // Right-drag pans (suppressNextMenu); a clean right-click opens the
+    // menu programmatically at pointerup. Either way the native menu dies.
+    e.preventDefault()
+    if (suppressNextMenu) { suppressNextMenu = false; return }
+    menus.contextMenuAt(e.clientX, e.clientY, e.target)
+  }, signal)
+
+  // ── poll reconcile: incremental, never repositions existing nodes ──
+  let lastTeams: ReadonlyArray<PlanningTeam> = []
+
+  function reconcile(input: PlanningInput): void {
+    lastTeams = input.teams
+    lastPeers = input.peers ?? []
+    lastInFlight = input.inFlight ?? []
+    // Unjoined sessions have no node on the canvas — the panel-slim
+    // migration made this view the join surface, so they ride a compact
+    // toolbar chip instead of vanishing entirely.
+    lastSessions = input.sessions
+    menus.setUnjoined(input.sessions.filter(s => s.joined !== true && !s.id.startsWith('peer-')))
+    const memberships = new Map<string, Array<{ team: string; index: number }>>()
+    for (const team of input.teams) {
+      for (let i = 0; i < team.members.length; i++) {
+        const id = team.members[i]!.id
+        const list = memberships.get(id) ?? []
+        list.push({ team: team.name, index: i })
+        memberships.set(id, list)
+      }
+    }
+    lastCanvasMemberIds = new Set(memberships.keys())
+    const seen = new Set<string>()
+    // In-flight write guard: membership entries of teams with unsettled
+    // writes come from the model, not the (stale) payload — a poll racing
+    // an optimistic add must not snap the new edge away.
+    const resolveMemberships = (id: string): Array<{ team: string; index: number }> => {
+      const payload = memberships.get(id) ?? []
+      if (pendingTeams.size === 0) return payload
+      const keep = payload.filter(m => !pendingTeams.has(m.team))
+      // In-flight teams read their in-membership from the team roster
+      // (teamMemberIds), NOT from getNode(id).memberships: an optimistic
+      // add can target a node the teamed gate kept OFF the model (no card
+      // yet) — its membership lives only in the roster map, and dropping
+      // it here would pop the node right back off the canvas mid-flight.
+      const pending: Array<{ team: string; index: number }> = []
+      for (const [team] of pendingTeams) {
+        const roster = model.teamMemberIds(team)
+        const index = roster.indexOf(id)
+        if (index >= 0) pending.push({ team, index })
+      }
+      return [...keep, ...pending]
+    }
+    // First build with nothing saved: seat the fleet team by team (see
+    // planTeamClusters). Later arrivals, or any board with a saved layout,
+    // keep the ring fallback.
+    let clusterSeats: Map<string, { x: number; y: number }> | undefined
+    if (layoutDoc === undefined && !model.allNodes().some(n => n.remote !== true)) {
+      const seatIds = input.sessions
+        .filter(s => s.joined === true && (resolveMemberships(s.id).length > 0 || (s.teams?.length ?? 0) > 0))
+        .map(s => s.id)
+      syncViewSize()
+      clusterSeats = planTeamClusters(input.teams, seatIds, viewW > 0 ? viewW : undefined)
+    }
+    for (const s of input.sessions) {
+      if (s.joined !== true) continue
+      // Teamed-only canvas (network-membership-display ruling): a joined
+      // session earns a canvas node only with a team — canvas membership
+      // (optimistic-aware) or a declared roster team. Teamless joined
+      // sessions ride the node list's 未组队 group instead; sessions absent
+      // from `seen` are swept from the model below.
+      const effective = resolveMemberships(s.id)
+      if (effective.length === 0 && (s.teams === undefined || s.teams.length === 0)) continue
+      seen.add(s.id)
+      if (model.getNode(s.id) !== undefined) {
+        model.upsertNode({
+          id: s.id, x: model.getNode(s.id)!.x, y: model.getNode(s.id)!.y,
+          label: s.label, team: s.team, name: s.name, live: s.live !== false,
+          memberships: effective,
+          ...(s.teams !== undefined && s.teams.length > 0 ? { teams: s.teams } : {}),
+        })
+      } else {
+        const saved = layoutDoc?.nodes[s.id]
+        let x: number
+        let y: number
+        if (saved !== undefined) { x = saved.x; y = saved.y } else {
+          const seat = clusterSeats?.get(s.id) ?? seatFor2(s.id)
+          x = seat.x
+          y = seat.y
+        }
+        model.upsertNode({
+          id: s.id, x, y, label: s.label, team: s.team, name: s.name, live: s.live !== false,
+          memberships: effective,
+          ...(s.teams !== undefined && s.teams.length > 0 ? { teams: s.teams } : {}),
+        })
+      }
+    }
+    for (const id of model.nodeIds()) {
+      if (!seen.has(id) && !id.startsWith('peer-')) model.removeNode(id)
+    }
+
+    // Peer nodes (v1 ruling): same model pipeline as sessions, `remote` flag
+    // on. Saved positions win; new peers take the deterministic column over
+    // the LOCAL content bounds (remote cards hang outside the field and are
+    // excluded from bounds, so the column cannot feed back into itself).
+    const peerSeen = new Set<string>()
+    lastRemoteTeams = groupRemoteTeams(input.remoteTeams ?? [])
+    peerScoreByText.clear()
+    for (const p of input.peers ?? []) {
+      peerScoreByText.set(peerHostOf(p.url), p.score)
+    }
+    if (input.peers !== undefined) {
+      const localBounds = model.contentBounds()
+      const placements = placePeers(input.peers, localBounds)
+      input.peers.forEach((p, i) => {
+        const id = peerNodeId(p.url)
+        peerSeen.add(id)
+        const saved = layoutDoc?.nodes[id]
+        const existing = model.getNode(id)
+        const base = existing !== undefined
+          ? { x: existing.x, y: existing.y }
+          : saved !== undefined
+            ? { x: saved.x, y: saved.y }
+            : { x: placements[i]?.x ?? 200, y: placements[i]?.y ?? 0 }
+        model.upsertNode({
+          id, x: base.x, y: base.y,
+          label: p.url, team: '', name: p.url, peerUrl: p.url,
+          live: true, remote: true, memberships: [],
+        })
+        model.upsertScore(id, p.score)
+      })
+    }
+    for (const id of model.nodeIds()) {
+      if (id.startsWith('peer-') && !peerSeen.has(id)) model.removeNode(id)
+    }
+    const homes = homeTeams(input.teams)
+    for (const team of input.teams) {
+      if (model.getFrame(team.name) !== undefined) continue // live rect wins
+      if (pendingTeams.has(team.name)) continue // 散队 in flight: don't resurrect
+      const saved = layoutDoc?.frames[team.name]
+      if (saved !== undefined) { model.setFrame(team.name, { ...saved }); continue }
+      // A derived frame wraps its HOME members only: a cross-team member is
+      // reached by its dashed edge, not by stretching this frame over its
+      // home frame. A team made only of members homed elsewhere falls back
+      // to wrapping them all.
+      const rects: LayoutRect[] = []
+      const all: LayoutRect[] = []
+      for (const m of team.members) {
+        const n = model.getNode(m.id)
+        if (n === undefined) continue
+        all.push(nodeRect(n))
+        if (homes.get(m.id) === team.name) rects.push(nodeRect(n))
+      }
+      const wrap = rects.length > 0 ? rects : all
+      if (wrap.length > 0) model.setFrame(team.name, deriveInitialFrame(wrap))
+    }
+    for (const [name] of model.allFrames()) {
+      if (pendingTeams.has(name)) continue // an in-flight create/remove owns this name
+      if (!input.teams.some(t => t.name === name)) model.removeFrame(name)
+    }
+    // An open node panel follows the poll: facts (joins, leaves, team
+    // declarations, peer arrivals) land within one cadence.
+    nodes.refresh()
+    renderStatus(input)
+    // First-run framing: with no saved layout the ring seats are centered on
+    // world (0,0) while the viewport origin is the board's top-left corner,
+    // so half the fleet landed above/left of the view and a healthy board
+    // opened empty. Fit once, the first time there is something to frame.
+    // Not marked dirty — nothing the user arranged changed; a saved layout
+    // (adopted at any point) keeps its own viewport and cancels this.
+    if (firstFitPending && gesture.kind === 'none' && model.nodeIds().length > 0) {
+      syncViewSize()
+      if (viewW > 0 && viewH > 0) {
+        firstFitPending = false
+        // Peer cards hang outside the local content bounds — frame them too,
+        // or the federation column opens clipped at the board's edge.
+        let bounds = model.contentBounds()
+        for (const n of model.allNodes()) {
+          if (n.remote !== true) continue
+          const r = nodeRect(n)
+          bounds = bounds === null
+            ? { minX: r.x, minY: r.y, maxX: r.x + r.w, maxY: r.y + r.h }
+            : { minX: Math.min(bounds.minX, r.x), minY: Math.min(bounds.minY, r.y), maxX: Math.max(bounds.maxX, r.x + r.w), maxY: Math.max(bounds.maxY, r.y + r.h) }
+        }
+        vp = fitView(bounds, viewW, viewH, 1) // frame, never magnify
+      }
+    }
+    render()
+  }
+
+  // Same fallback contract as WorldModel.fromState: the card-scaled ring.
+  function seatFor2(id: string): { x: number; y: number } {
+    return planSeatClear(id, model.allNodes().filter(n => n.remote !== true))
+  }
+
+  function adoptExternalLayout(layout: unknown): void {
+    const doc = clampDoc(layout)
+    if (doc === undefined) return
+    layoutDoc = doc
+    const store = deps.viewportStore
+    if (store === undefined) {
+      firstFitPending = false
+      if (gesture.kind === 'none') vp = clampViewport({ ...doc.viewport })
+    } else if (!viewportAdopted && gesture.kind === 'none') {
+      viewportAdopted = true
+      const local = store.get(bucket()) as Partial<LayoutViewport> | null | undefined
+      if (local != null && Number.isFinite(local.x) && Number.isFinite(local.y) && Number.isFinite(local.scale)) {
+        vp = clampViewport({ x: local.x!, y: local.y!, scale: local.scale! })
+        firstFitPending = false
+      } else if (bucket() === 'wide') {
+        vp = clampViewport({ ...doc.viewport })
+        firstFitPending = false
+      } // narrow/medium with no memory of its own: keep firstFitPending, frame on reconcile
+    }
+    renderedRevision = -1 // force a repaint of frames/edges on next render
+    render()
+  }
+
+  function snapshotDoc(): unknown {
+    return buildLayoutDoc(vp, model.positions(), model.frameRects())
+  }
+
+  function setLamp(state: LampState, savedAt?: string): void {
+    lamp.classList.remove('pending', 'saved', 'error')
+    if (state === 'pending') lamp.classList.add('pending')
+    if (state === 'saved') lamp.classList.add('saved')
+    if (state === 'error') lamp.classList.add('error')
+    // Error state is a keyboard-reachable retry control (review P0-2).
+    if (state === 'error') {
+      lamp.tabIndex = 0
+      lamp.setAttribute('role', 'button')
+      lamp.setAttribute('aria-label', '布局保存失败，按回车重试')
+    } else {
+      lamp.removeAttribute('tabindex')
+      lamp.removeAttribute('role')
+      lamp.removeAttribute('aria-label')
+    }
+    const text = state === 'pending' ? '布局待保存…'
+      : state === 'saved' ? `布局已保存 ${savedAt ?? ''}`.trimEnd()
+      : state === 'error' ? '保存失败 · 回车重试'
+      : '布局'
+    lampText.textContent = text
+  }
+
+  function activate(): void {
+    root.style.display = 'block'
+    syncViewSize()
+    applyViewport()
+    root.focus()
+  }
+
+  function deactivate(): void { root.style.display = 'none' }
+
+  function destroy(): void {
+    ac.abort()
+    for (const t of noticeTimers) clearTimeout(t)
+  }
+
+  return {
+    root,
+    reconcile,
+    activate,
+    deactivate,
+    adoptExternalLayout,
+    snapshotDoc,
+    setLamp,
+    notice,
+    destroy,
+    seam: {
+      pointerDown,
+      pointerMove,
+      pointerUp,
+      wheel,
+      key,
+      keyUp,
+      contextMenu(ev: SeamPointer): void {
+        ev.preventDefault()
+        menus.contextMenuAt(ev.clientX, ev.clientY, ev.target)
+      },
+    },
+  }
+}