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

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

@@ -1,159 +1,159 @@
-/**
- * Board overlap rules (owner, 2026-10-27: 团队方框需要避免遮盖和覆盖 — frames
- * must not overlap each other, and a card must not sit on a frame it is not
- * a member of).
- *
- * settleBoard() resolves both, deterministically:
- * - Frame vs frame: one frame of an overlapping pair steps aside along the
- *   shortest of the four directions, carrying its members like a drag. The
- *   frame the user just touched stays where it was put; a remote org frame
- *   never moves on its own (gh#44: its rect is the user's), so a local frame
- *   yields to it; two remote frames are left alone.
- * - Card vs frame: a card lying on a frame it does not belong to goes home
- *   first — the first free grid seat inside its own frame (memberships in
- *   state order) — and only a card with no frame (or no free seat) goes
- *   outside: right of that frame, else below it, else down a column right of
- *   every frame. No landing spot covers another card or a foreign frame, and
- *   frames are never moved or resized by this step. Members are never moved
- *   off their own frame; a member merely outside its frame (PR#85: a frame
- *   moves only itself) is left where it is.
- * Callers run it after a frame drag or resize, after 整理成员 / 一键重排,
- * and once when the board first has content — never on every poll (a poll
- * does not reposition what the user arranged).
- *
- * tidyMembers() is the gh#48 整理成员 grid, moved here from planning-view.
- * @module nexus-stage/planning-overlap
- */
-import { NODE_W, NODE_H, nodeRect, type FrameGeom, type WorldModel } from './world'
-
-/** Clearance kept between a moved frame or card and what it stepped off. */
-export const OVERLAP_GAP = 24
-/** Bound on resolution passes (a dense board settles in a few). */
-const MAX_PASSES = 200
-
-type Rect = { readonly x: number; readonly y: number; readonly w: number; readonly h: number }
-const hit = (a: Rect, b: Rect): boolean => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h
-
-/** The shortest translation that takes `m` clear of `f` (plus the gap). */
-function stepAside(m: Rect, f: Rect): { dx: number; dy: number } {
-  const right = f.x + f.w + OVERLAP_GAP - m.x
-  const left = f.x - OVERLAP_GAP - (m.x + m.w)
-  const down = f.y + f.h + OVERLAP_GAP - m.y
-  const up = f.y - OVERLAP_GAP - (m.y + m.h)
-  const dx = Math.abs(right) <= Math.abs(left) ? right : left
-  const dy = Math.abs(down) <= Math.abs(up) ? down : up
-  return Math.abs(dx) <= Math.abs(dy) ? { dx, dy: 0 } : { dx: 0, dy }
-}
-
-function moveFrame(model: WorldModel, name: string, dx: number, dy: number): void {
-  const snap = model.beginFrameDrag(name)
-  if (snap !== undefined) model.applyFrameDrag(snap, dx, dy)
-}
-
-/** Separate overlapping frames; true when anything moved. */
-export function separateFrames(model: WorldModel, remote: ReadonlySet<string>, touched?: string): boolean {
-  let changed = false
-  for (let pass = 0; pass < MAX_PASSES; pass++) {
-    const frames = model.allFrames()
-    let pair: [string, FrameGeom, string, FrameGeom] | undefined
-    for (let i = 0; i < frames.length && pair === undefined; i++) {
-      for (let j = i + 1; j < frames.length; j++) {
-        const [a, ra] = frames[i]!
-        const [b, rb] = frames[j]!
-        if (remote.has(a) && remote.has(b)) continue
-        if (hit(ra, rb)) { pair = [a, ra, b, rb]; break }
-      }
-    }
-    if (pair === undefined) return changed
-    const [a, ra, b, rb] = pair
-    // Who yields: the lower stay score moves — remote 2 (never moves on its
-    // own), the frame just placed 1, any other 0; a tie moves the later one
-    // in board order. (A plain "a stays" check moved a remote b whenever a
-    // was the frame just placed — order-dependent: PR #83 review.)
-    const stay = (n: string): number => remote.has(n) ? 2 : n === touched ? 1 : 0
-    const [mover, mr, fixed] = stay(a) < stay(b) ? [a, ra, rb] : [b, rb, ra]
-    const { dx, dy } = stepAside(mr, fixed)
-    moveFrame(model, mover, dx, dy)
-    changed = true
-  }
-  return changed
-}
-
-/** Grid of the 整理成员 layout, shared by eviction seats. */
-const PAD = 28
-const GAP_X = 16
-const GAP_Y = 14
-
-/** Card-centred seats inside a frame, row by row (the 整理成员 grid). */
-function seatsIn(f: Rect): Array<{ x: number; y: number }> {
-  const out: Array<{ x: number; y: number }> = []
-  for (let y = f.y + PAD; y + NODE_H <= f.y + f.h - PAD; y += NODE_H + GAP_Y) {
-    for (let x = f.x + PAD; x + NODE_W <= f.x + f.w - PAD; x += NODE_W + GAP_X) out.push({ x: x + NODE_W / 2, y: y + NODE_H / 2 })
-  }
-  return out
-}
-
-/** Move cards off frames they do not belong to; true when anything moved. */
-export function evictStrangers(model: WorldModel): boolean {
-  let changed = false
-  const frames = model.allFrames()
-  const rectOf = new Map(frames)
-  for (const n of model.allNodes()) {
-    const own = new Set(n.memberships.map(m => m.team))
-    const host = frames.find(([name, f]) => !own.has(name) && hit(nodeRect(n), f))
-    if (host === undefined) continue
-    const f = host[1]
-    // Free = no foreign frame and no other card under it (cards read live: earlier evictions count).
-    const free = (p: { x: number; y: number }): boolean => {
-      const r = nodeRect(p)
-      return frames.every(([name, g]) => own.has(name) || !hit(r, g)) &&
-        model.allNodes().every(o => o.id === n.id || !hit(r, nodeRect(o)))
-    }
-    const home = n.memberships.map(m => rectOf.get(m.team)).filter((g): g is FrameGeom => g !== undefined)
-    const seat = home.flatMap(seatsIn).find(free)
-    const right = { x: f.x + f.w + OVERLAP_GAP + NODE_W / 2, y: n.y }
-    const below = { x: n.x, y: f.y + f.h + OVERLAP_GAP + NODE_H / 2 }
-    // Last resort: a column right of every frame, top-down from this frame. A card blocks
-    // at most two seats of this pitch, so 2·cards+1 seats always hold a free one.
-    const farX = Math.max(...frames.map(([, g]) => g.x + g.w)) + OVERLAP_GAP + NODE_W / 2
-    const column = Array.from({ length: 2 * model.allNodes().length + 1 }, (_, i) => ({ x: farX, y: f.y + NODE_H / 2 + i * (NODE_H + GAP_Y) }))
-    const to = seat ?? [right, below, ...column].find(free) ?? column[column.length - 1]!
-    model.dragNodes([n.id], to.x - n.x, to.y - n.y)
-    changed = true
-  }
-  return changed
-}
-
-/** Both rules, frames first (moving a frame can uncover or cover cards). */
-export function settleBoard(model: WorldModel, remote: ReadonlySet<string>, touched?: string): boolean {
-  const framesMoved = separateFrames(model, remote, touched)
-  const cardsMoved = evictStrangers(model)
-  return framesMoved || cardsMoved
-}
-
-/**
- * gh#48 整理成员: inside every frame, the members that belong to exactly that
- * one team re-seat into a padded grid; the frame grows downward (bounded) to
- * fit them. Members of 2+ teams keep their positions.
- */
-export function tidyMembers(model: WorldModel): void {
-  for (const [name, rect] of model.allFrames()) {
-    const sole = model.teamMemberIds(name)
-      .map(id => model.getNode(id))
-      .filter((n): n is NonNullable<typeof n> => n !== undefined)
-      .filter(n => n.memberships.length === 1)
-    if (sole.length === 0) continue // empty frame / only shared members: untouched
-    const perRow = Math.max(1, Math.floor((rect.w - 2 * PAD + GAP_X) / (NODE_W + GAP_X)))
-    const rows = Math.ceil(sole.length / perRow)
-    const needed = PAD * 2 + rows * NODE_H + (rows - 1) * GAP_Y
-    if (needed > rect.h) model.setFrame(name, { ...rect, h: Math.min(needed, rect.h + 400) })
-    const startX = rect.x + PAD + NODE_W / 2
-    let y = rect.y + PAD + NODE_H / 2
-    sole.forEach((n, i) => {
-      const col = i % perRow
-      if (i > 0 && col === 0) y += NODE_H + GAP_Y
-      const x = startX + col * (NODE_W + GAP_X)
-      model.dragNodes([n.id], x - n.x, y - n.y)
-    })
-  }
-}
+/**
+ * Board overlap rules (owner, 2026-10-27: 团队方框需要避免遮盖和覆盖 — frames
+ * must not overlap each other, and a card must not sit on a frame it is not
+ * a member of).
+ *
+ * settleBoard() resolves both, deterministically:
+ * - Frame vs frame: one frame of an overlapping pair steps aside along the
+ *   shortest of the four directions, carrying its members like a drag. The
+ *   frame the user just touched stays where it was put; a remote org frame
+ *   never moves on its own (gh#44: its rect is the user's), so a local frame
+ *   yields to it; two remote frames are left alone.
+ * - Card vs frame: a card lying on a frame it does not belong to goes home
+ *   first — the first free grid seat inside its own frame (memberships in
+ *   state order) — and only a card with no frame (or no free seat) goes
+ *   outside: right of that frame, else below it, else down a column right of
+ *   every frame. No landing spot covers another card or a foreign frame, and
+ *   frames are never moved or resized by this step. Members are never moved
+ *   off their own frame; a member merely outside its frame (PR#85: a frame
+ *   moves only itself) is left where it is.
+ * Callers run it after a frame drag or resize, after 整理成员 / 一键重排,
+ * and once when the board first has content — never on every poll (a poll
+ * does not reposition what the user arranged).
+ *
+ * tidyMembers() is the gh#48 整理成员 grid, moved here from planning-view.
+ * @module nexus-stage/planning-overlap
+ */
+import { NODE_W, NODE_H, nodeRect, type FrameGeom, type WorldModel } from './world'
+
+/** Clearance kept between a moved frame or card and what it stepped off. */
+export const OVERLAP_GAP = 24
+/** Bound on resolution passes (a dense board settles in a few). */
+const MAX_PASSES = 200
+
+type Rect = { readonly x: number; readonly y: number; readonly w: number; readonly h: number }
+const hit = (a: Rect, b: Rect): boolean => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h
+
+/** The shortest translation that takes `m` clear of `f` (plus the gap). */
+function stepAside(m: Rect, f: Rect): { dx: number; dy: number } {
+  const right = f.x + f.w + OVERLAP_GAP - m.x
+  const left = f.x - OVERLAP_GAP - (m.x + m.w)
+  const down = f.y + f.h + OVERLAP_GAP - m.y
+  const up = f.y - OVERLAP_GAP - (m.y + m.h)
+  const dx = Math.abs(right) <= Math.abs(left) ? right : left
+  const dy = Math.abs(down) <= Math.abs(up) ? down : up
+  return Math.abs(dx) <= Math.abs(dy) ? { dx, dy: 0 } : { dx: 0, dy }
+}
+
+function moveFrame(model: WorldModel, name: string, dx: number, dy: number): void {
+  const snap = model.beginFrameDrag(name)
+  if (snap !== undefined) model.applyFrameDrag(snap, dx, dy)
+}
+
+/** Separate overlapping frames; true when anything moved. */
+export function separateFrames(model: WorldModel, remote: ReadonlySet<string>, touched?: string): boolean {
+  let changed = false
+  for (let pass = 0; pass < MAX_PASSES; pass++) {
+    const frames = model.allFrames()
+    let pair: [string, FrameGeom, string, FrameGeom] | undefined
+    for (let i = 0; i < frames.length && pair === undefined; i++) {
+      for (let j = i + 1; j < frames.length; j++) {
+        const [a, ra] = frames[i]!
+        const [b, rb] = frames[j]!
+        if (remote.has(a) && remote.has(b)) continue
+        if (hit(ra, rb)) { pair = [a, ra, b, rb]; break }
+      }
+    }
+    if (pair === undefined) return changed
+    const [a, ra, b, rb] = pair
+    // Who yields: the lower stay score moves — remote 2 (never moves on its
+    // own), the frame just placed 1, any other 0; a tie moves the later one
+    // in board order. (A plain "a stays" check moved a remote b whenever a
+    // was the frame just placed — order-dependent: PR #83 review.)
+    const stay = (n: string): number => remote.has(n) ? 2 : n === touched ? 1 : 0
+    const [mover, mr, fixed] = stay(a) < stay(b) ? [a, ra, rb] : [b, rb, ra]
+    const { dx, dy } = stepAside(mr, fixed)
+    moveFrame(model, mover, dx, dy)
+    changed = true
+  }
+  return changed
+}
+
+/** Grid of the 整理成员 layout, shared by eviction seats. */
+const PAD = 28
+const GAP_X = 16
+const GAP_Y = 14
+
+/** Card-centred seats inside a frame, row by row (the 整理成员 grid). */
+function seatsIn(f: Rect): Array<{ x: number; y: number }> {
+  const out: Array<{ x: number; y: number }> = []
+  for (let y = f.y + PAD; y + NODE_H <= f.y + f.h - PAD; y += NODE_H + GAP_Y) {
+    for (let x = f.x + PAD; x + NODE_W <= f.x + f.w - PAD; x += NODE_W + GAP_X) out.push({ x: x + NODE_W / 2, y: y + NODE_H / 2 })
+  }
+  return out
+}
+
+/** Move cards off frames they do not belong to; true when anything moved. */
+export function evictStrangers(model: WorldModel): boolean {
+  let changed = false
+  const frames = model.allFrames()
+  const rectOf = new Map(frames)
+  for (const n of model.allNodes()) {
+    const own = new Set(n.memberships.map(m => m.team))
+    const host = frames.find(([name, f]) => !own.has(name) && hit(nodeRect(n), f))
+    if (host === undefined) continue
+    const f = host[1]
+    // Free = no foreign frame and no other card under it (cards read live: earlier evictions count).
+    const free = (p: { x: number; y: number }): boolean => {
+      const r = nodeRect(p)
+      return frames.every(([name, g]) => own.has(name) || !hit(r, g)) &&
+        model.allNodes().every(o => o.id === n.id || !hit(r, nodeRect(o)))
+    }
+    const home = n.memberships.map(m => rectOf.get(m.team)).filter((g): g is FrameGeom => g !== undefined)
+    const seat = home.flatMap(seatsIn).find(free)
+    const right = { x: f.x + f.w + OVERLAP_GAP + NODE_W / 2, y: n.y }
+    const below = { x: n.x, y: f.y + f.h + OVERLAP_GAP + NODE_H / 2 }
+    // Last resort: a column right of every frame, top-down from this frame. A card blocks
+    // at most two seats of this pitch, so 2·cards+1 seats always hold a free one.
+    const farX = Math.max(...frames.map(([, g]) => g.x + g.w)) + OVERLAP_GAP + NODE_W / 2
+    const column = Array.from({ length: 2 * model.allNodes().length + 1 }, (_, i) => ({ x: farX, y: f.y + NODE_H / 2 + i * (NODE_H + GAP_Y) }))
+    const to = seat ?? [right, below, ...column].find(free) ?? column[column.length - 1]!
+    model.dragNodes([n.id], to.x - n.x, to.y - n.y)
+    changed = true
+  }
+  return changed
+}
+
+/** Both rules, frames first (moving a frame can uncover or cover cards). */
+export function settleBoard(model: WorldModel, remote: ReadonlySet<string>, touched?: string): boolean {
+  const framesMoved = separateFrames(model, remote, touched)
+  const cardsMoved = evictStrangers(model)
+  return framesMoved || cardsMoved
+}
+
+/**
+ * gh#48 整理成员: inside every frame, the members that belong to exactly that
+ * one team re-seat into a padded grid; the frame grows downward (bounded) to
+ * fit them. Members of 2+ teams keep their positions.
+ */
+export function tidyMembers(model: WorldModel): void {
+  for (const [name, rect] of model.allFrames()) {
+    const sole = model.teamMemberIds(name)
+      .map(id => model.getNode(id))
+      .filter((n): n is NonNullable<typeof n> => n !== undefined)
+      .filter(n => n.memberships.length === 1)
+    if (sole.length === 0) continue // empty frame / only shared members: untouched
+    const perRow = Math.max(1, Math.floor((rect.w - 2 * PAD + GAP_X) / (NODE_W + GAP_X)))
+    const rows = Math.ceil(sole.length / perRow)
+    const needed = PAD * 2 + rows * NODE_H + (rows - 1) * GAP_Y
+    if (needed > rect.h) model.setFrame(name, { ...rect, h: Math.min(needed, rect.h + 400) })
+    const startX = rect.x + PAD + NODE_W / 2
+    let y = rect.y + PAD + NODE_H / 2
+    sole.forEach((n, i) => {
+      const col = i % perRow
+      if (i > 0 && col === 0) y += NODE_H + GAP_Y
+      const x = startX + col * (NODE_W + GAP_X)
+      model.dragNodes([n.id], x - n.x, y - n.y)
+    })
+  }
+}

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

