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

package/nexus-stage/src/planning.css

@@ -0,0 +1,280 @@
+/* Planning mode (2D infinite canvas) — ported from the approved wireframe
+   (feedback/2026-08-27-nexus-canvas-ux/prototype-v1.html) with the design
+   system's three-layer token discipline. Tokens are scoped to #dsh-plan
+   (token sovereignty: the stage owns its theme, detached from any host).
+   Deviations from the prototype, all for computable geometry:
+   - .frame-head is horizontally centered with a fixed 24px border-box
+     height, so the star-edge origin is exactly (fx + fw/2, fy + 11);
+   - .node has a fixed 56px border-box height matching world.NODE_H, with
+     nowrap/ellipsis so the card can never outgrow the edge math.
+   Layers (z): grid 0 < world 1 < marquee 2 < HUD 3. */
+
+#dsh-plan *,#dsh-plan *::before,#dsh-plan *::after{box-sizing:border-box}
+
+#dsh-plan{
+  /* primitive — bound to the workbench tokens (--n-*, workbench.css) so the
+     board follows the same dark/light theme as the rail; the literal after
+     each comma is the stage's own dark value, kept so the board still
+     renders on a host that ships without workbench.css (token sovereignty). */
+  --uupm-ink-0:var(--n-ink,#dde3f0); --uupm-ink-1:var(--n-ink-muted,#7a86a0);
+  --uupm-bg-0:var(--n-bg,#060a12); --uupm-bg-1:var(--n-panel,#0d1322); --uupm-bg-2:var(--n-raised,#131b2e);
+  --uupm-accent:var(--n-accent,#9673f7); --uupm-live:var(--n-live,#4ade80); --uupm-cold:var(--n-cold,#7a86a0);
+  --uupm-edge-member:var(--n-canvas,#22d3ee);
+  --uupm-warn:var(--n-act,#f59e0b); --uupm-error:var(--n-danger,#f87171); --uupm-indigo:var(--n-federal,#6366f1);
+  /* accent washes (hover 8% / active 12-18% / tint 5-10%), one definition each */
+  --uupm-wash-5:color-mix(in srgb,var(--uupm-accent) 5%,transparent);
+  --uupm-wash-8:color-mix(in srgb,var(--uupm-accent) 8%,transparent);
+  --uupm-wash-12:color-mix(in srgb,var(--uupm-accent) 12%,transparent);
+  --uupm-wash-15:color-mix(in srgb,var(--uupm-accent) 15%,transparent);
+  --uupm-wash-18:color-mix(in srgb,var(--uupm-accent) 18%,transparent);
+  /* semantic */
+  --surface:var(--uupm-bg-1); --ink:var(--uupm-ink-0); --ink-muted:var(--uupm-ink-1);
+  --accent:var(--uupm-accent); --edge-live:var(--uupm-live); --edge-cold:var(--uupm-cold);
+  --federal:var(--uupm-indigo);
+  /* component */
+  --card-bg:var(--surface); --card-line:var(--n-card-line,#5c6680); --card-line-hover:var(--uupm-ink-1);
+  --toolbar-bg:color-mix(in srgb,var(--uupm-bg-1) 92%,transparent);
+  --grid-dot:color-mix(in srgb,var(--uupm-ink-1) 22%,transparent);
+  --scrim:color-mix(in srgb,var(--uupm-bg-0) 60%,transparent);
+  --error-ink:var(--n-error-ink,#fecaca); --error-panel:var(--n-error-panel,#2a0d10f2);
+}
+
+#dsh-plan{
+  position:absolute; inset:0; overflow:hidden; background:var(--uupm-bg-0); color:var(--ink);
+  font-size:13px; line-height:1.5; outline:none;
+}
+#dsh-plan .mono{font-family:ui-monospace,Cascadia,Consolas,monospace}
+#dsh-plan:focus-visible{outline:2px solid var(--accent); outline-offset:-2px}
+
+/* ── dot-grid world layer: screen-fixed, positioned by JS from the viewport ── */
+#dsh-plan .p-grid{position:absolute; inset:0; z-index:0; pointer-events:none;
+  background-image:radial-gradient(circle, var(--grid-dot) 1px, transparent 1px);
+  background-size:24px 24px; background-position:0 0}
+
+/* ── transformed world container ── */
+#dsh-plan .p-world{position:absolute; inset:0; z-index:1; transform-origin:0 0}
+#dsh-plan .p-layer{position:absolute; inset:0; pointer-events:none}
+#dsh-plan .p-edges{position:absolute; overflow:visible; width:100%; height:100%; pointer-events:none}
+/* The team frame is a grouping surface, not an interactive one: left
+   event-transparent so real drags reach the member cards inside it (the
+   frame head opts back in for group-drag/menu/Delete). */
+#dsh-plan .p-frame{pointer-events:none}
+#dsh-plan .p-frame-head{pointer-events:auto}
+#dsh-plan .p-node{pointer-events:auto}
+#dsh-plan .e-member{stroke:var(--uupm-edge-member); stroke-opacity:.38; stroke-width:1.5}
+#dsh-plan .e-member.dashed{stroke-dasharray:3 4}
+
+/* ── team frame ── */
+/* --frame-line is the team hue set inline per frame (frameHue); --frame-ink is
+   what the frame actually paints with — the hue itself on dark, shaded 72%
+   toward black on light, where amber/lime/teal outlines fell to 1.8-2.2:1. */
+#dsh-plan .p-frame{--frame-ink:var(--frame-line,#8B5CF6)}
+@media (prefers-color-scheme: light){
+  #dsh-plan .p-frame{--frame-ink:color-mix(in srgb,var(--frame-line,#8B5CF6) 72%,black)}
+}
+#dsh-plan .p-frame{position:absolute; border:1px solid var(--frame-ink); border-radius:10px;
+  background:var(--frame-bg,var(--uupm-wash-5)); min-width:120px; min-height:60px}
+#dsh-plan .p-frame-head{position:absolute; top:-13px; left:50%; transform:translateX(-50%);
+  height:24px; padding:0 10px; border-radius:6px; display:flex; gap:8px; align-items:center;
+  background:var(--uupm-bg-2); border:1px solid var(--frame-ink);
+  font-size:12px; font-weight:600; letter-spacing:.02em; white-space:nowrap; cursor:grab}
+#dsh-plan .p-frame-head:active{cursor:grabbing}
+#dsh-plan .p-frame-head:hover{border-color:var(--card-line-hover)}
+#dsh-plan .p-frame-head .cnt{color:var(--ink-muted); font-weight:400}
+#dsh-plan .p-frame-head .route{font-size:10.5px; color:var(--ink-muted)}
+
+/* ── node card (fixed 56px border-box height = world.NODE_H) ── */
+#dsh-plan .p-node{position:absolute; width:172px; height:56px; padding:8px 26px 8px 14px;
+  background:var(--card-bg); border:1px solid var(--card-line); border-left:3px solid var(--edge-live);
+  border-radius:8px; cursor:grab; user-select:none;
+  transition:border-color 120ms cubic-bezier(0.2,0,0,1), transform 120ms cubic-bezier(0.2,0,0,1)}
+#dsh-plan .p-node:hover{border-color:var(--card-line-hover)}
+#dsh-plan .p-node:active{cursor:grabbing}
+#dsh-plan .p-node:focus-visible{outline:2px solid var(--accent); outline-offset:2px}
+#dsh-plan .p-node.selected{outline:2px solid var(--accent); outline-offset:1px}
+#dsh-plan .p-node.dragging{transform:scale(1.02); border-color:var(--accent)}
+#dsh-plan .p-node.cold{border-left-color:var(--edge-cold)}
+#dsh-plan .p-node .nm{font-weight:600; display:flex; align-items:center; gap:7px;
+  overflow:hidden; text-overflow:ellipsis; white-space:nowrap}
+/* The name span clips with an ellipsis (min-width:0 lets it shrink inside
+   the flex row) — without it a long peer address was hard-cut mid-digit. */
+#dsh-plan .p-node .nm-text{min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap}
+#dsh-plan .p-node .dot{width:8px; height:8px; border-radius:50%; background:var(--edge-live); flex:none}
+#dsh-plan .p-node.cold .dot{background:transparent; border:1.5px solid var(--edge-cold)}
+#dsh-plan .p-node .sub{font-size:11px; color:var(--ink-muted); margin-top:2px;
+  overflow:hidden; text-overflow:ellipsis; white-space:nowrap}
+#dsh-plan .p-node .prio{position:absolute; top:6px; right:8px; font-size:10px; color:var(--ink-muted);
+  border:1px solid var(--card-line); border-radius:4px; padding:0 5px}
+
+/* ── marquee ── */
+#dsh-plan .p-marquee{position:absolute; z-index:2; display:none; pointer-events:none;
+  border:1px solid var(--accent); background:var(--uupm-wash-8)}
+
+/* ── HUD ── */
+#dsh-plan .p-toolbar{position:absolute; top:16px; left:16px; z-index:3; display:flex; gap:6px; align-items:center;
+  background:var(--toolbar-bg); border:1px solid var(--card-line); border-radius:8px; padding:6px 8px}
+#dsh-plan .p-tabs{position:absolute; top:16px; left:50%; transform:translateX(-50%); z-index:3; display:flex; gap:4px;
+  background:var(--toolbar-bg); border:1px solid var(--card-line); border-radius:8px; padding:4px}
+#dsh-plan .p-tabs [role=tab]{background:transparent; color:var(--ink-muted); border:1px solid transparent; border-radius:6px;
+  padding:4px 12px; font:inherit; cursor:pointer}
+#dsh-plan .p-tabs [role=tab]:hover{color:var(--ink); border-color:var(--card-line)}
+#dsh-plan .p-tabs [role=tab][aria-selected=true]{color:var(--ink); border-color:var(--accent); background:var(--uupm-wash-12)}
+#dsh-plan .p-tabs [role=tab]:focus-visible{outline:2px solid var(--accent); outline-offset:1px}
+#dsh-plan .p-toolbar button{background:transparent; color:var(--ink); border:1px solid var(--card-line); border-radius:6px;
+  padding:4px 10px; font:inherit; cursor:pointer; white-space:nowrap}
+#dsh-plan .p-toolbar button:hover{border-color:var(--accent)}
+#dsh-plan .p-toolbar button:active{background:var(--uupm-wash-15)}
+#dsh-plan .p-toolbar button:focus-visible{outline:2px solid var(--accent); outline-offset:1px}
+#dsh-plan .p-zoom{min-width:44px; text-align:center; font-size:11px; color:var(--ink-muted)}
+#dsh-plan .p-lamp{display:flex; align-items:center; gap:6px; font-size:11px; color:var(--ink-muted); padding:0 6px}
+#dsh-plan .p-lamp i{width:7px; height:7px; border-radius:50%; background:var(--ink-muted); transition:background 140ms ease}
+#dsh-plan .p-lamp.saved i{background:var(--edge-live)}
+#dsh-plan .p-lamp.pending i{background:var(--uupm-warn)}
+#dsh-plan .p-lamp.error{color:var(--uupm-error); cursor:pointer}
+#dsh-plan .p-lamp.error i{background:var(--uupm-error)}
+#dsh-plan .p-lamp.error:hover{border:1px solid var(--uupm-error); border-radius:4px}
+
+#dsh-plan .p-status{position:absolute; top:16px; right:16px; z-index:3; display:flex; gap:14px;
+  background:var(--toolbar-bg); border:1px solid var(--card-line); border-radius:8px; padding:8px 14px; font-size:12px}
+#dsh-plan .p-status b{font-weight:600}
+#dsh-plan .ok{color:var(--edge-live)} #dsh-plan .warn{color:var(--uupm-warn)} #dsh-plan .mut{color:var(--ink-muted)}
+
+#dsh-plan .p-legend{position:absolute; bottom:16px; left:16px; z-index:3; font-size:11px; color:var(--ink-muted);
+  background:var(--toolbar-bg); border:1px solid var(--card-line); border-radius:8px; padding:8px 12px;
+  display:grid; gap:4px}
+#dsh-plan .p-legend i{display:inline-block; width:18px; border-top:2px solid var(--uupm-edge-member);
+  vertical-align:middle; margin-right:6px}
+#dsh-plan .p-legend i.dashed{border-top-style:dashed}
+
+/* ── narrow board (<680px): the HUD stacks instead of colliding ──
+   The toolbar, status chip and legend are absolutely placed for a wide
+   board; on a phone they overlapped each other and the toolbar's CJK
+   labels wrapped one glyph per line. Toolbar scrolls sideways on one row,
+   the status chip drops under it, the legend (reference, not state) hides. */
+@media (max-width:680px){
+  #dsh-plan .p-toolbar{left:8px; right:8px; top:8px; overflow-x:auto; scrollbar-width:none}
+  #dsh-plan .p-toolbar > *{flex:none}
+  #dsh-plan .p-status{left:8px; right:auto; top:58px; padding:6px 10px; gap:10px; flex-wrap:wrap}
+  #dsh-plan .p-legend{display:none}
+}
+@media (pointer:coarse){
+  #dsh-plan .p-toolbar button{min-height:36px; min-width:36px}
+}
+
+/* ── reduced motion: zero animation, state carried by text (hard baseline) ── */
+@media (prefers-reduced-motion: reduce){
+  #dsh-plan *{transition:none !important; animation:none !important}
+}
+
+/* ── PR C: drop-target highlight, context menu, name dialog, notices ── */
+#dsh-plan .p-frame.drop-target{border-color:var(--accent); border-width:2px; background:var(--uupm-wash-12)}
+#dsh-plan .p-frame-head:focus-visible{outline:2px solid var(--accent); outline-offset:1px}
+
+/* ── PR D: federation overlay — peer badges, activity/federal edges, status fly ── */
+/* Peer cards: the 'peer' tag is ~36px wide against the 26px gutter a P0–P9
+   tag fits in, so it sat on top of the address text — widen the gutter. */
+#dsh-plan .p-node.remote{border-left-color:var(--federal); padding-right:46px}
+#dsh-plan .p-node.remote .dot{background:var(--federal)}
+#dsh-plan .p-node.remote .prio{color:var(--ink)}
+#dsh-plan .e-activity{stroke:var(--accent); stroke-width:2; stroke-dasharray:8 6; stroke-opacity:.9}
+#dsh-plan .e-federal{stroke:var(--federal); stroke-width:1.5; stroke-dasharray:6 5; stroke-opacity:.5}
+#dsh-plan .edge-label{font-size:10.5px; fill:var(--ink-muted)}
+/* in-flight routes flow only when motion is welcome; reduced-motion keeps
+   the zero-animation baseline (state stays in the label text). */
+@media (prefers-reduced-motion: no-preference){
+  #dsh-plan .e-activity{animation:p-activity-flow 1.1s linear infinite}
+}
+@keyframes p-activity-flow{to{stroke-dashoffset:-28}}
+#dsh-plan .p-status{cursor:pointer}
+#dsh-plan .p-status:hover{border-color:var(--accent)}
+#dsh-plan .p-status:active{background:var(--uupm-wash-12)}
+#dsh-plan .p-status:focus-visible{outline:2px solid var(--accent); outline-offset:2px}
+
+#dsh-plan .p-menu{position:fixed; z-index:5; min-width:170px; display:grid; padding:4px; gap:2px;
+  background:var(--toolbar-bg); border:1px solid var(--card-line); border-radius:8px}
+#dsh-plan .p-menu [role=menuitem]{background:transparent; color:var(--ink); border:1px solid transparent;
+  border-radius:6px; padding:6px 10px; font:inherit; text-align:left; cursor:pointer; white-space:nowrap}
+#dsh-plan .p-menu [role=menuitem]:hover{border-color:var(--card-line); background:var(--uupm-wash-8)}
+#dsh-plan .p-menu [role=menuitem]:active{background:var(--uupm-wash-18)}
+#dsh-plan .p-menu [role=menuitem]:focus-visible{outline:2px solid var(--accent); outline-offset:1px}
+#dsh-plan .p-menu [role=menuitem][aria-disabled=true]{color:var(--ink-muted); cursor:not-allowed}
+
+#dsh-plan .p-dialog{position:absolute; inset:0; z-index:6; display:grid; place-items:center;
+  background:var(--scrim)}
+#dsh-plan .p-dialog-panel{min-width:300px; padding:14px 16px; display:grid; gap:10px;
+  background:var(--uupm-bg-2); border:1px solid var(--card-line); border-radius:10px}
+#dsh-plan .p-dialog-title{font-weight:600; font-size:12.5px; color:var(--ink)}
+#dsh-plan .p-dialog-input{font:inherit; color:var(--ink); background:var(--uupm-bg-0);
+  border:1px solid var(--card-line); border-radius:6px; padding:7px 10px}
+#dsh-plan .p-dialog-input:hover{border-color:color-mix(in srgb,var(--uupm-ink-1) 55%,transparent)}
+#dsh-plan .p-dialog-input:focus-visible{outline:2px solid var(--accent); outline-offset:1px; border-color:var(--accent)}
+#dsh-plan .p-dialog-err{min-height:1.2em; font-size:11px; color:var(--uupm-error)}
+#dsh-plan .p-dialog-row{display:flex; gap:8px; justify-content:flex-end}
+#dsh-plan .p-dialog-row button{background:transparent; color:var(--ink); border:1px solid var(--card-line);
+  border-radius:6px; padding:5px 12px; font:inherit; cursor:pointer}
+#dsh-plan .p-dialog-row button:hover{border-color:var(--accent)}
+#dsh-plan .p-dialog-row button:active{background:var(--uupm-wash-15)}
+#dsh-plan .p-dialog-row button:focus-visible{outline:2px solid var(--accent); outline-offset:1px}
+
+#dsh-plan .p-notice-stack{position:absolute; bottom:52px; left:50%; transform:translateX(-50%); z-index:5;
+  display:grid; gap:6px; justify-items:center; pointer-events:none}
+#dsh-plan .p-notice{max-width:60ch; padding:7px 12px; font-size:12px; color:var(--ink);
+  background:var(--toolbar-bg); border:1px solid var(--card-line); border-radius:8px; white-space:nowrap;
+  overflow:hidden; text-overflow:ellipsis}
+#dsh-plan .p-notice.error{color:var(--error-ink); border-color:var(--uupm-error); background:var(--error-panel)}
+
+/* Panel-slim migration: the unjoined-sessions join affordance on the toolbar. */
+#dsh-plan .p-netbtn{color:var(--ink-muted)}
+#dsh-plan .p-netbtn:not([disabled]){color:var(--ink)}
+#dsh-plan .p-netmenu{max-height:240px; overflow:auto}
+
+/* ── Node list drawer (network-membership-display): teamed nodes hold the
+   canvas; every other session is managed here, switched by host. ── */
+#dsh-plan .p-nodebtn{color:var(--ink)}
+#dsh-plan .p-nodelist{min-width:300px; max-width:340px; max-height:420px; overflow:auto; padding:6px}
+#dsh-plan .p-nodelist-head{display:flex; align-items:center; justify-content:space-between; gap:8px;
+  padding:2px 4px 6px; border-bottom:1px solid var(--card-line)}
+#dsh-plan .p-nodelist-title{font-size:12px; font-weight:600; color:var(--ink)}
+#dsh-plan .p-nodesel{font:inherit; font-size:11.5px; color:var(--ink); background:var(--uupm-bg-0);
+  border:1px solid var(--card-line); border-radius:6px; padding:2px 6px; max-width:220px}
+#dsh-plan .p-nodesel:focus-visible{outline:2px solid var(--accent); outline-offset:1px}
+#dsh-plan .p-nodelist-group{font-size:11px; color:var(--ink-muted); padding:8px 4px 3px;
+  display:flex; align-items:baseline; gap:8px}
+#dsh-plan .p-nodelist-note{font-size:10px; color:var(--ink-muted); opacity:.8}
+#dsh-plan .p-noderow{display:flex; align-items:center; gap:6px; padding:3px 4px; border-radius:6px;
+  font-size:12px; color:var(--ink)}
+#dsh-plan .p-noderow:hover{background:var(--uupm-wash-8)}
+#dsh-plan .p-nodedot{flex:none; width:7px; height:7px; border-radius:50%; background:var(--edge-live)}
+#dsh-plan .p-nodedot.cold{background:var(--ink-muted)}
+#dsh-plan .p-nodedot.off{background:transparent; border:1px solid var(--ink-muted)}
+#dsh-plan .p-nodename{flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap}
+#dsh-plan .p-nonet{flex:none; font-size:10px; color:var(--uupm-warn); border:1px solid var(--uupm-warn);
+  border-radius:4px; padding:0 4px}
+#dsh-plan .p-teamcount{flex:none; font-size:10px; color:var(--ink-muted); border:1px solid var(--card-line);
+  border-radius:4px; padding:0 4px}
+#dsh-plan .p-listbtn{flex:none; background:transparent; color:var(--ink); border:1px solid var(--card-line);
+  border-radius:5px; padding:1px 7px; font:inherit; font-size:11px; cursor:pointer}
+#dsh-plan .p-listbtn:hover{border-color:var(--card-line-hover); background:var(--uupm-wash-8)}
+#dsh-plan .p-listbtn:focus-visible{outline:2px solid var(--accent); outline-offset:1px}
+#dsh-plan .p-nodelist-empty{padding:10px 4px; font-size:11.5px; color:var(--ink-muted)}
+
+/* ── Frame resize handles (owner ruling: frames stretch/adjust) — eight
+   invisible hit zones that show the grip on hover. ── */
+#dsh-plan .p-frame{position:absolute}
+#dsh-plan .p-frame-handle{position:absolute; pointer-events:auto; width:10px; height:10px; z-index:2; opacity:0;
+  transition:opacity 120ms ease}
+#dsh-plan .p-frame:hover .p-frame-handle{opacity:1}
+#dsh-plan .p-frame-handle::after{content:''; position:absolute; inset:2px; background:var(--frame-ink);
+  border-radius:2px}
+#dsh-plan .p-h-n{top:-5px; left:calc(50% - 12px); width:24px; height:8px; cursor:ns-resize}
+#dsh-plan .p-h-s{bottom:-5px; left:calc(50% - 12px); width:24px; height:8px; cursor:ns-resize}
+#dsh-plan .p-h-e{right:-5px; top:calc(50% - 12px); width:8px; height:24px; cursor:ew-resize}
+#dsh-plan .p-h-w{left:-5px; top:calc(50% - 12px); width:8px; height:24px; cursor:ew-resize}
+#dsh-plan .p-h-ne{top:-5px; right:-5px; cursor:nesw-resize}
+#dsh-plan .p-h-nw{top:-5px; left:-5px; cursor:nwse-resize}
+#dsh-plan .p-h-se{bottom:-5px; right:-5px; cursor:nwse-resize}
+#dsh-plan .p-h-sw{bottom:-5px; left:-5px; cursor:nesw-resize}
+#dsh-plan .p-h-ne::after, #dsh-plan .p-h-sw::after{transform:rotate(45deg)}
+#dsh-plan .p-h-nw::after, #dsh-plan .p-h-se::after{transform:rotate(-45deg)}
+#dsh-plan .p-frame.selected .p-frame-handle{opacity:1}
+#dsh-plan .p-frame.selected{outline:1px solid var(--frame-ink)}

