@nelsonlongxiang/dsh-open-a2a-net 0.6.41 → 0.6.43

package/nexus-stage/src/planning-card-text.ts

@@ -1,73 +1,73 @@
-/**
- * Board card text (review 2026-10-27): what a card's title, second line and
- * tooltip say. Extracted from planning-view so the card rules read in one
- * place (and the view stays under its M1 module-size cap).
- *
- * - Session cards used to read `dsh/11111111 · scout-01` on the second line:
- *   the title repeated, the handle truncated on every card. The line now
- *   carries what the session is FOR (its description) and falls back to the
- *   handle; the handle always rides the tooltip.
- * - Peer cards titled `192.168.3.157:13080`, clipped by the peer badge with no
- *   break point. When the host publishes exactly one named team (its host
- *   row), that name is the title and the address moves to the second line.
- * @module nexus-stage/planning-card-text
- */
-import { displayName } from './stage-name'
-import type { RemoteTeamRow } from './federation'
-import type { WorldNode } from './world'
-
-export interface CardText { readonly title: string; readonly sub: string; readonly tip: string }
-
-/**
- * A description as one plain line. /state `description` is the session's
- * recent-activity excerpt — the head of its last reply, newlines folded,
- * capped at 160 chars — so on a real host it reads `# ✅ 已纠正——…`,
- * `**全绿**`, `` `direct-…` `` and folded tables (`| 环节 | 结果 | |---|`).
- * The card keeps the prose: it stops at the first table or code fence and
- * drops heading, emphasis, code and link markup.
- */
-export function plainLine(text: string): string {
-  let s = text
-  const stop = s.search(/\|| ```|^```/)
-  if (stop >= 0) s = s.slice(0, stop)
-  return s
-    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // [text](url) → text
-    .replace(/(^|\s)#{1,6}\s+/g, '$1') // headings
-    .replace(/\*\*|__|`/g, '') // bold, code
-    .replace(/\s+/g, ' ')
-    .trim()
-}
-
-/** The remote-team summary a peer card carries: score + count + first names. */
-function remoteSummary(rows: ReadonlyArray<RemoteTeamRow>, score: number | undefined): string {
-  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}` : ''
-  return (score !== undefined ? `score ${score} · ` : '') + `${rows.length} 远端团队` + (head !== '' ? `：${head}${more}` : '')
-}
-
-export function cardText(n: WorldNode, remoteRows: ReadonlyArray<RemoteTeamRow>, score: number | undefined): CardText {
-  // gh#38: member cards show their display NAME as the title (the whole
-  // point is picking a person).
-  if (n.id.startsWith('member-')) {
-    const title = n.name !== undefined && n.name !== '' ? n.name : n.team
-    return { title, sub: n.team, tip: n.team }
-  }
-  if (n.remote === true) {
-    const host = n.id.slice('peer-'.length)
-    const named = remoteRows.length === 1 && remoteRows[0]!.name !== undefined && remoteRows[0]!.name !== '' ? remoteRows[0]!.name : undefined
-    const summary = remoteSummary(remoteRows, score)
-    return named !== undefined
-      ? { title: named, sub: `${host} · ${summary}`, tip: `${named}\n${host}\n${summary}` }
-      : { title: host, sub: summary, tip: `${host}\n${summary}` }
-  }
-  const title = displayName(n)
-  const handle = n.team + (n.name !== undefined && n.name !== '' ? ' · ' + n.name : '')
-  const desc = plainLine(n.description ?? '')
-  // When the title fell back to the team label the handle would repeat it
-  // verbatim; then only the suffixes remain.
-  const base = desc !== '' ? desc : handle === title ? '' : n.team
-  const suffix = (n.memberships.length > 1 ? ` · 跨队×${n.memberships.length}` : '')
-    + (n.teams !== undefined && n.teams.length > 0 ? ` · 网络队×${n.teams.length}` : '')
-  return { title, sub: base + suffix, tip: desc !== '' ? `${handle}\n${desc}` : handle }
-}
+/**
+ * Board card text (review 2026-10-27): what a card's title, second line and
+ * tooltip say. Extracted from planning-view so the card rules read in one
+ * place (and the view stays under its M1 module-size cap).
+ *
+ * - Session cards used to read `dsh/11111111 · scout-01` on the second line:
+ *   the title repeated, the handle truncated on every card. The line now
+ *   carries what the session is FOR (its description) and falls back to the
+ *   handle; the handle always rides the tooltip.
+ * - Peer cards titled `192.168.3.157:13080`, clipped by the peer badge with no
+ *   break point. When the host publishes exactly one named team (its host
+ *   row), that name is the title and the address moves to the second line.
+ * @module nexus-stage/planning-card-text
+ */
+import { displayName } from './stage-name'
+import type { RemoteTeamRow } from './federation'
+import type { WorldNode } from './world'
+
+export interface CardText { readonly title: string; readonly sub: string; readonly tip: string }
+
+/**
+ * A description as one plain line. /state `description` is the session's
+ * recent-activity excerpt — the head of its last reply, newlines folded,
+ * capped at 160 chars — so on a real host it reads `# ✅ 已纠正——…`,
+ * `**全绿**`, `` `direct-…` `` and folded tables (`| 环节 | 结果 | |---|`).
+ * The card keeps the prose: it stops at the first table or code fence and
+ * drops heading, emphasis, code and link markup.
+ */
+export function plainLine(text: string): string {
+  let s = text
+  const stop = s.search(/\|| ```|^```/)
+  if (stop >= 0) s = s.slice(0, stop)
+  return s
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // [text](url) → text
+    .replace(/(^|\s)#{1,6}\s+/g, '$1') // headings
+    .replace(/\*\*|__|`/g, '') // bold, code
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/** The remote-team summary a peer card carries: score + count + first names. */
+function remoteSummary(rows: ReadonlyArray<RemoteTeamRow>, score: number | undefined): string {
+  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}` : ''
+  return (score !== undefined ? `score ${score} · ` : '') + `${rows.length} 远端团队` + (head !== '' ? `：${head}${more}` : '')
+}
+
+export function cardText(n: WorldNode, remoteRows: ReadonlyArray<RemoteTeamRow>, score: number | undefined): CardText {
+  // gh#38: member cards show their display NAME as the title (the whole
+  // point is picking a person).
+  if (n.id.startsWith('member-')) {
+    const title = n.name !== undefined && n.name !== '' ? n.name : n.team
+    return { title, sub: n.team, tip: n.team }
+  }
+  if (n.remote === true) {
+    const host = n.id.slice('peer-'.length)
+    const named = remoteRows.length === 1 && remoteRows[0]!.name !== undefined && remoteRows[0]!.name !== '' ? remoteRows[0]!.name : undefined
+    const summary = remoteSummary(remoteRows, score)
+    return named !== undefined
+      ? { title: named, sub: `${host} · ${summary}`, tip: `${named}\n${host}\n${summary}` }
+      : { title: host, sub: summary, tip: `${host}\n${summary}` }
+  }
+  const title = displayName(n)
+  const handle = n.team + (n.name !== undefined && n.name !== '' ? ' · ' + n.name : '')
+  const desc = plainLine(n.description ?? '')
+  // When the title fell back to the team label the handle would repeat it
+  // verbatim; then only the suffixes remain.
+  const base = desc !== '' ? desc : handle === title ? '' : n.team
+  const suffix = (n.memberships.length > 1 ? ` · 跨队×${n.memberships.length}` : '')
+    + (n.teams !== undefined && n.teams.length > 0 ? ` · 网络队×${n.teams.length}` : '')
+  return { title, sub: base + suffix, tip: desc !== '' ? `${handle}\n${desc}` : handle }
+}

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

@@ -1,63 +1,63 @@
-/**
- * Board node card: the DOM skeleton and the right-hand chip. Extracted from planning-view so the card's static
- * structure reads in one place and the view stays under its M1 module-size cap (1507 lines; it reached 1529 with
- * the 工作中/空闲 chip). Pure DOM helpers — no view state; renderNodes still decides what each card shows.
- * @module nexus-stage/planning-card
- */
-import type { PlanningSession } from './planning-types'
-import type { WorldNode } from './world'
-
-/** The card's 工作中/空闲 chip text; empty when the host reported no status (older host, cold or remote node). */
-export function workLabel(work: Pick<PlanningSession, 'status' | 'queued'> | undefined): string {
-  if (work?.status === undefined) return ''
-  const base = work.status === 'running' ? '工作中' : '空闲'
-  return typeof work.queued === 'number' && work.queued > 0 ? `${base} · 排队 ${String(work.queued)}` : base
-}
-
-/** A fresh `.p-node` card: title row (dot + text), second row (description + 工作中/空闲 chip), and the right-hand chip. */
-export function createCardElement(id: string): HTMLDivElement {
-  const el = document.createElement('div')
-  el.className = 'p-node'
-  el.dataset.id = 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'
-  // Second line: the description, with the 工作中/空闲 chip at its right end — the title keeps its full width.
-  const work = document.createElement('span')
-  work.className = 'work'
-  const subRow = document.createElement('div')
-  subRow.className = 'sub-row'
-  subRow.append(sub, work)
-  el.append(nm, subRow, prio)
-  return el
-}
-
-/**
- * The right-hand chip. Peer cards show the link badge (gh#20 W-A: linked green / stranger gray, then the
- * verified tick/cross; an absent link field from an older host renders the neutral 'peer'). A remote MEMBER card
- * (gh#38) is one session on that host, not the host: it reads 成员, colored and ticked by its host's link
- * (it used to fall through to 'peer' and looked like a host card). Session cards show their first membership
- * priority `P<n>`. Writes only on change.
- */
-export function paintPrio(prioEl: HTMLElement, n: WorldNode, info: { link?: 'linked' | 'stranger'; verified?: boolean } | undefined): void {
-  if (n.remote === true) {
-    const cls = info?.link === 'linked' ? 'lnk-linked' : info?.link === 'stranger' ? 'lnk-stranger' : ''
-    if (prioEl.className !== `prio mono ${cls}`.trim()) prioEl.className = `prio mono ${cls}`.trim()
-    const mark = info === undefined ? '' : info.verified === true ? '✓' : '✗'
-    const badge = (n.id.startsWith('member-') ? '成员' : info?.link ?? 'peer') + mark
-    if (prioEl.textContent !== badge) prioEl.textContent = badge
-  } else {
-    if (prioEl.className !== 'prio mono') prioEl.className = 'prio mono'
-    const prioText = n.memberships[0] !== undefined ? `P${n.memberships[0]!.index}` : ''
-    if (prioEl.textContent !== prioText) prioEl.textContent = prioText
-  }
-}
+/**
+ * Board node card: the DOM skeleton and the right-hand chip. Extracted from planning-view so the card's static
+ * structure reads in one place and the view stays under its M1 module-size cap (1507 lines; it reached 1529 with
+ * the 工作中/空闲 chip). Pure DOM helpers — no view state; renderNodes still decides what each card shows.
+ * @module nexus-stage/planning-card
+ */
+import type { PlanningSession } from './planning-types'
+import type { WorldNode } from './world'
+
+/** The card's 工作中/空闲 chip text; empty when the host reported no status (older host, cold or remote node). */
+export function workLabel(work: Pick<PlanningSession, 'status' | 'queued'> | undefined): string {
+  if (work?.status === undefined) return ''
+  const base = work.status === 'running' ? '工作中' : '空闲'
+  return typeof work.queued === 'number' && work.queued > 0 ? `${base} · 排队 ${String(work.queued)}` : base
+}
+
+/** A fresh `.p-node` card: title row (dot + text), second row (description + 工作中/空闲 chip), and the right-hand chip. */
+export function createCardElement(id: string): HTMLDivElement {
+  const el = document.createElement('div')
+  el.className = 'p-node'
+  el.dataset.id = 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'
+  // Second line: the description, with the 工作中/空闲 chip at its right end — the title keeps its full width.
+  const work = document.createElement('span')
+  work.className = 'work'
+  const subRow = document.createElement('div')
+  subRow.className = 'sub-row'
+  subRow.append(sub, work)
+  el.append(nm, subRow, prio)
+  return el
+}
+
+/**
+ * The right-hand chip. Peer cards show the link badge (gh#20 W-A: linked green / stranger gray, then the
+ * verified tick/cross; an absent link field from an older host renders the neutral 'peer'). A remote MEMBER card
+ * (gh#38) is one session on that host, not the host: it reads 成员, colored and ticked by its host's link
+ * (it used to fall through to 'peer' and looked like a host card). Session cards show their first membership
+ * priority `P<n>`. Writes only on change.
+ */
+export function paintPrio(prioEl: HTMLElement, n: WorldNode, info: { link?: 'linked' | 'stranger'; verified?: boolean } | undefined): void {
+  if (n.remote === true) {
+    const cls = info?.link === 'linked' ? 'lnk-linked' : info?.link === 'stranger' ? 'lnk-stranger' : ''
+    if (prioEl.className !== `prio mono ${cls}`.trim()) prioEl.className = `prio mono ${cls}`.trim()
+    const mark = info === undefined ? '' : info.verified === true ? '✓' : '✗'
+    const badge = (n.id.startsWith('member-') ? '成员' : info?.link ?? 'peer') + mark
+    if (prioEl.textContent !== badge) prioEl.textContent = badge
+  } else {
+    if (prioEl.className !== 'prio mono') prioEl.className = 'prio mono'
+    const prioText = n.memberships[0] !== undefined ? `P${n.memberships[0]!.index}` : ''
+    if (prioEl.textContent !== prioText) prioEl.textContent = prioText
+  }
+}

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

@@ -1,26 +1,26 @@
-/**
- * The membership spokes' SVG layer (edges.ts stays pure geometry). Moved
- * out of planning-view (module-size cap) when pointercancel landed.
- * @module nexus-stage/planning-edges
- */
-import { starEdges } from './edges'
-import type { WorldModel } from './world'
-
-/**
- * Stateless, rebuilt wholesale. Derived from the MODEL (not the host's
- * teams): optimistic membership changes must repaint their edges
- * immediately, before the host confirms.
- */
-export function drawMemberEdges(svg: SVGSVGElement, model: WorldModel): 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)
-  }
-}
+/**
+ * The membership spokes' SVG layer (edges.ts stays pure geometry). Moved
+ * out of planning-view (module-size cap) when pointercancel landed.
+ * @module nexus-stage/planning-edges
+ */
+import { starEdges } from './edges'
+import type { WorldModel } from './world'
+
+/**
+ * Stateless, rebuilt wholesale. Derived from the MODEL (not the host's
+ * teams): optimistic membership changes must repaint their edges
+ * immediately, before the host confirms.
+ */
+export function drawMemberEdges(svg: SVGSVGElement, model: WorldModel): 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)
+  }
+}

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

