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

package/nexus-stage/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "dsh-a2a-nexus-stage",
+  "private": true,
+  "version": "0.2.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc --noEmit && vite build",
+    "dev": "vite",
+    "test": "vitest run"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vite": "^5.4.8",
+    "vitest": "^2.1.8",
+    "jsdom": "^24.1.0"
+  },
+  "allowScripts": {
+    "esbuild@0.21.5": true
+  }
+}

package/nexus-stage/scripts/mockhost.py

@@ -0,0 +1,253 @@
+"""Standalone mock host for the nexus stage - the standing smoke artifact.
+
+Serves the built stage (assets/nexusDist) plus canned /__dsh_a2a endpoints so
+both proof scenes are plain openable URLs, no browser automation required:
+
+  http://127.0.0.1:<port>/            healthy (canned live-shaped state)
+  http://127.0.0.1:<port>/?fault=500  state answers 500 -> on-page fault badge
+  http://127.0.0.1:<port>/?demo=1     state merges a demo federation dataset
+                                      (2 peers + 2 inFlight routes) so the PR D
+                                      activity/federal layers stay demonstrable
+                                      offline and on fleets with no live routes
+
+Usage: python scripts/mockhost.py [port]        (default 8780)
+State source: LIVE_STATE env, else http://127.0.0.1:3080/__dsh_a2a/state, with
+a graceful empty-fleet fallback so offline dev still boots.
+"""
+import functools
+import json
+import os
+import sys
+import time
+import urllib.request
+from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler
+from pathlib import Path
+
+PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8780
+DIST = Path(__file__).resolve().parents[2] / 'assets' / 'nexusDist'
+LIVE = os.environ.get('LIVE_STATE', 'http://127.0.0.1:3080/__dsh_a2a/state')
+
+
+def fetch_state() -> bytes:
+    try:
+        return urllib.request.urlopen(LIVE, timeout=5).read()
+    except Exception:  # noqa: BLE001 - offline dev must still boot
+        return json.dumps({'sessions': [], 'canvas': {'teams': []}, 'peers': []}).encode()
+
+
+state_bytes = fetch_state()
+# The layout store starts absent and remembers saves in memory only - the
+# mock exists to exercise the stage's save loop (lamp ladder), not to be a
+# second implementation of the host's clamp (the stage normalizes on GET).
+# Optional on-disk persistence: set LAYOUT_FILE=<path> so the layout
+# survives mock-host restarts (the in-memory default wipes on exit).
+# Corrupt files are treated as absent - presentation state only.
+LAYOUT_FILE = os.environ.get('LAYOUT_FILE', '')
+
+
+def layout_load():
+    if not LAYOUT_FILE or not os.path.exists(LAYOUT_FILE):
+        return None
+    try:
+        with open(LAYOUT_FILE, 'r', encoding='utf-8') as f:
+            return json.load(f)
+    except Exception:  # noqa: BLE001 - corrupt layout is presentation loss only
+        return None
+
+
+def layout_persist(doc):
+    if not LAYOUT_FILE:
+        return
+    try:
+        fd = os.open(LAYOUT_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, 'w', encoding='utf-8') as f:
+            f.write('' if doc is None else json.dumps(doc))
+    except OSError:
+        pass
+
+
+layout_store = {'doc': None}
+
+# ── canvas store (PR C): mutable teams, mirrored shapes from src/canvas-store.ts,
+# so team writes are visible on the NEXT POLL (state is regenerated per request
+# from this store - a startup snapshot would hide every write). ──
+CANVAS_NAME_MAX = 40
+CANVAS_TEAM_CAP = 64
+CANVAS_MEMBER_CAP = 32
+
+_BASE = json.loads(state_bytes)
+member_rows = {}  # id -> rich member row captured from the snapshot
+joined_ids = {s.get('id') for s in _BASE.get('sessions', []) if isinstance(s, dict)}
+teams = {}  # name -> [member ids], order = routing priority
+host_prefix = 'dsh'
+for _t in _BASE.get('canvas', {}).get('teams', []):
+    teams[_t['name']] = [m['id'] for m in _t.get('members', [])]
+    for _m in _t.get('members', []):
+        member_rows[_m['id']] = _m
+        _p = _m.get('team', '').split('/')[0]
+        if _p:
+            host_prefix = _p
+            break
+
+
+def valid_name(raw):
+    """Mirror of canvas-store.validName: trim, 1..40, no '/', not pure digits."""
+    if not isinstance(raw, str):
+        return None
+    name = raw.strip()
+    if name == '' or len(name) > CANVAS_NAME_MAX or '/' in name or name.isdigit():
+        return None
+    return name
+
+
+# ── demo federation dataset (PR D): merged into /__dsh_a2a/state only when the
+# request carries demo=1 (query or Referer), so the activity/federal layers are
+# demonstrable offline and on live fleets that have no in-flight routes. ──
+DEMO_PEERS = [
+    {'url': 'http://192.168.3.88:3080', 'score': 42},
+    {'url': 'http://10.0.0.7:13080', 'score': 17},
+]
+
+
+def build_state(demo: bool = False) -> bytes:
+    """The snapshot with canvas.teams regenerated from the mutable store."""
+    state = dict(_BASE)
+    team_rows = []
+    for name, ids in teams.items():
+        members = []
+        for mid in ids:
+            row = member_rows.get(mid)
+            if row is None:
+                row = {'id': mid, 'team': f'{host_prefix}/{mid[:8]}', 'joined': True, 'live': True}
+                member_rows[mid] = row
+            members.append(row)
+        team_rows.append({'name': name, 'team': f'{host_prefix}/canvas/{name}', 'members': members})
+    state['canvas'] = {'teams': team_rows}
+    if demo:
+        # fresh list copies - _BASE's own peers must stay untouched
+        state['peers'] = list(state.get('peers') or []) + [dict(p) for p in DEMO_PEERS]
+        names = [row['name'] for row in team_rows]
+        first = names[0] if names else 'dsh'
+        second = names[1] if len(names) > 1 else first
+        now_ms = int(time.time() * 1000)
+        state['inFlight'] = [
+            {'team': first, 'peer': '192.168.3.88:3080', 'startedAt': now_ms - 12000},
+            {'team': second, 'peer': '10.0.0.7:13080', 'startedAt': now_ms - 45000},
+        ]
+    return json.dumps(state).encode()
+
+
+class MockHost(SimpleHTTPRequestHandler):
+    def do_GET(self):  # noqa: N802 - stdlib signature
+        path, _, query = self.path.partition('?')
+        referer = self.headers.get('Referer') or ''
+        faulted = 'fault' in query or 'fault' in referer
+        demo = 'demo=1' in query or 'demo=1' in referer
+        if path == '/__dsh_a2a/state':
+            if faulted:
+                self._json(b'{"ok":false,"error":"injected fault"}', status=500)
+            else:
+                self._json(build_state(demo))  # regenerated: canvas writes stay visible
+        elif path == '/__dsh_a2a/canvas-layout':
+            doc = layout_load() if LAYOUT_FILE else layout_store['doc']
+            self._json(json.dumps({'ok': True, 'layout': doc}).encode())
+        else:
+            super().do_GET()
+
+    def do_POST(self):  # noqa: N802 - stdlib signature
+        path, _, query = self.path.partition('?')
+        referer = self.headers.get('Referer') or ''
+        faulted = 'fault' in query or 'fault' in referer
+        if path not in ('/__dsh_a2a/canvas-layout', '/__dsh_a2a/canvas'):
+            self._json(b'{"ok":false,"error":"unknown route"}', status=404)
+            return
+        try:
+            length = int(self.headers.get('Content-Length') or 0)
+            raw = self.rfile.read(length) or b'{}'
+            if b'\xef\xbf\xbd' in raw:  # U+FFFD guard, same as the host's text-guard
+                self._json(b'{"error": "text contains undecodable characters (U+FFFD) '
+                           b'\xe2\x80\x94 fix the sender encoding and retry", "code": -32005}', status=422)
+                return
+            body = json.loads(raw)
+        except Exception:  # noqa: BLE001 - malformed body mirrors the host 400
+            self._json(b'{"ok":false,"error":"malformed body"}', status=400)
+            return
+        if faulted:
+            self._json(b'{"ok":false,"error":"injected fault"}', status=500)
+            return
+        action = body.get('action')
+        if path == '/__dsh_a2a/canvas-layout':
+            self._canvas_layout(action, body)
+        else:
+            self._canvas(action, body)
+
+    def _canvas_layout(self, action, body):
+        if action == 'reset':
+            layout_store['doc'] = None
+            layout_persist(None)
+            self._json(b'{"ok":true,"layout":null}')
+        elif action == 'save':
+            layout_store['doc'] = body.get('layout')
+            layout_persist(layout_store['doc'])
+            self._json(json.dumps({'ok': True, 'layout': layout_store['doc']}).encode())
+        else:
+            self._json(b'{"ok":false,"error":"unknown action"}')
+
+    def _canvas(self, action, body):
+        if action == 'create':
+            name = valid_name(body.get('name'))
+            if name is None or (name not in teams and len(teams) >= CANVAS_TEAM_CAP):
+                self._json(b'{"ok":false,"error":"invalid name or team cap reached"}')
+            else:
+                teams.setdefault(name, [])
+                self._json(json.dumps({'ok': True, 'name': name, 'teams': list(teams)}).encode())
+        elif action == 'remove':
+            name = body.get('name')
+            teams.pop(name, None)
+            self._json(json.dumps({'ok': True, 'teams': list(teams)}).encode())
+        elif action == 'add-member':
+            name = valid_name(body.get('name'))
+            mid = body.get('id')
+            if name is None or not isinstance(mid, str) or mid not in joined_ids:
+                self._json(b'{"ok":false,"error":"name and a joined session id are required"}')
+                return
+            roster = teams.setdefault(name, [])
+            if mid in roster:
+                self._json(json.dumps({'ok': True, 'teams': list(teams), 'members': list(roster)}).encode())
+            elif len(roster) >= CANVAS_MEMBER_CAP:
+                self._json(json.dumps({'ok': False, 'teams': list(teams), 'members': list(roster)}).encode())
+            else:
+                roster.append(mid)
+                self._json(json.dumps({'ok': True, 'teams': list(teams), 'members': list(roster)}).encode())
+        elif action == 'remove-member':
+            name = body.get('name')
+            mid = body.get('id')
+            if not isinstance(name, str) or not name.strip() or not isinstance(mid, str):
+                self._json(b'{"ok":false,"error":"name and id are required"}')
+                return
+            roster = teams.get(name)
+            if roster is None:
+                self._json(json.dumps({'ok': False, 'teams': list(teams), 'members': []}).encode())
+            elif mid in roster:
+                roster.remove(mid)
+                self._json(json.dumps({'ok': True, 'teams': list(teams), 'members': list(roster)}).encode())
+            else:
+                self._json(json.dumps({'ok': False, 'teams': list(teams), 'members': list(roster)}).encode())
+        else:
+            self._json(b'{"ok":false,"error":"unknown action"}')
+
+    def _json(self, payload: bytes, status: int = 200):
+        self.send_response(status)
+        self.send_header('Content-Type', 'application/json')
+        self.send_header('Content-Length', str(len(payload)))
+        self.send_header('Cache-Control', 'no-store')
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def log_message(self, *args):  # keep the console readable
+        pass
+
+
+handler = functools.partial(MockHost, directory=str(DIST))
+print(f'mock host on http://127.0.0.1:{PORT}/  (dist: {DIST})', flush=True)
+ThreadingHTTPServer(('127.0.0.1', PORT), handler).serve_forever()