@@ -1,28 +1,28 @@
-/** Project the peer's last missed card read onto existing remote cards and frames. */
-import { peerHostOf, type RemoteTeamRow } from './federation'
-
-export const UNREACHABLE_HINT = '对端未应答（显示的是最后已知状态）'
-
-export function unreachableRefs(input: {
-  remoteTeams?: ReadonlyArray<RemoteTeamRow>
-  peerOrg?: ReadonlyArray<{ url: string; unreachable?: boolean }>
-}): { hosts: ReadonlySet<string>; members: ReadonlySet<string> } {
-  const hosts = new Set<string>()
-  for (const row of input.remoteTeams ?? []) if (row.unreachable === true && row.via) hosts.add(peerHostOf(row.via))
-  for (const row of input.peerOrg ?? []) if (row.unreachable === true) hosts.add(peerHostOf(row.url))
-  const members = new Set<string>()
-  for (const row of input.remoteTeams ?? []) if (row.via && hosts.has(peerHostOf(row.via))) members.add(`member-${row.team.replace(/[^a-z0-9-]/gi, '-')}`)
-  return { hosts, members }
-}
-
-/** A mirror keeps its last known contents visible but warns until its owner responds again. */
-export function showFrameReachability(frame: HTMLElement, lost: boolean): void {
-  frame.classList.toggle('is-unreachable', lost)
-  const existing = frame.querySelector('.p-frame-unreachable')
-  if (lost && existing === null) {
-    const hint = document.createElement('span')
-    hint.className = 'p-frame-unreachable'
-    hint.textContent = UNREACHABLE_HINT
-    frame.appendChild(hint)
-  } else if (!lost) existing?.remove()
-}
+/** Project the peer's last missed card read onto existing remote cards and frames. */
+import { peerHostOf, type RemoteTeamRow } from './federation'
+
+export const UNREACHABLE_HINT = '对端未应答（显示的是最后已知状态）'
+
+export function unreachableRefs(input: {
+  remoteTeams?: ReadonlyArray<RemoteTeamRow>
+  peerOrg?: ReadonlyArray<{ url: string; unreachable?: boolean }>
+}): { hosts: ReadonlySet<string>; members: ReadonlySet<string> } {
+  const hosts = new Set<string>()
+  for (const row of input.remoteTeams ?? []) if (row.unreachable === true && row.via) hosts.add(peerHostOf(row.via))
+  for (const row of input.peerOrg ?? []) if (row.unreachable === true) hosts.add(peerHostOf(row.url))
+  const members = new Set<string>()
+  for (const row of input.remoteTeams ?? []) if (row.via && hosts.has(peerHostOf(row.via))) members.add(`member-${row.team.replace(/[^a-z0-9-]/gi, '-')}`)
+  return { hosts, members }
+}
+
+/** A mirror keeps its last known contents visible but warns until its owner responds again. */
+export function showFrameReachability(frame: HTMLElement, lost: boolean): void {
+  frame.classList.toggle('is-unreachable', lost)
+  const existing = frame.querySelector('.p-frame-unreachable')
+  if (lost && existing === null) {
+    const hint = document.createElement('span')
+    hint.className = 'p-frame-unreachable'
+    hint.textContent = UNREACHABLE_HINT
+    frame.appendChild(hint)
+  } else if (!lost) existing?.remove()
+}

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