@@ -1,45 +1,45 @@
-/**
- * The board's 适配 (fit) framing (review 2026-10-27).
- *
- * 适配 used to fit the local content into the whole board at any scale: a
- * small board zoomed to 167%, the top frame's title slid under the toolbar,
- * and the peer cards on the right were cut off. 适配 now frames what the
- * first-run fit frames:
- * - local content plus the peer cards;
- * - the frame titles that sit above their frames;
- * - never magnified past 100%;
- * - the area below the HUD (toolbar / status chip), not under it.
- * @module nexus-stage/planning-fit
- */
-import { FRAME_HEAD_TOP } from './edges'
-import { fitView, type LayoutViewport, type WorldBounds } from './viewport'
-import { nodeRect, type WorldNode } from './world'
-
-/** Local content bounds ∪ peer cards, lifted to include the frame titles
- *  (a title straddles its frame's top border, FRAME_HEAD_TOP above it). */
-export function boardBounds(content: WorldBounds | null, nodes: Iterable<WorldNode>): WorldBounds | null {
-  let b = content === null ? null : { ...content, minY: content.minY + FRAME_HEAD_TOP }
-  for (const n of nodes) {
-    if (n.remote !== true) continue
-    const r = nodeRect(n)
-    b = b === null
-      ? { minX: r.x, minY: r.y, maxX: r.x + r.w, maxY: r.y + r.h }
-      : { minX: Math.min(b.minX, r.x), minY: Math.min(b.minY, r.y), maxX: Math.max(b.maxX, r.x + r.w), maxY: Math.max(b.maxY, r.y + r.h) }
-  }
-  return b
-}
-
-/** Fit `bounds` at ≤100% into the board area below the HUD's bottom edge
- *  (`hudBottom` px from the board's top; 0 when the HUD is not laid out). */
-export function fitBelowHud(bounds: WorldBounds | null, viewW: number, viewH: number, hudBottom: number): LayoutViewport {
-  const inset = hudBottom > 0 && hudBottom < viewH / 2 ? hudBottom : 0
-  const vp = fitView(bounds, viewW, viewH - inset, 1)
-  return inset === 0 || bounds === null ? vp : { ...vp, y: vp.y - inset / vp.scale }
-}
-
-/** The HUD's bottom edge inside the board root: the lowest of the toolbar
- *  and status chip, plus a small gap; 0 before layout (jsdom, hidden). */
-export function hudBottomOf(...els: ReadonlyArray<HTMLElement>): number {
-  const bottom = Math.max(0, ...els.map(e => e.offsetHeight > 0 ? e.offsetTop + e.offsetHeight : 0))
-  return bottom > 0 ? bottom + 8 : 0
-}
+/**
+ * The board's 适配 (fit) framing (review 2026-10-27).
+ *
+ * 适配 used to fit the local content into the whole board at any scale: a
+ * small board zoomed to 167%, the top frame's title slid under the toolbar,
+ * and the peer cards on the right were cut off. 适配 now frames what the
+ * first-run fit frames:
+ * - local content plus the peer cards;
+ * - the frame titles that sit above their frames;
+ * - never magnified past 100%;
+ * - the area below the HUD (toolbar / status chip), not under it.
+ * @module nexus-stage/planning-fit
+ */
+import { FRAME_HEAD_TOP } from './edges'
+import { fitView, type LayoutViewport, type WorldBounds } from './viewport'
+import { nodeRect, type WorldNode } from './world'
+
+/** Local content bounds ∪ peer cards, lifted to include the frame titles
+ *  (a title straddles its frame's top border, FRAME_HEAD_TOP above it). */
+export function boardBounds(content: WorldBounds | null, nodes: Iterable<WorldNode>): WorldBounds | null {
+  let b = content === null ? null : { ...content, minY: content.minY + FRAME_HEAD_TOP }
+  for (const n of nodes) {
+    if (n.remote !== true) continue
+    const r = nodeRect(n)
+    b = b === null
+      ? { minX: r.x, minY: r.y, maxX: r.x + r.w, maxY: r.y + r.h }
+      : { minX: Math.min(b.minX, r.x), minY: Math.min(b.minY, r.y), maxX: Math.max(b.maxX, r.x + r.w), maxY: Math.max(b.maxY, r.y + r.h) }
+  }
+  return b
+}
+
+/** Fit `bounds` at ≤100% into the board area below the HUD's bottom edge
+ *  (`hudBottom` px from the board's top; 0 when the HUD is not laid out). */
+export function fitBelowHud(bounds: WorldBounds | null, viewW: number, viewH: number, hudBottom: number): LayoutViewport {
+  const inset = hudBottom > 0 && hudBottom < viewH / 2 ? hudBottom : 0
+  const vp = fitView(bounds, viewW, viewH - inset, 1)
+  return inset === 0 || bounds === null ? vp : { ...vp, y: vp.y - inset / vp.scale }
+}
+
+/** The HUD's bottom edge inside the board root: the lowest of the toolbar
+ *  and status chip, plus a small gap; 0 before layout (jsdom, hidden). */
+export function hudBottomOf(...els: ReadonlyArray<HTMLElement>): number {
+  const bottom = Math.max(0, ...els.map(e => e.offsetHeight > 0 ? e.offsetTop + e.offsetHeight : 0))
+  return bottom > 0 ? bottom + 8 : 0
+}