package/nexus-stage/src/seat.ts

@@ -0,0 +1,35 @@
+/**
+ * Deterministic fallback seating: a session id hashes to a stable polar
+ * seat, so a reload reproduces the same star map even when no layout is
+ * persisted (saved layouts still win - main.ts checks them first). This
+ * replaces three Math.random() calls whose only product was a star map
+ * that reshuffled on every reload, making screenshots and sessions
+ * incomparable. Same hash family as getHue (FNV-1a 32-bit); zero
+ * dependencies so the unit test pins stability/bounds without three.
+ * @module nexus-stage/seat
+ */
+
+/** Radial distance bounds, mirroring the historical random-seat envelope. */
+export const SEAT_DIST_MIN = 12
+export const SEAT_DIST_MAX = 30
+/** Vertical jitter bound in world units above/below the grid plane. */
+export const SEAT_Y_SPAN = 1
+
+/** FNV-1a 32-bit - the same determinism family as getHue. */
+export function hashId(sid: string): number {
+  let h = 0x811c9dc5
+  for (let i = 0; i < sid.length; i++) {
+    h ^= sid.charCodeAt(i)
+    h = Math.imul(h, 0x01000193) >>> 0
+  }
+  return h >>> 0
+}
+
+/** Deterministic world seat (x, vertical jitter, z) for one session id. */
+export function seatFor(sid: string): { x: number; y: number; z: number } {
+  const h = hashId(sid)
+  const angle = ((h % 3600) / 3600) * Math.PI * 2
+  const dist = SEAT_DIST_MIN + (((h >>> 9) % 1800) / 1800) * (SEAT_DIST_MAX - SEAT_DIST_MIN)
+  const y = (((h >>> 18) % 2000) / 1999) * 2 * SEAT_Y_SPAN - SEAT_Y_SPAN
+  return { x: Math.cos(angle) * dist, y, z: Math.sin(angle) * dist }
+}