package/nexus-stage/src/canvas-ops.ts

@@ -0,0 +1,175 @@
+/**
+ * Canvas action algebra for PR C (design.md §3.3/§3.4): the five user-facing
+ * write actions as optimistic model mutations that each return a TEAM-SCOPED
+ * undo. Scoped undos are the feedback loop's core - a whole-state revert
+ * would clobber other queued actions' optimistic state; a per-team undo only
+ * ever touches the team whose write failed, so queued actions on other teams
+ * survive, and undo state (captured at apply time) stays consistent with the
+ * per-team serial settle order.
+ *
+ * Pure: no DOM, no three, no fetch. The wire (canvas-wire.ts) owns transport;
+ * the view owns calling applyAction before emitting and undo() on failure.
+ * @module nexus-stage/canvas-ops
+ */
+
+import { nodeRect, deriveInitialFrame, type WorldModel } from './world'
+
+/** One pre-computed host op (remove = remove-member, add = add-member). */
+export type RosterOp = { op: 'remove' | 'add'; id: string }
+
+/** The five user-facing write actions (one per design.md §3.3 row), plus the two network join/leave actions the panel-slim migration moved into the planning view. */
+export type CanvasAction =
+  | { type: 'create-team'; name: string; ids: readonly string[]; /** true when the model had no such team before this action (a serial failure then leaves a ghost EMPTY team on the host — the wire compensates with a remove). */ created?: boolean }
+  | { type: 'add-member'; team: string; ids: readonly string[] }
+  | { type: 'remove-member'; team: string; ids: readonly string[] }
+  | { type: 'remove-team'; name: string }
+  /** `ops` comes from reorderOps() at emit time; the wire stays model-free. */
+  | { type: 'reorder'; team: string; ops: ReadonlyArray<RosterOp> }
+  /** Network-level join/leave (the session joins the A2A mesh) — distinct from canvas-team membership. */
+  | { type: 'join-network'; id: string }
+  | { type: 'leave-network'; id: string }
+
+/** Reverts exactly what one applyAction did (team-scoped). */
+export type Undo = () => void
+
+/** The team whose writes this action touches (queue key for the wire). */
+export function actionTeam(a: CanvasAction): string {
+  // Network join/leave are session-scoped, not team-scoped: one shared
+  // queue key keeps them serial against each other.
+  if (a.type === 'join-network' || a.type === 'leave-network') return '$network'
+  return a.type === 'create-team' || a.type === 'remove-team' ? a.name : a.team
+}
+
+/**
+ * Apply one action's optimistic mutation and return its undo. The undo is
+ * expressed as the INVERSE DELTA against the roster at undo time, never as
+ * a wholesale restore of a captured prefix - a later queued action on the
+ * same team may have applied optimistically before this action's write
+ * fails, and rolling back must remove only this action's effect.
+ */
+export function applyAction(model: WorldModel, a: CanvasAction): Undo {
+  if (a.type === 'create-team') {
+    const rects = a.ids
+      .map(id => model.getNode(id))
+      .filter(n => n !== undefined)
+      .map(n => nodeRect(n))
+    // Ids not on the canvas yet (a create emitted from the node list for an
+    // unteamed session) resolve no rect: skip the optimistic frame so the
+    // next poll derives it from the member's real seat instead of pinning a
+    // 260x160 placeholder at the origin.
+    if (rects.length > 0) model.setFrame(a.name, deriveInitialFrame(rects))
+    model.setTeamMembers(a.name, a.ids)
+    return () => {
+      // Only the created ids (a later add to this new team must survive).
+      model.setTeamMembers(a.name, model.teamMemberIds(a.name).filter(id => !a.ids.includes(id)))
+      model.removeFrame(a.name)
+    }
+  }
+  if (a.type === 'add-member') {
+    const pre = model.teamMemberIds(a.team)
+    const fresh = a.ids.filter(id => !pre.includes(id))
+    model.setTeamMembers(a.team, [...pre, ...fresh])
+    return () => {
+      model.setTeamMembers(a.team, model.teamMemberIds(a.team).filter(id => !fresh.includes(id)))
+    }
+  }
+  if (a.type === 'remove-member') {
+    const pre = model.teamMemberIds(a.team)
+    model.setTeamMembers(a.team, pre.filter(id => !a.ids.includes(id)))
+    return () => {
+      // Re-append the removed ids that nothing else has re-added since.
+      const current = model.teamMemberIds(a.team)
+      model.setTeamMembers(a.team, [...current, ...a.ids.filter(id => !current.includes(id))])
+    }
+  }
+  if (a.type === 'remove-team') {
+    const preIds = model.teamMemberIds(a.name)
+    const frame = model.getFrame(a.name)
+    const preRect = frame !== undefined ? { ...frame } : undefined
+    model.setTeamMembers(a.name, [])
+    model.removeFrame(a.name)
+    return () => {
+      if (preRect !== undefined) model.setFrame(a.name, preRect)
+      model.setTeamMembers(a.name, preIds)
+    }
+  }
+  // Network join/leave: no optimistic canvas mutation — the next inventory
+  // poll absorbs the host's truth (the node appears/disappears on the
+  // reconcile after the host accepts), so the undo is a no-op.
+  if (a.type === 'join-network' || a.type === 'leave-network') {
+    return () => {}
+  }
+  // reorder: apply the pre-computed ops to the current roster (remove
+  // anywhere, append). The undo WALKS the current roster back to the
+  // captured pre-order (same append-host discipline), so members a later
+  // queued action added stay put.
+  const pre = model.teamMemberIds(a.team)
+  let roster = [...pre]
+  for (const op of a.ops) {
+    if (op.op === 'remove') roster = roster.filter(x => x !== op.id)
+    else roster.push(op.id)
+  }
+  model.setTeamMembers(a.team, roster)
+  return () => {
+    let back = model.teamMemberIds(a.team)
+    for (let i = 0; i < pre.length; i++) {
+      const id = pre[i]!
+      if (back[i] === id) continue
+      if (!back.includes(id)) continue
+      back = back.filter(x => x !== id)
+      back.push(id)
+    }
+    model.setTeamMembers(a.team, back)
+  }
+}
+
+/**
+ * The minimal remove+add walk that turns `current` into `desired` on a
+ * host whose add-member always APPENDS: walk desired positions in order;
+ * whenever the working copy disagrees, remove+re-add the desired member
+ * (host-side remove is positional, add appends, so the working copy mirrors
+ * the host roster exactly). Bounded at 2*|desired| writes and converges;
+ * an already-equal roster yields zero ops; desired ids absent from current
+ * are skipped (adding members is never reorder's business).
+ */
+export function reorderOps(
+  current: ReadonlyArray<string>,
+  desired: ReadonlyArray<string>,
+): Array<{ op: 'remove' | 'add'; id: string }> {
+  const working = [...current]
+  const ops: Array<{ op: 'remove' | 'add'; id: string }> = []
+  for (let i = 0; i < desired.length; i++) {
+    const id = desired[i]!
+    if (working[i] === id) continue
+    if (!working.includes(id)) continue // not a member: not reorder's business
+    ops.push({ op: 'remove', id })
+    ops.push({ op: 'add', id })
+    working.splice(working.indexOf(id), 1)
+    working.push(id)
+  }
+  return ops
+}
+
+/** That team's members ordered by card-center y (ties: current priority). */
+export function yOrderedMembers(model: WorldModel, team: string): string[] {
+  return model
+    .teamMemberIds(team)
+    .map(id => ({ id, y: model.getNode(id)?.y ?? 0 }))
+    .sort((a, b) => a.y - b.y)
+    .map(r => r.id)
+}
+
+/** Innermost (smallest-area) frame containing the world point, if any. */
+export function innermostFrameAt(
+  frames: ReadonlyMap<string, { x: number; y: number; w: number; h: number }>,
+  p: { x: number; y: number },
+): string | undefined {
+  let best: string | undefined
+  let bestArea = Number.POSITIVE_INFINITY
+  for (const [name, r] of frames) {
+    if (p.x < r.x || p.x > r.x + r.w || p.y < r.y || p.y > r.y + r.h) continue
+    const area = r.w * r.h
+    if (area < bestArea) { best = name; bestArea = area }
+  }
+  return best
+}