package/nexus-stage/src/planning-frame-hue.ts

@@ -1,13 +1,13 @@
-/** Stable team hue shared by canvas and roster frames. */
-import { FRAME_HUES } from './tokens'
-
-export 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")
-  const r = (rgb >> 16) & 0xff
-  const g = (rgb >> 8) & 0xff
-  const b = rgb & 0xff
-  return { line, bg: `rgba(${r},${g},${b},0.05)` }
-}
+/** Stable team hue shared by canvas and roster frames. */
+import { FRAME_HUES } from './tokens'
+
+export 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")
+  const r = (rgb >> 16) & 0xff
+  const g = (rgb >> 8) & 0xff
+  const b = rgb & 0xff
+  return { line, bg: `rgba(${r},${g},${b},0.05)` }
+}

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

@@ -1,39 +1,39 @@
-/**
- * The board legend (review 2026-10-27, real-host check): a fixed panel at
- * the bottom-left sat over the lowest frames of a real 66-card board. It is
- * now a native <details> fold — closed by default, a small 图例 chip that
- * covers nothing; open, it shows the edge key. The open state is a
- * per-viewer convenience in browser storage (absent or throwing → closed).
- * @module nexus-stage/planning-legend
- */
-const KEY = 'dsh-a2a.board.legend'
-
-/** Build the legend fold. */
-export function createLegend(): HTMLDetailsElement {
-  const legend = document.createElement('details')
-  legend.className = 'p-legend'
-  const summary = document.createElement('summary')
-  summary.textContent = '图例'
-  summary.title = '边的含义（点击展开 / 收起）'
-  const rows = document.createElement('div')
-  rows.className = 'p-legend-rows'
-  const row = (dashed: boolean, text: string, color?: string): void => {
-    const line = document.createElement('span')
-    const bar = document.createElement('i')
-    if (dashed) bar.className = 'dashed'
-    if (color !== undefined) bar.style.borderTopColor = color
-    line.append(bar, document.createTextNode(text))
-    rows.appendChild(line)
-  }
-  row(false, '成员边（星形，框→成员）')
-  row(true, '跨队多属（虚线）')
-  row(true, 'roster 网络队框（双线边框）')
-  row(false, '活动边（inFlight 路由，瞬时）', 'var(--accent)')
-  row(true, '联邦线（→peer）', 'var(--federal)')
-  legend.append(summary, rows)
-  try { legend.open = window.localStorage.getItem(KEY) === 'open' } catch { /* closed */ }
-  legend.addEventListener('toggle', () => {
-    try { window.localStorage.setItem(KEY, legend.open ? 'open' : 'closed') } catch { /* convenience only */ }
-  })
-  return legend
-}
+/**
+ * The board legend (review 2026-10-27, real-host check): a fixed panel at
+ * the bottom-left sat over the lowest frames of a real 66-card board. It is
+ * now a native <details> fold — closed by default, a small 图例 chip that
+ * covers nothing; open, it shows the edge key. The open state is a
+ * per-viewer convenience in browser storage (absent or throwing → closed).
+ * @module nexus-stage/planning-legend
+ */
+const KEY = 'dsh-a2a.board.legend'
+
+/** Build the legend fold. */
+export function createLegend(): HTMLDetailsElement {
+  const legend = document.createElement('details')
+  legend.className = 'p-legend'
+  const summary = document.createElement('summary')
+  summary.textContent = '图例'
+  summary.title = '边的含义（点击展开 / 收起）'
+  const rows = document.createElement('div')
+  rows.className = 'p-legend-rows'
+  const row = (dashed: boolean, text: string, color?: string): void => {
+    const line = document.createElement('span')
+    const bar = document.createElement('i')
+    if (dashed) bar.className = 'dashed'
+    if (color !== undefined) bar.style.borderTopColor = color
+    line.append(bar, document.createTextNode(text))
+    rows.appendChild(line)
+  }
+  row(false, '成员边（星形，框→成员）')
+  row(true, '跨队多属（虚线）')
+  row(true, 'roster 网络队框（双线边框）')
+  row(false, '活动边（inFlight 路由，瞬时）', 'var(--accent)')
+  row(true, '联邦线（→peer）', 'var(--federal)')
+  legend.append(summary, rows)
+  try { legend.open = window.localStorage.getItem(KEY) === 'open' } catch { /* closed */ }
+  legend.addEventListener('toggle', () => {
+    try { window.localStorage.setItem(KEY, legend.open ? 'open' : 'closed') } catch { /* convenience only */ }
+  })
+  return legend
+}