package/nexus-stage/src/stage-name.ts

@@ -0,0 +1,13 @@
+/**
+ * Display name for one stage node: the session title when present, then the
+ * routable team label (`team/<id8>`), then the host fallback label
+ * (`dsh-host-<node>-<id8>`). Untitled cold joined sessions carry no title and
+ * without the middle step the canvas drowned in dsh-host-* noise (2026-08-30
+ * user report: the planning canvas showed a dozen unreadable label cards).
+ * @module nexus-stage/stage-name
+ */
+
+/** One node's display title. */
+export function displayName(node: { readonly name?: string; readonly team?: string; readonly label?: string }): string {
+  return node.name ?? node.team ?? node.label ?? ''
+}

package/nexus-stage/src/tokens.ts

@@ -0,0 +1,32 @@
+/**
+ * A2A Nexus design tokens.
+ * Three-layer: primitive(C) -> semantic(S) -> component-level inline styles.
+ */
+
+export const C = {
+  bg0: '#060a12',
+  bg1: '#0d1322',
+  ink: '#dde3f0',
+  inkMuted: '#7a86a0',
+  accent: '#8b5cf6',
+  liveGreen: '#4ade80',
+  coldGrey: '#4a5568',
+  lineFederal: '#6366f1',
+  membershipLine: '#22d3ee',
+} as const;
+
+/**
+ * Semantic layer: the scene-facing names the viewer actually consumes,
+ * each pinned to its primitive above. This is the `S` main.ts reached for
+ * as `T.S.*` — the layer was documented but never exported, so every seat
+ * attempt threw and cycle()'s empty catch buried it: an eternally empty
+ * stage behind a healthy-looking render loop.
+ */
+export const S = {
+  /** Mesh color + emissive for live session nodes (primitive liveGreen). */
+  nodeLive: 0x4ade80,
+  /** Mesh color + emissive for cold/joined-offline nodes (primitive coldGrey). */
+  nodeCold: 0x4a5568,
+} as const;
+
+export const FRAME_HUES = [0x8b5cf6, 0x3b82f6, 0x14b8a6, 0xf59e0b, 0xec4899, 0x84cc16];

