From 4ffd632506e30550e05eae24b5c26a54730b0214 Mon Sep 17 00:00:00 2001
From: archipelago <archipelago@localhost>
Date: Sun, 9 Aug 2026 17:53:40 -0400
Subject: [PATCH] =?UTF-8?q?refactor(federation):=20keyed=20diff-reconciled?=
 =?UTF-8?q?=20map=20scene=20=E2=80=94=20stable=20intro,=20smooth=20revisit?=
 =?UTF-8?q?s?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Root causes of the flaky intro / janky revisits, all fixed structurally:

- Graph updates now RECONCILE against the live scene by identity (peer DID /
  request id) instead of wiping the SVG: in-place updates for label/online/
  trust changes, animated arrivals for new nodes, animated departures for
  removed ones, and short-way-around slot glides when the ring layout shifts.
  The old wipe-and-rebuild orphaned every in-flight intro tween whenever the
  5s poll or the async self-DID fetch landed mid-intro — that was the
  'sometimes parts don't show'.
- The intro is gated on readiness: first real container measurement (post-
  layout, via ResizeObserver) AND the self node being present, with a 1.2s
  fallback. Graph changes during the intro queue and apply on completion.
- Layout is deterministic per node: peers sort by DID for slot assignment and
  jitter/phase hash from the DID, so backend response order can't shuffle
  the map between polls.
- The long cinematic intro plays once per browser session; revisits get a
  shorter, lighter entrance that doesn't fight the route transition.
- selfDid seeds from the cached localStorage value (re-cached on fetch) so
  the centre node and links exist from the first frame.
- Requests' waiting-room orbit pushed clearly outside the peer rings (+1.0)
  with loose per-request hover jitter — outside until accepted, then the
  join animation glides them in.
- Full unmount hygiene: every tween killed by target (incl. the repeating
  sonar pulse), fallback timer cleared, window listeners removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../components/federation/NetworkMap3D.vue    | 925 ++++++++++++------
 neode-ui/src/views/Federation.vue             |   9 +-
 2 files changed, 617 insertions(+), 317 deletions(-)

diff --git a/neode-ui/src/components/federation/NetworkMap3D.vue b/neode-ui/src/components/federation/NetworkMap3D.vue
index 31834fac..d0d1ac31 100644
--- a/neode-ui/src/components/federation/NetworkMap3D.vue
+++ b/neode-ui/src/components/federation/NetworkMap3D.vue
@@ -51,6 +51,28 @@
 </template>
 
 <script setup lang="ts">
+// Federation network map — a keyed, diff-reconciled GSAP scene.
+//
+// ARCHITECTURE (the answer to "the intro is flaky and revisits are janky"):
+//
+// 1. The scene is KEYED by identity (peer DID / request id). Data changes
+//    reconcile against the live scene — update in place, animate arrivals in,
+//    animate departures out, tween slot changes — instead of wiping the SVG.
+//    A wipe-and-rebuild while the intro timeline was mid-flight used to
+//    orphan every tween target, which is exactly why parts of the intro
+//    vanished whenever the 5s poll (or the async self-DID fetch) landed
+//    during it.
+// 2. The intro is GATED on readiness: the container must have a real size
+//    (the first ResizeObserver callback, i.e. post-layout) and the self node
+//    must exist (it arrives async), with a 1.2s fallback so a failed DID
+//    fetch can't hold the scene hostage. Graph updates that land during the
+//    intro are queued and applied when it completes.
+// 3. Layout is DETERMINISTIC per node: peers sort by DID for slot assignment
+//    and jitter/phase derive from a DID hash, so backend response order
+//    can't shuffle the map between polls.
+// 4. The full cinematic intro plays once per browser session; revisits get a
+//    shorter, lighter entrance (they remount mid route-transition, where the
+//    long dolly reads as jank).
 import { computed, onActivated, onDeactivated, onMounted, onUnmounted, ref, watch } from 'vue'
 import { gsap, motionTokens, prefersReducedMotion } from '@/utils/motion'
 