package/nexus-stage/src/canvas-wire.ts

@@ -0,0 +1,156 @@
+/**
+ * The canvas write face's transport layer (POST /__dsh_a2a/canvas): action
+ * sequencing, per-team serialization, and the notice classification that
+ * design.md §3.4 mandates (host error text surfaces VERBATIM - the sidebar
+ * reference's swallowed `.catch(() => {})` is the anti-pattern here).
+ *
+ * Classification per request:
+ * - `ok:true`                                    → success (silent)
+ * - `ok:false` WITH an `error` string            → error notice, verbatim
+ * - `ok:false` without `error` (absent target,   → idempotent no-op,
+ *   member cap hit)                                silent success
+ * - HTTP >= 400                                  → body error verbatim, else `HTTP <status>`
+ * - send() throws                                → `画布不可达：<message>`
+ * - 200 + ok:false WITHOUT an error string       → idempotent no-op
+ *   (absent target, member/team cap hit) — silent success
+ * - 200 + non-JSON body (proxy artifact)         → classified as success
+ *   (known limitation: nothing parseable to classify)
+ *
+ * Ops on the same team run through a serial queue (a later gesture waits
+ * instead of racing; cross-team ops run in parallel) - mirrors the
+ * sidebar's per-team busy keys, minus the rejection hostility. Pure
+ * control flow: the transport is injected.
+ * @module nexus-stage/canvas-wire
+ */
+
+/** One send outcome: HTTP status plus the parsed JSON body (whatever it is). */
+export interface CanvasWireResult {
+  status: number
+  body: { ok?: boolean; error?: string; teams?: readonly string[]; members?: readonly string[]; name?: string }
+}
+
+/** Transport injection: POST the body, resolve with parsed outcome, throw on network failure. */
+export type CanvasSend = (body: unknown) => Promise<CanvasWireResult>
+
+export interface CanvasWireDeps {
+  send: CanvasSend
+  onNotice(kind: 'error' | 'info', text: string): void
+}
+
+export interface CanvasWire {
+  /** create → add-member per id, serial, first failure stops. `created`:
+   *  the team did not exist model-side before this action — a first-add
+   *  failure would then leave a ghost EMPTY team on the host, compensated
+   *  with a best-effort remove. */
+  createTeam(name: string, ids: readonly string[], created?: boolean): Promise<boolean>
+  addMembers(team: string, ids: readonly string[]): Promise<boolean>
+  removeMembers(team: string, ids: readonly string[]): Promise<boolean>
+  /** Pre-computed remove/add roster ops (from canvas-ops.reorderOps). */
+  runRosterOps(team: string, ops: ReadonlyArray<{ op: 'remove' | 'add'; id: string }>): Promise<boolean>
+  removeTeam(name: string): Promise<boolean>
+  hasPending(): boolean
+}
+
+type RosterOp = { op: 'remove' | 'add'; id: string }
+
+function errorText(body: CanvasWireResult['body']): string | undefined {
+  return typeof body.error === 'string' ? body.error : undefined
+}
+
+export function createCanvasWire(deps: CanvasWireDeps): CanvasWire {
+  const queues = new Map<string, Promise<unknown>>()
+  let pending = 0
+
+  /** Serial per-team queue: same key waits, other keys run in parallel. */
+  function enqueue<T>(key: string, task: () => Promise<T>): Promise<T> {
+    pending += 1
+    const prev = queues.get(key) ?? Promise.resolve()
+    const run = async (): Promise<T> => {
+      try {
+        return await task()
+      } finally {
+        pending -= 1 // settles BEFORE the returned promise resolves
+      }
+    }
+    const next = prev.then(run, run) // run regardless of how the predecessor settled
+    queues.set(
+      key,
+      next.then(
+        () => undefined,
+        () => undefined,
+      ),
+    )
+    return next
+  }
+
+  /** One classified request — NEVER enqueues (public ops own the queue). */
+  async function raw(body: Record<string, unknown>): Promise<boolean> {
+    let res: CanvasWireResult
+    try {
+      res = await deps.send(body)
+    } catch (error) {
+      const message = String((error as Error | undefined)?.message ?? error).slice(0, 80)
+      deps.onNotice('error', `画布不可达：${message}`)
+      return false
+    }
+    if (res.status >= 400) {
+      deps.onNotice('error', errorText(res.body) ?? `HTTP ${res.status}`)
+      return false
+    }
+    if (res.body.ok === true) return true
+    const text = errorText(res.body)
+    if (text !== undefined) {
+      deps.onNotice('error', text)
+      return false
+    }
+    return true // ok:false without error: idempotent no-op (absent target / cap)
+  }
+
+  async function serial(body: Record<string, unknown>, ids: readonly string[]): Promise<boolean> {
+    for (const id of ids) {
+      if (!(await raw({ ...body, id }))) return false
+    }
+    return true
+  }
+
+  return {
+    createTeam(name, ids, created = false) {
+      return enqueue(name, async () => {
+        if (!(await raw({ action: 'create', name }))) return false
+        for (let i = 0; i < ids.length; i++) {
+          if (!(await raw({ action: 'add-member', name, id: ids[i]! }))) {
+            // A failure on the FIRST add of a team this action created leaves
+            // a ghost EMPTY team on the host — compensate with a remove.
+            // Later failures keep whatever members genuinely joined.
+            if (created && i === 0) await raw({ action: 'remove', name })
+            return false
+          }
+        }
+        return true
+      })
+    },
+    addMembers(team, ids) {
+      return enqueue(team, () => serial({ action: 'add-member', name: team }, ids))
+    },
+    removeMembers(team, ids) {
+      return enqueue(team, () => serial({ action: 'remove-member', name: team }, ids))
+    },
+    runRosterOps(team, ops) {
+      return enqueue(team, async () => {
+        for (const op of ops) {
+          const body = op.op === 'remove'
+            ? { action: 'remove-member', name: team, id: op.id }
+            : { action: 'add-member', name: team, id: op.id }
+          if (!(await raw(body))) return false
+        }
+        return true
+      })
+    },
+    removeTeam(name) {
+      return enqueue(name, () => raw({ action: 'remove', name }))
+    },
+    hasPending() {
+      return pending > 0
+    },
+  }
+}

