feat(orchestrator): S2 agent and node popups with leader line, node search

Requirement 001 phase 6, S2:

- Agent popup: a click on an agent opens one fading <dialog> with face,
  name, earlier names, offices, tasks, claims, subagents, history and
  the composer; Escape or a click outside closes it. The agent drawer
  and the Details side panel are gone.
- Node popup: a click on a node in a graph view enlarges it and marks it
  red, and an SVG leader line ties it to the translucent popup; a click
  elsewhere restores the node. popup.js places the popup right, left,
  below or above the node, caps its height to the room there and
  returns the line.
- Search: in the 3D views a search field with suggestions replaces the
  list of every node, one chip per distinct label.
- Fit: body.fit now applies at every width; without the side panel the
  orbit view otherwise grew a page scrollbar at 390 px.
- Two page modules had silently shadowed each other's functions of the
  same name while this was built; test_no_two_page_modules_declare_the_same_function
  now guards that. Artifact ids carry NUL, which CSS.escape turns into
  U+FFFD, so the node lookup compares dataset values.

- Composer: a message goes to the agent whose popup it was written in.
  deliver() read the global ui.agent after awaiting the upload, so
  closing the popup or opening another agent during an upload sent the
  signed message to null or to the other agent (found by the security
  skeptic, present before, easier now that a backdrop click closes).

Limits: the 3D leader line is placed when the popup opens and does not
follow the camera while the layout settles; the search keeps the first
node per label, so a second repository's main branch is found in the
graph, not through the search.

Evidence: make test 667 OK, ruff and markdownlint clean
(/tmp/s2-make-test-1.log); e2e 19 OK in Chromium and Firefox at 1920,
1366 and 390 px, none skipped, rerun after the composer fix
(/tmp/s2-e2e-4.log); screenshots in /tmp/orchestrator-phase4-shots/;
MEDUSA 22 files, 6 findings (a "PLA" pattern in "templates", the UI
names openAgent and drawAgent) accepted after an independent skeptic
that also found no XSS or selector injection in the popup code.

🎯 Fix: 93 %
💥 Break: 4 %
💸 Cost: 100 %
⏱️ Time: –
🛡️ Security: 100 %
🏆 Score: 89
🚦 Gate: ✅ 90/5, cost and time <= 100, security 100 %

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/e2e/test_orchestrator_e2e.py