@@ -69,7 +91,7 @@ export interface MapLink {
 }
 
 /** Inbound peer request awaiting a decision — rendered as a blinking yellow
- *  globe on the outermost orbit. */
+ *  globe hovering outside the peer orbits (not yet part of the federation). */
 export interface MapRequest {
   id: string
   label: string
@@ -94,6 +116,7 @@ const svgRef = ref<SVGSVGElement>()
 const peerCount = computed(() => props.nodes.filter(n => !n.is_self).length)
 
 const SVG_NS = 'http://www.w3.org/2000/svg'
+const FONT = "'Avenir Next', system-ui, sans-serif"
 
 /* ------------------------------------------------------------------ *
  * Scene state — mutated by GSAP tweens and read by the per-frame
@@ -101,10 +124,10 @@ const SVG_NS = 'http://www.w3.org/2000/svg'
  * repaints at 60fps and must not churn the reactivity graph.
  * ------------------------------------------------------------------ */
 const cam = {
-  rotY: -1.1, // intro starts swung around; settles to 0
+  rotY: 0,
   tilt: -0.5, // downward tilt; tweened between the 2D and 3D projections
   persp: 3.2, // perspective strength; large = near-orthographic (flat 2D)
-  zoom: 0.82, // intro dollies in to 1
+  zoom: 1,
   spin: 0, // rad/s — only ever non-zero from drag inertia; the scene does not
            // idle-orbit (nodes hold position so the map stays readable)
 }
@@ -127,13 +150,14 @@ interface GlobeDot {
 
 interface PeerVis {
   node: MapNode
+  /** Tweenable orbital slot (reconciliation glides nodes to new slots). */
   angle: number
-  ring: number
   ringRadius: number
   yJitter: number
   bobPhase: number
-  /** Intro/arrival progress 0→1: drives fly-in offset, scale, opacity. */
+  /** Arrival progress 0→1: drives fly-in offset, scale, opacity. */
   p: number
+  dying: boolean
   el: SVGGElement
   label: SVGTextElement
   linkEl: SVGPathElement | null
@@ -143,9 +167,6 @@ interface PeerVis {
   depth: number
 }
 
-/** A pending request on the map. Shares the peer projection maths; adds a
- *  blink phase and decision-animation fields (deathScale for the reject pop,
- *  a tweenable ringRadius for the accept glide). */
 interface RequestVis {
   req: MapRequest
   angle: number
@@ -154,7 +175,11 @@ interface RequestVis {
   bobPhase: number
   p: number
   blinking: boolean
+  /** Reject-pop scale multiplier. */
   deathScale: number
+  /** Set once the user decided — departure then skips the generic fade. */
+  decided: boolean
+  dying: boolean
   el: SVGGElement
   outline: SVGCircleElement
   halo: SVGCircleElement
@@ -166,11 +191,30 @@ interface RequestVis {
   depth: number
 }
 
+interface SelfVis {
+  did: string
+  el: SVGGElement
+  label: SVGTextElement
+  pulseEl: SVGCircleElement
+  dots: GlobeDot[]
+  radiusPx: number
+}
+
+interface RingVis {
+  el: SVGPathElement
+  radius: number
+  kind: 'peer' | 'request'
+}
+
+/** Render arrays include dying members (they animate out in place). Maps hold
+ *  only live members and drive reconciliation. */
 let peers: PeerVis[] = []
 let requestVis: RequestVis[] = []
-let selfEl: SVGGElement | null = null
+const peerMap = new Map<string, PeerVis>()
+const reqMap = new Map<string, RequestVis>()
+let selfVis: SelfVis | null = null
 const selfState = { p: 0 }
-let ringPaths: { el: SVGPathElement; radius: number }[] = []
+let ringPaths: RingVis[] = []
 let nodesLayer: SVGGElement | null = null
 let linksLayer: SVGGElement | null = null
 let ringsLayer: SVGGElement | null = null
@@ -182,18 +226,24 @@ let height = 0
 const fit = { unit: 1, centerY: 0 }
 let elapsed = 0
 let frame = 0
-let selfDots: GlobeDot[] = []
-let selfRadiusPx = 15
 let modeTween: gsap.core.Tween[] = []
 let modeInitialized = false
 
 const viewMode = ref<MapMode>('3d')
 let resizeObserver: ResizeObserver | null = null
 let intro: gsap.core.Timeline | null = null
-let spinTween: gsap.core.Tween | null = null
+let spinTween: gsap.core.Tween[] = []
 let tickerAttached = false
 let staticMode = false
 
+/** Lifecycle gates (see file header). */
+let built = false
+let introPlayed = false
+let introFallback: ReturnType<typeof setTimeout> | null = null
+let pendingGraphUpdate = false
+
+/* ------------------------------ helpers ---------------------------- */
+
 function trustColor(n: MapNode): string {
   switch (n.trust_level) {
     case 'trusted': return motionTokens.color.trusted
@@ -223,6 +273,49 @@ function ringFor(i: number, total: number): { ring: number; indexInRing: number;
   return { ring: RING_CAPACITIES.length, indexInRing: i - start, countInRing: Math.max(total - start, 1) }
 }
 
+function peerSlot(i: number, total: number): { angle: number; ringRadius: number; ring: number } {
+  const { ring, indexInRing, countInRing } = ringFor(i, total)
+  return {
+    angle: (indexInRing / countInRing) * Math.PI * 2 + ring * 0.5,
+    ringRadius: 1 + ring * 0.65,
+    ring,
+  }
+}
+
+function maxPeerRingRadius(total: number): number {
+  return total ? 1 + ringFor(total - 1, total).ring * 0.65 : 1
+}
+
+/** The request "waiting room" orbit sits clearly OUTSIDE the peer rings —
+ *  requests are not part of the federation until accepted. */
+function requestRingRadius(peerTotal: number): number {
+  return maxPeerRingRadius(peerTotal) + 1.0
+}
+
+/** Deterministic [0,1) from a string — jitter/phases keyed by identity, so a
+ *  node keeps its personality across polls, sessions, and reorderings. */
+function hashStr(s: string): number {
+  let h = 2166136261
+  for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 16777619)
+  return (h >>> 0) / 4294967296
+}
+
+/** Equivalent target angle nearest to `current`, so slot-change tweens take
+ *  the short way around the ring. */
+function nearestAngle(current: number, target: number): number {
+  const TWO = Math.PI * 2
+  let delta = (target - current) % TWO
+  if (delta > Math.PI) delta -= TWO
+  if (delta < -Math.PI) delta += TWO
+  return current + delta
+}
+
+function el<K extends keyof SVGElementTagNameMap>(tag: K, attrs: Record<string, string> = {}): SVGElementTagNameMap[K] {
+  const e = document.createElementNS(SVG_NS, tag)
+  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v)
+  return e
+}
+
 /** Project a world-space point through the camera. Returns screen coords + depth scale. */
 function project(x: number, y: number, z: number) {
   const cr = Math.cos(cam.rotY), sr = Math.sin(cam.rotY)
@@ -240,32 +333,7 @@ function project(x: number, y: number, z: number) {
   }
 }
 
-function clearScene() {
-  const svg = svgRef.value
-  if (svg) while (svg.firstChild) svg.removeChild(svg.firstChild)
-  peers = []
-  requestVis = []
-  ringPaths = []
-  selfEl = null
-  selfDots = []
-  activeRequest.value = null
-  nodesLayer = null
-  linksLayer = null
-  ringsLayer = null
-}
-
-function el<K extends keyof SVGElementTagNameMap>(tag: K, attrs: Record<string, string> = {}): SVGElementTagNameMap[K] {
-  const e = document.createElementNS(SVG_NS, tag)
-  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v)
-  return e
-}
-
-/** Deterministic pseudo-random in [0,1) from an index — stable across renders
- *  so nodes keep their orbit slot between data refreshes. */
-function hash01(i: number): number {
-  const x = Math.sin(i * 127.1 + 311.7) * 43758.5453
-  return x - Math.floor(x)
-}
+/* ---------------------------- globe dots ---------------------------- */
 
 /** Build a point-cloud sphere: dots on a fibonacci-sphere surface, appended
  *  to `parent` in the node's local px coordinate space. Positions/opacity are
@@ -278,7 +346,7 @@ function makeGlobe(parent: SVGGElement, radiusPx: number, color: string, count:
     const rr = Math.sqrt(Math.max(0, 1 - y * y))
     const phi = k * golden
     const dot = el('circle', {
-      r: (radiusPx * (0.06 + hash01(k) * 0.035)).toFixed(2),
+      r: (radiusPx * (0.06 + hashStr(String(k)) * 0.035)).toFixed(2),
       fill: color,
     })
     parent.appendChild(dot)
@@ -305,221 +373,382 @@ function renderGlobe(dots: GlobeDot[], radiusPx: number, spin: number, baseOpaci
   }
 }
 
-function buildScene() {
-  const svg = svgRef.value
-  if (!svg) return
-  clearScene()
+/* --------------------------- scene assembly ------------------------- */
 
+function ensureLayers() {
+  if (nodesLayer) return
+  const svg = svgRef.value!
   ringsLayer = el('g')
   linksLayer = el('g')
   nodesLayer = el('g')
-  svg.appendChild(ringsLayer)
-  svg.appendChild(linksLayer)
-  svg.appendChild(nodesLayer)
+  svg.append(ringsLayer, linksLayer, nodesLayer)
+}
 
-  const peerNodes = props.nodes.filter(n => !n.is_self)
-  const selfNode = props.nodes.find(n => n.is_self)
-
-  // Orbit guide rings — drawn per-frame as projected ellipses; they are what
-  // makes the plane read as 3D. Only draw rings that hold peers.
-  const usedRings = new Set(peerNodes.map((_, i) => ringFor(i, peerNodes.length).ring))
-  for (const r of usedRings) {
-    const radius = 1 + r * 0.65
-    const p = el('path', {
-      fill: 'none',
-      stroke: motionTokens.color.lineFaint,
-      'stroke-width': '1',
-      opacity: '0',
-    })
-    ringsLayer.appendChild(p)
-    ringPaths.push({ el: p, radius })
-  }
-
-  // Self node: a BLACK point-cloud globe — dark dots over a soft light
-  // backing disc so it reads against the dark glass, with the brand-orange
-  // sonar pulse marking "you".
-  if (selfNode) {
-    const g = el('g', { cursor: 'pointer' }) as SVGGElement
-    const r = nodeRadius(selfNode)
-    selfRadiusPx = r
-    const halo = el('circle', { r: String(r * 2.2), fill: '#ffffff', opacity: '0.07' })
-    const pulse = el('circle', { r: String(r), fill: 'none', stroke: motionTokens.color.accent, 'stroke-width': '1.5', opacity: '0.6' })
-    const backing = el('circle', { r: String(r * 1.04), fill: '#ffffff', opacity: '0.16' })
-    const rim = el('circle', { r: String(r * 1.04), fill: 'none', stroke: '#ffffff', 'stroke-width': '1', 'stroke-opacity': '0.45' })
-    g.append(halo, pulse, backing, rim)
-    selfDots = makeGlobe(g, r, '#000000', 56)
-    const label = el('text', {
-      dy: String(r + 18),
-      'text-anchor': 'middle',
-      class: 'nm-label',
-      fill: motionTokens.color.textPrimary,
-      'font-size': '12px',
-      'font-weight': '600',
-      'font-family': "'Avenir Next', system-ui, sans-serif",
-    })
-    label.textContent = selfNode.label || 'This node'
-    const title = el('title')
-    title.textContent = `${selfNode.did}\nThis node`
-    g.append(label, title)
-    g.addEventListener('click', () => emit('select', selfNode.did))
-    nodesLayer.appendChild(g)
-    selfEl = g
-
-    // Sonar pulse — repeats forever, cheap (2 attrs on one circle)
-    if (!staticMode) {
-      gsap.fromTo(pulse,
-        { attr: { r: r } , opacity: 0.55 },
-        { attr: { r: r * 2.6 }, opacity: 0, duration: 2.4, repeat: -1, ease: 'sine.out', repeatDelay: 0.6 })
-    }
-  }
-
-  // Peers + their link back to self
-  peerNodes.forEach((node, i) => {
-    const { ring, indexInRing, countInRing } = ringFor(i, peerNodes.length)
-    const ringRadius = 1 + ring * 0.65
-    // Even spacing around the ring, offset per ring so rings interleave
-    const angle = (indexInRing / countInRing) * Math.PI * 2 + ring * 0.5
-    const r = nodeRadius(node)
-    const color = trustColor(node)
-
-    const g = el('g', { cursor: 'pointer' }) as SVGGElement
-    const halo = el('circle', { r: String(r * 1.9), fill: color, opacity: node.online ? '0.12' : '0.04' })
-    // Faint limb outline sells the sphere silhouette; offline nodes get the
-    // dashed ring + dim dots instead of a solid fill change.
-    const outline = el('circle', {
-      r: String(r),
-      fill: 'none',
-      stroke: color,
-      'stroke-width': '1',
-      'stroke-opacity': node.online ? '0.35' : '0.3',
-      'stroke-dasharray': node.online ? 'none' : '3 3',
-    })
-    const core = el('circle', { r: String(r * 0.4), fill: color, opacity: node.online ? '0.22' : '0.08' })
-    g.append(halo, outline, core)
-    const dotCount = Math.max(22, Math.round(r * 3.4))
-    const dots = makeGlobe(g, r, color, dotCount)
-    const label = el('text', {
-      dy: String(r + 15),
-      'text-anchor': 'middle',
-      class: 'nm-label',
-      fill: motionTokens.color.textSecondary,
-      'font-size': '11px',
-      'font-family': "'Avenir Next', system-ui, sans-serif",
-    })
-    label.textContent = node.label
-    const title = el('title')
-    title.textContent = `${node.did}\nApps: ${node.app_count}\n${node.online ? 'Online' : 'Offline'}`
-    g.append(label, title)
-    g.addEventListener('click', () => emit('select', node.did))
-    nodesLayer!.appendChild(g)
-
-    const hasLink = props.links.some(l => l.target === node.did || l.source === node.did)
-    let linkEl: SVGPathElement | null = null
-    if (hasLink) {
-      linkEl = el('path', {
-        fill: 'none',
-        stroke: node.online ? color : motionTokens.color.neutral,
-        'stroke-width': '1.5',
-        'stroke-opacity': node.online ? '0.35' : '0.15',
-        'stroke-dasharray': node.online ? 'none' : '5 4',
-      })
-      linksLayer!.appendChild(linkEl)
-    }
-
-    peers.push({
-      node,
-      angle,
-      ring,
-      ringRadius,
-      yJitter: (hash01(i) - 0.5) * 0.22,
-      bobPhase: hash01(i + 100) * Math.PI * 2,
-      p: 0,
-      el: g,
-      label,
-      linkEl,
-      dots,
-      radiusPx: r,
-      dotBaseOpacity: node.online ? 0.95 : 0.35,
-      depth: 0,
-    })
+function createSelf(node: MapNode) {
+  // Self: a BLACK point-cloud globe — dark dots over a soft light backing
+  // disc so it reads against the dark glass, with the brand-orange sonar
+  // pulse marking "you".
+  const g = el('g', { cursor: 'pointer' }) as SVGGElement
+  const r = nodeRadius(node)
+  const halo = el('circle', { r: String(r * 2.2), fill: '#ffffff', opacity: '0.07' })
+  const pulse = el('circle', { r: String(r), fill: 'none', stroke: motionTokens.color.accent, 'stroke-width': '1.5', opacity: '0.6' })
+  const backing = el('circle', { r: String(r * 1.04), fill: '#ffffff', opacity: '0.16' })
+  const rim = el('circle', { r: String(r * 1.04), fill: 'none', stroke: '#ffffff', 'stroke-width': '1', 'stroke-opacity': '0.45' })
+  g.append(halo, pulse, backing, rim)
+  const dots = makeGlobe(g, r, '#000000', 56)
+  const label = el('text', {
+    dy: String(r + 18), 'text-anchor': 'middle', class: 'nm-label',
+    fill: motionTokens.color.textPrimary, 'font-size': '12px', 'font-weight': '600', 'font-family': FONT,
   })
+  label.textContent = node.label || 'This node'
+  const title = el('title')
+  title.textContent = `${node.did}\nThis node`
+  g.append(label, title)
+  g.addEventListener('click', () => emit('select', node.did))
+  nodesLayer!.appendChild(g)
+  selfVis = { did: node.did, el: g, label, pulseEl: pulse, dots, radiusPx: r }
 
-  // Inbound peer requests: blinking yellow globes on an orbit OUTSIDE the
-  // peers — visually "knocking at the door", linked to self by a dotted line.
-  const reqs = props.requests ?? []
-  if (reqs.length) {
-    const maxPeerRingRadius = peerNodes.length
-      ? 1 + ringFor(peerNodes.length - 1, peerNodes.length).ring * 0.65
-      : 1
-    const reqRing = maxPeerRingRadius + 0.65
-    const color = motionTokens.color.pending
-    const ringEl = el('path', {
-      fill: 'none',
-      stroke: color,
-      'stroke-opacity': '0.12',
-      'stroke-width': '1',
-      'stroke-dasharray': '4 5',
-      opacity: '0',
-    })
-    ringsLayer.appendChild(ringEl)
-    ringPaths.push({ el: ringEl, radius: reqRing })
-
-    reqs.forEach((req, i) => {
-      const r = 7.5
-      const g = el('g', { cursor: 'pointer' }) as SVGGElement
-      const halo = el('circle', { r: String(r * 2), fill: color, opacity: '0.14' })
-      const outline = el('circle', {
-        r: String(r), fill: 'none', stroke: color,
-        'stroke-width': '1', 'stroke-opacity': '0.5', 'stroke-dasharray': '3 3',
-      })
-      const coreGlow = el('circle', { r: String(r * 0.4), fill: color, opacity: '0.25' })
-      g.append(halo, outline, coreGlow)
-      const dots = makeGlobe(g, r, color, 24)
-      const label = el('text', {
-        dy: String(r + 15),
-        'text-anchor': 'middle',
-        class: 'nm-label',
-        fill: motionTokens.color.textSecondary,
-        'font-size': '11px',
-        'font-family': "'Avenir Next', system-ui, sans-serif",
-      })
-      label.textContent = req.label
-      const title = el('title')
-      title.textContent = `Peer request from ${req.label}`
-      g.append(label, title)
-      // stopPropagation: the same click must not bubble to the container's
-      // popover-dismiss handler and immediately close what it just opened
-      g.addEventListener('click', (e) => { e.stopPropagation(); activeRequest.value = req })
-      nodesLayer!.appendChild(g)
-      const linkEl = el('path', {
-        fill: 'none', stroke: color,
-        'stroke-width': '1.2', 'stroke-opacity': '0.3', 'stroke-dasharray': '2 5',
-      })
-      linksLayer!.appendChild(linkEl)
-
-      requestVis.push({
-        req,
-        angle: (i / reqs.length) * Math.PI * 2 + 0.35,
-        ringRadius: reqRing,
-        yJitter: (hash01(i + 40) - 0.5) * 0.2,
-        bobPhase: hash01(i + 140) * Math.PI * 2,
-        p: 0,
-        blinking: true,
-        deathScale: 1,
-        el: g,
-        outline,
-        halo,
-        coreGlow,
-        label,
-        linkEl,
-        dots,
-        radiusPx: r,
-        depth: 0,
-      })
-    })
+  if (!staticMode) {
+    gsap.fromTo(pulse,
+      { attr: { r }, opacity: 0.55 },
+      { attr: { r: r * 2.6 }, opacity: 0, duration: 2.4, repeat: -1, ease: 'sine.out', repeatDelay: 0.6 })
   }
 }
 
+/** Per-peer static attrs derived from node data — split out so online/trust
+ *  changes can restyle in place. */
+function stylePeerDom(vis: PeerVis) {
+  const { node, el: g } = vis
+  const color = trustColor(node)
+  const children = g.children
+  const halo = children[0] as SVGCircleElement
+  const outline = children[1] as SVGCircleElement
+  const core = children[2] as SVGCircleElement
+  halo.setAttribute('fill', color)
+  halo.setAttribute('opacity', node.online ? '0.12' : '0.04')
+  outline.setAttribute('stroke', color)
+  outline.setAttribute('stroke-opacity', node.online ? '0.35' : '0.3')
+  if (node.online) outline.removeAttribute('stroke-dasharray')
+  else outline.setAttribute('stroke-dasharray', '3 3')
+  core.setAttribute('fill', color)
+  core.setAttribute('opacity', node.online ? '0.22' : '0.08')
+  for (const d of vis.dots) d.el.setAttribute('fill', color)
+  vis.dotBaseOpacity = node.online ? 0.95 : 0.35
+  if (vis.linkEl) {
+    vis.linkEl.setAttribute('stroke', node.online ? color : motionTokens.color.neutral)
+    vis.linkEl.setAttribute('stroke-opacity', node.online ? '0.35' : '0.15')
+    if (node.online) vis.linkEl.removeAttribute('stroke-dasharray')
+    else vis.linkEl.setAttribute('stroke-dasharray', '5 4')
+  }
+}
+
+function createPeer(node: MapNode, slot: { angle: number; ringRadius: number }, hasLink: boolean): PeerVis {
+  const r = nodeRadius(node)
+  const color = trustColor(node)
+  const g = el('g', { cursor: 'pointer' }) as SVGGElement
+  g.append(
+    el('circle', { r: String(r * 1.9) }), // halo — styled below
+    el('circle', { r: String(r), fill: 'none', stroke: color, 'stroke-width': '1' }), // outline
+    el('circle', { r: String(r * 0.4) }), // core glow
+  )
+  const dots = makeGlobe(g, r, color, Math.max(22, Math.round(r * 3.4)))
+  const label = el('text', {
+    dy: String(r + 15), 'text-anchor': 'middle', class: 'nm-label',
+    fill: motionTokens.color.textSecondary, 'font-size': '11px', 'font-family': FONT,
+  })
+  label.textContent = node.label
+  const title = el('title')
+  title.textContent = `${node.did}\nApps: ${node.app_count}\n${node.online ? 'Online' : 'Offline'}`
+  g.append(label, title)
+  g.addEventListener('click', () => emit('select', node.did))
+  nodesLayer!.appendChild(g)
+
+  let linkEl: SVGPathElement | null = null
+  if (hasLink) {
+    linkEl = el('path', { fill: 'none', 'stroke-width': '1.5' })
+    linksLayer!.appendChild(linkEl)
+  }
+
+  const vis: PeerVis = {
+    node,
+    angle: slot.angle,
+    ringRadius: slot.ringRadius,
+    yJitter: (hashStr(node.did) - 0.5) * 0.22,
+    bobPhase: hashStr(node.did + 'p') * Math.PI * 2,
+    p: 0,
+    dying: false,
+    el: g,
+    label,
+    linkEl,
+    dots,
+    radiusPx: r,
+    dotBaseOpacity: 0.95,
+    depth: 0,
+  }
+  stylePeerDom(vis)
+  peers.push(vis)
+  peerMap.set(node.did, vis)
+  return vis
+}
+
+function removeVisDom(elm: SVGGElement, linkEl: SVGPathElement | null) {
+  elm.remove()
+  linkEl?.remove()
+}
+
+function killPeer(vis: PeerVis) {
+  peerMap.delete(vis.node.did)
+  vis.dying = true
+  gsap.killTweensOf(vis)
+  const finish = () => {
+    removeVisDom(vis.el, vis.linkEl)
+    peers = peers.filter(p => p !== vis)
+  }
+  if (staticMode) finish()
+  else gsap.to(vis, { p: 0, duration: 0.35, ease: 'power2.in', onComplete: finish })
+}
+
+function createRequest(req: MapRequest, slot: { angle: number; ringRadius: number }): RequestVis {
+  const r = 7.5
+  const color = motionTokens.color.pending
+  const g = el('g', { cursor: 'pointer' }) as SVGGElement
+  const halo = el('circle', { r: String(r * 2), fill: color, opacity: '0.14' })
+  const outline = el('circle', {
+    r: String(r), fill: 'none', stroke: color,
+    'stroke-width': '1', 'stroke-opacity': '0.5', 'stroke-dasharray': '3 3',
+  })
+  const coreGlow = el('circle', { r: String(r * 0.4), fill: color, opacity: '0.25' })
+  g.append(halo, outline, coreGlow)
+  const dots = makeGlobe(g, r, color, 24)
+  const label = el('text', {
+    dy: String(r + 15), 'text-anchor': 'middle', class: 'nm-label',
+    fill: motionTokens.color.textSecondary, 'font-size': '11px', 'font-family': FONT,
+  })
+  label.textContent = req.label
+  const title = el('title')
+  title.textContent = `Peer request from ${req.label}`
+  g.append(label, title)
+  // stopPropagation: the same click must not bubble to the container's
+  // popover-dismiss handler and immediately close what it just opened
+  g.addEventListener('click', (e) => { e.stopPropagation(); activeRequest.value = req })
+  nodesLayer!.appendChild(g)
+  const linkEl = el('path', {
+    fill: 'none', stroke: color,
+    'stroke-width': '1.2', 'stroke-opacity': '0.3', 'stroke-dasharray': '2 5',
+  })
+  linksLayer!.appendChild(linkEl)
+
+  const vis: RequestVis = {
+    req,
+    angle: slot.angle,
+    // Loose hover around the waiting-room orbit, not a tidy ring — these
+    // nodes are outside the federation until accepted.
+    ringRadius: slot.ringRadius + (hashStr(req.id + 'r') - 0.5) * 0.24,
+    yJitter: (hashStr(req.id) - 0.5) * 0.2,
+    bobPhase: hashStr(req.id + 'p') * Math.PI * 2,
+    p: 0,
+    blinking: true,
+    deathScale: 1,
+    decided: false,
+    dying: false,
+    el: g,
+    outline,
+    halo,
+    coreGlow,
+    label,
+    linkEl,
+    dots,
+    radiusPx: r,
+    depth: 0,
+  }
+  requestVis.push(vis)
+  reqMap.set(req.id, vis)
+  return vis
+}
+
+function killRequest(vis: RequestVis) {
+  reqMap.delete(vis.req.id)
+  vis.dying = true
+  if (activeRequest.value?.id === vis.req.id) activeRequest.value = null
+  gsap.killTweensOf(vis)
+  const finish = () => {
+    removeVisDom(vis.el, vis.linkEl)
+    requestVis = requestVis.filter(r => r !== vis)
+  }
+  // Decided requests already played their bespoke exit (pop / join morph) —
+  // just clear them fast once the backend confirms.
+  if (staticMode || vis.decided) gsap.to(vis, { p: 0, duration: 0.15, onComplete: finish })
+  else gsap.to(vis, { p: 0, duration: 0.3, ease: 'power2.in', onComplete: finish })
+}
+
+/** Reconcile the orbit guide rings with the desired set (crossfade). */
+function syncRings(desired: { radius: number; kind: 'peer' | 'request' }[]) {
+  const key = (radius: number, kind: string) => `${kind}:${radius.toFixed(2)}`
+  const want = new Map(desired.map(d => [key(d.radius, d.kind), d]))
+  const have = new Map(ringPaths.map(r => [key(r.radius, r.kind), r]))
+
+  for (const [k, spec] of want) {
+    if (have.has(k)) continue
+    const p = spec.kind === 'peer'
+      ? el('path', { fill: 'none', opacity: '0', stroke: motionTokens.color.lineFaint, 'stroke-width': '1' })
+      : el('path', { fill: 'none', opacity: '0', stroke: motionTokens.color.pending, 'stroke-opacity': '0.12', 'stroke-width': '1', 'stroke-dasharray': '4 5' })
+    ringsLayer!.appendChild(p)
+    const vis: RingVis = { el: p, radius: spec.radius, kind: spec.kind }
+    ringPaths.push(vis)
+    if (introPlayed) {
+      if (staticMode) p.setAttribute('opacity', '1')
+      else gsap.to(p, { opacity: 1, duration: 0.6, ease: motionTokens.ease.inOut })
+    }
+  }
+  for (const [k, ring] of have) {
+    if (want.has(k)) continue
+    ringPaths = ringPaths.filter(r => r !== ring)
+    if (staticMode) ring.el.remove()
+    else gsap.to(ring.el, { opacity: 0, duration: 0.4, onComplete: () => ring.el.remove() })
+  }
+}
+
+/** THE reconciler: diff props against the live scene and animate the deltas.
+ *  Never wipes the SVG — in-flight animations keep their targets. */
+function applyGraph() {
+  ensureLayers()
+
+  const peerNodes = props.nodes
+    .filter(n => !n.is_self)
+    .sort((a, b) => (a.did < b.did ? -1 : a.did > b.did ? 1 : 0))
+  const selfNode = props.nodes.find(n => n.is_self)
+
+  // --- self ---
+  if (selfNode && !selfVis) {
+    createSelf(selfNode)
+    if (introPlayed && selfState.p < 1) {
+      if (staticMode) selfState.p = 1
+      else gsap.to(selfState, { p: 1, duration: 0.55, ease: motionTokens.ease.arrive })
+    }
+  } else if (selfNode && selfVis && selfVis.label.textContent !== (selfNode.label || 'This node')) {
+    selfVis.label.textContent = selfNode.label || 'This node'
+  }
+
+  // --- peers ---
+  const seenDids = new Set<string>()
+  peerNodes.forEach((node, i) => {
+    seenDids.add(node.did)
+    const slot = peerSlot(i, peerNodes.length)
+    const hasLink = props.links.some(l => l.target === node.did || l.source === node.did)
+    const existing = peerMap.get(node.did)
+
+    if (!existing) {
+      const vis = createPeer(node, slot, hasLink)
+      if (introPlayed) {
+        if (staticMode) vis.p = 1
+        else gsap.to(vis, { p: 1, duration: 0.6, ease: motionTokens.ease.arrive })
+      }
+      return
+    }
+
+    // Structural change (trust colour, size, link gained/lost) → rebuild this
+    // one node's DOM in place, preserving its arrival progress and slot.
+    const structural = existing.node.trust_level !== node.trust_level
+      || nodeRadius(node) !== existing.radiusPx
+      || (existing.linkEl !== null) !== hasLink
+    if (structural) {
+      const keepP = existing.p
+      const keepAngle = existing.angle
+      const keepRing = existing.ringRadius
+      gsap.killTweensOf(existing)
+      removeVisDom(existing.el, existing.linkEl)
+      peers = peers.filter(p => p !== existing)
+      peerMap.delete(node.did)
+      const vis = createPeer(node, slot, hasLink)
+      vis.p = keepP
+      vis.angle = keepAngle
+      vis.ringRadius = keepRing
+    } else {
+      // Cheap in-place updates
+      existing.node = node
+      if (existing.label.textContent !== node.label) existing.label.textContent = node.label
+      const title = existing.el.querySelector('title')
+      if (title) title.textContent = `${node.did}\nApps: ${node.app_count}\n${node.online ? 'Online' : 'Offline'}`
+      stylePeerDom(existing)
+    }
+
+    // Slot drift (another peer joined/left) → glide the short way around
+    const vis = peerMap.get(node.did)!
+    if (Math.abs(vis.ringRadius - slot.ringRadius) > 1e-3
+      || Math.abs(nearestAngle(vis.angle, slot.angle) - vis.angle) > 1e-3) {
+      if (staticMode) {
+        vis.angle = slot.angle
+        vis.ringRadius = slot.ringRadius
+      } else {
+        gsap.to(vis, {
+          angle: nearestAngle(vis.angle, slot.angle),
+          ringRadius: slot.ringRadius,
+          duration: 0.7,
+          ease: motionTokens.ease.inOut,
+          overwrite: 'auto',
+        })
+      }
+    }
+  })
+  for (const [did, vis] of peerMap) {
+    if (!seenDids.has(did)) killPeer(vis)
+  }
+
+  // --- requests (waiting-room orbit, outside the peers) ---
+  const reqs = [...(props.requests ?? [])].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  const reqRing = requestRingRadius(peerNodes.length)
+  const seenReqs = new Set<string>()
+  reqs.forEach((req, i) => {
+    seenReqs.add(req.id)
+    const slot = { angle: (i / reqs.length) * Math.PI * 2 + 0.35, ringRadius: reqRing }
+    const existing = reqMap.get(req.id)
+    if (!existing) {
+      const vis = createRequest(req, slot)
+      if (introPlayed) {
+        if (staticMode) vis.p = 1
+        else gsap.to(vis, { p: 1, duration: 0.6, ease: motionTokens.ease.arrive })
+      }
+      return
+    }
+    existing.req = req
+    if (existing.label.textContent !== req.label) existing.label.textContent = req.label
+    if (!existing.decided) {
+      const targetRing = reqRing + (hashStr(req.id + 'r') - 0.5) * 0.24
+      if (Math.abs(existing.ringRadius - targetRing) > 1e-3
+        || Math.abs(nearestAngle(existing.angle, slot.angle) - existing.angle) > 1e-3) {
+        if (staticMode) {
+          existing.angle = slot.angle
+          existing.ringRadius = targetRing
+        } else {
+          gsap.to(existing, {
+            angle: nearestAngle(existing.angle, slot.angle),
+            ringRadius: targetRing,
+            duration: 0.7,
+            ease: motionTokens.ease.inOut,
+            overwrite: 'auto',
+          })
+        }
+      }
+    }
+  })
+  for (const [id, vis] of reqMap) {
+    if (!seenReqs.has(id)) killRequest(vis)
+  }
+
+  // --- orbit guide rings ---
+  const desiredRings: { radius: number; kind: 'peer' | 'request' }[] = []
+  const usedPeerRings = new Set<number>()
+  peerNodes.forEach((_, i) => usedPeerRings.add(peerSlot(i, peerNodes.length).ring))
+  for (const r of usedPeerRings) desiredRings.push({ radius: 1 + r * 0.65, kind: 'peer' })
+  if (reqs.length) desiredRings.push({ radius: reqRing, kind: 'request' })
+  syncRings(desiredRings)
+
+  // --- re-fit to the (possibly new) outermost orbit ---
+  refit()
+}
+
+/* ------------------------------ render ------------------------------ */
+
 /** One frame: project every element through the camera and write attrs. */
 function render() {
   if (!width || !height) return
@@ -541,12 +770,12 @@ function render() {
   }
 
   // Self node at origin
-  if (selfEl) {
+  if (selfVis) {
     const pt = project(0, 0, 0)
     const s = pt.s * cam.zoom * selfState.p
-    selfEl.setAttribute('transform', `translate(${pt.x},${pt.y}) scale(${Math.max(s, 0.001)})`)
-    selfEl.setAttribute('opacity', String(selfState.p))
-    if (updateDots) renderGlobe(selfDots, selfRadiusPx, cam.rotY + elapsed * 0.22, 0.95)
+    selfVis.el.setAttribute('transform', `translate(${pt.x},${pt.y}) scale(${Math.max(s, 0.001)})`)
+    selfVis.el.setAttribute('opacity', String(selfState.p))
+    if (updateDots) renderGlobe(selfVis.dots, selfVis.radiusPx, cam.rotY + elapsed * 0.22, 0.95)
   }
 
   const origin = project(0, 0, 0)
@@ -584,7 +813,6 @@ function render() {
   }
 
   // Pending requests: same projection as peers, plus the attention blink
-  // (skipped once a decision animation has started or under reduced motion)
   for (const rv of requestVis) {
     const dist = rv.ringRadius * (1.9 - 0.9 * rv.p)
     const sway = staticMode ? 0 : Math.sin(elapsed * 0.55 + rv.bobPhase) * 0.04
@@ -605,13 +833,12 @@ function render() {
   }
 
   // Painter's order: farthest first so near nodes overlap far ones. The self
-  // node sits at z=0 (mid-plane) and takes part in the same sort, so peers
-  // orbiting in front genuinely pass over it. Only touch the DOM when the
-  // order actually changed.
+  // node sits at z=0 (mid-plane) and takes part in the same sort. Only touch
+  // the DOM when the order actually changed.
   if (nodesLayer && (peers.length > 0 || requestVis.length > 0)) {
     const drawables: { el: SVGGElement; depth: number }[] = peers.map(p => ({ el: p.el, depth: p.depth }))
     for (const rv of requestVis) drawables.push({ el: rv.el, depth: rv.depth })
-    if (selfEl) drawables.push({ el: selfEl, depth: 0 })
+    if (selfVis) drawables.push({ el: selfVis.el, depth: 0 })
     drawables.sort((a, b) => b.depth - a.depth)
     let dirty = false
     const children = nodesLayer.children
@@ -642,6 +869,26 @@ function detachTicker() {
 
 /* ----------------------------- intro ------------------------------ */
 
+/** Session flag: the long cinematic intro plays once per browser session;
+ *  revisits (component remounts on every route entry) get a shorter, lighter
+ *  entrance that doesn't fight the route transition. */
+function sessionIntroSeen(): boolean {
+  try { return sessionStorage.getItem('nm-intro-seen') === '1' } catch { return false }
+}
+function markSessionIntroSeen() {
+  try { sessionStorage.setItem('nm-intro-seen', '1') } catch { /* private mode */ }
+}
+
+function startIntroIfReady(force = false) {
+  if (introPlayed || !built) return
+  // Wait for the self node (async DID fetch) so the intro includes the centre
+  // and its links — unless the fallback timer forces the show to go on.
+  if (!selfVis && !force) return
+  introPlayed = true
+  if (introFallback) { clearTimeout(introFallback); introFallback = null }
+  playIntro()
+}
+
 function playIntro() {
   intro?.kill()
   if (staticMode) {
@@ -653,37 +900,47 @@ function playIntro() {
     for (const rv of requestVis) rv.p = 1
     for (const r of ringPaths) r.el.setAttribute('opacity', '1')
     render()
+    flushPendingGraph()
     return
   }
 
-  cam.rotY = -1.1
-  cam.zoom = 0.82
+  const short = sessionIntroSeen()
+  markSessionIntroSeen()
+  const T = short
+    ? { rotY: -0.35, zoom: 0.94, delay: 0.05, dolly: 0.7, self: 0.4, rings: 0.5, node: 0.5, stagger: 0.035, nodesAt: 0.15, reqsAt: 0.3 }
+    : { rotY: -1.1, zoom: 0.82, delay: 0.2, dolly: motionTokens.duration.cinematic, self: 0.55, rings: 0.9, node: 0.7, stagger: 0.07, nodesAt: 0.45, reqsAt: 0.7 }
+
+  cam.rotY = T.rotY
+  cam.zoom = T.zoom
   selfState.p = 0
   for (const p of peers) p.p = 0
+  for (const rv of requestVis) rv.p = 0
 
-  intro = gsap.timeline()
+  intro = gsap.timeline({ delay: T.delay, onComplete: flushPendingGraph })
   intro
-    .to(cam, { rotY: 0, zoom: 1, duration: motionTokens.duration.cinematic, ease: motionTokens.ease.out }, 0)
-    .to(selfState, { p: 1, duration: 0.55, ease: motionTokens.ease.arrive }, 0.15)
-    .to(ringPaths.map(r => r.el), { opacity: 1, duration: 0.9, ease: motionTokens.ease.inOut, stagger: 0.12 }, 0.3)
+    .to(cam, { rotY: 0, zoom: 1, duration: T.dolly, ease: motionTokens.ease.out }, 0)
+    .to(selfState, { p: 1, duration: T.self, ease: motionTokens.ease.arrive }, T.nodesAt * 0.4)
+  if (ringPaths.length) {
+    intro.to(ringPaths.map(r => r.el), { opacity: 1, duration: T.rings, ease: motionTokens.ease.inOut, stagger: 0.1 }, 0.25)
+  }
   if (peers.length) {
     intro.to(peers, {
-      p: 1,
-      duration: 0.7,
-      ease: motionTokens.ease.arrive,
-      stagger: { each: 0.07, from: 'random' },
-    }, 0.45)
+      p: 1, duration: T.node, ease: motionTokens.ease.arrive,
+      stagger: { each: T.stagger, from: 'random' },
+    }, T.nodesAt)
   }
   if (requestVis.length) {
-    intro.to(requestVis, {
-      p: 1,
-      duration: 0.7,
-      ease: motionTokens.ease.arrive,
-      stagger: 0.08,
-    }, 0.7)
+    intro.to(requestVis, { p: 1, duration: T.node, ease: motionTokens.ease.arrive, stagger: 0.08 }, T.reqsAt)
   }
 }
 
+/** Graph updates that land mid-intro are deferred here and applied once. */
+function flushPendingGraph() {
+  if (!pendingGraphUpdate) return
+  pendingGraphUpdate = false
+  applyGraph()
+}
+
 /* ----------------------- request popover ------------------------- */
 
 const activeRequest = ref<MapRequest | null>(null)
@@ -692,9 +949,11 @@ function decideRequest(decision: 'approve' | 'reject') {
   const req = activeRequest.value
   if (!req) return
   activeRequest.value = null
-  const rv = requestVis.find(v => v.req.id === req.id)
+  const rv = reqMap.get(req.id)
   if (rv && !staticMode) {
     rv.blinking = false
+    rv.decided = true
+    gsap.killTweensOf(rv)
     if (decision === 'reject') {
       // Pop out of existence: a quick swell, then collapse — the dotted
       // link dies with the node.
@@ -703,7 +962,8 @@ function decideRequest(decision: 'approve' | 'reject') {
         .to(rv, { deathScale: 0.001, p: 0.0001, duration: 0.32, ease: 'back.in(2.4)' })
     } else {
       // Join: green burst ring, the point cloud and link morph to the
-      // trusted colour, and the globe glides inward onto the peer orbit.
+      // trusted colour, and the globe glides in from the waiting-room orbit
+      // onto the peer rings.
       const trusted = motionTokens.color.trusted
       const burst = el('circle', {
         r: String(rv.radiusPx), fill: 'none',
@@ -718,6 +978,8 @@ function decideRequest(decision: 'approve' | 'reject') {
       gsap.to([rv.outline, rv.linkEl], { attr: { stroke: trusted }, duration: 0.6, ease: motionTokens.ease.inOut })
       gsap.to(rv, { ringRadius: 1, duration: 0.9, ease: motionTokens.ease.inOut, delay: 0.15 })
     }
+  } else if (rv) {
+    rv.decided = true
   }
   if (decision === 'approve') emit('approve', req.id)
   else emit('reject', req.id)
@@ -746,8 +1008,8 @@ function onPointerDown(e: PointerEvent) {
   dragging = true
   lastX = e.clientX
   dragVel = 0
-  dragDistance = 0
-  spinTween?.kill()
+  for (const t of spinTween) t.kill()
+  spinTween = []
   // Deliberately NO setPointerCapture: capture retargets pointerup to the
   // container, which suppresses the browser's click synthesis on child
   // elements — it silently killed node taps and the 2D/3D toggle. Drag
@@ -781,10 +1043,10 @@ function onPointerUp(_e: PointerEvent) {
   // Inertia: carry the fling velocity, then settle to a full stop — the
   // scene never idle-orbits on its own.
   cam.spin = Math.max(-3, Math.min(3, dragVel))
-  spinTween = gsap.to(cam, { spin: 0, duration: 1.4, ease: 'power2.out' })
+  spinTween = [gsap.to(cam, { spin: 0, duration: 1.4, ease: 'power2.out' })]
 }
 
-/* ----------------------------- lifecycle --------------------------- */
+/* --------------------------- fit & modes --------------------------- */
 
 /** Auto-fit for a given projection: sample the outermost orbit through the
  *  camera math (rotation-invariant — a ring about the Y axis projects
@@ -793,7 +1055,10 @@ function onPointerUp(_e: PointerEvent) {
  *  Pure with respect to tilt/persp so a mode toggle can compute its target
  *  fit and tween towards it. */
 function computeFit(tilt: number, perspVal: number): { unit: number; centerY: number } {
-  const maxRing = ringPaths.length ? Math.max(...ringPaths.map(r => r.radius)) : 1
+  let maxRing = 1
+  for (const r of ringPaths) maxRing = Math.max(maxRing, r.radius)
+  // Requests hover loosely up to ~0.12 beyond their guide ring
+  if (ringPaths.some(r => r.kind === 'request')) maxRing += 0.15
   const ct = Math.cos(tilt), st = Math.sin(tilt)
   let maxAbsX = 0
   let yMin = Infinity
@@ -822,6 +1087,22 @@ function computeFit(tilt: number, perspVal: number): { unit: number; centerY: nu
   return { unit: u, centerY: marginTop + bandH / 2 - ((yMax + yMin) / 2) * u }
 }
 
+/** Re-fit after a graph change (e.g. the outermost orbit appeared/vanished).
+ *  Tweens once the scene is live so the reframe glides instead of jumping. */
+function refit() {
+  if (!modeInitialized) return
+  const m = MODES[viewMode.value]
+  const target = computeFit(m.tilt, m.persp)
+  if (Math.abs(target.unit - fit.unit) < 0.5 && Math.abs(target.centerY - fit.centerY) < 0.5) return
+  gsap.killTweensOf(fit)
+  if (introPlayed && !staticMode) {
+    gsap.to(fit, { ...target, duration: 0.6, ease: motionTokens.ease.inOut })
+  } else {
+    fit.unit = target.unit
+    fit.centerY = target.centerY
+  }
+}
+
 /** Snap (or tween, via setMode) the camera + fit to the given mode. */
 function applyMode(mode: MapMode, animate: boolean) {
   const target = MODES[mode]
@@ -850,60 +1131,69 @@ function setMode(mode: MapMode) {
   applyMode(mode, true)
 }
 
+/* ----------------------------- lifecycle --------------------------- */
+
 function measure() {
   const c = containerRef.value
   if (!c) return
   width = c.clientWidth
   height = c.clientHeight
   svgRef.value?.setAttribute('viewBox', `0 0 ${width} ${height}`)
-
-  // First measurement decides the default projection: saved preference wins,
-  // otherwise portrait containers (phone/companion) open in the flat 2D view.
-  if (!modeInitialized) {
-    modeInitialized = true
-    let saved: string | null = null
-    try { saved = localStorage.getItem('federation-map-projection') } catch { /* private mode */ }
-    viewMode.value = saved === '2d' || saved === '3d' ? saved : (height > width ? '2d' : '3d')
+  // Zero-size means layout hasn't happened yet (mid route transition) —
+  // building now would compute a garbage fit. The observer will call again.
+  if (width === 0 || height === 0) return
+  if (!built) {
+    initialBuild()
+    return
   }
   // Resize: snap to the current mode's fit (no tween — tracks the drag)
   applyMode(viewMode.value, false)
 }
 
+function initialBuild() {
+  staticMode = prefersReducedMotion()
+  built = true
+  applyGraph()
+
+  // First measurement decides the default projection: saved preference wins,
+  // otherwise portrait containers (phone/companion) open in the flat 2D view.
+  modeInitialized = true
+  let saved: string | null = null
+  try { saved = localStorage.getItem('federation-map-projection') } catch { /* private mode */ }
+  viewMode.value = saved === '2d' || saved === '3d' ? saved : (height > width ? '2d' : '3d')
+  applyMode(viewMode.value, false)
+
+  if (staticMode) {
+    introPlayed = true
+    playIntro() // static branch: everything lands in place
+    return
+  }
+  attachTicker()
+  startIntroIfReady()
+  if (!introPlayed) {
+    introFallback = setTimeout(() => startIntroIfReady(true), 1200)
+  }
+}
+
 const graphSignature = computed(() => JSON.stringify({
   nodes: props.nodes.map(n => [n.did, n.label, n.trust_level, n.online, n.app_count, n.is_self]),
   links: props.links.map(l => [l.source, l.target]),
   requests: (props.requests ?? []).map(r => [r.id, r.label]),
 }))
 
-let hasIntroPlayed = false
-
-function rebuild(replayIntro: boolean) {
-  staticMode = prefersReducedMotion()
-  buildScene()
-  measure()
-  if (replayIntro || !hasIntroPlayed) {
-    playIntro()
-    hasIntroPlayed = true
-  } else {
-    // Data refresh mid-session: pop new elements in without the full dolly
-    selfState.p = 1
-    if (staticMode) {
-      for (const p of peers) p.p = 1
-      for (const rv of requestVis) rv.p = 1
-    } else {
-      gsap.to(peers, { p: 1, duration: 0.5, ease: motionTokens.ease.arrive, stagger: 0.03 })
-      if (requestVis.length) {
-        gsap.to(requestVis, { p: 1, duration: 0.5, ease: motionTokens.ease.arrive, stagger: 0.05 })
-      }
-    }
-    for (const r of ringPaths) r.el.setAttribute('opacity', '1')
-    render()
+watch(graphSignature, () => {
+  if (!built) return // initial build reads the latest props when size arrives
+  if (intro?.isActive()) {
+    // Never reconcile under a running intro — that's how tween targets used
+    // to get orphaned and parts of the intro went missing.
+    pendingGraphUpdate = true
+    return
   }
-  if (!staticMode) attachTicker()
-}
+  applyGraph()
+  startIntroIfReady() // covers the late-arriving self node
+})
 
 onMounted(() => {
-  rebuild(true)
   resizeObserver = new ResizeObserver(() => measure())
   if (containerRef.value) {
     resizeObserver.observe(containerRef.value)
@@ -919,9 +1209,14 @@ onMounted(() => {
 
 onUnmounted(() => {
   detachTicker()
+  if (introFallback) { clearTimeout(introFallback); introFallback = null }
   intro?.kill()
-  spinTween?.kill()
+  for (const t of spinTween) t.kill()
   for (const t of modeTween) t.kill()
+  gsap.killTweensOf([cam, fit, selfState])
+  for (const p of peers) gsap.killTweensOf(p)
+  for (const rv of requestVis) gsap.killTweensOf(rv)
+  if (selfVis) gsap.killTweensOf(selfVis.pulseEl)
   resizeObserver?.disconnect()
   window.removeEventListener('pointermove', onPointerMove)
   window.removeEventListener('pointerup', onPointerUp)
@@ -930,9 +1225,7 @@ onUnmounted(() => {
 
 // KeepAlive-aware: pause the 60fps loop while the tab is cached, resume on return
 onDeactivated(() => detachTicker())
-onActivated(() => { if (!staticMode) attachTicker() })
-
-watch(graphSignature, () => rebuild(false))
+onActivated(() => { if (built && !staticMode) attachTicker() })
 </script>
 
 <style scoped>
diff --git a/neode-ui/src/views/Federation.vue b/neode-ui/src/views/Federation.vue
index 3a451ff4..0eec7cba 100644
--- a/neode-ui/src/views/Federation.vue
+++ b/neode-ui/src/views/Federation.vue
@@ -339,7 +339,13 @@ function onMapSelect(did: string) {
   if (node) selectedNode.value = node
 }
 
-const selfDid = ref('')
+/** Seeded from the cached DID so the map's centre node (and its links) exist
+ *  on the very first frame; the authoritative fetch in onMounted refreshes it
+ *  and re-caches. Without this the intro raced the RPC and often played with
+ *  no centre. */
+const selfDid = ref<string>((() => {
+  try { return localStorage.getItem('neode_did') || '' } catch { return '' }
+})())
 
 const mapNodes = computed(() => {
   const result = []
@@ -819,6 +825,7 @@ onMounted(async () => {
   try {
     const result = await rpcClient.getNodeDid()
     selfDid.value = result.did
+    try { localStorage.setItem('neode_did', result.did) } catch { /* private mode */ }
   } catch {
     // Self DID not available
   }