package/nexus-stage/src/edges.ts

@@ -0,0 +1,72 @@
+/**
+ * Star-shaped membership edges for the 2D planning canvas: one spoke per
+ * (team frame -> member card), replacing the O(n^2) pairwise mesh. All
+ * geometry is world-space so the SVG layer can emit raw coordinates - the
+ * transformed #world container carries them to the screen for free.
+ *
+ * Anchor contract (must stay in lockstep with planning.css):
+ * - origin   = the frame titlebar's bottom-edge midpoint. The head is a
+ *   24px border-box straddling the frame's top border at top:-13px, so
+ *   its bottom edge sits at fy + 11, horizontally centered at fx + fw/2.
+ * - target   = the member card's top-edge midpoint {nx, ny - NODE_H/2}.
+ *
+ * Cross-team members draw solid from their first membership (state order)
+ * and dashed from every later one - the many-to-many invariant made
+ * visible. Edges are derived only; there is no freehand edge in this
+ * canvas. Pure: no DOM, no three.
+ * @module nexus-stage/edges
+ */
+
+import { NODE_H } from './world'
+import type { FrameGeom } from './world'
+
+/** Titlebar border-box height (planning.css .frame-head must match). */
+export const FRAME_HEAD_H = 24
+/** Titlebar CSS top offset, negative - straddles the frame's top border. */
+export const FRAME_HEAD_TOP = -13
+/** Origin anchor: frame top + the head's bottom edge offset. */
+export const FRAME_HEAD_LIFT = FRAME_HEAD_TOP + FRAME_HEAD_H
+
+/** Minimal team shape (topology.CanvasTeam satisfies it). */
+export interface EdgeTeam { name: string; members: ReadonlyArray<{ id: string }> }
+
+/** One derived spoke, ready for the SVG layer. */
+export interface StarEdge {
+  x1: number
+  y1: number
+  x2: number
+  y2: number
+  /** True from a member's second membership on (cross-team many-to-many). */
+  dashed: boolean
+  /** Team name and member id, for keyed diffing. */
+  team: string
+  id: string
+}
+
+/**
+ * Compute every membership spoke for the current world. Frames without a
+ * rect and member ids without a position are skipped - dangling rows are
+ * a polling transient, not an error.
+ */
+export function starEdges(
+  teams: ReadonlyArray<EdgeTeam>,
+  frames: ReadonlyMap<string, FrameGeom>,
+  positions: ReadonlyMap<string, { readonly x: number; readonly y: number }>,
+): StarEdge[] {
+  const out: StarEdge[] = []
+  const seen = new Set<string>()
+  for (const team of teams) {
+    const rect = frames.get(team.name)
+    if (rect === undefined) continue
+    const x1 = rect.x + rect.w / 2
+    const y1 = rect.y + FRAME_HEAD_LIFT
+    for (const member of team.members) {
+      const pos = positions.get(member.id)
+      if (pos === undefined) continue
+      const dashed = seen.has(member.id)
+      seen.add(member.id)
+      out.push({ x1, y1, x2: pos.x, y2: pos.y - NODE_H / 2, dashed, team: team.name, id: member.id })
+    }
+  }
+  return out
+}