@@ -1,121 +1,121 @@
-/**
- * 「一键重排」board relayout (supervisor order v2, upgrade of gh#48): a
- * deterministic whole-board re-seat — every LOCAL canvas team frame is
- * resized from its content (sole-member count drives cols/rows; width AND
- * height both derive from the grid), then the frames tile in a row flow
- * (constructively non-overlapping, no collision pass). Multi-team members
- * never enter the size derivation and never move (their dashed edges
- * express membership); remote org frames and frameless nodes are out of
- * scope. Pure geometry: same input, same output — pressing twice is
- * stable by construction.
- * @module nexus-stage/planning-relayout
- */
-import { NODE_W, NODE_H, type FrameGeom, type WorldModel } from './world'
-
-/** Inner padding between frame edge and the card grid (gh#48 family). */
-export const RELAYOUT_PAD = 28
-/** Card gaps inside a frame (same family as the tidy grid). */
-export const RELAYOUT_GAP_X = 16
-export const RELAYOUT_GAP_Y = 14
-/** Gap between neighbouring frames in the row-flow tiling. */
-export const FRAME_GAP = 48
-/** Column cap: perRow = min(4, ceil(sqrt(n))). */
-export const PER_ROW_CAP = 4
-/** Floor widths/heights: keeps the floating title band legible. */
-export const FRAME_MIN_W = 180
-export const FRAME_MIN_H = 90
-/** Default world-space wrap width of one tiling row. */
-export const RELAYOUT_WRAP = 1600
-
-/** One local frame to re-seat: its current rect and its SOLE member ids. */
-export interface RelayoutFrameInput {
-  readonly name: string
-  readonly rect: FrameGeom
-  readonly soleIds: readonly string[]
-}
-
-/** The deterministic outcome: new frame rects and absolute card centers. */
-export interface RelayoutOutput {
-  readonly frames: ReadonlyArray<{ name: string; rect: FrameGeom }>
-  readonly seats: ReadonlyArray<{ id: string; x: number; y: number }>
-}
-
-/**
- * Derive the whole-board layout. Frame order in = tiling order out (the
- * caller passes a stable order, e.g. the model's insertion order, which
- * keeps the result deterministic across presses).
- */
-export function planBoardRelayout(input: {
-  frames: ReadonlyArray<RelayoutFrameInput>
-  wrapWidth?: number
-}): RelayoutOutput {
-  const wrap = input.wrapWidth ?? RELAYOUT_WRAP
-  // Pass 1 — content-derived size per frame (multi-team members excluded
-  // upstream: soleIds carries exactly the re-seatable cards).
-  const sized = input.frames.map(f => {
-    const n = Math.max(f.soleIds.length, 1)
-    const perRow = Math.min(PER_ROW_CAP, Math.max(1, Math.ceil(Math.sqrt(n))))
-    const rows = Math.ceil(n / perRow)
-    const w = Math.max(FRAME_MIN_W, RELAYOUT_PAD * 2 + perRow * NODE_W + (perRow - 1) * RELAYOUT_GAP_X)
-    const h = Math.max(FRAME_MIN_H, RELAYOUT_PAD * 2 + rows * NODE_H + (rows - 1) * RELAYOUT_GAP_Y)
-    return { name: f.name, w, h, rows, perRow, soleIds: f.soleIds }
-  })
-  // Pass 2 — row-flow tiling: left→right until the wrap width is full,
-  // then advance one row by the tallest frame of the band. Constructive
-  // disjointness: boxes on one band share the y band and never overlap in
-  // x; bands stack with FRAME_GAP.
-  const frames: Array<{ name: string; rect: FrameGeom }> = []
-  const seats: Array<{ id: string; x: number; y: number }> = []
-  let x = 0
-  let y = 0
-  let bandH = 0
-  for (const f of sized) {
-    if (x > 0 && x + f.w > wrap) {
-      x = 0
-      y += bandH + FRAME_GAP
-      bandH = 0
-    }
-    const rect: FrameGeom = { x, y, w: f.w, h: f.h }
-    frames.push({ name: f.name, rect })
-    // Pass 3 — seat the sole cards on the new rect's grid (the gh#48 rule,
-    // driven by the NEW frame geometry).
-    const startX = rect.x + RELAYOUT_PAD + NODE_W / 2
-    let cy = rect.y + RELAYOUT_PAD + NODE_H / 2
-    f.soleIds.forEach((id, i) => {
-      const col = i % f.perRow
-      if (i > 0 && col === 0) cy += NODE_H + RELAYOUT_GAP_Y
-      seats.push({ id, x: startX + col * (NODE_W + RELAYOUT_GAP_X), y: cy })
-    })
-    x += f.w + FRAME_GAP
-    bandH = Math.max(bandH, f.h)
-  }
-  return { frames, seats }
-}
-
-/**
- * The model adapter (supervisor order v2): collect the LOCAL frames and
- * their sole members (remote org frames and multi-team members are out of
- * scope by spec), run the pure planner, apply the rects and seat moves
- * through the model's own mutation seam. Returns false when nothing is in
- * scope (the caller decides whether to dirty the layout).
- */
-export function applyBoardRelayout(model: WorldModel, remoteNames: ReadonlySet<string>): boolean {
-  const frames: Array<{ name: string; rect: FrameGeom; soleIds: string[] }> = []
-  for (const [name, rect] of model.allFrames()) {
-    if (remoteNames.has(name)) continue // remote org frames: untouched
-    const soleIds = model.teamMemberIds(name)
-      .map(id => model.getNode(id))
-      .filter((n): n is NonNullable<typeof n> => n !== undefined)
-      .filter(n => n.memberships.length === 1)
-      .map(n => n.id)
-    frames.push({ name, rect, soleIds })
-  }
-  if (frames.length === 0) return false
-  const out = planBoardRelayout({ frames })
-  for (const f of out.frames) model.setFrame(f.name, f.rect)
-  for (const seat of out.seats) {
-    const n = model.getNode(seat.id)
-    if (n !== undefined) model.dragNodes([seat.id], seat.x - n.x, seat.y - n.y)
-  }
-  return true
-}
+/**
+ * 「一键重排」board relayout (supervisor order v2, upgrade of gh#48): a
+ * deterministic whole-board re-seat — every LOCAL canvas team frame is
+ * resized from its content (sole-member count drives cols/rows; width AND
+ * height both derive from the grid), then the frames tile in a row flow
+ * (constructively non-overlapping, no collision pass). Multi-team members
+ * never enter the size derivation and never move (their dashed edges
+ * express membership); remote org frames and frameless nodes are out of
+ * scope. Pure geometry: same input, same output — pressing twice is
+ * stable by construction.
+ * @module nexus-stage/planning-relayout
+ */
+import { NODE_W, NODE_H, type FrameGeom, type WorldModel } from './world'
+
+/** Inner padding between frame edge and the card grid (gh#48 family). */
+export const RELAYOUT_PAD = 28
+/** Card gaps inside a frame (same family as the tidy grid). */
+export const RELAYOUT_GAP_X = 16
+export const RELAYOUT_GAP_Y = 14
+/** Gap between neighbouring frames in the row-flow tiling. */
+export const FRAME_GAP = 48
+/** Column cap: perRow = min(4, ceil(sqrt(n))). */
+export const PER_ROW_CAP = 4
+/** Floor widths/heights: keeps the floating title band legible. */
+export const FRAME_MIN_W = 180
+export const FRAME_MIN_H = 90
+/** Default world-space wrap width of one tiling row. */
+export const RELAYOUT_WRAP = 1600
+
+/** One local frame to re-seat: its current rect and its SOLE member ids. */
+export interface RelayoutFrameInput {
+  readonly name: string
+  readonly rect: FrameGeom
+  readonly soleIds: readonly string[]
+}
+
+/** The deterministic outcome: new frame rects and absolute card centers. */
+export interface RelayoutOutput {
+  readonly frames: ReadonlyArray<{ name: string; rect: FrameGeom }>
+  readonly seats: ReadonlyArray<{ id: string; x: number; y: number }>
+}
+
+/**
+ * Derive the whole-board layout. Frame order in = tiling order out (the
+ * caller passes a stable order, e.g. the model's insertion order, which
+ * keeps the result deterministic across presses).
+ */
+export function planBoardRelayout(input: {
+  frames: ReadonlyArray<RelayoutFrameInput>
+  wrapWidth?: number
+}): RelayoutOutput {
+  const wrap = input.wrapWidth ?? RELAYOUT_WRAP
+  // Pass 1 — content-derived size per frame (multi-team members excluded
+  // upstream: soleIds carries exactly the re-seatable cards).
+  const sized = input.frames.map(f => {
+    const n = Math.max(f.soleIds.length, 1)
+    const perRow = Math.min(PER_ROW_CAP, Math.max(1, Math.ceil(Math.sqrt(n))))
+    const rows = Math.ceil(n / perRow)
+    const w = Math.max(FRAME_MIN_W, RELAYOUT_PAD * 2 + perRow * NODE_W + (perRow - 1) * RELAYOUT_GAP_X)
+    const h = Math.max(FRAME_MIN_H, RELAYOUT_PAD * 2 + rows * NODE_H + (rows - 1) * RELAYOUT_GAP_Y)
+    return { name: f.name, w, h, rows, perRow, soleIds: f.soleIds }
+  })
+  // Pass 2 — row-flow tiling: left→right until the wrap width is full,
+  // then advance one row by the tallest frame of the band. Constructive
+  // disjointness: boxes on one band share the y band and never overlap in
+  // x; bands stack with FRAME_GAP.
+  const frames: Array<{ name: string; rect: FrameGeom }> = []
+  const seats: Array<{ id: string; x: number; y: number }> = []
+  let x = 0
+  let y = 0
+  let bandH = 0
+  for (const f of sized) {
+    if (x > 0 && x + f.w > wrap) {
+      x = 0
+      y += bandH + FRAME_GAP
+      bandH = 0
+    }
+    const rect: FrameGeom = { x, y, w: f.w, h: f.h }
+    frames.push({ name: f.name, rect })
+    // Pass 3 — seat the sole cards on the new rect's grid (the gh#48 rule,
+    // driven by the NEW frame geometry).
+    const startX = rect.x + RELAYOUT_PAD + NODE_W / 2
+    let cy = rect.y + RELAYOUT_PAD + NODE_H / 2
+    f.soleIds.forEach((id, i) => {
+      const col = i % f.perRow
+      if (i > 0 && col === 0) cy += NODE_H + RELAYOUT_GAP_Y
+      seats.push({ id, x: startX + col * (NODE_W + RELAYOUT_GAP_X), y: cy })
+    })
+    x += f.w + FRAME_GAP
+    bandH = Math.max(bandH, f.h)
+  }
+  return { frames, seats }
+}
+
+/**
+ * The model adapter (supervisor order v2): collect the LOCAL frames and
+ * their sole members (remote org frames and multi-team members are out of
+ * scope by spec), run the pure planner, apply the rects and seat moves
+ * through the model's own mutation seam. Returns false when nothing is in
+ * scope (the caller decides whether to dirty the layout).
+ */
+export function applyBoardRelayout(model: WorldModel, remoteNames: ReadonlySet<string>): boolean {
+  const frames: Array<{ name: string; rect: FrameGeom; soleIds: string[] }> = []
+  for (const [name, rect] of model.allFrames()) {
+    if (remoteNames.has(name)) continue // remote org frames: untouched
+    const soleIds = model.teamMemberIds(name)
+      .map(id => model.getNode(id))
+      .filter((n): n is NonNullable<typeof n> => n !== undefined)
+      .filter(n => n.memberships.length === 1)
+      .map(n => n.id)
+    frames.push({ name, rect, soleIds })
+  }
+  if (frames.length === 0) return false
+  const out = planBoardRelayout({ frames })
+  for (const f of out.frames) model.setFrame(f.name, f.rect)
+  for (const seat of out.seats) {
+    const n = model.getNode(seat.id)
+    if (n !== undefined) model.dragNodes([seat.id], seat.x - n.x, seat.y - n.y)
+  }
+  return true
+}