@@ -102,6 +102,8 @@ PROBE = """(async () => {@HELPERS@
     flows: all("#main .flow").map((flow) => flow.dataset.flow),
     flowEdges: all("#main svg.chart path.flow").map((path) => path.dataset.side),
     openWork: all("#main .open-work").length,
+    panel: all("#drawer, .drawer, #main aside, #main .panel, #main .graph-body").length,
+    nodeChips: all("#main .space-list, #main .chip[data-node]").length,
     wide: document.documentElement.scrollWidth > window.innerWidth + 1,
     tall: document.documentElement.scrollHeight > window.innerHeight,
   };
@@ -198,34 +200,123 @@ ACTIONS = """(async () => {@HELPERS@
   await sleep(900);
   document.querySelector('#main button.linkish[title^="Open "]').click();
   await sleep(500);
-  found.drawer = all("#drawer input[type=radio]").map((input) => [input.value, input.checked]);
-  found.drawerUnlabelled = all("#drawer svg.bi").map((svg) => svg.parentElement).filter((owner) => !text(owner) && !(owner.getAttribute("title") && owner.getAttribute("aria-label"))).length;
+  found.popup = all("#popup input[type=radio]").map((input) => [input.value, input.checked]);
+  found.popupUnlabelled = all("#popup svg.bi").map((svg) => svg.parentElement).filter((owner) => !text(owner) && !(owner.getAttribute("title") && owner.getAttribute("aria-label"))).length;
+  found.centred = [document.getElementById("popup").open, document.querySelector("#popup .leader line").getAttribute("display")];
   return found;
 })()""".replace("@HELPERS@", HELPERS)
+POPUPS = """
+  const dialog = document.getElementById("popup");
+  const box = dialog.querySelector(".popup-box");
+  const line = dialog.querySelector(".leader line");
+  const click = (target) => target.dispatchEvent(new MouseEvent("click", {bubbles: true, cancelable: true}));
+  const tint = document.createElement("i");
+  tint.style.color = "var(--alarm)";
+  document.body.append(tint);
+  const red = getComputedStyle(tint).color;
+  tint.remove();
+  const tall = () => document.documentElement.scrollHeight > innerHeight;
+  const look = (node) => ({picked: node.classList.contains("picked"), size: Math.round(node.querySelector("circle").getBoundingClientRect().width), red: getComputedStyle(node.querySelector("circle")).fill === red});
+  const opened = () => {
+    const rect = box.getBoundingClientRect();
+    const ends = line.getAttribute("display") === "none" ? null : ["x1", "y1", "x2", "y2"].map((key) => Number(line.getAttribute(key)));
+    return {
+      open: dialog.open, fade: [dialog.classList.contains("fade"), getComputedStyle(dialog).animationName], title: text(box.querySelector(".panel-title")), opacity: Number(getComputedStyle(box).opacity), line: ends,
+      onBox: Boolean(ends) && (Math.abs(ends[2] - rect.left) < 1 || Math.abs(ends[2] - rect.right) < 1 || Math.abs(ends[3] - rect.top) < 1 || Math.abs(ends[3] - rect.bottom) < 1),
+      inside: rect.left >= 0 && rect.top >= 0 && rect.right <= innerWidth && rect.bottom <= innerHeight,
+      tall: tall(), wide: document.documentElement.scrollWidth > innerWidth + 1, panel: all("#drawer, .drawer, #main aside, #main .panel, #main .graph-body").length,
+    };
+  };
+  const away = async (pick) => {
+    const outside = document.elementFromPoint(2, innerHeight - 2);
+    click(outside);
+    await sleep(250);
+    return {...look(pick()), open: dialog.open, outside: outside === dialog};
+  };
+"""
+POPUP_ORBIT = """(async () => {@HELPERS@@POPUPS@
+  const pick = () => document.querySelector('#main svg .node[data-pick="s2"]');
+  if (!(await until(pick, 8000))) {
+    return {error: text(document.getElementById("main"))};
+  }
+  const before = look(pick());
+  const flat = !tall();
+  click(pick());
+  await sleep(400);
+  const shown = {...opened(), ...look(pick()), sections: all("h3", box).map((head) => head.firstChild.textContent), composer: Boolean(box.querySelector("form textarea")), offices: text(box.querySelector(".popup-body p"))};
+  const gone = await away(pick);
+  click(pick());
+  await sleep(300);
+  const again = dialog.open;
+  (document.activeElement || document.body).dispatchEvent(new KeyboardEvent("keydown", {key: "Escape", bubbles: true}));
+  await sleep(250);
+  const escaped = {...look(pick()), open: dialog.open, again};
+  click(pick());
+  await sleep(500);
+  return {before, flat, shown, gone, escaped, last: dialog.open};
+})()""".replace("@HELPERS@", HELPERS).replace("@POPUPS@", POPUPS)
+POPUP_ARTIFACT = """(async () => {@HELPERS@@POPUPS@
+  const first = await until(() => document.querySelector('#main svg .node[data-pick^="branch:"]'), 8000);
+  if (!first) {
+    return {error: text(document.getElementById("main"))};
+  }
+  const id = first.dataset.pick;
+  const pick = () => all("#main svg .node[data-pick]").find((node) => node.dataset.pick === id);
+  const before = look(pick());
+  const flat = !tall();
+  click(pick());
+  await sleep(400);
+  const shown = {...opened(), ...look(pick()), label: first.getAttribute("aria-label").split(",")[0]};
+  const gone = await away(pick);
+  click(pick());
+  await sleep(400);
+  return {before, flat, shown, gone, last: dialog.open};
+})()""".replace("@HELPERS@", HELPERS).replace("@POPUPS@", POPUPS)
 PICK_3D = """(async () => {@HELPERS@
-  const list = await until(() => document.querySelector("#main .space-list"), 8000);
-  if (!list) {
+  const field = await until(() => document.querySelector('#main input[aria-label="Find a node"]'), 8000);
+  const ready = await until(() => document.querySelector("#main .graph3d canvas") && !text(document.querySelector("#main .space-note")).startsWith("Loading"), 8000);
+  if (!field || !ready) {
     return {error: text(document.querySelector("#main .graph"))};
   }
-  list.open = true;
-  const chip = all("#main .space-list [data-node]").find((node) => node.dataset.node.startsWith("@PREFIX@"));
+  const type = async (value) => {
+    field.value = value;
+    field.dispatchEvent(new Event("input", {bubbles: true}));
+    await sleep(150);
+    return all("#main .hits .chip").map((chip) => [chip.dataset.hit, text(chip)]);
+  };
+  const tree = await (await fetch("/api/tree", {cache: "no-store"})).json();
+  const found = {empty: await type(""), twins: tree.repos.flatMap((repo) => repo.branches).filter((branch) => branch.name === "main").length, twin: await type("main"), hits: await type("@QUERY@")};
+  found.flat = document.documentElement.scrollHeight <= innerHeight;
+  const chip = all("#main .hits .chip").find((node) => node.dataset.hit.startsWith("@PREFIX@"));
   if (!chip) {
-    return {error: all("#main .space-list [data-node]").map((node) => node.dataset.node)};
+    return {error: found};
   }
   chip.click();
   await sleep(600);
-  return {panel: text(document.querySelector("#main aside .panel-title")), label: chip.textContent};
+  const dialog = document.getElementById("popup");
+  const line = dialog.querySelector(".leader line");
+  const host = () => document.querySelector("#main .graph3d");
+  found.opened = {
+    open: dialog.open, title: text(dialog.querySelector(".popup-box .panel-title")), label: text(chip), hit: chip.dataset.hit, picked: host().dataset.picked || null,
+    line: line.getAttribute("display") !== "none", lists: all("#main .space-list, #main .chip[data-node]").length, flat: document.documentElement.scrollHeight <= innerHeight,
+  };
+  dialog.dispatchEvent(new MouseEvent("click", {bubbles: true}));
+  await sleep(300);
+  found.closed = {open: dialog.open, picked: host().dataset.picked || null};
+  chip.click();
+  await sleep(600);
+  return found;
 })()""".replace("@HELPERS@", HELPERS)
 CALL = """(async () => {@HELPERS@
   document.querySelector('#main [aria-label="Categories"] button[aria-label="Radio"]').click();
   const someone = await until(() => document.querySelector('#main button.linkish[title^="Open "]'), 8000);
   someone.click();
   await sleep(500);
-  document.querySelector('#drawer input[type=radio][value="call"]').click();
-  const field = document.querySelector("#drawer textarea");
+  document.querySelector('#popup input[type=radio][value="call"]').click();
+  const field = document.querySelector("#popup textarea");
   field.value = "E2E call ping";
   field.dispatchEvent(new Event("input", {bubbles: true}));
-  document.querySelector('#drawer button[type="submit"]').click();
+  document.querySelector('#popup button[type="submit"]').click();
   const entry = await until(() => all("#main .entry").find((row) => row.textContent.includes("Read") && row.textContent.includes("E2E call ping")), 20000);
   return {to: text(someone), receipt: entry ? text(entry) : null, sent: all("#main .entry").filter((row) => row.textContent.includes("E2E call ping")).length};
 })()""".replace("@HELPERS@", HELPERS)
@@ -787,6 +878,64 @@ class TestOrchestratorE2E(HubCase):
         self.assertEqual([entry for entry in click["log"] if entry.get("csp") == "media-src"], [])
         return data
 
+    def popped(self, result: dict, title: str) -> None:
+        before, shown, gone = result["before"], result["shown"], result["gone"]
+        self.assertEqual((before["picked"], before["red"]), (False, False))
+        self.assertEqual((shown["open"], shown["picked"], shown["red"], shown["fade"], shown["title"]), (True, True, True, [True, "fade"], title), shown)
+        self.assertGreater(shown["size"], before["size"] * 1.4)
+        self.assertLess(shown["opacity"], 1)
+        self.assertIsNotNone(shown["line"], shown)
+        self.assertTrue(shown["onBox"] and shown["inside"], shown)
+        self.assertEqual((not shown["tall"], shown["wide"], shown["panel"]), (result["flat"], False, 0))
+        self.assertEqual(gone, {"picked": False, "size": before["size"], "red": False, "open": False, "outside": True})
+        self.assertTrue(result["last"])
+
+    def check_popups(self, browser: str, driver: str, binary: str) -> None:
+        steps = []
+        for width, height in WIDTHS:
+            steps.append({"width": width, "height": height, "url": f"{self.base}#agents/orbit", "wait": 1200, "probe": POPUP_ORBIT, "shot": str(OUT / f"{browser}-{width}-agents-orbit-popup.png")})
+            steps.append({"width": width, "height": height, "url": f"{self.base}#artifacts/orbit", "wait": 1200, "probe": POPUP_ARTIFACT, "shot": str(OUT / f"{browser}-{width}-artifacts-orbit-popup.png")})
+        for tab, query, prefix in (("artifacts", "feature", "branch:"), ("agents", "sta", "s2")):
+            steps.append({"width": 1366, "height": 768, "url": f"{self.base}#{tab}/3d", "wait": 900, "probe": PICK_3D.replace("@QUERY@", query).replace("@PREFIX@", prefix), "shot": str(OUT / f"{browser}-1366-{tab}-3d-picked.png")})
+        data = self.drive(steps, None, driver, binary)
+        (OUT / f"{browser}-popups.json").write_text(json.dumps(data, indent=1), encoding="utf-8")
+        self.assertEqual([error for error in data["errors"] if "(style-src-elem)" not in error and "/favicon.ico" not in error], [])
+        results = data["results"]
+        for index, (width, _) in enumerate(WIDTHS):
+            agent, artifact = results[2 * index : 2 * index + 2]
+            with self.subTest(browser=browser, width=width):
+                self.assertNotIn("error", agent)
+                self.assertNotIn("error", artifact)
+                self.assertTrue(agent["flat"], "#agents/orbit scrolls")
+                self.popped(agent, "Stage")
+                self.assertEqual(agent["shown"]["sections"], ["Tasks", "Claims", "Subagents", "History"])
+                self.assertTrue(agent["shown"]["composer"])
+                self.assertRegex(agent["shown"]["offices"], r"^Offices: .*identity/oidc")
+                escaped = agent["escaped"]
+                self.assertEqual((escaped["again"], escaped["open"], escaped["picked"], escaped["red"], escaped["size"]), (True, False, False, False, agent["before"]["size"]))
+                self.popped(artifact, artifact["shown"]["label"])
+        for found, tab in zip(results[-2:], ("artifacts", "agents"), strict=True):
+            with self.subTest(browser=browser, tab=tab):
+                self.assertNotIn("error", found)
+                self.assertEqual(found["empty"], [])
+                labels = [label for _, label in found["hits"]]
+                self.assertEqual(len(labels), len(set(labels)), labels)
+                self.assertLessEqual(len(labels), 8)
+                opened = found["opened"]
+                self.assertEqual((opened["open"], opened["title"], opened["picked"], opened["line"], opened["lists"], opened["flat"]), (True, opened["label"], opened["hit"], True, 0, found["flat"]), opened)
+                self.assertEqual(found["closed"], {"open": False, "picked": None})
+        artifacts, agents = results[-2:]
+        self.assertEqual((artifacts["twins"], [label for _, label in artifacts["twin"]]), (2, ["main"]))
+        self.assertTrue(artifacts["opened"]["hit"].startswith("branch:"), artifacts["opened"])
+        self.assertEqual((agents["hits"], agents["opened"]["title"]), ([["s2", "Stage"]], "Stage"))
+
+    def test_chromium_opens_agent_and_node_popups_and_finds_nodes_at_three_widths(self):
+        self.check_popups("chromium", "cdp.mjs", os.environ.get("CHROMIUM", "chromium"))
+
+    @unittest.skipUnless(shutil.which(os.environ.get("FIREFOX", "firefox")), "no Firefox")
+    def test_firefox_opens_agent_and_node_popups_and_finds_nodes_at_three_widths(self):
+        self.check_popups("firefox", "bidi.mjs", os.environ.get("FIREFOX", "firefox"))
+
     def test_chromium_form_controls_never_overlap(self):
         self.check_overlaps("chromium", "cdp.mjs", os.environ.get("CHROMIUM", "chromium"))
 
@@ -812,8 +961,6 @@ class TestOrchestratorE2E(HubCase):
         steps = [{"width": width, "height": height, "url": f"{self.base}#{screen}", "wait": 900, "probe": PROBE, "shot": self.shot(f"{width}-{screen.replace('/', '-')}")} for width, height in WIDTHS for screen in SCREENS]
         steps += [{"width": 1366, "height": 768, "url": f"{self.base}#{old}", "wait": 600, "probe": PROBE, "shot": None} for old in ("graph", "graph/chord", "tree")]
         steps.append({"width": 1366, "height": 768, "url": f"{self.base}#stream", "wait": 900, "probe": ACTIONS, "shot": None})
-        steps.append({"width": 1366, "height": 768, "url": f"{self.base}#artifacts/3d", "wait": 900, "probe": PICK_3D.replace("@PREFIX@", "branch:"), "shot": self.shot("1366-artifacts-3d-picked")})
-        steps.append({"width": 1366, "height": 768, "url": f"{self.base}#agents/3d", "wait": 900, "probe": PICK_3D.replace("@PREFIX@", "s2"), "shot": self.shot("1366-agents-3d-picked")})
         steps.append({"width": 1366, "height": 768, "url": f"{self.base}#artifacts/3d", "wait": 900, "probe": PROBE, "shot": self.shot("1366-artifacts-3d-reduced-motion"), "media": [{"name": "prefers-reduced-motion", "value": "reduce"}]})
         steps.append({"width": 1366, "height": 768, "url": f"{self.base}#tasks/list", "wait": 900, "probe": INBOX_CHIP, "shot": self.shot("1366-tasks-grant")})
         data = self.drive(steps, None)
@@ -833,6 +980,7 @@ class TestOrchestratorE2E(HubCase):
                 self.assertGreater(probe["icons"], 8)
                 self.assertEqual(labelled(probe), {"unlabelled": [], "broken": []})
                 self.assertFalse(probe["wide"], "the page scrolls sideways")
+                self.assertEqual((probe["panel"], probe["nodeChips"]), (0, 0))
         self.assertEqual([probe["tall"] for probe in probes if probe["hash"] == "#agents/orbit"], [False] * len(WIDTHS))
         by_hash = {probe["hash"]: probe for probe in probes}
         stream = by_hash["#stream"]
@@ -884,16 +1032,15 @@ class TestOrchestratorE2E(HubCase):
         self.assertNotIn("error", actions)
         self.assertEqual(actions["keys"], ["#agents/chord", "#artifacts/tree", "#tasks/rasci", "#stream"])
         self.assertEqual(actions["ambience"], ["sky-look", "music-toggle", "leitstand", "notify"])
-        self.assertEqual((actions["settingsUnlabelled"], actions["drawerUnlabelled"]), (0, 0))
+        self.assertEqual((actions["settingsUnlabelled"], actions["popupUnlabelled"]), (0, 0))
         self.assertEqual([name for name, _, _ in actions["speech"]], ["Post", "Call", "Newsletter", "Broadcast", "MAYDAY", "PAN-PAN", "Sécurité"])
         self.assertEqual([entry[1:] for entry in actions["speech"] if entry[0] == "MAYDAY"], [[True, True]])
         for tool in ("Radio to all …", "Cancel mayday", "Priority …", "Evening", "Firewall …", "Settings …", "Look at the sky", "Toggle control room", "Enable notifications"):
             with self.subTest(tool=tool):
                 self.assertTrue(any(tool in entry for entry in actions["palette"]), actions["palette"])
-        self.assertEqual(actions["drawer"], [["post", True], ["call", False]])
-        artifact_pick, agent_pick, calm, chips = extra[4:]
-        self.assertEqual(artifact_pick["panel"], artifact_pick["label"])
-        self.assertEqual(agent_pick["panel"], agent_pick["label"])
+        self.assertEqual(actions["popup"], [["post", True], ["call", False]])
+        self.assertEqual(actions["centred"], [True, "none"])
+        calm, chips = extra[4:]
         self.assertRegex(calm["note"], r"Force · without motion \(prefers-reduced-motion\)$")
         self.assertEqual({key: value for key, value in chips["inbox"].items() if key != "counted"}, {"hash": "#stream/inbox", "items": chips["inbox"]["counted"], "pressed": "true", "current": ["Inbox"]})
         self.assertGreaterEqual(chips["inbox"]["items"], 1)
@@ -1205,6 +1352,7 @@ class TestOrchestratorE2E(HubCase):
                 self.assertEqual((probe["tabs"], probe["subs"]), (TABS, SUBS))
                 self.assertEqual(labelled(probe), {"unlabelled": [], "broken": []})
                 self.assertFalse(probe["wide"], "the page scrolls sideways")
+                self.assertEqual((probe["panel"], probe["nodeChips"]), (0, 0))
                 self.assertTrue(shot.is_file() and shot.stat().st_size > 1000, shot)
                 if screen.endswith("/3d"):
                     self.assertTrue(probe["canvas"], probe["note"])

tests/hub_support.py

@@ -76,6 +76,7 @@ def offline_redirects() -> Redirects:
 VOICE = HUB / "templates" / "voice.js"
 SPACE = HUB / "templates" / "space.js"
 NAV = HUB / "templates" / "nav.js"
+POPUP = HUB / "templates" / "popup.js"
 
 
 class FakeScripts:

tests/test_hub_page.py

@@ -6,11 +6,12 @@ import re
 import subprocess
 import time
 import unittest
+from collections import Counter
 from pathlib import Path
 from unittest import mock
 
 from hub_case import HubCase
-from hub_support import AMBIENCE, NAV, SPACE, VOICE
+from hub_support import AMBIENCE, NAV, POPUP, SPACE, VOICE
 from kvb_orchestrator import exchange
 
 
@@ -62,9 +63,9 @@ class TestHubPage(HubCase):
         self.assertEqual((state["reviews"][0]["title"], state["reviews"][0]["notes"]), ("<script>alert(1)</script>", "</pre><script>alert(2)</script>"))
         self.assertEqual((state["register"][0]["title"], state["radio"][0]["from"]), ("<script>alert(3)</script>", "<img src=x>"))
 
-    def test_the_index_scripts_parse_and_embed_the_ambience_voice_nav_and_space_modules(self):
+    def test_the_index_scripts_parse_and_embed_the_ambience_voice_nav_popup_and_space_modules(self):
         html = self.index()
-        for module in (AMBIENCE, VOICE, NAV, SPACE):
+        for module in (AMBIENCE, VOICE, NAV, POPUP, SPACE):
             with self.subTest(module=module.name):
                 self.assertIn(module.read_text(encoding="utf-8").strip(), html)
         scripts = re.findall(r'<script nonce="[^"]+">(.*?)</script>', html, re.DOTALL)
@@ -73,11 +74,17 @@ class TestHubPage(HubCase):
         page.write_text("\n;\n".join(scripts), encoding="utf-8")
         done = subprocess.run(["node", "--check", str(page)], capture_output=True, text=True, timeout=60, check=False)
         self.assertEqual(done.returncode, 0, done.stderr)
-        for module in (AMBIENCE, VOICE, NAV, SPACE):
+        for module in (AMBIENCE, VOICE, NAV, POPUP, SPACE):
             with self.subTest(module=module.name):
                 done = subprocess.run(["node", "--check", str(module)], capture_output=True, text=True, timeout=60, check=False)
                 self.assertEqual(done.returncode, 0, done.stderr)
 
+    def test_no_two_page_modules_declare_the_same_function(self):
+        page = re.findall(r'<script nonce="[^"]+">(.*?)</script>', self.index(), re.DOTALL)[-1]
+        names = Counter(re.findall(r"^  (?:async )?function (\w+)\(", page, re.MULTILINE))
+        self.assertGreater(len(names), 100)
+        self.assertEqual([name for name, count in names.items() if count > 1], [])
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_hub_popup.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import unittest
+
+from hub_support import POPUP
+
+POPUP_PROBE = """
+const P = require(process.argv[1]);
+let seed = 11;
+const next = () => {
+  seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0;
+  return seed / 4294967296;
+};
+const node = (left, top) => ({left, top, width: 20, height: 20});
+const wide = {width: 1366, height: 768};
+const phone = {width: 390, height: 844};
+const random = Array.from({length: 600}, () => {
+  const view = {width: 300 + Math.round(next() * 1700), height: 300 + Math.round(next() * 900)};
+  const size = {width: Math.min(440, view.width - 2 * P.GAP), height: Math.round(80 + next() * (view.height - 2 * P.GAP - 80))};
+  const anchor = {left: Math.round(next() * view.width) - 10, top: Math.round(next() * view.height) - 10, width: 20, height: 20};
+  return {view, size, anchor, at: P.place(anchor, size, view)};
+});
+const nodes = [
+  {id: "s1", label: "Skills session"}, {id: "s2", label: "Stage"}, {id: "agent:Stage@/a", label: "Stage"}, {id: "agent:Stage@/b", label: "Stage"},
+  {id: "b1", label: "feature/stage-fix"}, {id: "b2", label: "main"}, {id: "b3", label: "main"}, {id: "x", label: "Backstage"},
+];
+const ids = (list) => list.map((entry) => entry.id);
+console.log(JSON.stringify({
+  constants: [P.GAP, P.REACH, P.MIN],
+  right: P.place(node(100, 300), {width: 440, height: 300}, wide),
+  left: P.place(node(1200, 300), {width: 440, height: 300}, wide),
+  below: P.place(node(185, 100), {width: 358, height: 300}, phone),
+  above: P.place(node(185, 700), {width: 358, height: 300}, phone),
+  capped: P.place(node(185, 400), {width: 358, height: 700}, phone),
+  covered: P.place(node(185, 180), {width: 358, height: 368}, {width: 390, height: 400}),
+  centre: P.place(null, {width: 440, height: 300}, wide),
+  random,
+  hits: {
+    stage: ids(P.hits(nodes, "sta", 8)),
+    main: ids(P.hits(nodes, "  MAIN ", 8)),
+    blank: P.hits(nodes, "   ", 8),
+    limit: ids(P.hits(nodes, "a", 2)),
+    none: P.hits(nodes, "zzz", 8),
+    same: P.hits(nodes, "stage", 8)[0] === nodes[1],
+  },
+}));
+"""
+SLACK = 0.06
+
+
+class TestPopupModule(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        done = subprocess.run(["node", "-e", POPUP_PROBE, str(POPUP)], capture_output=True, text=True, timeout=60, check=True)
+        cls.data = json.loads(done.stdout)
+        cls.gap, cls.reach, cls.min = cls.data["constants"]
+
+    def test_the_popup_sits_right_of_the_node_and_the_leader_spans_the_gap_between_them(self):
+        self.assertEqual(self.data["right"], {"left": 160, "top": 160, "height": None, "line": {"x1": 120, "y1": 310, "x2": 160, "y2": 310}})
+        self.assertEqual(self.data["right"]["line"]["x2"] - self.data["right"]["line"]["x1"], self.reach)
+
+    def test_a_node_near_the_right_edge_gets_the_popup_on_its_left(self):
+        self.assertEqual(self.data["left"], {"left": 720, "top": 160, "height": None, "line": {"x1": 1200, "y1": 310, "x2": 1160, "y2": 310}})
+
+    def test_on_a_phone_the_popup_goes_below_or_above_the_node(self):
+        self.assertEqual(self.data["below"], {"left": 16, "top": 160, "height": None, "line": {"x1": 195, "y1": 120, "x2": 195, "y2": 160}})
+        self.assertEqual(self.data["above"], {"left": 16, "top": 360, "height": None, "line": {"x1": 195, "y1": 700, "x2": 195, "y2": 660}})
+
+    def test_a_popup_too_tall_for_either_side_is_capped_to_the_larger_room_and_keeps_its_leader(self):
+        self.assertEqual(self.data["capped"], {"left": 16, "top": 460, "height": 368, "line": {"x1": 195, "y1": 420, "x2": 195, "y2": 460}})
+
+    def test_without_room_the_popup_covers_the_node_and_draws_no_leader(self):
+        self.assertEqual(self.data["covered"], {"left": 16, "top": 16, "height": None, "line": None})
+
+    def test_a_popup_without_a_node_is_centred_without_a_leader(self):
+        self.assertEqual(self.data["centre"], {"left": 463, "top": 234, "height": None, "line": None})
+
+    def test_every_placement_stays_in_the_viewport_and_every_leader_runs_from_the_node_edge_to_the_popup_edge(self):
+        leaders = 0
+        for case in self.data["random"]:
+            view, size, anchor, at = case["view"], case["size"], case["anchor"], case["at"]
+            height = size["height"] if at["height"] is None else at["height"]
+            box = (at["left"], at["top"], at["left"] + size["width"], at["top"] + height)
+            with self.subTest(case=case):
+                self.assertGreaterEqual(min(box[0], box[1]), self.gap - SLACK)
+                self.assertLessEqual(box[2], view["width"] - self.gap + SLACK)
+                self.assertLessEqual(box[3], view["height"] - self.gap + SLACK)
+                if at["height"] is not None:
+                    self.assertGreaterEqual(at["height"], self.min - SLACK)
+                    self.assertLess(at["height"], size["height"])
+                rect = (anchor["left"], anchor["top"], anchor["left"] + anchor["width"], anchor["top"] + anchor["height"])
+                line = at["line"]
+                if line is None:
+                    self.assertTrue(box[0] <= rect[2] + SLACK and rect[0] <= box[2] + SLACK and box[1] <= rect[3] + SLACK and rect[1] <= box[3] + SLACK, "no leader although the popup misses the node")
+                    continue
+                leaders += 1
+                self.assertTrue(any(abs(line["x2"] - edge) <= SLACK for edge in (box[0], box[2])) or any(abs(line["y2"] - edge) <= SLACK for edge in (box[1], box[3])))
+                self.assertTrue(any(abs(line["x1"] - edge) <= SLACK for edge in (rect[0], rect[2])) or any(abs(line["y1"] - edge) <= SLACK for edge in (rect[1], rect[3])))
+                self.assertTrue(rect[0] - SLACK <= line["x1"] <= rect[2] + SLACK and rect[1] - SLACK <= line["y1"] <= rect[3] + SLACK)
+        self.assertGreater(leaders, len(self.data["random"]) * 0.9)
+
+    def test_search_hits_are_one_per_label_prefix_first_case_insensitive_and_limited(self):
+        hits = self.data["hits"]
+        self.assertEqual(hits["stage"], ["s2", "b1", "x"])
+        self.assertEqual(hits["main"], ["b2"])
+        self.assertEqual(hits["limit"], ["s2", "b1"])
+        self.assertTrue(hits["same"])
+
+    def test_a_blank_or_unknown_query_finds_nothing(self):
+        self.assertEqual((self.data["hits"]["blank"], self.data["hits"]["none"]), ([], []))
+
+
+if __name__ == "__main__":
+    unittest.main()