package/nexus-stage/src/viewport.ts

@@ -0,0 +1,83 @@
+/**
+ * Viewport math for the 2D planning canvas: pan/zoom state with the same
+ * clamp contract as the persisted layout (scale 0.25-3, coordinates
+ * bounded), pointer-anchored zoom, and the CSS transform that carries the
+ * world container. Pure functions throughout - the DOM layer applies the
+ * returned transform, it never computes one.
+ *
+ * Convention (shared with the host LayoutStore): (x, y) is the world
+ * point displayed at the viewport's top-left corner; scale multiplies
+ * world units into screen pixels.
+ * @module nexus-stage/viewport
+ */
+
+import { SCALE_MAX, SCALE_MIN, type LayoutViewport } from './layout-doc'
+
+/** Re-export for callers that only want the viewport vocabulary. */
+export type { LayoutViewport, LayoutViewport as ViewportState } from './layout-doc'
+
+/** The zero viewport: origin, unzoomed - what a fresh canvas shows. */
+export const IDENTITY_VIEWPORT: LayoutViewport = { x: 0, y: 0, scale: 1 }
+
+function clampScale(scale: number): number {
+  return Math.max(SCALE_MIN, Math.min(SCALE_MAX, scale))
+}
+
+/** Clamp an untrusted viewport into the persisted-layout envelope. */
+export function clampViewport(vp: LayoutViewport): LayoutViewport {
+  const safe = Number.isFinite(vp.scale) ? vp.scale : 1
+  const x = Number.isFinite(vp.x) ? vp.x : 0
+  const y = Number.isFinite(vp.y) ? vp.y : 0
+  return { x, y, scale: clampScale(safe) }
+}
+
+/** Screen (client-relative px) -> world point. */
+export function screenToWorld(vp: LayoutViewport, sx: number, sy: number): { x: number; y: number } {
+  return { x: vp.x + sx / vp.scale, y: vp.y + sy / vp.scale }
+}
+
+/** World point -> screen (client-relative px). */
+export function worldToScreen(vp: LayoutViewport, wx: number, wy: number): { x: number; y: number } {
+  return { x: (wx - vp.x) * vp.scale, y: (wy - vp.y) * vp.scale }
+}
+
+/** Pan by screen-space pixels; dividing by scale keeps 1px = 1px on screen. */
+export function panBy(vp: LayoutViewport, dx: number, dy: number): LayoutViewport {
+  return { x: vp.x + dx / vp.scale, y: vp.y + dy / vp.scale, scale: vp.scale }
+}
+
+/**
+ * Zoom by a multiplicative factor keeping the world point under the
+ * anchor screen position (ax, ay) fixed: the card under the cursor stays
+ * under the cursor. Invariant: vp' = vp + a/s - a/s'.
+ */
+export function zoomAt(vp: LayoutViewport, factor: number, ax: number, ay: number): LayoutViewport {
+  const scale = clampScale(vp.scale * factor)
+  if (scale === vp.scale) return vp
+  return { x: vp.x + ax / vp.scale - ax / scale, y: vp.y + ay / vp.scale - ay / scale, scale }
+}
+
+/** Content bounds in world space (null = nothing to fit). */
+export interface WorldBounds { readonly minX: number; readonly minY: number; readonly maxX: number; readonly maxY: number }
+
+/**
+ * Fit the content bounds into a viewW x viewH viewport at 90% fill,
+ * clamped to the persisted scale envelope; empty bounds reset to identity.
+ */
+export function fitView(bounds: WorldBounds | null, viewW: number, viewH: number, maxScale = Number.POSITIVE_INFINITY): LayoutViewport {
+  if (bounds === null || viewW <= 0 || viewH <= 0) return IDENTITY_VIEWPORT
+  const bw = bounds.maxX - bounds.minX
+  const bh = bounds.maxY - bounds.minY
+  if (!(bw > 0) || !(bh > 0)) return IDENTITY_VIEWPORT
+  const scale = clampScale(Math.min(maxScale, 0.9 * Math.min(viewW / bw, viewH / bh)))
+  return {
+    x: (bounds.minX + bounds.maxX) / 2 - viewW / (2 * scale),
+    y: (bounds.minY + bounds.maxY) / 2 - viewH / (2 * scale),
+    scale,
+  }
+}
+
+/** The CSS transform for the world container: translate then scale. */
+export function worldTransformCss(vp: LayoutViewport): string {
+  return `translate(${-vp.x * vp.scale}px, ${-vp.y * vp.scale}px) scale(${vp.scale})`
+}